<a id="nupp.io.http"></a>
# Module: `nupp.io.http`

An optional asynchronous HTTP client whose sockets and TLS run in the native
Reqwest/Tokio provider. Calls suspend through `nupp.suspension`: a CLI blocks on the
provider's condvar, while a scheduler or SDL host only drives the nonblocking source.

Response bodies and generic request readers are progressive and bounded. A response
status is an answer (including 4xx and 5xx); transport and body failures are returned
as reasons.

## Constructors

<a id="nupp.io.http.newClient"></a>
### `http.newClient` _constructor_

```nupp
function http.newClient(options: http.Options?): http.Client?, string?
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | `http.Options?` |  |

#### Returns

| Type | Description |
| --- | --- |
| `http.Client?` |  |
| `string?` |  |

## Types

<a id="nupp.io.http.Body"></a>
### `Body` _record_

```nupp
record http.Body is nupp.io.Reader
    _client: any
    _transfer: any
    _closed: boolean
    _reading: boolean

    function _next(self, count: integer, destination: nupp.io.Buffer?, offset: integer): (any?, string?)
    end

    function read(self, count: integer): (string?, string?)
    end

    function readInto(self, destination: nupp.io.Buffer, offset: integer?, count: integer?): (integer?, string?)
    end

    function transferTo(self, destination: nupp.io.Writer): (integer?, string?)
    end

    function close(self): (boolean, string?)
    end

    @drop
    function release(self): nil
    end
end
```

#### Methods

<a id="nupp.io.http.Body.read"></a>
##### `read`

```nupp
read: function read(self, count: integer): string?, string?
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `count` | `integer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `string?` |  |
| `string?` |  |

<a id="nupp.io.http.Body.readInto"></a>
##### `readInto`

```nupp
readInto: function readInto(self, destination: nupp.io.Buffer, offset: integer?, count: integer?): integer?, string?
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `destination` | `nupp.io.Buffer` |  |
| `offset` | `integer?` |  |
| `count` | `integer?` |  |

###### Returns

| Type | Description |
| --- | --- |
| `integer?` |  |
| `string?` |  |

<a id="nupp.io.http.Body.transferTo"></a>
##### `transferTo`

```nupp
transferTo: function transferTo(self, destination: nupp.io.Writer): integer?, string?
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `destination` | `nupp.io.Writer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `integer?` |  |
| `string?` |  |

<a id="nupp.io.http.Body.close"></a>
##### `close`

```nupp
close: function close(self): boolean, string?
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |

###### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |
| `string?` |  |

<a id="nupp.io.http.Body.release"></a>
##### `release`

```nupp
release: function release(self): nil
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |

###### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="nupp.io.http.Client"></a>
### `Client` _record_

```nupp
record http.Client
    _native: any
    _options: any
    _source: suspension.Source?
    _sourceUsers: integer
    _closed: boolean

    function _retainSource(self, context: suspension.Context): nil
    end

    function _releaseSource(self): nil
    end
end
```

#### Methods

<a id="nupp.io.http.Client.send"></a>
##### `send`

```nupp
send: function http.Client:send(request: http.Request): http.Response?, string?
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `request` | `http.Request` |  |

###### Returns

| Type | Description |
| --- | --- |
| `http.Response?` |  |
| `string?` |  |

<a id="nupp.io.http.Client.pending"></a>
##### `pending`

```nupp
pending: function http.Client:pending(): integer
```

###### Returns

| Type | Description |
| --- | --- |
| `integer` |  |

<a id="nupp.io.http.Client.close"></a>
##### `close`

```nupp
close: function http.Client:close(): boolean, string?
```

###### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |
| `string?` |  |

<a id="nupp.io.http.FileBody"></a>
### `FileBody` _record_

```nupp
record http.FileBody
    path: string | nupp.io.Path
    contentType: string?
end
```

#### Fields

| Name | Type | Description |
| --- | --- | --- |
| `path` | `string | nupp.io.Path` |  |
| `contentType` | `string?` |  |

<a id="nupp.io.http.Options"></a>
### `Options` _record_

```nupp
record http.Options
    userAgent: string?
    headers: {
        string: string
    }?
    timeoutMs: integer?
    connectTimeoutMs: integer?
    stallTimeoutMs: integer?
    maxRedirects: integer?
    maxPendingRequests: integer?
    maxConnections: integer?
    maxConnectionsPerHost: integer?
    maxBytes: integer?
    compressed: boolean?
    insecureHosts: {string}?
    proxy: string?
    noProxy: string?
    proxyCredentials: string?
end
```

#### Fields

| Name | Type | Description |
| --- | --- | --- |
| `userAgent` | `string?` |  |
| `headers` | `{string: string}?` |  |
| `timeoutMs` | `integer?` |  |
| `connectTimeoutMs` | `integer?` |  |
| `stallTimeoutMs` | `integer?` |  |
| `maxRedirects` | `integer?` |  |
| `maxPendingRequests` | `integer?` |  |
| `maxConnections` | `integer?` |  |
| `maxConnectionsPerHost` | `integer?` |  |
| `maxBytes` | `integer?` |  |
| `compressed` | `boolean?` |  |
| `insecureHosts` | `{string}?` |  |
| `proxy` | `string?` |  |
| `noProxy` | `string?` |  |
| `proxyCredentials` | `string?` |  |

<a id="nupp.io.http.ReaderBody"></a>
### `ReaderBody` _record_

```nupp
record http.ReaderBody
    reader: nupp.io.Reader
    length: integer?
    contentType: string?
end
```

#### Fields

| Name | Type | Description |
| --- | --- | --- |
| `reader` | `nupp.io.Reader` |  |
| `length` | `integer?` |  |
| `contentType` | `string?` |  |

<a id="nupp.io.http.Request"></a>
### `Request` _record_

```nupp
record http.Request
    url: nupp.io.URI
    method: string?
    headers: {
        string: string
    }?
    body: http.RequestBody?
    timeoutMs: integer?
    stallTimeoutMs: integer?
    maxBytes: integer?
end
```

#### Fields

| Name | Type | Description |
| --- | --- | --- |
| `url` | `nupp.io.URI` |  |
| `method` | `string?` |  |
| `headers` | `{string: string}?` |  |
| `body` | `http.RequestBody?` |  |
| `timeoutMs` | `integer?` |  |
| `stallTimeoutMs` | `integer?` |  |
| `maxBytes` | `integer?` |  |

<a id="nupp.io.http.RequestBody"></a>
### `RequestBody` _type_

```nupp
type http.RequestBody = string | nupp.io.ByteView | nupp.io.Buffer | http.ReaderBody | http.FileBody
```

<a id="nupp.io.http.Response"></a>
### `Response` _record_

```nupp
record http.Response
    status: integer
    version: http.Version
    url: nupp.io.URI
    body: owned<http.Body>
    _packed: string
    _values: {[string]: {string}}?
    _headers: {
        string: string
    }?
    _closed: boolean

    function _decode(self): nil
    end

    function ok(self): boolean
    end

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

    function getAll(self, name: string): {string}
    end

    function headers(self): {
        string: string
    }
    end

    @drop
    function close(self): (boolean, string?)
    end
end
```

#### Methods

<a id="nupp.io.http.Response.ok"></a>
##### `ok`

```nupp
ok: function ok(self): boolean
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |

###### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="nupp.io.http.Response.header"></a>
##### `header`

```nupp
header: function header(self, name: string): string?
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `name` | `string` |  |

###### Returns

| Type | Description |
| --- | --- |
| `string?` |  |

<a id="nupp.io.http.Response.getAll"></a>
##### `getAll`

```nupp
getAll: function getAll(self, name: string): {string}
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `name` | `string` |  |

###### Returns

| Type | Description |
| --- | --- |
| `{string}` |  |

<a id="nupp.io.http.Response.headers"></a>
##### `headers`

```nupp
headers: function headers(self): {string: string}
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |

###### Returns

| Type | Description |
| --- | --- |
| `{string: string}` |  |

<a id="nupp.io.http.Response.close"></a>
##### `close`

```nupp
close: function close(self): boolean, string?
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |

###### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |
| `string?` |  |

#### Fields

| Name | Type | Description |
| --- | --- | --- |
| `status` | `integer` |  |
| `version` | `http.Version` |  |
| `url` | `nupp.io.URI` |  |
| `body` | `owned\<http.Body\>` |  |

<a id="nupp.io.http.Version"></a>
### `Version` _type_

```nupp
type http.Version = "1.0" | "1.1" | "2"
```

## Functions

<a id="nupp.io.http.file"></a>
### `http.file` _function_

```nupp
function http.file(path: string | nupp.io.Path, contentType: string?): http.FileBody
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `path` | `string | nupp.io.Path` |  |
| `contentType` | `string?` |  |

#### Returns

| Type | Description |
| --- | --- |
| `http.FileBody` |  |

<a id="nupp.io.http.reader"></a>
### `http.reader` _function_

```nupp
function http.reader(reader: nupp.io.Reader, length: integer?, contentType: string?): http.ReaderBody
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `reader` | `nupp.io.Reader` |  |
| `length` | `integer?` |  |
| `contentType` | `string?` |  |

#### Returns

| Type | Description |
| --- | --- |
| `http.ReaderBody` |  |