Build server-side HTTP applications from Starlark with a Flask-inspired API: routing, route groups, path-pattern middleware, request/response helpers, pluggable authentication, and custom error handlers β on top of gin.
Within the Star* ecosystem starpkg is "support for necessary local
operations plus simple abstractions over common online services, for ease of
use." web is a local capability: it stands up an HTTP listener inside the
host process so a script can serve requests (the inverse of an HTTP client β
for outbound calls use starlet's http module).
- Routing β
create_serverreturns a server with per-method registrars (get/post/put/β¦),route, and routegroups; Flask-style/{id}path parameters. - Responses β builders for plain, JSON, HTML, text, file, download, and
redirect/error responses, returned from a
func(req)handler. - Middleware β built-in CORS, logging, security headers, timing, JSON,
compression, rate limiting, caching, and request-size limits, plus custom
func(req, next)middleware, attached globally or per path pattern. - Authentication β pluggable
api_key_auth,bearer_auth, andbasic_authauthenticators that yield middleware. - Safe by default β a default-deny loopback bind guardrail keeps a
server started from an untrusted script off the network unless the host opts
in with
allow_public_bind.
For the complete per-builtin / per-object-method reference β signatures, parameters, returns, errors, examples β and the configuration accessors, see docs/API.md.
go get github.com/starpkg/webWire the module into a Starlet interpreter, then load("web", β¦) from a script:
package main
import (
"github.com/1set/starlet"
"github.com/starpkg/web"
)
func main() {
machine := starlet.NewWithNames(nil, []string{"go_idiomatic"}, nil)
machine.AddLazyloadModules(starlet.ModuleLoaderMap{
web.ModuleName: web.NewModule().LoadModule(),
})
_, err := machine.RunScript([]byte(`
load("web", "create_server", "html_response", "json_response")
srv = create_server(host="localhost", port=8080)
srv.get("/", lambda req: html_response("<h1>Hello, World!</h1>"))
srv.get("/users/{id}", lambda req: json_response({"id": req.param("id")}))
srv.run()
`), nil)
if err != nil {
panic(err)
}
}A script loads the module, calls create_server to get a server object,
registers route handlers (each a func(req) returning a response), and starts
it with srv.start() (non-blocking) or srv.run() (blocking).
Module builtins (load("web", β¦)):
create_server(host?, port?, server_header?)β create an HTTP server object.response(body, status?, headers?)β plain response.json_response(data, status?, headers?)β JSON response.html_response(content, status?, headers?)β HTML response.text_response(text, status?)β plain-text response.file_response(filepath, content_type?, filename?)β serve a file (optionally as a download). Confined to the working directory captured when the server is created; setallow_unsafe_file_pathsto serve outside it.send_file(filepath, content_type?)β serve a file (same working-directory confinement asfile_response).send_data(data, filename, content_type?)β send in-memory data as a download.static_dir(root, index?, spa?, cache_control?)β read-only static-file root forsrv.static; mounts require an existing directory under the server's captured working directory by default (no traversal/dotfiles/listing).redirect(location, status?)β redirect response.error_response(status, message?)β error response.api_key_auth(keys?, header?, query_param?)β API-key authenticator.bearer_auth(validate_func, header?)β bearer-token authenticator.basic_auth(users?, realm?)β HTTP Basic authenticator.cors_middleware(origins?, methods?, headers?, credentials?)β CORS middleware.logging_middleware(format?)β request logging middleware.security_headers_middleware(frame_options?, content_type_options?, xss_protection?, hsts?, csp?, referrer_policy?)β security headers middleware.timing_middleware(header?)β response-time header middleware.json_middleware()β JSON request/response middleware.compression_middleware(level?, min_size?, types?)β gzip compression middleware.rate_limit_middleware(requests?, window?, key_func?)β per-key rate limiting middleware.cache_middleware(max_age?, private?, patterns?, vary?)βCache-Controlmiddleware.request_size_middleware(max_content_length?, max_url_length?, max_headers?)β request-size limiting middleware.
Server object: get / post / put / delete / patch / options / head,
route, group, static (mount a static_dir), use, use_for,
error_handler, start, stop, run, is_running.
Request object β properties method, url, path, host, remote,
client_ip, proto, headers, query, context; methods body, json,
form, files, cookie, param, get_header, bearer_token, basic_auth.
Uploaded-file entries expose read.
Response object β settable status_code, headers, body, file_path;
methods set_header, get_header, set_cookie, delete_cookie.
Authenticators expose middleware. Custom middleware receives a next callable.
See docs/API.md for the full signatures, return values, errors, and examples of every builtin and method above.
The module's options (host, port, read_timeout, write_timeout,
max_body_size, debug_mode, server_header, allow_public_bind,
allow_unsafe_file_paths) are configured via environment variables (WEB_*) or
per-option get_<key> / set_<key> accessor builtins, and serve as defaults for
the servers the module creates. Two opt-in levers default to off: allow_public_bind
lets the host expose a server beyond loopback, and allow_unsafe_file_paths lets
file responses and static mounts use paths outside the server's captured working
directory. Relative file responses remain anchored there even if the process
changes directory later. Static mounts bind to a resolved directory at mount
time; changing its original symlink alias cannot redirect the mount. Both
allow_unsafe_file_paths and max_body_size are host-only (no set_<key>
builtin) β an untrusted script cannot weaken these safety guards; set them via
Go config or WEB_*. See the
Configuration section of docs/API.md for the full
option table, defaults, accessors, and the bind-guardrail details.
This project is licensed under the MIT License β see the LICENSE file for details.
Go 1.25.0 or newer is required. Production builds use Go 1.27.1. This patch retains the established Starlark interpreter pin and updates the reviewed networking/Unicode dependencies.
The Go 1.25.0 floor comes from the networking and Unicode fixes (x/net and
x/text), independently of the Starlark pin. Production applications should
use a supported patched Go toolchain. x/crypto v0.55.0 keeps Go 1.25
compatibility; this module imports its SHA-3 package, not SSH or OpenPGP. Those
unused packages retain advisories, and CI rejects their introduction until a
separate dependency and compatibility review. This is not a claim that the
entire dependency module is free of vulnerabilities.