diff --git a/docs/data.md b/docs/data.md index d37283a..e244556 100644 --- a/docs/data.md +++ b/docs/data.md @@ -1,4 +1,26 @@ # Handy-Http Data [DDoc Reference](ddoc/data/index.html) -WIP +The [Data](https://git.andrewlalis.com/Handy-Http/data) component provides support for some data formats that are common in web servers. + +## JSON + +Support for reading and writing JSON is provided via the [ASDF](https://code.dlang.org/packages/asdf) library. Two methods are provided to help with JSON I/O for HTTP requests: + +* [`readJsonBodyAs`](ddoc/data/handy_http_data.json.readJsonBodyAs.html) for deserializing a JSON request body into some type. +* [`writeJsonBody`](ddoc/data/handy_http_data.json.writeJsonBody.html) for serializing some data into a JSON response body. + +## Multipart Formdata + +The [`multipart.d`](ddoc/data/handy_http_data.multipart.html) module provides support for reading HTTP request bodies defined as `multipart/form-data`. The main function to use here is [`readBodyAsMultipartFormData`](ddoc/data/handy_http_data.multipart.readBodyAsMultipartFormData.html), which takes in a reference to a `ServerHttpRequest`, and returns a [`MultipartFormData`](ddoc/data/handy_http_data.multipart.MultipartFormData.html) struct containing the parsed contents. + +The parsed form data simply contains a list of elements of type [`MultipartElement`](ddoc/data/handy_http_data.multipart.MultipartElement.html), and you can read the underlying data from the element's `content` attribute. + +In practice, multipart formdata is most often used when one would like to send multiple types of data to an API at once, such as when a user is submitting a form that includes basic fields as well as file uploads. + +## XML + +Support for XML is provided via the [DXML](https://code.dlang.org/packages/dxml) library. Two methods are provided to help with XML I/O for HTTP requests: + +* [`readXMLBody`](ddoc/data/handy_http_data.xml.readXMLBody.html) for reading a request body as an XML `DOMEntity`. +* [`writeXMLBody`](ddoc/data/handy_http_data.xml.writeXMLBody.html) for writing a response body by supplying a delegate function that builds the XML tag tree that you'd like to write. diff --git a/docs/websockets.md b/docs/websockets.md index 59e26db..8abac41 100644 --- a/docs/websockets.md +++ b/docs/websockets.md @@ -1,4 +1,10 @@ # Handy-Http Websockets [DDoc Reference](ddoc/websockets/index.html) -WIP +The [Websockets](https://git.andrewlalis.com/Handy-Http/websockets) component provides an [RFC-6455](https://datatracker.ietf.org/doc/html/rfc6455)-compatible implementation of server-side websockets. + +You can add websocket support to your server by using the [`WebSocketRequestHandler`](ddoc/websockets/handy_http_websockets.handler.WebSocketRequestHandler.html) to handle requests that you'd like to upgrade to websockets. Typically, you'd use the [`PathHandler`](handlers.md#the-path-handler) to map requests of a particular URL, say, `GET /websocket`, to the `WebSocketRequestHandler`. + +All that you need to do is define a class that extends from [`WebSocketMessageHandler`](ddoc/websockets/handy_http_websockets.components.WebSocketMessageHandler.html) to override the callback methods you'd like to deal with, and provide your message handler when constructing the `WebSocketRequestHandler`. + +Check out the [example](https://git.andrewlalis.com/Handy-Http/websockets/src/branch/main/examples) available in the project's source code!