30 lines
2.6 KiB
Markdown
30 lines
2.6 KiB
Markdown
# Handy-Http Primitives
|
|
[DDoc Reference](ddoc/primitives/index.html)
|
|
|
|
The [Primitives](https://git.andrewlalis.com/Handy-Http/primitives) library provides the foundational set of types and interfaces for Handy-Http. Most notably, the Primitives component defines the [`ServerHttpRequest`](ddoc/primitives/handy_http_primitives.request.ServerHttpRequest.html) and [`ServerHttpResponse`](ddoc/primitives/handy_http_primitives.response.ServerHttpResponse.html) structs, and the [`HttpRequestHandler`](ddoc/primitives/handy_http_primitives.handler.HttpRequestHandler.html) interface. Together, these symbols form the basis for a common HTTP layer, loosely inspired by Java's *Servlet* specification. All other Handy-Http components build on top of Primitives' types to implement request handling, response writing, filtering, and all manner of other conveniences you'd expect in a web framework.
|
|
|
|
!!! info "Streams"
|
|
Handy-Http makes extensive use of the [streams](https://github.com/andrewlalis/streams) library for low-level byte input and output operations. This library was also written by Andrew specifically for Handy-Http, and it'll be familiar to programmers coming from Java or other languages that have a *stream* concept.
|
|
|
|
In general, we *read* HTTP requests from an input stream, and *write* responses to an output stream. To allow for flexibility, the Primitives component only refers to streams using their object-oriented interface types, i.e. `InputStream!ubyte` and `OutputStream!ubyte`.
|
|
|
|
## Requests
|
|
|
|
Whenever Handy-Http receives an HTTP request from a client, it will store that request content in a `ServerHttpRequest` which contains the client's address, [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), requested URL, headers, query parameters, and an input stream for reading the request's body content, if available.
|
|
|
|
## Responses
|
|
|
|
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.
|
|
|
|
## Request Handlers
|
|
|
|
We combine the request and response types into one functional interface, `HttpRequestHandler`, which is defined as:
|
|
|
|
```d
|
|
interface HttpRequestHandler {
|
|
void handle(ref ServerHttpRequest request, ref ServerHttpResponse response);
|
|
}
|
|
```
|
|
|
|
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.
|