# API Stability Inventory
This document classifies every exported Rust and Python item by stability tier: **stable**, **experimental**, or **internal**. It is the authoritative reference for the release contract.
See [release-contract.md](release-contract.md) for the overall product surface and behavioral guarantees.
## Stability Tiers
| **stable** | Intentional public API. Patch releases must not break stable APIs. While pre-1.0, a minor release may break stable APIs only with explicit release notes and migration guidance. Semantic behavior identified in the release contract is covered by conformance tests. Unspecified formatting, debug output, log text, and internal implementation details are not stable unless explicitly documented. |
| **experimental** | May change in any non-patch release. Consumers should pin versions. Functionality is tested but the interface is not frozen. Experimental APIs may be omitted from language parity. |
| **internal** | Unavailable or unsupported for downstream use. No compatibility guarantee. Internal Python names are not exported through `__all__`. Internal Rust features do not become accidental default features. May be removed without notice. |
## Stability Rules
### Enum variant exhaustiveness
Stable enum variants are exhaustive unless documented otherwise. Adding a new variant to a stable enum is a breaking change.
### Thread safety (Send/Sync)
All stable canonical request types (`Method`, `HttpVersion`, `HeaderBlock`, `HeaderName`, `HeaderValue`, `HeaderField`, `RequestTarget`, `RequestHead`, `ConnectionInfo`, `Scheme`, `TlsInfo`, `StatusCode`, `ReadOnlyMethod`) implement `Send + Sync`. This means they can be safely shared between threads and sent across thread boundaries. This is a compile-time guarantee enforced by `public_api_consumers::canonical_types_are_send_and_sync`.
Error types (`MethodError`, `HttpVersionError`, `HeaderError`, `DuplicateHeaderError`, `RequestTargetError`, `RequestHeadError`, `ResponseConstructionError`, `RequestValidationError`) implement `Send` but not necessarily `Sync`, as they may contain `String` payloads.
`ResponseBody` and `Response` implement `Send`; file-backed bodies carry an
already-opened file capability rather than a path to reopen.
Python wrapper types (`#[pyclass(frozen)]`) are frozen/immutable but are not `Send`/`Sync` in the Rust sense — Python GIL constraints apply.
### Exception classes, fields, and messages
Python exception classes and their field names are stable. Exception message strings are not stable and may change between releases.
### Header ordering and duplicate preservation
Rust `HeaderMapPlan` and canonical Python `HeaderBlock` preserve insertion order and duplicate headers. This behavior is stable. Legacy Python response dictionaries are not part of the current compatibility façade.
### Denial/error taxonomy variants
`PathRejection`, `RequestValidationError`, and `ResourceDeniedReason` variants are stable. Adding a new variant is a breaking change.
### Serialization and repr output
`Debug` output, `Display` formatting, and Python `repr()` output are not stable unless explicitly documented as a contract.
### Deprecation
Deprecated stable items must remain functional for at least one minor release after deprecation is announced. Removal requires explicit release notes and migration guidance.
The canonical primitive types and older planning types listed below remain
functional.
## Rust API — `eggserve-core`
### Crate Root Modules
| `config` | pub | stable | `ServeConfig`, `StartupSummary`, `ServeState` |
| `limits` | pub | stable | `Limits` resource-limit configuration |
| `policy` | pub | stable | `StaticPolicy`, policy enums |
| `server` | pub | experimental | `Server`, `Service` trait, `StaticService`, lifecycle state machine, connection tracking |
| `server/lifecycle` | pub | experimental | `LifecycleState` — lifecycle state machine |
| `primitives` | pub | stable | Public facade for embedding consumers |
| `error` | pub(crate) | internal | Not externally visible |
| `fs` | pub(crate) | internal | Not externally visible |
| `mime` | pub(crate) | internal | Not externally visible |
| `path` | pub(crate) | internal | Not externally visible |
| `response` | pub(crate) | internal | Not externally visible |
| `ops` | pub | experimental | Structured logging, event model, counters |
### Experimental (eggserve-core::server)
- `LifecycleState` — lifecycle state enum
- `Server` — runtime server
- `ServerBuilder` — server builder
- `ServerHandle` — control handle
- `ShutdownResult` — shutdown outcome
- `Service` trait — custom service abstraction
- `service_fn` — closure-based service
- `StaticService` / `StaticServiceBuilder` — static file service
### Request body primitives (experimental)
| `RequestBodyPolicy` | Experimental | Body acceptance policy (Reject/Buffer/Stream) |
| `RequestBody` | Experimental | One-shot, bounded request body |
| `RequestBody::from_incoming()` | Internal | `pub(crate)` — not public API |
| `RequestBody::consumed_flag()` | Internal | `pub(crate)` — not public API |
| `RequestBody::was_fully_consumed()` | Internal | `pub(crate)` — not public API |
| `BodyState` | Experimental | Body consumption state machine |
| `RequestBodyError` | Experimental | Typed body error taxonomy |
| `Request` | Experimental | Canonical request envelope |
| `Service::call(Request)` | Experimental | Updated to accept Request envelope |
| `RuntimeConfig::max_request_body_bytes` | Experimental | Hard body size ceiling |
| `Service::request_body_policy(&RequestHead)` | Experimental | Service-declared body policy, bounded by the runtime ceiling |
| `IncompleteBodyPolicy` | Experimental | Public marker for the close-on-incomplete-body behavior; the runtime does not expose a configuration field |
### `server` Module
**All server module items are experimental.** API is subject to change without notice.
The `server` module remains experimental for the initial release. Plan 129
qualified clean external static and custom-service consumers over TCP, and
Plan 133 verified the packaged crate graph, but the runtime API and
`RuntimeConfig` field set may still evolve before 1.0. The Python compatibility
facade uses this runtime through the native bridge; its public surface is
documented separately in `docs/python-api.md`.
| `Server` | experimental | Main entry point; `Server::builder()` returns `ServerBuilder` |
| `ServerBuilder` | experimental | Configured builder; `.runtime()`, `.serve_config()`, `.static_service()`, `.start()`, `.bind()`, `.from_listener()` |
| `ServerHandle` | experimental | Control handle: `local_addr()`, `shutdown()`, `wait()`, `ready()`, `force_shutdown()`, `state()` |
| `RuntimeConfig` | experimental | Transport-level config: bind, limits, timeouts, body ceiling, optional TLS |
| `RuntimeConfigBuilder` | experimental | Builder for RuntimeConfig |
| `Service` trait | experimental | `call(Request) -> Result<Response, ServiceError>` (updated from `RequestHead`) |
| `service_fn` | experimental | Create a Service from a closure |
| `StaticService` | experimental | Hardened static file service |
| `StaticServiceBuilder` | experimental | Builder for StaticService |
| `ServiceError` | experimental | Per-request errors: Internal, Rejected, Panic, Timeout |
| `ServerError` | experimental | Startup/lifecycle errors: Bind, Config, AlreadyStarted, Accept, ShutdownTimeout, Startup, Terminal |
| `LifecycleState` | experimental | Lifecycle state machine: Created, Starting, Running, Draining, Stopped, Failed |
| `ShutdownResult` | experimental | Returned by shutdown operations, carries final LifecycleState |
### `config` Module
| `ServeConfig` | stable | All fields public: `bind`, `root`, `limits`, `static_policy` |
| `ServeConfig::default()` | stable | Binds to `127.0.0.1:8000`, serves `.` |
| `StartupSummary` | stable | Read-only summary after startup |
| `ServeState` | stable | Pinned static-root state; it does not own transport admission |
### `limits` Module
| `Limits` | stable | `max_connections`, `max_file_streams`, `header_read_timeout`, `connection_total_timeout`, `graceful_shutdown_timeout` are pub; `max_request_body_bytes` is pub(crate) |
| `Limits::default()` | stable | Safe defaults |
### `policy` Module
| `DirectoryListingPolicy` | stable | Enum: `Disabled`, `Enabled` |
| `SymlinkPolicy` | stable | Enum: `Denied`, `Follow` |
| `DotfilePolicy` | stable | Enum: `Denied`, `Serve` |
| `StaticPolicy` | stable | All fields public |
| `PolicyMode` | internal | pub(crate) |
### `primitives` Module — Path Types
| `ConfinedPath` | stable | Parsed request target |
| `PathDotfilePolicy` | stable | Alias for `path::DotfilePolicy` |
| `PathPolicy` | stable | Parse-time dotfile/backslash policy |
| `PathRejection` | stable | 16-variant rejection taxonomy |
### `primitives` Module — Policy Types (re-exported)
| `DirectoryListingPolicy` | stable | Re-export from `policy` |
| `DotfilePolicy` | stable | Re-export from `policy` |
| `StaticPolicy` | stable | Re-export from `policy` |
| `SymlinkPolicy` | stable | Re-export from `policy` |
### `primitives` Module — Secure Root
| `SecureRoot` | stable | Primary entry point for filesystem resolution |
| `ResolvedResource` | stable | Capability object — file, directory, not-found, denied |
| `ResolvedFile` | stable | File handle under policy. No public constructor |
| `ResolvedDirectory` | stable | Directory listing and child resolution |
| `ResourceDeniedReason` | stable | SymlinkDenied, DotfileDenied, RootEscapeDenied, PolicyDenied |
| `resolve_and_plan()` | stable | Combined resolve + plan convenience function |
| `ResolveAndPlanError` | stable | Error taxonomy for resolve_and_plan |
### `primitives` Module — HTTP Validation
| `ReadOnlyMethod` | stable | GET, HEAD only (legacy, prefer `Method`) |
| `RequestValidationError` | stable | 6-variant HTTP validation error |
| `validate_method()` | stable | Method string → ReadOnlyMethod (legacy) |
| `validate_request_body()` | stable | Body metadata validation |
| `validate_request_target()` | stable | Target string validation (legacy) |
### `primitives` Module — Canonical HTTP Request Types
**All canonical request types are stable** and covered by the conformance corpus.
| `Method` | stable | Validated HTTP method; standard + extension support |
| `MethodError` | stable | Empty, InvalidToken |
| `HttpVersion` | stable | HTTP/1.0, HTTP/1.1 |
| `HttpVersionError` | stable | Unsupported version |
| `HeaderBlock` | stable | Duplicate-preserving ordered header collection |
| `HeaderName` | stable | Validated header name (token) |
| `HeaderValue` | stable | Validated header value (no CR/LF/NUL) |
| `HeaderError` | stable | InvalidName, InvalidValue, NameTooLong |
| `DuplicateHeaderError` | stable | Returned by get_unique() on duplicates |
| `HeaderField` | stable | `pub name: HeaderName`, `pub value: HeaderValue` |
| `RequestTarget` | stable | Validated origin-form target (path + query) |
| `RequestTargetError` | stable | 6-variant target validation error |
| `RequestHead` | stable | Canonical request head: method, target, version, headers |
| `RequestHeadError` | stable | Conversion error from Hyper |
| `ConnectionInfo` | stable | Transport metadata: addrs, scheme, TLS |
| `Scheme` | stable | Http, Https |
| `TlsInfo` | stable | Protocol version, server name |
### `primitives` Module — Response Planning
| `plan_file_response()` | stable | Full response plan for a file |
| `evaluate_conditional_headers()` | stable | If-None-Match / If-Modified-Since |
| `evaluate_if_none_match()` | stable | ETag comparison |
| `evaluate_range_header()` | stable | Range parsing |
| `evaluate_if_range()` | stable | If-Range evaluation |
| `generate_etag()` | stable | ETag from metadata |
| `plan_directory_listing()` | stable | Directory listing plan |
### `primitives` Module — Response Types
| `ResponseStatus` | stable | Newtype u16 with associated constants |
| `ResponseHeader` | stable | `pub name: String`, `pub value: String` |
| `HeaderMapPlan` | stable | Ordered Vec of ResponseHeader; preserves duplicates |
| `FileRange` | stable | `pub start: u64`, `pub end_inclusive: u64` |
| `BodyPlan` | stable | Enum: Empty, FullBytes, FileFull, FileRange |
| `StaticResponsePlan` | stable | Status + headers + body plan |
| `ConditionalRequestOutcome` | stable | NotModified, FullResponse, Malformed |
| `RangeRequestOutcome` | stable | Satisfiable, NotSatisfiable, MalformedOrUnsupported, MultipleRanges |
### `primitives` Module — Canonical Response Types
**All canonical response types are stable** and covered by the conformance corpus.
| `StatusCode` | stable | Validated HTTP status code (100–599, three-digit only) |
| `ResponseHead` | stable | Status + `HeaderBlock`; transport-independent response metadata |
| `ResponseBody` | stable | Body representation: Empty, Bytes, File, EmptyWithLength |
| `Response` | stable | Complete response: head + body; one-shot consumption |
| `ResponseBuilder` | stable | Validated builder for Response |
| `NormalizeRequest` | stable | Context for response normalization (is_head flag) |
| `ResponseConstructionError` | stable | InvalidStatus, InvalidHeader, ForbiddenFramingHeader, BodyAlreadyConsumed, ContentLengthMismatch |
| `normalize_response()` | stable | Applies HEAD suppression, body-forbidden enforcement, hop-by-hop stripping, content-length computation |
| `normalize_metadata()` | stable | Shared metadata normalization: Transfer-Encoding stripping, Content-Length computation |
| `to_hyper_response()` | stable | Converts canonical Response to Hyper Response |
### `primitives` Module — Body Types
| `BodySource` | stable | Owned body: Empty, Bytes, FileFull, FileRange |
| `BodyKind` | stable | Discriminant for BodySource |
| `BodySourceError` | stable | InvalidRange, AlreadyConsumed |
## Python API — current contract
The historical Python stability tables are retained below only for migration
context. The supported public façade is intentionally small:
| `eggserve.server` | `HTTPServer`, `ThreadingHTTPServer`, `HTTPSServer`, `ThreadingHTTPSServer`, `BaseHTTPRequestHandler`, `SimpleHTTPRequestHandler` | experimental |
| `eggserve` | the six server classes above, `serve_directory`, `__version__` | experimental/stable as individually documented |
| `eggserve.lowlevel` | advanced Rust-backed primitives | experimental |
| `eggserve.subprocess` | `ServeConfig`, `ServerProcess`, `StaticPolicy`, `serve_directory` | experimental |
<details>
<summary>Historical Python API tables (superseded; retained only for migration history)</summary>
### `eggserve.__init__` — Always Available
| `__version__` | stable | Version string |
| `ServeConfig` | stable | Server configuration dataclass |
| `ServerProcess` | stable | Subprocess lifecycle manager |
| `serve_directory()` | stable | Blocking convenience function |
| `ResponsePlan` | stable | Namedtuple for response plan |
| `NATIVE_AVAILABLE` | stable | Whether native module loaded |
### `eggserve.server` — `__all__`
| `StaticPolicy` | stable | Policy dataclass (directory_listing, follow_symlinks, allow_dotfiles) |
| `ServeConfig` | stable | Config dataclass |
| `ServerProcess` | stable | Subprocess lifecycle |
| `serve_directory()` | stable | Blocking server |
### `eggserve._native` — Primitives (when NATIVE_AVAILABLE)
| `EggserveError` | stable | Base exception |
| `PathPolicyError` | stable | Child of EggserveError |
| `RequestTargetError` | stable | Child of EggserveError |
| `RequestValidationError` | stable | Child of EggserveError |
| `SecureRootError` | stable | Child of EggserveError |
| `BodySourceError` | stable | Child of EggserveError |
| `LifecycleError` | stable | Raised on lifecycle violations (double start, stop before start) |
| `ResponseConstructionError` | stable | Raised when handler returns an invalid Response object |
| `MethodError` | stable | Invalid HTTP method |
| `HttpVersionError` | stable | Unsupported HTTP version |
| `HeaderError` | stable | Invalid header name or value |
| `DuplicateHeaderError` | stable | Duplicate header on unique access |
| `PathPolicy` | stable | Frozen, mirrors Rust PathPolicy |
| `StaticPolicy` | stable | Frozen, mirrors Rust StaticPolicy |
| `RequestTarget` | stable | Frozen, mirrors ConfinedPath |
| `SecureRoot` | stable | Resolution entry point |
| `ResolvedResource` | stable | Capability object |
| `ResolvedFile` | stable | File metadata + plan_response/body_for_plan |
| `ResolvedDirectory` | stable | list() + resolve_child() |
| `BodySource` | stable | Body read access |
| `validate_method()` | stable | Method validation |
| `validate_request_body()` | stable | Body validation |
| `validate_request_target()` | stable | Target validation |
| `generate_etag()` | stable | ETag generation |
| `parse_method()` | stable | Create validated Method |
| `parse_http_version()` | stable | Create validated HttpVersion |
| `Method` | stable | Canonical HTTP method |
| `HttpVersion` | stable | Canonical HTTP version |
| `HeaderBlock` | stable | Duplicate-preserving headers |
| `ConnectionInfo` | stable | Transport metadata |
| `CanonicalRequest` | stable | Canonical request head |
### `eggserve._native` — Server Types (when NATIVE_AVAILABLE)
| `Request` | stable | Frozen request object |
| `Response` | stable | Frozen response builder |
| `StaticResponder` | stable | Static file responder |
| `StaticPolicyWrapper` | stable | Frozen policy wrapper |
| `ServerSecureRoot` | stable | Frozen secure root |
| `ServerBodySource` | stable | Body read + to_response |
| `ServerRequestError` | stable | Raised as ValueError |
| `Server` | stable | Rust-owned HTTP server |
### `eggserve._native` — Request Body Types (when NATIVE_AVAILABLE)
**All request body types are experimental.** The interface may change in any release.
| `RequestBody` | experimental | One-shot, bounded request body; `read()`, `iter_chunks()` |
| `BodyChunkIterator` | experimental | Synchronous iterator over body chunks |
| `RequestBodyError` | experimental | Base body error (child of `EggserveError`) |
| `RequestBodyRejectedError` | experimental | Body rejected by policy (child of `RequestBodyError`) |
| `RequestBodyTooLargeError` | experimental | Body exceeds byte limit (child of `RequestBodyError`) |
| `RequestBodyTimeoutError` | experimental | Body read timed out (child of `RequestBodyError`) |
| `RequestBodyDisconnectedError` | experimental | Client disconnected (child of `RequestBodyError`) |
| `RequestBodyIncompleteError` | experimental | Body incomplete (child of `RequestBodyError`) |
| `RequestBodyConsumedError` | experimental | Body already consumed (child of `RequestBodyError`) |
| `RequestBodyCancelledError` | experimental | Body consumption cancelled (child of `RequestBodyError`) |
### `eggserve.__init__` — Body Type Re-exports
| `RequestBody` | experimental | Re-exported from `_native` |
| `BodyChunkIterator` | experimental | Re-exported from `_native` |
| `RequestBodyError` | experimental | Re-exported from `_native` |
| `RequestBodyRejectedError` | experimental | Re-exported from `_native` |
| `RequestBodyTooLargeError` | experimental | Re-exported from `_native` |
| `RequestBodyTimeoutError` | experimental | Re-exported from `_native` |
| `RequestBodyDisconnectedError` | experimental | Re-exported from `_native` |
| `RequestBodyIncompleteError` | experimental | Re-exported from `_native` |
| `RequestBodyConsumedError` | experimental | Re-exported from `_native` |
| `RequestBodyCancelledError` | experimental | Re-exported from `_native` |
### Internal Names (not in `__all__`)
| `main()` | `_bin.py` | internal |
| `_parse_bind()` | `server.py` | internal |
| `_config_to_argv()` | `server.py` | internal |
| `_VALID_LOG_FORMATS` | `server.py` | internal |
</details>
## Internal Bridge APIs
The `python-bindings-internal` feature gate enables:
| `ResolvedFile::into_std_file()` | `python-bindings-internal` | internal |
| `ResolvedFile::into_parts()` | `python-bindings-internal` | internal |
| `ResolvedFile::from_parts()` | `python-bindings-internal` | internal |
These methods:
- Are disabled by default
- Are not documented as a user feature
- Are used only by the Python crate
- Do not appear in default Rust docs or package examples
- Are unavailable under the `default` feature build
## Production Profile API Classification
Every production claim must name a profile. The production profiles are documented in README.md and validated by contract consistency tests.
### Scope boundary
- eggserve is a hardened, read-only HTTP/1.1 static file server and a low-level primitive library.
- Downstream clients, ASGI/WSGI adapters, and application servers may be built outside the repository.
- Those downstream projects are not release deliverables or supported application-serving modes of eggserve.
- No public API promises application-server cancellation semantics beyond documented generic server behavior.
- No ASGI/WSGI vocabulary enters public types. No routing or middleware abstractions are added.
- Hyper, Tokio channel, PyO3, and platform FFI implementation types remain absent from stable public signatures.
### API tier summary
| Path confinement/primitives | stable | SecureRoot, ConfinedPath, StaticPolicy, PathPolicy, etc. |
| Canonical HTTP value types | stable | Method, HttpVersion, HeaderBlock, RequestTarget, StatusCode, Response, etc. |
| Response planning | stable | plan_file_response, evaluate_conditional_headers, generate_etag, etc. |
| Static server config | stable | ServeConfig, Limits, StaticPolicy |
| Static server lifecycle | experimental | Server, ServerBuilder, ServerHandle, Service trait, LifecycleState |
| Request body primitives | experimental | RequestBody, RequestBodyPolicy, RequestBodyError |
| Internal transport | internal | fs, path, response, mime, error modules |
## Key Design Decisions
### Header Representation
- **Rust**: `HeaderMapPlan` is an ordered `Vec<ResponseHeader>`. Duplicates are preserved.
- **Python**: canonical `HeaderBlock` is an ordered list of validated fields and preserves duplicates.
- **Decision**: Rust and the canonical Python low-level surface preserve duplicates. Legacy flat-dictionary response APIs are historical and are not part of the current façade.
### Response Contract
- Python handlers must return a `Response` object (or duck-typed equivalent).
- Invalid returns produce 500 without leaking tracebacks.
- HEAD is not special-cased in the Python handler path.
- Informational statuses and 204/205/304 are body-forbidden and are normalized
to empty responses.
- Hop-by-hop headers are rejected at the Python boundary and stripped from
canonical metadata where the runtime owns them.
- File-backed responses retain their Rust-owned capability and stream without an eager Python-memory copy.