@salang/sa 0.1.3 → 0.1.4

package/sa_std/net.sai

@@ -0,0 +1,239 @@
+// SA-facing contracts for the Zig-backed sa_std.net module.
+// TcpStream, TcpListener, UdpSocket, and NetAddr values are opaque u64 handles.
+@extern sa_std_last_error() -> i32
+@extern sa_std_net_error_code_from_status(status: i32) -> i32
+@extern sa_std_net_error_code_from_posix_errno(errno: i32) -> i32
+@extern sa_std_net_error_code_from_wsa_error(error: i32) -> i32
+@extern sa_std_net_error_code_name(code: i32, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_std_net_error_platform() -> i32
+@extern sa_std_net_error_code_from_native_error(error: i32) -> i32
+@extern sa_std_net_hostname(&out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_std_net_tcp_connect(&host: ptr, host_len: u64, port: u32, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_connect_timeout(&host: ptr, host_len: u64, port: u32, timeout_ns: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_connect_timeout_addr(addr: u64, timeout_ns: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_connect_timeout_all(&host: ptr, host_len: u64, port: u32, timeout_ns: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_listen(&host: ptr, host_len: u64, port: u32, &out_handle: ptr, &out_bound_port: ptr) -> i32
+@extern sa_std_net_tcp_accept(listener: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_accept_addr(listener: u64, &out_stream: ptr, &out_addr: ptr) -> i32
+@extern sa_std_net_tcp_listener_local_addr(listener: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_stream_read(stream: u64, &buf: ptr, cap: u64, &out_read: ptr) -> i32
+@extern sa_std_net_tcp_stream_peek(stream: u64, &buf: ptr, cap: u64, &out_read: ptr) -> i32
+@extern sa_std_net_tcp_stream_read_vectored(stream: u64, &iovs: ptr, iov_count: u64, &out_read: ptr) -> i32
+@extern sa_std_net_tcp_stream_write_vectored(stream: u64, &iovs: ptr, iov_count: u64, &out_written: ptr) -> i32
+@extern sa_std_net_tcp_stream_write(stream: u64, &buf: ptr, len: u64, &out_written: ptr) -> i32
+@extern sa_std_net_tcp_stream_set_read_timeout(stream: u64, timeout_ns: u64) -> i32
+@extern sa_std_net_tcp_stream_set_write_timeout(stream: u64, timeout_ns: u64) -> i32
+@extern sa_std_net_tcp_stream_set_nonblocking(stream: u64, enabled: i32) -> i32
+@extern sa_std_net_tcp_stream_set_linger(stream: u64, enabled: i32, timeout_ns: u64) -> i32
+@extern sa_std_net_tcp_stream_linger(stream: u64, &out_enabled: ptr, &out_timeout_ns: ptr) -> i32
+@extern sa_std_net_tcp_stream_set_nodelay(stream: u64, enabled: i32) -> i32
+@extern sa_std_net_tcp_stream_set_quickack(stream: u64, enabled: i32) -> i32
+@extern sa_std_net_tcp_stream_quickack(stream: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_tcp_stream_set_deferaccept(stream: u64, seconds: u32) -> i32
+@extern sa_std_net_tcp_stream_deferaccept(stream: u64, &out_seconds: ptr) -> i32
+@extern sa_std_net_tcp_stream_set_ttl(stream: u64, ttl: u32) -> i32
+@extern sa_std_net_tcp_stream_read_timeout(stream: u64, &out_timeout_ns: ptr) -> i32
+@extern sa_std_net_tcp_stream_write_timeout(stream: u64, &out_timeout_ns: ptr) -> i32
+@extern sa_std_net_tcp_stream_set_recv_buffer_size(stream: u64, size: u32) -> i32
+@extern sa_std_net_tcp_stream_recv_buffer_size(stream: u64, &out_size: ptr) -> i32
+@extern sa_std_net_tcp_stream_set_send_buffer_size(stream: u64, size: u32) -> i32
+@extern sa_std_net_tcp_stream_send_buffer_size(stream: u64, &out_size: ptr) -> i32
+@extern sa_std_net_tcp_stream_nodelay(stream: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_tcp_stream_ttl(stream: u64, &out_ttl: ptr) -> i32
+@extern sa_std_net_tcp_stream_take_error(stream: u64, &out_error: ptr) -> i32
+@extern sa_std_net_tcp_stream_peer_addr(stream: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_stream_local_addr(stream: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_to_socket_addr_first(&host: ptr, host_len: u64, port: u32, &out_handle: ptr) -> i32
+@extern sa_std_net_to_socket_addr_list(&host: ptr, host_len: u64, port: u32, &out_handle: ptr) -> i32
+@extern sa_std_net_addr_list_next(list: u64, &out_ok: ptr, &out_addr: ptr) -> i32
+@extern sa_std_net_addr_list_remaining(list: u64, &out_remaining: ptr) -> i32
+@extern sa_std_net_addr_list_reset(list: u64) -> i32
+@extern sa_std_net_addr_list_free(list: u64) -> i32
+@extern sa_std_net_tcp_listener_set_nonblocking(listener: u64, enabled: i32) -> i32
+@extern sa_std_net_tcp_listener_set_ttl(listener: u64, ttl: u32) -> i32
+@extern sa_std_net_tcp_listener_ttl(listener: u64, &out_ttl: ptr) -> i32
+@extern sa_std_net_tcp_listener_take_error(listener: u64, &out_error: ptr) -> i32
+@extern sa_std_net_tcp_listener_from_raw_fd(fd: i32, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_stream_from_raw_fd(fd: i32, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_stream_try_clone(stream: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_tcp_listener_try_clone(listener: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_udp_try_clone(socket: u64, &out_handle: ptr) -> i32
+
+// Unix domain sockets (stream). Handles reuse the tcp_stream/tcp_listener kinds,
+// so NET_TCP_STREAM_READ/WRITE/CLOSE and NET_TCP_LISTENER_CLOSE work on them.
+@extern sa_std_net_unix_listen(&path: ptr, path_len: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_accept(listener: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_accept_addr(listener: u64, &out_stream: ptr, &out_addr: ptr) -> i32
+@extern sa_std_net_unix_connect(&path: ptr, path_len: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_pair(&out_left: ptr, &out_right: ptr) -> i32
+@extern sa_std_net_unix_addr_from_abstract_name(&name: ptr, name_len: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_addr_from_pathname(&path: ptr, path_len: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_listen_addr(addr: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_connect_addr(addr: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_listener_local_addr(listener: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_listener_try_clone(listener: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_listener_from_raw_fd(fd: i32, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_stream_local_addr(stream: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_stream_try_clone(stream: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_stream_from_raw_fd(fd: i32, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_stream_peer_addr(stream: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_stream_set_passcred(stream: u64, enabled: i32) -> i32
+@extern sa_std_net_unix_stream_passcred(stream: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_unix_stream_set_mark(stream: u64, mark: u32) -> i32
+@extern sa_std_net_unix_stream_peer_cred(stream: u64, &out_pid: ptr, &out_uid: ptr, &out_gid: ptr) -> i32
+@extern sa_std_net_unix_datagram_unbound(&out_handle: ptr) -> i32
+@extern sa_std_net_unix_datagram_bind(&path: ptr, path_len: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_datagram_bind_addr(addr: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_datagram_pair(&out_left: ptr, &out_right: ptr) -> i32
+@extern sa_std_net_unix_datagram_connect(socket: u64, &path: ptr, path_len: u64) -> i32
+@extern sa_std_net_unix_datagram_connect_addr(socket: u64, addr: u64) -> i32
+@extern sa_std_net_unix_datagram_try_clone(socket: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_datagram_from_raw_fd(fd: i32, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_datagram_local_addr(socket: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_datagram_peer_addr(socket: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_unix_datagram_set_passcred(socket: u64, enabled: i32) -> i32
+@extern sa_std_net_unix_datagram_passcred(socket: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_unix_datagram_set_mark(socket: u64, mark: u32) -> i32
+@extern sa_std_net_unix_datagram_shutdown(socket: u64, how: u32) -> i32
+@extern sa_std_net_unix_datagram_send_to(socket: u64, &buf: ptr, len: u64, &path: ptr, path_len: u64, &out_written: ptr) -> i32
+@extern sa_std_net_unix_datagram_send_to_addr(socket: u64, &buf: ptr, len: u64, addr: u64, &out_written: ptr) -> i32
+@extern sa_std_net_unix_datagram_recv_from(socket: u64, &buf: ptr, cap: u64, &out_read: ptr, &out_addr: ptr) -> i32
+@extern sa_std_net_unix_datagram_peek_from(socket: u64, &buf: ptr, cap: u64, &out_read: ptr, &out_addr: ptr) -> i32
+
+// Additional stream/listener socket options.
+@extern sa_std_net_tcp_stream_set_keepalive(stream: u64, enabled: i32) -> i32
+@extern sa_std_net_tcp_stream_keepalive(stream: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_tcp_stream_set_keepalive_params(stream: u64, idle_secs: u32, intvl_secs: u32, cnt: u32) -> i32
+@extern sa_std_net_tcp_listener_set_reuseaddr(listener: u64, enabled: i32) -> i32
+@extern sa_std_net_tcp_listener_set_reuseport(listener: u64, enabled: i32) -> i32
+@extern sa_std_net_tcp_listener_set_only_v6(listener: u64, enabled: i32) -> i32
+@extern sa_std_net_tcp_listener_only_v6(listener: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_udp_set_only_v6(socket: u64, enabled: i32) -> i32
+@extern sa_std_net_udp_only_v6(socket: u64, &out_enabled: ptr) -> i32
+
+// TLS ClientHello fingerprint digests (JA3 = MD5 hex, JA4 segment = SHA256 first 12 hex chars).
+@extern sa_std_net_ja3_hash(&ja3: ptr, ja3_len: u64, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_std_net_ja4_hash12(&data: ptr, data_len: u64, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+
+// Shared WebSocket frame codec (downpushed from http_client/http_server/node/deno plugins).
+@extern sa_std_ws_accept_key(&key: ptr, key_len: u64, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_std_ws_frame_parse(&data: ptr, data_len: u64, &out_fin: ptr, &out_opcode: ptr, &out_masked: ptr, &out_payload_offset: ptr, &out_payload_len: ptr, &out_frame_len: ptr, &out_mask: ptr) -> i32
+@extern sa_std_ws_unmask(&payload: ptr, payload_len: u64, &mask: ptr) -> i32
+@extern sa_std_ws_frame_build(opcode: u32, fin: u32, &payload: ptr, payload_len: u64, &mask: ptr, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_std_ws_frame_build_unmasked(opcode: u32, fin: u32, &payload: ptr, payload_len: u64, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+
+// Shared URL parser (scheme://host[:port][/path]). Any out buffer may be omitted.
+@extern sa_std_url_parse(&url: ptr, url_len: u64, &scheme_out: ptr, scheme_cap: u64, &scheme_len: ptr, &host_out: ptr, host_cap: u64, &host_len: ptr, &path_out: ptr, path_cap: u64, &path_len: ptr, &out_port: ptr) -> i32
+
+@extern sa_std_net_udp_bind(&host: ptr, host_len: u64, port: u32, &out_handle: ptr) -> i32
+@extern sa_std_net_udp_from_raw_fd(fd: i32, &out_handle: ptr) -> i32
+@extern sa_std_net_udp_local_addr(socket: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_udp_peer_addr(socket: u64, &out_handle: ptr) -> i32
+@extern sa_std_net_udp_connect(socket: u64, &host: ptr, host_len: u64, port: u32) -> i32
+@extern sa_std_net_udp_connect_addr(socket: u64, addr: u64) -> i32
+@extern sa_std_net_udp_set_read_timeout(socket: u64, timeout_ns: u64) -> i32
+@extern sa_std_net_udp_set_write_timeout(socket: u64, timeout_ns: u64) -> i32
+@extern sa_std_net_udp_set_nonblocking(socket: u64, enabled: i32) -> i32
+@extern sa_std_net_udp_set_broadcast(socket: u64, enabled: i32) -> i32
+@extern sa_std_net_udp_set_ttl(socket: u64, ttl: u32) -> i32
+@extern sa_std_net_udp_set_multicast_loop_v4(socket: u64, enabled: i32) -> i32
+@extern sa_std_net_udp_set_multicast_ttl_v4(socket: u64, ttl: u32) -> i32
+@extern sa_std_net_udp_set_multicast_loop_v6(socket: u64, enabled: i32) -> i32
+@extern sa_std_net_udp_set_multicast_hops_v6(socket: u64, hops: u32) -> i32
+@extern sa_std_net_udp_read_timeout(socket: u64, &out_timeout_ns: ptr) -> i32
+@extern sa_std_net_udp_write_timeout(socket: u64, &out_timeout_ns: ptr) -> i32
+@extern sa_std_net_udp_set_recv_buffer_size(socket: u64, size: u32) -> i32
+@extern sa_std_net_udp_recv_buffer_size(socket: u64, &out_size: ptr) -> i32
+@extern sa_std_net_udp_set_send_buffer_size(socket: u64, size: u32) -> i32
+@extern sa_std_net_udp_send_buffer_size(socket: u64, &out_size: ptr) -> i32
+@extern sa_std_net_udp_broadcast(socket: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_udp_ttl(socket: u64, &out_ttl: ptr) -> i32
+@extern sa_std_net_udp_multicast_loop_v4(socket: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_udp_multicast_ttl_v4(socket: u64, &out_ttl: ptr) -> i32
+@extern sa_std_net_udp_multicast_loop_v6(socket: u64, &out_enabled: ptr) -> i32
+@extern sa_std_net_udp_multicast_hops_v6(socket: u64, &out_hops: ptr) -> i32
+@extern sa_std_net_udp_set_multicast_if_v4(socket: u64, &interface_addr: ptr) -> i32
+@extern sa_std_net_udp_multicast_if_v4(socket: u64, &out_interface_addr: ptr) -> i32
+@extern sa_std_net_udp_set_multicast_if_v6(socket: u64, interface_index: u32) -> i32
+@extern sa_std_net_udp_multicast_if_v6(socket: u64, &out_interface_index: ptr) -> i32
+@extern sa_std_net_udp_take_error(socket: u64, &out_error: ptr) -> i32
+@extern sa_std_net_udp_send(socket: u64, &buf: ptr, len: u64, &out_written: ptr) -> i32
+@extern sa_std_net_udp_recv(socket: u64, &buf: ptr, cap: u64, &out_read: ptr) -> i32
+@extern sa_std_net_udp_peek(socket: u64, &buf: ptr, cap: u64, &out_read: ptr) -> i32
+@extern sa_std_net_udp_send_to(socket: u64, &buf: ptr, len: u64, &host: ptr, host_len: u64, port: u32, &out_written: ptr) -> i32
+@extern sa_std_net_udp_recv_from(socket: u64, &buf: ptr, cap: u64, &out_read: ptr, &out_addr: ptr) -> i32
+@extern sa_std_net_udp_peek_from(socket: u64, &buf: ptr, cap: u64, &out_read: ptr, &out_addr: ptr) -> i32
+@extern sa_std_net_udp_send_vectored(socket: u64, &iovs: ptr, iov_count: u64, &out_written: ptr) -> i32
+@extern sa_std_net_udp_send_to_vectored(socket: u64, &iovs: ptr, iov_count: u64, &host: ptr, host_len: u64, port: u32, &out_written: ptr) -> i32
+@extern sa_std_net_udp_recv_from_vectored(socket: u64, &iovs: ptr, iov_count: u64, &out_read: ptr, &out_addr: ptr) -> i32
+@extern sa_std_net_udp_join_multicast_v4(socket: u64, &multi_host: ptr, multi_host_len: u64, &interface_host: ptr, interface_host_len: u64) -> i32
+@extern sa_std_net_udp_leave_multicast_v4(socket: u64, &multi_host: ptr, multi_host_len: u64, &interface_host: ptr, interface_host_len: u64) -> i32
+@extern sa_std_net_udp_join_multicast_v6(socket: u64, &multi_host: ptr, multi_host_len: u64, interface_index: u32) -> i32
+@extern sa_std_net_udp_leave_multicast_v6(socket: u64, &multi_host: ptr, multi_host_len: u64, interface_index: u32) -> i32
+
+@extern sa_net_tcp_connect(&host: ptr, host_len: u64, port: u32) -> u64!
+@extern sa_net_tcp_stream_read(stream: u64, &buf: ptr, cap: u64) -> u64!
+@extern sa_net_tcp_stream_peek(stream: u64, &buf: ptr, cap: u64) -> i32
+@extern sa_net_tcp_stream_set_read_timeout(stream: u64, timeout_ns: u64) -> i32
+@extern sa_net_tcp_stream_set_write_timeout(stream: u64, timeout_ns: u64) -> i32
+@extern sa_net_tcp_stream_set_nonblocking(stream: u64, enabled: i32) -> i32
+@extern sa_net_tcp_stream_set_nodelay(stream: u64, enabled: i32) -> i32
+@extern sa_net_tcp_stream_set_ttl(stream: u64, ttl: u32) -> i32
+@extern sa_net_tcp_stream_write(stream: u64, &buf: ptr, len: u64) -> i32
+@extern sa_net_tcp_stream_write_all(stream: u64, &buf: ptr, len: u64) -> i32!
+@extern sa_net_tcp_stream_read_exact(stream: u64, &buf: ptr, len: u64) -> i32!
+@extern sa_net_tcp_stream_flush(stream: u64) -> i32
+@extern sa_net_tcp_stream_peer_addr(stream: u64) -> i32
+@extern sa_net_tcp_stream_shutdown(stream: u64, how: u32) -> i32
+@extern sa_net_tcp_stream_close(stream: u64) -> i32!
+
+@extern sa_net_tcp_listener_bind(&host: ptr, host_len: u64, port: u16) -> u64!
+@extern sa_net_tcp_listener_accept(listener: u64) -> u64!
+@extern sa_net_tcp_listener_local_addr(listener: u64) -> u64!
+@extern sa_net_tcp_listener_close(listener: u64) -> i32!
+
+@extern sa_net_udp_bind(&host: ptr, host_len: u64, port: u16) -> i32
+@extern sa_net_udp_connect(socket: u64, &host: ptr, host_len: u64, port: u16) -> i32
+@extern sa_net_udp_local_addr(socket: u64) -> i32
+@extern sa_net_udp_set_read_timeout(socket: u64, timeout_ns: u64) -> i32
+@extern sa_net_udp_set_write_timeout(socket: u64, timeout_ns: u64) -> i32
+@extern sa_net_udp_set_nonblocking(socket: u64, enabled: i32) -> i32
+@extern sa_net_udp_set_broadcast(socket: u64, enabled: i32) -> i32
+@extern sa_net_udp_set_ttl(socket: u64, ttl: u32) -> i32
+@extern sa_net_udp_set_multicast_loop_v4(socket: u64, enabled: i32) -> i32
+@extern sa_net_udp_set_multicast_ttl_v4(socket: u64, ttl: u32) -> i32
+@extern sa_net_udp_send(socket: u64, &buf: ptr, len: u64) -> i32
+@extern sa_net_udp_recv(socket: u64, &buf: ptr, cap: u64) -> i32
+@extern sa_net_udp_peek(socket: u64, &buf: ptr, cap: u64) -> i32
+@extern sa_net_udp_send_to(socket: u64, &buf: ptr, len: u64, &host: ptr, host_len: u64, port: u16) -> i32
+@extern sa_net_udp_recv_from(socket: u64, &buf: ptr, cap: u64, &out_addr: ptr) -> i32
+@extern sa_net_udp_peek_from(socket: u64, &buf: ptr, cap: u64, &out_addr: ptr) -> i32
+@extern sa_net_udp_join_multicast_v4(socket: u64, &multi_host: ptr, multi_host_len: u64, &interface_host: ptr, interface_host_len: u64) -> i32
+@extern sa_net_udp_leave_multicast_v4(socket: u64, &multi_host: ptr, multi_host_len: u64, &interface_host: ptr, interface_host_len: u64) -> i32
+@extern sa_net_udp_join_multicast_v6(socket: u64, &multi_host: ptr, multi_host_len: u64, interface_index: u32) -> i32
+@extern sa_net_udp_leave_multicast_v6(socket: u64, &multi_host: ptr, multi_host_len: u64, interface_index: u32) -> i32
+@extern sa_net_udp_close(socket: u64) -> i32
+
+// Owned SaNetAddr values are returned by address query APIs and must be freed.
+@extern sa_net_addr_host(addr: u64) -> &ptr
+@extern sa_net_addr_host_len(addr: u64) -> u64
+@extern sa_net_addr_port(addr: u64) -> u32
+@extern sa_net_addr_family(addr: u64) -> u32
+@extern sa_net_addr_scope_id(addr: u64) -> u64
+@extern sa_std_net_addr_format(addr: u64, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_net_addr_free(addr: u64) -> i32!
+@extern sa_net_unix_addr_kind(addr: u64) -> u32
+@extern sa_net_unix_addr_is_unnamed(addr: u64) -> u8
+@extern sa_net_unix_addr_path_ptr(addr: u64) -> &ptr
+@extern sa_net_unix_addr_path_len(addr: u64) -> u64
+@extern sa_net_unix_addr_abstract_ptr(addr: u64) -> &ptr
+@extern sa_net_unix_addr_abstract_len(addr: u64) -> u64
+@extern sa_net_unix_addr_free(addr: u64) -> i32!
+@extern sa_net_ipv4_parse_ascii(&text: ptr, text_len: u64, &out_addr: ptr) -> i32
+@extern sa_net_socket_addr_v4_parse_ascii(&text: ptr, text_len: u64, &out_socket_addr: ptr) -> i32
+@extern sa_net_ipv6_parse_ascii(&text: ptr, text_len: u64, &out_addr: ptr) -> i32
+@extern sa_net_socket_addr_v6_parse_ascii(&text: ptr, text_len: u64, &out_socket_addr: ptr) -> i32
+@extern sa_net_ipv4_format_ascii(&addr: ptr, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_net_ipv6_format_ascii(&addr: ptr, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_net_socket_addr_v4_format_ascii(&addr: ptr, &out: ptr, out_cap: u64, &out_len: ptr) -> i32
+@extern sa_net_socket_addr_v6_format_ascii(&addr: ptr, &out: ptr, out_cap: u64, &out_len: ptr) -> i32

package/sa_std/net.sal

@@ -0,0 +1,159 @@
+#def SA_NET_OK = 0
+#def SA_NET_ERR_UNKNOWN = 1
+#def SA_NET_ERR_DNS = 2
+#def SA_NET_ERR_REFUSED = 3
+#def SA_NET_ERR_TIMEOUT = 4
+#def SA_NET_ERR_CLOSED = 5
+#def SA_NET_ERR_WOULD_BLOCK = 6
+#def SA_NET_ERR_INVALID_ADDR = 7
+#def SA_NET_ERR_ACCESS = 4
+#def SA_NET_ERR_UNSUPPORTED = 8
+#def SA_NET_ERROR_CODE_OK = 0
+#def SA_NET_ERROR_CODE_UNKNOWN = 1
+#def SA_NET_ERROR_CODE_DNS = 2
+#def SA_NET_ERROR_CODE_CONNECTION_REFUSED = 3
+#def SA_NET_ERROR_CODE_TIMED_OUT = 4
+#def SA_NET_ERROR_CODE_CONNECTION_CLOSED = 5
+#def SA_NET_ERROR_CODE_WOULD_BLOCK = 6
+#def SA_NET_ERROR_CODE_INVALID_ADDRESS = 7
+#def SA_NET_ERROR_CODE_ACCESS_DENIED = 8
+#def SA_NET_ERROR_CODE_UNSUPPORTED = 9
+#def SA_NET_ERROR_CODE_INVALID_ARGUMENT = 10
+#def SA_NET_ERROR_CODE_INVALID_HANDLE = 11
+#def SA_NET_ERROR_CODE_NOT_FOUND = 12
+#def SA_NET_ERROR_CODE_NO_MEMORY = 13
+#def SA_NET_ERROR_CODE_IO = 14
+#def SA_NET_ERROR_CODE_NETWORK_UNREACHABLE = 15
+#def SA_NET_ERROR_CODE_ADDR_IN_USE = 16
+#def SA_NET_ERROR_CODE_ADDR_NOT_AVAILABLE = 17
+#def SA_NET_ERROR_CODE_CONNECTION_RESET = 18
+#def SA_NET_ERROR_CODE_CONNECTION_ABORTED = 19
+#def SA_NET_ERROR_CODE_NOT_CONNECTED = 20
+#def SA_NET_ERROR_CODE_HOST_UNREACHABLE = 21
+#def SA_NET_ERROR_CODE_BROKEN_PIPE = 22
+#def SA_NET_ERROR_CODE_ALREADY_EXISTS = 23
+#def SA_NET_ERROR_CODE_INTERRUPTED = 24
+#def SA_NET_ERROR_CODE_UNEXPECTED_EOF = 25
+#def SA_NET_ERROR_CODE_INVALID_DATA = 26
+#def SA_NET_ERROR_CODE_NETWORK_DOWN = 27
+#def SA_NET_ERROR_CODE_WRITE_ZERO = 28
+
+#def SA_NET_ERROR_PLATFORM_NONE = 0
+#def SA_NET_ERROR_PLATFORM_POSIX = 1
+#def SA_NET_ERROR_PLATFORM_WINDOWS = 2
+
+#def SaNetError_SIZE = 16
+#def SaNetError_ALIGN = 4
+#def SaNetError_code = +0
+#def SaNetError_platform = +4
+#def SaNetError_raw = +8
+#def SaNetError_status = +12
+
+#def SA_NET_AF_UNSPEC = 0
+#def SA_NET_AF_IPV4 = 4
+#def SA_NET_AF_IPV6 = 6
+
+#def SA_NET_SHUTDOWN_READ = 0
+#def SA_NET_SHUTDOWN_WRITE = 1
+#def SA_NET_SHUTDOWN_BOTH = 2
+
+#def SA_NET_AF_INET = 2
+#def SA_NET_AF_INET6 = 10
+
+#def SA_NET_UNIX_ADDR_UNNAMED = 0
+#def SA_NET_UNIX_ADDR_PATHNAME = 1
+#def SA_NET_UNIX_ADDR_ABSTRACT = 2
+
+#def SA_NET_SOCKET_OPTION_ENABLE = 1
+#def SA_NET_SOCKET_OPTION_DISABLE = 0
+
+#def SA_NET_IOV_MAX = 1024
+#def SaNetIov_SIZE = 16
+#def SaNetIov_ALIGN = 8
+#def SaNetIov_base = +0
+#def SaNetIov_len = +8
+
+#def SaNetAddr_SIZE = 32
+#def SaNetAddr_family = +0
+#def SaNetAddr_port = +4
+#def SaNetAddr_host_ptr = +8
+#def SaNetAddr_host_len = +16
+#def SaNetAddr_scope_id = +24
+
+#def NetIpv4Addr_SIZE = 4
+#def NET_IPV4_BITS_VALUE = 32
+#def NetIpv4Addr_a = +0
+#def NetIpv4Addr_b = +1
+#def NetIpv4Addr_c = +2
+#def NetIpv4Addr_d = +3
+
+#def NetIpv6Addr_SIZE = 16
+#def NET_IPV6_BITS_VALUE = 128
+#def NET_IPV6_MULTICAST_SCOPE_INTERFACE_LOCAL = 1
+#def NET_IPV6_MULTICAST_SCOPE_LINK_LOCAL = 2
+#def NET_IPV6_MULTICAST_SCOPE_REALM_LOCAL = 3
+#def NET_IPV6_MULTICAST_SCOPE_ADMIN_LOCAL = 4
+#def NET_IPV6_MULTICAST_SCOPE_SITE_LOCAL = 5
+#def NET_IPV6_MULTICAST_SCOPE_ORGANIZATION_LOCAL = 8
+#def NET_IPV6_MULTICAST_SCOPE_GLOBAL = 14
+#def NET_IPV6_MULTICAST_SCOPE_RESERVED_ZERO = 0
+#def NET_IPV6_MULTICAST_SCOPE_UNASSIGNED6 = 6
+#def NET_IPV6_MULTICAST_SCOPE_UNASSIGNED7 = 7
+#def NET_IPV6_MULTICAST_SCOPE_UNASSIGNED9 = 9
+#def NET_IPV6_MULTICAST_SCOPE_UNASSIGNED_A = 10
+#def NET_IPV6_MULTICAST_SCOPE_UNASSIGNED_B = 11
+#def NET_IPV6_MULTICAST_SCOPE_UNASSIGNED_C = 12
+#def NET_IPV6_MULTICAST_SCOPE_UNASSIGNED_D = 13
+#def NET_IPV6_MULTICAST_SCOPE_RESERVED_F = 15
+#def NetIpv6Addr_s0 = +0
+#def NetIpv6Addr_s1 = +2
+#def NetIpv6Addr_s2 = +4
+#def NetIpv6Addr_s3 = +6
+#def NetIpv6Addr_s4 = +8
+#def NetIpv6Addr_s5 = +10
+#def NetIpv6Addr_s6 = +12
+#def NetIpv6Addr_s7 = +14
+
+#def NetIpAddr_SIZE = 24
+#def NetIpAddr_tag = +0
+#def NetIpAddr_payload = +8
+#def NET_IP_ADDR_V4 = 4
+#def NET_IP_ADDR_V6 = 6
+
+#def NetSocketAddrV4_SIZE = 8
+#def NetSocketAddrV4_ip = +0
+#def NetSocketAddrV4_port = +4
+
+#def NetSocketAddrV6_SIZE = 32
+#def NetSocketAddrV6_ip = +0
+#def NetSocketAddrV6_port = +16
+#def NetSocketAddrV6_flowinfo = +20
+#def NetSocketAddrV6_scope_id = +24
+
+#def NetSocketAddr_SIZE = 40
+#def NetSocketAddr_tag = +0
+#def NetSocketAddr_payload = +8
+
+#def NetTcpIncoming_SIZE = 8
+#def NetTcpIncoming_listener = +0
+
+#def AddrParseError_SIZE = 8
+#def AddrParseError_ALIGN = 8
+#def AddrParseError_kind = +0
+#def ADDR_PARSE_ERROR_IP = 0
+#def ADDR_PARSE_ERROR_IPV4 = 1
+#def ADDR_PARSE_ERROR_IPV6 = 2
+#def ADDR_PARSE_ERROR_SOCKET = 3
+#def ADDR_PARSE_ERROR_SOCKET_V4 = 4
+#def ADDR_PARSE_ERROR_SOCKET_V6 = 5
+#def SA_NET_STATUS_OK = 0
+#def SA_NET_STATUS_INVALID_ARGUMENT = 1
+#def SA_NET_STATUS_INVALID_HANDLE = 2
+#def SA_NET_STATUS_NOT_FOUND = 3
+#def SA_NET_STATUS_ACCESS = 4
+#def SA_NET_STATUS_NO_MEMORY = 5
+#def SA_NET_STATUS_IO = 6
+#def SA_NET_STATUS_NET = 7
+#def SA_NET_STATUS_UNSUPPORTED = 8
+#def SA_NET_STATUS_TRUNCATED = 9
+#def SA_NET_STATUS_UNKNOWN = 127

package/sa_std/netx.sa

@@ -0,0 +1,85 @@
+@import "netx.sal"
+@import "netx.sai"
+
+// Netx (io_uring 网络引擎) 的 SA 宏层。
+// 运行时 (src/runtime/sa_net_uring.zig) 拥有 socket/槽位池/解析/io_uring 编排；
+// 这些宏只是对 sa_netx_* C-ABI 的薄封装，全部返回 SA_NETX_* 状态码 (i32)。
+// 传缓冲区的参数遵循 net.sa 约定：调用方传缓冲区符号，宏内部取地址。
+
+// ---- 引擎生命周期 ----
+
+[MACRO] NETX_INIT %out_status, %slot_capacity, %reactor_count
+    %out_status = call @sa_netx_init(%slot_capacity, %reactor_count)
+[END_MACRO]
+
+[MACRO] NETX_LISTEN %out_status, %host, %host_len, %port
+    %out_status = call @sa_netx_listen(&%host, %host_len, %port)
+[END_MACRO]
+
+[MACRO] NETX_SHUTDOWN %out_status
+    %out_status = call @sa_netx_shutdown()
+[END_MACRO]
+
+// ---- 事件消费与出站 ----
+
+// %ticket 必须指向一块至少 Ticket_SIZE 字节的缓冲区 (stack_alloc Ticket_SIZE)。
+// 阻塞直到有票据；返回 SA_NETX_OK 时 %ticket 被填充，SA_NETX_ERR_NOT_FOUND 表示引擎已关停。
+[MACRO] NETX_RECV_TICKET %out_status, %reactor_id, %ticket
+    %out_status = call @sa_netx_recv_ticket(%reactor_id, &%ticket)
+[END_MACRO]
+
+[MACRO] NETX_PUSH_OUTBOUND %out_status, %reactor_id, %slot_id, %msg, %len
+    %out_status = call @sa_netx_push_outbound(%reactor_id, %slot_id, &%msg, %len)
+[END_MACRO]
+
+// %slot_ids 指向 %n 个连续 u32 槽位 id；同一条 %msg 扇出给全部槽位。
+[MACRO] NETX_BROADCAST %out_status, %reactor_id, %slot_ids, %n, %msg, %len
+    %out_status = call @sa_netx_broadcast(%reactor_id, &%slot_ids, %n, &%msg, %len)
+[END_MACRO]
+
+[MACRO] NETX_CLOSE_SLOT %out_status, %slot_id
+    %out_status = call @sa_netx_close_slot(%slot_id)
+[END_MACRO]
+
+// ---- Ticket 字段直读 ----
+// %ticket 是 NETX_RECV_TICKET 填充的缓冲区地址；以下宏按 netx.sal 偏移直读，无拷贝。
+
+[MACRO] NETX_TICKET_SLOT_ID %out_slot_id, %ticket
+    %out_slot_id = load %ticket+Ticket_slot_id as u32
+[END_MACRO]
+
+[MACRO] NETX_TICKET_OP_CODE %out_op, %ticket
+    %out_op = load %ticket+Ticket_op_code as u16
+[END_MACRO]
+
+[MACRO] NETX_TICKET_PROTO %out_proto, %ticket
+    %out_proto = load %ticket+Ticket_proto as u8
+[END_MACRO]
+
+[MACRO] NETX_TICKET_FLAGS %out_flags, %ticket
+    %out_flags = load %ticket+Ticket_flags as u8
+[END_MACRO]
+
+[MACRO] NETX_TICKET_PAYLOAD %out_ptr, %ticket
+    %out_ptr = load %ticket+Ticket_payload as ptr
+[END_MACRO]
+
+[MACRO] NETX_TICKET_PAYLOAD_LEN %out_len, %ticket
+    %out_len = load %ticket+Ticket_payload_len as u32
+[END_MACRO]
+
+// ---- 复合便利宏 ----
+
+// 一次性把 op_code / slot_id / proto 三个最常用字段读出。
+[MACRO] NETX_TICKET_HEADER %out_op, %out_slot_id, %out_proto, %ticket
+    %out_op = load %ticket+Ticket_op_code as u16
+    %out_slot_id = load %ticket+Ticket_slot_id as u32
+    %out_proto = load %ticket+Ticket_proto as u8
+[END_MACRO]
+
+// 判定票据是否为某个 TicketOp (见 netx.sal 的 NETX_OP_*)。
+[MACRO] NETX_TICKET_IS_OP %out_flag, %ticket, %op
+    __netx_ticket_op_%out_flag = load %ticket+Ticket_op_code as u16
+    %out_flag = eq __netx_ticket_op_%out_flag, %op
+    !__netx_ticket_op_%out_flag
+[END_MACRO]

package/sa_std/netx.sai

@@ -0,0 +1,11 @@
+// SA-facing contracts for the Zig-backed sa_netx runtime module.
+// The runtime owns sockets, slot pools, parsing, and io_uring orchestration.
+// Every entry returns a plain i32 status code (SA_NETX_OK / SA_NETX_ERR_*),
+// matching the `pub export fn ... i32` signatures in src/runtime/sa_net_uring.zig.
+@extern sa_netx_init(slot_capacity: u64, reactor_count: u32) -> i32
+@extern sa_netx_listen(&host: ptr, host_len: u64, port: u16) -> i32
+@extern sa_netx_recv_ticket(reactor_id: u32, &out_ticket: ptr) -> i32
+@extern sa_netx_push_outbound(reactor_id: u32, slot_id: u32, &msg: ptr, len: u32) -> i32
+@extern sa_netx_broadcast(reactor_id: u32, &slot_ids: ptr, n: u32, &msg: ptr, len: u32) -> i32
+@extern sa_netx_close_slot(slot_id: u32) -> i32
+@extern sa_netx_shutdown() -> i32

package/sa_std/netx.sal

@@ -0,0 +1,39 @@
+#def Ticket_SIZE = 24
+#def Ticket_slot_id      = +0
+#def Ticket_op_code      = +4
+#def Ticket_proto        = +6
+#def Ticket_flags        = +7
+#def Ticket_payload      = +8
+#def Ticket_payload_len  = +16
+#def Ticket_pad          = +20
+
+#def NetxProto_HTTP = 1
+#def NetxProto_WS   = 2
+#def NetxProto_RAW  = 3
+
+#def SA_NETX_OK = 0
+#def SA_NETX_ERR_INVALID_ARGUMENT = 1
+#def SA_NETX_ERR_INVALID_HANDLE = 2
+#def SA_NETX_ERR_NOT_FOUND = 3
+#def SA_NETX_ERR_ACCESS = 4
+#def SA_NETX_ERR_NO_MEMORY = 5
+#def SA_NETX_ERR_IO = 6
+#def SA_NETX_ERR_NET = 7
+#def SA_NETX_ERR_UNSUPPORTED = 8
+#def SA_NETX_ERR_TRUNCATED = 9
+
+#def NETX_OP_ACCEPT = 1
+#def NETX_OP_HTTP_REQUEST = 2
+#def NETX_OP_WEBSOCKET_UPGRADE = 3
+#def NETX_OP_WS_FRAME = 4
+#def NETX_OP_RAW_BYTES = 5
+#def NETX_OP_PEER_CLOSE = 6
+#def NETX_OP_SEND_DONE = 7
+#def NETX_OP_ERR = 8
+
+#def NETX_FLAG_TRUNCATED = 1
+#def NETX_FLAG_UPGRADE = 2
+#def NETX_FLAG_EOF = 4
+#def NETX_FLAG_MASKED = 8
+#def NETX_FLAG_ZC = 16
+#def NETX_FLAG_FIN_CONTINUATION = 32

package/sa_std/nonzero.sa

@@ -0,0 +1,3 @@
+// Public NonZero integer facade over num.sa.
+@import "num.sal"
+@import "num.sa"

package/sa_std/nonzero.sal

@@ -0,0 +1,2 @@
+// NonZero integer layout and constants.
+@import "num.sal"

package/sa_std/num/nonzero.sa

@@ -0,0 +1,3 @@
+// NonZero integer namespace facade.
+@import "../num.sal"
+@import "../num.sa"

package/sa_std/num/nonzero.sal

@@ -0,0 +1 @@
+@import "../num.sal"

package/sa_std/num/prelude.sa

@@ -0,0 +1,3 @@
+// Stable numeric namespace aggregation.
+@import "nonzero.sa"
+@import "../num.sa"

package/sa_std/num/prelude.sal

@@ -0,0 +1,3 @@
+// ABI/layout companion for numeric namespace aggregation.
+@import "nonzero.sal"
+@import "../num.sal"