Firefly Framework - Client

Unified reactive client library for REST, SOAP, gRPC, GraphQL, and WebSocket services with circuit breakers and observability.

---

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Quick Start
• Configuration
• Documentation
• Contributing
• License

Overview

Firefly Framework Client provides a unified, reactive communication library that supports multiple protocols through a consistent API. It includes pre-built clients for REST, SOAP, gRPC, GraphQL, and WebSocket services, each with integrated circuit breaker patterns, health monitoring, and comprehensive metrics collection.

The library features builder-based client construction (RestClientBuilder, SoapClientBuilder, GrpcClientBuilder), service discovery integration (Eureka, Consul, Kubernetes, static), and advanced capabilities including HTTP response caching, request deduplication, OAuth2 authentication, API key management, and certificate pinning.

Additional features include a chaos engineering interceptor for fault injection during testing, client-side rate limiting, interceptor chain support for request/response transformation, and pluggable error handling with protocol-specific error mappers.

Features

• REST, SOAP, gRPC, GraphQL, and WebSocket client implementations
• Builder pattern for type-safe client construction
• Circuit breaker with configurable sliding window and failure thresholds
• Service discovery: Eureka, Consul, Kubernetes, static endpoints
• Load balancer strategy support
• OAuth2 client helper with token management
• API key management and certificate pinning
• HTTP response caching with configurable cache policies
• Request deduplication manager
• Interceptor chain for logging, metrics, and custom transformations
• Chaos engineering interceptor for fault injection testing
• Client-side rate limiting
• Health indicators and metrics per client instance
• Error handling with HTTP, gRPC, and SOAP fault mappers
• Multipart upload helper
• Dynamic JSON response handling
• Spring Boot auto-configuration with validation

Requirements

• Java 21+
• Spring Boot 3.x
• Maven 3.9+

Installation

<dependency>
    <groupId>org.fireflyframework</groupId>
    <artifactId>fireflyframework-client</artifactId>
    <version>26.02.04</version>
</dependency>

Quick Start

import org.fireflyframework.client.RestClient;
import org.fireflyframework.client.builder.RestClientBuilder;

@Configuration
public class ClientConfig {

    @Bean
    public RestClient paymentClient() {
        return RestClientBuilder.create("payment-service")
            .baseUrl("https://api.payments.com")
            .connectTimeout(Duration.ofSeconds(5))
            .circuitBreaker(cb -> cb
                .failureRateThreshold(50)
                .waitDurationInOpenState(Duration.ofSeconds(30)))
            .build();
    }
}

@Service
public class PaymentService {

    private final RestClient paymentClient;

    public Mono<PaymentResponse> charge(PaymentRequest request) {
        return paymentClient.post("/charges", request, PaymentResponse.class);
    }
}

Configuration

firefly:
  client:
    services:
      payment-service:
        base-url: https://api.payments.com
        connect-timeout: 5s
        read-timeout: 10s
        circuit-breaker:
          enabled: true
          failure-rate-threshold: 50
        retry:
          max-attempts: 3
          backoff: 1s

Documentation

Additional documentation is available in the docs/ directory:

• Quick Start
• Configuration
• Rest Client
• Soap Client
• Grpc Client
• Graphql Client
• Websocket Helper
• Multipart Helper
• Oauth2 Helper
• Security
• Observability
• Advanced Features
• Integration Testing

Contributing

Contributions are welcome. Please read the CONTRIBUTING.md guide for details on our code of conduct, development process, and how to submit pull requests.

License

Copyright 2024-2026 Firefly Software Solutions Inc.

Licensed under the Apache License, Version 2.0. See LICENSE for details.