hellhound/exchange

Explicit HTTPS credential exchange, independent of discovery and custody.

new validates pure options. Start supervised(client) under your owning supervisor before calling perform; stop it through that supervisor. Each call sends at most one request. Applications own token reuse and retry authority, including a failure whose evidence is MaybeSent.

A caller decoder converts the provider’s JSON into TokenResponse. Decoder failures/exceptions are sanitized. Its purity, runtime and captured-resource lifetime belong to the application. No raw response is kept in errors. Transport policy applies before status classification: an oversized, incomplete or unsupported-encoding response fails as TransportFailure, including when its observed status is non-2xx.

Types

Authentication

</>

pub type Authentication {
  Bearer(assertion.Assertion)
  FormAssertion(name: String, assertion: assertion.Assertion)
}

Constructors

```
Bearer(assertion.Assertion)
```

FormAssertion(name: String, assertion: assertion.Assertion)

Body

</>

pub type Body {
  Empty
  Form(List(#(String, String)))
  Json(json.Json)
}

Constructors

```
Empty
```
```
Form(List(#(String, String)))
```
```
Json(json.Json)
```

Client

opaque </>

pub opaque type Client

ConfigError

</>

pub type ConfigError {
  InvalidTrust
  InvalidTimeout
  InvalidResponseLimit
  InvalidHeaderLimit
  InvalidHost
}

Constructors

```
InvalidTrust
```
```
InvalidTimeout
```
```
InvalidResponseLimit
```
```
InvalidHeaderLimit
```
```
InvalidHost
```

Error

</>

pub type Error {
  InvalidRequest
  TransportFailure(
    evidence: telemetry.Evidence,
    reason: telemetry.TransportReason,
  )
  ProviderRejected(status: Int)
  MalformedResponse
  InvalidToken
}

Constructors

```
InvalidRequest
```

TransportFailure(
  evidence: telemetry.Evidence,
  reason: telemetry.TransportReason,
)

```
ProviderRejected(status: Int)
```
```
MalformedResponse
```
```
InvalidToken
```

Options

</>

pub type Options {
  Options(
    trust: config.Trust,
    destinations: config.DestinationPolicy,
    allowed_hosts: option.Option(List(String)),
    timeout: duration.Duration,
    max_response_bytes: Int,
    max_header_bytes: Int,
    max_headers: Int,
  )
}

Constructors

Options(
  trust: config.Trust,
  destinations: config.DestinationPolicy,
  allowed_hosts: option.Option(List(String)),
  timeout: duration.Duration,
  max_response_bytes: Int,
  max_header_bytes: Int,
  max_headers: Int,
)

Request

opaque </>

pub opaque type Request

Token

opaque </>

pub opaque type Token

TokenResponse

</>

A decoder’s transient input to token admission. The raw string here belongs to the caller decoder; only the admitted opaque Token is returned by perform.

pub type TokenResponse {
  TokenResponse(
    token: String,
    expires_at: option.Option(timestamp.Timestamp),
  )
}

Constructors

TokenResponse(
  token: String,
  expires_at: option.Option(timestamp.Timestamp),
)

Values

expires_at

</>

pub fn expires_at(
  token: Token,
) -> option.Option(timestamp.Timestamp)

Absent or past expiry remains honest evidence; the application owns reuse.

new

</>

pub fn new(options: Options) -> Result(Client, ConfigError)

new_request

</>

pub fn new_request(
  endpoint: String,
  authentication: Authentication,
) -> Request

options

</>

pub fn options() -> Options

perform

</>

pub fn perform(
  client: Client,
  request: Request,
  decoder: decode.Decoder(TokenResponse),
) -> Result(Token, Error)

supervised

</>

pub fn supervised(
  client: Client,
) -> supervision.ChildSpecification(Nil)

The application owns the returned child’s supervisor and shutdown.

token_value

</>

pub fn token_value(token: Token) -> String

Deliberately expose the credential for an application-owned resource request.

with_body

</>

pub fn with_body(request: Request, body: Body) -> Request

with_correlation

</>

pub fn with_correlation(
  client: Client,
  correlation: correlation.Correlation,
) -> Client

with_header

</>

pub fn with_header(
  request: Request,
  name: String,
  value: String,
) -> Request

Adds one header. Credential/framing overrides and duplicates are refused by perform, rather than silently replacing existing configured headers.