mirror of
https://github.com/hanzo-go/sdk.git
synced 2026-11-20 20:13:42 +00:00
184 lines
6.4 KiB
Go
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 ""
|
|
}
|