# `nupp.runtime.services.http` High-level HTTP provider contract for `host.http` API 1. Import `service` for setup before requiring `nupp.io.http`. 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 flush. 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. ## Types ### `Body` _type_ ```nupp type Body = ResponseBody ``` ### `Client` _interface_ ```nupp affine interface Client is nupp.Closeable readonly flush: function(exclusive self: Client): nil readonly pending: function(self: Client): integer readonly send: function(self: Client, borrows request: Request): (Response?, string?) end ``` #### Methods ##### `flush` ```nupp flush: function(exclusive self: Client): nil ``` Services outstanding client work while holding exclusive client access. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Client` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `pending` ```nupp pending: function(self: Client): integer ``` Returns the number of outstanding requests or transfers. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Client` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `send` ```nupp send: function(self: Client, borrows request: Request): (Response?, string?) ``` 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?` | | | `string?` | | ### `Provider` _interface_ ```nupp interface Provider readonly client: function(options: Options?): Client readonly capabilities: function(): Capabilities end ``` #### Methods ##### `client` ```nupp client: function(options: Options?): Client ``` Constructs an owned client with the requested transport policy. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `options` | `Options?` | | ###### Returns | Type | Description | | --- | --- | | `Client` | | ##### `capabilities` ```nupp capabilities: function(): Capabilities ``` Reports the guarantees this implementation actually provides. ###### Returns | Type | Description | | --- | --- | | `Capabilities` | | ### `Response` _interface_ ```nupp affine interface Response is nupp.Closeable readonly status: integer readonly version: Version? readonly url: URI readonly body: Body readonly ok: function(self: Response): boolean readonly header: function(self: Response, name: string): string? readonly getAll: function(self: Response, name: string): {string} readonly headers: function(self: Response): {[string]: string} end ``` #### Methods ##### `ok` ```nupp ok: function(self: Response): boolean ``` Reports whether the status is in the successful 2xx range. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Response` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `header` ```nupp header: function(self: Response, name: string): string? ``` Returns one header value by case-insensitive name, or nil if absent. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Response` | | | `name` | `string` | | ###### Returns | Type | Description | | --- | --- | | `string?` | | ##### `getAll` ```nupp getAll: function(self: Response, name: string): {string} ``` Returns all values for a case-insensitive header name. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Response` | | | `name` | `string` | | ###### Returns | Type | Description | | --- | --- | | `{string}` | | ##### `headers` ```nupp headers: function(self: Response): {[string]: string} ``` Returns the response header mapping exposed by the host. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Response` | | ###### Returns | Type | Description | | --- | --- | | `{\[string\]: string}` | | #### Fields ##### `status` ```nupp status: integer ``` HTTP response status code. ##### `version` ```nupp version: Version? ``` Observed protocol version, absent when the host cannot expose it. ##### `url` ```nupp url: URI ``` Canonical final response URI, including completed redirects. ##### `body` ```nupp body: Body ``` Owned response reader whose lifetime is governed by the response. ## Values ### `service` _variable_ ```nupp const service: services.Service ``` Canonical host.http API 1 handle; setup selects before the public facade loads.