Skip to content

Exercise declared dependency floors in CI #210

Closed

Description

@lesnik512

Every floor in [project.optional-dependencies] — litestar>=2.15,
prometheus-fastapi-instrumentator>=8.0.1, prometheus-client>=0.20,
opentelemetry-instrumentation-asgi>=0.46b0, and now fastmcp>=3 /
faststream>=0.6 (#175) — is a claim that nothing in CI checks. just install
runs uv lock --upgrade, so every job resolves the newest release of every
dependency; the lowest version each bootstrapper is documented as supporting is
never imported, let alone bootstrapped.

The floors added in #175 were established by hand, in throwaway venvs, against
the release list as it stood on that day. That verification does not survive the
next change to a bootstrapper: a new call into a framework API that landed after
the declared floor raises the real minimum silently, and the declaration decays
into a comment that used to be true.

Add a _checks.yml job that resolves lowest-direct (uv lock --resolution lowest-direct, or uv pip install --resolution lowest-direct per extra) and
runs the suite against it, so a floor that is too low fails here rather than in a
downstream service. Worth deciding when opening this up:

  • whether the job gates PRs or only runs in scheduled.yml, since a transitive
    dependency's own bad floor can break it for reasons unrelated to this repo;
  • whether it runs the whole suite once on an all-extras lowest-direct lock, or
    per-framework the way install-isolation already loops over extras.

Revisit trigger: a downstream report of a bootstrap failing on a version
inside a declared range, which is exactly the failure this job exists to catch.

Activity

  1. lesnik512 commented on Sep 12, 2026

    @lesnik512
    MemberAuthor

    I ran the two commands this issue proposes against a copy of the tree. Notes below; nothing changed in the repo.

    The premise holds, but it understates the problem by half

    The issue frames this as declared floors going unchecked. The larger fact is that most direct requirements declare no floor at all, and lowest-direct reads an absent floor as the first release ever published.

    Counting [project.optional-dependencies] plus core: 18 distinct direct runtime requirements, 6 of which carry a floor (litestar, prometheus-fastapi-instrumentator, prometheus-client, opentelemetry-instrumentation-asgi, faststream, fastmcp). The other 12 are bare: typing-extensions, orjson, sentry-sdk, pyroscope-io, structlog, fastapi, opentelemetry-api, -sdk, -instrumentation, -exporter-otlp-proto-grpc, -exporter-otlp-proto-http, -instrumentation-fastapi.

    So this is not a job that checks existing claims. It is a forcing function that requires ~12 new floors before it can go green. What --resolution lowest-direct resolves today:

    extra resolves to
    core only typing-extensions==3.6.2 (plus the typing PyPI backport)
    fastapi fastapi==0.1.0, starlette==0.47.0
    logging structlog==0.1.0
    sentry sentry-sdk==0.1.0
    otl opentelemetry-{api,sdk}==1.0.0, -instrumentation==0.19b0, protobuf==7.36.1
    pyroscope pyroscope-io==0.3.0
    litestar / fastmcp / faststream / *-metrics exactly the declared floors (2.15.0 / 3.0.0 / 0.6.0 / 0.20.0 / 8.0.1)

    The floored six behave exactly as this issue hopes. The unfloored twelve resolve to 2013.

    The sharpest case is that a bare install does not import:

    + typing-extensions==3.6.2
    ImportError: cannot import name 'GenericMeta' from 'typing'
      at lite_bootstrap/instruments/base.py:4
    

    typing_extensions.Self needs >=4.0; 4.0.0 imports clean. ADR-0007 documents that dependency as load-bearing and the floor it implies was never written down. That one is a real undeclared floor, not an artifact of the experiment.

    uv lock --resolution lowest-direct cannot work here at all

    The first command suggested above fails immediately:

    hint: `pytest` (v2.0.0) was included because `lite-bootstrap:dev` depends on `pytest`
    urllib.error.HTTPError: HTTP Error 403: SSL is required
    

    uv lock always resolves every [dependency-groups] entry and has no --no-dev / --no-default-groups (uv 0.12.5). pytest at lowest-direct is 2.0.0, whose sdist shells out to a 2011 setuptools bootstrap URL that now 403s. The dev and lint groups would each need floors too; only redis>=5.2.1 has one. The per-extra uv pip install --resolution lowest-direct form is the only viable one, which matches what #211 did by hand.

    All-extras would hide the failures the job exists to catch

    This settles the second open question. lowest-direct floors direct dependencies and takes transitives at highest, so a floor declared in one extra propagates through the shared stack:

    • litestar-otl declares opentelemetry-instrumentation-asgi>=0.46b0, which drags opentelemetry-api to 1.25.0.
    • fastapi-otl declares nothing, so it gets opentelemetry-api==1.0.0, -instrumentation-fastapi==0.19b0, -instrumentation-asgi==0.19b0.

    Same OpenTelemetryInstrument code, two effective floors 25 minor versions apart, decided by which extra the user installed. An all-extras run resolves the union and tests neither user's reality.

    Same effect on core: fastapi alone yields typing-extensions==3.6.2, fastapi-all yields 4.10.0 (pulled up by the instrumentator's pydantic). Whether the library imports at all currently depends on which extra happens to rescue it.

    Per-extra is blocked by conftest; per-framework is not

    tests/conftest.py imports sentry_sdk, opentelemetry.instrumentation.instrumentor and structlog.typing at module level, so any pytest run needs sentry + otl + logging present. Per-extra suite runs would require restructuring collection. Per-framework over the five -all extras (free-all, fastapi-all, litestar-all, faststream-all, fastmcp-all) works as-is, maps one-to-one onto the five bootstrappers, and preserves the fastapi/litestar OTel divergence above.

    The suite measures a stricter claim than the library's floor

    The tests reach into internals of their own: faststream._internal.logger.params_storage.ManualLoggerStorage, sentry_sdk.envelope.Envelope, structlog.typing, starlette.testclient. A job that runs the suite pushes floors up to where the test helpers work, which can exceed the library's true minimum and over-constrain downstream services. Worth deciding deliberately: accept test-driven floors as the declared ones (simple, slightly conservative), or keep a narrower import-and-bootstrap smoke as the floor oracle.

    The PR-gate objection, corrected

    The scheduled-only option is justified above by "a transitive dependency's own bad floor". Under lowest-direct transitives resolve highest, so the real instability is the opposite: a brand-new upstream release landing next to an old direct pin (fastapi==0.1.0 beside starlette==1.6.0, opentelemetry-sdk==1.0.0 beside protobuf==7.36.1). Combinations no user will ever have, changing daily.

    That is fixable rather than a reason to demote the job. uv pip compile --resolution lowest-direct works. Commit one resolved file per framework, install --frozen from it in the PR gate, and regenerate it in scheduled.yml so drift reports through the existing report-scheduled-failure.sh. The PR gate becomes hermetic, and the file changes only when a floor changes, which is exactly when a human should look.

    Mechanically, _checks.yml is shared by ci.yml and scheduled.yml with workflow_call: {} and no inputs, so "gate PRs or only scheduled" is not expressible by dropping a job into it. It needs a workflow_call input, or the scheduled-only half lives in scheduled.yml.

    Cheapest first step

    install-isolation already loops 27 extras, builds a venv each, and asserts import lite_bootstrap. Running that loop a second time with --resolution lowest-direct catches "the declared floor does not import" for every extra, with no conftest restructuring, no test-suite floors and no new lockfile. It fails today on core alone, which is the honest starting state.

    One adjacent gap

    import_checker.py is presence-only (find_spec). A too-old-but-present dependency passes every guard and fails at attribute access inside bootstrap(), never as InstrumentDependencyMissingWarning. There is no runtime version check anywhere, so the declared floor is the only defence. That is why the revisit trigger above, a downstream bug report, is the one signal this design cannot generate for itself.

    Suggested reshape

    Split in two: one issue to establish and declare floors for the 12 bare requirements (plus the dev and lint groups, which the lock form needs), one for the CI job that holds them. In that order, since the job cannot go green before the floors exist.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions