Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/kj/compat/http.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // Copyright (c) 2017 Sandstorm Development Group, Inc. and contributors
jpayne@69 2 // Licensed under the MIT License:
jpayne@69 3 //
jpayne@69 4 // Permission is hereby granted, free of charge, to any person obtaining a copy
jpayne@69 5 // of this software and associated documentation files (the "Software"), to deal
jpayne@69 6 // in the Software without restriction, including without limitation the rights
jpayne@69 7 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
jpayne@69 8 // copies of the Software, and to permit persons to whom the Software is
jpayne@69 9 // furnished to do so, subject to the following conditions:
jpayne@69 10 //
jpayne@69 11 // The above copyright notice and this permission notice shall be included in
jpayne@69 12 // all copies or substantial portions of the Software.
jpayne@69 13 //
jpayne@69 14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
jpayne@69 15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
jpayne@69 16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
jpayne@69 17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
jpayne@69 18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
jpayne@69 19 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
jpayne@69 20 // THE SOFTWARE.
jpayne@69 21
jpayne@69 22 #pragma once
jpayne@69 23 // The KJ HTTP client/server library.
jpayne@69 24 //
jpayne@69 25 // This is a simple library which can be used to implement an HTTP client or server. Properties
jpayne@69 26 // of this library include:
jpayne@69 27 // - Uses KJ async framework.
jpayne@69 28 // - Agnostic to transport layer -- you can provide your own.
jpayne@69 29 // - Header parsing is zero-copy -- it results in strings that point directly into the buffer
jpayne@69 30 // received off the wire.
jpayne@69 31 // - Application code which reads and writes headers refers to headers by symbolic names, not by
jpayne@69 32 // string literals, with lookups being array-index-based, not map-based. To make this possible,
jpayne@69 33 // the application announces what headers it cares about in advance, in order to assign numeric
jpayne@69 34 // values to them.
jpayne@69 35 // - Methods are identified by an enum.
jpayne@69 36
jpayne@69 37 #include <kj/string.h>
jpayne@69 38 #include <kj/vector.h>
jpayne@69 39 #include <kj/memory.h>
jpayne@69 40 #include <kj/one-of.h>
jpayne@69 41 #include <kj/async-io.h>
jpayne@69 42 #include <kj/debug.h>
jpayne@69 43
jpayne@69 44 KJ_BEGIN_HEADER
jpayne@69 45
jpayne@69 46 namespace kj {
jpayne@69 47
jpayne@69 48 #define KJ_HTTP_FOR_EACH_METHOD(MACRO) \
jpayne@69 49 MACRO(GET) \
jpayne@69 50 MACRO(HEAD) \
jpayne@69 51 MACRO(POST) \
jpayne@69 52 MACRO(PUT) \
jpayne@69 53 MACRO(DELETE) \
jpayne@69 54 MACRO(PATCH) \
jpayne@69 55 MACRO(PURGE) \
jpayne@69 56 MACRO(OPTIONS) \
jpayne@69 57 MACRO(TRACE) \
jpayne@69 58 /* standard methods */ \
jpayne@69 59 /* */ \
jpayne@69 60 /* (CONNECT is intentionally omitted since it should be handled specially in HttpServer) */ \
jpayne@69 61 \
jpayne@69 62 MACRO(COPY) \
jpayne@69 63 MACRO(LOCK) \
jpayne@69 64 MACRO(MKCOL) \
jpayne@69 65 MACRO(MOVE) \
jpayne@69 66 MACRO(PROPFIND) \
jpayne@69 67 MACRO(PROPPATCH) \
jpayne@69 68 MACRO(SEARCH) \
jpayne@69 69 MACRO(UNLOCK) \
jpayne@69 70 MACRO(ACL) \
jpayne@69 71 /* WebDAV */ \
jpayne@69 72 \
jpayne@69 73 MACRO(REPORT) \
jpayne@69 74 MACRO(MKACTIVITY) \
jpayne@69 75 MACRO(CHECKOUT) \
jpayne@69 76 MACRO(MERGE) \
jpayne@69 77 /* Subversion */ \
jpayne@69 78 \
jpayne@69 79 MACRO(MSEARCH) \
jpayne@69 80 MACRO(NOTIFY) \
jpayne@69 81 MACRO(SUBSCRIBE) \
jpayne@69 82 MACRO(UNSUBSCRIBE)
jpayne@69 83 /* UPnP */
jpayne@69 84
jpayne@69 85 enum class HttpMethod {
jpayne@69 86 // Enum of known HTTP methods.
jpayne@69 87 //
jpayne@69 88 // We use an enum rather than a string to allow for faster parsing and switching and to reduce
jpayne@69 89 // ambiguity.
jpayne@69 90
jpayne@69 91 #define DECLARE_METHOD(id) id,
jpayne@69 92 KJ_HTTP_FOR_EACH_METHOD(DECLARE_METHOD)
jpayne@69 93 #undef DECLARE_METHOD
jpayne@69 94 };
jpayne@69 95
jpayne@69 96 struct HttpConnectMethod {};
jpayne@69 97 // CONNECT is handled specially and separately from the other HttpMethods.
jpayne@69 98
jpayne@69 99 kj::StringPtr KJ_STRINGIFY(HttpMethod method);
jpayne@69 100 kj::StringPtr KJ_STRINGIFY(HttpConnectMethod method);
jpayne@69 101 kj::Maybe<HttpMethod> tryParseHttpMethod(kj::StringPtr name);
jpayne@69 102 kj::Maybe<kj::OneOf<HttpMethod, HttpConnectMethod>> tryParseHttpMethodAllowingConnect(
jpayne@69 103 kj::StringPtr name);
jpayne@69 104 // Like tryParseHttpMethod but, as the name suggests, explicitly allows for the CONNECT
jpayne@69 105 // method. Added as a separate function instead of modifying tryParseHttpMethod to avoid
jpayne@69 106 // breaking API changes in existing uses of tryParseHttpMethod.
jpayne@69 107
jpayne@69 108 class HttpHeaderTable;
jpayne@69 109
jpayne@69 110 class HttpHeaderId {
jpayne@69 111 // Identifies an HTTP header by numeric ID that indexes into an HttpHeaderTable.
jpayne@69 112 //
jpayne@69 113 // The KJ HTTP API prefers that headers be identified by these IDs for a few reasons:
jpayne@69 114 // - Integer lookups are much more efficient than string lookups.
jpayne@69 115 // - Case-insensitivity is awkward to deal with when const strings are being passed to the lookup
jpayne@69 116 // method.
jpayne@69 117 // - Writing out strings less often means fewer typos.
jpayne@69 118 //
jpayne@69 119 // See HttpHeaderTable for usage hints.
jpayne@69 120
jpayne@69 121 public:
jpayne@69 122 HttpHeaderId() = default;
jpayne@69 123
jpayne@69 124 inline bool operator==(const HttpHeaderId& other) const { return id == other.id; }
jpayne@69 125 inline bool operator!=(const HttpHeaderId& other) const { return id != other.id; }
jpayne@69 126 inline bool operator< (const HttpHeaderId& other) const { return id < other.id; }
jpayne@69 127 inline bool operator> (const HttpHeaderId& other) const { return id > other.id; }
jpayne@69 128 inline bool operator<=(const HttpHeaderId& other) const { return id <= other.id; }
jpayne@69 129 inline bool operator>=(const HttpHeaderId& other) const { return id >= other.id; }
jpayne@69 130
jpayne@69 131 inline size_t hashCode() const { return id; }
jpayne@69 132 // Returned value is guaranteed to be small and never collide with other headers on the same
jpayne@69 133 // table.
jpayne@69 134
jpayne@69 135 kj::StringPtr toString() const;
jpayne@69 136
jpayne@69 137 void requireFrom(const HttpHeaderTable& table) const;
jpayne@69 138 // In debug mode, throws an exception if the HttpHeaderId is not from the given table.
jpayne@69 139 //
jpayne@69 140 // In opt mode, no-op.
jpayne@69 141
jpayne@69 142 #define KJ_HTTP_FOR_EACH_BUILTIN_HEADER(MACRO) \
jpayne@69 143 /* Headers that are always read-only. */ \
jpayne@69 144 MACRO(CONNECTION, "Connection") \
jpayne@69 145 MACRO(KEEP_ALIVE, "Keep-Alive") \
jpayne@69 146 MACRO(TE, "TE") \
jpayne@69 147 MACRO(TRAILER, "Trailer") \
jpayne@69 148 MACRO(UPGRADE, "Upgrade") \
jpayne@69 149 \
jpayne@69 150 /* Headers that are read-only except in the case of a response to a HEAD request. */ \
jpayne@69 151 MACRO(CONTENT_LENGTH, "Content-Length") \
jpayne@69 152 MACRO(TRANSFER_ENCODING, "Transfer-Encoding") \
jpayne@69 153 \
jpayne@69 154 /* Headers that are read-only for WebSocket handshakes. */ \
jpayne@69 155 MACRO(SEC_WEBSOCKET_KEY, "Sec-WebSocket-Key") \
jpayne@69 156 MACRO(SEC_WEBSOCKET_VERSION, "Sec-WebSocket-Version") \
jpayne@69 157 MACRO(SEC_WEBSOCKET_ACCEPT, "Sec-WebSocket-Accept") \
jpayne@69 158 MACRO(SEC_WEBSOCKET_EXTENSIONS, "Sec-WebSocket-Extensions") \
jpayne@69 159 \
jpayne@69 160 /* Headers that you can write. */ \
jpayne@69 161 MACRO(HOST, "Host") \
jpayne@69 162 MACRO(DATE, "Date") \
jpayne@69 163 MACRO(LOCATION, "Location") \
jpayne@69 164 MACRO(CONTENT_TYPE, "Content-Type")
jpayne@69 165 // For convenience, these headers are valid for all HttpHeaderTables. You can refer to them like:
jpayne@69 166 //
jpayne@69 167 // HttpHeaderId::HOST
jpayne@69 168 //
jpayne@69 169 // TODO(someday): Fill this out with more common headers.
jpayne@69 170
jpayne@69 171 #define DECLARE_HEADER(id, name) \
jpayne@69 172 static const HttpHeaderId id;
jpayne@69 173 // Declare a constant for each builtin header, e.g.: HttpHeaderId::CONNECTION
jpayne@69 174
jpayne@69 175 KJ_HTTP_FOR_EACH_BUILTIN_HEADER(DECLARE_HEADER);
jpayne@69 176 #undef DECLARE_HEADER
jpayne@69 177
jpayne@69 178 private:
jpayne@69 179 const HttpHeaderTable* table;
jpayne@69 180 uint id;
jpayne@69 181
jpayne@69 182 inline explicit constexpr HttpHeaderId(const HttpHeaderTable* table, uint id)
jpayne@69 183 : table(table), id(id) {}
jpayne@69 184 friend class HttpHeaderTable;
jpayne@69 185 friend class HttpHeaders;
jpayne@69 186 };
jpayne@69 187
jpayne@69 188 class HttpHeaderTable {
jpayne@69 189 // Construct an HttpHeaderTable to declare which headers you'll be interested in later on, and
jpayne@69 190 // to manufacture IDs for them.
jpayne@69 191 //
jpayne@69 192 // Example:
jpayne@69 193 //
jpayne@69 194 // // Build a header table with the headers we are interested in.
jpayne@69 195 // kj::HttpHeaderTable::Builder builder;
jpayne@69 196 // const HttpHeaderId accept = builder.add("Accept");
jpayne@69 197 // const HttpHeaderId contentType = builder.add("Content-Type");
jpayne@69 198 // kj::HttpHeaderTable table(kj::mv(builder));
jpayne@69 199 //
jpayne@69 200 // // Create an HTTP client.
jpayne@69 201 // auto client = kj::newHttpClient(table, network);
jpayne@69 202 //
jpayne@69 203 // // Get http://example.com.
jpayne@69 204 // HttpHeaders headers(table);
jpayne@69 205 // headers.set(accept, "text/html");
jpayne@69 206 // auto response = client->send(kj::HttpMethod::GET, "http://example.com", headers)
jpayne@69 207 // .wait(waitScope);
jpayne@69 208 // auto msg = kj::str("Response content type: ", response.headers.get(contentType));
jpayne@69 209
jpayne@69 210 struct IdsByNameMap;
jpayne@69 211
jpayne@69 212 public:
jpayne@69 213 HttpHeaderTable();
jpayne@69 214 // Constructs a table that only contains the builtin headers.
jpayne@69 215
jpayne@69 216 class Builder {
jpayne@69 217 public:
jpayne@69 218 Builder();
jpayne@69 219 HttpHeaderId add(kj::StringPtr name);
jpayne@69 220 Own<HttpHeaderTable> build();
jpayne@69 221
jpayne@69 222 HttpHeaderTable& getFutureTable();
jpayne@69 223 // Get the still-unbuilt header table. You cannot actually use it until build() has been
jpayne@69 224 // called.
jpayne@69 225 //
jpayne@69 226 // This method exists to help when building a shared header table -- the Builder may be passed
jpayne@69 227 // to several components, each of which will register the headers they need and get a reference
jpayne@69 228 // to the future table.
jpayne@69 229
jpayne@69 230 private:
jpayne@69 231 kj::Own<HttpHeaderTable> table;
jpayne@69 232 };
jpayne@69 233
jpayne@69 234 KJ_DISALLOW_COPY_AND_MOVE(HttpHeaderTable); // Can't copy because HttpHeaderId points to the table.
jpayne@69 235 ~HttpHeaderTable() noexcept(false);
jpayne@69 236
jpayne@69 237 uint idCount() const;
jpayne@69 238 // Return the number of IDs in the table.
jpayne@69 239
jpayne@69 240 kj::Maybe<HttpHeaderId> stringToId(kj::StringPtr name) const;
jpayne@69 241 // Try to find an ID for the given name. The matching is case-insensitive, per the HTTP spec.
jpayne@69 242 //
jpayne@69 243 // Note: if `name` contains characters that aren't allowed in HTTP header names, this may return
jpayne@69 244 // a bogus value rather than null, due to optimizations used in case-insensitive matching.
jpayne@69 245
jpayne@69 246 kj::StringPtr idToString(HttpHeaderId id) const;
jpayne@69 247 // Get the canonical string name for the given ID.
jpayne@69 248
jpayne@69 249 bool isReady() const;
jpayne@69 250 // Returns true if this HttpHeaderTable either was default constructed or its Builder has
jpayne@69 251 // invoked `build()` and released it.
jpayne@69 252
jpayne@69 253 private:
jpayne@69 254 kj::Vector<kj::StringPtr> namesById;
jpayne@69 255 kj::Own<IdsByNameMap> idsByName;
jpayne@69 256
jpayne@69 257 enum class BuildStatus {
jpayne@69 258 UNSTARTED = 0,
jpayne@69 259 BUILDING = 1,
jpayne@69 260 FINISHED = 2,
jpayne@69 261 };
jpayne@69 262 BuildStatus buildStatus = BuildStatus::UNSTARTED;
jpayne@69 263 };
jpayne@69 264
jpayne@69 265 class HttpHeaders {
jpayne@69 266 // Represents a set of HTTP headers.
jpayne@69 267 //
jpayne@69 268 // This class guards against basic HTTP header injection attacks: Trying to set a header name or
jpayne@69 269 // value containing a newline, carriage return, or other invalid character will throw an
jpayne@69 270 // exception.
jpayne@69 271
jpayne@69 272 public:
jpayne@69 273 explicit HttpHeaders(const HttpHeaderTable& table);
jpayne@69 274
jpayne@69 275 static bool isValidHeaderValue(kj::StringPtr value);
jpayne@69 276 // This returns whether the value is a valid parameter to the set call. While the HTTP spec
jpayne@69 277 // suggests that only printable ASCII characters are allowed in header values, in practice that
jpayne@69 278 // turns out to not be the case. We follow the browser's lead in disallowing \r and \n.
jpayne@69 279 // https://github.com/httpwg/http11bis/issues/19
jpayne@69 280 // Use this if you want to validate the value before supplying it to set() if you want to avoid
jpayne@69 281 // an exception being thrown (e.g. you have custom error reporting). NOTE that set will still
jpayne@69 282 // validate the value. If performance is a problem this API needs to be adjusted to a
jpayne@69 283 // `validateHeaderValue` function that returns a special type that set can be confident has
jpayne@69 284 // already passed through the validation routine.
jpayne@69 285
jpayne@69 286 KJ_DISALLOW_COPY(HttpHeaders);
jpayne@69 287 HttpHeaders(HttpHeaders&&) = default;
jpayne@69 288 HttpHeaders& operator=(HttpHeaders&&) = default;
jpayne@69 289
jpayne@69 290 size_t size() const;
jpayne@69 291 // Returns the number of headers that forEach() would iterate over.
jpayne@69 292
jpayne@69 293 void clear();
jpayne@69 294 // Clears all contents, as if the object was freshly-allocated. However, calling this rather
jpayne@69 295 // than actually re-allocating the object may avoid re-allocation of internal objects.
jpayne@69 296
jpayne@69 297 HttpHeaders clone() const;
jpayne@69 298 // Creates a deep clone of the HttpHeaders. The returned object owns all strings it references.
jpayne@69 299
jpayne@69 300 HttpHeaders cloneShallow() const;
jpayne@69 301 // Creates a shallow clone of the HttpHeaders. The returned object references the same strings
jpayne@69 302 // as the original, owning none of them.
jpayne@69 303
jpayne@69 304 bool isWebSocket() const;
jpayne@69 305 // Convenience method that checks for the presence of the header `Upgrade: websocket`.
jpayne@69 306 //
jpayne@69 307 // Note that this does not actually validate that the request is a complete WebSocket handshake
jpayne@69 308 // with the correct version number -- such validation will occur if and when you call
jpayne@69 309 // acceptWebSocket().
jpayne@69 310
jpayne@69 311 kj::Maybe<kj::StringPtr> get(HttpHeaderId id) const;
jpayne@69 312 // Read a header.
jpayne@69 313 //
jpayne@69 314 // Note that there is intentionally no method to look up a header by string name rather than
jpayne@69 315 // header ID. The intent is that you should always allocate a header ID for any header that you
jpayne@69 316 // care about, so that you can get() it by ID. Headers with registered IDs are stored in an array
jpayne@69 317 // indexed by ID, making lookup fast. Headers without registered IDs are stored in a separate list
jpayne@69 318 // that is optimized for re-transmission of the whole list, but not for lookup.
jpayne@69 319
jpayne@69 320 template <typename Func>
jpayne@69 321 void forEach(Func&& func) const;
jpayne@69 322 // Calls `func(name, value)` for each header in the set -- including headers that aren't mapped
jpayne@69 323 // to IDs in the header table. Both inputs are of type kj::StringPtr.
jpayne@69 324
jpayne@69 325 template <typename Func1, typename Func2>
jpayne@69 326 void forEach(Func1&& func1, Func2&& func2) const;
jpayne@69 327 // Calls `func1(id, value)` for each header in the set that has a registered HttpHeaderId, and
jpayne@69 328 // `func2(name, value)` for each header that does not. All calls to func1() precede all calls to
jpayne@69 329 // func2().
jpayne@69 330
jpayne@69 331 void set(HttpHeaderId id, kj::StringPtr value);
jpayne@69 332 void set(HttpHeaderId id, kj::String&& value);
jpayne@69 333 // Sets a header value, overwriting the existing value.
jpayne@69 334 //
jpayne@69 335 // The String&& version is equivalent to calling the other version followed by takeOwnership().
jpayne@69 336 //
jpayne@69 337 // WARNING: It is the caller's responsibility to ensure that `value` remains valid until the
jpayne@69 338 // HttpHeaders object is destroyed. This allows string literals to be passed without making a
jpayne@69 339 // copy, but complicates the use of dynamic values. Hint: Consider using `takeOwnership()`.
jpayne@69 340
jpayne@69 341 void add(kj::StringPtr name, kj::StringPtr value);
jpayne@69 342 void add(kj::StringPtr name, kj::String&& value);
jpayne@69 343 void add(kj::String&& name, kj::String&& value);
jpayne@69 344 // Append a header. `name` will be looked up in the header table, but if it's not mapped, the
jpayne@69 345 // header will be added to the list of unmapped headers.
jpayne@69 346 //
jpayne@69 347 // The String&& versions are equivalent to calling the other version followed by takeOwnership().
jpayne@69 348 //
jpayne@69 349 // WARNING: It is the caller's responsibility to ensure that `name` and `value` remain valid
jpayne@69 350 // until the HttpHeaders object is destroyed. This allows string literals to be passed without
jpayne@69 351 // making a copy, but complicates the use of dynamic values. Hint: Consider using
jpayne@69 352 // `takeOwnership()`.
jpayne@69 353
jpayne@69 354 void unset(HttpHeaderId id);
jpayne@69 355 // Removes a header.
jpayne@69 356 //
jpayne@69 357 // It's not possible to remove a header by string name because non-indexed headers would take
jpayne@69 358 // O(n) time to remove. Instead, construct a new HttpHeaders object and copy contents.
jpayne@69 359
jpayne@69 360 void takeOwnership(kj::String&& string);
jpayne@69 361 void takeOwnership(kj::Array<char>&& chars);
jpayne@69 362 void takeOwnership(HttpHeaders&& otherHeaders);
jpayne@69 363 // Takes ownership of a string so that it lives until the HttpHeaders object is destroyed. Useful
jpayne@69 364 // when you've passed a dynamic value to set() or add() or parse*().
jpayne@69 365
jpayne@69 366 struct Request {
jpayne@69 367 HttpMethod method;
jpayne@69 368 kj::StringPtr url;
jpayne@69 369 };
jpayne@69 370 struct ConnectRequest {
jpayne@69 371 kj::StringPtr authority;
jpayne@69 372 };
jpayne@69 373 struct Response {
jpayne@69 374 uint statusCode;
jpayne@69 375 kj::StringPtr statusText;
jpayne@69 376 };
jpayne@69 377
jpayne@69 378 struct ProtocolError {
jpayne@69 379 // Represents a protocol error, such as a bad request method or invalid headers. Debugging such
jpayne@69 380 // errors is difficult without a copy of the data which we tried to parse, but this data is
jpayne@69 381 // sensitive, so we can't just lump it into the error description directly. ProtocolError
jpayne@69 382 // provides this sensitive data separate from the error description.
jpayne@69 383 //
jpayne@69 384 // TODO(cleanup): Should maybe not live in HttpHeaders? HttpServerErrorHandler::ProtocolError?
jpayne@69 385 // Or HttpProtocolError? Or maybe we need a more general way of attaching sensitive context to
jpayne@69 386 // kj::Exceptions?
jpayne@69 387
jpayne@69 388 uint statusCode;
jpayne@69 389 // Suggested HTTP status code that should be used when returning an error to the client.
jpayne@69 390 //
jpayne@69 391 // Most errors are 400. An unrecognized method will be 501.
jpayne@69 392
jpayne@69 393 kj::StringPtr statusMessage;
jpayne@69 394 // HTTP status message to go with `statusCode`, e.g. "Bad Request".
jpayne@69 395
jpayne@69 396 kj::StringPtr description;
jpayne@69 397 // An error description safe for all the world to see.
jpayne@69 398
jpayne@69 399 kj::ArrayPtr<char> rawContent;
jpayne@69 400 // Unredacted data which led to the error condition. This may contain anything transported over
jpayne@69 401 // HTTP, to include sensitive PII, so you must take care to sanitize this before using it in any
jpayne@69 402 // error report that may leak to unprivileged eyes.
jpayne@69 403 //
jpayne@69 404 // This ArrayPtr is merely a copy of the `content` parameter passed to `tryParseRequest()` /
jpayne@69 405 // `tryParseResponse()`, thus it remains valid for as long as a successfully-parsed HttpHeaders
jpayne@69 406 // object would remain valid.
jpayne@69 407 };
jpayne@69 408
jpayne@69 409 using RequestOrProtocolError = kj::OneOf<Request, ProtocolError>;
jpayne@69 410 using ResponseOrProtocolError = kj::OneOf<Response, ProtocolError>;
jpayne@69 411 using RequestConnectOrProtocolError = kj::OneOf<Request, ConnectRequest, ProtocolError>;
jpayne@69 412
jpayne@69 413 RequestOrProtocolError tryParseRequest(kj::ArrayPtr<char> content);
jpayne@69 414 RequestConnectOrProtocolError tryParseRequestOrConnect(kj::ArrayPtr<char> content);
jpayne@69 415 ResponseOrProtocolError tryParseResponse(kj::ArrayPtr<char> content);
jpayne@69 416
jpayne@69 417 // Parse an HTTP header blob and add all the headers to this object.
jpayne@69 418 //
jpayne@69 419 // `content` should be all text from the start of the request to the first occurrence of two
jpayne@69 420 // newlines in a row -- including the first of these two newlines, but excluding the second.
jpayne@69 421 //
jpayne@69 422 // The parse is performed with zero copies: The callee clobbers `content` with '\0' characters
jpayne@69 423 // to split it into a bunch of shorter strings. The caller must keep `content` valid until the
jpayne@69 424 // `HttpHeaders` is destroyed, or pass it to `takeOwnership()`.
jpayne@69 425
jpayne@69 426 bool tryParse(kj::ArrayPtr<char> content);
jpayne@69 427 // Like tryParseRequest()/tryParseResponse(), but don't expect any request/response line.
jpayne@69 428
jpayne@69 429 kj::String serializeRequest(HttpMethod method, kj::StringPtr url,
jpayne@69 430 kj::ArrayPtr<const kj::StringPtr> connectionHeaders = nullptr) const;
jpayne@69 431 kj::String serializeConnectRequest(kj::StringPtr authority,
jpayne@69 432 kj::ArrayPtr<const kj::StringPtr> connectionHeaders = nullptr) const;
jpayne@69 433 kj::String serializeResponse(uint statusCode, kj::StringPtr statusText,
jpayne@69 434 kj::ArrayPtr<const kj::StringPtr> connectionHeaders = nullptr) const;
jpayne@69 435 // **Most applications will not use these methods; they are called by the HTTP client and server
jpayne@69 436 // implementations.**
jpayne@69 437 //
jpayne@69 438 // Serialize the headers as a complete request or response blob. The blob uses '\r\n' newlines
jpayne@69 439 // and includes the double-newline to indicate the end of the headers.
jpayne@69 440 //
jpayne@69 441 // `connectionHeaders`, if provided, contains connection-level headers supplied by the HTTP
jpayne@69 442 // implementation, in the order specified by the KJ_HTTP_FOR_EACH_BUILTIN_HEADER macro. These
jpayne@69 443 // headers values override any corresponding header value in the HttpHeaders object. The
jpayne@69 444 // CONNECTION_HEADERS_COUNT constants below can help you construct this `connectionHeaders` array.
jpayne@69 445
jpayne@69 446 enum class BuiltinIndicesEnum {
jpayne@69 447 #define HEADER_ID(id, name) id,
jpayne@69 448 KJ_HTTP_FOR_EACH_BUILTIN_HEADER(HEADER_ID)
jpayne@69 449 #undef HEADER_ID
jpayne@69 450 };
jpayne@69 451
jpayne@69 452 struct BuiltinIndices {
jpayne@69 453 #define HEADER_ID(id, name) static constexpr uint id = static_cast<uint>(BuiltinIndicesEnum::id);
jpayne@69 454 KJ_HTTP_FOR_EACH_BUILTIN_HEADER(HEADER_ID)
jpayne@69 455 #undef HEADER_ID
jpayne@69 456 };
jpayne@69 457
jpayne@69 458 static constexpr uint HEAD_RESPONSE_CONNECTION_HEADERS_COUNT = BuiltinIndices::CONTENT_LENGTH;
jpayne@69 459 static constexpr uint CONNECTION_HEADERS_COUNT = BuiltinIndices::SEC_WEBSOCKET_KEY;
jpayne@69 460 static constexpr uint WEBSOCKET_CONNECTION_HEADERS_COUNT = BuiltinIndices::HOST;
jpayne@69 461 // Constants for use with HttpHeaders::serialize*().
jpayne@69 462
jpayne@69 463 kj::String toString() const;
jpayne@69 464
jpayne@69 465 private:
jpayne@69 466 const HttpHeaderTable* table;
jpayne@69 467
jpayne@69 468 kj::Array<kj::StringPtr> indexedHeaders;
jpayne@69 469 // Size is always table->idCount().
jpayne@69 470
jpayne@69 471 struct Header {
jpayne@69 472 kj::StringPtr name;
jpayne@69 473 kj::StringPtr value;
jpayne@69 474 };
jpayne@69 475 kj::Vector<Header> unindexedHeaders;
jpayne@69 476
jpayne@69 477 kj::Vector<kj::Array<char>> ownedStrings;
jpayne@69 478
jpayne@69 479 void addNoCheck(kj::StringPtr name, kj::StringPtr value);
jpayne@69 480
jpayne@69 481 kj::StringPtr cloneToOwn(kj::StringPtr str);
jpayne@69 482
jpayne@69 483 kj::String serialize(kj::ArrayPtr<const char> word1,
jpayne@69 484 kj::ArrayPtr<const char> word2,
jpayne@69 485 kj::ArrayPtr<const char> word3,
jpayne@69 486 kj::ArrayPtr<const kj::StringPtr> connectionHeaders) const;
jpayne@69 487
jpayne@69 488 bool parseHeaders(char* ptr, char* end);
jpayne@69 489
jpayne@69 490 // TODO(perf): Arguably we should store a map, but header sets are never very long
jpayne@69 491 // TODO(perf): We could optimize for common headers by storing them directly as fields. We could
jpayne@69 492 // also add direct accessors for those headers.
jpayne@69 493 };
jpayne@69 494
jpayne@69 495 class HttpInputStream {
jpayne@69 496 // Low-level interface to receive HTTP-formatted messages (headers followed by body) from an
jpayne@69 497 // input stream, without a paired output stream.
jpayne@69 498 //
jpayne@69 499 // Most applications will not use this. Regular HTTP clients and servers don't need this. This
jpayne@69 500 // is mainly useful for apps implementing various protocols that look like HTTP but aren't
jpayne@69 501 // really.
jpayne@69 502
jpayne@69 503 public:
jpayne@69 504 struct Request {
jpayne@69 505 HttpMethod method;
jpayne@69 506 kj::StringPtr url;
jpayne@69 507 const HttpHeaders& headers;
jpayne@69 508 kj::Own<kj::AsyncInputStream> body;
jpayne@69 509 };
jpayne@69 510 virtual kj::Promise<Request> readRequest() = 0;
jpayne@69 511 // Reads one HTTP request from the input stream.
jpayne@69 512 //
jpayne@69 513 // The returned struct contains pointers directly into a buffer that is invalidated on the next
jpayne@69 514 // message read.
jpayne@69 515
jpayne@69 516 struct Connect {
jpayne@69 517 kj::StringPtr authority;
jpayne@69 518 const HttpHeaders& headers;
jpayne@69 519 kj::Own<kj::AsyncInputStream> body;
jpayne@69 520 };
jpayne@69 521 virtual kj::Promise<kj::OneOf<Request, Connect>> readRequestAllowingConnect() = 0;
jpayne@69 522 // Reads one HTTP request from the input stream.
jpayne@69 523 //
jpayne@69 524 // The returned struct contains pointers directly into a buffer that is invalidated on the next
jpayne@69 525 // message read.
jpayne@69 526
jpayne@69 527 struct Response {
jpayne@69 528 uint statusCode;
jpayne@69 529 kj::StringPtr statusText;
jpayne@69 530 const HttpHeaders& headers;
jpayne@69 531 kj::Own<kj::AsyncInputStream> body;
jpayne@69 532 };
jpayne@69 533 virtual kj::Promise<Response> readResponse(HttpMethod requestMethod) = 0;
jpayne@69 534 // Reads one HTTP response from the input stream.
jpayne@69 535 //
jpayne@69 536 // You must provide the request method because responses to HEAD requests require special
jpayne@69 537 // treatment.
jpayne@69 538 //
jpayne@69 539 // The returned struct contains pointers directly into a buffer that is invalidated on the next
jpayne@69 540 // message read.
jpayne@69 541
jpayne@69 542 struct Message {
jpayne@69 543 const HttpHeaders& headers;
jpayne@69 544 kj::Own<kj::AsyncInputStream> body;
jpayne@69 545 };
jpayne@69 546 virtual kj::Promise<Message> readMessage() = 0;
jpayne@69 547 // Reads an HTTP header set followed by a body, with no request or response line. This is not
jpayne@69 548 // useful for HTTP but may be useful for other protocols that make the unfortunate choice to
jpayne@69 549 // mimic HTTP message format, such as Visual Studio Code's JSON-RPC transport.
jpayne@69 550 //
jpayne@69 551 // The returned struct contains pointers directly into a buffer that is invalidated on the next
jpayne@69 552 // message read.
jpayne@69 553
jpayne@69 554 virtual kj::Promise<bool> awaitNextMessage() = 0;
jpayne@69 555 // Waits until more data is available, but doesn't consume it. Returns false on EOF.
jpayne@69 556 };
jpayne@69 557
jpayne@69 558 class EntropySource {
jpayne@69 559 // Interface for an object that generates entropy. Typically, cryptographically-random entropy
jpayne@69 560 // is expected.
jpayne@69 561 //
jpayne@69 562 // TODO(cleanup): Put this somewhere more general.
jpayne@69 563
jpayne@69 564 public:
jpayne@69 565 virtual void generate(kj::ArrayPtr<byte> buffer) = 0;
jpayne@69 566 };
jpayne@69 567
jpayne@69 568 struct CompressionParameters {
jpayne@69 569 // These are the parameters for `Sec-WebSocket-Extensions` permessage-deflate extension.
jpayne@69 570 // Since we cannot distinguish the client/server in `upgradeToWebSocket`, we use the prefixes
jpayne@69 571 // `inbound` and `outbound` instead.
jpayne@69 572 bool outboundNoContextTakeover = false;
jpayne@69 573 bool inboundNoContextTakeover = false;
jpayne@69 574 kj::Maybe<size_t> outboundMaxWindowBits = nullptr;
jpayne@69 575 kj::Maybe<size_t> inboundMaxWindowBits = nullptr;
jpayne@69 576 };
jpayne@69 577
jpayne@69 578 class WebSocket {
jpayne@69 579 // Interface representincg an open WebSocket session.
jpayne@69 580 //
jpayne@69 581 // Each side can send and receive data and "close" messages.
jpayne@69 582 //
jpayne@69 583 // Ping/Pong and message fragmentation are not exposed through this interface. These features of
jpayne@69 584 // the underlying WebSocket protocol are not exposed by the browser-level JavaScript API either,
jpayne@69 585 // and thus applications typically need to implement these features at the application protocol
jpayne@69 586 // level instead. The implementation is, however, expected to reply to Ping messages it receives.
jpayne@69 587
jpayne@69 588 public:
jpayne@69 589 virtual kj::Promise<void> send(kj::ArrayPtr<const byte> message) = 0;
jpayne@69 590 virtual kj::Promise<void> send(kj::ArrayPtr<const char> message) = 0;
jpayne@69 591 // Send a message (binary or text). The underlying buffer must remain valid, and you must not
jpayne@69 592 // call send() again, until the returned promise resolves.
jpayne@69 593
jpayne@69 594 virtual kj::Promise<void> close(uint16_t code, kj::StringPtr reason) = 0;
jpayne@69 595 // Send a Close message.
jpayne@69 596 //
jpayne@69 597 // Note that the returned Promise resolves once the message has been sent -- it does NOT wait
jpayne@69 598 // for the other end to send a Close reply. The application should await a reply before dropping
jpayne@69 599 // the WebSocket object.
jpayne@69 600
jpayne@69 601 virtual kj::Promise<void> disconnect() = 0;
jpayne@69 602 // Sends EOF on the underlying connection without sending a "close" message. This is NOT a clean
jpayne@69 603 // shutdown, but is sometimes useful when you want the other end to trigger whatever behavior
jpayne@69 604 // it normally triggers when a connection is dropped.
jpayne@69 605
jpayne@69 606 virtual void abort() = 0;
jpayne@69 607 // Forcefully close this WebSocket, such that the remote end should get a DISCONNECTED error if
jpayne@69 608 // it continues to write. This differs from disconnect(), which only closes the sending
jpayne@69 609 // direction, but still allows receives.
jpayne@69 610
jpayne@69 611 virtual kj::Promise<void> whenAborted() = 0;
jpayne@69 612 // Resolves when the remote side aborts the connection such that send() would throw DISCONNECTED,
jpayne@69 613 // if this can be detected without actually writing a message. (If not, this promise never
jpayne@69 614 // resolves, but send() or receive() will throw DISCONNECTED when appropriate. See also
jpayne@69 615 // kj::AsyncOutputStream::whenWriteDisconnected().)
jpayne@69 616
jpayne@69 617 struct ProtocolError {
jpayne@69 618 // Represents a protocol error, such as a bad opcode or oversize message.
jpayne@69 619
jpayne@69 620 uint statusCode;
jpayne@69 621 // Suggested WebSocket status code that should be used when returning an error to the client.
jpayne@69 622 //
jpayne@69 623 // Most errors are 1002; an oversize message will be 1009.
jpayne@69 624
jpayne@69 625 kj::StringPtr description;
jpayne@69 626 // An error description safe for all the world to see. This should be at most 123 bytes so that
jpayne@69 627 // it can be used as the body of a Close frame (RFC 6455 sections 5.5 and 5.5.1).
jpayne@69 628 };
jpayne@69 629
jpayne@69 630 struct Close {
jpayne@69 631 uint16_t code;
jpayne@69 632 kj::String reason;
jpayne@69 633 };
jpayne@69 634
jpayne@69 635 typedef kj::OneOf<kj::String, kj::Array<byte>, Close> Message;
jpayne@69 636
jpayne@69 637 static constexpr size_t SUGGESTED_MAX_MESSAGE_SIZE = 1u << 20; // 1MB
jpayne@69 638
jpayne@69 639 virtual kj::Promise<Message> receive(size_t maxSize = SUGGESTED_MAX_MESSAGE_SIZE) = 0;
jpayne@69 640 // Read one message from the WebSocket and return it. Can only call once at a time. Do not call
jpayne@69 641 // again after Close is received.
jpayne@69 642
jpayne@69 643 virtual kj::Promise<void> pumpTo(WebSocket& other);
jpayne@69 644 // Continuously receives messages from this WebSocket and send them to `other`.
jpayne@69 645 //
jpayne@69 646 // On EOF, calls other.disconnect(), then resolves.
jpayne@69 647 //
jpayne@69 648 // On other read errors, calls other.close() with the error, then resolves.
jpayne@69 649 //
jpayne@69 650 // On write error, rejects with the error.
jpayne@69 651
jpayne@69 652 virtual kj::Maybe<kj::Promise<void>> tryPumpFrom(WebSocket& other);
jpayne@69 653 // Either returns null, or performs the equivalent of other.pumpTo(*this). Only returns non-null
jpayne@69 654 // if this WebSocket implementation is able to perform the pump in an optimized way, better than
jpayne@69 655 // the default implementation of pumpTo(). The default implementation of pumpTo() always tries
jpayne@69 656 // calling this first, and the default implementation of tryPumpFrom() always returns null.
jpayne@69 657
jpayne@69 658 virtual uint64_t sentByteCount() = 0;
jpayne@69 659 virtual uint64_t receivedByteCount() = 0;
jpayne@69 660
jpayne@69 661 enum ExtensionsContext {
jpayne@69 662 // Indicate whether a Sec-WebSocket-Extension header should be rendered for use in request
jpayne@69 663 // headers or response headers.
jpayne@69 664 REQUEST,
jpayne@69 665 RESPONSE
jpayne@69 666 };
jpayne@69 667 virtual kj::Maybe<kj::String> getPreferredExtensions(ExtensionsContext ctx) { return nullptr; }
jpayne@69 668 // If pumpTo() / tryPumpFrom() is able to be optimized only if the other WebSocket is using
jpayne@69 669 // certain extensions (e.g. compression settings), then this method returns what those extensions
jpayne@69 670 // are. For example, matching extensions between standard WebSockets allows pumping to be
jpayne@69 671 // implemented by pumping raw bytes between network connections, without reading individual frames.
jpayne@69 672 //
jpayne@69 673 // A null return value indicates that there is no preference. A non-null return value containing
jpayne@69 674 // an empty string indicates a preference for no extensions to be applied.
jpayne@69 675 };
jpayne@69 676
jpayne@69 677 using TlsStarterCallback = kj::Maybe<kj::Function<kj::Promise<void>(kj::StringPtr)>>;
jpayne@69 678 struct HttpConnectSettings {
jpayne@69 679 bool useTls = false;
jpayne@69 680 // Requests to automatically establish a TLS session over the connection. The remote party
jpayne@69 681 // will be expected to present a valid certificate matching the requested hostname.
jpayne@69 682 kj::Maybe<TlsStarterCallback&> tlsStarter;
jpayne@69 683 // This is an output parameter. It doesn't need to be set. But if it is set, then it may get
jpayne@69 684 // filled with a callback function. It will get filled with `nullptr` if any of the following
jpayne@69 685 // are true:
jpayne@69 686 //
jpayne@69 687 // * kj is not built with TLS support
jpayne@69 688 // * the underlying HttpClient does not support the startTls mechanism
jpayne@69 689 // * `useTls` has been set to `true` and so TLS has already been started
jpayne@69 690 //
jpayne@69 691 // The callback function itself can be called to initiate a TLS handshake on the connection in
jpayne@69 692 // between write() operations. It is not allowed to initiate a TLS handshake while a write
jpayne@69 693 // operation or a pump operation to the connection exists. Read operations are not subject to
jpayne@69 694 // the same constraint, however: implementations are required to be able to handle TLS
jpayne@69 695 // initiation while a read operation or pump operation from the connection exists. Once the
jpayne@69 696 // promise returned from the callback is fulfilled, the connection has become a secure stream,
jpayne@69 697 // and write operations are once again permitted. The StringPtr parameter to the callback,
jpayne@69 698 // expectedServerHostname may be dropped after the function synchronously returns.
jpayne@69 699 //
jpayne@69 700 // The PausableReadAsyncIoStream class defined below can be used to ensure that read operations
jpayne@69 701 // are not pending when the tlsStarter is invoked.
jpayne@69 702 //
jpayne@69 703 // This mechanism is required for certain protocols, more info can be found on
jpayne@69 704 // https://en.wikipedia.org/wiki/Opportunistic_TLS.
jpayne@69 705 };
jpayne@69 706
jpayne@69 707
jpayne@69 708 class PausableReadAsyncIoStream final: public kj::AsyncIoStream {
jpayne@69 709 // A custom AsyncIoStream which can pause pending reads. This is used by startTls to pause a
jpayne@69 710 // a read before TLS is initiated.
jpayne@69 711 //
jpayne@69 712 // TODO(cleanup): this class should be rewritten to use a CRTP mixin approach so that pumps
jpayne@69 713 // can be optimised once startTls is invoked.
jpayne@69 714 class PausableRead;
jpayne@69 715 public:
jpayne@69 716 PausableReadAsyncIoStream(kj::Own<kj::AsyncIoStream> stream)
jpayne@69 717 : inner(kj::mv(stream)), currentlyWriting(false), currentlyReading(false) {}
jpayne@69 718
jpayne@69 719 _::Deferred<kj::Function<void()>> trackRead();
jpayne@69 720
jpayne@69 721 _::Deferred<kj::Function<void()>> trackWrite();
jpayne@69 722
jpayne@69 723 kj::Promise<size_t> tryRead(void* buffer, size_t minBytes, size_t maxBytes) override;
jpayne@69 724
jpayne@69 725 kj::Promise<size_t> tryReadImpl(void* buffer, size_t minBytes, size_t maxBytes);
jpayne@69 726
jpayne@69 727 kj::Maybe<uint64_t> tryGetLength() override;
jpayne@69 728
jpayne@69 729 kj::Promise<uint64_t> pumpTo(kj::AsyncOutputStream& output, uint64_t amount) override;
jpayne@69 730
jpayne@69 731 kj::Promise<void> write(const void* buffer, size_t size) override;
jpayne@69 732
jpayne@69 733 kj::Promise<void> write(kj::ArrayPtr<const kj::ArrayPtr<const byte>> pieces) override;
jpayne@69 734
jpayne@69 735 kj::Maybe<kj::Promise<uint64_t>> tryPumpFrom(
jpayne@69 736 kj::AsyncInputStream& input, uint64_t amount = kj::maxValue) override;
jpayne@69 737
jpayne@69 738 kj::Promise<void> whenWriteDisconnected() override;
jpayne@69 739
jpayne@69 740 void shutdownWrite() override;
jpayne@69 741
jpayne@69 742 void abortRead() override;
jpayne@69 743
jpayne@69 744 kj::Maybe<int> getFd() const override;
jpayne@69 745
jpayne@69 746 void pause();
jpayne@69 747
jpayne@69 748 void unpause();
jpayne@69 749
jpayne@69 750 bool getCurrentlyReading();
jpayne@69 751
jpayne@69 752 bool getCurrentlyWriting();
jpayne@69 753
jpayne@69 754 kj::Own<kj::AsyncIoStream> takeStream();
jpayne@69 755
jpayne@69 756 void replaceStream(kj::Own<kj::AsyncIoStream> stream);
jpayne@69 757
jpayne@69 758 void reject(kj::Exception&& exc);
jpayne@69 759
jpayne@69 760 private:
jpayne@69 761 kj::Own<kj::AsyncIoStream> inner;
jpayne@69 762 kj::Maybe<PausableRead&> maybePausableRead;
jpayne@69 763 bool currentlyWriting;
jpayne@69 764 bool currentlyReading;
jpayne@69 765 };
jpayne@69 766
jpayne@69 767 class HttpClient {
jpayne@69 768 // Interface to the client end of an HTTP connection.
jpayne@69 769 //
jpayne@69 770 // There are two kinds of clients:
jpayne@69 771 // * Host clients are used when talking to a specific host. The `url` specified in a request
jpayne@69 772 // is actually just a path. (A `Host` header is still required in all requests.)
jpayne@69 773 // * Proxy clients are used when the target could be any arbitrary host on the internet.
jpayne@69 774 // The `url` specified in a request is a full URL including protocol and hostname.
jpayne@69 775
jpayne@69 776 public:
jpayne@69 777 struct Response {
jpayne@69 778 uint statusCode;
jpayne@69 779 kj::StringPtr statusText;
jpayne@69 780 const HttpHeaders* headers;
jpayne@69 781 kj::Own<kj::AsyncInputStream> body;
jpayne@69 782 // `statusText` and `headers` remain valid until `body` is dropped or read from.
jpayne@69 783 };
jpayne@69 784
jpayne@69 785 struct Request {
jpayne@69 786 kj::Own<kj::AsyncOutputStream> body;
jpayne@69 787 // Write the request entity body to this stream, then drop it when done.
jpayne@69 788 //
jpayne@69 789 // May be null for GET and HEAD requests (which have no body) and requests that have
jpayne@69 790 // Content-Length: 0.
jpayne@69 791
jpayne@69 792 kj::Promise<Response> response;
jpayne@69 793 // Promise for the eventual response.
jpayne@69 794 };
jpayne@69 795
jpayne@69 796 virtual Request request(HttpMethod method, kj::StringPtr url, const HttpHeaders& headers,
jpayne@69 797 kj::Maybe<uint64_t> expectedBodySize = nullptr) = 0;
jpayne@69 798 // Perform an HTTP request.
jpayne@69 799 //
jpayne@69 800 // `url` may be a full URL (with protocol and host) or it may be only the path part of the URL,
jpayne@69 801 // depending on whether the client is a proxy client or a host client.
jpayne@69 802 //
jpayne@69 803 // `url` and `headers` need only remain valid until `request()` returns (they can be
jpayne@69 804 // stack-allocated).
jpayne@69 805 //
jpayne@69 806 // `expectedBodySize`, if provided, must be exactly the number of bytes that will be written to
jpayne@69 807 // the body. This will trigger use of the `Content-Length` connection header. Otherwise,
jpayne@69 808 // `Transfer-Encoding: chunked` will be used.
jpayne@69 809
jpayne@69 810 struct WebSocketResponse {
jpayne@69 811 uint statusCode;
jpayne@69 812 kj::StringPtr statusText;
jpayne@69 813 const HttpHeaders* headers;
jpayne@69 814 kj::OneOf<kj::Own<kj::AsyncInputStream>, kj::Own<WebSocket>> webSocketOrBody;
jpayne@69 815 // `statusText` and `headers` remain valid until `webSocketOrBody` is dropped or read from.
jpayne@69 816 };
jpayne@69 817 virtual kj::Promise<WebSocketResponse> openWebSocket(
jpayne@69 818 kj::StringPtr url, const HttpHeaders& headers);
jpayne@69 819 // Tries to open a WebSocket. Default implementation calls send() and never returns a WebSocket.
jpayne@69 820 //
jpayne@69 821 // `url` and `headers` need only remain valid until `openWebSocket()` returns (they can be
jpayne@69 822 // stack-allocated).
jpayne@69 823
jpayne@69 824 struct ConnectRequest {
jpayne@69 825 struct Status {
jpayne@69 826 uint statusCode;
jpayne@69 827 kj::String statusText;
jpayne@69 828 kj::Own<HttpHeaders> headers;
jpayne@69 829 kj::Maybe<kj::Own<kj::AsyncInputStream>> errorBody;
jpayne@69 830 // If the connect request is rejected, the statusCode can be any HTTP status code
jpayne@69 831 // outside the 200-299 range and errorBody *may* be specified if there is a rejection
jpayne@69 832 // payload.
jpayne@69 833
jpayne@69 834 // TODO(perf): Having Status own the statusText and headers is a bit unfortunate.
jpayne@69 835 // Ideally we could have these be non-owned so that the headers object could just
jpayne@69 836 // point directly into HttpOutputStream's buffer and not be copied. That's a bit
jpayne@69 837 // more difficult to with CONNECT since the lifetimes of the buffers are a little
jpayne@69 838 // different than with regular HTTP requests. It should still be possible but for
jpayne@69 839 // now copying and owning the status text and headers is easier.
jpayne@69 840
jpayne@69 841 Status(uint statusCode,
jpayne@69 842 kj::String statusText,
jpayne@69 843 kj::Own<HttpHeaders> headers,
jpayne@69 844 kj::Maybe<kj::Own<kj::AsyncInputStream>> errorBody = nullptr)
jpayne@69 845 : statusCode(statusCode),
jpayne@69 846 statusText(kj::mv(statusText)),
jpayne@69 847 headers(kj::mv(headers)),
jpayne@69 848 errorBody(kj::mv(errorBody)) {}
jpayne@69 849 };
jpayne@69 850
jpayne@69 851 kj::Promise<Status> status;
jpayne@69 852 kj::Own<kj::AsyncIoStream> connection;
jpayne@69 853 };
jpayne@69 854
jpayne@69 855 virtual ConnectRequest connect(
jpayne@69 856 kj::StringPtr host, const HttpHeaders& headers, HttpConnectSettings settings);
jpayne@69 857 // Handles CONNECT requests.
jpayne@69 858 //
jpayne@69 859 // `host` must specify both the host and port (e.g. "example.org:1234").
jpayne@69 860 //
jpayne@69 861 // The `host` and `headers` need only remain valid until `connect()` returns (it can be
jpayne@69 862 // stack-allocated).
jpayne@69 863 };
jpayne@69 864
jpayne@69 865 class HttpService {
jpayne@69 866 // Interface which HTTP services should implement.
jpayne@69 867 //
jpayne@69 868 // This interface is functionally equivalent to HttpClient, but is intended for applications to
jpayne@69 869 // implement rather than call. The ergonomics and performance of the method signatures are
jpayne@69 870 // optimized for the serving end.
jpayne@69 871 //
jpayne@69 872 // As with clients, there are two kinds of services:
jpayne@69 873 // * Host services are used when talking to a specific host. The `url` specified in a request
jpayne@69 874 // is actually just a path. (A `Host` header is still required in all requests, and the service
jpayne@69 875 // may in fact serve multiple origins via this header.)
jpayne@69 876 // * Proxy services are used when the target could be any arbitrary host on the internet, i.e. to
jpayne@69 877 // implement an HTTP proxy. The `url` specified in a request is a full URL including protocol
jpayne@69 878 // and hostname.
jpayne@69 879
jpayne@69 880 public:
jpayne@69 881 class Response {
jpayne@69 882 public:
jpayne@69 883 virtual kj::Own<kj::AsyncOutputStream> send(
jpayne@69 884 uint statusCode, kj::StringPtr statusText, const HttpHeaders& headers,
jpayne@69 885 kj::Maybe<uint64_t> expectedBodySize = nullptr) = 0;
jpayne@69 886 // Begin the response.
jpayne@69 887 //
jpayne@69 888 // `statusText` and `headers` need only remain valid until send() returns (they can be
jpayne@69 889 // stack-allocated).
jpayne@69 890 //
jpayne@69 891 // `send()` may only be called a single time. Calling it a second time will cause an exception
jpayne@69 892 // to be thrown.
jpayne@69 893
jpayne@69 894 virtual kj::Own<WebSocket> acceptWebSocket(const HttpHeaders& headers) = 0;
jpayne@69 895 // If headers.isWebSocket() is true then you can call acceptWebSocket() instead of send().
jpayne@69 896 //
jpayne@69 897 // If the request is an invalid WebSocket request (e.g., it has an Upgrade: websocket header,
jpayne@69 898 // but other WebSocket-related headers are invalid), `acceptWebSocket()` will throw an
jpayne@69 899 // exception, and the HttpServer will return a 400 Bad Request response and close the
jpayne@69 900 // connection. In this circumstance, the HttpServer will ignore any exceptions which propagate
jpayne@69 901 // from the `HttpService::request()` promise. `HttpServerErrorHandler::handleApplicationError()`
jpayne@69 902 // will not be invoked, and the HttpServer's listen task will be fulfilled normally.
jpayne@69 903 //
jpayne@69 904 // `acceptWebSocket()` may only be called a single time. Calling it a second time will cause an
jpayne@69 905 // exception to be thrown.
jpayne@69 906
jpayne@69 907 kj::Promise<void> sendError(uint statusCode, kj::StringPtr statusText,
jpayne@69 908 const HttpHeaders& headers);
jpayne@69 909 kj::Promise<void> sendError(uint statusCode, kj::StringPtr statusText,
jpayne@69 910 const HttpHeaderTable& headerTable);
jpayne@69 911 // Convenience wrapper around send() which sends a basic error. A generic error page specifying
jpayne@69 912 // the error code is sent as the body.
jpayne@69 913 //
jpayne@69 914 // You must provide headers or a header table because downstream service wrappers may be
jpayne@69 915 // expecting response headers built with a particular table so that they can insert additional
jpayne@69 916 // headers.
jpayne@69 917 };
jpayne@69 918
jpayne@69 919 virtual kj::Promise<void> request(
jpayne@69 920 HttpMethod method, kj::StringPtr url, const HttpHeaders& headers,
jpayne@69 921 kj::AsyncInputStream& requestBody, Response& response) = 0;
jpayne@69 922 // Perform an HTTP request.
jpayne@69 923 //
jpayne@69 924 // `url` may be a full URL (with protocol and host) or it may be only the path part of the URL,
jpayne@69 925 // depending on whether the service is a proxy service or a host service.
jpayne@69 926 //
jpayne@69 927 // `url` and `headers` are invalidated on the first read from `requestBody` or when the returned
jpayne@69 928 // promise resolves, whichever comes first.
jpayne@69 929 //
jpayne@69 930 // Request processing can be canceled by dropping the returned promise. HttpServer may do so if
jpayne@69 931 // the client disconnects prematurely.
jpayne@69 932 //
jpayne@69 933 // The implementation of `request()` should usually not try to use `response` in any way in
jpayne@69 934 // exception-handling code, because it is often not possible to tell whether `Response::send()` or
jpayne@69 935 // `Response::acceptWebSocket()` has already been called. Instead, to generate error HTTP
jpayne@69 936 // responses for the client, implement an HttpServerErrorHandler and pass it to the HttpServer via
jpayne@69 937 // HttpServerSettings. If the `HttpService::request()` promise rejects and no response has yet
jpayne@69 938 // been sent, `HttpServerErrorHandler::handleApplicationError()` will be passed a non-null
jpayne@69 939 // `Maybe<Response&>` parameter.
jpayne@69 940
jpayne@69 941 class ConnectResponse {
jpayne@69 942 public:
jpayne@69 943 virtual void accept(
jpayne@69 944 uint statusCode,
jpayne@69 945 kj::StringPtr statusText,
jpayne@69 946 const HttpHeaders& headers) = 0;
jpayne@69 947 // Signals acceptance of the CONNECT tunnel.
jpayne@69 948
jpayne@69 949 virtual kj::Own<kj::AsyncOutputStream> reject(
jpayne@69 950 uint statusCode,
jpayne@69 951 kj::StringPtr statusText,
jpayne@69 952 const HttpHeaders& headers,
jpayne@69 953 kj::Maybe<uint64_t> expectedBodySize = nullptr) = 0;
jpayne@69 954 // Signals rejection of the CONNECT tunnel.
jpayne@69 955 };
jpayne@69 956
jpayne@69 957 virtual kj::Promise<void> connect(kj::StringPtr host,
jpayne@69 958 const HttpHeaders& headers,
jpayne@69 959 kj::AsyncIoStream& connection,
jpayne@69 960 ConnectResponse& response,
jpayne@69 961 HttpConnectSettings settings);
jpayne@69 962 // Handles CONNECT requests.
jpayne@69 963 //
jpayne@69 964 // The `host` must include host and port.
jpayne@69 965 //
jpayne@69 966 // `host` and `headers` are invalidated when accept or reject is called on the ConnectResponse
jpayne@69 967 // or when the returned promise resolves, whichever comes first.
jpayne@69 968 //
jpayne@69 969 // The connection is provided to support pipelining. Writes to the connection will be blocked
jpayne@69 970 // until one of either accept() or reject() is called on tunnel. Reads from the connection are
jpayne@69 971 // permitted at any time.
jpayne@69 972 //
jpayne@69 973 // Request processing can be canceled by dropping the returned promise. HttpServer may do so if
jpayne@69 974 // the client disconnects prematurely.
jpayne@69 975 };
jpayne@69 976
jpayne@69 977 class HttpClientErrorHandler {
jpayne@69 978 public:
jpayne@69 979 virtual HttpClient::Response handleProtocolError(HttpHeaders::ProtocolError protocolError);
jpayne@69 980 // Override this function to customize error handling when the client receives an HTTP message
jpayne@69 981 // that fails to parse. The default implementations throws an exception.
jpayne@69 982 //
jpayne@69 983 // There are two main use cases for overriding this:
jpayne@69 984 // 1. `protocolError` contains the actual header content that failed to parse, giving you the
jpayne@69 985 // opportunity to log it for debugging purposes. The default implementation throws away this
jpayne@69 986 // content.
jpayne@69 987 // 2. You could potentially convert protocol errors into HTTP error codes, e.g. 502 Bad Gateway.
jpayne@69 988 //
jpayne@69 989 // Note that `protocolError` may contain pointers into buffers that are no longer valid once
jpayne@69 990 // this method returns; you will have to make copies if you want to keep them.
jpayne@69 991
jpayne@69 992 virtual HttpClient::WebSocketResponse handleWebSocketProtocolError(
jpayne@69 993 HttpHeaders::ProtocolError protocolError);
jpayne@69 994 // Like handleProtocolError() but for WebSocket requests. The default implementation calls
jpayne@69 995 // handleProtocolError() and converts the Response to WebSocketResponse. There is probably very
jpayne@69 996 // little reason to override this.
jpayne@69 997 };
jpayne@69 998
jpayne@69 999 struct HttpClientSettings {
jpayne@69 1000 kj::Duration idleTimeout = 5 * kj::SECONDS;
jpayne@69 1001 // For clients which automatically create new connections, any connection idle for at least this
jpayne@69 1002 // long will be closed. Set this to 0 to prevent connection reuse entirely.
jpayne@69 1003
jpayne@69 1004 kj::Maybe<EntropySource&> entropySource = nullptr;
jpayne@69 1005 // Must be provided in order to use `openWebSocket`. If you don't need WebSockets, this can be
jpayne@69 1006 // omitted. The WebSocket protocol uses random values to avoid triggering flaws (including
jpayne@69 1007 // security flaws) in certain HTTP proxy software. Specifically, entropy is used to generate the
jpayne@69 1008 // `Sec-WebSocket-Key` header and to generate frame masks. If you know that there are no broken
jpayne@69 1009 // or vulnerable proxies between you and the server, you can provide a dummy entropy source that
jpayne@69 1010 // doesn't generate real entropy (e.g. returning the same value every time). Otherwise, you must
jpayne@69 1011 // provide a cryptographically-random entropy source.
jpayne@69 1012
jpayne@69 1013 kj::Maybe<HttpClientErrorHandler&> errorHandler = nullptr;
jpayne@69 1014 // Customize how protocol errors are handled by the HttpClient. If null, HttpClientErrorHandler's
jpayne@69 1015 // default implementation will be used.
jpayne@69 1016
jpayne@69 1017 enum WebSocketCompressionMode {
jpayne@69 1018 NO_COMPRESSION,
jpayne@69 1019 MANUAL_COMPRESSION, // Lets the application decide the compression configuration (if any).
jpayne@69 1020 AUTOMATIC_COMPRESSION, // Automatically includes the compression header in the WebSocket request.
jpayne@69 1021 };
jpayne@69 1022 WebSocketCompressionMode webSocketCompressionMode = NO_COMPRESSION;
jpayne@69 1023
jpayne@69 1024 kj::Maybe<SecureNetworkWrapper&> tlsContext;
jpayne@69 1025 // A reference to a TLS context that will be used when tlsStarter is invoked.
jpayne@69 1026 };
jpayne@69 1027
jpayne@69 1028 class WebSocketErrorHandler {
jpayne@69 1029 public:
jpayne@69 1030 virtual kj::Exception handleWebSocketProtocolError(WebSocket::ProtocolError protocolError);
jpayne@69 1031 // Handles low-level protocol errors in received WebSocket data.
jpayne@69 1032 //
jpayne@69 1033 // This is called when the WebSocket peer sends us bad data *after* a successful WebSocket
jpayne@69 1034 // upgrade, e.g. a continuation frame without a preceding start frame, a frame with an unknown
jpayne@69 1035 // opcode, or similar.
jpayne@69 1036 //
jpayne@69 1037 // You would override this method in order to customize the exception. You cannot prevent the
jpayne@69 1038 // exception from being thrown.
jpayne@69 1039 };
jpayne@69 1040
jpayne@69 1041 kj::Own<HttpClient> newHttpClient(kj::Timer& timer, const HttpHeaderTable& responseHeaderTable,
jpayne@69 1042 kj::Network& network, kj::Maybe<kj::Network&> tlsNetwork,
jpayne@69 1043 HttpClientSettings settings = HttpClientSettings());
jpayne@69 1044 // Creates a proxy HttpClient that connects to hosts over the given network. The URL must always
jpayne@69 1045 // be an absolute URL; the host is parsed from the URL. This implementation will automatically
jpayne@69 1046 // add an appropriate Host header (and convert the URL to just a path) once it has connected.
jpayne@69 1047 //
jpayne@69 1048 // Note that if you wish to route traffic through an HTTP proxy server rather than connect to
jpayne@69 1049 // remote hosts directly, you should use the form of newHttpClient() that takes a NetworkAddress,
jpayne@69 1050 // and supply the proxy's address.
jpayne@69 1051 //
jpayne@69 1052 // `responseHeaderTable` is used when parsing HTTP responses. Requests can use any header table.
jpayne@69 1053 //
jpayne@69 1054 // `tlsNetwork` is required to support HTTPS destination URLs. If null, only HTTP URLs can be
jpayne@69 1055 // fetched.
jpayne@69 1056
jpayne@69 1057 kj::Own<HttpClient> newHttpClient(kj::Timer& timer, const HttpHeaderTable& responseHeaderTable,
jpayne@69 1058 kj::NetworkAddress& addr,
jpayne@69 1059 HttpClientSettings settings = HttpClientSettings());
jpayne@69 1060 // Creates an HttpClient that always connects to the given address no matter what URL is requested.
jpayne@69 1061 // The client will open and close connections as needed. It will attempt to reuse connections for
jpayne@69 1062 // multiple requests but will not send a new request before the previous response on the same
jpayne@69 1063 // connection has completed, as doing so can result in head-of-line blocking issues. The client may
jpayne@69 1064 // be used as a proxy client or a host client depending on whether the peer is operating as
jpayne@69 1065 // a proxy. (Hint: This is the best kind of client to use when routing traffic through an HTTP
jpayne@69 1066 // proxy. `addr` should be the address of the proxy, and the proxy itself will resolve remote hosts
jpayne@69 1067 // based on the URLs passed to it.)
jpayne@69 1068 //
jpayne@69 1069 // `responseHeaderTable` is used when parsing HTTP responses. Requests can use any header table.
jpayne@69 1070
jpayne@69 1071 kj::Own<HttpClient> newHttpClient(const HttpHeaderTable& responseHeaderTable,
jpayne@69 1072 kj::AsyncIoStream& stream,
jpayne@69 1073 HttpClientSettings settings = HttpClientSettings());
jpayne@69 1074 // Creates an HttpClient that speaks over the given pre-established connection. The client may
jpayne@69 1075 // be used as a proxy client or a host client depending on whether the peer is operating as
jpayne@69 1076 // a proxy.
jpayne@69 1077 //
jpayne@69 1078 // Note that since this client has only one stream to work with, it will try to pipeline all
jpayne@69 1079 // requests on this stream. If one request or response has an I/O failure, all subsequent requests
jpayne@69 1080 // fail as well. If the destination server chooses to close the connection after a response,
jpayne@69 1081 // subsequent requests will fail. If a response takes a long time, it blocks subsequent responses.
jpayne@69 1082 // If a WebSocket is opened successfully, all subsequent requests fail.
jpayne@69 1083
jpayne@69 1084 kj::Own<HttpClient> newConcurrencyLimitingHttpClient(
jpayne@69 1085 HttpClient& inner, uint maxConcurrentRequests,
jpayne@69 1086 kj::Function<void(uint runningCount, uint pendingCount)> countChangedCallback);
jpayne@69 1087 // Creates an HttpClient that is limited to a maximum number of concurrent requests. Additional
jpayne@69 1088 // requests are queued, to be opened only after an open request completes. `countChangedCallback`
jpayne@69 1089 // is called when a new connection is opened or enqueued and when an open connection is closed,
jpayne@69 1090 // passing the number of open and pending connections.
jpayne@69 1091
jpayne@69 1092 kj::Own<HttpClient> newHttpClient(HttpService& service);
jpayne@69 1093 kj::Own<HttpService> newHttpService(HttpClient& client);
jpayne@69 1094 // Adapts an HttpClient to an HttpService and vice versa.
jpayne@69 1095
jpayne@69 1096 kj::Own<HttpInputStream> newHttpInputStream(
jpayne@69 1097 kj::AsyncInputStream& input, const HttpHeaderTable& headerTable);
jpayne@69 1098 // Create an HttpInputStream on top of the given stream. Normally applications would not call this
jpayne@69 1099 // directly, but it can be useful for implementing protocols that aren't quite HTTP but use similar
jpayne@69 1100 // message delimiting.
jpayne@69 1101 //
jpayne@69 1102 // The HttpInputStream implementation does read-ahead buffering on `input`. Therefore, when the
jpayne@69 1103 // HttpInputStream is destroyed, some data read from `input` may be lost, so it's not possible to
jpayne@69 1104 // continue reading from `input` in a reliable way.
jpayne@69 1105
jpayne@69 1106 kj::Own<WebSocket> newWebSocket(kj::Own<kj::AsyncIoStream> stream,
jpayne@69 1107 kj::Maybe<EntropySource&> maskEntropySource,
jpayne@69 1108 kj::Maybe<CompressionParameters> compressionConfig = nullptr,
jpayne@69 1109 kj::Maybe<WebSocketErrorHandler&> errorHandler = nullptr);
jpayne@69 1110 // Create a new WebSocket on top of the given stream. It is assumed that the HTTP -> WebSocket
jpayne@69 1111 // upgrade handshake has already occurred (or is not needed), and messages can immediately be
jpayne@69 1112 // sent and received on the stream. Normally applications would not call this directly.
jpayne@69 1113 //
jpayne@69 1114 // `maskEntropySource` is used to generate cryptographically-random frame masks. If null, outgoing
jpayne@69 1115 // frames will not be masked. Servers are required NOT to mask their outgoing frames, but clients
jpayne@69 1116 // ARE required to do so. So, on the client side, you MUST specify an entropy source. The mask
jpayne@69 1117 // must be crytographically random if the data being sent on the WebSocket may be malicious. The
jpayne@69 1118 // purpose of the mask is to prevent badly-written HTTP proxies from interpreting "things that look
jpayne@69 1119 // like HTTP requests" in a message as being actual HTTP requests, which could result in cache
jpayne@69 1120 // poisoning. See RFC6455 section 10.3.
jpayne@69 1121 //
jpayne@69 1122 // `compressionConfig` is an optional argument that allows us to specify how the WebSocket should
jpayne@69 1123 // compress and decompress messages. The configuration is determined by the
jpayne@69 1124 // `Sec-WebSocket-Extensions` header during WebSocket negotiation.
jpayne@69 1125 //
jpayne@69 1126 // `errorHandler` is an optional argument that lets callers throw custom exceptions for WebSocket
jpayne@69 1127 // protocol errors.
jpayne@69 1128
jpayne@69 1129 struct WebSocketPipe {
jpayne@69 1130 kj::Own<WebSocket> ends[2];
jpayne@69 1131 };
jpayne@69 1132
jpayne@69 1133 WebSocketPipe newWebSocketPipe();
jpayne@69 1134 // Create a WebSocket pipe. Messages written to one end of the pipe will be readable from the other
jpayne@69 1135 // end. No buffering occurs -- a message send does not complete until a corresponding receive
jpayne@69 1136 // accepts the message.
jpayne@69 1137
jpayne@69 1138 class HttpServerErrorHandler;
jpayne@69 1139 class HttpServerCallbacks;
jpayne@69 1140
jpayne@69 1141 struct HttpServerSettings {
jpayne@69 1142 kj::Duration headerTimeout = 15 * kj::SECONDS;
jpayne@69 1143 // After initial connection open, or after receiving the first byte of a pipelined request,
jpayne@69 1144 // the client must send the complete request within this time.
jpayne@69 1145
jpayne@69 1146 kj::Duration pipelineTimeout = 5 * kj::SECONDS;
jpayne@69 1147 // After one request/response completes, we'll wait up to this long for a pipelined request to
jpayne@69 1148 // arrive.
jpayne@69 1149
jpayne@69 1150 kj::Duration canceledUploadGracePeriod = 1 * kj::SECONDS;
jpayne@69 1151 size_t canceledUploadGraceBytes = 65536;
jpayne@69 1152 // If the HttpService sends a response and returns without having read the entire request body,
jpayne@69 1153 // then we have to decide whether to close the connection or wait for the client to finish the
jpayne@69 1154 // request so that it can pipeline the next one. We'll give them a grace period defined by the
jpayne@69 1155 // above two values -- if they hit either one, we'll close the socket, but if the request
jpayne@69 1156 // completes, we'll let the connection stay open to handle more requests.
jpayne@69 1157
jpayne@69 1158 kj::Maybe<HttpServerErrorHandler&> errorHandler = nullptr;
jpayne@69 1159 // Customize how client protocol errors and service application exceptions are handled by the
jpayne@69 1160 // HttpServer. If null, HttpServerErrorHandler's default implementation will be used.
jpayne@69 1161
jpayne@69 1162 kj::Maybe<HttpServerCallbacks&> callbacks = nullptr;
jpayne@69 1163 // Additional optional callbacks used to control some server behavior.
jpayne@69 1164
jpayne@69 1165 kj::Maybe<WebSocketErrorHandler&> webSocketErrorHandler = nullptr;
jpayne@69 1166 // Customize exceptions thrown on WebSocket protocol errors.
jpayne@69 1167
jpayne@69 1168 enum WebSocketCompressionMode {
jpayne@69 1169 NO_COMPRESSION,
jpayne@69 1170 MANUAL_COMPRESSION, // Gives the application more control when considering whether to compress.
jpayne@69 1171 AUTOMATIC_COMPRESSION, // Will perform compression parameter negotiation if client requests it.
jpayne@69 1172 };
jpayne@69 1173 WebSocketCompressionMode webSocketCompressionMode = NO_COMPRESSION;
jpayne@69 1174 };
jpayne@69 1175
jpayne@69 1176 class HttpServerErrorHandler {
jpayne@69 1177 public:
jpayne@69 1178 virtual kj::Promise<void> handleClientProtocolError(
jpayne@69 1179 HttpHeaders::ProtocolError protocolError, kj::HttpService::Response& response);
jpayne@69 1180 virtual kj::Promise<void> handleApplicationError(
jpayne@69 1181 kj::Exception exception, kj::Maybe<kj::HttpService::Response&> response);
jpayne@69 1182 virtual kj::Promise<void> handleNoResponse(kj::HttpService::Response& response);
jpayne@69 1183 // Override these functions to customize error handling during the request/response cycle.
jpayne@69 1184 //
jpayne@69 1185 // Client protocol errors arise when the server receives an HTTP message that fails to parse. As
jpayne@69 1186 // such, HttpService::request() will not have been called yet, and the handler is always
jpayne@69 1187 // guaranteed an opportunity to send a response. The default implementation of
jpayne@69 1188 // handleClientProtocolError() replies with a 400 Bad Request response.
jpayne@69 1189 //
jpayne@69 1190 // Application errors arise when HttpService::request() throws an exception. The default
jpayne@69 1191 // implementation of handleApplicationError() maps the following exception types to HTTP statuses,
jpayne@69 1192 // and generates bodies from the stringified exceptions:
jpayne@69 1193 //
jpayne@69 1194 // - OVERLOADED: 503 Service Unavailable
jpayne@69 1195 // - UNIMPLEMENTED: 501 Not Implemented
jpayne@69 1196 // - DISCONNECTED: (no response)
jpayne@69 1197 // - FAILED: 500 Internal Server Error
jpayne@69 1198 //
jpayne@69 1199 // No-response errors occur when HttpService::request() allows its promise to settle before
jpayne@69 1200 // sending a response. The default implementation of handleNoResponse() replies with a 500
jpayne@69 1201 // Internal Server Error response.
jpayne@69 1202 //
jpayne@69 1203 // Unlike `HttpService::request()`, when calling `response.send()` in the context of one of these
jpayne@69 1204 // functions, a "Connection: close" header will be added, and the connection will be closed.
jpayne@69 1205 //
jpayne@69 1206 // Also unlike `HttpService::request()`, it is okay to return kj::READY_NOW without calling
jpayne@69 1207 // `response.send()`. In this case, no response will be sent, and the connection will be closed.
jpayne@69 1208
jpayne@69 1209 virtual void handleListenLoopException(kj::Exception&& exception);
jpayne@69 1210 // Override this function to customize error handling for individual connections in the
jpayne@69 1211 // `listenHttp()` overload which accepts a ConnectionReceiver reference.
jpayne@69 1212 //
jpayne@69 1213 // The default handler uses KJ_LOG() to log the exception as an error.
jpayne@69 1214 };
jpayne@69 1215
jpayne@69 1216 class HttpServerCallbacks {
jpayne@69 1217 public:
jpayne@69 1218 virtual bool shouldClose() { return false; }
jpayne@69 1219 // Whenever the HttpServer begins response headers, it will check `shouldClose()` to decide
jpayne@69 1220 // whether to send a `Connection: close` header and close the connection.
jpayne@69 1221 //
jpayne@69 1222 // This can be useful e.g. if the server has too many connections open and wants to shed some
jpayne@69 1223 // of them. Note that to implement graceful shutdown of a server, you should use
jpayne@69 1224 // `HttpServer::drain()` instead.
jpayne@69 1225 };
jpayne@69 1226
jpayne@69 1227 class HttpServer final: private kj::TaskSet::ErrorHandler {
jpayne@69 1228 // Class which listens for requests on ports or connections and sends them to an HttpService.
jpayne@69 1229
jpayne@69 1230 public:
jpayne@69 1231 typedef HttpServerSettings Settings;
jpayne@69 1232 typedef kj::Function<kj::Own<HttpService>(kj::AsyncIoStream&)> HttpServiceFactory;
jpayne@69 1233 class SuspendableRequest;
jpayne@69 1234 typedef kj::Function<kj::Maybe<kj::Own<HttpService>>(SuspendableRequest&)>
jpayne@69 1235 SuspendableHttpServiceFactory;
jpayne@69 1236
jpayne@69 1237 HttpServer(kj::Timer& timer, const HttpHeaderTable& requestHeaderTable, HttpService& service,
jpayne@69 1238 Settings settings = Settings());
jpayne@69 1239 // Set up an HttpServer that directs incoming connections to the given service. The service
jpayne@69 1240 // may be a host service or a proxy service depending on whether you are intending to implement
jpayne@69 1241 // an HTTP server or an HTTP proxy.
jpayne@69 1242
jpayne@69 1243 HttpServer(kj::Timer& timer, const HttpHeaderTable& requestHeaderTable,
jpayne@69 1244 HttpServiceFactory serviceFactory, Settings settings = Settings());
jpayne@69 1245 // Like the other constructor, but allows a new HttpService object to be used for each
jpayne@69 1246 // connection, based on the connection object. This is particularly useful for capturing the
jpayne@69 1247 // client's IP address and injecting it as a header.
jpayne@69 1248
jpayne@69 1249 kj::Promise<void> drain();
jpayne@69 1250 // Stop accepting new connections or new requests on existing connections. Finish any requests
jpayne@69 1251 // that are already executing, then close the connections. Returns once no more requests are
jpayne@69 1252 // in-flight.
jpayne@69 1253
jpayne@69 1254 kj::Promise<void> listenHttp(kj::ConnectionReceiver& port);
jpayne@69 1255 // Accepts HTTP connections on the given port and directs them to the handler.
jpayne@69 1256 //
jpayne@69 1257 // The returned promise never completes normally. It may throw if port.accept() throws. Dropping
jpayne@69 1258 // the returned promise will cause the server to stop listening on the port, but already-open
jpayne@69 1259 // connections will continue to be served. Destroy the whole HttpServer to cancel all I/O.
jpayne@69 1260
jpayne@69 1261 kj::Promise<void> listenHttp(kj::Own<kj::AsyncIoStream> connection);
jpayne@69 1262 // Reads HTTP requests from the given connection and directs them to the handler. A successful
jpayne@69 1263 // completion of the promise indicates that all requests received on the connection resulted in
jpayne@69 1264 // a complete response, and the client closed the connection gracefully or drain() was called.
jpayne@69 1265 // The promise throws if an unparsable request is received or if some I/O error occurs. Dropping
jpayne@69 1266 // the returned promise will cancel all I/O on the connection and cancel any in-flight requests.
jpayne@69 1267
jpayne@69 1268 kj::Promise<bool> listenHttpCleanDrain(kj::AsyncIoStream& connection);
jpayne@69 1269 // Like listenHttp(), but allows you to potentially drain the server without closing connections.
jpayne@69 1270 // The returned promise resolves to `true` if the connection has been left in a state where a
jpayne@69 1271 // new HttpServer could potentially accept further requests from it. If `false`, then the
jpayne@69 1272 // connection is either in an inconsistent state or already completed a closing handshake; the
jpayne@69 1273 // caller should close it without any further reads/writes. Note this only ever returns `true`
jpayne@69 1274 // if you called `drain()` -- otherwise this server would keep handling the connection.
jpayne@69 1275
jpayne@69 1276 class SuspendedRequest {
jpayne@69 1277 // SuspendedRequest is a representation of a request immediately after parsing the method line and
jpayne@69 1278 // headers. You can obtain one of these by suspending a request by calling
jpayne@69 1279 // SuspendableRequest::suspend(), then later resume the request with another call to
jpayne@69 1280 // listenHttpCleanDrain().
jpayne@69 1281
jpayne@69 1282 public:
jpayne@69 1283 // Nothing, this is an opaque type.
jpayne@69 1284
jpayne@69 1285 private:
jpayne@69 1286 SuspendedRequest(kj::Array<byte>, kj::ArrayPtr<byte>, kj::OneOf<HttpMethod, HttpConnectMethod>, kj::StringPtr, HttpHeaders);
jpayne@69 1287
jpayne@69 1288 kj::Array<byte> buffer;
jpayne@69 1289 // A buffer containing at least the request's method, URL, and headers, and possibly content
jpayne@69 1290 // thereafter.
jpayne@69 1291
jpayne@69 1292 kj::ArrayPtr<byte> leftover;
jpayne@69 1293 // Pointer to the end of the request headers. If this has a non-zero length, then our buffer
jpayne@69 1294 // contains additional content, presumably the head of the request body.
jpayne@69 1295
jpayne@69 1296 kj::OneOf<HttpMethod, HttpConnectMethod> method;
jpayne@69 1297 kj::StringPtr url;
jpayne@69 1298 HttpHeaders headers;
jpayne@69 1299 // Parsed request front matter. `url` and `headers` both store pointers into `buffer`.
jpayne@69 1300
jpayne@69 1301 friend class HttpServer;
jpayne@69 1302 };
jpayne@69 1303
jpayne@69 1304 kj::Promise<bool> listenHttpCleanDrain(kj::AsyncIoStream& connection,
jpayne@69 1305 SuspendableHttpServiceFactory factory,
jpayne@69 1306 kj::Maybe<SuspendedRequest> suspendedRequest = nullptr);
jpayne@69 1307 // Like listenHttpCleanDrain(), but allows you to suspend requests.
jpayne@69 1308 //
jpayne@69 1309 // When this overload is in use, the HttpServer's default HttpService or HttpServiceFactory is not
jpayne@69 1310 // used. Instead, the HttpServer reads the request method line and headers, then calls `factory`
jpayne@69 1311 // with a SuspendableRequest representing the request parsed so far. The factory may then return
jpayne@69 1312 // a kj::Own<HttpService> for that specific request, or it may call SuspendableRequest::suspend()
jpayne@69 1313 // and return nullptr. (It is an error for the factory to return nullptr without also calling
jpayne@69 1314 // suspend(); this will result in a rejected listenHttpCleanDrain() promise.)
jpayne@69 1315 //
jpayne@69 1316 // If the factory chooses to suspend, the listenHttpCleanDrain() promise is resolved with false
jpayne@69 1317 // at the earliest opportunity.
jpayne@69 1318 //
jpayne@69 1319 // SuspendableRequest::suspend() returns a SuspendedRequest. You can resume this request later by
jpayne@69 1320 // calling this same listenHttpCleanDrain() overload with the original connection stream, and the
jpayne@69 1321 // SuspendedRequest in question.
jpayne@69 1322 //
jpayne@69 1323 // This overload of listenHttpCleanDrain() implements draining, as documented above. Note that the
jpayne@69 1324 // returned promise will resolve to false (not clean) if a request is suspended.
jpayne@69 1325
jpayne@69 1326 private:
jpayne@69 1327 class Connection;
jpayne@69 1328
jpayne@69 1329 kj::Timer& timer;
jpayne@69 1330 const HttpHeaderTable& requestHeaderTable;
jpayne@69 1331 kj::OneOf<HttpService*, HttpServiceFactory> service;
jpayne@69 1332 Settings settings;
jpayne@69 1333
jpayne@69 1334 bool draining = false;
jpayne@69 1335 kj::ForkedPromise<void> onDrain;
jpayne@69 1336 kj::Own<kj::PromiseFulfiller<void>> drainFulfiller;
jpayne@69 1337
jpayne@69 1338 uint connectionCount = 0;
jpayne@69 1339 kj::Maybe<kj::Own<kj::PromiseFulfiller<void>>> zeroConnectionsFulfiller;
jpayne@69 1340
jpayne@69 1341 kj::TaskSet tasks;
jpayne@69 1342
jpayne@69 1343 HttpServer(kj::Timer& timer, const HttpHeaderTable& requestHeaderTable,
jpayne@69 1344 kj::OneOf<HttpService*, HttpServiceFactory> service,
jpayne@69 1345 Settings settings, kj::PromiseFulfillerPair<void> paf);
jpayne@69 1346
jpayne@69 1347 kj::Promise<void> listenLoop(kj::ConnectionReceiver& port);
jpayne@69 1348
jpayne@69 1349 void taskFailed(kj::Exception&& exception) override;
jpayne@69 1350
jpayne@69 1351 kj::Promise<bool> listenHttpImpl(kj::AsyncIoStream& connection, bool wantCleanDrain);
jpayne@69 1352 kj::Promise<bool> listenHttpImpl(kj::AsyncIoStream& connection,
jpayne@69 1353 SuspendableHttpServiceFactory factory,
jpayne@69 1354 kj::Maybe<SuspendedRequest> suspendedRequest,
jpayne@69 1355 bool wantCleanDrain);
jpayne@69 1356 };
jpayne@69 1357
jpayne@69 1358 class HttpServer::SuspendableRequest {
jpayne@69 1359 // Interface passed to the SuspendableHttpServiceFactory parameter of listenHttpCleanDrain().
jpayne@69 1360
jpayne@69 1361 public:
jpayne@69 1362 kj::OneOf<HttpMethod,HttpConnectMethod> method;
jpayne@69 1363 kj::StringPtr url;
jpayne@69 1364 const HttpHeaders& headers;
jpayne@69 1365 // Parsed request front matter, so the implementer can decide whether to suspend the request.
jpayne@69 1366
jpayne@69 1367 SuspendedRequest suspend();
jpayne@69 1368 // Signal to the HttpServer that the current request loop should be exited. Return a
jpayne@69 1369 // SuspendedRequest, containing HTTP method, URL, and headers access, along with the actual header
jpayne@69 1370 // buffer. The request can be later resumed with a call to listenHttpCleanDrain() using the same
jpayne@69 1371 // connection.
jpayne@69 1372
jpayne@69 1373 private:
jpayne@69 1374 explicit SuspendableRequest(
jpayne@69 1375 Connection& connection, kj::OneOf<HttpMethod, HttpConnectMethod> method, kj::StringPtr url, const HttpHeaders& headers)
jpayne@69 1376 : method(method), url(url), headers(headers), connection(connection) {}
jpayne@69 1377 KJ_DISALLOW_COPY_AND_MOVE(SuspendableRequest);
jpayne@69 1378
jpayne@69 1379 Connection& connection;
jpayne@69 1380
jpayne@69 1381 friend class Connection;
jpayne@69 1382 };
jpayne@69 1383
jpayne@69 1384 // =======================================================================================
jpayne@69 1385 // inline implementation
jpayne@69 1386
jpayne@69 1387 inline void HttpHeaderId::requireFrom(const HttpHeaderTable& table) const {
jpayne@69 1388 KJ_IREQUIRE(this->table == nullptr || this->table == &table,
jpayne@69 1389 "the provided HttpHeaderId is from the wrong HttpHeaderTable");
jpayne@69 1390 }
jpayne@69 1391
jpayne@69 1392 inline kj::Own<HttpHeaderTable> HttpHeaderTable::Builder::build() {
jpayne@69 1393 table->buildStatus = BuildStatus::FINISHED;
jpayne@69 1394 return kj::mv(table);
jpayne@69 1395 }
jpayne@69 1396 inline HttpHeaderTable& HttpHeaderTable::Builder::getFutureTable() { return *table; }
jpayne@69 1397
jpayne@69 1398 inline uint HttpHeaderTable::idCount() const { return namesById.size(); }
jpayne@69 1399 inline bool HttpHeaderTable::isReady() const {
jpayne@69 1400 switch (buildStatus) {
jpayne@69 1401 case BuildStatus::UNSTARTED: return true;
jpayne@69 1402 case BuildStatus::BUILDING: return false;
jpayne@69 1403 case BuildStatus::FINISHED: return true;
jpayne@69 1404 }
jpayne@69 1405
jpayne@69 1406 KJ_UNREACHABLE;
jpayne@69 1407 }
jpayne@69 1408
jpayne@69 1409 inline kj::StringPtr HttpHeaderTable::idToString(HttpHeaderId id) const {
jpayne@69 1410 id.requireFrom(*this);
jpayne@69 1411 return namesById[id.id];
jpayne@69 1412 }
jpayne@69 1413
jpayne@69 1414 inline kj::Maybe<kj::StringPtr> HttpHeaders::get(HttpHeaderId id) const {
jpayne@69 1415 id.requireFrom(*table);
jpayne@69 1416 auto result = indexedHeaders[id.id];
jpayne@69 1417 return result == nullptr ? kj::Maybe<kj::StringPtr>(nullptr) : result;
jpayne@69 1418 }
jpayne@69 1419
jpayne@69 1420 inline void HttpHeaders::unset(HttpHeaderId id) {
jpayne@69 1421 id.requireFrom(*table);
jpayne@69 1422 indexedHeaders[id.id] = nullptr;
jpayne@69 1423 }
jpayne@69 1424
jpayne@69 1425 template <typename Func>
jpayne@69 1426 inline void HttpHeaders::forEach(Func&& func) const {
jpayne@69 1427 for (auto i: kj::indices(indexedHeaders)) {
jpayne@69 1428 if (indexedHeaders[i] != nullptr) {
jpayne@69 1429 func(table->idToString(HttpHeaderId(table, i)), indexedHeaders[i]);
jpayne@69 1430 }
jpayne@69 1431 }
jpayne@69 1432
jpayne@69 1433 for (auto& header: unindexedHeaders) {
jpayne@69 1434 func(header.name, header.value);
jpayne@69 1435 }
jpayne@69 1436 }
jpayne@69 1437
jpayne@69 1438 template <typename Func1, typename Func2>
jpayne@69 1439 inline void HttpHeaders::forEach(Func1&& func1, Func2&& func2) const {
jpayne@69 1440 for (auto i: kj::indices(indexedHeaders)) {
jpayne@69 1441 if (indexedHeaders[i] != nullptr) {
jpayne@69 1442 func1(HttpHeaderId(table, i), indexedHeaders[i]);
jpayne@69 1443 }
jpayne@69 1444 }
jpayne@69 1445
jpayne@69 1446 for (auto& header: unindexedHeaders) {
jpayne@69 1447 func2(header.name, header.value);
jpayne@69 1448 }
jpayne@69 1449 }
jpayne@69 1450
jpayne@69 1451 // =======================================================================================
jpayne@69 1452 namespace _ { // private implementation details for WebSocket compression
jpayne@69 1453
jpayne@69 1454 kj::ArrayPtr<const char> splitNext(kj::ArrayPtr<const char>& cursor, char delimiter);
jpayne@69 1455
jpayne@69 1456 void stripLeadingAndTrailingSpace(ArrayPtr<const char>& str);
jpayne@69 1457
jpayne@69 1458 kj::Vector<kj::ArrayPtr<const char>> splitParts(kj::ArrayPtr<const char> input, char delim);
jpayne@69 1459
jpayne@69 1460 struct KeyMaybeVal {
jpayne@69 1461 ArrayPtr<const char> key;
jpayne@69 1462 kj::Maybe<ArrayPtr<const char>> val;
jpayne@69 1463 };
jpayne@69 1464
jpayne@69 1465 kj::Array<KeyMaybeVal> toKeysAndVals(const kj::ArrayPtr<kj::ArrayPtr<const char>>& params);
jpayne@69 1466
jpayne@69 1467 struct UnverifiedConfig {
jpayne@69 1468 // An intermediate representation of the final `CompressionParameters` struct; used during parsing.
jpayne@69 1469 // We use it to ensure the structure of an offer is generally correct, see
jpayne@69 1470 // `populateUnverifiedConfig()` for details.
jpayne@69 1471 bool clientNoContextTakeover = false;
jpayne@69 1472 bool serverNoContextTakeover = false;
jpayne@69 1473 kj::Maybe<ArrayPtr<const char>> clientMaxWindowBits = nullptr;
jpayne@69 1474 kj::Maybe<ArrayPtr<const char>> serverMaxWindowBits = nullptr;
jpayne@69 1475 };
jpayne@69 1476
jpayne@69 1477 kj::Maybe<UnverifiedConfig> populateUnverifiedConfig(kj::Array<KeyMaybeVal>& params);
jpayne@69 1478
jpayne@69 1479 kj::Maybe<CompressionParameters> validateCompressionConfig(UnverifiedConfig&& config,
jpayne@69 1480 bool isAgreement);
jpayne@69 1481
jpayne@69 1482 kj::Vector<CompressionParameters> findValidExtensionOffers(StringPtr offers);
jpayne@69 1483
jpayne@69 1484 kj::String generateExtensionRequest(const ArrayPtr<CompressionParameters>& extensions);
jpayne@69 1485
jpayne@69 1486 kj::Maybe<CompressionParameters> tryParseExtensionOffers(StringPtr offers);
jpayne@69 1487
jpayne@69 1488 kj::Maybe<CompressionParameters> tryParseAllExtensionOffers(StringPtr offers,
jpayne@69 1489 CompressionParameters manualConfig);
jpayne@69 1490
jpayne@69 1491 kj::Maybe<CompressionParameters> compareClientAndServerConfigs(CompressionParameters requestConfig,
jpayne@69 1492 CompressionParameters manualConfig);
jpayne@69 1493
jpayne@69 1494 kj::String generateExtensionResponse(const CompressionParameters& parameters);
jpayne@69 1495
jpayne@69 1496 kj::OneOf<CompressionParameters, kj::Exception> tryParseExtensionAgreement(
jpayne@69 1497 const Maybe<CompressionParameters>& clientOffer,
jpayne@69 1498 StringPtr agreedParameters);
jpayne@69 1499
jpayne@69 1500 }; // namespace _ (private)
jpayne@69 1501
jpayne@69 1502 } // namespace kj
jpayne@69 1503
jpayne@69 1504 KJ_END_HEADER