nupp.runtime.services.tls

Provider protocol for host.tls API 1.

Setup selects this service before requiring nupp.io.tls. The facade retains the provider and supplies its explicit receiver. The provider wraps an opaque network stream handle, so its transport representation must agree with the selected nupp.runtime.services.net implementation.

Wrapping creates TLS state; handshake and I/O then report pending work to the facade, which drives readiness. Verification is a policy input and an observable session result. Do not report a verified peer merely because a handshake completed with verification disabled. ALPN protocol text describes the negotiated result; resumed is an optional observation.

closeNotify sends the TLS shutdown notification and may need further progress. destroy releases session state; the owning public connection separately controls the underlying network stream. No method may resolve or switch providers.

Module contents

Types

TypeKindDescription
Providerinterface

Values

ValueKindDescription
servicevariableCanonical host.tls API 1 handle; setup selects before the public facade loads.

Types#

Providerinterface#

interface Provider
    readonly wrap: function(
        self: Provider,
        handle: any,
        server: boolean,
        hostname: string,
        certificate: string,
        privateKey: string,
        authority: string?,
        protocols: string,
        verify: boolean
    ): (any?, string?)
    readonly handshake: function(self: Provider, session: any): (boolean?, string?)
    readonly verified: function(self: Provider, session: any): boolean
    readonly resumed: (function(self: Provider, session: any): boolean)?
    readonly read: function(self: Provider, session: any, wanted: integer): (string?, string?)
    readonly write: function(self: Provider, session: any, bytes: string): (integer?, string?)
    readonly flushed: function(self: Provider, session: any): (boolean, string?)
    readonly closeNotify: function(self: Provider, session: any): (boolean, string?)
    readonly destroy: function(self: Provider, session: any): nil
    readonly connected: function(self: Provider, session: any): boolean
    readonly protocol: function(self: Provider, session: any): string?

end

Methods

wrap#
wrap: function(
    self: Provider,
    handle: any,
    server: boolean,
    hostname: string,
    certificate: string,
    privateKey: string,
    authority: string?,
    protocols: string,
    verify: boolean
): (any?, string?)

Creates session state over a compatible network handle. Certificate, private key, authority, hostname, and ALPN options follow the public TLS API. Returns the session or nil and an error.

Arguments
NameTypeDescription
selfProvider
handleany
serverboolean
hostnamestring
certificatestring
privateKeystring
authoritystring?
protocolsstring
verifyboolean
Returns
TypeDescription
any?
string?
handshake#
handshake: function(self: Provider, session: any): (boolean?, string?)

Returns true when ready, false while pending, or nil and an error.

Arguments
NameTypeDescription
selfProvider
sessionany
Returns
TypeDescription
boolean?
string?
verified#
verified: function(self: Provider, session: any): boolean

Reports whether peer verification succeeded for this session.

Arguments
NameTypeDescription
selfProvider
sessionany
Returns
TypeDescription
boolean
read#
read: function(self: Provider, session: any, wanted: integer): (string?, string?)

Returns bytes, nil while pending, an empty string at EOF, or nil and an error.

Arguments
NameTypeDescription
selfProvider
sessionany
wantedinteger
Returns
TypeDescription
string?
string?
write#
write: function(self: Provider, session: any, bytes: string): (integer?, string?)

Returns bytes accepted, nil while pending, or nil and an error.

Arguments
NameTypeDescription
selfProvider
sessionany
bytesstring
Returns
TypeDescription
integer?
string?
flushed#
flushed: function(self: Provider, session: any): (boolean, string?)

Returns true when encrypted output has drained, false while pending, or false with an error on failure.

Arguments
NameTypeDescription
selfProvider
sessionany
Returns
TypeDescription
boolean
string?
closeNotify#
closeNotify: function(self: Provider, session: any): (boolean, string?)

Starts or continues orderly TLS shutdown; true means complete, false means pending unless accompanied by an error.

Arguments
NameTypeDescription
selfProvider
sessionany
Returns
TypeDescription
boolean
string?
destroy#
destroy: function(self: Provider, session: any): nil

Releases TLS session state; the connection owner handles the transport.

Arguments
NameTypeDescription
selfProvider
sessionany
Returns
TypeDescription
nil
connected#
connected: function(self: Provider, session: any): boolean

Reports whether the session remains connected.

Arguments
NameTypeDescription
selfProvider
sessionany
Returns
TypeDescription
boolean
protocol#
protocol: function(self: Provider, session: any): string?

Returns the negotiated ALPN protocol, or nil when none is available.

Arguments
NameTypeDescription
selfProvider
sessionany
Returns
TypeDescription
string?

Fields

resumed#
resumed: (function(self: Provider, session: any): boolean)?

Optionally reports whether this session resumed prior TLS state.

Values#

servicevariable#

const service: services.Service<Provider>

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