Skip to content

Latest commit

 

History

History
60 lines (53 loc) · 7.05 KB

tcp.md

File metadata and controls

60 lines (53 loc) · 7.05 KB

TCP cosocket

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

ngx.socket.tcp is adapted as a typed VM resource plus sixteen explicit hosts (methods plus convenience ngx.socket.connect and TLS credential constructors). The constructor returns a resource handle (ngx.socket.tcp). Async I/O futures hold only Tokio TCP/Unix stream halves, owned unread buffer, timeout, generation, and cancel identity — 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 fd). One pending read and one pending write may run concurrently; a second same-direction op is a structured host error. Send loops until the full payload is written. Receive modes are exact size, ()/"*l" line (CR ignored), and "*a" until peer close. receiveany returns at most max bytes. receiveuntil is exclusive of a bounded delimiter and preserves unread bytes, including overlap across fragments. Caps: DNS host 255 bytes, Unix path 107 bytes, send/receive/unread buffer 1048576 bytes, delimiter 256 bytes. Timeout is milliseconds (OpenResty); 0 disables the timer. A transport timeout on send/receive is a HostError ("{name} timeout"). The socket stays connected and reusable (generation and fd survive), but under current VM policy a HostError still aborts the current script/request (Error500). This is not OpenResty's nil, err continuation. Connect timeout is also a HostError and drops the in-progress handshake. DNS and connect use Tokio, not the nginx resolver. The raw fd is never exposed.

OpenResty API RustScript callable Status Phases Yield Limits Semantic differences Acceptance
ngx.socket.tcp ngx::socket::tcp() -> resource adapted PHASE_SOCKET_UDP sync VM resource table Typed handle, not userdata. Cosocket request-owned even though sync. tests/ngx_tcp_socket.rs, tests/socket_lifecycle.rs
tcpsock:connect ngx::socket::tcp::connect(sock, host, port) -> () adapted PHASE_SOCKET_UDP Waiting host ≤255; unix: path ≤107 with port 0; port 0–65535 Tokio DNS/connect; IPv4/IPv6/Unix. tests/ngx_tcp_socket.rs, tests/socket_lifecycle.rs
ngx.socket.connect ngx::socket::connect(host, port) -> resource adapted PHASE_SOCKET_UDP Waiting same as connect Creates the TCP resource then connects. tests/ngx_tcp_socket.rs
tcpsock:send ngx::socket::tcp::send(sock, data) -> () adapted PHASE_SOCKET_UDP Waiting 1048576-byte payload; string or bytes Partial-write loop until complete. Transport timeout is HostError; the socket stays connected, but HostError aborts the current script/request. src/socket/tcp.rs, tests/ngx_tcp_socket.rs
tcpsock:receive ngx::socket::tcp::receive(sock, mode) -> bytes adapted PHASE_SOCKET_UDP Waiting exact/()/*l/*a; max 1048576 Line ignores CR. *a succeeds on peer close. Transport timeout is HostError; the socket stays connected, but HostError aborts the current script/request. src/socket/tcp.rs, tests/ngx_tcp_socket.rs
tcpsock:receiveany ngx::socket::tcp::receiveany(sock, max) -> bytes adapted PHASE_SOCKET_UDP Waiting 1–1048576 Returns unread first; one kernel read otherwise. tests/ngx_tcp_socket.rs
tcpsock:receiveuntil ngx::socket::tcp::receiveuntil(sock, delimiter) -> bytes adapted PHASE_SOCKET_UDP Waiting delimiter 1–256 bytes Single-shot, exclusive delimiter, unread preserved. tests/ngx_tcp_socket.rs
tcpsock:close ngx::socket::tcp::close(sock) -> () adapted PHASE_SOCKET_UDP sync — Double close is HostError. Cosocket request-owned. tests/ngx_tcp_socket.rs
tcpsock:settimeout ngx::socket::tcp::settimeout(sock, ms) -> () adapted PHASE_SOCKET_UDP sync non-negative ms; 0 = no timer Applies to subsequent ops; default 60000. tests/ngx_tcp_socket.rs
tcpsock:setkeepalive ngx::socket::tcp::setkeepalive(sock, timeout, pool_size) -> () adapted PHASE_SOCKET_UDP sync timeout ms (()=60000, 0=never); pool_size ()=30, 1–256; max 32 keys / 256 conns / 1000 reuse Worker-local LRU pool keyed by endpoint+TLS identity. Detaches IO from the request so cancel/close cannot drop a pooled socket. Rejects pending ops, unread buffers, EOF, and dirty sockets. tests/ngx_tcp_keepalive.rs
tcpsock:getreusedtimes ngx::socket::tcp::getreusedtimes(sock) -> int adapted PHASE_SOCKET_UDP sync — 0 until checkout; closed is HostError. tests/ngx_tcp_keepalive.rs
tcpsock:sslhandshake ngx::socket::tcp::sslhandshake(sock, reused_session, server_name, ssl_verify, send_status_req) -> () adapted PHASE_SOCKET_UDP Waiting SNI ≤255; verify defaults true Tokio/rustls only. No NGINX SSL FFI. Session userdata is not returned; reused_session session handles are a structured unsupported error. ()/true keep automatic same-identity rustls resumption; false disables it. rustls always sends OCSP status_request; send_status_req=false is unsupported. TLS pool checkout happens only during handshake after endpoint+SNI+verify+trust+client identity match. tests/ngx_tcp_tls.rs
— ngx::socket::tcp::trustedstore(pem) -> resource adapted PHASE_SOCKET_UDP sync PEM ≤65536 Parses PEM into a VM-owned trusted-store resource. PEM is never logged. tests/ngx_tcp_tls.rs
tcpsock:settrustedstore ngx::socket::tcp::settrustedstore(sock, store) -> () adapted PHASE_SOCKET_UDP sync typed store resource Attaches a trusted-store resource. Default is system roots then webpki-roots. tests/ngx_tcp_tls.rs
— ngx::socket::tcp::clientcert(cert, pkey) -> resource adapted PHASE_SOCKET_UDP sync PEM ≤65536 each Parses cert+key into a VM-owned resource. Private key is parsed through zeroizing storage and retained only as rustls PrivateKeyDer. Cert/key mismatch fails at construction. tests/ngx_tcp_tls.rs
tcpsock:setclientcert ngx::socket::tcp::setclientcert(sock, cert) -> () adapted PHASE_SOCKET_UDP sync typed clientcert resource Attaches a client-cert resource. OpenResty two-PEM method is adapted to one typed resource. tests/ngx_tcp_tls.rs

TCP programs are request-owned (HostFamily::Cosocket). Lifecycle, timeout, cancel, shutdown, DNS, IPv4/IPv6/Unix, concurrent read+write / duplicate same-direction ops, and handle reuse are covered by tests/ngx_tcp_socket.rs and tests/socket_lifecycle.rs. Keepalive pool, worker isolation, and TLS verification are covered by tests/ngx_tcp_keepalive.rs and tests/ngx_tcp_tls.rs. NGINX acceptance is tests/nginx_integration.py.


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