# `nupp.io.net.spi` Implementation interface for network transports. Importing this declaration opens no sockets. 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 ... ``` #### Members | Name | Kind | Description | | --- | --- | --- | | [`priority`](#nupp.io.net.spi.Provider.priority) | field | | | [`listen`](#nupp.io.net.spi.Provider.listen) | method | Creates a TCP listener; returns its handle or nil and an error. | | [`listenPath`](#nupp.io.net.spi.Provider.listenPath) | method | Creates a local-path listener with the requested backlog. | | [`listenerPort`](#nupp.io.net.spi.Provider.listenerPort) | method | Returns the bound port, or -1 when no IP port is available. | | [`accept`](#nupp.io.net.spi.Provider.accept) | method | Returns an accepted stream, nil while pending, or nil and an error. | | [`closeListener`](#nupp.io.net.spi.Provider.closeListener) | method | Releases a listener and its pending accept resources. | | [`connect`](#nupp.io.net.spi.Provider.connect) | method | Starts a TCP connection request with a millisecond timeout. | | [`connectPath`](#nupp.io.net.spi.Provider.connectPath) | method | Starts a local-path connection request with a millisecond timeout. | | [`connectPoll`](#nupp.io.net.spi.Provider.connectPoll) | method | Returns the completed stream, nil while pending, or nil and an error. | | [`closeConnect`](#nupp.io.net.spi.Provider.closeConnect) | method | Releases the connection request, independently of any resulting stream. | | [`read`](#nupp.io.net.spi.Provider.read) | method | Returns up to wanted bytes; an empty string means no bytes are ready. | | [`ended`](#nupp.io.net.spi.Provider.ended) | method | Reports that no further read bytes will arrive. | | [`write`](#nupp.io.net.spi.Provider.write) | method | Returns the accepted byte count, or nil and an error. | | [`pending`](#nupp.io.net.spi.Provider.pending) | method | Returns bytes accepted for writing that have not yet drained. | | [`writeFailed`](#nupp.io.net.spi.Provider.writeFailed) | method | Reports a terminal write failure, including one after enqueueing. | | [`shuttingDown`](#nupp.io.net.spi.Provider.shuttingDown) | method | Reports that the sending half is shutting down. | | [`shutdownWrite`](#nupp.io.net.spi.Provider.shutdownWrite) | method | Ends the sending half after queued writes; reports success or an error. | | [`address`](#nupp.io.net.spi.Provider.address) | method | Returns the canonical peer or local Address, or nil when unavailable. | | [`noDelay`](#nupp.io.net.spi.Provider.noDelay) | method | Sets TCP no-delay behavior on a stream. | | [`keepAlive`](#nupp.io.net.spi.Provider.keepAlive) | method | Configures TCP keepalive and its idle delay in milliseconds. | | [`broadcast`](#nupp.io.net.spi.Provider.broadcast) | method | Enables or disables sending broadcast datagrams. | | [`multicastTtl`](#nupp.io.net.spi.Provider.multicastTtl) | method | Sets the datagram multicast hop limit. | | [`multicastLoop`](#nupp.io.net.spi.Provider.multicastLoop) | method | Enables or disables local multicast loopback. | | [`membership`](#nupp.io.net.spi.Provider.membership) | method | Joins or leaves a multicast group on the named interface. | | [`closeStream`](#nupp.io.net.spi.Provider.closeStream) | method | Releases a stream and its queued native resources. | | [`bindDatagram`](#nupp.io.net.spi.Provider.bindDatagram) | method | Creates a bound datagram socket or returns nil and an error. | | [`datagramPort`](#nupp.io.net.spi.Provider.datagramPort) | method | Returns the bound datagram port, or -1 when unavailable. | | [`receive`](#nupp.io.net.spi.Provider.receive) | method | Returns bytes, source host, source port, truncation flag, and optional error. | | [`sendTo`](#nupp.io.net.spi.Provider.sendTo) | method | Sends one datagram to the destination or reports an error. | | [`closeDatagram`](#nupp.io.net.spi.Provider.closeDatagram) | method | Releases a datagram socket. | | [`run`](#nupp.io.net.spi.Provider.run) | method | Pumps shared reactor readiness for at most timeoutMs milliseconds. | #### `priority` _field_ ```nupp priority: integer? ``` `@readonly` #### `listen` _method_ ```nupp listen: function(self: Provider, host: string, port: integer, backlog: integer, reusePort: boolean): (any?, string?) ``` `@readonly` 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` _method_ ```nupp listenPath: function(self: Provider, path: string, backlog: integer): (any?, string?) ``` `@readonly` 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` _method_ ```nupp listenerPort: function(self: Provider, listener: any): integer ``` `@readonly` 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` _method_ ```nupp accept: function(self: Provider, listener: any): (any?, string?) ``` `@readonly` 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` _method_ ```nupp closeListener: function(self: Provider, listener: any): nil ``` `@readonly` Releases a listener and its pending accept resources. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `listener` | `any` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `connect` _method_ ```nupp connect: function(self: Provider, host: string, port: integer, timeoutMs: integer): (any?, string?) ``` `@readonly` 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` _method_ ```nupp connectPath: function(self: Provider, path: string, timeoutMs: integer): (any?, string?) ``` `@readonly` 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` _method_ ```nupp connectPoll: function(self: Provider, request: any): (any?, string?) ``` `@readonly` 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` _method_ ```nupp closeConnect: function(self: Provider, request: any): nil ``` `@readonly` Releases the connection request, independently of any resulting stream. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `request` | `any` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `read` _method_ ```nupp read: function(self: Provider, stream: any, wanted: integer): (string?, string?) ``` `@readonly` 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` _method_ ```nupp ended: function(self: Provider, stream: any): boolean ``` `@readonly` Reports that no further read bytes will arrive. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `write` _method_ ```nupp write: function(self: Provider, stream: any, bytes: string): (integer?, string?) ``` `@readonly` 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` _method_ ```nupp pending: function(self: Provider, stream: any): integer ``` `@readonly` Returns bytes accepted for writing that have not yet drained. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `writeFailed` _method_ ```nupp writeFailed: function(self: Provider, stream: any): boolean ``` `@readonly` Reports a terminal write failure, including one after enqueueing. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `shuttingDown` _method_ ```nupp shuttingDown: function(self: Provider, stream: any): boolean ``` `@readonly` Reports that the sending half is shutting down. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `shutdownWrite` _method_ ```nupp shutdownWrite: function(self: Provider, stream: any): (boolean, string?) ``` `@readonly` 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` _method_ ```nupp address: function(self: Provider, stream: any, peer: boolean): Address? ``` `@readonly` 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` _method_ ```nupp noDelay: function(self: Provider, stream: any, enable: boolean): (boolean, string?) ``` `@readonly` Sets TCP no-delay behavior on a stream. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | | `enable` | `boolean` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | #### `keepAlive` _method_ ```nupp keepAlive: function(self: Provider, stream: any, enable: boolean, delayMs: integer): (boolean, string?) ``` `@readonly` Configures TCP keepalive and its idle delay in milliseconds. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | | `enable` | `boolean` | | | `delayMs` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | #### `broadcast` _method_ ```nupp broadcast: function(self: Provider, socket: any, enable: boolean): (boolean, string?) ``` `@readonly` Enables or disables sending broadcast datagrams. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `enable` | `boolean` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | #### `multicastTtl` _method_ ```nupp multicastTtl: function(self: Provider, socket: any, ttl: integer): (boolean, string?) ``` `@readonly` Sets the datagram multicast hop limit. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `ttl` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | #### `multicastLoop` _method_ ```nupp multicastLoop: function(self: Provider, socket: any, enable: boolean): (boolean, string?) ``` `@readonly` Enables or disables local multicast loopback. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | | `enable` | `boolean` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | #### `membership` _method_ ```nupp membership: function( self: Provider, socket: any, group: string, interfaceAddress: string, join: boolean ): (boolean, string?) ``` `@readonly` 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` _method_ ```nupp closeStream: function(self: Provider, stream: any): nil ``` `@readonly` Releases a stream and its queued native resources. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `stream` | `any` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `bindDatagram` _method_ ```nupp bindDatagram: function(self: Provider, host: string, port: integer, reusePort: boolean): (any?, string?) ``` `@readonly` 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` _method_ ```nupp datagramPort: function(self: Provider, socket: any): integer ``` `@readonly` Returns the bound datagram port, or -1 when unavailable. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `receive` _method_ ```nupp receive: function(self: Provider, socket: any, maximum: integer): (string?, string?, integer?, boolean?, string?) ``` `@readonly` 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` _method_ ```nupp sendTo: function(self: Provider, socket: any, host: string, port: integer, bytes: string): (boolean, string?) ``` `@readonly` 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` _method_ ```nupp closeDatagram: function(self: Provider, socket: any): nil ``` `@readonly` Releases a datagram socket. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `socket` | `any` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `run` _method_ ```nupp run: function(self: Provider, timeoutMs: integer): nil ``` `@readonly` 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` | |