Files

184 lines
6.4 KiB
Go

// Package hanzoai is the Hanzo API client for Go.
//
// Everything else at the module root is generated by scripts/generate.sh from
// hanzoai/cloud's openapi.yaml, at the ref .spec-lock names. This file is not:
// it is the hand-written seam that turns the generated transport into an
// authenticated client and hangs the six capabilities off it.
//
// client := hanzoai.New(hanzoai.Options{})
// left, err := client.Budget.Left(ctx)
//
// The six — Budget, Policy, Audit, Search, KB and Graph — are the surface a
// caller reaches for. They live in their own packages because the generated
// client already spells Answer, Page, Hit, Backend, Wrote, Allowance and Charge
// as projections of unrelated operations, and a hand-written type cannot share
// a package with a generated one of the same name.
//
// The whole generated surface is still here: Client embeds *APIClient, so
// client.AgentAPI and the other 2449 operations are reached off the same value
// under the same credential.
package hanzoai
import (
"net/http"
"os"
"github.com/hanzoai/go-sdk/v8/audit"
"github.com/hanzoai/go-sdk/v8/budget"
"github.com/hanzoai/go-sdk/v8/call"
"github.com/hanzoai/go-sdk/v8/graph"
"github.com/hanzoai/go-sdk/v8/kb"
"github.com/hanzoai/go-sdk/v8/policy"
"github.com/hanzoai/go-sdk/v8/search"
)
// DefaultBaseURL is the Hanzo gateway, and the only host a call goes to. Every
// route is <base>/v1/…: no /api/ segment, no second host, no v2. The one other
// host any client contacts is the IAM issuer, and only to mint.
const DefaultBaseURL = "https://api.hanzo.ai"
// The three arms of an answer, named here so a caller reads them off the
// package it already imports. call.Answer and call.Page carry a type parameter
// and are named where they are declared, because the generated client at this
// root already defines an Answer and a Page of its own.
type (
// Denied is a call that was authenticated and refused.
Denied = call.Denied
// Held is a call the platform stopped for a human decision.
Held = call.Held
// Fault is an answer with no decision in it.
Fault = call.Fault
// Cure is one way out of a refusal.
Cure = call.Cure
// Money is an amount in integer minor units.
Money = call.Money
)
// Options is how a client is built. Every one falls back to an environment
// variable, so hanzoai.New(hanzoai.Options{}) is the normal case.
type Options struct {
// ID is the IAM client id. HANZO_CLIENT_ID.
ID string
// Secret is the IAM client secret. HANZO_CLIENT_SECRET.
Secret string
// Base is the gateway. HANZO_BASE_URL, else DefaultBaseURL.
Base string
// Issuer is where IAM answers. HANZO_ISSUER_URL, else DefaultIssuerURL.
Issuer string
// Resource is the RFC 8707 audience the minted token names. HANZO_RESOURCE,
// else Base — a token scoped to what it may spend at and useless elsewhere.
Resource string
}
// Client is the Hanzo API: the whole generated surface, and the six
// capabilities.
type Client struct {
*APIClient
// Budget is what you may spend, what is left, and what it cost.
Budget *budget.Client
// Policy is whether a subject may act on an object.
Policy *policy.Client
// Audit is the org's own trail.
Audit *audit.Client
// Search is one ranked result set over everything the org has stored.
Search *search.Client
// KB is the corpus you write and the connectors that fill it.
KB *kb.Client
// Graph is assertions with provenance and time.
Graph *graph.Client
options Options
who *identity
}
// New returns a client authenticated as the IAM client o names.
//
// The client exchanges its client credentials for an access token and presents
// that. It does not take a token, an API key or a bearer: a credential handed
// to an SDK is a credential nobody rotates and one that says nothing about who
// is calling — which is the question every refusal in the estate exists to
// answer.
//
// Construction never fails on a missing credential; the first call does, and
// says which environment variable is unset. There is nothing to exchange
// without one, so nothing is sent.
func New(o Options) *Client {
o = filled(o)
who := &identity{
issuer: o.Issuer,
id: o.ID,
secret: o.Secret,
resource: o.Resource,
next: http.DefaultTransport,
}
return build(o, who, who)
}
// As scopes every call to one of the tenant's subjects.
//
// scoped := client.As("usr_7")
//
// The returned client mints a subject-bound token from IAM's act grant — the
// operator credential this client already holds names the subject — caches it
// to expiry, and mints again on a 401. No method then takes a user id: the
// credential is the scope, so a caller cannot pass the wrong one and there is
// nothing to forget.
//
// The operator credential leaves with the scope. Two credentials on one request
// are two answers to who is calling.
//
// subject is a subject id or the externalId the operator filed the member under.
func (c *Client) As(subject string) *Client {
return build(c.options, c.who, &grant{
subject: subject,
operator: c.who,
issuer: c.options.Issuer,
next: http.DefaultTransport,
})
}
// build assembles one client over one transport. The generated surface and the
// six capabilities share it, so the credential is presented in exactly one
// place and a scoped client is the same client with a different one.
func build(o Options, who *identity, transport http.RoundTripper) *Client {
shared := &http.Client{Transport: transport}
cfg := NewConfiguration()
cfg.Servers = ServerConfigurations{{URL: o.Base}}
cfg.HTTPClient = shared
endpoint := &call.Endpoint{Base: o.Base, HTTP: shared}
return &Client{
APIClient: NewAPIClient(cfg),
Budget: budget.New(endpoint),
Policy: policy.New(endpoint),
Audit: audit.New(endpoint),
Search: search.New(endpoint),
KB: kb.New(endpoint),
Graph: graph.New(endpoint),
options: o,
who: who,
}
}
// filled answers o with every empty option taken from the environment, and then
// from the default.
func filled(o Options) Options {
o.ID = first(o.ID, os.Getenv("HANZO_CLIENT_ID"))
o.Secret = first(o.Secret, os.Getenv("HANZO_CLIENT_SECRET"))
o.Base = first(o.Base, os.Getenv("HANZO_BASE_URL"), DefaultBaseURL)
o.Issuer = first(o.Issuer, os.Getenv("HANZO_ISSUER_URL"), DefaultIssuerURL)
o.Resource = first(o.Resource, os.Getenv("HANZO_RESOURCE"), o.Base)
return o
}
// first answers the first value that is not empty.
func first(values ...string) string {
for _, value := range values {
if value != "" {
return value
}
}
return ""
}