tobogganSe connecter

louise

The Louise language: compiler, runtime, std, tooling

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

1691 lignes · 49785 octetsBrut · Historique
1/// A small HTTP/1.1 server (native programs only).
2///
3/// pub fn main() -> () / <io, proc> {
4/// match http.listen("0.0.0.0", 8080) {
5/// Ok(server) -> http.serve(server, fn(req) {
6/// http.html(<h1>{"Hello from " <> req.path}</h1>)
7/// }),
8/// Error(e) -> io.eprintln(e),
9/// }
10/// }
11///
12/// Each connection is handled by an actor of its own, which serves its
13/// requests one after another (keep-alive; ADR 0012):
14/// - an HTTP/1.1 connection stays open unless the request or the response
15/// has `Connection: close`; an HTTP/1.0 one only if the request has
16/// `Connection: keep-alive`;
17/// - a connection that waits longer than the idle timeout for a request
18/// to start, or for more of a body, is closed; so is one whose request
19/// head, once begun, takes longer than the head timeout to arrive whole
20/// (a client that trickles it), and one whose response takes longer
21/// than the write timeout to send (a client that stops reading); the
22/// handler is not timed;
23/// - at most `max_open` connections are open at once. At the limit, the
24/// next client is accepted and held while the oldest connection is
25/// asked to close: at once if it waits for a request, else after its
26/// current response (`Connection: close`). So kept-alive clients cannot
27/// starve waiting ones (issue #304), and the next client gets in within
28/// about one response time. A streamed response is not cut: its
29/// connection closes when the stream ends;
30/// - a connection serves at most `max_requests` requests: the last one is
31/// answered with `Connection: close`, and the client reconnects;
32/// - request bodies are read whole, sized by `Content-Length` or chunked
33/// (`Transfer-Encoding: chunked`), up to a size limit (413 beyond it),
34/// which can be larger under some path prefixes (`large_bodies`); a
35/// malformed request gets an error response, and the connection is
36/// closed;
37/// - the server sets `Content-Length` and `Connection` on responses, except
38/// that final 204 and 304 responses have no content length or body;
39/// - a response can be **streamed** (ADR 0053): the head goes out with
40/// `Transfer-Encoding: chunked`, the handler's stream fn writes chunks
41/// (each flushed, each write timed per chunk; the stream between chunks
42/// is not timed), and keep-alive continues after the final chunk.
43/// Server-Sent Events are a streamed response that stays open. A response
44/// with final status 204 or 304 sends no framing, chunks or final chunk, and
45/// does not call the stream fn.
46///
47/// Request heads and chunk sizes are parsed by httparse (picohttpparser's
48/// design) in the runtime.
49
50import std/bytes.{type Builder}
51import std/dict.{type Dict}
52import std/ffi.{type Resource}
53import std/html.{type Html}
54import std/int
55import std/io
56import std/list
57import std/net.
58{type SocketAddress, type TcpListener, type TcpStream, SocketAddress}
59import std/option
60import std/process.
61{type ExitReason, type Pid, type Subject, type proc, Crashed, Down}
62import std/random.{type random}
63import std/result
64import std/string
65import std/time.{type clock}
66
67pub type Request
68{ Request(
69 method: String
70 , path: String
71 , headers: List<(String, String)>
72 , body: Bytes
73 )
74}
75
76pub type Response
77{ Response(status: Int, headers: List<(String, String)>, body: Body) }
78
79/// What a response's body is (ADR 0053).
80pub type Body
81{ /// The whole body, in hand.
82 Whole(Bytes)
83 /// Written chunk by chunk: the server sends the head with
84 /// `Transfer-Encoding: chunked`, then calls `write` with a `Writer`
85 /// and sends the final chunk when it returns. Between chunks the
86 /// connection is not timed; each chunk's write is, per chunk, by the
87 /// write timeout. A 204 or 304 response skips `write` and sends neither
88 /// framing nor a final chunk. A HEAD request for any other status
89 /// sends the head only: `write` runs with a writer whose every write fails,
90 /// so it stops, and whatever cleanup it does on a failed write runs (#363).
91 /// If `write` unwinds, the connection dies without the final
92 /// chunk: the client sees a truncated stream, the only honest end
93 /// once the status line is sent.
94, Streamed(write: fn(Writer) -> () / <io, proc, clock, random, ffi>)
95}
96
97/// What a streamed response writes with (ADR 0053): the connection,
98/// memory when the body is read in hand (`collect_body`), or nothing, for
99/// a HEAD request, whose writes all fail.
100pub opaque type Writer
101{ Socket(conn: Resource<TcpStream>, activity: Subject<Activity>)
102, Memory(chunks: Subject<Bytes>)
103, Headless
104}
105
106/// Write one chunk, flushed (one frame, one socket write). `Error` says
107/// the client is gone: stop writing. An empty chunk writes nothing: its
108/// frame would be the chunked encoding's last one, ending the body.
109pub fn write_chunk :: w: Writer chunk: Bytes -> Result<(), String> / <io, proc>
110{
111 match w
112 { _ if bytes.length chunk == 0 -> Ok(())
113 , Socket(conn, activity) ->
114 {
115 process.send activity Writing
116 match net.write conn (frame chunk)
117 { Ok(()) ->
118 {
119 process.send activity Streaming
120 Ok(())
121 }
122 , Error(e) -> Error(e)
123 }
124 }
125 , Memory(chunks) ->
126 {
127 process.send chunks chunk
128 Ok(())
129 }
130 , Headless -> Error("a HEAD request has no body")
131 }
132}
133
134/// Write one chunk of text, flushed.
135pub fn write_string :: w: Writer text: String -> Result<(), String> / <io, proc>
136{
137 write_chunk w (bytes.from_string text)
138}
139
140/// A chunk's frame: its length in hex, CRLF, the data, CRLF.
141fn frame :: chunk: Bytes -> Bytes
142{
143 let head = to_hex (bytes.length chunk) <> "\r\n"
144 bytes.concat_all [bytes.from_string head, chunk, bytes.from_string "\r\n"]
145}
146
147fn to_hex :: n: Int -> String
148{
149 if n <= 0
150 {
151 "0"
152 }
153 else
154 {
155 hex_up n ""
156 }
157}
158
159fn hex_up :: n: Int acc: String -> String
160{
161 if n == 0
162 {
163 acc
164 }
165 else
166 {
167 hex_up (int.shift_right n 4) (hex_digit (int.and n 15) <> acc)
168 }
169}
170
171fn hex_digit :: d: Int -> String
172{
173 match d
174 { 0 -> "0"
175 , 1 -> "1"
176 , 2 -> "2"
177 , 3 -> "3"
178 , 4 -> "4"
179 , 5 -> "5"
180 , 6 -> "6"
181 , 7 -> "7"
182 , 8 -> "8"
183 , 9 -> "9"
184 , 10 -> "a"
185 , 11 -> "b"
186 , 12 -> "c"
187 , 13 -> "d"
188 , 14 -> "e"
189 , _ -> "f"
190 }
191}
192
193/// Change the defaults with a record update:
194/// `Settings(..http.defaults(), idle_timeout: 1000)`.
195pub type Settings
196{ /// - `connections`: serve this many connections, then return (all of
197 /// them if negative);
198 /// - `idle_timeout`: close a connection that waits this many
199 /// milliseconds for a request to start, or for more of a body (never
200 /// if negative);
201 /// - `write_timeout`: close a connection whose response takes longer
202 /// than this many milliseconds to send (never if negative);
203 /// - `max_body`: answer 413 to a request whose body is larger than this
204 /// many bytes, and close the connection (no limit if negative);
205 /// - `large_bodies`: other body limits for some paths, as `(prefix,
206 /// limit)`: the first prefix that matches the request's path on whole
207 /// segments (`/uploads` matches `/uploads` and `/uploads/a`, not
208 /// `/uploadsx`) sets its limit instead of `max_body` (see
209 /// `body_limit`). The 413 still comes before any byte of the body is
210 /// read;
211 /// - `max_open`: keep at most this many connections open at once (no
212 /// limit if negative). At the limit, the next client is held (one
213 /// more open socket) and the oldest connection asked to close, at once
214 /// if it waits for a request, else after its current response;
215 /// - `max_requests`: answer this many requests on one connection, the
216 /// last with `Connection: close` (no limit if negative);
217 /// - `head_timeout`: close a connection whose request head, once begun,
218 /// takes longer than this many milliseconds to arrive whole (never if
219 /// negative);
220 /// - `drain_timeout`: once `serve_until` is told to stop, give the
221 /// requests in flight this many milliseconds to finish, then close
222 /// their connections (no limit if negative).
223 Settings(
224 connections: Int
225 , idle_timeout: Int
226 , write_timeout: Int
227 , max_body: Int
228 , large_bodies: List<(String, Int)>
229 , max_open: Int
230 , head_timeout: Int
231 , max_requests: Int
232 , drain_timeout: Int
233 )
234}
235
236/// Every connection, at most 512 at once (under the usual limit of 1024
237/// open files, so the limit is reached before `accept` fails); closed
238/// after 5 idle seconds, when a request head takes over 10 seconds to
239/// arrive, when a response takes over 30 seconds to send, or after 1,000
240/// requests (nginx's `keepalive_requests`); bodies up to 1 MiB on every
241/// path; 10 seconds to drain when stopped.
242pub fn defaults :: -> Settings
243{
244 Settings( connections: -1
245 , idle_timeout: 5000
246 , write_timeout: 30000
247 , max_body: 1048576
248 , large_bodies: []
249 , max_open: 512
250 , head_timeout: 10000
251 , max_requests: 1000
252 , drain_timeout: 10000
253 )
254}
255
256/// The client's address (issue #308): the other end of the connection the
257/// request came on, as the server accepted it. Behind a proxy, that is
258/// the proxy: see `client_address`. `None` for a request built by hand
259/// (in tests).
260///
261/// The server puts it among the request's headers as the pseudo-header
262/// `:peer` (`"127.0.0.1:52144"`, `"[::1]:52144"`), which no client can
263/// send: a header name cannot contain `:`. It is found anywhere in the
264/// list (issue #313); a server-built request always has it first.
265/// `wire_headers` leaves it out.
266pub fn peer :: req: Request -> Option<SocketAddress>
267{
268 option.then (find_header req.headers ":peer") parse_address
269}
270
271/// `req` as if it arrived from `address` (for tests): the `:peer`
272/// pseudo-header first, where the server puts it.
273pub fn with_peer :: req: Request address: SocketAddress -> Request
274{
275 Request(..req, headers: [(":peer", address_text address), ..req.headers])
276}
277
278/// `host:port`, or `[host]:port` for an IPv6 host.
279fn parse_address :: value: String -> Option<SocketAddress>
280{
281 let ( host
282 , port
283 ) = if string.starts_with value "["
284 {
285 match string.split (string.slice value 1 (string.length value)) "]:"
286 { [host, port] -> (host, port), _ -> ("", "") }
287 }
288 else
289 {
290 match string.split value ":" { [host, port] -> (host, port), _ -> ("", "") }
291 }
292 match string.to_int port
293 { Ok(port) -> if host == "" { None } else { Some(SocketAddress(host, port)) }
294 , Error(_) -> None
295 }
296}
297
298/// How the server writes a peer in `:peer`.
299fn address_text :: address: SocketAddress -> String
300{
301 let host = if string.contains address.host ":"
302 {
303 "[" <> address.host <> "]"
304 }
305 else
306 {
307 address.host
308 }
309 host <> ":" <> show address.port
310}
311
312/// The headers the client sent, without the server's pseudo-headers
313/// (`:peer`): what to forward or log.
314pub fn wire_headers :: req: Request -> List<(String, String)>
315{
316 use h <- list.filter req.headers
317 !string.starts_with h.0 ":"
318}
319
320/// The client's IP address, through the proxies in `trusted` (exact
321/// addresses, as text). When the peer is not trusted, it is the client:
322/// its `X-Forwarded-For`, which anyone can send, is ignored. When it is,
323/// the client is the right-most `X-Forwarded-For` entry that is not
324/// trusted (each proxy appends the address it got the request from), or
325/// the left-most one if all are; with no entries, the peer itself.
326/// `None` without a peer (a request built by hand).
327///
328/// // Behind one nginx on 10.0.0.2:
329/// http.client_address(req, ["10.0.0.2"])
330pub fn client_address :: req: Request trusted: List<String> -> Option<String>
331{
332 match peer req
333 { None -> None
334 , Some(p) -> if !is_trusted trusted p.host
335 {
336 Some(p.host)
337 }
338 else
339 {
340 Some(untrusted_hop (list.reverse (forwarded_for req)) trusted p.host)
341 }
342 }
343}
344
345/// Every `X-Forwarded-For` entry, in order, across repeated headers.
346fn forwarded_for :: req: Request -> List<String>
347{
348 use h <- list.flat_map req.headers
349 if string.eq_ignore_ascii_case h.0 "x-forwarded-for"
350 {
351 string.split h.1 ","
352 |> list.map string.trim
353 |> list.filter fn entry { entry != "" }
354 }
355 else
356 {
357 []
358 }
359}
360
361/// The first of `hops` (right-most first) not in `trusted`, else the
362/// last one seen (`seen`: the peer, before any).
363fn untrusted_hop ::
364 hops: List<String>
365 trusted: List<String>
366 seen: String
367 -> String
368{
369 match hops
370 { [] -> seen
371 , [ hop
372 , ..rest
373 ] -> if is_trusted trusted hop
374 {
375 untrusted_hop rest trusted hop
376 }
377 else
378 {
379 hop
380 }
381 }
382}
383
384fn is_trusted :: trusted: List<String> address: String -> Bool
385{
386 list.any trusted fn t { t == address }
387}
388
389/// The value of header `name` (case-insensitive), if present.
390pub fn header :: req: Request name: String -> Option<String>
391{
392 find_header req.headers name
393}
394
395fn find_header :: headers name
396{
397 match headers
398 { [] -> None
399 , [(k, v), ..rest] -> if string.eq_ignore_ascii_case k name
400 {
401 Some(v)
402 }
403 else
404 {
405 find_header rest name
406 }
407 }
408}
409
410/// The request body as text, if it is valid UTF-8.
411pub fn body_text :: req: Request -> Result<String, String>
412{
413 bytes.to_string req.body
414}
415
416/// The fields of a form-encoded request body (see `form`).
417pub fn form_body :: req: Request -> List<(String, String)>
418{
419 form (bytes.to_string_lossy req.body)
420}
421
422/// A response with `body` of type `content_type`.
423pub fn response :: status: Int content_type: String body: Bytes -> Response
424{
425 Response(status, [("Content-Type", content_type)], Whole(body))
426}
427
428/// A 200 response written chunk by chunk (ADR 0053): the head goes out
429/// first (`Transfer-Encoding: chunked`), then `write` runs with a
430/// `Writer`; each `write_chunk`/`write_string` flushes. Between chunks
431/// the connection is not timed; each write is, per chunk. Keep-alive
432/// continues after the final chunk.
433///
434/// http.stream("text/html; charset=utf-8", fn(w) {
435/// let _ = http.write_string(w, html.render(shell_top))
436/// // each component, as it finishes
437/// let _ = http.write_string(w, "</body></html>")
438/// })
439pub fn stream ::
440 content_type: String
441 write: fn(Writer) -> () / <io, proc, clock, random, ffi>
442 -> Response
443{
444 Response(200, [("Content-Type", content_type)], Streamed(write))
445}
446
447/// The body a response holds, if it is a whole one (a streamed response's
448/// body is written, not held).
449pub fn whole_body :: resp: Response -> Option<Bytes>
450{
451 match resp.body { Whole(body) -> Some(body), Streamed(_) -> None }
452}
453
454/// A response's body in hand: a streamed one is written into memory,
455/// chunk by chunk, as the server would send it. For tests and tools: the
456/// whole body is held at once.
457pub fn collect_body :: resp: Response -> Bytes / <io, proc, clock, random, ffi>
458{
459 match resp.body
460 { Whole(body) -> body
461 , Streamed(write) ->
462 {
463 let chunks = process.subject ()
464 write Memory(chunks)
465 bytes.concat_all (written chunks [])
466 }
467 }
468}
469
470/// The chunks a memory writer was given, in order.
471fn written :: chunks: Subject<Bytes> held: List<Bytes> -> List<Bytes> / <proc>
472{
473 match process.receive chunks 0
474 { Some(chunk) -> written chunks [chunk, ..held], None -> list.reverse held }
475}
476
477/// A 200 response with a rendered page.
478pub fn html :: page: Html -> Response
479{
480 response 200 "text/html; charset=utf-8" (bytes.from_string (html.render page))
481}
482
483/// A plain-text response.
484pub fn text :: status: Int body: String -> Response
485{
486 response status "text/plain; charset=utf-8" (bytes.from_string body)
487}
488
489pub fn not_found :: -> Response
490{
491 text 404 "not found"
492}
493
494/// `resp` with the header `name: value` added, after the ones it has
495/// (headers can repeat: each `Set-Cookie` is its own header).
496pub fn with_header :: resp: Response name: String value: String -> Response
497{
498 Response(..resp, headers: list.append resp.headers [(name, value)])
499}
500
501/// Listen for HTTP connections.
502pub fn listen ::
503 host: String
504 port: Int
505 -> Result<Resource<TcpListener>, String> / <io>
506{
507 net.listen host port
508}
509
510/// Serve forever with the default settings.
511pub fn serve ::
512 server: Resource<TcpListener>
513 handler: send fn(Request) -> Response / <io, proc, clock, random, ffi>
514 -> () / <io, proc>
515{
516 serve_with server (defaults ()) handler
517}
518
519/// Serve with `settings`: one actor per connection. When this returns,
520/// the last connections' actors may still be running.
521pub fn serve_with ::
522 server: Resource<TcpListener>
523 settings: Settings
524 handler: send fn(Request) -> Response / <io, proc, clock, random, ffi>
525 -> () / <io, proc>
526{
527 accept_all
528 server
529 settings
530 handler
531 (process.subject ())
532 Open(0, dict.empty (), 0, False)
533 10
534}
535
536/// Serve with `settings` until a message arrives on `stop`, then stop
537/// gracefully (ADR 0060): new clients are refused at once; idle
538/// connections are closed, and busy ones after their current response
539/// (with `Connection: close`); after `settings.drain_timeout`, the
540/// connections still open are closed. Returns once every connection is.
541///
542/// `stop` is one of the calling actor's subjects, and any message on it
543/// stops the server: `os.signals([Term])` for a program that stops on
544/// SIGTERM, `process.exits()` for a `main` that traps exits under
545/// `[application]` (ADR 0060), or a `process.subject()` another actor
546/// sends on.
547pub fn serve_until ::
548 server: Resource<TcpListener>
549 settings: Settings
550 handler: send fn(Request) -> Response / <io, proc, clock, random, ffi>
551 stop: Subject<m>
552 -> () / <io, proc>
553{
554 let ready = process.subject ()
555 let (_, done) =
556 process.spawn_monitor
557 fn
558 {
559 let events = process.subject ()
560 process.send ready events
561 accept_all
562 server
563 settings
564 handler
565 events
566 Open(0, dict.empty (), 0, False)
567 10
568 }
569 let events = process.receive_forever ready
570 let stopped =
571 process.new_selector ()
572 |> process.selecting stop fn _ { True }
573 |> process.selecting done fn _ { False }
574 if process.select_forever stopped
575 {
576 // Wakes the acceptor, parked in `accept`, which then drains.
577 process.send events Stop
578 net.close_listener server
579 let Down(_, reason) = process.receive_forever done
580 stopped_with reason
581 }
582 else
583 {
584 // `settings.connections` were served.
585 ()
586 }
587}
588
589/// The acceptor's end: a crash is `serve_until`'s.
590fn stopped_with :: reason: ExitReason -> ()
591{
592 match reason
593 { Crashed(message) -> panic ("http: the acceptor crashed: " <> message)
594 , _ -> ()
595 }
596}
597
598/// Accept connections while `settings.connections` lasts. Their
599/// watchdogs report on `events` when they open and end. After a failed
600/// `accept` (out of file descriptors, say), wait `pause` milliseconds,
601/// doubling up to a second while it keeps failing (ADR 0012, Revision 2).
602fn accept_all ::
603 server
604 settings: Settings
605 handler
606 events: Subject<Event>
607 open: Open
608 pause: Int
609 -> () / <io, proc>
610{
611 if settings.connections != 0
612 {
613 let next = Settings(..settings, connections: settings.connections - 1)
614 match net.accept server
615 { Ok(conn) ->
616 {
617 // At `max_open`, this client is held until there is room (or the
618 // server stops: it is served, then drained).
619 let open =
620 make_room
621 events
622 (take_events events open False)
623 settings.max_open
624 False
625 let id = open.next
626 let _ =
627 process.spawn fn { handle_connection conn id settings handler events }
628 accept_all
629 server
630 next
631 handler
632 events
633 Open(..open, count: open.count + 1, next: id + 1)
634 10
635 }
636 , Error(e) ->
637 {
638 let open = take_events events open False
639 if open.stopping
640 {
641 drain events open settings.drain_timeout
642 }
643 else
644 {
645 io.eprintln ("http: accept failed: " <> e)
646 process.sleep pause
647 accept_all
648 server
649 next
650 handler
651 events
652 open
653 if pause >= 500 { 1000 } else { pause * 2 }
654 }
655 }
656 }
657 }
658 else
659 {
660 ()
661 }
662}
663
664/// Stop serving (`serve_until`): ask every open connection to close
665/// (idle ones at once, busy ones after their response), and wait until
666/// they have, for `timeout` milliseconds at most; then close the rest.
667fn drain :: events: Subject<Event> open: Open timeout: Int -> () / <proc>
668{
669 let asked =
670 list.map (dict.to_list open.closable) fn entry { ask_to_close entry.1 }
671 let timer = if timeout >= 0
672 {
673 Some( process.spawn
674 fn
675 {
676 process.sleep timeout
677 process.send events DrainOver
678 }
679 )
680 }
681 else
682 {
683 None
684 }
685 wait_drained events open.count asked
686 match timer { Some(pid) -> process.kill pid, None -> () }
687}
688
689/// Ask a connection to close: its actor and its watchdog (see `Opened`).
690/// Returns its actor's subject.
691fn ask_to_close :: subjects: (Subject<()>, Subject<()>) -> Subject<()> / <proc>
692{
693 let (actor, watchdog) = subjects
694 process.send actor ()
695 process.send watchdog ()
696 actor
697}
698
699/// Wait until `count` connections have ended, asking those that open
700/// meanwhile (accepted just before the stop) to close too; at
701/// `DrainOver`, stop the actors of those asked.
702fn wait_drained ::
703 events: Subject<Event>
704 count: Int
705 asked: List<Subject<()>>
706 -> () / <proc>
707{
708 if count > 0
709 {
710 match process.receive_forever events
711 { Ended(_) -> wait_drained events (count - 1) asked
712 , Opened(_, actor, watchdog) ->
713 wait_drained events count [ask_to_close (actor, watchdog), ..asked]
714 , DrainOver ->
715 list.each asked fn actor { process.kill (process.owner actor) }
716 , Stop -> wait_drained events count asked
717 }
718 }
719 else
720 {
721 ()
722 }
723}
724
725/// What a connection's watchdog tells the acceptor.
726type Event
727{ /// Connection `id` is open: a `()` on both subjects (its actor's, its
728 /// watchdog's) asks it to close.
729 Opened(id: Int, actor: Subject<()>, watchdog: Subject<()>)
730 /// Connection `id` ended.
731, Ended(id: Int)
732 /// `serve_until` was told to stop: drain once `accept` fails.
733, Stop
734 /// The drain timeout passed.
735, DrainOver
736}
737
738/// The acceptor's view: `count` connections open, those it may still ask
739/// to close by id (ids grow, so the least is the oldest), the next id,
740/// and whether `serve_until` was told to stop.
741type Open
742{ Open(
743 count: Int
744 , closable: Dict<Int, (Subject<()>, Subject<()>)>
745 , next: Int
746 , stopping: Bool
747 )
748}
749
750/// `open` after the events received so far; with `wait`, after waiting
751/// for one first.
752fn take_events :: events: Subject<Event> open: Open wait: Bool -> Open / <proc>
753{
754 match process.receive events if wait { -1 } else { 0 }
755 { Some(Opened(id, actor, watchdog)) ->
756 take_events
757 events
758 Open(..open, closable: dict.insert open.closable id (actor, watchdog))
759 False
760 , Some(Ended(id)) ->
761 take_events
762 events
763 Open( ..open
764 , count: open.count - 1
765 , closable: dict.remove open.closable id
766 )
767 False
768 , Some(Stop) -> take_events events Open(..open, stopping: True) False
769 , Some(DrainOver) -> take_events events open False
770 , None -> open
771 }
772}
773
774/// `open` once a connection more fits under `max_open`. While full, the
775/// oldest connection not asked yet is asked to close (once per held
776/// client, `asked`), and the acceptor waits for one to end: that one, or
777/// any other.
778fn make_room ::
779 events: Subject<Event>
780 open: Open
781 max_open: Int
782 asked: Bool
783 -> Open / <proc>
784{
785 if max_open < 0 || open.count < max_open || open.stopping
786 {
787 open
788 }
789 else
790 {
791 let (open, asked) = match (asked, dict.first open.closable)
792 { (False, Some((id, (actor, watchdog)))) ->
793 {
794 process.send actor ()
795 process.send watchdog ()
796 (Open(..open, closable: dict.remove open.closable id), True)
797 }
798 , _ -> (open, asked)
799 }
800 make_room events (take_events events open True) max_open asked
801 }
802}
803
804/// What a connection's watchdog learns.
805type Activity
806{ /// The connection's actor waits for a request to start: timed by
807 /// `idle_timeout`. Asked to close now, the connection closes at once.
808 Idle
809 /// It waits for more of a body: timed by `idle_timeout` from each read.
810, Reading
811 /// A request head has begun and is not whole yet: timed by
812 /// `head_timeout` from here, once, since nothing else is sent until the
813 /// head is read.
814, HeadStarted
815 /// It runs the handler: not timed.
816, Handling
817 /// It sends a response: timed.
818, Writing
819 /// A streamed response, between chunks: not timed (a stream may be
820 /// quiet arbitrarily long); each chunk's write is `Writing`.
821, Streaming
822 /// It stopped (also by crashing).
823, Stopped
824 /// The acceptor asks the connection to close (at `max_open`, for a
825 /// waiting client): the watchdog closes it if it is `Idle`; otherwise
826 /// its actor answers the current request with `Connection: close`.
827, Drain
828}
829
830fn handle_connection ::
831 conn: Resource<TcpStream>
832 id: Int
833 settings: Settings
834 handler: fn(Request) -> Response / <io, proc, clock, random, ffi>
835 events: Subject<Event>
836 -> () / <io, proc, clock, random, ffi>
837{
838 let me = process.self ()
839 let ready = process.subject ()
840 let drain = process.subject ()
841 let _ = process.spawn fn { watchdog conn me id drain settings ready events }
842 let activity = process.receive_forever ready
843 let peer = match net.peer conn
844 { Ok(address) -> [(":peer", address_text address)], Error(_) -> [] }
845 let serving = Serving(conn, peer, activity, drain, settings, handler)
846 serve_requests serving (bytes.empty ()) 0 0
847 net.close conn
848}
849
850/// Close the connection when it waits too long for a request, takes too
851/// long to send its head, or takes too long to send a response: its actor
852/// then reads the end of the stream, or fails to write, and stops. The
853/// watchdog monitors that actor, and stops with it, releasing its
854/// reference to the socket. It tells the acceptor that the connection
855/// opened, with how to ask it to close (`drain`, its actor's subject, and
856/// one of its own), and, once, that it ended (for `max_open`).
857fn watchdog ::
858 conn: Resource<TcpStream>
859 owner: Pid
860 id: Int
861 drain: Subject<()>
862 settings: Settings
863 ready: Subject<Subject<Activity>>
864 acceptor: Subject<Event>
865 -> () / <io, proc>
866{
867 let activity = process.subject ()
868 let asked = process.subject ()
869 let down = process.monitor owner
870 process.send ready activity
871 process.send acceptor Opened(id, drain, asked)
872 let events =
873 process.new_selector ()
874 |> process.selecting activity fn a { a }
875 |> process.selecting down fn _ { Stopped }
876 |> process.selecting asked fn _ { Drain }
877 watch conn settings events settings.idle_timeout True
878 process.send acceptor Ended(id)
879}
880
881/// `idle`: the actor waits for a request to start. (A `Drain` otherwise
882/// restarts the current timeout; it comes at most once.) Closing an idle
883/// connection races with a request just sent, as the idle timeout does:
884/// a client retries it on a new connection (RFC 9112, section 9.3.1).
885fn watch :: conn settings: Settings events timeout idle: Bool
886{
887 match process.select events timeout
888 { None -> net.close conn
889 , Some(Idle) -> watch conn settings events settings.idle_timeout True
890 , Some(Reading) -> watch conn settings events settings.idle_timeout False
891 , Some(HeadStarted) -> watch conn settings events settings.head_timeout False
892 , Some(Handling) -> watch conn settings events (-1) False
893 , Some(Writing) -> watch conn settings events settings.write_timeout False
894 , Some(Streaming) -> watch conn settings events (-1) False
895 , Some
896 ( Drain
897 ) -> if idle
898 {
899 net.close conn
900 }
901 else
902 {
903 watch conn settings events timeout False
904 }
905 , Some(Stopped) -> ()
906 }
907}
908
909/// Why no request was read.
910type Failure
911{ /// The connection closed or failed: nothing to answer.
912 Closed
913 /// A malformed request, answered with `status` before closing.
914, Bad(status: Int, message: String)
915}
916
917/// A request, whether the client keeps the connection open after it, and
918/// where the next request starts (offset `at` of `buffer`).
919type Incoming
920{ Incoming(request: Request, keep_alive: Bool, buffer: Bytes, at: Int) }
921
922/// Serve the requests in `buffer` (from offset `at`), then those that
923/// arrive, until either side closes the connection.
924/// A connection's actor: the socket, its watchdog's subject, its own
925/// subject on which the acceptor asks it to close, and how to serve.
926type Serving
927{ Serving(
928 conn: Resource<TcpStream>
929 // `[(":peer", address)]`, or none if it is not known: put first among
930 // every request's headers (`peer`).
931 , peer: List<(String, String)>
932 , activity: Subject<Activity>
933 , drain: Subject<()>
934 , settings: Settings
935 , handler: fn(Request) -> Response / <io, proc, clock, random, ffi>
936 )
937}
938
939/// Serve requests from `buffer` at `at`, `served` of them so far. The
940/// connection is kept unless the request, the response, the acceptor
941/// (`drain`) or `max_requests` says otherwise.
942fn serve_requests ::
943 serving: Serving
944 buffer: Bytes
945 at: Int
946 served: Int
947 -> () / <io, proc, clock, random, ffi>
948{
949 let conn = serving.conn
950 let activity = serving.activity
951 match read_request conn activity serving.settings buffer at
952 { Ok(Incoming(req, keep_alive, buffer, at)) ->
953 {
954 process.send activity Handling
955 let req = Request(..req, headers: list.append serving.peer req.headers)
956 // HEAD is GET without the body (RFC 9110 §9.3.2): the handler sees
957 // a GET, and the body is not sent (a stream fn is not called).
958 let with_body = req.method != "HEAD"
959 let req = if with_body { req } else { Request(..req, method: "GET") }
960 let handler = serving.handler
961 let resp = handler req
962 let served = served + 1
963 let closes =
964 find_header resp.headers "connection"
965 |> option.unwrap_or ""
966 |> has_token "close"
967 let max = serving.settings.max_requests
968 let drained = option.is_some (process.receive serving.drain 0)
969 let keep = keep_alive && !closes && !drained && (max < 0 || served < max)
970 let sent = if final_status_without_body resp.status
971 {
972 send_response
973 conn
974 activity
975 (bytes.from_string (head_bytes resp.status resp.headers keep ""))
976 }
977 else
978 {
979 match resp.body
980 { Whole(_) ->
981 send_response conn activity (serialize resp keep with_body)
982 , Streamed
983 ( write
984 ) -> if with_body
985 {
986 serve_streamed conn activity resp keep write
987 }
988 else
989 {
990 // HEAD: the head only. The stream fn still runs, and its first
991 // write fails, so what it started is stopped (#363).
992 let head =
993 send_response conn activity (serialize_stream_head resp keep)
994 write Headless
995 head
996 }
997 }
998 }
999 match sent
1000 { Ok(_) -> if keep { serve_requests serving buffer at served } else { () }
1001 , Error(_) -> ()
1002 }
1003 }
1004 , Error(Closed) -> ()
1005 , Error(Bad(status, message)) ->
1006 {
1007 let _ =
1008 send_response conn activity (serialize (text status message) False True)
1009 ()
1010 }
1011 }
1012}
1013
1014/// A streamed response (ADR 0053): the head (chunked, no length), the
1015/// stream fn, the final chunk. Between chunks the connection is untimed;
1016/// each write is timed per chunk by the watchdog.
1017fn serve_streamed ::
1018 conn: Resource<TcpStream>
1019 activity: Subject<Activity>
1020 resp: Response
1021 keep: Bool
1022 write: fn(Writer) -> () / <io, proc, clock, random, ffi>
1023 -> Result<(), String> / <io, proc, clock, random, ffi>
1024{
1025 use () <-
1026 result.try (send_response conn activity (serialize_stream_head resp keep))
1027 process.send activity Streaming
1028 write Socket(conn, activity)
1029 process.send activity Writing
1030 net.write conn (bytes.from_string "0\r\n\r\n")
1031}
1032
1033/// Write a response (timed by the watchdog).
1034fn send_response ::
1035 conn: Resource<TcpStream>
1036 activity: Subject<Activity>
1037 data: Bytes
1038 -> Result<(), String> / <io, proc>
1039{
1040 process.send activity Writing
1041 net.write conn data
1042}
1043
1044/// The largest request head, in bytes (431 beyond it).
1045fn head_limit :: -> Int
1046{
1047 65536
1048}
1049
1050fn read_request ::
1051 conn
1052 activity
1053 settings: Settings
1054 buffer: Bytes
1055 at: Int
1056 -> Result<Incoming, Failure> / <io, proc>
1057{
1058 match parse_head buffer at
1059 { Partial -> if bytes.length buffer > at
1060 {
1061 // A head has begun: it must arrive whole within `head_timeout`.
1062 process.send activity HeadStarted
1063 let begun = bytes.slice buffer at (bytes.length buffer)
1064 read_head
1065 conn
1066 activity
1067 settings
1068 (bytes.append (bytes.builder ()) begun)
1069 (bytes.length begun)
1070 (last_bytes begun)
1071 }
1072 else
1073 {
1074 // Waiting for a request to start: `idle_timeout`, and the acceptor
1075 // may close the connection now (`Idle`).
1076 process.send activity Idle
1077 match read_raw conn
1078 { Ok(more) -> read_request conn activity settings more 0
1079 , Error(e) -> Error(e)
1080 }
1081 }
1082 , head -> request_of conn activity settings head buffer at
1083 }
1084}
1085
1086/// The request whose head, from offset `at` of `buffer`, is `head`.
1087fn request_of ::
1088 conn
1089 activity
1090 settings: Settings
1091 head: Head
1092 buffer: Bytes
1093 at: Int
1094 -> Result<Incoming, Failure> / <io, proc>
1095{
1096 match head
1097 { Complete
1098 ( method
1099 , path
1100 , version
1101 , headers
1102 , end
1103 , length
1104 ) -> if end - at > head_limit ()
1105 {
1106 Error(Bad(431, "request head too large"))
1107 }
1108 else
1109 {
1110 let max_body = body_limit settings path
1111 match read_body conn activity max_body headers length buffer end
1112 { Ok((body, buffer, at)) ->
1113 Ok( Incoming( Request(method, path, headers, body)
1114 , keeps_alive version headers
1115 , buffer
1116 , at
1117 )
1118 )
1119 , Error(e) -> Error(e)
1120 }
1121 }
1122 , Invalid(reason) -> Error(Bad(400, "bad request: " <> reason))
1123 // Its end was found, yet it is incomplete: blank lines before the
1124 // request line, which would otherwise restart `head_timeout`.
1125 , Partial -> Error(Bad(400, "bad request: an empty head"))
1126 }
1127}
1128
1129/// Read the rest of a head begun in `received` (`size` bytes, ending in
1130/// `tail`), not reported to the watchdog, which times it by
1131/// `head_timeout`. Each read is scanned once for the head's end, with
1132/// the 3 bytes before it; then the head is built and parsed once (ADR
1133/// 0012, Revision 2).
1134fn read_head ::
1135 conn
1136 activity
1137 settings: Settings
1138 received: Builder
1139 size: Int
1140 tail: Bytes
1141 -> Result<Incoming, Failure> / <io, proc>
1142{
1143 if size > head_limit ()
1144 {
1145 Error(Bad(431, "request head too large"))
1146 }
1147 else
1148 {
1149 match read_raw conn
1150 { Ok(more) ->
1151 {
1152 let window = bytes.concat tail more
1153 let received = bytes.append received more
1154 if parse_head_end window 0 >= 0
1155 {
1156 let buffer = bytes.build received
1157 request_of conn activity settings (parse_head buffer 0) buffer 0
1158 }
1159 else
1160 {
1161 read_head
1162 conn
1163 activity
1164 settings
1165 received
1166 (size + bytes.length more)
1167 (last_bytes window)
1168 }
1169 }
1170 , Error(e) -> Error(e)
1171 }
1172 }
1173}
1174
1175/// The last 3 bytes of `b` (all of them if fewer): an end of head may
1176/// straddle two reads.
1177fn last_bytes :: b: Bytes -> Bytes
1178{
1179 let n = bytes.length b
1180 bytes.slice b if n > 3 { n - 3 } else { 0 } n
1181}
1182
1183/// Whether the client wants the connection kept open after its request.
1184fn keeps_alive :: version: Int headers: List<(String, String)> -> Bool
1185{
1186 let connection = option.unwrap_or (find_header headers "connection") ""
1187 if version == 0
1188 {
1189 has_token connection "keep-alive"
1190 }
1191 else
1192 {
1193 !has_token connection "close"
1194 }
1195}
1196
1197/// Whether the comma-separated `value` lists `token` (lowercase).
1198fn has_token :: value: String token: String -> Bool
1199{
1200 list.any
1201 (string.split (string.to_lower value) ",")
1202 fn t { string.trim t == token }
1203}
1204
1205/// The body that starts at offset `at` of `buffer`, then where the next
1206/// request starts. A body over `max_body` bytes (if not negative) is not
1207/// read: it gets a 413, and the connection is closed.
1208fn read_body ::
1209 conn
1210 activity
1211 max_body: Int
1212 headers
1213 length: Int
1214 buffer: Bytes
1215 at: Int
1216 -> Result<(Bytes, Bytes, Int), Failure> / <io, proc>
1217{
1218 match find_header headers "transfer-encoding"
1219 { Some
1220 ( coding
1221 ) -> if length >= 0
1222 {
1223 // Two framings: reading the wrong one would desynchronize the
1224 // connection (request smuggling).
1225 Error(Bad(400, "bad request: both Content-Length and Transfer-Encoding"))
1226 }
1227 else if string.to_lower (string.trim coding) == "chunked"
1228 {
1229 continue_if_expected conn headers buffer at
1230 read_chunks conn activity max_body buffer at (bytes.builder ()) 0
1231 }
1232 else
1233 {
1234 Error(Bad(501, "unsupported Transfer-Encoding: " <> coding))
1235 }
1236 , None -> if too_large length max_body
1237 {
1238 // Before `100 Continue`: a waiting client does not send the body.
1239 Error(too_large_error ())
1240 }
1241 else if length > 0
1242 {
1243 continue_if_expected conn headers buffer at
1244 take conn activity buffer at length
1245 }
1246 else
1247 {
1248 Ok((bytes.empty (), buffer, at))
1249 }
1250 }
1251}
1252
1253/// The body limit for a request to `target` (a path, with or without its
1254/// query): the limit of the first of `settings.large_bodies` whose
1255/// prefix matches the path on whole segments, else `settings.max_body`.
1256/// The path is matched as the client wrote it, not decoded: a request
1257/// that spells a prefix another way (`/upl%6Fads`) gets `max_body`.
1258pub fn body_limit :: settings: Settings target: String -> Int
1259{
1260 let path = (target_split target).0
1261 match list.find settings.large_bodies fn entry { under path entry.0 }
1262 { Some((_, limit)) -> limit, None -> settings.max_body }
1263}
1264
1265/// Whether `path` is `prefix` or below it, on whole segments.
1266fn under :: path: String prefix: String -> Bool
1267{
1268 string.starts_with path prefix
1269 && ( string.ends_with prefix "/"
1270 || string.byte_length path == string.byte_length prefix
1271 || string.starts_with
1272 (string.slice path (string.length prefix) (string.length path))
1273 "/"
1274 )
1275}
1276
1277fn too_large :: size: Int max_body: Int -> Bool
1278{
1279 max_body >= 0 && size > max_body
1280}
1281
1282fn too_large_error :: -> Failure
1283{
1284 Bad(413, "request body too large")
1285}
1286
1287/// Tell a client that waits for it (`Expect: 100-continue`) to send the
1288/// body.
1289fn continue_if_expected :: conn headers buffer: Bytes at: Int -> () / <io>
1290{
1291 let expect = option.map (find_header headers "expect") string.to_lower
1292 if expect == Some("100-continue") && bytes.length buffer == at
1293 {
1294 let _ = net.write_string conn "HTTP/1.1 100 Continue\r\n\r\n"
1295 ()
1296 }
1297 else
1298 {
1299 ()
1300 }
1301}
1302
1303/// The data of the chunks from offset `at` of `buffer` on, appended to
1304/// `body` (`size` bytes so far); then where the next request starts.
1305fn read_chunks ::
1306 conn
1307 activity
1308 max_body: Int
1309 buffer: Bytes
1310 at: Int
1311 body: Builder
1312 size: Int
1313 -> Result<(Bytes, Bytes, Int), Failure> / <io, proc>
1314{
1315 match parse_chunk buffer at
1316 { ChunkData(start, chunk) -> if too_large (size + chunk) max_body
1317 {
1318 Error(too_large_error ())
1319 }
1320 else
1321 {
1322 match take conn activity buffer start (chunk + 2)
1323 { Ok((data, buffer, at)) -> if bytes.slice data chunk (chunk + 2)
1324 == bytes.from_string "\r\n"
1325 {
1326 read_chunks
1327 conn
1328 activity
1329 max_body
1330 buffer
1331 at
1332 (bytes.append body (bytes.slice data 0 chunk))
1333 (size + chunk)
1334 }
1335 else
1336 {
1337 Error(Bad(400, "bad request: no CRLF after a chunk"))
1338 }
1339 , Error(e) -> Error(e)
1340 }
1341 }
1342 , ChunkEnd(end) -> Ok((bytes.build body, buffer, end))
1343 , ChunkInvalid(reason) -> Error(Bad(400, "bad request: " <> reason))
1344 , ChunkPartial -> if bytes.length buffer - at > 65536
1345 {
1346 Error(Bad(400, "bad request: chunk header too large"))
1347 }
1348 else
1349 {
1350 match receive_more conn activity buffer at
1351 { Ok(buffer) -> read_chunks conn activity max_body buffer 0 body size
1352 , Error(e) -> Error(e)
1353 }
1354 }
1355 }
1356}
1357
1358/// `length` bytes from offset `at` of `buffer`, reading more as needed;
1359/// then where what follows them starts. Reads go into a builder, so a
1360/// large body is copied a bounded number of times.
1361fn take ::
1362 conn
1363 activity
1364 buffer: Bytes
1365 at: Int
1366 length: Int
1367 -> Result<(Bytes, Bytes, Int), Failure> / <io, proc>
1368{
1369 let available = bytes.length buffer - at
1370 if available >= length
1371 {
1372 Ok((bytes.slice buffer at (at + length), buffer, at + length))
1373 }
1374 else
1375 {
1376 let rest = bytes.slice buffer at (bytes.length buffer)
1377 take_more
1378 conn
1379 activity
1380 (bytes.append (bytes.builder ()) rest)
1381 available
1382 length
1383 }
1384}
1385
1386fn take_more ::
1387 conn
1388 activity
1389 received: Builder
1390 size: Int
1391 length: Int
1392 -> Result<(Bytes, Bytes, Int), Failure> / <io, proc>
1393{
1394 if size >= length
1395 {
1396 let all = bytes.build received
1397 Ok((bytes.slice all 0 length, all, length))
1398 }
1399 else
1400 {
1401 match read_some conn activity
1402 { Ok(more) ->
1403 take_more
1404 conn
1405 activity
1406 (bytes.append received more)
1407 (size + bytes.length more)
1408 length
1409 , Error(e) -> Error(e)
1410 }
1411 }
1412}
1413
1414/// The unread part of `buffer` (from offset `at`), then what arrives next.
1415fn receive_more ::
1416 conn
1417 activity
1418 buffer: Bytes
1419 at: Int
1420 -> Result<Bytes, Failure> / <io, proc>
1421{
1422 match read_some conn activity
1423 { Ok(more) ->
1424 Ok(bytes.concat (bytes.slice buffer at (bytes.length buffer)) more)
1425 , Error(e) -> Error(e)
1426 }
1427}
1428
1429/// The next bytes from the connection, timed by `idle_timeout` from now.
1430fn read_some ::
1431 conn: Resource<TcpStream>
1432 activity: Subject<Activity>
1433 -> Result<Bytes, Failure> / <io, proc>
1434{
1435 process.send activity Reading
1436 read_raw conn
1437}
1438
1439/// The next bytes from the connection, under whatever timeout runs.
1440fn read_raw :: conn: Resource<TcpStream> -> Result<Bytes, Failure> / <io>
1441{
1442 match net.read conn 65536
1443 { Ok(more) -> if bytes.length more == 0 { Error(Closed) } else { Ok(more) }
1444 , Error(_) -> Error(Closed)
1445 }
1446}
1447
1448type Head
1449{ Partial
1450, Invalid(reason: String)
1451 /// The head ends at offset `end`; `content_length` is -1 when absent.
1452, Complete(
1453 method: String
1454 , path: String
1455 , version: Int
1456 , headers: List<(String, String)>
1457 , end: Int
1458 , content_length: Int
1459 )
1460}
1461
1462@extern c "tl_http_parse_request"
1463fn parse_head :: buffer: Bytes at: Int -> Head
1464
1465/// Where the head in `buffer` ends (just past its empty line), if it ends
1466/// at or after `from`; else -1.
1467@extern c "tl_http_parse_head_end"
1468fn parse_head_end :: buffer: Bytes from: Int -> Int
1469
1470type Chunk
1471{ ChunkPartial
1472, ChunkInvalid(reason: String)
1473 /// `size` bytes of data from offset `start`, then CRLF.
1474, ChunkData(start: Int, size: Int)
1475 /// The last chunk and its trailers end at offset `end`.
1476, ChunkEnd(end: Int)
1477}
1478
1479@extern c "tl_http_parse_chunk"
1480fn parse_chunk :: buffer: Bytes at: Int -> Chunk
1481
1482/// Whether `status` is a final status this server sends without framing or a
1483/// message body: 204 No Content or 304 Not Modified.
1484fn final_status_without_body :: status: Int -> Bool
1485{
1486 status == 204 || status == 304
1487}
1488
1489/// The head and (unless `with_body` is false, for HEAD requests) the body,
1490/// in one buffer so they leave in one write. The whole-body case.
1491fn serialize :: resp: Response keep_alive: Bool with_body: Bool -> Bytes
1492{
1493 let body = option.unwrap_or (whole_body resp) (bytes.empty ())
1494 let head =
1495 head_bytes
1496 resp.status
1497 resp.headers
1498 keep_alive
1499 ("Content-Length: " <> show (bytes.length body))
1500 let out = bytes.append_string (bytes.builder ()) head
1501 bytes.build if with_body { bytes.append out body } else { out }
1502}
1503
1504/// A streamed response's head: `Transfer-Encoding: chunked`, no length.
1505fn serialize_stream_head :: resp: Response keep_alive: Bool -> Bytes
1506{
1507 bytes.from_string
1508 ( head_bytes
1509 resp.status
1510 resp.headers
1511 keep_alive
1512 "Transfer-Encoding: chunked"
1513 )
1514}
1515
1516/// The status line, the caller's headers (framing filtered), the framing
1517/// header, and the keep-alive line.
1518fn head_bytes ::
1519 status: Int
1520 headers: List<(String, String)>
1521 keep_alive: Bool
1522 framing: String
1523 -> String
1524{
1525 let own = list.filter headers fn h { !is_framing (string.to_lower h.0) }
1526 string.concat
1527 [ "HTTP/1.1 "
1528 , show status
1529 , " "
1530 , reason status
1531 , "\r\n"
1532 , string.concat (list.map own fn h { h.0 <> ": " <> h.1 <> "\r\n" })
1533 , if framing == "" { "" } else { framing <> "\r\n" }
1534 , if keep_alive
1535 {
1536 "Connection: keep-alive\r\n\r\n"
1537 }
1538 else
1539 {
1540 "Connection: close\r\n\r\n"
1541 }
1542 ]
1543}
1544
1545/// Headers the server sets itself.
1546fn is_framing :: name: String -> Bool
1547{
1548 match name
1549 { "content-length" | "connection" | "transfer-encoding" -> True, _ -> False }
1550}
1551
1552/// The status line's reason phrase (RFC 9110 §15 and the registered
1553/// extensions); `"Status"` for one not in the set.
1554pub fn reason :: status: Int -> String
1555{
1556 match status
1557 { 100 -> "Continue"
1558 , 101 -> "Switching Protocols"
1559 , 200 -> "OK"
1560 , 201 -> "Created"
1561 , 202 -> "Accepted"
1562 , 203 -> "Non-Authoritative Information"
1563 , 204 -> "No Content"
1564 , 205 -> "Reset Content"
1565 , 206 -> "Partial Content"
1566 , 226 -> "IM Used"
1567 , 300 -> "Multiple Choices"
1568 , 301 -> "Moved Permanently"
1569 , 302 -> "Found"
1570 , 303 -> "See Other"
1571 , 304 -> "Not Modified"
1572 , 305 -> "Use Proxy"
1573 , 307 -> "Temporary Redirect"
1574 , 308 -> "Permanent Redirect"
1575 , 400 -> "Bad Request"
1576 , 401 -> "Unauthorized"
1577 , 402 -> "Payment Required"
1578 , 403 -> "Forbidden"
1579 , 404 -> "Not Found"
1580 , 405 -> "Method Not Allowed"
1581 , 406 -> "Not Acceptable"
1582 , 407 -> "Proxy Authentication Required"
1583 , 408 -> "Request Timeout"
1584 , 409 -> "Conflict"
1585 , 410 -> "Gone"
1586 , 411 -> "Length Required"
1587 , 412 -> "Precondition Failed"
1588 , 413 -> "Content Too Large"
1589 , 414 -> "URI Too Long"
1590 , 415 -> "Unsupported Media Type"
1591 , 416 -> "Range Not Satisfiable"
1592 , 417 -> "Expectation Failed"
1593 , 418 -> "I'm a Teapot"
1594 , 421 -> "Misdirected Request"
1595 , 422 -> "Unprocessable Content"
1596 , 423 -> "Locked"
1597 , 424 -> "Failed Dependency"
1598 , 425 -> "Too Early"
1599 , 426 -> "Upgrade Required"
1600 , 428 -> "Precondition Required"
1601 , 429 -> "Too Many Requests"
1602 , 431 -> "Request Header Fields Too Large"
1603 , 451 -> "Unavailable For Legal Reasons"
1604 , 500 -> "Internal Server Error"
1605 , 501 -> "Not Implemented"
1606 , 502 -> "Bad Gateway"
1607 , 503 -> "Service Unavailable"
1608 , 504 -> "Gateway Timeout"
1609 , 505 -> "HTTP Version Not Supported"
1610 , 507 -> "Insufficient Storage"
1611 , 508 -> "Loop Detected"
1612 , 510 -> "Not Extended"
1613 , 511 -> "Network Authentication Required"
1614 , _ -> "Status"
1615 }
1616}
1617
1618/// The fields of an `application/x-www-form-urlencoded` body (or query
1619/// string): `a=1&b=two+words` gives `[("a", "1"), ("b", "two words")]`.
1620/// Pairs split on `&`, each on its first `=`, both sides percent-decoded
1621/// with `+` a space — in the query (`query_params`) as in a form body,
1622/// as browsers send both; empty pairs are dropped, a bare `k` is
1623/// `("k", "")`.
1624@extern c "tl_http_parse_query"
1625pub fn form :: body: String -> List<(String, String)>
1626
1627/// The request target split at its first `?`: `(path, query)`, the query
1628/// without the `?` ("" when there is none). Later `?`s stay in the query:
1629/// `target_split("/a?b?c")` is `("/a", "b?c")`.
1630pub fn target_split :: target: String -> (String, String)
1631{
1632 match string.split target "?"
1633 { [path] -> (path, "")
1634 , [path, ..rest] -> (path, string.join rest "?")
1635 , [] -> ("", "")
1636 }
1637}
1638
1639/// The path of the request's target (before any `?`).
1640pub fn path :: req: Request -> String
1641{
1642 (target_split req.path).0
1643}
1644
1645/// The query of the request's target (after the first `?`), "" when it
1646/// has none.
1647pub fn query :: req: Request -> String
1648{
1649 (target_split req.path).1
1650}
1651
1652/// The path's segments: split on `/` with empty segments dropped, each
1653/// percent-decoded. Decoding happens after splitting, so an encoded slash
1654/// (`%2F`) stays inside its segment.
1655pub fn segments :: req: Request -> List<String>
1656{
1657 list.map
1658 (list.filter (string.split (path req) "/") fn s { s != "" })
1659 url_decode
1660}
1661
1662/// The query's parameters: split on `&`, each `k=v` on its first `=`,
1663/// both sides percent-decoded; a bare `k` is `("k", "")`.
1664pub fn query_params :: req: Request -> List<(String, String)>
1665{
1666 form (query req)
1667}
1668
1669/// The value of field `name` in a form, if present.
1670pub fn field :: fields: List<(String, String)> name: String -> Option<String>
1671{
1672 match fields
1673 { [] -> None
1674 , [(k, v), ..rest] -> if k == name { Some(v) } else { field rest name }
1675 }
1676}
1677
1678/// Decode `%XX` escapes and `+` (a space); invalid escapes stay as they
1679/// are. A string without `%` or `+` is returned as is.
1680@extern c "tl_url_decode" owned
1681pub fn url_decode :: s: String -> String
1682
1683/// Percent-encode `s` for a URL path or query (RFC 3986): every byte
1684/// outside the unreserved set (`A-Z a-z 0-9 - _ . ~`) becomes `%XX`
1685/// (uppercase hex). A space is `%20`, not `+`: `url_decode` maps both
1686/// back to a space, and a `+` in a path segment decodes as a space only
1687/// in a query or form, so `%20` is the safe spelling everywhere.
1688/// `url_decode(url_encode(s))` is `s`. A string without a byte to encode
1689/// is returned as is.
1690@extern c "tl_url_encode" owned
1691pub fn url_encode :: s: String -> String