Scope-Cut Proposal — testable core, optional extras

Status: partially implemented (2026-08-06). The core-crate side is done;
the Python-binding split is a planned phase with a documented blocker.

Implementation status (2026-08-06)

Done

1. justapi-core heavy features were already optional — db, ws,
   wasm, graphql, grpc, inference, mail, redis-rate-limit, tls,
   http3, orjson, opentelemetry are all feature-gated. default = ["opentelemetry"].
2. Default-feature test gate fixed — db_bridge.rs/edge_cases.rs
   integration tests now carry #![cfg(feature = ...)] guards;
   cargo test --workspace is green on default features (was broken).
3. CI split is the documented pattern — fast default-features gate +
   --all-features matrix (see PLAN.md gates).
4. Honest wheel story — the Python wheel is full-featured by design
   (verified: justapi-core features db, ws, wasm, graphql, grpc are what
   the Python API exposes — set_database, websocket, graphql,
   add_grpc_service).

Deferred (blocked, needs a focused session)

Python-binding lean feature. Making justapi-py build without
db/ws/wasm/graphql/grpc requires feature-guarding ~50+ symbols across
native/app.rs, websocket.rs, database.rs, test_client.rs, handlers.rs
plus the Python glue (app.py, __init__.py, .pyi stubs). Verified
experimentally: removing the core features breaks the build in 20+ places.
Payoff is build-time only (the product bundles everything by design), so it is
lower priority than the runtime correctness work (ADR-080, ADR-081). Tracked
here so it is not lost.

The original problem

justapi-py unconditionally enables justapi-core features
db, ws, wasm, graphql, grpc (plus inference/mail/redis-rate-limit
optionally). Consequences:

• The core test gate is coupled to every feature. cargo test --workspace
  compiles sqlx+postgres/mysql, wasmtime, async-graphql, tonic+prost, and the
  whole inference stack whether or not the user uses them. A clean-machine
  "does the framework work?" check is impossible.
• The wheel is heavy and untested in its default form. The default install
  carries wasmtime/grpc/graphql compile time and binary size even for a
  hello-world app.
• "Done" is not verifiable. PLAN.md lists 50+ phases complete, but the
  default build never exercises them in isolation — regressions hide behind the
  feature soup (the db_bridge/edge_cases integration tests already fail
  without --all-features).

The proposal: three tiers

Tier 1 — justapi-core (always compiled, always tested)

The transport + framework core. No feature-gated deps in the default path:

• tokio, hyper, hyper-util, http-body-util, matchit, serde_json, jsonschema
• middleware (CORS/JWT/rate-limit/security headers/compression), router,
  serialize, validate, metrics, health, server, testing, openapi, static_files
• Existing flags stay, but default = [] (drop opentelemetry from default;
  OTel becomes opt-in — it currently drags grpc-tonic into every build via
  opentelemetry-otlp).

Exit criterion: cargo test -p justapi-core (default features) is green in
under ~60s on a clean machine and exercises routing, middleware, serialization,
validation, static files, health, test client.

Tier 2 — justapi-py (the pip package)

• default = ["mail"] today → make default = []; map every Python feature to
  the corresponding core feature flag so users install exactly what they use:
  pip install justapi[db], justapi[wasm], justapi[grpc], justapi[graphql],
  justapi[inference], justapi[http3], justapi[otlp], justapi[all].
• Python glue that touches a disabled feature must degrade gracefully at import
  time (try/except around the native submodule), not hard-fail.

Exit criterion: pip install justapi in a fresh venv → justapi serve
hello-world works with no wasmtime/grpc/graphql installed; each extra
installs only its own transitive deps.

Tier 3 — optional feature flags to keep (already correct pattern)

Keep the existing per-feature gates and simply stop forcing them all on:

What moves where

1. justapi-py/Cargo.toml: drop features = ["db","ws","wasm","graphql","grpc"]
   from the justapi-core dependency; re-enable via [features] passthrough
   with dep: forwarding. Python extras in pyproject.toml mirror the
   feature names.
2. justapi-core/Cargo.toml: default = [] (OTel opt-in). Add a
   full convenience feature = ["tls","ws","db","mail","compression","brotli-compression","zstd-compression","wasm","graphql","grpc","http3","redis-rate-limit","opentelemetry"] for the benchmark harness and CI matrix.
3. Fix the integration tests (db_bridge, edge_cases) so they carry the
   right #![cfg(feature = ...)] guards and the default-feature gate is green
   alone; run --all-features only in the full matrix.
4. CI: two jobs — default-features (fast, the "does it work" gate) and
   all-features (the "everything still compiles" gate). BENCHMARKS records
   which feature set each number was measured with.

Honest tradeoffs

• Compile time for power users: justapi[all] users still pull everything —
  but that's their explicit choice, not the default tax.
• Python import behavior: currently from justapi import WebSocket works
  because ws is always on. After the cut, importing a feature's symbol without
  the extra installed must raise a clear ImportError with an install hint
  (pip install justapi[ws]), not a confusing AttributeError from a missing
  native submodule.
• This is a packaging/CI change, not a feature change. It changes when
  things compile and what the default is, not what exists. Risk is low; the
  payoff is a verifiable core.

Suggested order

1. justapi-core default-features-to-empty + full convenience flag + CI split
   (verify the fast gate).
2. justapi-py feature passthrough + pyproject.toml extras + import-hint
   degradation.
3. Fix the two integration-test guards; record a clean-machine default-feature
   run in BENCHMARKS.
4. Ship 2.0.8 with the default wheel being the lean, tested core.