# `nupp.io.tls.spi` Implementation interface for TLS transports. The facade selects during initialization, 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.io.net.spi` 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 and the transport it owns. No method may resolve or switch providers. ## Types ### `Provider` _interface_ ```nupp interface Provider ... ``` #### Members | Name | Kind | Description | | --- | --- | --- | | [`priority`](#nupp.io.tls.spi.Provider.priority) | field | | | [`wrap`](#nupp.io.tls.spi.Provider.wrap) | method | Creates session state over a compatible network handle. | | [`handshake`](#nupp.io.tls.spi.Provider.handshake) | method | Returns true when ready, false while pending, or nil and an error. | | [`verified`](#nupp.io.tls.spi.Provider.verified) | method | Reports whether peer verification succeeded for this session. | | [`resumed`](#nupp.io.tls.spi.Provider.resumed) | field | Optionally reports whether this session resumed prior TLS state. | | [`read`](#nupp.io.tls.spi.Provider.read) | method | Returns at most wanted bytes, nil while pending, an empty string at EOF, or nil and an error. | | [`write`](#nupp.io.tls.spi.Provider.write) | method | Returns a positive byte count no greater than the input length, nil while pending, or nil and an error. | | [`flushed`](#nupp.io.tls.spi.Provider.flushed) | method | Returns true when encrypted output has drained, false while pending, or false with an error on failure. | | [`closeNotify`](#nupp.io.tls.spi.Provider.closeNotify) | method | Starts or continues orderly TLS shutdown; true means complete, or that the bounded time a drain may take is spent,... | | [`destroy`](#nupp.io.tls.spi.Provider.destroy) | method | Releases TLS session state and its owned transport. | | [`connected`](#nupp.io.tls.spi.Provider.connected) | method | Reports whether the session remains connected. | | [`protocol`](#nupp.io.tls.spi.Provider.protocol) | method | Returns the negotiated ALPN protocol, or nil when none is available. | #### `priority` _field_ ```nupp priority: integer? ``` `@readonly` #### `wrap` _method_ ```nupp wrap: function( self: Provider, handle: any, server: boolean, hostname: string, certificate: string, privateKey: string, authority: string?, protocols: string, verify: boolean ): (any?, string?) ``` `@readonly` Creates session state over a compatible network handle. The provider consumes the handle on success and failure. Certificate, private key, authority, hostname, and ALPN options follow the public TLS API. Returns the session or nil and an error. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `handle` | `any` | | | `server` | `boolean` | | | `hostname` | `string` | | | `certificate` | `string` | | | `privateKey` | `string` | | | `authority` | `string?` | | | `protocols` | `string` | | | `verify` | `boolean` | | ##### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | #### `handshake` _method_ ```nupp handshake: function(self: Provider, session: any): (boolean?, string?) ``` `@readonly` Returns true when ready, false while pending, or nil and an error. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ##### Returns | Type | Description | | --- | --- | | `boolean?` | | | `string?` | | #### `verified` _method_ ```nupp verified: function(self: Provider, session: any): boolean ``` `@readonly` Reports whether peer verification succeeded for this session. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `resumed` _field_ ```nupp resumed: (function(self: Provider, session: any): boolean)? ``` `@readonly` Optionally reports whether this session resumed prior TLS state. #### `read` _method_ ```nupp read: function(self: Provider, session: any, wanted: integer): (string?, string?) ``` `@readonly` Returns at most `wanted` bytes, nil while pending, an empty string at EOF, or nil and an error. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | | `wanted` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `string?` | | | `string?` | | #### `write` _method_ ```nupp write: function(self: Provider, session: any, bytes: string): (integer?, string?) ``` `@readonly` Returns a positive byte count no greater than the input length, nil while pending, or nil and an error. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `integer?` | | | `string?` | | #### `flushed` _method_ ```nupp flushed: function(self: Provider, session: any): (boolean, string?) ``` `@readonly` Returns true when encrypted output has drained, false while pending, or false with an error on failure. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | #### `closeNotify` _method_ ```nupp closeNotify: function(self: Provider, session: any): (boolean, string?) ``` `@readonly` Starts or continues orderly TLS shutdown; true means complete, or that the bounded time a drain may take is spent, and false means pending unless accompanied by an error. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | #### `destroy` _method_ ```nupp destroy: function(self: Provider, session: any): nil ``` `@readonly` Releases TLS session state and its owned transport. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `connected` _method_ ```nupp connected: function(self: Provider, session: any): boolean ``` `@readonly` Reports whether the session remains connected. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `protocol` _method_ ```nupp protocol: function(self: Provider, session: any): string? ``` `@readonly` Returns the negotiated ALPN protocol, or nil when none is available. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ##### Returns | Type | Description | | --- | --- | | `string?` | |