Import std.net.http.server
std.net.http.server
HttpServer: HTTP/1.1 over TCP, or HTTPS, over TLS, whose handlers are Async code on the main thread, so they share its Globals without data races. A request goes through the server's middleware, in the order Use gave it, to the handler of the route that fits its method and path best, through the middleware of the groups that route is in; the response goes back on a connection kept open for the next request, unless the request or the response says to close it. Automatic HTTPS gets the server's certificate from an ACME CA, as Let's Encrypt is, and renews it while the server runs.
std/net/http/server.fb
Types
HttpHandler
alias
Public Alias HttpHandler = Func(HttpRequest): Task<HttpResponse>What a route runs: an Async Function of the request, which gives the response.
HttpMiddleware
alias
Public Alias HttpMiddleware = Func(HttpRequest, HttpHandler): Task<HttpResponse>What runs around a handler: an Async Function of the request and the next handler, which it calls, or doesn't, to give the response.
HttpRequest
class
Public Class HttpRequestA request a server read: its method, its Verb, as the client wrote it, like "GET" (Method is a keyword); its target, and the target's path, percent-encoded, without dot segments, and query; its headers and body; the path parameters its route bound; and the client's address.
std/net/http/server.fb, line 47
-
Its method, as the client wrote it, like "GET".
-
Its target, as the client wrote it.
-
Its target's path, percent-encoded, without dot segments.
-
Its target's query.
-
Its headers.
-
Its body's bytes.
-
"HTTP/1.1" or "HTTP/1.0".
-
The client's address.
-
The body as text, its UTF-8, with U+FFFD for each byte that doesn't start well-formed UTF-8.
-
A path parameter its route bound, percent-decoded, like
:id's, or Null when it has none of thatname. -
Each path parameter its route bound, by name.
-
A form's fields, when the body is application/x-www-form-urlencoded, as a browser sends them, or none.
HttpRouter
class
Public Class HttpRouterRoutes, and the middleware around them: a server's own, or a group's, whose routes' paths
start with its prefix and whose middleware runs inside its parent's. A path is segments after
a '/' each: text, which the request's segment matches when it's the same once it's
percent-decoded, :name, which matches any one segment and binds it to name, or, last,
*name, which matches the rest of the path, empty too, and binds it. Of the routes whose
paths match a request's, the one whose segments are text first, segment by segment, takes it,
and of those its method fits, the first added; a request whose path some route matches but
whose method none has is a 405 Method Not Allowed, and one whose path none matches a 404. A
HEAD goes to a GET's route when there's no HEAD's, and its response's body isn't sent.
std/net/http/server.fb, line 215
-
Adds a route for GET and the
path, which panics unless it's a path as HttpRouter has them, or another route has the method and a path that matches what it matches. -
Adds a route for POST and
path, as Get does. -
Adds a route for PUT and
path, as Get does. -
Adds a route for PATCH and
path, as Get does. -
Adds a route for DELETE and
path, as Get does. -
Adds a route for
method, any token, like "PROPFIND", as Get does. -
Adds a work route for GET and the
path, as Get does, whose handler blocks, computing or waiting, and so runs on one of the server's Workers threads, given a Sendable copy of the request, while the main thread goes on answering others. The server's and groups' middleware runs around it on the main thread, as it does around any route. -
Adds a work route for
method, as Route does. -
Adds
middleware, which runs around each of its routes' handlers, after what Use gave it before, a server's around every request, the ones no route takes too. -
A group of routes whose paths start with
prefix, a path as routes have them, but without a*name, or it panics, and whose middleware runs inside this one's.
HttpServer
class
Public Class HttpServer Extends HttpRouterA server: routes and middleware, as HttpRouter has them, answering the requests that come to where Listen has it listen, or ListenTls over TLS, as Serve runs. A request that breaks HTTP/1.1's rules is answered as wire.fb has it (400, 413, 414, 431, 501, or 505) and its connection closed; an HTTP/1.1 one without a Host, or any with two, is a 400; an Expect other than 100-continue is a 417. A response has its Content-Length and Date set, and a Connection: close when its connection closes after it.
std/net/http/server.fb, line 464
-
A new HttpServer, with no routes, which lets a connection idle for 60 seconds.
-
The most bytes a request's body can have, 16 MiB unless it's set, past which it's a 413. Panics when it's set below 0.
-
How many threads its work routes' handlers run on, at most that many at once, the job pool's size, a core fewer than the machine's, unless it's set; the threads start when a work route is first called, and end once Serve has given and the connections it was answering have ended, so a request being answered as Stop comes is answered. Panics when it's set below 1, or once the threads have started.
-
How many work routes' calls wait for a Workers thread at most, 1024 unless it's set, past which a call is a 503 Service Unavailable. Panics when it's set below 1, or once the threads have started.
-
How long a connection waits for its next request, or for more of one, before it's closed: a minute unless it's set.
-
Listens at
address, whose port 0 has the OS pick one, which LocalAddress tells. Throws a NetError as TcpListener.Listen does. Panics when it listens already. -
Listens at
host's first address andport. -
@PanicsAtCaller Public Method ListenTls(address: SocketAddress, tls: TlsServer) Throws NetErrormethod #Listens at
addressas Listen does, for HTTPS: each connection is TLS, astlsaccepts it, with its certificate chain and key; a handshake that fails, or takes longer than IdleTimeout, closes its connection, and the server goes on. -
@PanicsAtCaller Public Method ListenTls(host: String, port: UInt16, tls: TlsServer) Throws NetErrormethod #Listens at
host's first address andport, for HTTPS, astlsaccepts connections. -
@PanicsAtCaller Public Async Method ListenAutoAsync(acme: AcmeClient, names: String[], folder: Path, https: SocketAddress, http: SocketAddress) Throws NetError, TimeoutError, IOErrormethod #Listens for HTTPS at
httpswith a certificate fornames, DNS names, whichacmegets from its CA, or whichfolderkeeps from a run before, while it's valid for thosenames. Onhttp, where the CA checks HTTP-01's challenges, a server of its own answers them, and redirects every other request to HTTPS, with a 308, once HTTPS listens, and until then answers a 503.folderkeeps the certificate's key and chain, as certificate.pem, and itsnames, each written atomically. Serve renews the certificate as it runs, as RenewAsync does, once less than a third of its lifetime is left, which it checks as it starts, as a kept one can be due, and then every RenewalCheck; connections from then on get the renewed one, and those before keep theirs. Throws what ObtainAsync, Listen, and writing thefolderdo. Panics when it listens already, and as ObtainAsync does for thenames. -
Gets automatic HTTPS's certificate again at once, and gives it to connections from then on. Throws what ObtainAsync and writing the folder do, which RenewalError then says, and the certificate before goes on. Panics without ListenAutoAsync.
-
How often automatic HTTPS checks whether its certificate is due to renew: 12 hours unless it's set, which counts from the check before even while a wait is under way. Panics when it's set to 0 or less.
-
When automatic HTTPS's certificate expires, or Null without it.
-
Why automatic HTTPS's last renewal failed, which std.log logs too, or Null once one has worked, or without it.
-
Where it listens, the port the OS picked included. Panics before Listen.
-
Takes connections and answers their requests until Stop, and gives once it stops taking them; requests being answered then are answered. Panics before Listen.
-
Stops taking connections, closes those waiting for a request, and has those answering one close once it's answered.
-
Whether it's listening and hasn't been stopped.
Extends
HttpResponse
extend
Extend HttpResponseNo doc comment.
std/net/http/server.fb, line 131
-
@PanicsAtCaller Public Static Method Of(status: Int, body: Body? = Null): HttpResponsestatic method #A response of
status, withbody's bytes and its Content-Type, or an empty one. Thestatusis a final response's, from 200 to 599, or it panics: a 1xx's response comes before the one that answers, and a WebSocket's 101 comes from its AcceptAsync. -
A 200 with
body. -
@PanicsAtCaller Public Static Method Redirect(url: String, status: Int = 302): HttpResponsestatic method #A redirect to
url, which a header's value can hold, a 302 Found unlessstatussays another from 300 to 399, or it panics.
Report an issue with this page or with FutureBlitz on GitHub.