The complete reference for every script-facing builtin, object method, and
configuration accessor exposed by the web module. For an overview,
installation, and a quickstart, see the README.
A script load("web", …)s the module-level builtins — create_server, the
response builders, the authentication constructors, and the middleware
constructors — plus a set of configuration accessors (get_<key> / set_<key>)
generated from the module's options. create_server returns a server object
that registers routes and controls the lifecycle; route handlers receive a
request object and return a response object.
- Server creation
- Response builders
- Static file serving
- Authentication constructors
- Middleware constructors
- Server object
- Request object
- Response object
- Custom middleware
- Hardening — the bind guardrail
- Configuration
Creates an HTTP server.
Parameters:
host(string, optional): Host to bind to. Falls back to thehostconfig option when omitted (default:localhost).port(int, optional): Port to listen on. Falls back to theportconfig option when omitted. Must be in1..65535.server_header(string, optional): Overrides the configuredServerresponse header for this server.
Returns: A server object (see Server object).
Errors: Fails if port is not a valid integer, or if it is outside
1..65535.
Example:
srv = create_server(host="localhost", port=8080)Each builder returns a response object that a handler returns to emit the HTTP response. The settable fields and methods of that object are documented under Response object.
Builds a plain response from a string body, an optional status code, and an
optional {name: value} headers dict.
Parameters:
body(string): The response body.status(int, optional): HTTP status code (default:200).headers(dict, optional):{name: value}response headers (default:{}).
Returns: A response object. No Content-Type is forced; when none is set,
the server sends application/json by default.
Example:
response("OK", status=201, headers={"X-Request-Id": "abc"})Encodes data to JSON and sets Content-Type: application/json.
Parameters:
data: The payload. Astringorbytesvalue is sent verbatim; any other value (dict, list, number, …) is serialized via starlet's JSON encoder.status(int, optional): HTTP status code (default:200).headers(dict, optional):{name: value}response headers (default:{}).
Returns: A response object.
Errors: Fails if data cannot be marshalled to JSON, or if headers is not
a string→string dict.
Example:
json_response({"id": 1, "name": "Alice"})HTML response; sets Content-Type: text/html.
Parameters:
content(string): The HTML body.status(int, optional): HTTP status code (default:200).headers(dict, optional):{name: value}response headers (default:{}).
Returns: A response object.
Example:
html_response("<h1>Hello, World!</h1>")Plain-text response; sets Content-Type: text/plain.
Parameters:
text(string): The text body.status(int, optional): HTTP status code (default:200).
Returns: A response object.
Example:
text_response("pong")Serves the file at filepath from disk.
Parameters:
filepath(string): Path to the file to serve.content_type(string, optional): Sets theContent-Typeheader.filename(string, optional): AddsContent-Disposition: attachment; filename=...to prompt a download.
Returns: A response object.
Example:
file_response("/srv/report.pdf", content_type="application/pdf",
filename="report.pdf")Serves the file at filepath from disk — like file_response but without the
attachment filename.
Parameters:
filepath(string): Path to the file to serve.content_type(string, optional): Sets theContent-Typeheader.
Returns: A response object.
Example:
send_file("/srv/index.html", content_type="text/html")Sends the in-memory string data as a download.
Parameters:
data(string): The in-memory content to send.filename(string): Required; setsContent-Disposition: attachment; filename=....content_type(string, optional): TheContent-Typeheader (default:application/octet-stream).
Returns: A response object.
Example:
send_data("col1,col2\n1,2\n", filename="data.csv", content_type="text/csv")Redirect response carrying a Location header.
Parameters:
location(string): The target URL for theLocationheader.status(int, optional): HTTP status code (default:302).
Returns: A response object.
Example:
redirect("/login", status=303)Error response with the given status code and message body. If a matching
error_handler is registered on the server, that handler renders the body
instead — see error_handler.
Parameters:
status(int): HTTP status code.message(string, optional): The response body (default:"").
Returns: A response object.
Example:
error_response(404, message="Not Found")Builds a read-only static-file root, mounted on a server with
srv.static. Serving goes through http.ServeContent, so
Range requests, conditional GET (If-Modified-Since / If-None-Match → 304),
and Content-Type by extension all work without the script handling them; an
*os.File is streamed with sendfile zero-copy.
Parameters:
root(string): The directory to serve. Must not be empty. At mount time it must exist and resolve to a directory under the working directory captured when the server was created. The host-onlyallow_unsafe_file_pathsoption permits an outside root; it does not disable confinement within that mount.index(string or list of strings, optional): Directory default pages, tried in order (default:["index.html", "index.htm"]). An empty list disables index pages (directories then 404).spa(bool, optional): When true, an unmatched path that is not a file serves the first index page (single-page-app fallback) instead of404(default:false— a miss is a404, which is safer and more predictable).cache_control(string, optional): ACache-Controlheader value to set on served files (default: none).
Returns: A web.StaticDir handle (pass it to srv.static).
The mount is bound to the resolved physical root at registration. Later cwd changes or retargeting of the supplied symlink alias do not select a new root.
Safety within an accepted mount (always on, no opt-out):
- No path traversal. The request path is cleaned and anchored under
root;..can never escape, and the resolved path is re-checked against the absolute root. - No dotfiles / junk. Any path segment starting with
.(e.g..git,.env) or named@eaDiris404, never served — except the standard.well-known/location (RFC 8615: ACME challenges,security.txt, …), which is served (a dotfile inside it is still blocked). - No directory listing. A directory with no index page is
404; the filesystem is never enumerated. - Read-only. No write path is ever exposed.
Example:
load("web", "create_server", "static_dir", "text_response")
srv = create_server(port=8080) # localhost by default
srv.static("/", static_dir("./public")) # serve a directory as a site
srv.get("/health", lambda req: text_response("ok")) # explicit routes win
srv.run()Each constructor returns an authenticator object exposing a single method,
middleware(), which yields a middleware you attach
with srv.use_for(...). On failure the middleware short-circuits with a 401
(Basic auth also sends a WWW-Authenticate challenge); on success it stores the
user info in the request context under auth_user.
API-key authenticator. Accepts a key supplied either in the named header or in
the query_param query-string parameter, matched against the allowed keys
list.
Parameters:
keys(list, optional): Allowed API keys (default:[]).header(string, optional): Header to read the key from (default:X-API-Key).query_param(string, optional): Query-string parameter to read the key from (default:api_key).
Returns: An authenticator object.
Errors: Fails if keys is not a list of strings.
Example:
api_key_auth(keys=["k1", "k2"], header="X-API-Key")Bearer-token authenticator. The Bearer scheme prefix (and its trailing space)
is stripped from the Authorization header (a custom header is used as-is or
also de-prefixed), then validate_func(token) is called.
Parameters:
validate_func(callable): Called asvalidate_func(token); return user info on success, orNoneto reject.header(string, optional): Header to read the token from (default:Authorization).
Returns: An authenticator object.
Example:
def check(token):
return {"user": "alice"} if token == "s3cret" else None
bearer_auth(validate_func=check)HTTP Basic authenticator from a {username: password} dict.
Parameters:
users(dict, optional):{username: password}credentials (default:{}).realm(string, optional): Realm shown in theWWW-Authenticatechallenge (default:Restricted).
Returns: An authenticator object.
Errors: Fails if users is not a string→string dict.
Example:
basic_auth(users={"admin": "secret"}, realm="Admin")An authenticator (from any of the three constructors above) exposes one method.
Produces a middleware to attach with srv.use_for(...).
- Parameters: None
- Returns: A middleware object.
auth = basic_auth(users={"admin": "secret"})
srv.use_for("/admin/*", auth.middleware())In handlers, read auth data through the request helpers — req.basic_auth(),
req.bearer_token(), req.get_header("X-API-Key") — or the auth_user entry
the authenticator wrote into req.context.
Each constructor returns a middleware object you attach with srv.use(mw) (all
paths) or srv.use_for(pattern, mw). See Custom middleware
for the path-pattern and custom-middleware model.
Cross-Origin Resource Sharing. Handles preflight OPTIONS with a 204 and
echoes the configured headers.
Parameters:
origins(list, optional): Allowed origins. Empty defaults to*(default:[]).methods(list, optional): Allowed methods. Empty defaults to the common method set (default:[]).headers(list, optional): Allowed request headers. Empty defaults toContent-Type, Authorization(default:[]).credentials(bool, optional): Whether to allow credentials (default:False).
Returns: A middleware object.
Example:
cors_middleware(origins=["https://example.com"], credentials=True)Logs each request to stdout.
Parameters:
format(string, optional): Log line format (default:{method} {path} {status} {duration}ms). The{method},{path},{status}, and{duration}placeholders are substituted.
Returns: A middleware object.
Example:
logging_middleware()security_headers_middleware(frame_options?, content_type_options?, xss_protection?, hsts?, csp?, referrer_policy?)
Adds common security response headers. Each option emits its header only when non-empty.
Parameters:
frame_options(string, optional):X-Frame-Optionsvalue (default:DENY).content_type_options(string, optional):X-Content-Type-Optionsvalue (default:nosniff).xss_protection(string, optional):X-XSS-Protectionvalue (default:1; mode=block).hsts(string, optional):Strict-Transport-Securityvalue (default:"", header omitted).csp(string, optional):Content-Security-Policyvalue (default:"", header omitted).referrer_policy(string, optional):Referrer-Policyvalue (default:"", header omitted).
Returns: A middleware object.
Example:
security_headers_middleware(hsts="max-age=31536000")Records handler duration and writes it to the named response header.
Parameters:
header(string, optional): Response header to write the duration to (default:X-Response-Time).
Returns: A middleware object.
Example:
timing_middleware()Parses a JSON request body (when Content-Type: application/json) into the
request context under json_data, and tags JSON-looking response bodies with
Content-Type: application/json when unset.
Parameters: None
Returns: A middleware object.
Example:
json_middleware()gzip response compression when the client sends Accept-Encoding: gzip, the body
is at least min_size bytes, and its content type is compressible.
Parameters:
level(int, optional): gzip level. A value outside1..9falls back to6(default:6).min_size(int, optional): Minimum body size in bytes to compress (default:1024).types(list, optional): Compressible content types. Empty defaults to the common text/JSON set (default:[]).
Returns: A middleware object.
Example:
compression_middleware(level=9, min_size=512)Per-key rate limiting: at most requests per window seconds. Over the limit
returns 429 with a Retry-After; otherwise sets X-RateLimit-* headers. State
is held in an in-process memory store.
Parameters:
requests(int, optional): Max requests per window (default:100).window(int, optional): Window length in seconds (default:60).key_func(callable, optional): Called askey_func(req)to derive the rate key; defaults to the client IP (and falls back to the client IP if the callable errors or does not return a string).
Returns: A middleware object.
Example:
rate_limit_middleware(requests=100, window=60)Adds Cache-Control (and optional Vary) headers to GET responses.
Parameters:
max_age(int, optional):max-agein seconds (default:3600).private(bool, optional): Selectsprivateoverpublic(default:False).patterns(list, optional): When non-empty, only matching request paths are affected (default:[]).vary(list, optional): Header names for theVaryheader (default:[]).
Returns: A middleware object.
Example:
cache_middleware(max_age=600, patterns=["/static/*"], vary=["Accept-Encoding"])Rejects oversized requests.
Parameters:
max_content_length(int, optional): Body size cap in bytes; over it returns413(default:10485760, i.e. 10 MiB).max_url_length(int, optional): URL length cap; over it returns414(default:2048).max_headers(int, optional): Header count cap; over it returns406(default:100).
Returns: A middleware object.
Example:
request_size_middleware(max_content_length=1048576)The object returned by create_server registers routes and controls the server
lifecycle.
Registers a GET route.
path(string): Route path; Flask-style braces (/users/{id}) define path parameters, read back withreq.param("id").handler(callable):func(req)returning a response.- Returns: None
Registers a POST route. Same parameters as get.
Registers a PUT route. Same parameters as get.
Registers a DELETE route. Same parameters as get.
Registers a PATCH route. Same parameters as get.
Registers an OPTIONS route. Same parameters as get.
Registers a HEAD route. Same parameters as get.
Registers one handler for one or more HTTP methods.
methods(string or list): A method string (e.g."GET") or a list of method strings.path(string): Route path.handler(callable):func(req)returning a response.- Returns: None
srv.route(["GET", "POST"], "/submit", handle_submit)Returns a route group sharing the prefix.
prefix(string): Path prefix shared by the group's routes.- Returns: A route group exposing the same per-method registrars
(
grp.get(path, handler),grp.post(...), andput/delete/patch/options/head).
api = srv.group("/api/v1")
api.get("/users", list_users)Mounts a static_dir at a URL
prefix. Static files are served as a fallback for unmatched routes, so any
explicit route registered on the server takes precedence. A request under
prefix that does not resolve to a servable file falls through to the normal
404 (it does not leak the filesystem).
prefix(string): URL prefix to mount under (/serves the whole site).dir(web.StaticDir): the handle returned bystatic_dir(...).- Returns:
None. A missing, non-directory or unauthorized root raises an error without registering the mount. Create the directory before mounting.
srv.static("/assets", static_dir("./public/assets", cache_control="max-age=3600"))Adds global middleware (matches every path). Shorthand for
srv.use_for("/*", middleware). Takes exactly one positional argument.
middleware: A middleware object or a customfunc(req, next)callable.- Returns: None
Adds middleware for requests whose path matches path_pattern.
path_pattern(string): Pattern — exact path,/*prefix glob, mid-path*, or{param}segments.middleware: A middleware object (from a constructor above or an authenticator'smiddleware()) or a customfunc(req, next)callable — see Custom middleware.- Returns: None
Registers a custom handler for one status code or a list of status codes. The
server invokes it whenever a response with a matching status (including built-in
404/405) is produced.
status_codes(int or list): One status code, or a list of codes.handler(callable):handler(req)returning a response.- Returns: None
srv.error_handler([404, 405], lambda req: json_response({"error": "not found"}, status=404))Starts listening in the background (non-blocking); surfaces an immediate bind failure (e.g. port in use, or a denied non-loopback bind).
- Parameters: None
- Returns: None
Gracefully shuts the server down.
- Parameters: None
- Returns: None
Starts and blocks until the server stops.
- Parameters: None
- Returns: None
Returns whether the server is currently running.
- Parameters: None
- Returns: Boolean.
The req passed to handlers and middleware exposes read-only properties and
methods.
Properties: method, url, path, host, remote, client_ip, proto,
headers (dict), query (dict), and context (dict — middleware can read/write
per-request state here, e.g. auth_user).
Returns the raw request body as a string.
- Parameters: None
- Returns: String.
Parses the body as JSON and returns the value.
- Parameters: None
- Returns: The parsed value, or
Nonewhen the body is empty or not valid JSON.
Parses URL-encoded / multipart form data into a dict.
- Parameters: None
- Returns: A dict; a key with multiple values becomes a list.
Returns uploaded files (multipart) keyed by field name.
- Parameters: None
- Returns: A dict keyed by field name. Each entry is a dict with
filename,size,content_type, and aread()method returning the file content as a string.
for field, f in req.files().items():
data = f["read"]()
print(field, f["filename"], f["size"], f["content_type"])Returns the named cookie's value.
name(string): Cookie name.- Returns: The cookie value, or
None.
Returns the named path parameter (e.g. id from /users/{id}).
name(string): Path-parameter name.- Returns: The parameter value, or
None.
Returns the named request header.
name(string): Header name.default(optional): Returned when the header is absent (default:None).- Returns: The header value, or
default.
Extracts a Bearer token, stripping the Bearer scheme prefix and its trailing
space on Authorization.
header(string, optional): Header to read from (default:Authorization).- Returns: The token string, or
None.
Returns HTTP Basic credentials.
- Parameters: None
- Returns: A
(username, password)tuple, orNone.
A response (from a builder, or constructed by middleware) has settable fields and methods.
Settable fields: status_code (int), headers (dict), body (string), and
file_path (string).
Sets a response header.
name(string): Header name.value(string): Header value.- Returns: None
Returns a response header.
name(string): Header name.default(optional): Returned when the header is absent (default:None).- Returns: The header value, or
default.
Appends a Set-Cookie header. Each call emits its own header line (cookies are
never comma-combined).
name(string): Cookie name.value(string): Cookie value.max_age(int, optional):Max-Agein seconds (default:None, omitted).path(string, optional): Cookie path (default:/).domain(string, optional): Cookie domain (default:"").secure(bool, optional): Sets theSecureflag (default:False).http_only(bool, optional): Sets theHttpOnlyflag (default:True).- Returns: None
Appends a Set-Cookie line that expires the named cookie (Max-Age=0).
name(string): Cookie name.path(string, optional): Cookie path (default:/).domain(string, optional): Cookie domain (default:"").- Returns: None
Middleware carries a path pattern; srv.use(mw) is shorthand for
srv.use_for("/*", mw). Patterns support exact paths, /* prefix globs,
mid-path *, and {param} segments.
A custom middleware is a callable func(req, next) that returns a response. It
calls next(req) to invoke the rest of the chain (next is itself a builtin
that takes the request and returns the downstream response), and may inspect or
mutate the response before returning it:
def add_header(req, next):
resp = next(req)
resp.set_header("X-Custom-Server", "Starlark-Web")
return resp
srv.use(add_header)Built-in middleware is composed the same way:
load("web", "create_server", "logging_middleware", "cors_middleware",
"security_headers_middleware", "rate_limit_middleware")
srv = create_server()
srv.use(logging_middleware()) # all paths
srv.use(cors_middleware(origins=["https://example.com"], credentials=True))
srv.use_for("/api/*", rate_limit_middleware(requests=100, window=60))
srv.use_for("/admin/*", security_headers_middleware(hsts="max-age=31536000"))By default the server binds to localhost, and starting it on any non-loopback
address (0.0.0.0, ::, an empty host, or a public/LAN IP) is refused with
an error. This keeps a server started from an untrusted script off the network.
To expose it deliberately, opt in with the allow_public_bind config option
(or the WEB_ALLOW_PUBLIC_BIND environment variable):
srv = create_server(host="0.0.0.0", port=8080)
srv.run() # error: refusing to bind to non-loopback host "0.0.0.0"; set allow_public_bind=true ...The guardrail defaults to off — historical scripts that bind localhost keep
working unchanged. Full host-level network capability gating (deny-by-policy)
lives in the sandbox runtime layer; this is the module-local guardrail.
The server captures the physical working directory at creation. Confined
file_response, send_file, direct file_path assignments and custom error
responses resolve relative paths against that fixed root. Changing cwd later
does not widen this boundary.
Each module configuration option is exposed to scripts as a pair of generated
accessor builtins (loaded from the web module alongside the functions above):
get_<key>()— returns the current value of the option.set_<key>(value)— sets the option (returnsNone).
An option's value resolves in priority order: an explicit set_<key> value, the
environment variable, then the default. The host and port options serve as
defaults used by create_server when the corresponding argument is not provided;
the timeouts, body cap, debug mode, server header, and bind guardrail apply to
every server the module creates.
Most web options expose both get_<key> and set_<key>. Two are
host-only — max_body_size and allow_unsafe_file_paths — and expose only
get_<key>: they are host-side safety guards (memory-DoS cap and file-path
confinement) that an untrusted script must not be able to weaken, so they can be
set only via Go configuration or their WEB_* environment variable, never a
script set_<key> builtin. (No web option is secret; a secret option would
expose only its set_<key> accessor — the inverse of host-only.)
Because they are host-only, there is deliberately no set_max_body_size and
no set_allow_unsafe_file_paths builtin — a script cannot call these; set
them from Go configuration or the corresponding WEB_* environment variable.
| Option | Getter | Setter | Type | Env var | Default | Description |
|---|---|---|---|---|---|---|
host |
get_host |
set_host |
string | WEB_HOST |
localhost |
Default host to bind to |
port |
get_port |
set_port |
int | WEB_PORT |
8080 |
Default port to listen on |
read_timeout |
get_read_timeout |
set_read_timeout |
int | WEB_READ_TIMEOUT |
30 |
Read timeout in seconds |
write_timeout |
get_write_timeout |
set_write_timeout |
int | WEB_WRITE_TIMEOUT |
30 |
Write timeout in seconds |
max_body_size |
get_max_body_size |
(host-only) | int | WEB_MAX_BODY_SIZE |
33554432 |
Maximum request body size in bytes (32 MiB) |
debug_mode |
get_debug_mode |
set_debug_mode |
bool | WEB_DEBUG_MODE |
false |
Enable Gin debug logging |
server_header |
get_server_header |
set_server_header |
string | WEB_SERVER_HEADER |
Starlark-Web/1.0 |
Custom Server header value |
allow_public_bind |
get_allow_public_bind |
set_allow_public_bind |
bool | WEB_ALLOW_PUBLIC_BIND |
false |
Allow binding to a non-loopback (public) address |
allow_unsafe_file_paths |
get_allow_unsafe_file_paths |
(host-only) | bool | WEB_ALLOW_UNSAFE_FILE_PATHS |
false |
Allow file responses and static mounts outside the server's captured working directory |
Example:
load(
"web",
"create_server",
# getters (host-only max_body_size / allow_unsafe_file_paths have no setter)
"get_host", "get_port", "get_read_timeout", "get_write_timeout",
"get_max_body_size", "get_debug_mode", "get_server_header",
"get_allow_public_bind", "get_allow_unsafe_file_paths",
# setters
"set_host", "set_port", "set_read_timeout", "set_write_timeout",
"set_debug_mode", "set_server_header",
"set_allow_public_bind",
)
set_port(9090)
print(get_port()) # 9090
srv = create_server() # binds to host=localhost, port=9090
srv.run()