Xo is experimental. The source is now public on GitHub, or try Xo in your browser.
Menu · http

Docs

Tour

Book

Reference

std/http

On this page

Index

Constants

CONTINUE

const CONTINUE: Status = Status(100)

The codes Go’s net/http names (std.md 4).

Source: std/http.xo:47

SWITCHING_PROTOCOLS

const SWITCHING_PROTOCOLS: Status = Status(101)

Source: std/http.xo:48

PROCESSING

const PROCESSING: Status = Status(102)

Source: std/http.xo:49

EARLY_HINTS

const EARLY_HINTS: Status = Status(103)

Source: std/http.xo:50

OK

const OK: Status = Status(200)

Source: std/http.xo:51

CREATED

const CREATED: Status = Status(201)

Source: std/http.xo:52

ACCEPTED

const ACCEPTED: Status = Status(202)

Source: std/http.xo:53

NON_AUTHORITATIVE_INFO

const NON_AUTHORITATIVE_INFO: Status = Status(203)

Source: std/http.xo:54

NO_CONTENT

const NO_CONTENT: Status = Status(204)

Source: std/http.xo:55

RESET_CONTENT

const RESET_CONTENT: Status = Status(205)

Source: std/http.xo:56

PARTIAL_CONTENT

const PARTIAL_CONTENT: Status = Status(206)

Source: std/http.xo:57

MULTI_STATUS

const MULTI_STATUS: Status = Status(207)

Source: std/http.xo:58

ALREADY_REPORTED

const ALREADY_REPORTED: Status = Status(208)

Source: std/http.xo:59

IM_USED

const IM_USED: Status = Status(226)

Source: std/http.xo:60

MULTIPLE_CHOICES

const MULTIPLE_CHOICES: Status = Status(300)

Source: std/http.xo:61

MOVED_PERMANENTLY

const MOVED_PERMANENTLY: Status = Status(301)

Source: std/http.xo:62

FOUND

const FOUND: Status = Status(302)

Source: std/http.xo:63

SEE_OTHER

const SEE_OTHER: Status = Status(303)

Source: std/http.xo:64

NOT_MODIFIED

const NOT_MODIFIED: Status = Status(304)

Source: std/http.xo:65

USE_PROXY

const USE_PROXY: Status = Status(305)

Source: std/http.xo:66

TEMPORARY_REDIRECT

const TEMPORARY_REDIRECT: Status = Status(307)

Source: std/http.xo:67

PERMANENT_REDIRECT

const PERMANENT_REDIRECT: Status = Status(308)

Source: std/http.xo:68

BAD_REQUEST

const BAD_REQUEST: Status = Status(400)

Source: std/http.xo:69

UNAUTHORIZED

const UNAUTHORIZED: Status = Status(401)

Source: std/http.xo:70

PAYMENT_REQUIRED

const PAYMENT_REQUIRED: Status = Status(402)

Source: std/http.xo:71

FORBIDDEN

const FORBIDDEN: Status = Status(403)

Source: std/http.xo:72

NOT_FOUND

const NOT_FOUND: Status = Status(404)

Source: std/http.xo:73

METHOD_NOT_ALLOWED

const METHOD_NOT_ALLOWED: Status = Status(405)

Source: std/http.xo:74

NOT_ACCEPTABLE

const NOT_ACCEPTABLE: Status = Status(406)

Source: std/http.xo:75

PROXY_AUTH_REQUIRED

const PROXY_AUTH_REQUIRED: Status = Status(407)

Source: std/http.xo:76

REQUEST_TIMEOUT

const REQUEST_TIMEOUT: Status = Status(408)

Source: std/http.xo:77

CONFLICT

const CONFLICT: Status = Status(409)

Source: std/http.xo:78

GONE

const GONE: Status = Status(410)

Source: std/http.xo:79

LENGTH_REQUIRED

const LENGTH_REQUIRED: Status = Status(411)

Source: std/http.xo:80

PRECONDITION_FAILED

const PRECONDITION_FAILED: Status = Status(412)

Source: std/http.xo:81

REQUEST_ENTITY_TOO_LARGE

const REQUEST_ENTITY_TOO_LARGE: Status = Status(413)

Source: std/http.xo:82

REQUEST_URI_TOO_LONG

const REQUEST_URI_TOO_LONG: Status = Status(414)

Source: std/http.xo:83

UNSUPPORTED_MEDIA_TYPE

const UNSUPPORTED_MEDIA_TYPE: Status = Status(415)

Source: std/http.xo:84

REQUESTED_RANGE_NOT_SATISFIABLE

const REQUESTED_RANGE_NOT_SATISFIABLE: Status = Status(416)

Source: std/http.xo:85

EXPECTATION_FAILED

const EXPECTATION_FAILED: Status = Status(417)

Source: std/http.xo:86

TEAPOT

const TEAPOT: Status = Status(418)

Source: std/http.xo:87

MISDIRECTED_REQUEST

const MISDIRECTED_REQUEST: Status = Status(421)

Source: std/http.xo:88

UNPROCESSABLE_ENTITY

const UNPROCESSABLE_ENTITY: Status = Status(422)

Source: std/http.xo:89

LOCKED

const LOCKED: Status = Status(423)

Source: std/http.xo:90

FAILED_DEPENDENCY

const FAILED_DEPENDENCY: Status = Status(424)

Source: std/http.xo:91

TOO_EARLY

const TOO_EARLY: Status = Status(425)

Source: std/http.xo:92

UPGRADE_REQUIRED

const UPGRADE_REQUIRED: Status = Status(426)

Source: std/http.xo:93

PRECONDITION_REQUIRED

const PRECONDITION_REQUIRED: Status = Status(428)

Source: std/http.xo:94

TOO_MANY_REQUESTS

const TOO_MANY_REQUESTS: Status = Status(429)

Source: std/http.xo:95

REQUEST_HEADER_FIELDS_TOO_LARGE

const REQUEST_HEADER_FIELDS_TOO_LARGE: Status = Status(431)

Source: std/http.xo:96

const UNAVAILABLE_FOR_LEGAL_REASONS: Status = Status(451)

Source: std/http.xo:97

INTERNAL_SERVER_ERROR

const INTERNAL_SERVER_ERROR: Status = Status(500)

Source: std/http.xo:98

NOT_IMPLEMENTED

const NOT_IMPLEMENTED: Status = Status(501)

Source: std/http.xo:99

BAD_GATEWAY

const BAD_GATEWAY: Status = Status(502)

Source: std/http.xo:100

SERVICE_UNAVAILABLE

const SERVICE_UNAVAILABLE: Status = Status(503)

Source: std/http.xo:101

GATEWAY_TIMEOUT

const GATEWAY_TIMEOUT: Status = Status(504)

Source: std/http.xo:102

HTTP_VERSION_NOT_SUPPORTED

const HTTP_VERSION_NOT_SUPPORTED: Status = Status(505)

Source: std/http.xo:103

VARIANT_ALSO_NEGOTIATES

const VARIANT_ALSO_NEGOTIATES: Status = Status(506)

Source: std/http.xo:104

INSUFFICIENT_STORAGE

const INSUFFICIENT_STORAGE: Status = Status(507)

Source: std/http.xo:105

LOOP_DETECTED

const LOOP_DETECTED: Status = Status(508)

Source: std/http.xo:106

NOT_EXTENDED

const NOT_EXTENDED: Status = Status(510)

Source: std/http.xo:107

NETWORK_AUTHENTICATION_REQUIRED

const NETWORK_AUTHENTICATION_REQUIRED: Status = Status(511)

Source: std/http.xo:108

Types

Router

struct Router {}

Source: std/http.xo:17

Router.handle

fn (var r: Router) handle[E: Error, fx: Effects](pattern: Str, h: fn(Request) -> Response ! E uses fx) uses fx

Source: std/http.xo:21

Router.handle_stream

fn (var r: Router) handle_stream[E: Error, fx: Effects](pattern: Str, h: fn(Request, BodyReader) -> Response ! E uses fx) uses fx

A route whose handler reads the request body as a stream (decision 0310): the server calls h before reading the body; req.body is empty.

Source: std/http.xo:24

Router.wrap

fn (var r: Router) wrap[E: Error, fx: Effects](m: fn(Request, Next) -> Response ! E uses fx) uses fx

Source: std/http.xo:25

Router.mount

fn (var r: Router) mount(prefix: Str, sub: Router)

Adds every route of sub under prefix, behind the middleware of sub (std.md 4.1).

Source: std/http.xo:28

Router.not_found

fn (var r: Router) not_found[E: Error, fx: Effects](h: fn(Request) -> Response ! E uses fx) uses fx

The response of a request no route matches, in place of the 404 (std.md 4.1); a mounted router’s hook is not copied.

Source: std/http.xo:31

Router.method_not_allowed

fn (var r: Router) method_not_allowed[E: Error, fx: Effects](h: fn(Request) -> Response ! E uses fx) uses fx

The response of a request whose path a route matches with another method, in place of the 405 (std.md 4.1); it gets the Allow header when it lacks one.

Source: std/http.xo:35

Router.call

fn (r: Router) call(req: Request) -> Response

Source: std/http.xo:36

Next

type Next = fn(Request) -> Response

Source: std/http.xo:18

Status

type Status struct(Int)

An HTTP status code (decision 0269): a distinct integer type, so a status cannot be mixed up with another Int.

Source: std/http.xo:44

StatusError

interface StatusError {
  fn status(self) -> Int
  fn display(self) -> Str
}

Source: std/http.xo:110

Request

struct Request {
  method: Str
  path: Str
  url: Url
  headers: Map[Str, Str]
  body: Bytes
  remote_ip: Str
}

Source: std/http.xo:115

Request.param

fn (r: Request) param(name: Str) -> Str

The path parameter name of the matched route; faults if the route has no such segment (param_opt answers None instead).

Source: std/http.xo:125

Request.param_opt

fn (r: Request) param_opt(name: Str) -> Str?

The path parameter name, or None when the route has no such segment.

Source: std/http.xo:127

Request.param_int

fn (r: Request) param_int(name: Str) -> Int

Source: std/http.xo:128

Request.query

fn (r: Request) query(name: Str) -> Str?

Source: std/http.xo:129

Request.query_all

fn (r: Request) query_all(name: Str) -> List[Str]

Every value of name in the query, in order (decision 0279).

Source: std/http.xo:131

Request.form

fn (r: Request) form() -> url.Values ! url.EscapeErr

The body of an application/x-www-form-urlencoded POST, PUT, or PATCH as Values; empty Values for any other request (decision 0279).

Source: std/http.xo:134

Request.multipart_form

fn (r: Request) multipart_form() -> multipart.Form ! multipart.MultipartErr

The body of a multipart/form-data request as a Form (Go’s ParseMultipartForm with its 32 MB limit); MultipartErr request Content-Type isn't multipart/form-data or no multipart boundary param in Content-Type for any other (decision 0282).

Source: std/http.xo:139

Request.header

fn (r: Request) header(name: Str) -> Str?

Source: std/http.xo:140

Request.json

fn (r: Request) json[T: Json]() -> T ! json.DecodeErr

Source: std/http.xo:141

Request.with_header

fn (r: Request) with_header(name: Str, value: Str) -> Request

Source: std/http.xo:142

Request.with_timeout

fn (r: Request) with_timeout(d: Duration) -> Request

The request with its own time limit in place of its client’s, for the whole exchange with the body (Go’s Client.Timeout); a client side builder (decision 0404).

Source: std/http.xo:146

Request.with_host

fn (r: Request) with_host(host: Str) -> Request

The request sent with Host (HTTP/1.1) and :authority (HTTP/2) host in place of the URL’s (Go’s Request.Host); the connection and the TLS name stay the URL’s. "" is the URL’s host.

Source: std/http.xo:149

Request.with_expect_continue

fn (r: Request) with_expect_continue(timeout: Duration = 1s) -> Request

The request with Expect: 100-continue (Go’s Transport.ExpectContinueTimeout, default 1s): an HTTP/1.1 client sends the head, waits up to timeout for the server’s 100 Continue, then sends the body; a final response first (a 401, a 413) is the result and the body is never sent; other 1xx are skipped. A request without a body, and an HTTP/2 or Client.open request, send as before.

Source: std/http.xo:156

Request.with_idle_timeout

fn (r: Request) with_idle_timeout(d: Duration) -> Request

The limit for each read of an opened stream’s body in place of its client’s timeout; a client side builder (decision 0404).

Source: std/http.xo:159

Request.with_body_reader

fn (r: Request) with_body_reader(b: BodyReader) -> Request

The request with its body read from b as it is sent (a handle_stream route’s body, decision 0404): chunked unless the header gives Content-Length, never sent twice (a 307 or 308 returns the 3xx).

Source: std/http.xo:163

Request.with_trailers

fn (r: Request) with_trailers(names: List[Str], f: fn() -> Map[Str, Str]) -> Request

The request with trailers (Go’s Request.Trailer, decision 0433): names are declared in its head (an HTTP/2 server keeps only declared ones), f is asked once its body has been sent and its values for those names go after it; other names, and names Go forbids in a trailer, are dropped. An HTTP/1.1 body is then chunked.

Source: std/http.xo:169

Request.header_values

fn (r: Request) header_values(name: Str) -> List[Str]

Every field of name, in order (decision 0288).

Source: std/http.xo:171

Request.host

fn (r: Request) host() -> Str

Go’s Request.Host: the Host header as sent (host, or host:port; HTTP/2’s :authority); url.host is the name alone. "" for a request built as a struct literal (std.md 4.3).

Source: std/http.xo:175

Request.tls

fn (r: Request) tls() -> Bool

Whether the request came over TLS (Go’s r.TLS != nil); url.scheme is then “https”.

Source: std/http.xo:178

Request.tls_state

fn (r: Request) tls_state() -> TlsState?

Go’s r.TLS (a tls.ConnectionState): what the connection’s handshake negotiated; None for a plain connection or a request built as a struct literal.

Source: std/http.xo:182

Request.raw_query

fn (r: Request) raw_query() -> Str

Go’s URL.RawQuery: the query as sent, before any unescaping.

Source: std/http.xo:184

Request.escaped_path

fn (r: Request) escaped_path() -> Str

Go’s URL.EscapedPath: the path as sent when it is a valid escaping of path, else path escaped (std/url’s path_escape).

Source: std/http.xo:187

Request.add_header

fn (r: Request) add_header(name: Str, value: Str) -> Request

The request with one more field of name.

Source: std/http.xo:189

Request.client_ip

fn (r: Request) client_ip(trusted: List[netip.Prefix] = [], header: ProxyHeader = ProxyHeader.XForwardedFor) -> netip.Addr?

The client’s address behind trusted proxies (std.md 4.3): the peer (remote_ip) when it is not inside a prefix of trusted, else the rightmost address of header (every field of it, in order) that is not inside one; None when an address does not parse.

Source: std/http.xo:194

Request.with_value

fn (r: Request) with_value[T](k: Key[T], v: T) -> Request

Source: std/http.xo:204

Request.value

fn (r: Request) value[T](k: Key[T]) -> T?

Source: std/http.xo:205

Request.cookie

fn (r: Request) cookie(name: Str) -> Cookie?

The first cookie of that name in the Cookie fields (Go’s Request.Cookie, decision 0288).

Source: std/http.xo:208

Request.cookies

fn (r: Request) cookies() -> List[Cookie]

Every cookie of the Cookie fields that parses (Go’s Request.Cookies).

Source: std/http.xo:210

fn (r: Request) with_cookie(c: Cookie) -> Request

The request with name=value appended to its Cookie field (Go’s Request.AddCookie).

Source: std/http.xo:213

ProxyHeader

enum ProxyHeader {
  XForwardedFor
  Forwarded
} derive Display

The header a server’s trusted proxies write the client chain to: X-Forwarded-For: client, proxy1 or RFC 7239’s Forwarded: for=client, for=proxy1. Only that one is read: a proxy that writes one passes a client’s own copy of the other through.

Source: std/http.xo:200

TlsState

struct TlsState {
  version: Str
  cipher_suite: Str
  server_name: Str
  resumed: Bool
  peer_certificates: List[x509.Certificate]
  verified_chains: List[List[x509.Certificate]]
}

What a TLS connection’s handshake negotiated (std.md 4.3; Go’s tls.ConnectionState).

Source: std/http.xo:217

struct Cookie {
  name: Str
  value: Str
  quoted: Bool = false
  path: Str = ""
  domain: Str = ""
  expires: Time? = None
  max_age: Int = 0
  secure: Bool = false
  http_only: Bool = false
  same_site: SameSite = SameSite.Default
  partitioned: Bool = false
}

An HTTP cookie (std.md 4.3, decision 0288; net/http’s Cookie).

Source: std/http.xo:236

Cookie.display

fn (c: Cookie) display() -> Str

The Set-Cookie value (Go’s Cookie.String); "" for a name that is not a token.

Source: std/http.xo:264

SameSite

enum SameSite {
  Default
  Lax
  Strict
  None
} derive Display

Source: std/http.xo:255

CookieErr

struct CookieErr {
  msg: Str
}

Source: std/http.xo:270

CookieErr.display

fn (e: CookieErr) display() -> Str

The message (decision 0358).

Source: std/http.xo:275

Key

struct Key[T] {}

A typed request value key (std.md 4.3).

Source: std/http.xo:278

Key.name

fn (k: Key[T]) name() -> Str

Source: std/http.xo:280

Response

struct Response {
  status: Int
  headers: Map[Str, Str]
  body: Bytes
}

Source: std/http.xo:284

Response.with_trailer_names

fn (r: Response) with_trailer_names(names: List[Str]) -> Response

The response declaring trailer names in its Trailer header (HTTP/1.1; decision 0433); set_trailer sends a name whether declared or not.

Source: std/http.xo:366

Response.with_full_duplex

fn (r: Response) with_full_duplex() -> Response

The streamed response whose function may read the request’s body while it writes (Go’s ResponseController.EnableFullDuplex, decision 0433): its head goes out at once, a 100 Continue before the first read when asked. HTTP/1.1 only needs it; an HTTP/2 stream always is.

Source: std/http.xo:371

Response.with_header

fn (r: Response) with_header(name: Str, value: Str) -> Response

Source: std/http.xo:384

Response.header

fn (r: Response) header(name: Str) -> Str?

Source: std/http.xo:385

Response.header_values

fn (r: Response) header_values(name: Str) -> List[Str]

Every field of name, in order (decision 0288).

Source: std/http.xo:387

Response.add_header

fn (r: Response) add_header(name: Str, value: Str) -> Response

The response with one more field of name.

Source: std/http.xo:389

fn (r: Response) with_cookie(c: Cookie) -> Response

One more Set-Cookie field (Go’s SetCookie); none for an invalid name.

Source: std/http.xo:391

Response.cookies

fn (r: Response) cookies() -> List[Cookie]

Every Set-Cookie field that parses (Go’s Response.Cookies).

Source: std/http.xo:393

Response.text

fn (r: Response) text() -> Str?

The body as text; None if it is not valid UTF-8 (std.md 4.3).

Source: std/http.xo:395

Response.decode_json

fn (r: Response) decode_json[T: Json]() -> T ! json.DecodeErr

Source: std/http.xo:396

BodyReader

struct BodyReader {}

The body of a request to a handle_stream route (decision 0310).

Source: std/http.xo:321

BodyReader.read

fn (b: BodyReader) read(max: Int = 32768) -> Bytes? ! IoErr

The next bytes of the body (at most max, at least 1), None at its end.

Source: std/http.xo:323

BodyReader.read_all

fn (b: BodyReader) read_all() -> Bytes ! IoErr

The rest of the body.

Source: std/http.xo:325

BodyReader.multipart

fn (b: BodyReader) multipart(req: Request) -> PartReader ! multipart.MultipartErr

The body as multipart/form-data parts, read as they arrive (decision 0310 phase 3; Go’s Request.MultipartReader): MultipartErr as Request.multipart_form’s for another Content-Type or no boundary.

Source: std/http.xo:329

BodyReader.trailers

fn (b: BodyReader) trailers() -> Map[Str, Str]

The request’s trailers (Go’s Request.Trailer, decision 0433), names canonical; empty until read has returned None.

Source: std/http.xo:332

PartReader

struct PartReader {}

A multipart body read part by part (Go’s multipart.Reader).

Source: std/http.xo:335

PartReader.next

fn (p: PartReader) next() -> StreamPart? ! multipart.MultipartErr

The next part, the open part’s unread data dropped (NextPart); None after the last part. An error sticks.

Source: std/http.xo:338

PartReader.read

fn (p: PartReader) read(max: Int = 32768) -> Bytes? ! multipart.MultipartErr

The open part’s next bytes (at most max, at least 1; decoded when quoted-printable, as Go’s NextPart), None at its end or before the first next.

Source: std/http.xo:342

StreamPart

struct StreamPart {
  name: Str
  filename: Str?
  headers: Map[Str, Str]
}

A part of a PartReader: multipart.Part’s fields but its data, which PartReader.read reads; headers holds each header’s first value.

Source: std/http.xo:346

StreamPart.header_values

fn (p: StreamPart) header_values(name: Str) -> List[Str]

Every value of the part’s header name, in order (MIMEHeader’s values); [] when it has none.

Source: std/http.xo:353

BodyWriter

struct BodyWriter {}

The body of a streamed response (std.md 4.3).

Source: std/http.xo:356

BodyWriter.write

fn (w: BodyWriter) write(data: Bytes) -> () ! IoErr

Source: std/http.xo:357

BodyWriter.flush

fn (w: BodyWriter) flush() -> () ! IoErr

Source: std/http.xo:358

BodyWriter.set_trailer

fn (w: BodyWriter) set_trailer(name: Str, value: Str)

A trailer sent after the body (Go’s TrailerPrefix, decision 0433), the name made canonical; a name Go forbids in a trailer (Content-Length, Host, Trailer, …) is dropped. Not sent on a response with a Content-Length.

Source: std/http.xo:363

PipeWriter

struct PipeWriter {}

The writing end of http.pipe.

Source: std/http.xo:377

PipeWriter.write

fn (w: PipeWriter) write(data: Bytes) -> () ! IoErr

Io(“io: read/write on closed pipe”) once either end is closed.

Source: std/http.xo:379

PipeWriter.close

fn (w: PipeWriter) close()

The reader’s next read is None (the body’s end).

Source: std/http.xo:381

PipeWriter.close_with_error

fn (w: PipeWriter) close_with_error(e: IoErr)

The reader’s next read is Err(e) (Go’s CloseWithError).

Source: std/http.xo:383

Server

struct Server {}

Source: std/http.xo:398

Server.serve

fn (s: Server) serve() -> () ! HttpErr uses net.listen

Source: std/http.xo:400

Server.addr

fn (s: Server) addr() -> Str

Source: std/http.xo:401

Server.with_tls

fn (s: Server) with_tls(certs: List[TlsCert]) -> Server

The server with HTTPS (std.md 4.6): certs[0] unless SNI names another certificate’s host.

Source: std/http.xo:404

Server.with_client_auth

fn (s: Server) with_client_auth(mode: tls.ClientAuth, roots: tls.Roots? = None) -> Server

The server asks a TLS client for its certificate (Go’s tls.Config.ClientAuth and ClientCAs; decision 0433): roots verify it, the system’s when None. A request’s tls_state has the client’s certificates and verified chains.

Source: std/http.xo:409

Server.with_read_timeout

fn (s: Server) with_read_timeout(d: Duration) -> Server

Go’s Server.ReadTimeout: the time a request’s head and body may take to arrive, from its first byte; a connection whose request is late closes without a reply, as net/http’s does; over TLS the handshake’s waits count too.

Source: std/http.xo:414

Server.with_read_header_timeout

fn (s: Server) with_read_header_timeout(d: Duration) -> Server

Go’s Server.ReadHeaderTimeout: the time the head alone may take.

Source: std/http.xo:416

Server.with_idle_timeout

fn (s: Server) with_idle_timeout(d: Duration) -> Server

Go’s Server.IdleTimeout: how long a kept alive connection waits for its next request’s first byte (the read timeout when 0).

Source: std/http.xo:419

Server.with_max_header_bytes

fn (s: Server) with_max_header_bytes(n: Int) -> Server

Go’s Server.MaxHeaderBytes (plus net/http’s 4096 bytes of slack): a longer head is 431 Request Header Fields Too Large (1 MB when 0, as Go’s DefaultMaxHeaderBytes).

Source: std/http.xo:423

Server.with_max_body

fn (s: Server) with_max_body(n: Int) -> Server

The largest request body the server reads before a handler (64 MB when 0, XO_HTTP_MAX_BODY’s default); a longer one is 413 Content Too Large. A route that needs a smaller cap wraps max_body(n).

Source: std/http.xo:427

Server.with_protocols

fn (s: Server) with_protocols(p: Set[Protocol]) -> Server

The server speaking the protocols of p (Go’s Server.Protocols; decision 0434): #{Http1, Http2} by default; UnencryptedHttp2 serves h2c with prior knowledge on a plain listener. serve fails on an empty set or a TLS server with neither Http1 nor Http2.

Source: std/http.xo:467

Server.with_h2_config

fn (s: Server) with_h2_config(c: H2Config) -> Server

The server’s HTTP/2 settings (Go’s Server.HTTP2; decision 0434).

Source: std/http.xo:469

Protocol

enum Protocol {
  Http1
  Http2
  UnencryptedHttp2
} derive Display

The protocols a server or client speaks (Go’s http.Protocols, decision 0434).

Source: std/http.xo:430

H2Config

struct H2Config {
  max_concurrent_streams: Int = 0
  max_read_frame_size: Int = 0
  max_receive_buffer_per_connection: Int = 0
  max_receive_buffer_per_stream: Int = 0
  max_decoder_header_table_size: Int = 0
  max_encoder_header_table_size: Int = 0
  send_ping_timeout: Duration = 0s
  ping_timeout: Duration = 0s
  write_byte_timeout: Duration = 0s
}

HTTP/2 settings (Go’s http.HTTP2Config, decision 0434); 0 is the default of each, and an out of range value is clamped as Go does.

Source: std/http.xo:441

TlsCert

type TlsCert = tls.TlsCert

A certificate chain with its private key (std.md 4.6): std/tls’s (decision 0433).

Source: std/http.xo:478

TlsErr

struct TlsErr {
  msg: Str
}

Source: std/http.xo:482

TlsErr.display

fn (e: TlsErr) display() -> Str

The message (decision 0358).

Source: std/http.xo:487

HttpErr

enum HttpErr {
  Io(msg: Str)
  Canceled
}

Source: std/http.xo:489

HttpErr.display

fn (e: HttpErr) display() -> Str

MSG for an Io, canceled (decision 0358).

Source: std/http.xo:495

Client

struct Client {}

Source: std/http.xo:497

Client.get

fn (c: Client) get(url: Str) -> Response ! ClientErr uses net.dial

Source: std/http.xo:499

Client.send

fn (c: Client) send(req: Request) -> Response ! ClientErr uses net.dial

Source: std/http.xo:500

Client.post_json

fn (c: Client) post_json[T: Json](url: Str, v: T) -> Response ! ClientErr uses net.dial

Source: std/http.xo:501

Client.with_roots

fn (c: Client) with_roots(pem: Bytes) -> Client ! TlsErr

The client trusting the certificates of pem instead of the system’s roots for https (std.md 4.6).

Source: std/http.xo:504

Client.with_server_name

fn (c: Client) with_server_name(name: Str) -> Client

The client’s name for the server (Go’s tls.Config.ServerName): sent as SNI and verified against the certificate in place of the URL’s host; "" keeps the URL’s. A client with one has its own connections (decision 0541).

Source: std/http.xo:507

Client.with_verify_conn

fn (c: Client) with_verify_conn(f: fn(List[x509.Certificate]) -> () ! Str) -> Client

The client calling f with the server’s certificates (leaf first) after the TLS handshake and its verification, before any request byte is sent (Go’s tls.Config.VerifyConnection); Err(text) fails the connection with that text. It runs on every new connection, so a pinning check works with a self signed server. A client with one has its own connections.

Source: std/http.xo:512

Client.with_verify

fn (c: Client) with_verify(v: tls.Verify) -> Client

How the client checks the server’s certificate for https (Go’s InsecureSkipVerify when Verify.None, with Verify.ChainOnly the chain without the name); the default is Verify.Full. UNSAFE alone: Verify.None accepts any certificate, so a request on such a client fails (“tls: Verify.None needs a verify_conn …”) unless with_verify_conn is set, which should pin the certificate (tls.pin_sha256, tls.pin_sha1). A client with one has its own connections.

Source: std/http.xo:518

Client.tls_options

fn (c: Client) tls_options() -> TlsOptions

Source: std/http.xo:527

Client.with_cert

fn (c: Client) with_cert(cert: TlsCert) -> Client

The client presenting cert when an https server asks for a certificate (Go’s tls.Config.Certificates on a client; decision 0433).

Source: std/http.xo:530

Client.with_protocols

fn (c: Client) with_protocols(p: Set[Protocol]) -> Client

The client speaking the protocols of p (Go’s Transport.Protocols; decision 0434): with UnencryptedHttp2 and not Http1, an http:// URL opens HTTP/2 with prior knowledge.

Source: std/http.xo:534

Client.with_h2_config

fn (c: Client) with_h2_config(cfg: H2Config) -> Client

The client’s HTTP/2 settings (Go’s Transport.HTTP2; decision 0434).

Source: std/http.xo:536

Client.open

fn (c: Client) open(req: Request) -> ClientStream ! ClientErr uses net.dial

The request sent and the response’s head read; its body follows on the stream (redirects followed as send follows them).

Source: std/http.xo:566

Client.with_redirects

fn (c: Client) with_redirects(max: Int) -> Client

The client following at most max redirects (10 by default); 0 returns a 3xx response as it came, its Location as the server sent it (Go’s ErrUseLastResponse; decision 0404).

Source: std/http.xo:581

TlsOptions

struct TlsOptions {
  server_name: Str
  verify_conn: Bool
  custom_roots: Bool
  client_cert: Bool
  verify: tls.Verify
}

What a client’s TLS settings are, for tests and diagnostics.

Source: std/http.xo:520

ReverseProxy

struct ReverseProxy {}

Source: std/http.xo:546

ReverseProxy.with_rewrite

fn (p: ReverseProxy) with_rewrite(f: fn(Request, Request) -> Request) -> ReverseProxy

The proxy applying f(in, out) to each outgoing request out after its own rewrite, in being the request received (httputil’s Rewrite with ProxyRequest.In and Out).

Source: std/http.xo:550

ReverseProxy.serve

fn (p: ReverseProxy) serve(req: Request, body: BodyReader) -> Response uses net.dial

Forwards req, its body read from body, and returns the target’s response with its body streamed back.

Source: std/http.xo:553

ResponseHead

struct ResponseHead {
  status: Int
  headers: Map[Str, Str]
}

A response’s status and header, without its body (decision 0404).

Source: std/http.xo:555

ClientStream

struct ClientStream {}

A response whose body is read as it arrives (decision 0404): from Client.open, read with read or read_all and released with close (or when the last copy goes): a body read to its end gives its connection back to the client’s pool, any other is closed.

Source: std/http.xo:563

ClientStream.head

fn (s: ClientStream) head() -> ResponseHead

Source: std/http.xo:567

ClientStream.read

fn (s: ClientStream) read(max: Int = 32768) -> Bytes? ! ClientErr uses net.dial

The next bytes of the body, at most max, None at its end; a body cut short is Protocol (unexpected EOF), never an end.

Source: std/http.xo:570

ClientStream.read_all

fn (s: ClientStream) read_all(max_size: Int = 1073741824) -> Bytes ! ClientErr uses net.dial

The rest of the body; Protocol past max_size bytes.

Source: std/http.xo:572

ClientStream.close

fn (s: ClientStream) close()

Releases the stream’s connection; again does nothing.

Source: std/http.xo:574

ClientStream.trailers

fn (s: ClientStream) trailers() -> Map[Str, Str]

The response’s trailers (Go’s Response.Trailer, decision 0433), names canonical; empty until read has returned None.

Source: std/http.xo:577

ClientErr

enum ClientErr {
  InvalidUrl(msg: Str)
  Connect(msg: Str)
  Timeout
  Protocol(msg: Str)
  Canceled
}

Source: std/http.xo:583

ClientErr.display

fn (e: ClientErr) display() -> Str

invalid URL: MSG, MSG for a Connect, request timed out, protocol error: MSG, canceled (decision 0358).

Source: std/http.xo:593

Url

struct Url {
  scheme: Str
  host: Str
  port: Int?
  path: Str
  query: Map[Str, Str]
}

Source: std/http.xo:597

UrlErr

struct UrlErr {
  msg: Str
}

Source: std/http.xo:605

UrlErr.display

fn (e: UrlErr) display() -> Str

The message (decision 0358).

Source: std/http.xo:610

Functions

router

fn router() -> Router

Source: std/http.xo:20

serve_component

fn serve_component(r: Router)

Serves the request a wasi:http component was called with through r (decision 0447): main builds the router and calls this; faults off the wasm backend.

Source: std/http.xo:40

fn parse_cookie(line: Str) -> List[Cookie] ! CookieErr

The cookies of a Cookie field’s value (Go’s ParseCookie).

Source: std/http.xo:266

fn parse_set_cookie(line: Str) -> Cookie ! CookieErr

The cookie of a Set-Cookie field’s value (Go’s ParseSetCookie).

Source: std/http.xo:268

key

fn key[T](name: Str) -> Key[T]

Source: std/http.xo:279

new_request

fn new_request(method: Str, url: Str, headers: Map[Str, Str] = {}, body: Bytes = b"") -> Request

Source: std/http.xo:282

json

fn json[T: Json](status: Int, v: T) -> Response

Source: std/http.xo:289

serve_content

fn serve_content(req: Request, name: Str, modtime: Time?, content: Bytes, headers: Map[Str, Str] = {}) -> Response

The response net/http’s ServeContent writes for req from content (decision 0306): Range requests (206, or multipart/byteranges for several), the conditional requests against modtime and an ETag in headers (304, 412), 416 for a range outside the content, the Content-Type from headers, name’s extension, or the content, and Last-Modified, Accept-Ranges, Content-Length. headers are the fields a Go handler sets on its ResponseWriter before the call.

Source: std/http.xo:297

text

fn text(status: Int, s: Str) -> Response

Source: std/http.xo:298

empty

fn empty(status: Int) -> Response

Source: std/http.xo:299

redirect

fn redirect(req: Request, url: Str, status: Int) -> Response

Go’s Redirect: a response of status with Location: url; a url with no scheme and no host is resolved against req’s escaped path (Go’s rules: the path’s directory, . and .. cleaned, a trailing slash kept, the query kept apart), non ASCII bytes of the Location percent encoded; a GET or HEAD gets text/html; charset=utf-8 and a GET the body <a href="URL">Status Text</a>. on a line.

Source: std/http.xo:306

status_text

fn status_text(code: Int) -> Str

The text of an HTTP status code, as Go’s http.StatusText (Not Found for 404); empty for a code Go does not name.

Source: std/http.xo:309

error_page

fn error_page(status: Int, msg: Str) -> Response

Go’s Error: text/plain; charset=utf-8, X-Content-Type-Options: nosniff, the body msg and a newline.

Source: std/http.xo:312

not_found

fn not_found() -> Response

Go’s NotFound: error_page(404, “404 page not found”).

Source: std/http.xo:314

error_html

fn error_html(status: Int, title: Str, detail: Str) -> Response

An HTML error page: text/html (nosniff), the title in <title> and <h1>, the detail in <p>, both escaped (std.md 4.3).

Source: std/http.xo:317

stream

fn stream[fx: Effects](status: Int, f: fn(BodyWriter) -> () ! IoErr uses fx) -> Response uses fx

Source: std/http.xo:318

pipe

fn pipe() -> (PipeWriter, BodyReader)

A body written by one task while another sends it (Go’s io.Pipe, decision 0433): the reader goes to Request.with_body_reader, each write waits until the request has taken its bytes.

Source: std/http.xo:375

server

fn server(l: Listener, r: Router) -> Server

Source: std/http.xo:399

max_body

fn max_body(n: Int) -> fn(Request, Next) -> Response

A middleware that answers 413 with Go’s MaxBytesReader text (http: request body too large) for a body over n bytes (a streamed body is capped at n as it is read).

Source: std/http.xo:474

tls_cert

fn tls_cert(cert_pem: Bytes, key_pem: Bytes) -> TlsCert ! TlsErr

Parses a PEM certificate chain and its PEM private key (std.md 4.6).

Source: std/http.xo:480

client

fn client(net: Net, timeout: Duration = 30s) -> Client

Source: std/http.xo:498

reverse_proxy

pub fn reverse_proxy(client: Client, target: Url) -> ReverseProxy

A reverse proxy to target, for a handle_stream route: r.handle_stream("/api/", fn(req, body) { p.serve(req, body) }). It forwards each request to target (decision 0404, httputil.ReverseProxy with SetURL and SetXForwarded): the target’s scheme and host, its path joined before the request’s, the queries merged; hop-by-hop fields removed both ways; X-Forwarded-For, -Host and -Proto set; rewrite applied last; the body streamed both ways, redirects returned as they came. A failure to reach the target is 502, a timeout 504.

Source: std/http.xo:545

parse_url

fn parse_url(s: Str) -> Url ! UrlErr

Source: std/http.xo:595

gzip_responses

fn gzip_responses(min_size: Int = 1024, level: compress.Level = compress.Level.Default) -> fn(Request, Next) -> Response

A middleware that compresses responses with gzip when the request accepts it (std.md 4.7, decision 0305): r.wrap(http.gzip_responses()).

Source: std/http.xo:614

↑ index