Skip to content

P4.md

Latest commit

 

History

History
86 lines (63 loc) · 15.5 KB

P4.md

File metadata and controls

86 lines (63 loc) · 15.5 KB
Raw

P4 granular work: HTTP and WebSocket profiles

English | 简体中文 | Main roadmap

All rows are ⏳ Planned. These leaves retain the five P4 parent commitments and the hard P3 prerequisite. They describe exact-version Rust# API profiles, not unchanged upstream crate source compatibility. New compat/, sample, profile, test and runtime subdirectories below are planned deliverables, not claims of existing implementation. Existing src/RustSharp.Runtime/, tools/RustSharp.Conformance/, eng/ and .github/workflows/ provide integration roots. Listed rsc test/rsc publish commands become executable only once the named workspaces, profiles and CLI support have been delivered.

Each contract leaf must freeze a nonempty versioned manifest: exact upstream/dependency versions, API signatures, feature combinations, wire-protocol rules, exclusions, fixture IDs, expected results, numeric limits and fixed denominator/hash. Protocol versions/extensions and crate versions must be explicitly decided there. Implementation leaves consume that inventory; scope expansion creates a new version and never removes or weakens existing cases. Local controlled endpoints replace public-service assumptions in required tests.

Each leaf owns named code and corresponding positive, negative, boundary and budget tests. Assign individual files before parallel work in shared roots. Evidence cells name future deliverables; no existing result is implied. A planned report artifacts/roadmap/<ID>.json records final source SHA, locked package hash, profile/manifest/version/hash, exact denominator/results, tools, platform/RID/runtime, commands, finite timeout/retry/item limits, PID/start/parent, failure reasons and owned-resource cleanup. Reports must be archived by CI with stable run links; all included cases run with zero failures/skips. A successful smoke sample alone cannot close an API/feature denominator.

A parent ID means every listed child has accepted evidence. A leaf can close after its own dependencies and evidence pass; it does not depend on its own phase gate. P4-GATE means the four gate rows at the end. P3-GATE remains mandatory before P4 closes, and P4-01 retains its original full P3 dependency. No gate claims the whole upstream crate ecosystem.

P4-01: Internal http/hyper/tower surface

ID Status Deliverable / ownership Depends on Done when Evidence
P4-01.01 ⏳ Planned compat/http-stack/profile-v1.json — Freeze exact versions, API/features and wire-protocol scope. P3-GATE Finite request/response/body/middleware inventory and HTTP/1.1 plus declared HTTP/2 cases have numeric header/body/stream budgets; excluded features reject explicitly. Profile validator, API inventory and protocol fixture IDs.
P4-01.02 ⏳ Planned compat/http-stack/http/ — Implement request/response, headers, URI and status values. P4-01.01 Frozen constructors/conversions round-trip; invalid headers/URIs/status and oversized metadata reject with stable errors; request/response ownership is preserved. API contract, encoding and metadata-boundary tests.
P4-01.03 ⏳ Planned compat/http-stack/body/ — Implement streaming bodies and bounded backpressure. P4-01.02 Partial chunks/EOF/trailers follow the manifest; slow producer/consumer, cancellation and oversized bodies cannot exceed buffer/queue budgets or leak streams. Body ordering, cancel races and peak-buffer reports.
P4-01.04 ⏳ Planned compat/http-stack/tower/ — Implement service readiness and middleware composition. P4-01.03 Declared layering, error propagation and readiness order match contract; overloaded/not-ready service and canceled requests respect finite concurrency/queue budgets. Middleware trace, overload and readiness tests.
P4-01.05 ⏳ Planned compat/http-stack/hyper/ — Implement HTTP/1.1 and the frozen HTTP/2 subset. P4-01.03 Valid loopback client/server wire fixtures interoperate; malformed framing, conflicting lengths, disconnects and stream/protocol limits fail as specified without cross-request data leakage. Protocol corpus with parser, framing and connection-limit negatives.
P4-01.06 ⏳ Planned compat/http-stack/, tools/RustSharp.Conformance/ — Integrate protocol, middleware and body lifecycle. P4-01.04, P4-01.05 All API/feature cases run; keep-alive/reuse, errors and cancellation release resources exactly as declared; no skipped or silently downgraded protocol cases. Planned: rsc test compat/http-stack/Cargo.toml; stack report.

P4-02: Exact-version reqwest client profile

ID Status Deliverable / ownership Depends on Done when Evidence
P4-02.01 ⏳ Planned compat/reqwest/profile-v1.json — Freeze client API/features, dependencies and policy defaults. P4-01, P3-06 Exact upstream version, builder/method/body/TLS/proxy/serialization APIs and redirect/retry/timeout policies have finite IDs and budgets; unsupported combinations are listed. Locked API/feature matrix and contract validator.
P4-02.02 ⏳ Planned compat/reqwest/client/ — Implement request builders, response values and connection reuse. P4-02.01 Declared methods/headers/body types and status handling work; invalid builder states and pool exhaustion fail predictably; dropped responses do not leak connections. Builder/response API cases and connection-pool resource checks.
P4-02.03 ⏳ Planned compat/reqwest/policy/ — Implement redirect, timeout, cancellation and retry policy. P4-02.02 Frozen policy handles relative/cross-origin redirects, deadlines and idempotency; cycles, forbidden credential forwarding and non-replayable retries fail within hop/attempt/time budgets. Local redirect/retry matrix and deadline/cancel traces.
P4-02.04 ⏳ Planned compat/reqwest/transport/ — Connect TLS and declared proxy/authentication modes. P4-02.02 Trusted direct/proxy requests succeed; certificate/hostname failure, proxy rejection and unsupported tunneling fail closed; credentials follow frozen origin/proxy boundaries. Local TLS/proxy fixture matrix and credential-isolation tests.
P4-02.05 ⏳ Planned compat/reqwest/body/ — Implement streaming and declared serialization adapters. P4-02.02 Upload/download and typed adapters use AOT-safe metadata; malformed/oversized data and canceled streams fail within budgets; backpressure bounds memory. Stream/serialization corpus, buffer peaks and AOT analysis.
P4-02.06 ⏳ Planned compat/reqwest/, tools/RustSharp.Conformance/ — Run and reconcile the client API/feature denominator. P4-02.03, P4-02.04, P4-02.05 Every frozen HTTP/TLS/redirect/stream/timeout/proxy/adapter member has passing runtime evidence; excluded feature requests reject explicitly; zero skips. Planned: rsc test compat/reqwest/Cargo.toml --features declared-profile; client report.

P4-03: Exact-version axum server profile

ID Status Deliverable / ownership Depends on Done when Evidence
P4-03.01 ⏳ Planned compat/axum/profile-v1.json — Freeze server API/features and extractor/handler contracts. P4-01, P3-04 Exact upstream version, routes/extractors/responses/state/middleware/errors and concurrency limits have finite case IDs; unsupported handler signatures reject. Locked server API inventory and manifest checks.
P4-03.02 ⏳ Planned compat/axum/routing/ — Implement route registration, matching and handler dispatch. P4-03.01 Declared static/parameter/nested routes and methods dispatch correctly; ambiguous registrations, malformed paths and missing/method-mismatched routes have specified outcomes. Route precedence, conflict and dispatch-budget tests.
P4-03.03 ⏳ Planned compat/axum/extract/, compat/axum/response/ — Implement declared extractors and response conversion. P4-03.02 Path/query/header/body/state extraction and response/status/body conversion match contract; malformed/oversized input and double body consumption reject predictably. Extractor/response API corpus and body-limit cases.
P4-03.04 ⏳ Planned compat/axum/middleware/, compat/axum/state/ — Implement shared state, middleware and handler error boundaries. P4-03.03 Layer order and state lifetimes remain correct under concurrency; handler errors/panics map at the declared boundary; canceled requests release owned state once. Layer/state traces, panic negatives and concurrency schedules.
P4-03.05 ⏳ Planned compat/axum/serve/ — Implement bounded serving and graceful shutdown. P4-03.04 New requests stop at shutdown, in-flight work drains or cancels by deadline, slow clients/overload obey limits; sockets/tasks are reclaimed after both success and failure. Shutdown, slow-client and overload resource reports.
P4-03.06 ⏳ Planned compat/axum/, tools/RustSharp.Conformance/ — Run the complete server API/feature integration matrix. P4-03.05 Frozen routing/extraction/response/state/middleware/error/shutdown/concurrency cases pass on generated programs; unsupported APIs reject without silent fallback. Planned: rsc test compat/axum/Cargo.toml --features declared-profile; server report.

P4-04: Client/server WebSocket profile

ID Status Deliverable / ownership Depends on Done when Evidence
P4-04.01 ⏳ Planned docs/profiles/websocket-v1.json — Freeze wire protocol, client/server APIs and extensions. P4-01, P3-06 Upgrade, text/binary, fragmentation, control/close/TLS/cancel rules and frame/message/queue/time budgets are enumerated; extension/subprotocol support is explicit. Protocol manifest and finite wire-fixture catalog.
P4-04.02 ⏳ Planned src/RustSharp.Runtime/WebSocket/Handshake/ — Implement client/server upgrade and subprotocol negotiation. P4-04.01 Valid negotiated upgrades succeed; invalid headers/version/key/accept and unsupported extensions reject; HTTP ownership transfers only after successful upgrade. Handshake positive/negative corpus and failed-upgrade cleanup.
P4-04.03 ⏳ Planned src/RustSharp.Runtime/WebSocket/Frames/ — Implement frame parsing, text/binary messages and fragmentation. P4-04.02 Declared masking, continuation and UTF-8 rules hold across fragmented/partial IO; invalid opcodes, lengths, masking and text fail within frame/message limits. Wire bytes, fragmented UTF-8 and size-limit fixtures.
P4-04.04 ⏳ Planned src/RustSharp.Runtime/WebSocket/Session/ — Implement ping/pong and closing state machine. P4-04.03 Control frames interleave correctly; local/remote/simultaneous close and valid codes complete once; malformed close, absent reply and post-close sends terminate under deadlines. Session-state traces and close/control negative corpus.
P4-04.05 ⏳ Planned src/RustSharp.Runtime/WebSocket/, tests/websocket/ — Integrate TLS, cancellation and bounded send/receive queues. P4-04.04 Secure client/server behavior follows TLS profile; slow peers and concurrent send/cancel honor backpressure; abrupt disconnect releases streams/tasks once. TLS, cancellation-race and queue-peak reports.
P4-04.06 ⏳ Planned tests/websocket/, tools/RustSharp.Conformance/ — Run the full client/server wire conformance denominator. P4-04.05 Every frozen role/protocol/TLS combination passes bounded local peer fixtures on both runtimes; invalid peer input has declared errors; zero skipped cases. Planned: rsc test tests/websocket/Cargo.toml; WebSocket report.

P4-05: Representative web applications and reports

ID Status Deliverable / ownership Depends on Done when Evidence
P4-05.01 ⏳ Planned samples/web-api/profile-v1.json — Freeze representative workloads and measurable budgets. P4-02, P4-03, P4-04 Finite HTTP API/client/WebSocket/TLS scenarios map to exact API/features; request/client/duration/payload/memory/startup budgets and pass thresholds are fixed before execution. Workload manifest, API coverage map and negative validator cases.
P4-05.02 ⏳ Planned samples/web-api/, samples/web-client/ — Build representative HTTP server/client applications. P4-05.01 Locked samples exercise routing, typed bodies, middleware, client policies and TLS; bad input, upstream timeout and graceful shutdown produce documented results. Source-to-generated-program functional and failure reports.
P4-05.03 ⏳ Planned samples/websocket/ — Build a representative secure bidirectional application. P4-05.01 Text/binary messages, heartbeat, fragmentation and shutdown exercise both roles; canceled/slow/malformed peers cannot exceed fixed queues or leak sessions. Application exchange traces and bounded adverse-peer report.
P4-05.04 ⏳ Planned eng/, .github/workflows/ — Publish/run the locked applications under finite load on both x64 platforms. P4-05.02, P4-05.03 Windows/Linux native AOT binaries and CoreCLR controls meet fixed functional/load/cancel budgets; zero AOT warnings, hung requests or owned-process/resource leaks. Planned: rsc publish samples/web-api/Cargo.toml --runtime linux-x64 --locked; matching win-x64 and other sample runs.
P4-05.05 ⏳ Planned docs/compatibility/web-v1.md, docs/compatibility/web-v1_zh.md — Publish exact API/feature coverage and reproducible application evidence. P4-05.04 Every claim maps to locked versions, case IDs, RID/runtime and final SHA; exclusions/known gaps are bilingual; stale or missing report cells fail reconciliation. Versioned compatibility matrix, artifact hashes and CI provenance.

P4-GATE: Phase exit

ID Status Deliverable / ownership Depends on Done when Evidence
P4-GATE.01 ⏳ Planned tools/RustSharp.Conformance/, docs/profiles/p4-exit-v1.json — Freeze the full web profile/app exit denominator. P3-GATE, P4-01, P4-02, P4-03, P4-04, P4-05 Reconcile every frozen API/feature/wire/workload case and budget; reject missing/duplicate IDs, changed denominators and absent P3 evidence; no unspecified HTTP/2 or extension claims. Exit validator mutation tests and evidence coverage index.
P4-GATE.02 ⏳ Planned .github/workflows/, eng/ — Run all web contracts and applications on native Windows x64. P4-GATE.01 Release/ILVerify/CoreCLR/Native AOT pass the fixed API and representative-app denominators with zero warnings/errors/failures/skips; timeout/cancel cleanup is verified. Windows run URL/SHA, published binary hashes and reports.
P4-GATE.03 ⏳ Planned .github/workflows/, eng/ — Run all web contracts and applications on native Linux x64. P4-GATE.01 The same fixed API and representative-app denominators pass Release/ILVerify/CoreCLR/Native AOT with zero warnings/errors/failures/skips; native applications actually serve requests. Linux run URL/SHA, published binary hashes and reports.
P4-GATE.04 ⏳ Planned docs/roadmap/P4.md, docs/roadmap/P4_zh.md, ROADMAP.md, ROADMAP_zh.md — Close P4 only after final evidence and scope reconciliation. P4-GATE.02, P4-GATE.03 All required cells share the final SHA and locked manifests, deterministic package outputs and owned-resource cleanup pass, bilingual claims match published profiles; stale/missing evidence fails closed. Final index with tool/platform/command/budget/PID/cleanup and stable CI links.