A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
http_sse_wire_stream.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 The A11 Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
28#ifndef A11_NET_HTTP_SSE_WIRE_STREAM_H_
29#define A11_NET_HTTP_SSE_WIRE_STREAM_H_
30
31#include <cstdint>
32#include <functional>
33#include <memory>
34#include <optional>
35#include <string>
36#include <string_view>
37
38#include <absl/base/nullability.h>
39#include <absl/status/status.h>
40#include <absl/status/statusor.h>
41#include <absl/time/time.h>
42
44#include "a11/data/types.h"
46#include "a11/net/http2.h"
49#include "a11/net/wire_stream.h"
50
51namespace a11::net {
52
54inline constexpr std::string_view kSseStreamIdHeader = "x-a11-stream-id";
56inline constexpr std::string_view kSseHttpHeaderPrefix = "x-a11-http-";
62inline constexpr std::string_view kSseOutboundModesHeader = "x-a11-outbound";
64inline constexpr std::string_view kSseOutboundPostToken = "post";
66inline constexpr std::string_view kSseOutboundStreamToken = "stream";
75inline constexpr std::string_view kSseWireStreamContentType =
76 "application/vnd.a11.wire-stream+json";
78inline constexpr std::string_view kDefaultSseConnectEndpoint = "/connect";
80inline constexpr std::string_view kDefaultSseMessageEndpoint =
81 "/streams/{id}/message";
82
101 kPost,
113 kStream,
114};
115
127 std::string connect_endpoint =
128 std::string(kDefaultSseConnectEndpoint);
139 std::string message_endpoint =
140 std::string(kDefaultSseMessageEndpoint);
146 // Server-side: whether a streamed outbound request body is accepted, and so
147 // advertised in kSseOutboundModesHeader.
158 // Server-side response-header policy: the `Server` header, cross-origin
159 // access, and the hints that tell a client and its intermediaries how to
160 // treat a reply.
166
168 absl::Status Validate() const;
169};
170
180 : public WireStream,
181 public std::enable_shared_from_this<HttpSseWireStream> {
182 public:
183 ~HttpSseWireStream() override = default;
184
187
188 absl::Status Send(data::WireMessage message) override;
189 a11::Task Start(OnMessage on_message, OnDone on_done) override;
190 a11::Task Accept(OnMessage on_message, OnDone on_done) override;
191 absl::Status HalfClose(data::ByteMap trailers) override;
193 absl::Status Abort(absl::Status status) override;
194 absl::Status SetDeadline(absl::Time deadline) override;
195
196 [[nodiscard]] absl::Time deadline() const override;
197 [[nodiscard]] absl::Status GetStatus() const override;
198 [[nodiscard]] std::optional<data::ByteMap> GetTrailers() const override;
199 [[nodiscard]] std::string GetId() const override;
200 [[nodiscard]] void* absl_nullable GetImpl() const override;
201
203 [[nodiscard]] HttpHeaders GetHttpRequestHeaders() const;
204
212 [[nodiscard]] std::string GetRequestPath() const;
215 [[nodiscard]] std::optional<HttpHeaders> GetHttpResponseHeaders() const;
217 absl::Status SetHttpRequestHeaders(HttpHeaders headers);
219 absl::Status SetHttpResponseHeaders(HttpHeaders headers);
223
224 protected:
225 enum class Role { kClient, kServer };
226 struct State;
227
229 std::shared_ptr<State> state);
230
231 a11::Task StartEndpoint(bool accept, OnMessage on_message, OnDone on_done);
233 a11::Task HandleBridgeMessage(std::optional<data::WireMessage> message);
236 void FailTransport(absl::Status status);
237 void MarkHttpHeadersReady(HttpHeaders headers);
238 void SetId(std::string id);
239 [[nodiscard]] HttpSseOptions options() const;
240 [[nodiscard]] std::shared_ptr<InProcessWireStream> bridge() const;
241
243 virtual absl::Status Transmit(data::WireMessage message) = 0;
244 virtual void* absl_nullable TransportImpl() const = 0;
245
246 virtual void TransportDone() {}
247
248 private:
249 Role role_;
250 std::shared_ptr<InProcessWireStream> application_;
251 std::shared_ptr<InProcessWireStream> bridge_;
252 std::shared_ptr<State> state_;
253
254 friend class HttpSseServer;
255};
256
264 private:
265 struct ClientState;
266
267 struct ConstructorToken {};
268
269 public:
280 static absl::StatusOr<std::shared_ptr<HttpSseClientWireStream>> Create(
281 std::string_view url, HttpSseOptions options = {},
282 std::shared_ptr<Http2Client> client = nullptr,
283 HttpHeaders request_headers = {});
284
287 [[nodiscard]] std::shared_ptr<Http2Client> client() const;
288
296 [[nodiscard]] SseOutboundDelivery outbound_delivery() const;
297
299 std::shared_ptr<State> state,
300 std::shared_ptr<ClientState> client_state);
301
302 protected:
303 a11::Task OpenTransport() override;
304 absl::Status Transmit(data::WireMessage message) override;
305 void* absl_nullable TransportImpl() const override;
306 void TransportDone() override;
307
308 private:
309 static void ReceiveSseLoop(
310 const std::shared_ptr<HttpSseClientWireStream>& self);
311
314 absl::Status OpenOutboundStream(const HttpHeaders& response_headers);
316 absl::Status TransmitOnStream(std::string_view payload, bool terminal);
318 absl::Status TransmitAsPost(std::string payload);
320 absl::Status ClaimPostSlot();
322 void ReleasePostSlot();
324 absl::Status AwaitPostsDelivered();
325
326 std::shared_ptr<ClientState> client_state_;
327};
328
329class HttpSseServer;
330
338 private:
339 struct ServerStreamState;
340
341 struct ConstructorToken {};
342
343 public:
346 a11::Task Accepted() const;
347
349 std::shared_ptr<State> state,
350 std::shared_ptr<ServerStreamState> server_state);
351
352 protected:
353 a11::Task OpenTransport() override;
354 absl::Status Transmit(data::WireMessage message) override;
355 void* absl_nullable TransportImpl() const override;
356 void TransportDone() override;
357
358 private:
359 std::shared_ptr<ServerStreamState> server_state_;
360
361 friend class HttpSseServer;
362};
363
366 std::function<a11::Task(std::shared_ptr<HttpSseServerWireStream>)>;
367
374class HttpSseServer : public std::enable_shared_from_this<HttpSseServer> {
375 public:
385 static absl::StatusOr<std::shared_ptr<HttpSseServer>> Create(
386 std::string bind_address, std::uint16_t port,
387 OnHttpSseConnect on_connect = {}, HttpSseOptions options = {});
388
390
394 absl::Status Stop();
396 [[nodiscard]] std::uint16_t port() const;
398 [[nodiscard]] bool running() const;
400 [[nodiscard]] std::shared_ptr<Http2Server> http2_server() const;
401
402 private:
403 struct State;
404
405 explicit HttpSseServer(std::shared_ptr<State> state)
406 : state_(std::move(state)) {}
407
408 static a11::Task HandleRequest(const std::shared_ptr<State>& state,
409 HttpRequest request,
410 std::shared_ptr<Http2ResponseWriter> response);
411 static a11::Task HandleConnect(const std::shared_ptr<State>& state,
412 HttpRequest request,
413 std::shared_ptr<Http2ResponseWriter> response);
414 static a11::Task HandleMessage(const std::shared_ptr<State>& state,
415 std::string stream_id, HttpRequest request,
416 std::shared_ptr<Http2ResponseWriter> response);
418 static a11::Task HandleMessageStream(
419 const std::shared_ptr<State>& state, std::string stream_id,
420 HttpRequest request, std::shared_ptr<Http2ResponseWriter> response);
421
422 std::shared_ptr<State> state_;
423
425};
426
429
430} // namespace a11::net
431
432#endif // A11_NET_HTTP_SSE_WIRE_STREAM_H_
std::string stream_id
Definition authorization.cc:218
The client-side HTTP SSE wire stream, dialing out to a server URL.
Definition http_sse_wire_stream.h:263
std::shared_ptr< Http2Client > client() const
Definition http_sse_wire_stream.cc:668
void TransportDone() override
Definition http_sse_wire_stream.cc:1106
SseOutboundDelivery outbound_delivery() const
The outbound delivery method actually in use.
Definition http_sse_wire_stream.cc:763
void *absl_nullable TransportImpl() const override
Definition http_sse_wire_stream.cc:1123
static absl::StatusOr< std::shared_ptr< HttpSseClientWireStream > > Create(std::string_view url, HttpSseOptions options={}, std::shared_ptr< Http2Client > client=nullptr, HttpHeaders request_headers={})
Creates a client SSE wire stream connecting to url.
Definition http_sse_wire_stream.cc:612
a11::Task OpenTransport() override
Definition http_sse_wire_stream.cc:673
absl::Status Transmit(data::WireMessage message) override
Sends one message from the bridge's sender fiber.
Definition http_sse_wire_stream.cc:860
The server-side HTTP SSE wire stream, accepted from a client.
Definition http_sse_wire_stream.h:337
a11::Task Accepted() const
Definition http_sse_wire_stream.cc:1151
void *absl_nullable TransportImpl() const override
Definition http_sse_wire_stream.cc:1212
void TransportDone() override
Definition http_sse_wire_stream.cc:1216
absl::Status Transmit(data::WireMessage message) override
Definition http_sse_wire_stream.cc:1196
a11::Task OpenTransport() override
Definition http_sse_wire_stream.cc:1155
Hosts HTTP SSE wire streams on top of an HTTP/2 server.
Definition http_sse_wire_stream.h:374
std::uint16_t port() const
Definition http_sse_wire_stream.cc:1730
absl::Status Stop()
Stops the server and releases its resources.
Definition http_sse_wire_stream.cc:1699
~HttpSseServer()
Definition http_sse_wire_stream.cc:1355
std::shared_ptr< Http2Server > http2_server() const
Definition http_sse_wire_stream.cc:1741
bool running() const
Definition http_sse_wire_stream.cc:1735
static absl::StatusOr< std::shared_ptr< HttpSseServer > > Create(std::string bind_address, std::uint16_t port, OnHttpSseConnect on_connect={}, HttpSseOptions options={})
Creates and starts an SSE server accepting A11 wire streams.
Definition http_sse_wire_stream.cc:1299
a11::Future< std::shared_ptr< HttpSseServerWireStream > > WaitForStream()
Definition http_sse_wire_stream.cc:1679
Common base for the client and server HTTP SSE wire streams.
Definition http_sse_wire_stream.h:181
Role
Definition http_sse_wire_stream.h:225
absl::Status Abort(absl::Status status) override
Abort the stream, discarding buffered work.
Definition http_sse_wire_stream.cc:454
std::string GetRequestPath() const
The path a server stream was accepted on, query string included.
Definition http_sse_wire_stream.cc:501
a11::Task Start(OnMessage on_message, OnDone on_done) override
Begin the stream as the initiating ("start") side.
Definition http_sse_wire_stream.cc:270
void FailTransport(absl::Status status)
Definition http_sse_wire_stream.cc:428
a11::Task ReceiveTransportMessage(data::WireMessage message)
Definition http_sse_wire_stream.cc:404
absl::Status SetHttpRequestHeaders(HttpHeaders headers)
Sets HTTP headers to send on the SSE request; call before connecting.
Definition http_sse_wire_stream.cc:511
virtual absl::Status Transmit(data::WireMessage message)=0
a11::Task Accept(OnMessage on_message, OnDone on_done) override
Begin the stream as the accepting ("accept") side.
Definition http_sse_wire_stream.cc:274
absl::Status SetDeadline()
Clear any deadline (equivalent to an infinite deadline).
Definition wire_stream.h:168
absl::Status GetStatus() const override
Definition http_sse_wire_stream.cc:472
absl::Status Send(data::WireMessage message) override
Enqueue a message for delivery to the peer.
Definition http_sse_wire_stream.cc:266
absl::Status HalfClose()
Half-close with no trailers.
Definition wire_stream.h:139
void *absl_nullable GetImpl() const override
Definition http_sse_wire_stream.cc:492
void MarkHttpHeadersReady(HttpHeaders headers)
Definition http_sse_wire_stream.cc:547
a11::Task StartEndpoint(bool accept, OnMessage on_message, OnDone on_done)
Definition http_sse_wire_stream.cc:278
HttpHeaders GetHttpRequestHeaders() const
Definition http_sse_wire_stream.cc:496
virtual void TransportDone()
Definition http_sse_wire_stream.h:246
std::string GetId() const override
Definition http_sse_wire_stream.cc:487
std::optional< HttpHeaders > GetHttpResponseHeaders() const
Definition http_sse_wire_stream.cc:506
a11::Task StartInternalBridge()
Definition http_sse_wire_stream.cc:325
absl::Status SetHttpResponseHeaders(HttpHeaders headers)
Sets HTTP headers to send on the SSE response (server side).
Definition http_sse_wire_stream.cc:527
a11::Task WaitForHttpHeaders() const
Definition http_sse_wire_stream.cc:543
absl::Time deadline() const override
Definition http_sse_wire_stream.cc:468
virtual void *absl_nullable TransportImpl() const =0
std::shared_ptr< InProcessWireStream > bridge() const
Definition http_sse_wire_stream.cc:572
void SetId(std::string id)
Definition http_sse_wire_stream.cc:562
virtual a11::Task OpenTransport()=0
std::optional< data::ByteMap > GetTrailers() const override
Definition http_sse_wire_stream.cc:483
a11::Task HandleBridgeMessage(std::optional< data::WireMessage > message)
Definition http_sse_wire_stream.cc:347
HttpSseOptions options() const
Definition http_sse_wire_stream.cc:567
a11::Task HandleBridgeDone()
Definition http_sse_wire_stream.cc:368
a11::Task DrainOutgoingMessages() override
Await delivery of all buffered outbound messages.
Definition http_sse_wire_stream.cc:450
~HttpSseWireStream() override=default
std::pair< std::shared_ptr< InProcessWireStream >, std::shared_ptr< InProcessWireStream > > Pair
A connected pair of endpoints returned by CreatePair().
Definition in_process_wire_stream.h:67
A bidirectional, message-oriented channel between two A11 endpoints.
Definition wire_stream.h:103
absl::Status SetDeadline()
Clear any deadline (equivalent to an infinite deadline).
Definition wire_stream.h:168
absl::Status HalfClose()
Half-close with no trailers.
Definition wire_stream.h:139
GET /actions, on whichever server happens to hold the port.
Completion values used by every asynchronous A11 operation.
A11's nghttp2 HTTP/2 client, server, and streaming primitives.
In-memory paired WireStream that connects two endpoints without a network.
absl::flat_hash_map< std::string, Bytes > ByteMap
String-keyed map of byte values (headers, attributes, etc.).
Definition types.h:58
Definition action.h:66
std::function< a11::Task(std::optional< data::WireMessage > message)> OnMessage
Called for each inbound message; std::nullopt signals the peer half-closed.
Definition wire_stream.h:79
std::function< a11::Task()> OnDone
Called once, when the stream has fully finished (cleanly or via abort).
Definition wire_stream.h:81
std::vector< std::pair< std::string, std::string > > HttpHeaders
An ordered list of (name, value) HTTP/2 header fields.
Definition http2.h:70
constexpr std::string_view kSseOutboundPostToken
Token for one-POST-per-message outbound delivery.
Definition http_sse_wire_stream.h:64
constexpr std::string_view kSseOutboundStreamToken
Token for long-lived-request-body outbound delivery.
Definition http_sse_wire_stream.h:66
constexpr std::string_view kSseStreamIdHeader
Response header naming the stream id assigned to an SSE connection.
Definition http_sse_wire_stream.h:54
SseOutboundDelivery
How an SSE client hands its outbound WireMessages to the server.
Definition http_sse_wire_stream.h:92
@ kPost
One HTTP POST per message.
@ kStream
One long-lived request body carrying every outbound message.
constexpr std::string_view kSseOutboundModesHeader
Response header on the connect response listing the outbound delivery modes the server accepts,...
Definition http_sse_wire_stream.h:62
constexpr std::string_view kDefaultSseConnectEndpoint
Default path on which a client opens the SSE event stream.
Definition http_sse_wire_stream.h:78
constexpr std::string_view kSseHttpHeaderPrefix
Prefix under which application HTTP headers are tunneled over SSE.
Definition http_sse_wire_stream.h:56
constexpr std::string_view kDefaultSseMessageEndpoint
Default message-post path template ({id} is the stream id).
Definition http_sse_wire_stream.h:80
std::function< a11::Task(std::shared_ptr< HttpSseServerWireStream >)> OnHttpSseConnect
Callback invoked with each accepted server-side SSE wire stream.
Definition http_sse_wire_stream.h:366
constexpr std::string_view kSseWireStreamContentType
Content type of a streamed outbound request body.
Definition http_sse_wire_stream.h:75
Future< Unit > Task
Asynchronous operation whose only successful result is completion itself.
Definition future.h:431
stores::ChunkStoreReaderOptions options
Definition runtime_streams.cc:31
Common response headers for A11 HTTP servers.
The top-level frame exchanged between two A11 endpoints.
Definition types.h:516
Where and whether a server answers discovery over plain HTTP.
Definition describe_endpoint.h:72
Body-size limits, buffering thresholds, deadline, TLS, and HTTP protocol negotiation for an HTTP clie...
Definition http2.h:150
A parsed HTTP/2 request: pseudo-headers, fields, and body.
Definition http2.h:90
Definition http_sse_wire_stream.cc:576
Endpoint paths and transport tuning for an HTTP SSE wire stream.
Definition http_sse_wire_stream.h:124
WireStreamOptions stream_options
Per-stream buffering and deadline.
Definition http_sse_wire_stream.h:125
ServerHeaderOptions headers
Server-side response-header policy: the Server header, cross-origin access, and the hints that tell a...
Definition http_sse_wire_stream.h:165
std::string message_endpoint
Outbound endpoint template.
Definition http_sse_wire_stream.h:139
absl::Status Validate() const
Definition http_sse_wire_stream.cc:233
DescribeEndpointOptions describe
Server-side: GET /actions, when something above filled in the handler.
Definition http_sse_wire_stream.h:145
std::string connect_endpoint_prefix
Server-side: also accept a connect POST anywhere under this prefix.
Definition http_sse_wire_stream.h:138
SseOutboundDelivery outbound
Client-side outbound delivery method; servers accept either.
Definition http_sse_wire_stream.h:142
std::string connect_endpoint
SSE connect POST path.
Definition http_sse_wire_stream.h:127
Http2Options http2_options
Shared HTTP/2 transport and TLS policy.
Definition http_sse_wire_stream.h:126
size_t max_concurrent_posts
Outbound POSTs a client keeps in flight at once (kPost only).
Definition http_sse_wire_stream.h:157
bool accept_streamed_outbound
Server-side: whether a streamed outbound request body is accepted, and so advertised in kSseOutboundM...
Definition http_sse_wire_stream.h:153
Definition http_sse_wire_stream.cc:1131
Definition http_sse_wire_stream.cc:1228
The response-header policy of one A11 HTTP surface.
Definition server_headers.h:90
Buffering, sizing, and deadline limits for a WireStream endpoint.
Definition wire_stream.h:58
A11's core wire value types: chunks, node fragments and messages.
A11's transport abstraction: the bidirectional WireStream channel and the options/callbacks that driv...