docs: concurrency model + SDK 26.05.02 + new env settings#27
Merged
Conversation
New canonical reference at ``docs/concurrency.md`` covering the
multi-worker safety story the recent four PRs delivered: atomic state
transitions, per-group ``pg_try_advisory_lock`` in the EDA drain,
idempotency-key collision recovery, and the ``JobReaper`` /
``BboxReaper`` orphan-revival sidecars. Includes lease defaults, the
five orphan classes the reaper handles, and operator-side recipes for
detecting + manually re-claiming stuck jobs.
Documentation drift fixes:
* ``docs/deployment.md`` -- the scaling table claimed worker delivery
was sharded via Redis consumer groups. That's only true when
``FLYDOCS_EDA_ADAPTER=redis``; the default is ``postgres`` with the
advisory-lock-based competitive consumer. Rewrote both Worker /
Bbox worker rows and the Redis / Postgres rows.
* ``docs/troubleshooting.md`` -- added "Stuck jobs" section with one
SQL snippet per orphan class + the operator override for forcing a
re-claim, plus the explicit "cancel a RUNNING job" recipe.
* ``env_template`` -- added five concurrency settings introduced by
the reaper PR (``FLYDOCS_JOB_RUN_LEASE_S``,
``FLYDOCS_BBOX_REFINE_LEASE_S``, ``FLYDOCS_REAPER_SWEEP_INTERVAL_S``,
``FLYDOCS_QUEUED_ORPHAN_THRESHOLD_S``,
``FLYDOCS_PARTIAL_SUCCEEDED_ORPHAN_THRESHOLD_S``).
Java SDK docs:
* ``QUICKSTART.md`` -- Spring Boot starter quickstart; fixed an
existing snippet that called ``doc.fields()`` on a
``Map<String,Object>``.
* ``TUTORIAL.md`` -- two new sections: Spring Boot starter and
resilience knobs (opt-in retry, pool sizing, AutoCloseable).
Table of contents updated.
* ``flydocs-examples/README.md`` -- NEW. 1:1 parity with the Python
SDK's examples README.
Version bumps to 26.05.02 (CalVer):
* Python: ``sdks/python/pyproject.toml`` + ``_version.py``.
* Java: parent + 3 submodule poms via
``versions:set -DprocessAllModules=true``; ``USER_AGENT`` constant in
``FlydocsClientAsync``; ``<dependency>`` snippets in README +
QUICKSTART + TUTORIAL.
All test suites green: Python 311 passed (2 LLM smoke tests skipped),
Java reactor 53 passed + 5 live integration vs the running API.
ancongui
added a commit
that referenced
this pull request
May 31, 2026
New canonical reference at ``docs/concurrency.md`` covering the
multi-worker safety story the recent four PRs delivered: atomic state
transitions, per-group ``pg_try_advisory_lock`` in the EDA drain,
idempotency-key collision recovery, and the ``JobReaper`` /
``BboxReaper`` orphan-revival sidecars. Includes lease defaults, the
five orphan classes the reaper handles, and operator-side recipes for
detecting + manually re-claiming stuck jobs.
Documentation drift fixes:
* ``docs/deployment.md`` -- the scaling table claimed worker delivery
was sharded via Redis consumer groups. That's only true when
``FLYDOCS_EDA_ADAPTER=redis``; the default is ``postgres`` with the
advisory-lock-based competitive consumer. Rewrote both Worker /
Bbox worker rows and the Redis / Postgres rows.
* ``docs/troubleshooting.md`` -- added "Stuck jobs" section with one
SQL snippet per orphan class + the operator override for forcing a
re-claim, plus the explicit "cancel a RUNNING job" recipe.
* ``env_template`` -- added five concurrency settings introduced by
the reaper PR (``FLYDOCS_JOB_RUN_LEASE_S``,
``FLYDOCS_BBOX_REFINE_LEASE_S``, ``FLYDOCS_REAPER_SWEEP_INTERVAL_S``,
``FLYDOCS_QUEUED_ORPHAN_THRESHOLD_S``,
``FLYDOCS_PARTIAL_SUCCEEDED_ORPHAN_THRESHOLD_S``).
Java SDK docs:
* ``QUICKSTART.md`` -- Spring Boot starter quickstart; fixed an
existing snippet that called ``doc.fields()`` on a
``Map<String,Object>``.
* ``TUTORIAL.md`` -- two new sections: Spring Boot starter and
resilience knobs (opt-in retry, pool sizing, AutoCloseable).
Table of contents updated.
* ``flydocs-examples/README.md`` -- NEW. 1:1 parity with the Python
SDK's examples README.
Version bumps to 26.05.02 (CalVer):
* Python: ``sdks/python/pyproject.toml`` + ``_version.py``.
* Java: parent + 3 submodule poms via
``versions:set -DprocessAllModules=true``; ``USER_AGENT`` constant in
``FlydocsClientAsync``; ``<dependency>`` snippets in README +
QUICKSTART + TUTORIAL.
All test suites green: Python 311 passed (2 LLM smoke tests skipped),
Java reactor 53 passed + 5 live integration vs the running API.
Co-authored-by: ancongui <andres.contreras@soon.es>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation + version bumps closing out the last four PRs (#23, #24, #25, #26) and preparing the 26.05.02 SDK release.
New canonical doc
docs/concurrency.md— the multi-worker scaling story we've been improving end-to-end:Drift fixes
docs/deployment.mdFLYDOCS_EDA_ADAPTER=redis. Default ispostgreswith the advisory-lock-based competitive consumer. Worker / Bbox worker / Postgres / Redis rows all rewritten.docs/troubleshooting.mdenv_templateJava SDK docs
sdks/java/QUICKSTART.mddoc.fields()on aMap<String,Object>.sdks/java/TUTORIAL.mdsdks/java/flydocs-examples/README.mdmvn exec:javainvocations + Spring Boot run command for the webhook receiver.Version bumps to 26.05.02
sdks/python/pyproject.tomlsdks/python/src/flydocs_sdk/_version.pysdks/java/pom.xml(parent)sdks/java/flydocs-sdk/pom.xmlsdks/java/flydocs-spring-boot-starter/pom.xmlsdks/java/flydocs-examples/pom.xmlFlydocsClientAsync.USER_AGENTTagging
v26.05.02after merge fires.github/workflows/publish-sdks.yamlwhich deploys the Java multi-module reactor to GitHub Packages and attaches the Python wheel + sdist to the GitHub Release.Test plan
tests/unit + tests/integration: 311 passed, 2 skipped.tests/eda: 42 passed.mvn verifyreactor: 53 passed, 5 live integration cleanly skipped.:8400: 5/5 passed.ruff check .clean.ruff format --check .clean.