MASQUE and CONNECT-UDP for Web Operators

Why MASQUE exists

Web applications increasingly use transports that do not fit a traditional HTTP request-response tunnel. MASQUE is a family of approaches for carrying traffic through HTTP proxies. For operators, its value is a standardized way to describe proxy functions; the name alone does not establish that a particular service offers them.

MASQUE sits across several protocol layers. HTTP defines the request and response semantics, HTTP/2 or HTTP/3 commonly provides the proxy connection, and the requested function determines how traffic is carried onward. RFC 9298 specifies proxying UDP in HTTP, while RFC 9297 defines HTTP Datagrams and the Capsule Protocol used by related extensions.

The problem space is easier to review when the names are treated as roles rather than as a product label. A proxy may expose an HTTP endpoint, accept a CONNECT-UDP request, and then apply an independent authorization decision for the target. Another service may support ordinary HTTPS tunneling but have no UDP relay at all. Both services can use familiar HTTP words in their documentation while offering different operational capabilities. Start with the function required by the application and map each responsibility to the team that owns it.

MASQUE also provides a common vocabulary for boundaries. The client knows the proxy endpoint and its local policy. The proxy knows which targets it will relay and which transport it can reach. The origin knows its own application protocol and access controls. These boundaries do not disappear when the connection is encrypted. They only become harder to see if a team treats a successful browser navigation as proof of every intermediate capability.

An operator can therefore ask a small set of outcome-focused questions. Which HTTP version is used between the client and proxy? Is CONNECT-UDP listed for the exact account and endpoint? Does the provider describe target authorization and regional availability? What user-visible state is accepted when the function is unavailable? These questions qualify a service without requiring private service details.

What CONNECT-UDP means

Over HTTP/2 and HTTP/3, CONNECT-UDP is the RFC 9298 extended CONNECT request that uses the :protocol=connect-udp value to ask a proxy for a UDP communication context; over HTTP/1.1 the same request role uses an HTTP Upgrade to connect-udp. The request is addressed to the proxy, which decides whether it will accept the requested target under its own policy. It is not a command that makes an ordinary web origin become a proxy, nor does a browser request prove that the proxy can reach every destination.

The word “connect” can be misleading because the resulting context is not the same as an end-to-end socket owned by the page. The proxy remains an intermediary with its own authorization, limits, and failure behavior. The web application still speaks its application protocol over the permitted context, and the destination still decides whether it accepts that protocol. This separation matters when a service advertises UDP support but restricts particular destinations, ports, regions, or account classes.

CONNECT-UDP is also not a general promise about browser APIs. A page cannot select a proxy request type merely by naming it in JavaScript, and a browser cannot manufacture a relay service that the configured provider does not offer. The browser, proxy, and destination each need compatible policy. A product review should describe the observable workflow and the approved route, not assume that a protocol token grants a new network capability.

The extended CONNECT request belongs to a larger HTTP control plane. Authentication, authorization, request lifecycle, and error reporting still follow the proxy's contract. A provider can reject the request before any UDP exchange, close an accepted context later, or limit the destination according to service policy. The application should preserve a clear recovery state for each category rather than presenting every failure as a generic page error.

The operator should separate three responsibilities: the client and proxy connection, the proxy's UDP relay service, and the destination's application behavior. A successful connection to the proxy only establishes the first leg. Provider support, account policy, destination reachability, and application protocol compatibility are separate conditions. This is different in scope from QUIC proxy routing and UDP over SOCKS5, which cover their own route setup and protocol-specific operating procedures.

Datagrams and Capsules

HTTP Datagrams provide a way to associate datagram data with an HTTP context, while the Capsule Protocol carries extension-defined control information in an HTTP stream. They have related but distinct roles: datagrams carry datagram-oriented traffic; capsules can communicate context changes or other control messages. The exact mapping depends on the extension and transport, so they should not be treated as interchangeable descriptions of one wire format.

When HTTP/3 is involved, QUIC is the transport for HTTP/3 streams and datagrams as defined by the relevant specifications. That relationship does not mean every HTTP/3 request uses CONNECT-UDP or that HTTP/3 support proves a proxy supports MASQUE. For negotiation and browser compatibility boundaries, see HTTP/3 and QUIC browser compatibility.

HTTP Datagrams are associated with an HTTP context, which gives an extension a place to relate datagram traffic to request-level state. Capsule messages travel through a reliable HTTP stream and can carry extension-defined instructions or context information. The distinction lets an extension choose the delivery property it needs for each kind of information. Even when a datagram travels in a DATAGRAM capsule on a stream (as with HTTP/2), it keeps datagram semantics, so the application should not depend on reliable delivery. Nor does the distinction make a Capsule a universal control language for unrelated services.

The transport underneath also matters. HTTP/3 uses QUIC, whose streams and datagram facilities have their own connection and loss behavior. HTTP/2 has a different set of framing and extension constraints. A provider may support a MASQUE function over one HTTP version while limiting it over another. Ask the provider which protocol combinations are qualified instead of inferring support from a generic statement that the endpoint speaks HTTP.

For an application owner, the practical question is which semantics are required. A media or interactive feature may need datagram delivery and tolerate loss, while an authorization decision may need a reliable control message. The operator does not need to redesign these semantics at the proxy layer; the operator needs to confirm that the selected service and browser policy preserve the application contract and expose a bounded failure when they cannot.

Operational review

Before adopting a UDP-capable proxy service, confirm which endpoint, account tier, region, target policy, and concurrency terms include CONNECT-UDP. Ask how the service reports rejection and what its documented availability expectations are. Record the application outcome that matters and an approved recovery path; do not infer a successful UDP relay from an ordinary HTTPS page load.

Keep the qualification record at the same level as the production decision. Name the browser release, context policy, provider endpoint class, region, account entitlement, and destination category. Record whether the primary journey completed, whether an optional feature was unavailable, and which owner receives the next action. This creates evidence that can be repeated after a provider or browser change without retaining customer content or secrets in a public document.

Review the proxy and origin as separate dependencies. The proxy may accept the control request while the origin rejects the application protocol. Conversely, the origin may support the application while the proxy account lacks the required operation. A useful incident category identifies the failed boundary and the approved retry or escalation path. It should not expose credentials, private destination histories, or detailed traffic captures to an end user.

A route policy should also say what is not allowed. If the UDP function is unavailable, an approved HTTP/2 journey may continue when the application permits it, or a feature may show an unavailable state until the operator resolves the provider issue. A direct connection that appears to make the page load is not an implicit fallback. Treating it as one would change the network boundary without an explicit decision.

Provider documentation is necessary but not permanent evidence. Recheck after a plan change, endpoint migration, region change, browser major update, or material origin change. Compare the same application journey and keep the last accepted policy available while evaluating a candidate. A protocol label is useful for explaining a result, but the customer outcome and recovery behavior are the acceptance criteria.

Treat failures as bounded capability or availability outcomes. A missing operation should be reported to the provider or deployment owner, while an application-specific fallback belongs to the application owner. Keep credentials and detailed traffic records in controlled systems. Avoid creating a direct route as an undocumented recovery behavior.

BotBrowser supports choosing an approved proxy route per browser context, which can make the same network policy repeatable for a reviewed journey. It cannot implement a MASQUE service, add CONNECT-UDP support to a provider, or control the provider's upstream relay or origin behavior. Context routing is a client-side policy boundary, not a substitute for provider capability.

Per-context routing is helpful when one browser process serves several approved workflows with different network requirements. The context setting selects the route that the deployment has already qualified; it does not create new provider entitlement or alter the destination's protocol choices. Apply the policy before the first page action, record the route name beside the context owner, and keep the user-visible outcome tied to that record.

The product boundary is intentionally modest. BotBrowser can repeat an approved client-side route and help an operator compare the same journey under a documented policy. It does not expose a MASQUE server, implement an upstream relay, or guarantee that a destination will use HTTP/3. Those capabilities belong to the proxy provider, origin, and surrounding network policy. Keeping the boundary explicit prevents a browser setting from being mistaken for a service contract.

When the route is not qualified, the responsible action is to choose another approved provider path, wait for recovery, or stop the workflow. Do not use a browser flag or page script to invent a missing CONNECT-UDP operation. The operational record should make that decision visible to support staff, while sensitive provider evidence remains in the controlled systems used for release review.

The route record should identify the relationship between the browser context and the proxy account without copying a secret into a command, ticket, or page log. A short route name, owner, region, and capability summary are usually enough for support to select the correct recovery. Keep the detailed provider agreement and authorization evidence in the system that controls access to it.

Application teams should state whether UDP is required for the primary task or only for an optional enhancement. A document, form, or ordinary API may remain useful over an approved stream-based route. A real-time function may instead show a clear unavailable state and invite a later retry. This decision belongs in the application contract before an incident occurs.

A provider can change behavior without changing the :protocol=connect-udp protocol token. It may alter regional capacity, account limits, destination policy, or the supported HTTP version. Repeat a representative journey after such changes and compare the result with the last accepted record. The comparison should focus on completion, bounded failure, and recovery ownership rather than on a presumed transport label.

Browser release reviews should keep protocol roles distinct. The browser can select a configured route, negotiate with a destination, and expose a user-visible result. It does not certify the proxy's relay policy or the destination's application service. Record the browser major, profile family, route policy, and destination category together so a later change has a useful baseline.

Network operators should also document which failures are expected. A rejected CONNECT-UDP request, an unavailable proxy endpoint, and an origin-level application error have different owners even if they appear during one page journey. A small category and an approved next action help support route the case without collecting private traffic or exposing credentials.

The most durable explanation is therefore layered: MASQUE names a proxying problem space, CONNECT-UDP names a standardized request role, HTTP Datagrams and Capsules describe related transport mechanisms, and the provider contract determines what is actually available. BotBrowser can repeat the client policy that has been approved, while the provider and origin remain responsible for the service capabilities beyond that boundary.

Use the same vocabulary in a runbook and in a customer-facing status. “Proxy accepted the HTTP request” is a narrower statement than “the application reached its destination.” “UDP relay is unavailable for this account” is more actionable than “HTTP/3 failed.” Precise wording keeps an incident from being assigned to the wrong team and helps an operator choose a permitted recovery without guessing.

The acceptance record should avoid turning protocol names into a performance promise. QUIC, HTTP/3, datagrams, and a proxy relay can affect how a journey behaves, but the result still depends on the destination, account policy, and network conditions. Measure the application task that matters, retain a bounded outcome, and revisit the record when one of those conditions changes.

Teams can keep this review lightweight. A named route, a matching browser and profile release, a representative destination category, and a clear unavailable state are enough to establish an operational baseline. Detailed provider logs and authorization material belong in controlled systems. A public status note only needs to tell readers which role is supported, which boundary remains external, and what recovery is approved.

This separation also helps when several teams share a browser deployment. The context owner selects an approved client route, the network owner qualifies the provider, and the application owner defines acceptable fallback. A short handoff between those owners is stronger evidence than assuming a browser option can supply a missing proxy service.

For a release note, describe the accepted result in ordinary terms: the selected context used the approved proxy policy, the destination journey completed or showed its documented unavailable state, and the next owner was known. Then link the public standards that explain the roles without suggesting that the browser supplies the provider service. This format gives web operators enough context to make a compatible choice while keeping provider credentials, private destinations, and detailed traffic evidence outside the release note.

That wording is useful during support handoffs as well. It separates a browser policy decision from a provider service decision, gives the application owner a concrete state to test, and leaves room for a qualified alternative route when one exists. It also prevents a successful HTTP navigation from being used as evidence for an unrelated UDP capability. The same record can support a release review, an incident update, and a later provider requalification without exposing session content. Public status pages should stay at the level of roles, outcomes, and boundaries; account-specific evidence stays in authorized systems.

Run the qualification checks

Apply these checks to each candidate route and record a pass or fail for each one.

1. Provider documentation names CONNECT-UDP (RFC 9298) support for the endpoint class and account. Record the endpoint class, the account entitlement, and the HTTP version. Fail if the documentation only claims HTTP/3.
2. The representative journey runs through the approved per-context route. Pass if it completes, or if it ends in a bounded failure with a named owner. Record the route name and context policy used.
3. The proxy-leg status is compared with the origin outcome. Classify "proxy accepts, origin rejects" and the reverse as separate results.
4. A route that lacks CONNECT-UDP is recorded as a capability mismatch. Fail if the run record shows the journey completed over a direct path instead of the approved route.
5. If an HTTP/2 fallback is approved for the application, it is recorded as a fallback. Fail if a fallback was used and not recorded.
6. The checks are repeated after a plan change, endpoint migration, region change, browser major update, or material origin change. Keep the last accepted policy until the repeat run passes.

Sources

• RFC 9298: Proxying UDP in HTTP
• RFC 9297: HTTP Datagrams and the Capsule Protocol
• RFC 9000: QUIC Transport
• RFC 9114: HTTP/3
• MDN: HTTP/3
• BotBrowser: per-context proxy