feat: HTTP/2 by default for NetScript services (feasibility + rollout)

[rickylabs]

Summary

Investigate and roll out HTTP/2 by default for NetScript services. HTTP/2 is largely "free" at the protocol layer — Deno's runtime already speaks it — but making it the default is gated almost entirely by TLS provisioning in local dev, because browsers only negotiate HTTP/2 over TLS (ALPN). This issue captures the feasibility verdict, the concrete requirements, a phased rollout, and the open questions.

Motivation

• Streams / SSE multiplexing. Under HTTP/1.1 a browser opens at most ~6 concurrent connections per origin; long-lived SSE/streams eat those slots fast (the caveat documented for devtools: enable Aspire browser-logs integration by default (capture island/browser console in the dashboard) #218/feat(aspire): enable browser-logs devtools integration by default + streams HTTP/2 caveat (#218) #231). HTTP/2 multiplexes all requests over a single connection, removing that ceiling — this is the strongest concrete reason to want h2 by default.
• Header compression + single-connection lower per-request overhead for the many small oRPC calls a Fresh island makes.
• Alignment with the .NET Aspire posture — Aspire/Kestrel default to HTTPS+h2 in dev; NetScript services currently serve plain HTTP/1.1, so the stack is inconsistent.

Current state (grounded)

• packages/service/src/builder/service-listener.ts starts a plain Deno.serve({ port, signal, onListen }) — no cert/key, and the startup banner hardcodes http://${hostname}:${port}. The file docstring already anticipates this: "Kept separate from the builder class so the listener concern can evolve (e.g. TLS, clustering)…".
• The SDK client (packages/sdk/src/client/http-client-link.ts / service-client.ts) and the tutorial's OpenAPILink/RPCLink are built on fetch. Deno's fetch already negotiates HTTP/2 automatically over TLS — no client code change is needed for the happy path, only trust of the dev cert.
• So the runtime pieces are present; the gap is TLS wiring + dev-cert trust + Aspire scheme, not a new HTTP/2 implementation.

Feasibility verdict

Feasible with no new dependency. Deno.serve serves HTTP/2 automatically when given a TLS cert/key and the client negotiates h2 via ALPN (Deno.serve({ cert, key, ... })). The work is plumbing and dev-ergonomics, not protocol implementation.

Key constraint: browsers do not support h2c (cleartext HTTP/2). So "h2 by default" for a browser-facing service necessarily means "TLS by default in dev." That TLS-in-dev requirement is the real cost of this issue.

Requirements

1. Dev TLS certificate + local trust (the hard part). Browsers reject untrusted certs, so the generated dev experience needs a trusted localhost cert. Options to evaluate:
   • Lean on Aspire dev-certs (dotnet dev-certs https --trust) — Aspire already provisions/trusts a localhost cert for its own HTTPS endpoints; reuse it for NetScript service endpoints.
   • mkcert-style locally-trusted CA (extra install step).
   • Self-signed + explicit trust env for non-browser clients only (DENO_CERT / NODE_EXTRA_CA_CERTS) — insufficient for browsers.
   • Cross-platform trust friction (Windows cert store vs. macOS keychain vs. linux) is the dominant UX risk.
2. Service listener TLS support. Extend ServeOptions with an optional tls: { cert, key } (or certFile/keyFile), branch startServiceListener to pass them to Deno.serve, and flip the onListen banner to https:// when TLS is active. Keep plain HTTP as a fallback (opt-out / no-cert path).
3. Aspire AppHost scheme. Generated AppHost endpoints, service-discovery URLs, and health-check probes must flip http→https when services serve TLS. (Note: the Aspire dashboard URL was already corrected to https in the docs; this is about the service endpoints.)
4. Client / SDK trust. fetch gets h2 for free over TLS, but Deno must trust the dev cert (DENO_CERT, --cert, or the OS trust store via Aspire dev-certs). Verify OpenAPILink/RPCLink and generated typed clients work end-to-end over h2.
5. Fresh / Vite dev server. Separate listener from the service. Vite's dev server + HMR over HTTPS/h2 has its own config (server.https); confirm HMR still works. Decide whether the web layer also goes TLS-by-default or stays HTTP in dev while only backend services go h2.
6. Production. Essentially free: TLS typically terminates at the ingress/proxy in an Aspire-published deployment, which already speaks h2 to browsers. Internal service-to-service h2 is optional and can be a later phase.

Proposed phased rollout

• Phase 0 — Spike (no default change). Prove Deno.serve({ cert, key }) serves h2 end-to-end: curl --http2 -k, Chrome DevTools Protocol column = h2, and a Deno fetch client. Confirm the ALPN path and measure the SSE-slot win.
• Phase 1 — Opt-in TLS. Add ServeOptions.tls + banner flip; document how to run a service over h2. No behavior change by default.
• Phase 2 — Aspire dev-cert provisioning. Wire the generated AppHost to provision/trust a dev cert and pass it to service listeners; flip endpoint scheme to https; make TLS+h2 the default in the scaffolded dev experience.
• Phase 3 — Docs + tutorial reconcile. Update service/streams/aspire docs to the h2 default; tie in the devtools: enable Aspire browser-logs integration by default (capture island/browser console in the dashboard) #218/feat(aspire): enable browser-logs devtools integration by default + streams HTTP/2 caveat (#218) #231 streams caveat resolution (h2 removes the ~6-connection limit). Coordinate with docs umbrella epic: docs — march to 0.0.1-stable (coverage & accuracy) #232.

Risks / open questions

• Dev-cert trust friction across Windows/macOS/Linux — can we fully delegate to Aspire dev-certs so there's zero extra user step? (Biggest adoption risk.)
• Vite/Fresh HMR over h2/TLS — does HMR survive, and do we want the web layer on TLS too or only backend services?
• Deno fetch → self-signed trust story for non-browser clients (CI, tests, server-to-server): DENO_CERT vs. OS store.
• Interaction with aspire start --isolated (aspire: --isolated should randomize profile-pinned dashboard/OTLP/resource-service ports for parallel isolated apphosts #215/fix(aspire): randomize dashboard/OTLP/resource-service ports under --isolated (#215) #222) randomized ports — cert SANs / wildcard localhost.
• Scope of the default: browser-facing edge only, or service-to-service too (mTLS)?
• Any impact on the e2e-cli / scaffold.runtime gates (they currently assert http:// endpoints).

Non-goals

• HTTP/3 / QUIC (separate, larger effort).
• Rewriting the client transport — fetch already handles h2.

---

Filed out of the alpha.18 docs-conformance work (the streams HTTP/1.1 ~6-connection caveat is the motivating case). Tracked standalone rather than folded into docs. Related: #218, #231, #215, docs umbrella #232.

[rickylabs]

Findings: Aspire now ships the dev-cert trust automation — the biggest risk largely dissolves

Followed up on the "dev-cert trust friction across Windows/macOS/Linux — can we delegate to Aspire?" open question by reviewing recent Aspire releases. Yes — and better than expected. Aspire added a first-class certificate-configuration surface (aspire.dev/app-host/certificate-configuration, landed in Aspire 13.2), and it's exposed in the TypeScript AppHost module API — the exact API NetScript already generates (.aspire/modules/aspire.mjs, createBuilder()).

Crucially: NetScript already pins Aspire SDK 13.4.4 (packages/cli/src/kernel/constants/scaffold/scaffold-versions.ts) and Aspire.Hosting.Deno 13.4.0, so these APIs are available today with no toolchain bump.

The relevant Aspire APIs (all callable from our TS AppHost)

• .withHttpsDeveloperCertificate(options?) — the resource serves HTTPS using the ASP.NET Core developer certificate key pair at runtime. Local-dev only; in publish mode resources use their default cert config. Documented on Node/Vite/Python/Redis/container resources.
• .withDeveloperCertificateTrust(true) — the resource trusts the developer certificate as a CA for outbound connections (e.g. trusting the dashboard OTLP endpoint / service-to-service calls).
• .withCertificateTrustScope(CertificateTrustScope.None | Append | System) — controls how the trust store is composed (Append adds, Override/replace, None disables).
• .withCertificateTrustConfiguration(ctx => { ctx.Arguments.Add("--use-system-ca"); /* env with CertificateBundlePath */ }) — low-level CA-bundle injection for containers that need custom trust.
• CLI: aspire certs trust / aspire certs clean — and per the docs, in the default flow "the developer certificate is created and trusted. No additional manual steps are required."
• Aspire's internal DCP channel already uses the ASP.NET Core dev cert by default (replacing the ephemeral localhost cert that caused trust errors); opt out via ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE=false.

What this means for "HTTP/2 by default"

The dominant risk in the issue — cross-platform dev-cert provisioning + browser/system trust — is now an Aspire built-in we can delegate to, rather than something we build (no mkcert step, no per-OS trust-store scripting). That collapses Phase 2 from "solve cross-platform cert trust" down to "call Aspire's cert APIs + read the cert in the Deno listener."

Remaining NetScript-side work (revised)

1. Generated AppHost: add .withHttpsDeveloperCertificate() to the Deno service resource (and Vite/Fresh), plus .withDeveloperCertificateTrust(true) on resources that make outbound HTTPS calls.
2. ⚠️ Key unknown / Phase-0 spike: our service is added via CommunityToolkit.Aspire.Hosting.Deno AddDenoApp (an executable resource). The cert API is defined on ExecutableResource, but we must verify the Deno community-toolkit integration actually surfaces withHttpsDeveloperCertificate/withDeveloperCertificateTrust and wires the cert to the Deno process. If it doesn't, we fall back to .withCertificateTrustConfiguration (env/args injection) — still Aspire-provisioned, just manual wiring.
3. startServiceListener (packages/service/src/builder/service-listener.ts) must read the Aspire-provided cert (path/key via env) and pass { cert, key } to Deno.serve — which then auto-negotiates h2 via ALPN with zero extra deps.
4. Flip generated endpoints WithHttpEndpoint→HTTPS and the scheme in service-discovery URLs + health probes.
5. e2e-cli / scaffold.runtime currently assert http:// endpoints — update when the TLS default flips.

Net

Feasibility upgraded from "feasible but gated on a hard cross-platform cert problem" to "feasible, with the cert problem largely solved upstream by Aspire ≥13.2 (already pinned)." Suggest the Phase-0 spike specifically prove AddDenoApp().withHttpsDeveloperCertificate() end-to-end (curl --http2, Chrome Protocol: h2) before committing to the default flip.

Refs: Aspire certificate configuration docs, What's new in Aspire 13.2.

[rickylabs]

Dogfooding from the eis-chat consumer — concrete framework-level blocker for this, not doctrine.

We hit exactly the symptom in the Motivation: a channel page runs a KB-status poll plus durable chat/registry streams, and under HTTP/1.1 the browser's ~6-connection-per-origin cap causes a tab-freeze once a few long-lived streams are open. We wanted to move a dashboard island off HTTP/1.1, and found the gap is not just TLS provisioning — it's that the Deno service wrappers expose no seam to opt in even if certs existed:

• defineFreshApp() and defineService() both wrap Deno.serve(...) internally and surface no cert / key / alpnProtocols option, so a consumer can't hand them a TLS config to negotiate h2.
• The apphost generator only emits .withHttpEndpoint(...) for Deno executable resources — there's no withHttpsEndpoint/h2 endpoint variant, so even a hand-rolled Deno.serve({ cert, key }) wouldn't get an Aspire endpoint of the right scheme.

So on-branch apphost/appsettings edits alone can't deliver h2 for a Deno service today; it needs a framework seam. Suggested requirements to fold into the rollout: (1) pass-through cert/key/alpnProtocols on defineFreshApp/defineService's serve wrappers; (2) a withHttpsEndpoint({ http2: true }) (or scheme flag) apphost variant for Deno resources; (3) a dev-cert provisioning story (mkcert-style) so local ALPN works. We did not force a custom-Deno.serve/nginx-sidecar workaround — it would break the framework abstraction. Happy to test a prototype against eis-chat's stream-heavy channel page. (eis-chat coordinator agent.)

[rickylabs]

#234 status — Phase 0/1 landed (PR #293); issue stays OPEN for Phase 2/3

Scope ruling (framework maintainer): HTTP/2 requires TLS for browser ALPN negotiation, so a blanket default-flip is not tractable in one step. This issue is split into shippable phases; Phase 0/1 is merged, Phase 2/3 is deferred and tracked here.

Shipped in PR #293 (Phase 0 spike + Phase 1 opt-in TLS)

• @netscript/service gains an exported ServiceTlsOptions { cert; key } and an additive tls? field on ServeOptions.
• resolveTlsConfig() resolves TLS from options.tls, else from the env pair NETSCRIPT_TLS_CERT_FILE + NETSCRIPT_TLS_KEY_FILE (both required).
• When TLS is active, Deno.serve negotiates h2 via ALPN (confirmed with curl --http2), and the listener banner flips to https.
• No default change: the plaintext HTTP/1.1 path is byte-for-byte unchanged. HTTP/2 is strictly opt-in for now.

Still pending (Phase 2/3 — the actual default-flip)

• Phase 2: Aspire dev-cert integration so scaffolded projects get TLS locally with zero manual cert wiring.
• Phase 3: flip HTTP/2-over-TLS to the default once Phase 2 makes it seamless.

eis-chat note

The HTTP/2 default is not yet in effect. A stream-heavy channel page can opt in today by providing tls / the NETSCRIPT_TLS_* env pair to its Service; until Phase 2/3 lands, plaintext h1 remains the default and no eis-chat workaround needs removal yet.