Module wade

Description
Function Index
Function Details

Wade is a lightweight HTTP server and WebSocket framework for Erlang/OTP.

Behaviours: gen_server.

Description

Wade is a lightweight HTTP server and WebSocket framework for Erlang/OTP. It provides routing, request/response handling, WebSocket support, and utilities for building web applications. Features: - RESTful routing with parameter extraction - WebSocket upgrade and messaging - Request/response utilities (query, body, headers, etc.) - Built-in HTTP client - Error handling and timeouts - Compatible with inets and gen_server

Function Index

body/2	Get the value of a body parameter from the request.
body/3	Get the value of a body parameter, with a default if missing.
close_sse/1
close_ws/1	Close WebSocket connection.
code_change/3	Handle code upgrades.
do/1	Main HTTP request handler, called by inets for each incoming request.
handle_call/3	Handle synchronous calls (e.g., adding routes).
handle_cast/2	Handle asynchronous messages.
handle_info/2	Handle non-OTP messages (e.g., TCP errors, HTTP server crashes).
init/1	Initialize the server.
match_pattern/3	Match path segments against route pattern.
method/1	Get the HTTP method of the request.
param/2	Get the value of a parameter (from path, query, or body).
parse_body/1	Parse request body based on HTTP method and content type.
parse_pattern/1	Parse route pattern (e.g., "/users/[id]/posts" -> [{literal, "users"}, {param, id}, {literal, "posts"}]).
parse_query/1	Parse query string into proplist.
query/2	Get the value of a query parameter from the request.
query/3	Get the value of a query parameter, with a default if missing.
reply/3	Reply to a request with status code and body.
reply/4	Reply to a request with status code, headers, and body.
request/4	Make an HTTP request to an external service.
route/4	Register a route for HTTP requests.
route/5	Register a route with required headers.
route_sse/3	Register an SSE (Server-Sent Events) route.
send_response/2	Placeholder for compatibility.
send_sse/2	Send a simple SSE event with data only.
send_sse/3	Send a named SSE event with data.
send_sse/4	Send a complete SSE event with type, data, and ID.
send_ws/2	Send WebSocket message.
start_link/1	Start the Wade server on the specified port.
start_link/2	Start the Wade server with custom options.
start_quic/2	Start Wade server with QUIC transport (HTTP/3).
start_quic/3	Start Wade server with both HTTP/1.1 and QUIC support Starts two servers on different ports.
stop/0	Stop the Wade server.
terminate/2	Clean up server resources.
upgrade_to_websocket/1	Upgrade HTTP connection to WebSocket.
url_decode/2
websocket_loop/2	WebSocket message loop.

Function Details

body/2

body(Req::#req{}, Key::atom() | string()) -> term() | undefined

Req: #req{} record.
Key: Atom or string: Parameter name.

returns: term() | undefined

Get the value of a body parameter from the request.

body/3

body(Req::#req{}, Key::atom() | string(), Default::term()) -> term()

Req: #req{} record.
Key: Atom or string: Parameter name.
Default: term(): Default value if parameter is missing.

returns: term()

Get the value of a body parameter, with a default if missing.

close_sse/1

close_sse(SSEConn) -> any()

close_ws/1

close_ws(Socket) -> any()

Close WebSocket connection.

code_change/3

code_change(OldVsn::term(), State::#state{}, Extra::term()) -> {ok, #state{}}

State: #state{}.

returns: {ok, #state{}}.

Handle code upgrades.

do/1

do(Mod::#mod{}) -> {proceed, term()}

returns: {proceed, term()}.

Main HTTP request handler, called by inets for each incoming request. Handles routing, parameter validation, and dispatching to handlers. Supports standard HTTP responses, WebSocket upgrades, and SSE connections.

handle_call/3

handle_call(X1::term(), From::pid(), State::#state{}) -> {reply, term(), #state{}}

returns: {reply, term(), #state{}}.

Handle synchronous calls (e.g., adding routes).

handle_cast/2

handle_cast(Msg::term(), State::#state{}) -> {noreply, #state{}}

Msg: term().

returns: {noreply, #state{}}.

Handle asynchronous messages.

handle_info/2

handle_info(Other::term(), State::#state{}) -> {noreply, #state{}} | {stop, term(), #state{}}

returns: {noreply, #state{}} | {stop, term(), #state{}}.

Handle non-OTP messages (e.g., TCP errors, HTTP server crashes).

init/1

init(X1::[term()]) -> {ok, #state{}} | {stop, term()}

returns: {ok, #state{}} | {stop, term()}.

Initialize the server.

match_pattern/3

match_pattern(PR::[{literal, string()} | {param, atom()}], PathR::[string()], Acc::[{atom(), string()}]) -> {ok, [{atom(), string()}]} | no_match

Acc: list({atom(), string()}).

returns: {ok, list({atom(), string()})} | no_match.

Match path segments against route pattern.

method/1

method(Req::#req{}) -> atom()

Req: #req{} record.

returns: atom(): get, post, put, delete, etc.

Get the HTTP method of the request.

param/2

param(Req::#req{}, Key::atom() | string()) -> term() | undefined

Req: #req{} record.
Key: Atom or string: Parameter name.

returns: term() | undefined

Get the value of a parameter (from path, query, or body).

parse_body/1

parse_body(Mod::#mod{}) -> [{atom(), string()}]

returns: list({atom(), string()}) | map() | [].

Parse request body based on HTTP method and content type. Supports: - application/x-www-form-urlencoded → parsed into proplist [{atom(), string()}] - application/json → parsed into map() - otherwise → []

parse_pattern/1

parse_pattern(Path::string()) -> [{literal, string()} | {param, atom()}]

Path: string().

returns: list({literal, string()} | {param, atom()}).

Parse route pattern (e.g., "/users/[id]/posts" -> [{literal, "users"}, {param, id}, {literal, "posts"}]).

parse_query/1

parse_query(Query::string()) -> [{atom(), string()}]

Query: string().

returns: list({atom(), string()}).

Parse query string into proplist.

query/2

query(Req::#req{}, Key::atom() | string()) -> term() | undefined

Req: #req{} record.
Key: Atom or string: Parameter name.

returns: term() | undefined

Get the value of a query parameter from the request.

query/3

query(Req::#req{}, Key::atom() | string(), Default::term()) -> term()

Req: #req{} record.
Key: Atom or string: Parameter name.
Default: term(): Default value if parameter is missing.

returns: term()

Get the value of a query parameter, with a default if missing.

reply/3

reply(Req::#req{}, StatusCode::integer(), Body::binary() | string()) -> #req{}

Req: #req{} record.
StatusCode: integer(): HTTP status code.
Body: binary() | string(): Response body.

returns: #req{} with reply fields set.

Reply to a request with status code and body.

reply/4

reply(Req::#req{}, StatusCode::integer(), Headers::map(), Body::binary() | string()) -> #req{}

Req: #req{} record.
StatusCode: integer(): HTTP status code.
Headers: map(): Additional response headers.
Body: binary() | string(): Response body.

returns: #req{} with reply fields set.

Reply to a request with status code, headers, and body.

request/4

request(Method::atom(), URL::string(), Headers::[{binary(), binary()}], Body::binary() | string()) -> {ok, integer(), [{binary(), binary()}], binary()} | {error, term()}

Method: atom(): HTTP method (get, post, put, etc.).
URL: string(): Target URL.
Headers: list({binary(), binary()}): Request headers.
Body: binary() | string(): Request body.

returns: {ok, StatusCode, Headers, Body} | {error, term()}.

Make an HTTP request to an external service.

route/4

route(Method::atom(), Path::string(), Handler::fun((#req{}) -> term()), RequiredParams::[atom()]) -> ok

Method: Atom: get, post, put, delete, patch, head, options, or any.
Path: String: URL path pattern (e.g., "/users/[id]").
Handler: Function: Fun(#req{}) -> #req{} | {StatusCode, Body} | {StatusCode, Headers, Body}.
RequiredParams: List of atoms: Required query/body parameters.

returns: ok

route/5

route(Method::atom(), Path::string(), Handler::fun((#req{}) -> term()), RequiredParams::[atom()], RequiredHeaders::[string()]) -> ok

Method: Atom: HTTP method.
Path: String: URL path pattern.
Handler: Function: Request handler.
RequiredParams: List of atoms: Required query/body parameters.
RequiredHeaders: List of strings: Required HTTP headers.

returns: ok

route_sse/3

route_sse(Path::string(), HandlerFun::fun((term()) -> ok), RequiredParams::[atom()]) -> ok

Path: String: URL path for the SSE endpoint.
HandlerFun: Function: fun(SSEConn) -> ok. Called when client connects.
RequiredParams: List of atoms: Required query parameters (rarely used for SSE).

returns: ok

Register an SSE (Server-Sent Events) route. Creates an endpoint that streams events to clients using the SSE protocol. The handler function receives an SSE connection and can send events asynchronously.

send_response/2

send_response(X1::term(), X2::term()) -> ok

Placeholder for compatibility.

send_sse/2

send_sse(Conn::term(), Data::binary() | string()) -> ok

Conn: SSE connection (from handler).
Data: The event data (binary or string).

returns: ok

Send a simple SSE event with data only.

send_sse/3

send_sse(Conn::term(), EventType::binary() | string(), Data::binary() | string()) -> ok

Conn: SSE connection (from handler).
EventType: The event type/name (binary or string).
Data: The event data (binary or string).

returns: ok

Send a named SSE event with data.

send_sse/4

Conn: SSE connection (from handler).
EventType: The event type/name (binary or string or undefined).
Data: The event data (binary or string).
EventId: The event ID (binary or string or undefined).

returns: ok

Send a complete SSE event with type, data, and ID.

send_ws/2

send_ws(Socket, X2) -> any()

Send WebSocket message.

start_link/1

start_link(Port::integer()) -> {ok, pid()} | {error, term()}

Port: The TCP port to listen on.

returns: {ok, pid()} | {error, term()}

Start the Wade server on the specified port.

start_link/2

start_link(Port::integer(), Options::map()) -> {ok, pid()} | {error, term()}

Port: The TCP port to listen on.
Options: Proplist of server options. Supported keys: - dispatch: List of {PathPattern, {Module, Args}} for dispatch-based routing.

returns: {ok, pid()} | {error, term()}

Start the Wade server with custom options.

start_quic/2

start_quic(Port::integer(), Options::map()) -> {ok, pid()} | {error, term()}

Port: The UDP port to listen on
Options: Map with QUIC-specific options: - certfile: Path to TLS certificate (required) - keyfile: Path to TLS private key (required) - alpn: List of ALPN protocols (default: ["h3"])

returns: {ok, pid()} | {error, term()}

Start Wade server with QUIC transport (HTTP/3)

start_quic/3

start_quic(HTTPPort::integer(), QUICPort::integer(), Options::map()) -> {ok, #{http => pid(), quic => pid()}} | {error, term()}

HTTPPort: TCP port for HTTP/1.1
QUICPort: UDP port for QUIC/HTTP3
Options: Options map (must include certfile/keyfile for QUIC)

returns: {ok, #{http => pid(), quic => pid()}} | {error, term()}

Start Wade server with both HTTP/1.1 and QUIC support Starts two servers on different ports

stop/0

stop() -> ok

returns: ok

Stop the Wade server.

terminate/2

terminate(Reason::term(), State::#state{}) -> ok

Reason: term().
State: #state{}.

returns: ok.

Clean up server resources.

Generated by EDoc