Skip to content

feat(net): add experimental HTTP and TLS capability stack - #282

Draft
HalfSweet wants to merge 7 commits into
pocket-stack:mainfrom
HalfSweet:feat/network-architecture
Draft

feat(net): add experimental HTTP and TLS capability stack#282
HalfSweet wants to merge 7 commits into
pocket-stack:mainfrom
HalfSweet:feat/network-architecture

Conversation

@HalfSweet

@HalfSweet HalfSweet commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • add format-3 network policy and Build Plan resolution, a generated private network ABI, and a compiler-hidden factory binding
  • add the staged PocketJS HTTP SDK plus strict URL/body/resource handling without exposing the native binding to applications
  • add ESP-IDF HTTP/1.1, HTTP Core, transport, and formal runtime components with strict framing, explicit body credit and lease ownership, redirects, bounded one-entry connection reuse, exact provider selection, and poison-safe shutdown
  • add TLS 1.2 verification, SNI, trusted-clock admission, Host-pinned CA support, bounded close-notify progress, distinct hostname-versus-certificate errors, and independent HTTP/TLS/DNS conformance fixtures
  • keep stock targets and the public compiler capability gate closed; only exact test-only plans can use the staged fetch path

Why

PocketJS needs a network capability whose authority, resource limits, native provider selection, and Guest/Host ownership are fixed before Guest evaluation. The implementation remains fail-closed while the remaining ESP-IDF allocation, DNS completeness, and product-admission gates are completed.

Repository footprint and review order

  • reduced this draft from 82,520 added lines in 259 files to 57,744 added lines in 222 files
  • rebased onto the current main and replaced 150 development-history commits with seven review commits: contracts, SDK, compiler boundary, HTTP Core, ESP runtime, conformance harness, and documentation
  • removed the superseded esp_http_client backend prototype and Guest spike rather than maintaining two native stacks
  • stopped committing three generated factory bundles, resolved plans, and metadata copies; ESP-IDF now regenerates them in the component build directory
  • consolidated three profile-specific artifact test files into one scenario suite and merged a previously unregistered network cleanup test into the canonical network suite
  • retained artifact source apps, manifests, generators, runners, and the public test CA because they are the reproducible input and hardware harness, not generated output

Impact

This PR adds the experimental substrate and conformance tooling. It does not advertise network.http.client or network.http.client.tls from a stock target, and it does not make the staged HTTP surface generally available.

Validation

  • bunx tsc --noEmit --pretty false and the repository contract drift guard
  • focused SDK/ABI tests for admission, private binding isolation, URL/body bounds, lease ownership, operation generations, and fail-closed Host metadata
  • one consolidated artifact suite covering deterministic plans and factories, exact provider selection, private test permits, representative plan mutation, runtime mount timing, and canonical IPv4 handling
  • independent peer coverage for HTTP framing, authoritative DNS, TLS version and certificate rejection, handshake interruption, soak, and the complete Phase 1B wire sequence
  • Clang -Wall -Wextra -Werror with ASan/UBSan for HTTP Core, ESP transport state, and ESP runtime contract/fake integration
  • Clang Static Analyzer for the HTTP parser/Core and runtime paths
  • ESP-IDF v6.0.2 (7101770dc6db) clean full-link builds for ESP32-S3 and ESP32-P4, with build-local artifact generation and embedding
  • AtomS3R and Tab5 ESP32-P4 rev1.3 each pass the exact formal TLS conformance artifact: 40 Guest operations, 44 HTTP wire requests over 25 TLS 1.2 connections, maximum six requests per reused connection, seven observed close-notify connections, 18 mandatory forced closes, 26 balanced leases, zero poison, and completed shutdown
  • both boards pass five isolated certificate-rejection profiles with exact fixture SHA-256 attestation: hostname mismatch maps to tls_hostname_mismatch; unknown CA, expired, not-yet-valid, and bad-signature certificates map to tls_certificate_invalid
  • both boards pass isolated delayed-handshake interruption profiles: a 2,000,000-us connect/TLS deadline maps to timed_out and a 500-ms AbortController delay maps to aborted while the peer holds the TLS 1.2 handshake for 10 seconds
  • every negative run has one controlled DNS answer, one SNI-bearing ClientHello, one failed TLS handshake, zero opened TLS connections or HTTP requests, cooperative Guest execution, balanced ownership, zero poison, and completed shutdown
  • the public ESP-TLS SSL-context accessor plus mbedtls_ssl_get_verify_result() recovers verification flags from the failed negotiation state; host tests cover captured/live flag precedence and generic X.509 fallback
  • after the interruption matrix, both boards were restored to the default conformance artifact and flashed; post-commit IDF v6.0.2 rebuilds are current with no app relink pending (AtomS3R 1,873,968 bytes, SHA-256 4ffb324d...c551b; Tab5 1,913,296 bytes, SHA-256 35d66e5b...ffb2f)

Remaining public-admission gates

  • complete DNS candidate-set evidence when stock lwIP does not expose response truncation
  • bounded lwIP, ESP-TLS, and Mbed TLS allocation envelopes
  • strictly bounded TLS native-step wall time
  • executable Host descriptor/provider/resource selection equality before Guest evaluation
  • production scheduler/lifecycle integration and broader fault, race, and long-duration hardware evidence
  • stock ESP target/registry/CLI integration, broader HTTP conformance, and the final public compiler gate

@doodlewind

Copy link
Copy Markdown
Collaborator

Please share your session via https://spool.new/ 😉

@HalfSweet
HalfSweet force-pushed the feat/network-architecture branch from e979da9 to 7c838a9 Compare August 16, 2026 08:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants