Skip to content

About

Go Client for the Orchestration Cluster API

Topics

Resources

Code of conduct

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

229 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Camunda 8 Orchestration Cluster API — Go SDK

Technical Preview. APIs may change between releases. See versioning.

An idiomatic Go client for the Camunda 8 Orchestration Cluster REST API, with a gRPC job-streaming worker. It pairs a generated low-level REST client (produced from the upstream OpenAPI specification) with a hand-written ergonomic runtime that handles the concerns real integrations need: configuration, authentication, adaptive backpressure, transient retry, and eventual-consistency handling.

This is a sibling of the Rust, TypeScript, Python, and C# SDKs and follows the same two-layer architecture.

Installation

go get github.com/camunda/orchestration-cluster-api-go/v11

Requires Go 1.25+. The /v11 suffix is the Camunda server line this SDK targets (8.11); see versioning.

Quick start

Construct a client (configuration comes from CAMUNDA_* environment variables) and call an ergonomic facade method:

// Configuration is resolved from CAMUNDA_* environment variables (with ZEEBE_*
// fallbacks) and validated fail-fast at construction.
client, err := camunda.New()
if err != nil {
	return err
}

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

topology, err := client.GetTopology(ctx)
if err != nil {
	return err
}
fmt.Printf("Camunda 8 %s — %d broker(s), %d partition(s)\n",
	topology.GetGatewayVersion(), len(topology.GetBrokers()), topology.GetPartitionsCount())

For production-shaped, runnable workflows, see the advanced examples: bounded load with adaptive backpressure, resilient job handling, and idempotent message correlation.

Architecture

OpenAPI spec ──▶ openapi-generator ──▶ client/  (generated REST client, never hand-edited)
gateway.proto ──▶ buf              ──▶ pb/      (generated gRPC stubs, never hand-edited)
                                          │
                     ergonomic runtime ───┤  config · auth · backpressure · retry ·
                     (hand-written)        │  eventual consistency · job workers
                                          ▼
                                   CamundaClient  (the facade you use)

Cross-cutting concerns are implemented as a composable http.RoundTripper chain (backpressure → retry → auth → base) injected into the generated client, so the generated code stays pure and regenerable.

  • Configuration — resolved from CAMUNDA_* environment variables (with ZEEBE_* fallbacks) and overridable via functional options. Validated fail-fast at construction.
  • Authentication — OAuth 2.0 client-credentials (with in-memory + on-disk token cache), HTTP Basic, or None.
  • Adaptive backpressure — an AIMD concurrency limiter that reacts to broker backpressure (HTTP 429 / 503 / RESOURCE_EXHAUSTED). BALANCED (default) gates; LEGACY observes only.
  • Transient retry — exponential backoff with full jitter on 429/502/503/504 and network errors.
  • Job workers — a REST activate-jobs worker (NewJobWorker) and a gRPC StreamActivatedJobs streaming worker (NewStreamJobWorker). Both share one JobHandler contract: returning variables completes the job, returning a *BpmnError throws a BPMN error, and returning any other error fails the job (decrementing its retries). The streaming worker also runs a low-frequency REST sidecar poll (a safety net for jobs re-queued after a timeout or a brief reconnect); poll-activated jobs are acknowledged over REST, streamed jobs over gRPC. Set WithStreamPollInterval to tune or disable it. While polls come back empty the interval backs off (×1.6, ±10% jitter, up to 60 s, as in the Camunda Java client) while the stream is open, and resets when a poll activates jobs or the stream disconnects; tune or disable this with WithStreamPollBackoff.

Configuration

Every setting is resolved from the environment and overridable with functional options. Options take precedence over environment variables:

// Functional options override the environment. Here: OAuth 2.0
// client-credentials against a SaaS cluster.
client, err := camunda.New(
	camunda.WithRestAddress("https://my-cluster.region.camunda.io"),
	camunda.WithOAuth(
		"my-client-id",
		"my-client-secret",
		"https://login.cloud.camunda.io/oauth/token",
	),
	camunda.WithOAuthAudience("zeebe.camunda.io"),
)

Authentication

Three strategies are supported: OAuth 2.0 client credentials, HTTP Basic, and none. The strategy is inferred from the credentials you supply, or set explicitly with CAMUNDA_AUTH_STRATEGY=OAUTH|BASIC|NONE.

// OAuth 2.0 client credentials. Tokens are cached in memory and on disk, and
// refreshed before expiry; concurrent refreshes are collapsed into one.
oauthClient, err := camunda.New(
	camunda.WithOAuth(
		"my-client-id",
		"my-client-secret",
		"https://login.cloud.camunda.io/oauth/token",
	),
	camunda.WithOAuthAudience("zeebe.camunda.io"),
	camunda.WithOAuthScope("camunda:read"),
	camunda.WithOAuthCacheDir("/var/cache/camunda"),
)

// HTTP Basic — typical for a Self-Managed cluster behind basic auth.
basicClient, err := camunda.New(
	camunda.WithBasicAuth("demo", "demo"),
)

// No authentication — a local development cluster with auth disabled.
openClient, err := camunda.New(camunda.WithNoAuth())

The OAuth token cache is two-tier: an in-memory cache backed by an on-disk cache (CAMUNDA_OAUTH_CACHE_DIR), so short-lived processes and CLI invocations reuse a valid token instead of re-authenticating on every start. Concurrent refreshes are collapsed into a single in-flight request.

The on-disk tier is opt-in and holds a bearer token, so it is treated as credential storage. The directory is created mode 0700 and each entry is written mode 0600 through a temp file renamed into place — so the mode is reapplied on every rewrite and a concurrent reader never sees a partially written entry. An entry found expired is deleted rather than left behind, after a re-read confirms another process has not just published a fresh one.

Entries are also checked before they are trusted. If the cache directory is writable by group or other, the cache is disabled rather than used: the entry path is derived from the token URL, client id and audience, so write access to that directory would be enough to substitute the token the SDK presents to the cluster. An individual entry whose own mode is wider than 0600 is ignored for the same reason — a restrictive directory does not stop someone rewriting a file their own permissions already allow — and the refetch that follows republishes it at 0600.

Windows: none of the above is enforced by the operating system. Go's permission bits are largely ignored on Windows — a file inherits the ACL of its parent directory, and 0700 on the directory does not restrict that ACL — so the group/other-writable check is skipped and the cache has no OS-enforced protection. Leave the on-disk cache disabled on a shared Windows host.

Configuration reference

CAMUNDA_* variables are canonical; the ZEEBE_* names are accepted as fallbacks for compatibility with older tooling. Functional options take precedence over both.

Connection

Variable Default Description
CAMUNDA_REST_ADDRESS / ZEEBE_REST_ADDRESS http://localhost:8080 Orchestration Cluster REST base address.
CAMUNDA_REST_ADDRESS_EXACT — Use CAMUNDA_REST_ADDRESS exactly as provided, without appending the /v2 suffix (for gateway/reverse-proxy fronted deployments).
CAMUNDA_GRPC_ADDRESS / ZEEBE_GRPC_ADDRESS localhost:26500 Zeebe gRPC gateway address (host:port) for the streaming job worker.
CAMUNDA_DEFAULT_TENANT_ID / CAMUNDA_TENANT_ID — Default tenant id applied to operations that accept one.
CAMUNDA_USER_AGENT — Application identifier (e.g. my-app/1.2) appended after the SDK's camunda-orchestration-sdk-go/<version> User-Agent token on REST, OAuth and gRPC requests. Never replaces it. Also WithUserAgent.

Authentication

Variable Default Description
CAMUNDA_AUTH_STRATEGY inferred OAUTH, BASIC, or NONE. Inferred from the supplied credentials when unset.
CAMUNDA_CLIENT_ID / ZEEBE_CLIENT_ID — OAuth 2.0 client id (client-credentials grant).
CAMUNDA_CLIENT_SECRET / ZEEBE_CLIENT_SECRET — OAuth 2.0 client secret.
CAMUNDA_OAUTH_URL / ZEEBE_AUTHORIZATION_SERVER_URL — OAuth 2.0 token endpoint URL.
CAMUNDA_TOKEN_AUDIENCE — OAuth token audience.
CAMUNDA_TOKEN_SCOPE — OAuth token scope.
CAMUNDA_OAUTH_CACHE_DIR — Directory for the on-disk OAuth token cache.
CAMUNDA_BASIC_AUTH_USERNAME — HTTP Basic authentication username.
CAMUNDA_BASIC_AUTH_PASSWORD — HTTP Basic authentication password.

Reliability

Variable Default Description
CAMUNDA_SDK_BACKPRESSURE_PROFILE BALANCED BALANCED (gates) or LEGACY (observe-only).
CAMUNDA_SDK_HTTP_RETRY_MAX_ATTEMPTS — Max transient-error retry attempts.
CAMUNDA_SDK_HTTP_RETRY_BASE_DELAY_MS — Base backoff delay for retries, in milliseconds.
CAMUNDA_SDK_HTTP_RETRY_MAX_DELAY_MS — Max backoff delay for retries, in milliseconds.
CAMUNDA_SDK_EVENTUAL_POLL_DEFAULT_MS — Default eventual-consistency poll timeout, in milliseconds.
CAMUNDA_SDK_LOG_LEVEL info off, error, warn, info, debug, or trace.

Job workers

Variable Default Description
CAMUNDA_WORKER_NAME hostname-derived Default worker name.
CAMUNDA_WORKER_TIMEOUT — Default job activation timeout, in milliseconds.
CAMUNDA_WORKER_MAX_CONCURRENT_JOBS / CAMUNDA_WORKER_MAX_JOBS_ACTIVE — Default max concurrently-activated jobs per worker.
CAMUNDA_WORKER_REQUEST_TIMEOUT — Default activate-jobs request timeout, in milliseconds.
CAMUNDA_WORKER_STARTUP_JITTER_MAX_SECONDS — Max random startup delay for workers, in seconds.

Transport

Variable Default Description
CAMUNDA_FALCON true Enable the FALCON command-stream transport upgrade when the gateway advertises it.
CAMUNDA_FORCE_REST — Force the pure-REST path even when the gateway advertises FALCON.
CAMUNDA_SDK_HTTP_MAX_IDLE_CONNS 256, grown to fit workers Max idle (keep-alive) HTTP connections across all hosts. Setting it pins the value.
CAMUNDA_SDK_HTTP_MAX_IDLE_CONNS_PER_HOST 256, grown to fit workers Max idle (keep-alive) HTTP connections per host. Setting it pins the value.

The SDK never uses http.DefaultTransport directly: it clones it and sizes the idle-connection pool for job-worker workloads. Go's default pool keeps only 2 idle connections per host, so a worker with many jobs in flight otherwise opens and closes a TCP connection per call — churning sockets into TIME_WAIT, exhausting ephemeral ports, and roughly halving throughput at moderate concurrency.

The 256 default is a floor: each time you create a job worker (NewJobWorker or NewStreamJobWorker) the SDK grows the pool so it covers the sum of all the client's workers' MaxConcurrentJobs plus one activation poll per worker. For example, 50 workers × 32 concurrent jobs raises both limits to 1,650. The pool is resized by swapping in a resized clone of the SDK's own transport, so in-flight requests are never disturbed. The pool never shrinks.

Explicit settings always win: a value set through CAMUNDA_SDK_HTTP_MAX_IDLE_CONNS(_PER_HOST) or WithMaxIdleConns(PerHost) pins that limit and turns off automatic growth for it. A transport supplied with WithTransport / WithHTTPClient is never touched. When pinning CAMUNDA_SDK_HTTP_MAX_IDLE_CONNS_PER_HOST, remember that CAMUNDA_SDK_HTTP_MAX_IDLE_CONNS caps the idle pool across all hosts, so raise it too (or set 0 for no global limit).

For full control, supply your own HTTP plumbing:

// WithTransport replaces the base RoundTripper; the SDK's retry, backpressure
// and auth layers still apply on top of it.
client, err := camunda.New(camunda.WithTransport(&http.Transport{
	MaxIdleConns:        1024,
	MaxIdleConnsPerHost: 1024,
}))
// WithHTTPClient replaces the whole HTTP client; it is used as-is, so the
// SDK's retry, backpressure, auth and TLS layers are bypassed.
client, err := camunda.New(camunda.WithHTTPClient(&http.Client{
	Transport: &http.Transport{MaxIdleConnsPerHost: 1024},
	Timeout:   30 * time.Second,
}))

The two options are mutually exclusive — setting both fails New with a configuration error.

Invalid values are rejected at construction with a configuration error rather than being silently coerced, so a typo in a deployment manifest fails the process at startup instead of at first request.

TLS and mutual TLS

TLS is derived from the scheme of CAMUNDA_REST_ADDRESS. Mutual TLS and custom certificate authorities — for a Self-Managed cluster behind a private CA, or one requiring client certificates — are configured by environment variable. Inline PEM values take precedence over the corresponding *_PATH file locations.

Variable Description
CAMUNDA_MTLS_CERT Inline client certificate PEM.
CAMUNDA_MTLS_KEY Inline client private key PEM.
CAMUNDA_MTLS_CA Inline CA certificate PEM for verifying the server.
CAMUNDA_MTLS_CERT_PATH Path to the client certificate PEM.
CAMUNDA_MTLS_KEY_PATH Path to the client private key PEM.
CAMUNDA_MTLS_CA_PATH Path to the CA certificate PEM.
CAMUNDA_MTLS_KEY_PASSPHRASE Recognized but not supported yet — setting it fails client construction. Supply an unencrypted client key.

The same material is applied to both the REST transport and the gRPC streaming worker, so a single configuration covers every connection the SDK opens.

Job workers

Register a REST activate-jobs worker with NewJobWorker. The handler's return value decides the job outcome:

// One JobHandler contract for both workers: returning variables completes the
// job; returning a *camunda.BpmnError throws a BPMN error; returning any other
// error fails the job (decrementing its retries).
worker := client.NewJobWorker("greet",
	func(ctx context.Context, job *camunda.Job) (map[string]any, error) {
		var in struct {
			Name string `json:"name"`
		}
		if err := job.Variables(&in); err != nil {
			return nil, err
		}
		return map[string]any{"greeting": "Hello, " + in.Name + "!"}, nil
	},
	camunda.WithMaxConcurrentJobs(10),
	camunda.WithPollInterval(500*time.Millisecond),
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Run blocks until ctx is canceled, draining in-flight jobs on shutdown.
if err := worker.Run(ctx); err != nil {
	fmt.Println("worker stopped:", err)
}

For high-throughput, low-latency work, use the gRPC streaming worker (NewStreamJobWorker) — a capability unique to this SDK among the Camunda Orchestration Cluster SDKs:

// The gRPC streaming worker activates jobs over a StreamActivatedJobs stream
// and acknowledges them over gRPC. A low-frequency REST sidecar poll backs it
// up (a safety net for jobs re-queued after a timeout or brief reconnect).
worker := client.NewStreamJobWorker("greet",
	func(ctx context.Context, job *camunda.Job) (map[string]any, error) {
		return map[string]any{"greeting": "Hello!"}, nil
	},
	camunda.WithStreamPollInterval(30*time.Second), // -1 disables the sidecar poll
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

if err := worker.Run(ctx); err != nil {
	fmt.Println("stream worker stopped:", err)
}

Pass camunda.WithStreamJobLease(true) to activate jobs with a lease. Each job then carries a lease token that the worker sends back when it completes, fails, or throws — so if the job timed out and another worker picked it up, the stale acknowledgement is rejected instead of racing the newer activation. It covers both the gRPC stream and the REST sidecar poll. The REST worker takes the same option as camunda.WithJobLease(true). Leases are off by default (matching the engine) and need an engine that supports them: rather than degrade to unfenced commands, a worker that asked for a lease and is handed a job without a token rejects the activation with camunda.ErrLeaseNotHonored.

Each job stream is recycled proactively, matching the Camunda Java client. camunda.WithStreamMaxLifetime (default 8 h) closes a stream and opens a new one at once, so streams rebalance across gateways after a scale-out or restart. camunda.WithStreamInactivityTimeout (default 10 min, must be less than the max lifetime) recycles a stream that has delivered no job for that long, catching streams that stay connected but stop delivering. Both deadlines are jittered down by up to 10% per stream, so a fleet started together does not recycle in lockstep; pass 0 to disable either. Jobs already received keep running and are acknowledged normally, and each recycle is logged at debug level. Rebalancing needs a request-level (L7) gRPC load balancer (Envoy, nginx gRPC, the SaaS ingress): behind a plain L4 load balancer the worker reuses its HTTP/2 connection, so the new stream lands on the same gateway; use DNS or client-side balancing there.

Job variables are untrusted input

Job variables reach your handler through the cluster, but their content is set by whoever started the process instance — a REST caller, a message publisher, an upstream service, or an earlier task. Treat them the way you would treat the body of an HTTP request from the internet.

What the SDK does:

  • Decodes into JSON-shaped values only. REST-activated jobs carry the variables as a map[string]any; gRPC-streamed jobs arrive as JSON strings and are decoded with encoding/json into a map[string]any. No mechanism here can instantiate a type chosen by the payload — there is no equivalent of unpickling or polymorphic deserialization.
  • Fills only the type you named. job.Variables(&v) re-marshals the decoded map and unmarshals it into the type you supplied. The payload selects values, never a type.
  • Bounds nesting. encoding/json rejects input nested deeper than 10000, so a deeply nested payload cannot exhaust the stack. Note what that means per transport: on a gRPC-streamed job the decode error is swallowed and the handler simply sees no variables (an empty map), so job.Variables(&v) succeeds against nothing — check for the keys you need rather than assuming a decode failure will surface as an error.
  • Keeps variable values out of its own log records. The worker logs job keys and types, never the variable map, and an undecodable frame is reported without its payload. One caveat: a decoding error is logged, and a Go JSON error can quote the offending literal — json: cannot unmarshal number 1e100000 into Go value of type float64 — so a malformed value can reach the log by that route.
  • Does not share variables between jobs. Each job gets its own *Job with its own maps before its handler goroutine starts, so concurrent handlers never share or mutate the same values. Reading from the map RawVariables() returns is always safe; copy it before writing rather than mutating what is returned.

What the SDK does not do:

  • No variable-specific size limit. Nothing inspects how large a variable payload is: whatever arrives is decoded. Two unrelated limits sit nearby and should not be mistaken for one — the FALCON command stream caps a single frame at 16 MiB (a transport limit, and it does not apply to REST or gRPC), and WithMaxConcurrentJobs / WithStreamMaxConcurrentJobs cap how many handlers run at once, which bounds neither the bytes in one payload nor the jobs buffered before dispatch. The engine applies its own limits; the SDK adds none of its own. Whether it should — and what the limit would be — is an open question tracked in #140; no limit is being introduced quietly.
  • No validation or sanitisation. The SDK does not check types, ranges, lengths or encodings beyond what JSON decoding requires. Validate in your handler.
  • No interpretation. A variable that happens to contain a path, a URL, a SQL fragment or a shell string is just a string to the SDK. If your handler passes one to a filesystem, a query, a template or a subprocess, that is your trust boundary to enforce.

Job Corrections (User Task Listeners)

When a job worker handles a user task listener, it can correct task properties (assignee, due date, candidate groups, etc.) by completing the job with a job result. Write the handler as a camunda.JobCompletionHandler, which returns a camunda.JobCompletion, and adapt it with camunda.CompletionHandler:

// A CompletionHandler returns a JobCompletion, which can carry a job result
// alongside the variables. Adapt it for NewJobWorker or NewStreamJobWorker.
worker := client.NewJobWorker("io.camunda:userTaskListener",
	camunda.CompletionHandler(func(ctx context.Context, job *camunda.Job) (camunda.JobCompletion, error) {
		corrections := camunda.NewJobResultCorrections()
		corrections.SetAssignee("corrected-user")
		corrections.SetPriority(80)
		corrections.SetFollowUpDate(camunda.ClearedDateTime()) // sent as "": removes the follow-up date
		return camunda.JobCompletion{Result: camunda.CorrectUserTask(*corrections)}, nil
	}),
	camunda.WithMaxConcurrentJobs(5),
)

To deny a task completion (reject the work):

return camunda.JobCompletion{
	Result: camunda.DenyUserTask("Insufficient documentation"),
}, nil
Correctable attribute Setter on JobResultCorrections Clear value
assignee SetAssignee(string) Empty string ""
dueDate SetDueDate(camunda.DateTime(t)) SetDueDate(camunda.ClearedDateTime()) (sent as "")
followUpDate SetFollowUpDate(camunda.DateTime(t)) SetFollowUpDate(camunda.ClearedDateTime()) (sent as "")
candidateUsers SetCandidateUsers([]string) Empty slice []string{}
candidateGroups SetCandidateGroups([]string) Empty slice []string{}
priority SetPriority(int32) (0–100) —

Leaving an attribute unset (or setting it to nil with its Set…Nil method) preserves the persisted value. The two dates are ClearableDateTime values: camunda.DateTime(t) sets a date and camunda.ClearedDateTime() clears it (sent as ""). The clear lives on the JobResultCorrections model, so it also applies when you build a JobCompletionRequest for client.CompleteJob yourself.

Ad-hoc sub-process results

The job of an ad-hoc sub-process completes with a result that names the inner elements to activate next and whether the sub-process is done:

// The job of an ad-hoc sub-process decides which inner elements to activate
// next, and whether the sub-process is done.
worker := client.NewJobWorker("plan-next-steps",
	camunda.CompletionHandler(func(ctx context.Context, job *camunda.Job) (camunda.JobCompletion, error) {
		result := camunda.NewJobResultAdHocSubProcess()
		result.SetActivateElements([]camunda.JobResultActivateElement{
			camunda.ActivateAdHocElement("review_document", map[string]any{"reviewer": "alice"}),
			camunda.ActivateAdHocElement("notify_customer", nil),
		})
		result.SetIsCompletionConditionFulfilled(false)
		result.SetIsCancelRemainingInstances(false)
		return camunda.JobCompletion{
			Variables: map[string]any{"planned": true},
			Result:    camunda.AdHocSubProcessJobResult(*result),
		}, nil
	}),
)

The worker sets the result's type discriminator (userTask or adHocSubProcess) from the variant you populate, so a result built directly from the generated JobResult union is sent correctly too. A result with no variant — or both — fails the job rather than completing it without the result. Job results work with both workers: the gRPC streaming worker sends them on CompleteJob, and the REST worker on POST /jobs/{jobKey}/completion.

The FALCON command stream (used by NewJobWorker when a nanobpmn gateway advertises it) cannot carry a job result: its completion frame has no result field. On FALCON, a handler that returns a result fails the job with a message saying so, rather than completing it without the result — which would, for example, approve a task the listener denied. To use job results against such a gateway, set CAMUNDA_FORCE_REST=true (or camunda.WithForceREST(true)) so the worker polls over REST.

Panicking handlers

A handler runs on its own goroutine, and in Go an unrecovered panic on any goroutine terminates the whole process. The workers therefore recover a panicking handler and fail the job with it, on every transport (REST polling, the FALCON command stream, the gRPC stream, and the gRPC worker's REST sidecar poll):

  • The job is failed exactly as it would be for a returned error, so its retries decrement and the engine schedules a retry instead of leaving the job to sit until its activation timeout expires.
  • The recovered panic is observable through the SDK log and through the failed job (and its incident) on the cluster. It is not returned to your code: the worker consumes the resulting camunda.ErrHandlerPanic internally and Run does not return per-job handler errors, so errors.Is cannot be used to detect it from application code.
  • The panic value and a stack trace are written to the SDK log at error level — the same detail the runtime would have printed to stderr as the process died.
  • The panic value is not sent to the cluster. The failure message the engine stores on the incident says only that the handler panicked, because that message is durable and widely visible, and a panic value can carry job-variable content.

This is a deliberate choice rather than a silent one: a panic is a bug in the handler, but losing the host application (and every other job it was running) is a disproportionate consequence. If your handler must not be recovered — if a panic indicates corrupted process state that should stop the program — detect that in the handler and terminate the process explicitly rather than relying on the panic to propagate. There is deliberately no option to turn recovery off; adding one would be a design decision for the SDK team.

Deploying and starting processes

The facade exposes request bodies as first-class parameters; the Raw() escape hatch covers anything the facade doesn't (such as multipart resource upload):

// Deploy a BPMN process. Multipart resource upload goes through the Raw()
// generated client (the escape hatch for anything the facade doesn't cover).
f, err := os.Open("greet.bpmn")
if err != nil {
	return err
}
defer func() { _ = f.Close() }()

if _, _, err := client.Raw().ResourceAPI.CreateDeployment(ctx).
	Resources([]*os.File{f}).
	Execute(); err != nil {
	return err
}

// Start an instance by process id. The request body is a first-class facade
// parameter — no Raw() needed.
byID := camunda.NewProcessInstanceCreationInstructionById(camunda.ProcessDefinitionId("demo-process"))
byID.SetVariables(map[string]any{"name": "Camunda"})
instruction := camunda.ProcessInstanceCreationInstructionByIdAsProcessInstanceCreationInstruction(byID)

instance, err := client.CreateProcessInstance(ctx, instruction)
if err != nil {
	return err
}
fmt.Printf("started process instance %v\n", instance.GetProcessInstanceKey())

Backpressure

A Camunda broker sheds load by rejecting commands (HTTP 429 / 503, RESOURCE_EXHAUSTED). Rather than surfacing those to your code as a wall of errors, the SDK gates outbound requests through an AIMD concurrency limiter — the same additive-increase/multiplicative-decrease shape TCP uses. Throughput rises while the cluster is healthy and backs off the moment it pushes back, so a burst queues client-side instead of being shed:

// BALANCED (the default) gates outbound requests through an AIMD concurrency
// limiter that reacts to broker backpressure (HTTP 429/503). LEGACY observes
// and reports, but never gates — use it to compare against older SDKs.
client, err := camunda.New(
	camunda.WithBackpressureProfile(camunda.ProfileLegacy),
)

BALANCED is the default and is what you want in production. LEGACY keeps the controller's observability but never gates, which is useful when comparing behavior against an older SDK or when an external system already governs concurrency.

Transient retry

Retries are layered below backpressure in the http.RoundTripper chain, so a retried request is still subject to the concurrency limiter and cannot amplify a load spike:

// Transient failures (429, 502, 503, 504 and network errors) are retried with
// exponential backoff and full jitter. Non-transient 4xx are never retried.
client, err := camunda.New(
	camunda.WithRetry(camunda.RetryConfig{
		MaxAttempts: 5,
		BaseDelay:   100 * time.Millisecond,
		MaxDelay:    5 * time.Second,
	}),
)

Only transient failures are retried. A 400, 403, or 404 is returned to you immediately — retrying a request the server has definitively rejected wastes time and hides the real error.

Eventual consistency

Reads are served from the cluster's secondary storage and are eventually consistent. Poll retries a read (by default while it returns 404) until the entity is visible or a timeout elapses:

// Reads are eventually consistent: a just-created entity may briefly 404.
// Poll retries 404s until the entity is visible or the timeout elapses.
key := camunda.MustProcessInstanceKey("2251799813685249")

instance, err := camunda.Poll(ctx, func(ctx context.Context) (*camunda.ProcessInstanceResult, error) {
	return client.GetProcessInstance(ctx, key)
}, camunda.WithPollTimeout(10*time.Second))
if err != nil {
	return err
}
fmt.Printf("instance state: %v\n", instance.GetState())

Clocks

Retry backoff, the backpressure gate, token refresh, job-worker polling and consistency polling all resolve through an injected clock rather than the time package, so a test can control cadence instead of waiting for it.

Two places deliberately stay on real time, each marked with a //nolint:forbidigo naming the reason: LiveClock itself, which is the adapter onto the time package, and internal/falcon, whose timers are mostly I/O bounds — read-idle detection and create-ack budgets — that would misfire if bound to engine time.

Clock Use
LiveClock real time; the default when nothing is injected
your own Clock tests; return whatever Now you like and make Sleep return immediately
EngineClock drives the Camunda engine's clock and the SDK's together

A local test clock makes the SDK wait instantly, but the engine carries on in real time — so a process that only completes once a BPMN timer fires still takes as long as the timer says. EngineClock is for that case.

Waiting inside a handler

A Job carries its worker's clock, so a handler that needs to wait can do it on the same clock as everything else:

worker := client.NewJobWorker("payment", func(ctx context.Context, job *camunda.Job) (map[string]any, error) {
	// Short coordination only -- a business wait belongs in the process as a
	// BPMN timer event.
	if err := job.Clock().Sleep(ctx, 500*time.Millisecond); err != nil {
		return nil, err
	}
	return map[string]any{"paid": true}, nil
})

Keep those waits short — spacing a retry, letting a resource settle. A long or business wait belongs in the process as a BPMN timer event, not in a handler. A handler that sleeps for minutes holds a worker slot for the duration, risks the job timeout expiring underneath it, and hides the delay from the process model, where it would otherwise be visible and changeable without a redeploy.

Driving the engine's clock

EngineClock pins the engine's clock instead of passing time locally:

// The control client issues the pin requests and keeps real time itself.
control, err := camunda.New(camunda.WithRestAddress(addr))
if err != nil {
	return err
}
clock := camunda.NewEngineClock(control)

// Anything this client waits on now advances the engine instead of real time.
client, err := camunda.New(camunda.WithRestAddress(addr), camunda.WithClock(clock))
if err != nil {
	return err
}

A wait now moves the engine forward and reports the new instant, so the SDK and the engine agree on what time it is. Waits that overlap — those that read the clock before any of them lands — settle at a single instant rather than summing; a wait that begins after an earlier one has landed reads the new time and composes from it. PinTo and Reset are available directly for tests that need to move the engine without waiting.

Clock pinning is an alpha engine endpoint, intended for tests rather than production clusters. Pass the control client the pin requests should travel on: it keeps real time, so the requests themselves are unaffected by the pinning.

Writing your own

Clock is a public interface (Now, Sleep, After); implement it and pass it to camunda.WithClock. ClockController is the engine-side half, if you want EngineClock to drive something other than a CamundaClient.

Ambient time is banned in the runtime by .golangci.yml — time.Now, time.Sleep, time.NewTimer and friends — so cadence cannot quietly drift back onto real time.

Reproducible jitter

Retry backoff, worker startup delay (CAMUNDA_WORKER_STARTUP_JITTER_MAX_SECONDS) and FALCON endpoint selection draw from an injected Random rather than math/rand. The default, LiveRandom, is the process-wide generator. A SeededRandom replays the same sequence for the same seed, so a test can assert the exact delays the SDK schedules instead of a range:

// Seeds from CAMUNDA_TEST_SEED when it is set, otherwise from a fresh seed.
random, err := camunda.SeededRandomFromEnv()
if err != nil {
	return err
}
// Log the source: it names the seed and how to replay this run.
fmt.Println(random) // SeededRandom(seed=...; replay with CAMUNDA_TEST_SEED=...)

client, err := camunda.New(camunda.WithRandom(random))

The seeded generator is specified across the Camunda SDKs, so one seed produces the same draws in every language. A worker draws its startup delay when it is built, not when Run starts, so the delays follow construction order however the goroutines are scheduled.

math/rand is banned in the runtime by .golangci.yml, alongside ambient time.

Semantic keys

Identifier types (JobKey, ProcessInstanceKey, …) are validated named string types rather than bare strings:

// Semantic key types validate their format at construction.
key, err := camunda.NewJobKey("2251799813685424") // validates pattern & length
if err != nil {
	return err
}
fmt.Println(key.String())

// Side-load a key you already trust, without validation:
loose := camunda.MustJobKey("2251799813685424")
_ = loose

Error handling

A server-side 4xx/5xx surfaces as a typed *APIError carrying the HTTP status and response body; anything else is a transport-level error:

_, err := client.GetTopology(ctx)
var apiErr *camunda.APIError
if errors.As(err, &apiErr) {
	// The server returned a 4xx/5xx — inspect the status and response body.
	fmt.Printf("API error: HTTP %d — %s\n", apiErr.Status, apiErr.Body)
} else if err != nil {
	// Transport-level failure (DNS, TLS, connection refused, ...).
	fmt.Println("request failed:", err)
}

Two helpers cover the common classifications without unwrapping by hand:

key := camunda.MustProcessInstanceKey("2251799813685249")

_, err := client.GetProcessInstance(ctx, key)

// IsNotFound is the idiomatic 404 check — the common case when reading an
// entity that has not yet propagated to secondary storage.
if camunda.IsNotFound(err) {
	fmt.Println("not visible yet")
	return nil
}

// StatusCode reports the HTTP status for any server-side error, and
// ok == false for transport-level failures.
if status, ok := camunda.StatusCode(err); ok {
	fmt.Printf("server rejected the request: HTTP %d\n", status)
}

Errors are values throughout: use errors.Is for sentinels and errors.As for typed errors. A function that cannot honour its contract returns an error rather than a zero value or a best-guess default.

Logging

The SDK logs through a level-gated internal logger, off by default at anything above info:

// Levels: LogOff, LogError, LogWarn, LogInfo (default), LogDebug, LogTrace.
// LogDebug reports auth-token refreshes, retries, and backpressure decisions;
// LogTrace adds per-request detail. Credentials are never logged.
client, err := camunda.New(camunda.WithLogLevel(camunda.LogDebug))

Set CAMUNDA_SDK_LOG_LEVEL=debug to get the same effect without a code change — useful when diagnosing an authentication or backpressure problem in a deployed service. Secrets (client secrets, passwords, bearer tokens, TLS key material) are never written to the log at any level.

The full API surface

CamundaClient exposes one ergonomic method per operation in the OpenAPI specification, generated from the same spec as the low-level client so the two can never diverge. Each facade method flattens the generated builder into first-class parameters and returns the deserialized result.

Every request, response, key and enum type is available from the camunda package, so one import covers normal use. Only the raw HTTP-client machinery — the client Raw() returns, its configuration, and its error type — stays in the generated github.com/camunda/orchestration-cluster-api-go/v11/client package.

When you need something the facade deliberately does not model — multipart uploads, unusual query-parameter combinations, or the raw *http.Response — Raw() hands you the generated client directly:

// Raw() exposes the generated client: every operation, with the full builder
// surface. Use it for anything the facade does not cover, and for access to
// the raw *http.Response.
result, resp, err := client.Raw().ProcessDefinitionAPI.
	SearchProcessDefinitions(ctx).
	Execute()
if err != nil {
	return err
}
fmt.Printf("HTTP %d — %d process definition(s)\n", resp.StatusCode, len(result.GetItems()))

Requests made through Raw() still traverse the full runtime — backpressure, retry, and authentication all apply, because those are http.RoundTripper layers on the transport rather than facade-level wrappers.

Full API documentation is published on pkg.go.dev.

Regenerating the client

client/, pb/, facade_generated.go and reexport_generated.go are generated. Never hand-edit them — change the generator instead, under scripts/hooks/ (post-processing) or cmd/facadegen/ (the facade and re-export generator).

make bundle        # re-bundle the upstream OpenAPI spec, then regenerate
make fetch-proto   # fetch gateway.proto
make generate      # regenerate from the already-fetched inputs
make check         # full local gate: fmt, vet, build, test, examples, snippet sync

When a change modifies the generator and its output, commit them separately — the generator change first, the regenerated output second. See AGENTS.md for the full contributor workflow.

All README examples are compiled from examples/readme.go by make sync-readme, so they cannot drift from the real API. Edit the region in the Go source, run make sync-readme, and commit both files — never edit a fenced code block in this README by hand.

Documentation site

The guide sections of this README and a go/doc-derived API reference are rendered into Docusaurus markdown for https://docs.camunda.io:

make docs-json    # cmd/docgen -> docs-json/*.json
make docs-md      # docs-json + README -> docs-md/

Content between <!-- docs:cut:start --> and <!-- docs:cut:end --> markers is maintainer-only and is excluded from the published pages. Both output directories are generated and gitignored; a scheduled workflow in camunda-docs runs make docs-md and opens the update PR.

Versioning

The SDK major version tracks the Camunda server minor version: use the SDK line that matches your server. Go requires majors ≥ 2 to carry a /vN module-path suffix, so the import path names the server line:

Camunda server Module path suffix Branch
8.10 /v10 stable/10
8.11 (in development) /v11 main

Moving to a new server minor means changing the import path. Releases before v10 (v0.x) used the module path without a suffix.

License

Apache-2.0. See LICENSE.

About

Go Client for the Orchestration Cluster API

Topics

Resources

Code of conduct

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages