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.
go get github.com/camunda/orchestration-cluster-api-go/v11Requires Go 1.25+. The /v11 suffix is the Camunda server line this SDK targets
(8.11); see versioning.
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.
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 (withZEEBE_*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;LEGACYobserves 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 gRPCStreamActivatedJobsstreaming worker (NewStreamJobWorker). Both share oneJobHandlercontract: returning variables completes the job, returning a*BpmnErrorthrows 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. SetWithStreamPollIntervalto 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 withWithStreamPollBackoff.
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"),
)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
0700on 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.
CAMUNDA_* variables are canonical; the ZEEBE_* names are accepted as
fallbacks for compatibility with older tooling. Functional options take
precedence over both.
| 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. |
| 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. |
| 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. |
| 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. |
| 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 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.
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 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 withencoding/jsoninto amap[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/jsonrejects 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), sojob.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
*Jobwith its own maps before its handler goroutine starts, so concurrent handlers never share or mutate the same values. Reading from the mapRawVariables()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/WithStreamMaxConcurrentJobscap 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.
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.
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.
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.ErrHandlerPanicinternally andRundoes not return per-job handler errors, soerrors.Iscannot 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.
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())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.
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.
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())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.
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.
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.
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.
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.
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")
_ = looseA 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.
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.
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.
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 syncWhen 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.
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.
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.
Apache-2.0. See LICENSE.