`nupp.io.http.spi`

Shared interfaces for HTTP implementations.

The HTTP module selects during initialization. Provider functions have no implicit receiver; Client and Response methods do. Request, Options, Version, and Capabilities come from nupp.io.http.messages, URI from nupp.io.uri, and Body is the canonical nupp.io Reader interface.

A Client owns its transport and outstanding work. A successful send returns an affine Response owning the response resources and body reader. Preserve borrowing of the Request during send and exclusive access during pump. Closing clients and responses must release resources on success, error, and cancellation paths. Implementers must not replace these affine contracts with unowned table aliases.

Capabilities describe actual behavior, including streaming, policy control, and protocol observability. Unsupported options must follow the public HTTP API's error behavior. The facade selects the implementation at require-time; clients and resource methods retain direct provider operations.

Module contents

Types

Type	Kind	Description
`Body`	interface	A forward-only byte source.
`Client`	interface
`Provider`	interface
`Response`	interface

Types#

`Body`interface#

interface Body is nupp.Closeable ...

A forward-only byte source.

An interface rather than the concrete things that satisfy it. A buffer's reader, an open file and an HTTP response body are all one of these, so code written against the contract works over any of them without knowing which it has.

Members

Name	Kind	Description
`read`	method	Reads up to count bytes.
`readSpan`	method	Reads directly into a checked writable span.
`readInto`	method	Reads into a buffer.
`transferTo`	method	Writes everything left to a writer.

`read`method#

read: function(exclusive self: Reader, count: integer): (string?, string?)

Reads up to count bytes.

An empty answer is the end.

Arguments

Name	Type	Description
`exclusive self`	`Body`	this reader
`count`	`integer`	the most bytes to read

Returns

Type	Description
`string?`	the bytes, or nil when the reader is closed
`string?`	why it could not read, when unsuccessful

Raises

Type	Condition
`string`	when count is not a positive integer

`readSpan`method#

readSpan: function(exclusive self: Reader, exclusive destination: span.Writable<uint8>): (integer?, string?)

Reads directly into a checked writable span. A zero answer is the end.

Arguments

Name	Type	Description
`exclusive self`	`Body`	this reader
`exclusive destination`	`span.Writable<uint8>`	the positive-sized range to fill

Returns

Type	Description
`integer?`	how many bytes were read, or nil when the reader is closed
`string?`	why it could not read, when unsuccessful

`readInto`method#

readInto: function(
    exclusive self: Reader,
    exclusive destination: Buffer,
    offset: integer?,
    count: integer?
): (integer?, string?)

Reads into a buffer.

A zero answer is the end.

Arguments

Name	Type	Description
`exclusive self`	`Body`	this reader
`exclusive destination`	`Buffer`	the buffer to write into
`offset`	`integer?`	where in the destination to start, or the beginning
`count`	`integer?`	the most bytes to read

Returns

Type	Description
`integer?`	how many bytes were read, or nil when the reader is closed
`string?`	why it could not read, when unsuccessful

`transferTo`method#

transferTo: function(exclusive self: Reader, exclusive destination: Writer): (integer?, string?)

Writes everything left to a writer.

Arguments

Name	Type	Description
`exclusive self`	`Body`	this reader
`exclusive destination`	`Writer`	the writer to fill

Returns

Type	Description
`integer?`	how many bytes moved, or nil on failure
`string?`	why it could not, when unsuccessful

`Client`interface#

interface Client is nupp.Closeable ...

Members

Name	Kind	Description
`pump`	method	Services outstanding client work, waiting up to the given milliseconds for some of it to move, while holding...
`pending`	method	Returns the number of outstanding requests or transfers.
`send`	method	Borrows the Request while sending and returns an owned Response or an error.

`pump`method#

pump: function(exclusive self: Client, timeoutMs: integer?): nil

@readonly

Services outstanding client work, waiting up to the given milliseconds for some of it to move, while holding exclusive client access.

Arguments

Name	Type	Description
`exclusive self`	`Client`
`timeoutMs`	`integer?`

Returns

Type	Description
`nil`

`pending`method#

pending: function(self: Client): integer

@readonly

Returns the number of outstanding requests or transfers.

Arguments

Name	Type	Description
`self`	`Client`

Returns

Type	Description
`integer`

`send`method#

send: function(self: Client, borrows request: Request): (Response?, Error?)

@readonly

Borrows the Request while sending and returns an owned Response or an error.

Arguments

Name	Type	Description
`self`	`Client`
`borrows request`	`Request`

Returns

Type	Description
`Response?`
`Error?`

`Provider`interface#

interface Provider ...

Members

Name	Kind	Description
`priority`	field
`newClient`	method	Constructs an owned client with the requested transport policy.
`capabilities`	method	Reports the guarantees this implementation actually provides.

`priority`field#

priority: integer?

@readonly

`newClient`method#

newClient: function(options: Options?): Client

@readonly

Constructs an owned client with the requested transport policy.

Arguments

Name	Type	Description
`options`	`Options?`

Returns

Type	Description
`Client`

`capabilities`method#

capabilities: function(): Capabilities

@readonly

Reports the guarantees this implementation actually provides.

Returns

Type	Description
`Capabilities`

`Response`interface#

interface Response is nupp.Closeable ...

Members

Name	Kind	Description
`status`	field	HTTP response status code.
`version`	field	Observed protocol version, absent when the host cannot expose it.
`url`	field	Canonical final response URI, including completed redirects.
`body`	field	Owned response reader whose lifetime is governed by the response.
`ok`	method	Reports whether the status is in the successful 2xx range.
`header`	method	Returns one header value by case-insensitive name, or nil if absent.
`headerValues`	method	Returns all values for a case-insensitive header name.
`headers`	method	Returns a fresh response header mapping keyed by lowercase name.

`status`field#

status: integer

@readonly

HTTP response status code.

`version`field#

version: Version?

@readonly

Observed protocol version, absent when the host cannot expose it.

`url`field#

url: URI

@readonly

Canonical final response URI, including completed redirects.

`body`field#

body: Body

@readonly

Owned response reader whose lifetime is governed by the response.

`ok`method#

ok: function(self: Response): boolean

@readonly

Reports whether the status is in the successful 2xx range.

Arguments

Name	Type	Description
`self`	`Response`

Returns

Type	Description
`boolean`

`header`method#

header: function(self: Response, name: string): string?

@readonly

Returns one header value by case-insensitive name, or nil if absent.

Arguments

Name	Type	Description
`self`	`Response`
`name`	`string`

Returns

Type	Description
`string?`

`headerValues`method#

headerValues: function(self: Response, name: string): {string}

@readonly

Returns all values for a case-insensitive header name.

Arguments

Name	Type	Description
`self`	`Response`
`name`	`string`

Returns

Type	Description
`{string}`

`headers`method#

headers: function(self: Response): {[string]: string}

@readonly

Returns a fresh response header mapping keyed by lowercase name. Repeated values are joined with , except set-cookie, whose first value is returned; use headerValues to preserve every value.

Arguments

Name	Type	Description
`self`	`Response`

Returns

Type	Description
`{[string]: string}`

nupp.io.http.spi

Module contents

Types

Types#

Bodyinterface#

Members

readmethod#

Arguments

Returns

Raises

readSpanmethod#

Arguments

Returns

readIntomethod#

Arguments

Returns

transferTomethod#

Arguments

Returns

Clientinterface#

Members

pumpmethod#

Arguments

Returns

pendingmethod#

Arguments

Returns

sendmethod#

Arguments

Returns

Providerinterface#

Members

priorityfield#

newClientmethod#

Arguments

Returns

capabilitiesmethod#

Returns

Responseinterface#

Members

statusfield#

versionfield#

urlfield#

bodyfield#

okmethod#

Arguments

Returns

headermethod#

Arguments

Returns

headerValuesmethod#

Arguments

Returns

headersmethod#

Arguments

Returns

`nupp.io.http.spi`

`Body`interface#

`read`method#

`readSpan`method#

`readInto`method#

`transferTo`method#

`Client`interface#

`pump`method#

`pending`method#

`send`method#

`Provider`interface#

`priority`field#

`newClient`method#

`capabilities`method#

`Response`interface#

`status`field#

`version`field#

`url`field#

`body`field#

`ok`method#

`header`method#

`headerValues`method#

`headers`method#