Skip to content

api-reference.md

Latest commit

 

History

History
124 lines (82 loc) · 4.41 KB

api-reference.md

File metadata and controls

124 lines (82 loc) · 4.41 KB
Raw

API reference

This page summarizes the public names exported by smallserver. Signatures omit overload detail where prose is clearer.

Application

SmallServer(regex_config=None, *, route_error_observer=None, websocket_config=None)

  • get(path), post(path), put(path), patch(path), delete(path) — route decorators for one supported method.
  • route(path, methods) — atomic multi-method route decorator.
  • get_regex, post_regex, put_regex, patch_regex, delete_regex, and route_regex(pattern, methods) — optional timeout-bounded regex decorators.
  • websocket(path, *, origins=None, subprotocols=()) — static HTTP/1.1 WebSocket Upgrade decorator.
  • async dispatch(request) — dispatch an existing Request.
  • listen(host="127.0.0.1", port=8000, config=None, *, protocol="http1", http2_config=None, runtime=None, start=None) — managed blocking lifecycle or caller-owned scheduling/startup.
  • serve(runtime, host="127.0.0.1", port=8000, config=None, *, protocol="http1", http2_config=None) — schedule against a caller-owned runtime and return immediately.

HTTP values

Headers(values=None)

Immutable, case-insensitive mapping with items() and get().

Request(method, path, headers, body=b"", version="HTTP/1.1")

Frozen request value with validated method, path, headers, and byte body, plus raw_target, query_string, immutable path_params, and route_pattern.

Response(status=200, body=b"", headers=Headers())

Frozen response value. Response.text(), Response.json(), and to_http1() provide common construction and serialization paths.

Server lifecycle

ServerConfig(...)

Frozen finite-limit configuration. See Configuration.

ManagedRuntimeConfig(...)

Frozen SmallOS settings used only when listen() creates the runtime. A caller-supplied runtime retains its own configuration.

HTTP2Config(...)

Optional cleartext HTTP/2 stream, buffer, frame-batch, and timeout limits. See Cleartext HTTP/2. Constructing a listener with protocol="http2" requires the smallserver[http2] extra.

ServerHandle

Read-only properties: address, port, closed, failure, finished, cleanup_errors, owned_connection_count, dropped_route_error_events, and route_observer_failures.

Operations: close(), async close_from_task(task), and finalize().

RegexRouteConfig(...)

Finite optional-regex limits. RouteErrorEvent, RouteMatchTimeout, RoutePathTooLarge, and RegexRoutesUnavailable describe its bounded error surface. Runtime regex matching requires smallserver[regex-routes].

WebSockets

  • WebSocketConfig — finite connection, frame, message, mailbox, and deadline limits.
  • WebSocket — accept, reject, receive/send methods, ping, close, iteration, request, and negotiated subprotocol.
  • WebSocketMessage — complete typed text or binary message.
  • WebSocketDisconnect, WebSocketStateError, and WebSocketCapacityError — application-visible lifecycle and capacity outcomes.
  • WebSocketUnavailable — the optional wsproto engine is missing.

See WebSockets for handshake and completion semantics.

Adapters

ThreadAdapter(max_workers=None, max_pending=64, ...)

Bounded worker-thread execution for synchronous or thread-affine callables.

AsyncioAdapter(max_pending=64, ...)

Bounded coroutine execution on one persistent asyncio loop thread.

AdapterRegistry(**adapters)

Methods: register, get, call, names, items, and shutdown. It also implements a context manager and exposes closed.

http_error_from_adapter(exc)

Convert a SmallOS AdapterError to a sanitized HTTPError.

Applications can import AdapterError, AdapterCapacityError, AdapterUnavailableError, AdapterClosedError, AdapterCancelledError, AdapterProtocolError, and AdapterExecutionError directly from smallserver.

AdapterShutdownError

Raised after registry shutdown attempts every adapter but one or more fail. Its failures tuple contains (name, exception) entries.

Errors

  • HTTPError(status, detail="")
  • ServerConfigurationError
  • ServerStartupError
  • ServerFinalizationError

Cleanup errors expose cleanup_errors, cleanup_complete, retry_cleanup(), and finalize(). ServerStartupError additionally exposes primary_error.

Public typing information is shipped through smallserver/py.typed.