camunda / camunda/orchestration-cluster-api-python
Consume x-present-when vendor key: type leaseToken by request + withLease worker surface
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6h 15m
- Merged PRs (30d)
- 20
Description
Summary
Upstream camunda/camunda#62777 adds a new field-level vendor extension x-present-when to the OpenAPI spec and applies it to ActivatedJobResult.leaseToken:
x-present-when: { request: withLease, equals: true }
Semantics: leaseToken is present (required, non-null) iff the activation request had withLease: true, and absent otherwise. OpenAPI 3.x can't express request→response dependent presence, so every SDK currently types leaseToken as always-nullable — code that reads it after an unleased activation compiles cleanly but fails at runtime. The marker is the ground truth each SDK derives dependent typing from. It is inert on the wire (no behavioural/wire change); this is a client-typing refinement plus a runtime surface to opt into leasing.
Sibling tracking issue (JS): camunda/orchestration-cluster-api-js#513.
Scope
Two surfaces:
1. Teach the generator about x-present-when
- Verify the spec bundler preserves the
x-present-whenvendor key end-to-end (fix at the bundler source if unknownx-*keys are stripped). - Add a generation/post-processing step that derives dependent typing for
leaseTokenfrom the marker rather than hardcoding thewithLease → leaseTokenrelationship, following the existing hook/pipeline patterns in this repo. Keep it marker-driven and generic so a future secondx-present-whenfield is handled automatically. - Design the derived projection (present / absent / dynamic) consistent with the per-SDK derivation contract in §2.21 of the upstream REST API endpoint guidelines, including the runtime guard for a newer client hitting an older server that doesn't populate the token.
2. Absorb the withLease surface in the hand-written job worker
- Expose a
withLeaseoption (defaultfalse) on the worker config surface. - Thread it into the activation request body.
- Thread the returned
leaseTokenthrough the fenced job commands (complete / fail / throw-error) when present.
Tests
- Worker requesting a lease → activation carries
withLease: true; returnedleaseTokenis threaded into the fenced commands. - Worker without it → no
withLease; commands carry no lease token. - A derivation/typing test scoped to the class of defect (dependent presence derived from
x-present-when), not just theleaseTokeninstance.
Notes
- Additive and inert upstream — landing this is non-breaking.
Python-specific
- Worker:
runtime/job_worker.py; generator entrygenerate.py; generated package undergenerated/; type stubs understubs/camunda_orchestration_sdk/api/job/(activate_jobs.pyi,complete_job.pyi,fail_job.pyi). - Idiom: add
with_lease: bool = Falseto the worker config; projectlease_tokentyping via@overload/Optionalin the stubs so a leased activation yields a non-optional token. Threadlease_tokeninto the fenced commands and add the older-server runtime guard.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with generate.py and the existing generator hook or pipeline patterns, then inspect runtime/job_worker.py and the listed activation and command stubs. Verify that x-present-when survives bundling and that dependent typing is derived generically, then test withLease activation, lease-token threading, and the older-server guard for both leased and unleased workers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, python
- Domain
- api, backend, developer-experience
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100