AuditFlow API Client (Java)
Minimal-dependency Java client for the Labs64.IO AuditFlow API. Wraps POST <baseUrl>/audit/publish with auto event-id, correlation propagation, retries, and synchronous / async / fire-and-forget publishing.
Install
<dependency>
<groupId>io.labs64</groupId>
<artifactId>auditflow-api</artifactId>
<version>1.0.0</version>
</dependency>
Quick Start (Zero-Config)
For containerized environments (Kubernetes/Docker), you can configure the client entirely via standard environment variables (AUDITFLOW_URL, AUDITFLOW_TOKEN, AUDITFLOW_DEFAULT_SOURCE):
AuditFlowClient client = AuditFlowClient.fromEnv();
Advanced Configuration
For advanced configurations, use the fluent builder:
AuditFlowClient client = AuditFlowClient.builder()
.baseUrl("https://gateway.labs64.io/auditflow/api/v1")
.token("eyJ...") // or .tokenProvider(() -> jwtCache.current())
.defaultSourceSystem("netlicensing/core")
// Use for OpenTelemetry trace propagation:
.correlationIdProvider(() -> Tracer.currentSpan().getTraceId())
.build();
Usage
// Compile-time safe: eventType is required in the constructor
AuditEvent event = AuditEvents.builder("user.login")
.extra("userId", "u1")
// `extra` is an open map: any key is valid. These two are the optional well-known
// convention the bundled transformers promote to dedicated fields — see the `Extra`
// schema in the OpenAPI contract for the full list and for how to promote your own.
.extra("actionStatus", "SUCCESS")
.build();
// Synchronous — throws a typed AuditFlowException on failure
PublishResult result = client.publish(event);
// Request-scoped headers, for example for a direct internal call
PublishResult internalResult = client.publish(event,
AuditFlowRequestOptions.builder()
.headers(internalCallHeaders)
.build());
// Asynchronous — non-blocking
client.publishAsync(event).thenAccept(r -> System.out.println(r.eventId()));
// Fire-and-forget — never throws into your code path
client.fireAndForget(event);
// Batch — one request per 100 events, per-event results in submission order
BatchResult batch = client.publishBatch(events);
batch.rejected().forEach(e -> log.warn("{} not stored: {} {}", e.eventId(), e.errorCode(), e.errorMessage()));
publishBatch assigns missing event ids before the first attempt, so a retry never stores an event twice. A whole request that fails with a network error or HTTP 503 is retried; entries rejected with TENANT_RATE_LIMITED or PUBLISH_FAILED are re-sent alone, after the server’s Retry-After at the earliest, while the retry policy allows. VALIDATION_ERROR entries are returned as rejected without retry. An accepted entry is stored by the broker.
Configuration Options
| Builder method | Default | Purpose |
|---|---|---|
baseUrl(String) | (required) | API base URL, e.g. https://gateway.host/auditflow/api/v1 (gateway) or http://auditflow-be:8080 (direct, root-mapped) |
token(String) / tokenProvider(TokenProvider) | none | Bearer auth; tokenProvider re-evaluated per request |
defaultSourceSystem(String) | none | Used when an event has no sourceSystem |
correlationIdProvider(Supplier<String>) | none | Dynamically injects OTel / Distributed Trace IDs into events |
httpClient(HttpClient) | internal client | Bring-Your-Own java.net.http.HttpClient for fine-grained network control |
connectTimeout(Duration) | 5s | TCP connect timeout |
requestTimeout(Duration) | 10s | Per-request timeout |
retry(RetryPolicy) | exponential(3) | Retries on network / HTTP 503 errors (and, for publishBatch, rate-limited or unpublished entries) |
errorHandler(BiConsumer<AuditEvent,Throwable>) | logs via System.Logger | Sink for fireAndForget failures |
Error Handling
If an operation fails after all retries are exhausted, the client throws a unified AuditFlowException.
OpenAPI contract
The exact contract is published alongside this artifact as auditflow-api-<version>-openapi.yaml and bundled at openapi/openapi-audit-v1.yaml on the classpath, so you can reference or re-generate against it.