scalar-labs/scalardb-saga

Purpose and deployment modes

ScalarDB Saga is a Java saga/TCC orchestration system for distributed service workflows. It persists durable state and an append-only event history through ScalarDB rather than requiring a broker. It can run embedded (including Java code steps) or as a standalone server with REST and gRPC APIs.

• core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java

• server/src/main/java/com/scalar/db/saga/server/SagaServer.java

• api/src/main/java/com/scalar/db/saga/api/SagaOrchestrator.java

Public contracts and client entry points

The api module defines application-facing orchestration, administration, step, context, status, detail, and exception contracts. Embedded callers construct/use the default engine services; remote Java 8-compatible callers use gRPC SDK implementations. RPC schemas are the protocol boundary between client and server.

• api/src/main/java/com/scalar/db/saga/api/SagaAdminService.java

• api/src/main/java/com/scalar/db/saga/api/Step.java

• client/src/main/java/com/scalar/db/saga/grpc/GrpcSagaOrchestratorClient.java

• rpc/src/main/proto/saga.proto

Definition and step-resolution layer

Saga definitions are parsed from JSON/YAML, versioned/registered, and turned into executable steps. Definitions support conventional saga execution/compensation and TCC reservation/confirmation/cancellation. Steps may resolve reflectively in embedded mode or bind declarative service calls to transport adapters.

• core/src/main/java/com/scalar/db/saga/definition/SagaDefinitionParser.java

• core/src/main/java/com/scalar/db/saga/engine/SagaDefinitionRegistry.java

• core/src/main/java/com/scalar/db/saga/engine/ReflectiveStepResolver.java

• core/src/main/java/com/scalar/db/saga/transport/DeclarativeBindingTccStep.java

Execution, state transitions, and recovery

SagaEngine drives steps in order, records attempted outcomes, applies retry/timeout policy, and compensates completed work in reverse on saga failure. TCC follows reserve-before-confirm semantics; confirmation failures are recovery-driven forward progress. Recovery managers find stranded nonterminal sagas, resolve the appropriate action from durable history, and retry; retention removes old data under policy.

• core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java

• core/src/main/java/com/scalar/db/saga/engine/SagaRecoveryManager.java

• core/src/main/java/com/scalar/db/saga/engine/RecoveryActionResolver.java

• core/src/main/java/com/scalar/db/saga/engine/TimeoutPolicy.java

Persistence boundary

The engine depends on the SagaStore abstraction, with ScalarDbSagaStore implementing durable definitions, state snapshots, events, listing, and administrative audit records via ScalarDB. The event/state model enables another replica to resume a crashed coordinator; step implementations must therefore be idempotent when execution occurred before its result was recorded.

• core/src/main/java/com/scalar/db/saga/store/SagaStore.java

• core/src/main/java/com/scalar/db/saga/store/ScalarDbSagaStore.java

• core/src/main/java/com/scalar/db/saga/store/SagaEvent.java

• core/src/main/java/com/scalar/db/saga/store/SagaSchema.java

Participant-service transport and asynchronous callbacks

Declarative steps issue outbound HTTP calls through a transport abstraction, classify HTTP/transport failures for retryability, interpolate/capture saga-context values, and propagate correlation. Long-running participant work can return asynchronously and resume a saga through callback handling; callback URLs are HMAC-protected in server mode.

• core/src/main/java/com/scalar/db/saga/transport/HttpTransportAdapter.java

• core/src/main/java/com/scalar/db/saga/transport/OutboundHttpPolicy.java

• core/src/main/java/com/scalar/db/saga/transport/SagaCorrelationContext.java

• server/src/main/java/com/scalar/db/saga/server/api/CallbackResource.java

Server edge, security, and infrastructure

The server composes the core engine, ScalarDB-backed store, REST resources, and generated gRPC services. Both transports enforce authentication/authorization and rate limiting before orchestration/admin operations. Supported security providers include API keys, JWT, or noop; deployment is a Java 21 container, while client/API/RPC artifacts target Java 8. ScalarDB connects this service to supported relational, NoSQL, or cloud database backends.

• server/src/main/java/com/scalar/db/saga/server/SagaServerCommand.java

• server/src/main/java/com/scalar/db/saga/server/api/SagaResource.java

• server/src/main/java/com/scalar/db/saga/server/grpc/SagaServiceImpl.java

• server/src/main/java/com/scalar/db/saga/server/security/SagaSecurityHandler.java

• server/docker/Dockerfile