connectrpc 0.1.0

data/docs/grpc-web.md

@@ -0,0 +1,165 @@
+# gRPC-Web servers
+
+The [supported 0.x contract](support.md) defines the target compatibility
+boundary and the remaining adoption gates.
+
+Enable gRPC-Web explicitly on the existing server. Generated declarations,
+message bindings, unary invokers and server-stream handlers remain protocol neutral.
+There is no Ruby gRPC-Web client or new runtime dependency.
+
+```ruby
+binding = ConnectRPC::Bindings::GoogleProtobuf.new
+cors = ConnectRPC::GRPCWebCORS.new(
+  origins: ["https://app.example"], credentials: true,
+  request_headers: %w[authorization x-csrf-token], expose_headers: ["x-request-id"]
+)
+server = ConnectRPC::Server.new(
+  services: [service], handlers: handlers, binding: binding,
+  protocol: %i[connect grpc grpc_web], cors: cors
+)
+```
+
+`protocol: :grpc_web` selects Web alone. A protocol array is copied and frozen;
+it must contain distinct `:connect`, `:grpc` or `:grpc_web` symbols. The default
+is `:connect`. `:auto` remains exactly Connect and native gRPC. Both gRPC families
+require `_GRPCStatusCodec`, supplied by the Google binding or a separate
+`status_codec:` composed with a custom protobuf binding. Enabling Web on a server
+does not change `Client(protocol: :connect | :grpc)` or its default transport.
+
+When Connect is enabled, an actual GET selects Connect before observation,
+native publication and Web CORS. Query controls override ignored POST content
+headers, including a supplied Web Content-Type. Safe unary methods use the
+existing Connect GET path; unsafe methods return 405 without handler dispatch.
+A Web-only server still classifies Web GET as Web and rejects it with 405.
+
+| Host | Unary binary/text | Server-stream binary/text wire | Incremental browser stream |
+| --- | --- | --- | --- |
+| Async native H2 | Yes | Yes | Text |
+| Falcon native H2 and H1 | Yes | Yes | Text |
+| Rack with rackup/WEBrick | Yes | Rejected before input | No |
+| Native Rails controller | Yes | Rejected before callbacks | No |
+| Testing manual encoded `TransportRequest` | Yes | Rejected before input | No |
+
+Official grpc-web 2.1.1 browser clients support binary unary, text unary and
+incremental text server streaming. Binary XHR buffers server-stream responses.
+Binary server-stream wire interoperability uses independent connect-go. Client
+streaming, bidi, JSON, per-message compression and whole-body compression are
+outside this profile. Puma has not been verified. Browser TLS fixtures use an
+explicit test-only verification exception; verified TLS/mTLS wire checks are
+separate. Browser client-certificate selection is not promised.
+
+## Media, framing and errors
+
+Requests accept exactly `application/grpc-web[+proto]` or
+`application/grpc-web-text[+proto]`, case-insensitively, without parameters.
+Responses include `+proto`. POST is required. An independent bounded Accept
+list supports these aliases, `application/*`, `*/*` and standard q values. The
+most specific match determines each representation's quality. Highest quality
+wins; the request representation wins ties. Responses vary on Accept.
+
+Exactly one framed protobuf request and request EOF precede invocation. Empty
+protobuf is a message; missing or excess requests are UNIMPLEMENTED. Excess
+framing is detected without decoding a second message. Reserved flags, request
+terminal, truncation, malformed protobuf/base64 and malformed Content-Length
+are INVALID_ARGUMENT. Unnegotiated compressed DATA is INTERNAL. Unsupported
+valid grpc-encoding tokens are UNIMPLEMENTED; malformed/repeated encoding is
+INTERNAL. Web remains identity-only on a mixed server configured with gzip.
+
+Before negotiation, 405/Allow, 415/Accept-Post and 406 are bare HTTP responses.
+After negotiation, RPC errors use HTTP 200 and one 0x80 body terminal. The
+terminal contains lower-case CRLF field lines, exactly one grpc-status and no
+extra empty line. Repeated trailers remain separate wire lines; the official
+JS runtime collapses duplicate trailer keys. Rich errors use the canonical
+private Any/Status codec described in [native gRPC](grpc.md). All six grpc-timeout
+units work; zero expires immediately and absence means no logical expiry.
+
+## CORS and Rails
+
+CORS is disabled by default. One owner controls each mount. `GRPCWebCORS` is an
+immutable configuration value with exact serialized ASCII HTTP(S) origins.
+It accepts no wildcard, regex, callback or null origin. At most 32 distinct
+origins of 2 KiB each and 32 additional token header names of 128 bytes each are
+accepted. Credential sharing defaults false. Explicit additions are required
+for auth, CSRF and trace request headers.
+
+Owned OPTIONS preflight returns empty 204 or 403 before RPC observation, body
+reads, binding or application callbacks. Requested method must be POST and
+requested names must be allowed. Max-Age is zero. Actual Web requests without
+Origin are allowed; disallowed or ambiguous origins receive 403 before input.
+Allowed-origin policy also decorates RPC errors, negotiation failures and native
+admission 503. Vary merges Origin, Accept and preflight controls without replacing
+application cache, cookie or security fields. Conflicting application
+access-control fields fail closed before publication. Set `cors: nil` when outer
+middleware already owns CORS. CORS does not authenticate or replace CSRF checks.
+
+Native Rails overrides stay private:
+
+```ruby
+def connect_protocol = %i[connect grpc_web]
+def connect_status_codec = connect_binding
+def connect_cors = application_web_cors
+def connect_limits = { grpc_status_wire_limit: 65_536, grpc_status_limit: 65_536 }
+```
+
+Explicitly route the intended POST and OPTIONS paths. The normal controller
+invoker, callbacks, authentication, sessions, cookies, CSRF and security headers
+remain active. Preflight does not bypass actual POST checks. A valid CSRF token
+does not override Rails' origin policy. No CSRF exemption is installed.
+
+## Bounds and host SPI
+
+Message and independent message-wire limits default to 4 MiB. Framing adds five
+bytes. Binary request entity cap is `5 + request_wire_limit`; text entity cap is
+`4 * (5 + request_wire_limit)` because independently padded one-byte groups can
+expand fourfold. Declared and actual encoded bytes, decoded framing and message
+bytes are checked independently. Incremental decoding retains at most three
+encoded carry characters plus a bounded decoded fragment. Whitespace, bad
+alphabet, padding, pad bits and incomplete quartets are rejected.
+
+`grpc_status_wire_limit` and `grpc_status_limit` default to 64 KiB. Terminal
+serialization checks both actual CRLF bytes and name/value/32-byte field
+accounting. Rich status has an independent decoded cap. Oversize status becomes
+bounded RESOURCE_EXHAUSTED, or aborts if even the minimal terminal cannot fit.
+Text terminal staging is separately bounded by base64 expansion. Portable unary
+uses a finite aggregate response cap; native streaming never aggregates a whole
+response. Native output retains one queued and one in-flight 16 KiB entity
+fragment. Text uses raw slices of at most 12,288 bytes and flushes padded groups
+at existing write boundaries, including the first small prefix.
+
+Native H2 ingress remains 65,536 bytes/five entries with 16 KiB chunks and
+consumption-based stream credit. The H1 input adapter may retain one pinned
+backend chunk of up to 64 KiB. During rejected-input cleanup this remainder can
+coexist with one discard read of at most 64 KiB. Complete parsed field blocks are checked before application copies;
+H2 includes pseudo/status fields. Parser/readahead, HPACK/CONTINUATION temporaries,
+codec allocations, CPU and total RSS are outside these retention bounds.
+
+Custom hosts call `Server#call_grpc_web(path:, http_method:, headers:, input:,
+output:, publish:, capabilities: [:unary], lifecycle: nil, cancellation: nil)`.
+Streaming requires explicit `:server_stream` capability. Input and publication
+reuse `_StreamingInput` and `StreamHead`; `_GRPCWebOutput` provides bounded
+`write(bytes, timeout:)`, `finish(terminal:)` and `abort`. Finish only stages
+prepared bytes. Hosts must hold **all terminal bytes** until the original
+processor and outer application cleanup succeed, then release those bytes.
+Body consumers perform no handler, codec, status or base64 work. Cleanup failure
+discards the candidate terminal and aborts delivery. Admission includes original
+processing and wire/callback completion. H1 has explicit resources, not fake H2
+streams. Only an actual H2 CANCEL reset signals Context cancellation. H1 EOF,
+disconnect and host shutdown do not. There is no Connect one-second tail policy.
+Falcon native H1 now has a separate explicit rejected-input resource policy:
+one absolute 100 ms allowance to finish the original HTTP body framing, shortened
+by the original valid grpc-timeout and subject to earlier cancellation, drain
+and owner abort. Each discard read is at most 64 KiB; progress does not reset the
+budget and a following request is never consumed. Expiry or malformed framing
+retires that connection raw-first, preserving the original RPC outcome and
+independent aborted delivery. This best effort does not promise delivery for
+arbitrarily slow uploads or extend existing cleanup allowances. See the
+[Falcon guide](../gems/connectrpc-falcon/README.md#grpc-web).
+
+`Server#cors_response(path:, http_method:, headers:, response: nil)` is a pure
+typed host SPI for early decisions and idempotent decoration, including admission
+503. Call it before lifecycle start for preflight or denied requests.
+
+The optional OTel adapter maps Web to the project's gRPC semconv 1.44 mapping,
+with `rpc.system.name=grpc` and bounded `connectrpc.protocol=grpc_web`. Call.protocol
+is fixed before subscriber start. Processing, admission, delivery and original
+failures remain separate; SDK/exporter ownership and privacy are unchanged.

data/docs/grpc.md

@@ -0,0 +1,75 @@
+# Native gRPC
+
+The [supported 0.x contract](support.md) defines the target compatibility
+boundary and the remaining adoption gates.
+
+Configure `Client(protocol: :grpc)` with an Async transport and a protobuf
+binding. Unary, server streaming, client streaming and bidi use the existing
+method declarations, generated clients and scoped stream endpoints. Configure
+`Server(protocol: :grpc)` for gRPC alone, or `protocol: :auto` for exactly Connect
+and gRPC. Async and Falcon HTTP/2 hosts share the native execution engine.
+h2c, verified TLS and mTLS use the existing backend configuration.
+
+The default remains Connect. gRPC accepts `application/grpc` and
+`application/grpc+proto`, and emits the latter. It supports protobuf, identity and
+opt-in per-message gzip. JSON and GET are rejected eagerly. NetHTTP, Rack, Rails,
+Testing and Falcon HTTP/1 reject gRPC before message encoding or handler input.
+Native handlers are plain handlers; native execution provides no Rails callback
+or authentication execution contract.
+
+Enabling gRPC requires a capable status codec at construction. A binding may
+implement `_GRPCStatusCodec`, or callers can pass a separate
+`status_codec:` with `encode_status(Error) -> String` and
+`decode_status(String, code: Integer) -> Error`. The optional Google binding
+provides it using canonical Any and Status descriptors in a private pool.
+Opaque detail types and bytes survive without registering their descriptors.
+Core has no protobuf runtime dependency.
+
+`grpc_status_wire_limit` bounds the complete terminal field block, counting
+name bytes, value bytes and 32 bytes per occurrence. `grpc_status_limit` bounds
+decoded rich status bytes before protobuf parsing. Both default to 65,536.
+Base64 expansion means a decoded status may exceed the independent wire limit.
+Native gRPC always limits each complete decoded HEADERS block to 65,536 bytes,
+including custom and informational fields, even with larger core configuration.
+These are retention bounds applied before application copies, excluding HPACK,
+CONTINUATION, parser temporary allocation, CPU and RSS. Message and independent
+wire limits remain 4 MiB per message. Ingress and output bounds are unchanged.
+
+Clients require actual final HTTP/2 HEADERS and stream EOF. Trailers-only means
+initial final-response HEADERS with END_STREAM. Ordinary initial grpc-status is
+not terminal. Server terminal fields are staged behind processor completion;
+late application cleanup failure prevents successful delivery. Success includes
+transport-owned cleanup, never peer receipt or TLS shutdown.
+
+Status accepts a nonempty ASCII digit sequence with leading zeros, bounded by
+the field block budget. Numeric values above uint32 map to unknown; there is no
+10-character spelling limit or unbounded integer parse. Output is canonical.
+Rich status codes compare numerically before unknown-code normalization, and
+rich messages take precedence over grpc-message. Invalid percent escapes remain
+literal; decoded invalid UTF8 is scrubbed. As a deliberate stricter policy than
+grpc-go, details on OK, malformed or duplicate details, and mismatched rich codes
+produce safe internal instead of silently dropping rich data.
+
+Missing server timeout means no logical expiry. gRPC timeout accepts all six
+case-sensitive units and zero as immediately expired. Clients default to 30
+seconds; nil omits the timeout and logical watchdog. Dispatch recomputes remaining
+budget without extending monotonic expiry. gRPC per-operation waits have a
+9,999,999.999-second ceiling, further shortened by real deadlines. Connect Async
+nil waits retain their existing behavior. There is no one-second gRPC tail timer.
+Send-I/O terminal recovery has one absolute 100ms budget and allows at most
+262,144 additional body bytes, with separate finite header limits. It skips
+messages without decoding or inflating them and cannot take over an active
+reader. Only a validated remote error can replace an unhandled send failure;
+remote success cannot. The existing destructive cleanup has a separate 100ms
+budget. A stuck frame can fail its connection and siblings during that cleanup.
+
+Only actual peer CANCEL resets signal server Context cancellation. Half-close,
+EOF, other resets, connection loss and shutdown do not. No retry or replay occurs.
+Client reset mapping follows grpc-go 1.85.0: FLOW_CONTROL_ERROR and
+ENHANCE_YOUR_CALM map to resource_exhausted, REFUSED_STREAM to unavailable,
+CANCEL to canceled, and INADEQUATE_SECURITY to permission_denied. Other resets
+map to internal. The FLOW_CONTROL_ERROR choice differs from the older protocol
+document's mapping. NO_ERROR can preserve queued data and a valid final status;
+it cannot establish success without that status and owned transport completion.
+Native unary executes the configured invoker with a normal Context, including
+custom invokers that have no handler-map entry.