httpd/server
start and stop HTTP servers.
Since: H6 (pool dispatch added in H7; runs on stdlib httpd since
ServerOpts
(defstruct ServerOpts [])
configuration for server-start-opts / server-start-conn-opts.
Since: tourist-on-stdlib-httpd H2
default-server-opts
(default-server-opts :)
the settings server-start uses.
ServerOpts
(server-start-opts 8080 my-handler
(make-struct ServerOpts 16 1048576 2000))
Since: tourist-on-stdlib-httpd H2
take-conn-response
(take-conn-response [hc ptr<void>] :)
move what a stdlib helper wrote on the conn into a
| hc | the stdlib httpd conn of the current request (request-conn) |
Response -- owned by the caller, like any handler's Response.
(if (httpd-static-serve! hc "./public" path)
(take-conn-response hc)
(not-found))
Since: tourist-on-stdlib-httpd H5
serve-httpd-request
(serve-httpd-request [hc ptr<void> handler : (c-fn [int])
internal: serve one stdlib httpd request with a
Since: tourist-on-stdlib-httpd H2
serve-httpd-request-conn
(serve-httpd-request-conn [hc ptr<void> handler : (c-fn [int int])
internal: serve one stdlib httpd request with a
Since: tourist-on-stdlib-httpd H2
server-launch
(server-launch [h ptr<void>] :)
internal: run a stdlib httpd server on a background
| h | a stdlib httpd pool server handle, or NULL |
:ptr<void> -- the server handle for server-stop, or NULL.
Since: tourist-on-stdlib-httpd H2
server-tls-ctx
(server-tls-ctx [s ptr<void>] :)
internal: the TLS context recorded on a server handle.
server-set-tls-ctx!
(server-set-tls-ctx! [s ptr<void> ctx : int] :)
internal: record the TLS context httpd/tls frees.
server-start
(server-start [port : int handler : (c-fn [int])
bind a TCP listener on `port` and dispatch requests to
| port | TCP port to bind on (0 = kernel-assigned; see server-port). | |
| 127.0.0.1 unless the program called httpd-set-bind-any! or | ||
| httpd-set-bind-addr!. | ||
| handler | captureless `(c-fn [int] int)` request handler. Define | |
| it as a top-level defn of type `[req : int] : int` | ||
| returning a Response handle, and pass the defn name. | ||
| The handler is invoked from a worker thread; it must be | ||
| Send-safe. The server takes ownership of the Response | ||
| it returns (it is freed after the response is written). |
:ptr<void> -- opaque server handle. Pass to server-stop to shut down, or NULL if the listening socket could not be created.
(defn my-handler [req :int] :int
(resp-ok "text/plain" "Hello"))
(let [srv (server-start 8080 my-handler)]
;; ... handle SIGINT, etc. ...
(server-stop srv))
Since: H6 (pool default added in H7)
server-start-pool
(server-start-pool [port : int handler : (c-fn [int])
like server-start but with an explicit pool size.
| port | TCP port to bind on | |
| handler | (c-fn [int] int) request handler (see server-start) | |
| size | number of worker threads in the pool (clamped to >= 1) |
:ptr<void> -- opaque server handle, or NULL on failure.
(def srv (server-start-pool 8080 my-handler 32))
Since: H7
server-start-opts
(server-start-opts [port : int handler : (c-fn [int])
like server-start, configured by a ServerOpts.
| port | TCP port to bind on | |
| handler | (c-fn [int] int) request handler (see server-start) | |
| opts | ServerOpts (pool size, body cap, read timeout) |
:ptr<void> -- opaque server handle, or NULL on failure.
(server-start-opts 8080 my-handler (make-struct ServerOpts 8 65536 1000))
Since: tourist-on-stdlib-httpd H2
server-start-conn
(server-start-conn [port : int handler : (c-fn [int int])
like server-start, but the handler receives a Conn
| port | TCP port to bind on | |
| handler | captureless `(c-fn [int int] int)`. Define it as a top-level | |
| `(defn h [conn : Conn req : Request] : Response ...)` and pass | ||
| the name. |
:ptr<void> -- opaque server handle, or NULL on failure.
Since: WS0
server-start-pool-conn
(server-start-pool-conn [port : int handler : (c-fn [int int])
like server-start-conn but with an explicit pool
| port | TCP port to bind on | |
| handler | (c-fn [int int] int) (Conn, Request) -> Response handler | |
| size | number of worker threads (clamped to >= 1) |
:ptr<void> -- opaque server handle, or NULL on failure.
Since: WS0
server-start-conn-opts
(server-start-conn-opts [port : int handler : (c-fn [int int])
like server-start-conn, configured by a ServerOpts.
| port | TCP port to bind on | |
| handler | (c-fn [int int] int) (Conn, Request) -> Response handler | |
| opts | ServerOpts (pool size, body cap, read timeout) |
:ptr<void> -- opaque server handle, or NULL on failure.
Since: tourist-on-stdlib-httpd H2
ServerWrap
(ServerWrap)
a function that puts stdlib middleware around a server's
Since: tourist-on-stdlib-httpd H4
server-wrap
(server-wrap [^fat f : (fn [ptr<void>] ptr<void>)])
package a wrap function for server-start-wrapped.
| f | (fn [ptr<void>] ptr<void>), called once when the server starts |
ServerWrap -- pass to exactly one server-start-wrapped call
(server-wrap (fn [inner : ptr<void>] : ptr<void>
(compose-middleware inner mw-recover mw-log)))
Since: tourist-on-stdlib-httpd H4
server-start-wrapped
(server-start-wrapped [port : int handler : (c-fn [int])
server-start-opts with stdlib middleware around
| port | TCP port to bind on | |
| handler | (c-fn [int] int) request handler (see server-start) | |
| opts | ServerOpts (pool size, body cap, read timeout) | |
| wrap | ServerWrap from server-wrap; called once and released, so | |
| build one per server |
:ptr<void> -- opaque server handle, or NULL on failure.
(server-start-wrapped 8080 my-handler (default-server-opts)
(server-wrap (fn [inner : ptr<void>] : ptr<void>
(compose-middleware inner mw-recover mw-log))))
Since: tourist-on-stdlib-httpd H4
server-start-conn-wrapped
(server-start-conn-wrapped [port : int handler : (c-fn [int int])
server-start-conn-opts with stdlib middleware
| port | TCP port to bind on | |
| handler | (c-fn [int int] int) (Conn, Request) -> Response handler | |
| opts | ServerOpts (pool size, body cap, read timeout) | |
| wrap | ServerWrap from server-wrap; called once and released |
:ptr<void> -- opaque server handle, or NULL on failure.
Since: tourist-on-stdlib-httpd H4
server-start-spawn
(server-start-spawn [port : int handler : (c-fn [int])
compatibility entry point: a pool of 64 workers.
| port | TCP port to bind on | |
| handler | (c-fn [int] int) request handler (see server-start) |
:ptr<void> -- opaque server handle, or NULL on failure.
(def srv (server-start-spawn 8080 my-handler))
Since: H7
server-port
(server-port [s ptr<void>] :)
the TCP port a server is listening on.
| s | server handle from a server-start* function |
:int -- the port, or -1 for a NULL handle.
(let [srv (server-start 0 my-handler)]
(println (server-port srv)))
Since: tourist-on-stdlib-httpd H2
server-stop
(server-stop [s ptr<void>] :)
stop the server and release it.
| s | :ptr<void> server handle returned by server-start (or NULL: no-op). |
:void
(server-stop srv)
Since: H6 (pool join added in H7)
Internal definitions
srv-call-handlersrv-call-handler-connsrv-send-responsesrv-null?srv-serve-viewsrv-serve-view-connsrv-null-ptrsrv-run-loopsrv-state-hsrv-state-joinsrv-state-freesrv-spawnsrv-clamp-poolsrv-apply-optssrv-default-pool-sizesrv-wrap-apply