camunda / camunda/orchestration-cluster-api-python

Consume x-present-when vendor key: type leaseToken by request + withLease worker surface

Open
#282 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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-when vendor key end-to-end (fix at the bundler source if unknown x-* keys are stripped).
  • Add a generation/post-processing step that derives dependent typing for leaseToken from the marker rather than hardcoding the withLease → leaseToken relationship, following the existing hook/pipeline patterns in this repo. Keep it marker-driven and generic so a future second x-present-when field 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 withLease option (default false) on the worker config surface.
  • Thread it into the activation request body.
  • Thread the returned leaseToken through the fenced job commands (complete / fail / throw-error) when present.

Tests

  • Worker requesting a lease → activation carries withLease: true; returned leaseToken is 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 the leaseToken instance.

Notes

  • Additive and inert upstream — landing this is non-breaking.

Python-specific

  • Worker: runtime/job_worker.py; generator entry generate.py; generated package under generated/; type stubs under stubs/camunda_orchestration_sdk/api/job/ (activate_jobs.pyi, complete_job.pyi, fail_job.pyi).
  • Idiom: add with_lease: bool = False to the worker config; project lease_token typing via @overload/Optional in the stubs so a leased activation yields a non-optional token. Thread lease_token into the fenced commands and add the older-server runtime guard.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.