From 2f9ed8449c5cea1be4d2188843b4d80ae6162970 Mon Sep 17 00:00:00 2001 From: andrewlalis Date: Fri, 3 Apr 2026 21:48:51 -0400 Subject: [PATCH] Added more docs to the primitives page. --- docs/primitives.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/primitives.md b/docs/primitives.md index b295676..858be96 100644 --- a/docs/primitives.md +++ b/docs/primitives.md @@ -16,6 +16,10 @@ Whenever Handy-Http receives an HTTP request from a client, it will store that r To respond to a client's HTTP request, you'll use a `ServerHttpResponse`, which allows you to provide a status and headers. Response body content is written to the response's output stream. +For your convenience the [`HttpStatus`](ddoc/primitives/handy_http_primitives.response.HttpStatus.html) enum defines a list of every possible HTTP response status. Use these to set the response's status. Also, the [`ContentTypes`](ddoc/primitives/handy_http_primitives.response.ContentTypes.html) enum defines some common `Content-Type` header values to use if you're returning a response body with a typical content type, like images, text, or JSON. + +The [`HttpStatusException`](ddoc/primitives/handy_http_primitives.response.HttpStatusException.html) is an exception that can be thrown at any time during request processing, and if so, it's expected that the transport layer (see [Transport](transport.md)) will gracefully set the indicated response status. You can use this as a quick means of escaping request processing if something goes wrong. However, due to the performance impacts associated with throwing and catching exceptions, try to avoid this for high-traffic, high-performance request processing. + ## Request Handlers We combine the request and response types into one functional interface, `HttpRequestHandler`, which is defined as: @@ -27,3 +31,17 @@ interface HttpRequestHandler { ``` The job of a request handler is to read in an HTTP request, do some logic, and write to the given response. With the use of streams for I/O abstraction, request handlers are the basis for all of Handy-Http, and to achieve more complex behavior, one can simply extend or wrap another request handler. + +## Other Utilities + +In addition to the basic HTTP types, the Primitives component provides some small utility types. These are generally used in the `ServerHttpRequest` and `ServerHttpResponse` structs to make it easier to work with the data, but you are free to use them elsewhere in your code. + +### Optional + +The [`Optional`](ddoc/primitives/handy_http_primitives.optional.Optional.html) type is a simplified version of D's standard library `Nullable`, that provides some convenience methods for mapping the underlying data if it's present. + +### Multi-Value Map + +The [`MultiValueMap`](ddoc/primitives/handy_http_primitives.multivalue_map.MultiValueMap.html) type defines a multi-valued mapping, where a key is mapped to an array of one or more values. The map is sorted by keys for `O(log(n))` lookup and retrieval, and `O(n*log(n))` insertion. + +This is used internally for the `ServerHttpResponse.headers` property, to provide a simple interface for adding headers to a response before flushing it.