Skip to content

v0.11.0 — Phase 10: SDK, CLI and Documentation

Choose a tag to compare

@Abolfazlrwm Abolfazlrwm released this 23 Oct 14:30
· 58 commits to main since this release

v0.11.0 — Phase 10: SDK, CLI and Documentation

Added

flowforge-client — a dependency-free Python client, published as its own
distribution because the server package drags in Django and a client library must
not. It imports nothing from core or api; it talks HTTP.

  • No runtime dependencies. urllib.request is enough for JSON over HTTP, so
    installing it cannot change a resolution anywhere else. CI asserts the list
    stays empty.
  • Frozen dataclasses, so run.task_runs[0].state gets completion and a typo
    raises AttributeError.
  • Typed errors from the envelope. The API's error.code is stable, so the
    client parses it once and you except NotFoundError, ConflictError,
    ThrottledError (with retry_after).
  • trigger(..., idempotency_key=...) — a POST is not idempotent, so the
    client refuses to retry one without a key; with one, a retry replays.
  • wait(run_id, timeout=...) polls with a growing interval and raises
    TimeoutError naming the last state, because a caller that ignored a
    still-running run would proceed on unfinished work.
  • Retries are 429/5xx only, with exponential backoff, jitter and Retry-After.
    The transport refuses any scheme but http/https — urlopen accepts
    file:, and a base URL that could point at a local path is a
    credential-disclosure bug.

The flowforge CLI — one subcommand per client call, so the CLI cannot do
what the SDK cannot. Config from FLOWFORGE_URL/FLOWFORGE_TOKEN first, flags
second. Exit codes: 0 ok, 1 failed, 2 usage. trigger exits 1 when the run did
not succeed, which is what makes it usable as a CI step.

examples/ — four runnable programs: publish-and-run, watch-the-event-log,
requeue-failed (dry-run by default, because requeueing is a state change on live
work), and a CLI walkthrough that asserts an exit code at every step.

Documentation

  • docs/sdk/index.md — the guide, leading with the design decisions and stating
    what the SDK deliberately does not do.
  • docs/cli.md — configuration precedence, exit codes, one example per
    subcommand with real output.
  • docs/api/reference.md — every endpoint with its request and response body,
    the error envelope, both state machines, rate limits and health probes.
  • docs/api/overview.md — its endpoint table now lists the whole surface.

Verification

CI: https://github.com/Abolfazlrwm/flowforge/actions/runs/39968849829

  • 52 SDK tests, all without a server — a FakeTransport answers from a
    table, which makes retry, pagination, error mapping and polling testable.
  • New sdk job: own lock file, ruff, ruff format, mypy, pytest, an empty
    runtime-dependency assertion, and a wheel build that checks the console script
    is declared.
  • Server: 681 unit tests on PostgreSQL, 29 integration tests, ruff, mypy
    (73 files), mkdocs build --strict.

Known limitations

  • flowforge-client is not on PyPI — publishing is a release decision that
    has not been taken. Install with pip install ./sdk.
  • No async client; no client-side definition validation; no cancellation call
    (the API has no endpoint for it); no publish subcommand.