# `nupp.runtime.services.net` Provider protocol for `host.net` API 1. Setup imports `service` here without opening sockets, then selects an implementation before requiring `nupp.io.net`. The facade retains the provider table and supplies it as the explicit receiver for every operation. Provider handles are opaque; shared Address values come from `nupp.io.net.types`. Listener acceptance, connection completion, and stream I/O are readiness probes. They must not run a private blocking loop. `run(timeoutMs)` pumps the provider's reactor, and the public facade exposes pumping as `nupp.io.net.pump`. Keep handle ownership separate for listeners, connect requests, streams, and datagrams. Pending and EOF conventions differ by operation and are documented below. Report failures through the declared error result rather than disguising them as pending work. A TLS provider wrapping these streams must understand their handle representation; selection cannot make unrelated transport handles interoperable. ## Types ### `Provider` _interface_ ```nupp interface Provider readonly listen: function( self: Provider, host: string, port: integer, backlog: integer, reusePort: boolean ): (any?, string?) readonly listenPath: function(self: Provider, path: string, backlog: integer): (any?, string?) readonly listenerPort: function(self: Provider, listener: any): integer readonly accept: function(self: Provider, listener: any): (any?, string?) readonly closeListener: function(self: Provider, listener: any): nil readonly connect: function(self: Provider, host: string, port: integer, timeoutMs: integer): (any?, string?) readonly connectPath: function(self: Provider, path: string, timeoutMs: integer): (any?, string?) readonly connectPoll: function(self: Provider, request: any): (any?, string?) readonly closeConnect: function(self: Provider, request: any): nil readonly read: function(self: Provider, stream: any, wanted: integer): (string?, string?) readonly ended: function(self: Provider, stream: any): boolean readonly write: function(self: Provider, stream: any, bytes: string): (integer?, string?) readonly pending: function(self: Provider, stream: any): integer readonly writeFailed: function(self: Provider, stream: any): boolean readonly shuttingDown: function(self: Provider, stream: any): boolean readonly shutdownWrite: function(self: Provider, stream: any): (boolean, string?) readonly address: function(self: Provider, stream: any, peer: boolean): Address? readonly noDelay: function(self: Provider, stream: any, enable: boolean): (boolean, string?) readonly keepAlive: function( self: Provider, stream: any, enable: boolean, delaySeconds: integer ): (boolean, string?) readonly broadcast: function(self: Provider, socket: any, enable: boolean): (boolean, string?) readonly multicastTtl: function(self: Provider, socket: any, ttl: integer): (boolean, string?) readonly multicastLoop: function(self: Provider, socket: any, enable: boolean): (boolean, string?) readonly membership: function( self: Provider, socket: any, group: string, interfaceAddress: string, join: boolean ): (boolean, string?) readonly closeStream: function(self: Provider, stream: any): nil readonly bindDatagram: function(self: Provider, host: string, port: integer, reusePort: boolean): (any?, string?) readonly datagramPort: function(self: Provider, socket: any): integer readonly receive: function( self: Provider, socket: any, maximum: integer ): (string?, string?, integer?, boolean?, string?) readonly sendTo: function( self: Provider, socket: any, host: string, port: integer, bytes: string ): (boolean, string?) readonly closeDatagram: function(self: Provider, socket: any): nil readonly run: function(self: Provider, timeoutMs: integer): nil end ``` #### Methods ##### `listen` ```nupp listen: function( self: Provider, host: string, port: integer, backlog: integer, reusePort: boolean ): (any?, string?) ``` Creates a TCP listener; returns its handle or nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `host` | `string` | | | `port` | `integer` | | | `backlog` | `integer` | | | `reusePort` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | ##### `listenPath` ```nupp listenPath: function(self: Provider, path: string, backlog: integer): (any?, string?) ``` Creates a local-path listener with the requested backlog. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `path` | `string` | | | `backlog` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | ##### `listenerPort` ```nupp listenerPort: function(self: Provider, listener: any): integer ``` Returns the bound port, or -1 when no IP port is available. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `listener` | `any` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `accept` ```nupp accept: function(self: Provider, listener: any): (any?, string?) ``` Returns an accepted stream, nil while pending, or nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `listener` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | ##### `closeListener` ```nupp closeListener: function(self: Provider, listener: any): nil ``` Releases a listener and its pending accept resources. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `listener` | `any` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `connect` ```nupp connect: function(self: Provider, host: string, port: integer, timeoutMs: integer): (any?, string?) ``` Starts a TCP connection request with a millisecond timeout. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `host` | `string` | | | `port` | `integer` | | | `timeoutMs` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | ##### `connectPath` ```nupp connectPath: function(self: Provider, path: string, timeoutMs: integer): (any?, string?) ``` Starts a local-path connection request with a millisecond timeout. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `path` | `string` | | | `timeoutMs` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | ##### `connectPoll` ```nupp connectPoll: function(self: Provider, request: any): (any?, string?) ``` Returns the completed stream, nil while pending, or nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `request` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | ##### `closeConnect` ```nupp closeConnect: function(self: Provider, request: any): nil ``` Releases the connection request, independently of any resulting stream. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `request` | `any` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `read` ```nupp read: function(self: Provider, stream: any, wanted: integer): (string?, string?) ``` Returns up to wanted bytes; an empty string means no bytes are ready. Use ended to distinguish EOF. nil with an error reports a failed read. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | | `wanted` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `string?` | | | `string?` | | ##### `ended` ```nupp ended: function(self: Provider, stream: any): boolean ``` Reports that no further read bytes will arrive. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `write` ```nupp write: function(self: Provider, stream: any, bytes: string): (integer?, string?) ``` Returns the accepted byte count, or nil and an error. Accepted bytes may remain queued; pending reports their outstanding count. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `integer?` | | | `string?` | | ##### `pending` ```nupp pending: function(self: Provider, stream: any): integer ``` Returns bytes accepted for writing that have not yet drained. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `writeFailed` ```nupp writeFailed: function(self: Provider, stream: any): boolean ``` Reports a terminal write failure, including one after enqueueing. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `shuttingDown` ```nupp shuttingDown: function(self: Provider, stream: any): boolean ``` Reports that the sending half is shutting down. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `shutdownWrite` ```nupp shutdownWrite: function(self: Provider, stream: any): (boolean, string?) ``` Ends the sending half after queued writes; reports success or an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `address` ```nupp address: function(self: Provider, stream: any, peer: boolean): Address? ``` Returns the canonical peer or local Address, or nil when unavailable. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | | `peer` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `Address?` | | ##### `noDelay` ```nupp noDelay: function(self: Provider, stream: any, enable: boolean): (boolean, string?) ``` Sets TCP no-delay behavior on a stream. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | | `enable` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `keepAlive` ```nupp keepAlive: function( self: Provider, stream: any, enable: boolean, delaySeconds: integer ): (boolean, string?) ``` Configures TCP keepalive and its idle delay in seconds. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | | `enable` | `boolean` | | | `delaySeconds` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `broadcast` ```nupp broadcast: function(self: Provider, socket: any, enable: boolean): (boolean, string?) ``` Enables or disables sending broadcast datagrams. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `enable` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `multicastTtl` ```nupp multicastTtl: function(self: Provider, socket: any, ttl: integer): (boolean, string?) ``` Sets the datagram multicast hop limit. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `ttl` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `multicastLoop` ```nupp multicastLoop: function(self: Provider, socket: any, enable: boolean): (boolean, string?) ``` Enables or disables local multicast loopback. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `enable` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `membership` ```nupp membership: function( self: Provider, socket: any, group: string, interfaceAddress: string, join: boolean ): (boolean, string?) ``` Joins or leaves a multicast group on the named interface. An empty interface address selects the host default. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `group` | `string` | | | `interfaceAddress` | `string` | | | `join` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `closeStream` ```nupp closeStream: function(self: Provider, stream: any): nil ``` Releases a stream and its queued native resources. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `bindDatagram` ```nupp bindDatagram: function(self: Provider, host: string, port: integer, reusePort: boolean): (any?, string?) ``` Creates a bound datagram socket or returns nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `host` | `string` | | | `port` | `integer` | | | `reusePort` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | ##### `datagramPort` ```nupp datagramPort: function(self: Provider, socket: any): integer ``` Returns the bound datagram port, or -1 when unavailable. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `receive` ```nupp receive: function( self: Provider, socket: any, maximum: integer ): (string?, string?, integer?, boolean?, string?) ``` Returns bytes, source host, source port, truncation flag, and optional error. A nil first result without an error means no datagram is ready. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `maximum` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `string?` | | | `string?` | | | `integer?` | | | `boolean?` | | | `string?` | | ##### `sendTo` ```nupp sendTo: function( self: Provider, socket: any, host: string, port: integer, bytes: string ): (boolean, string?) ``` Sends one datagram to the destination or reports an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `host` | `string` | | | `port` | `integer` | | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `closeDatagram` ```nupp closeDatagram: function(self: Provider, socket: any): nil ``` Releases a datagram socket. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `run` ```nupp run: function(self: Provider, timeoutMs: integer): nil ``` Pumps shared reactor readiness for at most timeoutMs milliseconds. A zero timeout performs a nonblocking pass. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `timeoutMs` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ## Values ### `service` _variable_ ```nupp const service: services.Service ``` Canonical host.net API 1 handle; setup selects before the public facade loads.