From f2135e4cd8b503bcafe2742166e21c964fb136dc Mon Sep 17 00:00:00 2001 From: Andres Contreras Date: Wed, 11 Feb 2026 09:45:22 +0100 Subject: [PATCH] docs: add professional README with unified template (#12) Standardize README.md with a consistent template including CI badge, features, installation, quick start, configuration, and documentation sections. Add paths-ignore to ci.yml to skip CI for docs-only changes. --- .github/workflows/ci.yml | 19 +- README.md | 600 +++++---------------------------------- 2 files changed, 91 insertions(+), 528 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b9093b6..9567aee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,8 +2,22 @@ name: CI on: push: branches: [develop] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' pull_request: branches: [develop, main] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' workflow_dispatch: inputs: triggered-by: @@ -13,10 +27,5 @@ on: jobs: build: uses: fireflyframework/.github/.github/workflows/java-ci.yml@main - permissions: - packages: read - contents: read - actions: write with: java-version: '25' - secrets: inherit diff --git a/README.md b/README.md index aeda352..c71a187 100644 --- a/README.md +++ b/README.md @@ -1,575 +1,129 @@ -# Firefly Common Core Library - +# Firefly Framework - Core + [![CI](https://github.com/fireflyframework/fireflyframework-core/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-core/actions/workflows/ci.yml) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) +[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org) +[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot) -**Copyright (c) 2025 Firefly Software Solutions Inc** +> Core framework module providing WebFlux configuration, actuator setup, resilience, tracing, and service registry integration. -[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -[![Java Version](https://img.shields.io/badge/Java-21%2B-orange)](https://openjdk.java.net/projects/jdk/21/) -[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.2-green)](https://spring.io/projects/spring-boot) +--- -A Spring Boot library providing utilities, configuration, and shared infrastructure components for the **core-infrastructure layer** of the **Firefly Framework**. +## Table of Contents -This library is developed by **Firefly Software Solutions Inc** and released under the Apache 2.0 License. +- [Overview](#overview) +- [Features](#features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Configuration](#configuration) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) ## Overview -The Firefly Common Core library is part of the Firefly Framework architecture, specifically designed for the core-infrastructure layer. It complements the [fireflyframework-domain](../fireflyframework-domain/) library which handles domain-layer concerns. - +Firefly Framework Core is the foundational runtime module that every Firefly-based microservice includes. It provides auto-configured WebFlux settings, WebClient configuration with resilience patterns, Actuator health and metrics endpoints, distributed tracing, and service registry integration. -## Features +The module handles cross-cutting concerns including banner display, web filters, transaction context propagation, cloud configuration, and step event publishing for the transactional engine. It integrates with Spring Cloud Config for centralized configuration and supports service discovery through configurable registry adapters. -### Messaging System -- **Unified EventPublisher API** supporting multiple messaging providers -- **Supported providers**: Kafka, RabbitMQ, AWS SQS, Google Pub/Sub, Azure Service Bus, Redis Pub/Sub, JMS/ActiveMQ, AWS Kinesis -- **Connection-aware publishers** for multiple connections per provider -- **Reactive messaging** built on Project Reactor -- **Resilience patterns** with Resilience4j integration +Core is designed to be included as a transitive dependency through higher-level modules like `fireflyframework-domain` or `fireflyframework-application`, but can also be used directly for custom microservice setups. -### Configuration Management -- **Spring Cloud Config** integration -- **Service discovery** with Eureka and Consul support -- **Multi-environment** configuration management +## Features -### Enhanced WebClient -- **Reactive WebClient** with connection pooling -- **Service registry integration** for load balancing -- **SSL and HTTP/2** support +- WebFlux auto-configuration with customizable WebClient settings +- Resilient WebClient with circuit breaker and retry patterns +- Spring Boot Actuator configuration (health, info, metrics, tracing) +- JVM, HTTP client, thread pool, and application metrics +- Database and cache health indicators +- OpenTelemetry distributed tracing integration +- Spring Cloud Config client auto-configuration +- Service registry integration (Eureka, Consul, Kubernetes) +- Step event publishing bridge for the transactional engine +- Firefly branded startup banner +- Transaction context web filter +- Logstash-compatible structured logging +- Cloud configuration properties management -### Observability & Monitoring -- **Health indicators** for messaging and external systems -- **Micrometer metrics** with Prometheus integration -- **Actuator enhancements** for production monitoring +## Requirements -### Integration Support -- **CQRS integration** with fireflyframework-cqrs -- **Transactional engine** support with lib-transactional-engine -- **Reactive patterns** throughout the library +- Java 21+ +- Spring Boot 3.x +- Maven 3.9+ -## ๐Ÿ“ฆ Installation +## Installation -### Maven ```xml org.fireflyframework fireflyframework-core - 1.0.0-SNAPSHOT + 26.01.01 ``` -### Gradle -```gradle -implementation 'org.fireflyframework:fireflyframework-core:1.0.0-SNAPSHOT' -``` - -## ๐Ÿš€ Quick Start - -### 1. Enable Core Features - -```yaml -# application.yml -messaging: - enabled: true - kafka: - enabled: true - bootstrap-servers: localhost:9092 - default-topic: events - -management: - endpoints: - web: - exposure: - include: "*" - metrics: - export: - prometheus: - enabled: true - -spring: - application: - name: my-service -``` - -### 2. Publish Messages +## Quick Start ```java -@RestController -public class EventController { - - @PostMapping("/events") - @PublishResult( - publisherType = KAFKA, - destination = "user-events", - eventType = "user.created" - ) - public Mono createUser(@RequestBody CreateUserRequest request) { - // Your business logic here - return Mono.just(new UserCreatedEvent(request.getUserId(), request.getEmail())); - } -} -``` +import org.fireflyframework.core.web.client.WebClientTemplate; -### 3. Handle Messages - -```java -@Component -public class UserEventHandler { - - @EventListener - public Mono handleUserCreated(@EventPayload UserCreatedEvent event, - @EventHeaders Map headers) { - log.info("User created: {} with transaction ID: {}", - event.getUserId(), headers.get("transactionId")); - - // Process the event - return userService.processNewUser(event); - } -} -``` +@Service +public class ExternalService { -### 4. Enhanced WebClient Usage + private final WebClientTemplate webClient; -```java -@Service -public class ExternalServiceClient { - - private final WebClient webClient; - - public ExternalServiceClient(WebClient.Builder webClientBuilder) { - this.webClient = webClientBuilder.build(); + public ExternalService(WebClientTemplate webClient) { + this.webClient = webClient; } - - public Mono callExternalService(RequestData request) { - return webClient.post() - .uri("/api/external") - .bodyValue(request) - .retrieve() - .bodyToMono(ResponseData.class); + + public Mono callApi(String path) { + return webClient.get(path, Response.class); } } ``` -## ๐Ÿ“‹ Table of Contents - -- [Architecture Overview](docs/ARCHITECTURE.md) -- [Quick Start Guide](docs/QUICKSTART.md) -- [Configuration Reference](docs/CONFIGURATION.md) -- [API Documentation](docs/API.md) -- [Integrations Guide](docs/INTEGRATIONS.md) -- [Examples and Use Cases](docs/EXAMPLES.md) -- [Migration Guide](docs/MIGRATION.md) -- [Contributing Guidelines](CONTRIBUTING.md) - -## ๐Ÿ—๏ธ Architecture - -The library is organized into several key modules: - -### Core Modules - -| Module | Description | Key Classes | -|--------|-------------|-------------| -| **Messaging** | Multi-provider messaging system | `EventPublisher`, `EventPublisherFactory`, `MessagingProperties` | -| **Configuration** | Cloud config and service discovery | `CloudConfigProperties`, `ServiceRegistryHelper` | -| **Observability** | Metrics, tracing, and health checks | `ActuatorProperties`, `MessagingHealthIndicator` | -| **Web** | Reactive web capabilities | `WebClientProperties`, `WebFluxConfig` | -| **Integration** | CQRS and saga orchestration | `StepEventPublisherBridge`, `TransactionalEngineAutoConfiguration` | - -### Messaging Publishers - -| Publisher | Class | Configuration Prefix | -|-----------|-------|---------------------| -| Apache Kafka | `KafkaEventPublisher` | `messaging.kafka` | -| RabbitMQ | `RabbitMqEventPublisher` | `messaging.rabbitmq` | -| AWS SQS | `SqsEventPublisher` | `messaging.sqs` | -| Google Pub/Sub | `GooglePubSubEventPublisher` | `messaging.google-pub-sub` | -| Azure Service Bus | `AzureServiceBusEventPublisher` | `messaging.azure-service-bus` | -| Redis Pub/Sub | `RedisEventPublisher` | `messaging.redis` | -| JMS/ActiveMQ | `JmsEventPublisher` | `messaging.jms` | -| AWS Kinesis | `KinesisEventPublisher` | `messaging.kinesis` | -| Spring Events | `SpringEventPublisher` | Always available when messaging enabled | - -## ๐Ÿ› ๏ธ Configuration - -### Messaging Configuration - -```yaml -messaging: - enabled: true - resilience: true - publish-timeout-seconds: 5 - default-connection-id: default - - # Kafka Configuration - kafka: - enabled: true - bootstrap-servers: localhost:9092 - default-topic: events - client-id: my-service - security-protocol: PLAINTEXT - properties: - "batch.size": "16384" - "linger.ms": "5" - - # Multiple Kafka Connections - kafka-connections: - primary: - enabled: true - bootstrap-servers: kafka-primary:9092 - default-topic: primary-events - secondary: - enabled: true - bootstrap-servers: kafka-secondary:9092 - default-topic: secondary-events - - # RabbitMQ Configuration - rabbitmq: - enabled: true - host: localhost - port: 5672 - username: guest - password: guest - default-exchange: events - default-routing-key: default - - # AWS SQS Configuration - sqs: - enabled: true - region: us-east-1 - default-queue: events - # Access keys can be configured via environment or IAM roles - - # Serialization Configuration - serialization: - default-format: JSON - formats: - json: - enabled: true - pretty-print: false - avro: - enabled: true - schema-registry-url: http://localhost:8081 - protobuf: - enabled: true -``` - -### Step Events Integration - -```yaml -# Step Events Configuration (for Transactional Engine integration) -step-events: - enabled: true - publisher-type: KAFKA - connection-id: default - event-destination: saga-events - include-step-context: true - -# Transactional Engine Configuration -transactional-engine: - enabled: true - step-event-publisher: stepEventPublisherBridge -``` - -### Cloud Configuration +## Configuration ```yaml -# Spring Cloud Config -cloud: - config: - enabled: true - uri: http://config-server:8888 - name: ${spring.application.name} - profile: ${spring.profiles.active:default} - label: main - fail-fast: true - retry: - enabled: true - max-attempts: 3 - -# Service Registry (Eureka) -service: - registry: - enabled: true - type: EUREKA - eureka: - service-url: http://eureka:8761/eureka/ - register: true - fetch-registry: true - health-check-enabled: true - health-check-url-path: /actuator/health -``` - -### Actuator and Observability - -```yaml -management: - endpoints: - web: - exposure: - include: "*" - base-path: /actuator - endpoint: - health: - show-details: always - show-components: true - prometheus: - enabled: true - - metrics: - export: - prometheus: +firefly: + core: + web-client: + connect-timeout: 5000 + read-timeout: 10000 + resilience: + circuit-breaker: enabled: true - step: 60s - tags: - service: ${spring.application.name} - environment: ${spring.profiles.active:default} - - tracing: - sampling: - probability: 0.1 - zipkin: - endpoint: http://zipkin:9411/api/v2/spans - -# Custom Actuator Configuration -actuator: - extended-metrics: - jvm: + failure-rate-threshold: 50 + cloud-config: enabled: true - memory: true - gc: true - threads: true - database: + uri: http://config-server:8888 + service-registry: enabled: true - connection-timeout: 5 - application: - enabled: true - startup-phases: true - enhanced-info: true -``` - -### WebClient Configuration - -```yaml -webclient: - enabled: true - connect-timeout-ms: 5000 - read-timeout-ms: 10000 - write-timeout-ms: 10000 - max-in-memory-size: 16777216 - - connection-pool: - enabled: true - max-connections: 500 - max-idle-time-ms: 30000 - - http2: - enabled: true - max-concurrent-streams: 100 -``` - -## ๐Ÿ”ง Advanced Features - -### Multiple Messaging Connections + type: eureka -```java -@RestController -public class MultiConnectionController { - - @PostMapping("/primary-events") - @PublishResult( - publisherType = KAFKA, - connectionId = "primary", - destination = "primary-topic" - ) - public Mono publishToPrimary(@RequestBody Event event) { - return Mono.just(event); - } - - @PostMapping("/secondary-events") - @PublishResult( - publisherType = KAFKA, - connectionId = "secondary", - destination = "secondary-topic" - ) - public Mono publishToSecondary(@RequestBody Event event) { - return Mono.just(event); - } -} -``` - -### Custom Serialization - -```java -@Component -public class EventSerializationConfig { - - @Bean - public MessageSerializer customAvroSerializer() { - return new AvroSerializer("http://schema-registry:8081"); - } - - @PostMapping("/avro-events") - @PublishResult( - publisherType = KAFKA, - destination = "avro-events", - serializer = "customAvroSerializer" - ) - public Mono publishAvroEvent(@RequestBody AvroEvent event) { - return Mono.just(event); - } -} -``` - -### Circuit Breaker Integration - -```java -@Service -public class ResilientMessagingService { - - @Retryable(value = {Exception.class}, maxAttempts = 3, backoff = @Backoff(delay = 1000)) - @CircuitBreaker(name = "messaging", fallbackMethod = "fallbackPublish") - @PublishResult(publisherType = KAFKA, destination = "resilient-events") - public Mono publishWithResilience(@RequestBody String message) { - return Mono.just(message); - } - - public Mono fallbackPublish(String message, Exception ex) { - log.warn("Publishing failed, using fallback: {}", ex.getMessage()); - return Mono.just("FALLBACK_PROCESSED"); - } -} -``` - -### Service Discovery Integration - -```java -@Service -public class ServiceIntegration { - - private final ServiceRegistryHelper serviceRegistry; - private final WebClient.Builder webClientBuilder; - - public Mono callDownstreamService(String serviceId, String path) { - return Mono.fromCallable(() -> serviceRegistry.getServiceUri(serviceId)) - .flatMap(uri -> webClientBuilder.build() - .get() - .uri(uri.resolve(path)) - .retrieve() - .bodyToMono(String.class)); - } -} -``` - -## ๐Ÿ“Š Monitoring and Observability - -### Available Metrics - -| Metric Category | Description | Examples | -|-----------------|-------------|----------| -| **Messaging** | Publisher success/failure rates, latency | `messaging.publish.timer`, `messaging.publish.counter` | -| **HTTP Client** | Request metrics, connection pool stats | `http.client.requests`, `reactor.netty.connection.provider` | -| **JVM** | Memory, GC, threads, class loading | `jvm.memory.used`, `jvm.gc.pause` | -| **Application** | Custom business metrics | `application.startup.phase`, `application.feature.usage` | - -### Health Checks - -- **Messaging**: Connectivity to all enabled messaging systems -- **Service Registry**: Connection to Eureka/Consul -- **Database**: Connection pool health (if applicable) -- **Disk Space**: Available storage monitoring -- **Custom**: Application-specific health indicators - -### Distributed Tracing - -Automatic trace propagation for: -- HTTP requests (WebClient/WebFlux) -- Messaging operations -- Database operations (when using Spring Data) -- Inter-service calls - -## ๐Ÿงช Testing - -### Test Configuration - -```yaml -# application-test.yml -messaging: - enabled: true - kafka: - enabled: true - bootstrap-servers: ${spring.embedded.kafka.brokers} - management: endpoints: web: exposure: - include: health,metrics + include: health,info,metrics,prometheus ``` -### Integration Tests - -```java -@SpringBootTest -@EmbeddedKafka(partitions = 1, topics = {"test-events"}) -class MessagingIntegrationTest { - - @Autowired - private EventPublisher eventPublisher; - - @Test - void shouldPublishAndConsumeMessages() { - StepVerifier.create( - eventPublisher.publish("test-events", "test.event", "test-payload", "tx-123") - ).verifyComplete(); - - // Verify message was consumed - // ... assertion logic - } -} -``` - -## ๐Ÿค Contributing - -We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details. - -### Development Setup - -```bash -# Clone repository -git clone https://github.org/fireflyframework-oss/fireflyframework-core.git -cd fireflyframework-core - -# Build and test -./mvnw clean test - -# Generate documentation -./mvnw javadoc:javadoc - -# Run integration tests -./mvnw verify -Pintegration-tests -``` - -## ๐Ÿ“„ License - -This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. +## Documentation -## ๐Ÿ”— Related Projects +Additional documentation is available in the [docs/](docs/) directory: -- [fireflyframework-cqrs](../fireflyframework-cqrs/) - CQRS patterns and event sourcing -- [lib-transactional-engine](../lib-transactional-engine/) - Transaction orchestration -- [fireflyframework-domain](../fireflyframework-domain/) - Domain layer utilities +- [Overview](docs/OVERVIEW.md) +- [Architecture](docs/ARCHITECTURE.md) +- [Configuration](docs/CONFIGURATION.md) +- [Quickstart](docs/QUICKSTART.md) +- [Api](docs/API.md) +- [Integrations](docs/INTEGRATIONS.md) -## ๐Ÿ“„ License +## Contributing -Copyright 2024-2026 Firefly Software Solutions Inc +Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests. -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at +## License - http://www.apache.org/licenses/LICENSE-2.0 +Copyright 2024-2026 Firefly Software Solutions Inc. -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. \ No newline at end of file +Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.