Skip to content

Latest commit

 

History

History
40 lines (32 loc) · 3.48 KB

udp.md

File metadata and controls

40 lines (32 loc) · 3.48 KB

UDP cosocket

Documentation · Directives · API · Execution model · Security · Examples · Compatibility

ngx.socket.udp is adapted as a typed VM resource plus seven explicit hosts. The constructor returns a resource handle (ngx.socket.udp). Async I/O futures hold only a Tokio UdpSocket, owned buffer, timeout, and a generation captured at operation start — never a request, pool, VM, or raw pointer. Generation is checked before and after each await and on close. Request cleanup cancels the pending future and closes the resource (including the UDP fd). Default receive size is 8192 bytes; datagrams and requested sizes above 65535 bytes are rejected. Timeout is milliseconds (OpenResty); 0 disables the timer rather than substituting a year-long deadline. DNS for setpeername uses Tokio, not the nginx resolver, and host names longer than 255 bytes are rejected before lookup.

OpenResty API RustScript callable Status Phases Yield Limits Semantic differences Acceptance
ngx.socket.udp ngx::socket::udp() -> resource adapted PHASE_SOCKET_UDP sync VM resource table Typed handle, not userdata. Cosocket request-owned even though sync. tests/ngx_udp_socket.rs, tests/socket_lifecycle.rs
udpsock:bind ngx::socket::udp::bind(sock, host, port) -> () adapted PHASE_SOCKET_UDP Waiting host string/(); port 0–65535 ()/* bind any IPv4. tests/ngx_udp_socket.rs, tests/socket_lifecycle.rs
udpsock:setpeername ngx::socket::udp::setpeername(sock, host, port) -> () adapted PHASE_SOCKET_UDP Waiting host string ≤255 bytes; port 0–65535 Tokio DNS; auto-bind if needed. tests/ngx_udp_socket.rs, tests/socket_lifecycle.rs
udpsock:send ngx::socket::udp::send(sock, data) -> () adapted PHASE_SOCKET_UDP Waiting 65535-byte payload; string or bytes Requires setpeername. tests/ngx_udp_socket.rs, tests/socket_lifecycle.rs
udpsock:receive ngx::socket::udp::receive(sock, size) -> bytes adapted PHASE_SOCKET_UDP Waiting default 8192; max 65535; () size Oversized datagrams error instead of silent truncate. tests/ngx_udp_socket.rs, tests/socket_lifecycle.rs
udpsock:close ngx::socket::udp::close(sock) -> () adapted PHASE_SOCKET_UDP sync — Double close is HostError. Cosocket request-owned. tests/ngx_udp_socket.rs, tests/socket_lifecycle.rs
udpsock:settimeout ngx::socket::udp::settimeout(sock, ms) -> () adapted PHASE_SOCKET_UDP sync non-negative ms; 0 = no timer Applies to subsequent ops; default 60000. tests/ngx_udp_socket.rs, tests/socket_lifecycle.rs

PHASE_SOCKET_UDP (OpenResty v0.10.29 ngx.socket.udp contexts): rewrite, access, content, timer, ssl_certificate, ssl_session_fetch. Same as sleep.

UDP programs are request-owned (HostFamily::Cosocket), including the sync constructor, close, and settimeout. Timeout, cancel, shutdown, generation, DNS, IPv6, workers, and handle reuse after close are covered by tests/ngx_udp_socket.rs and tests/socket_lifecycle.rs. NGINX acceptance is tests/nginx_integration.py.


See also: API index · Phase sets · Cross-cutting adaptations · Hard caps