`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.

Module contents

Types

Type	Kind	Description
`Provider`	interface

Values

Value	Kind	Description
`service`	variable	Canonical host.net API 1 handle; setup selects before the public facade loads.

Types#

`Provider`interface#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

closeDatagram: function(self: Provider, socket: any): nil

Releases a datagram socket.

Arguments

Name	Type	Description
`self`	`Provider`
`socket`	`any`

Returns

Type	Description
`nil`

`run`#

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#

const service: services.Service<Provider>

Canonical host.net API 1 handle; setup selects before the public facade loads.

nupp.runtime.services.net

Module contents

Types

Values

Types#

Providerinterface#

Methods

listen#

Arguments

Returns

listenPath#

Arguments

Returns

listenerPort#

Arguments

Returns

accept#

Arguments

Returns

closeListener#

Arguments

Returns

connect#

Arguments

Returns

connectPath#

Arguments

Returns

connectPoll#

Arguments

Returns

closeConnect#

Arguments

Returns

read#

Arguments

Returns

ended#

Arguments

Returns

write#

Arguments

Returns

pending#

Arguments

Returns

writeFailed#

Arguments

Returns

shuttingDown#

Arguments

Returns

shutdownWrite#

Arguments

Returns

address#

Arguments

Returns

noDelay#

Arguments

Returns

keepAlive#

Arguments

Returns

broadcast#

Arguments

Returns

multicastTtl#

Arguments

Returns

multicastLoop#

Arguments

Returns

membership#

Arguments

Returns

closeStream#

Arguments

Returns

bindDatagram#

`nupp.runtime.services.net`

`Provider`interface#

`listen`#

`listenPath`#

`listenerPort`#

`accept`#

`closeListener`#

`connect`#

`connectPath`#

`connectPoll`#

`closeConnect`#

`read`#

`ended`#

`write`#

`pending`#

`writeFailed`#

`shuttingDown`#

`shutdownWrite`#

`address`#

`noDelay`#

`keepAlive`#

`broadcast`#

`multicastTtl`#

`multicastLoop`#

`membership`#

`closeStream`#

`bindDatagram`#

`datagramPort`#

`receive`#

`sendTo`#

`closeDatagram`#

`run`#

`service`variable#