Documentation
¶
Overview ¶
Package client is the operator's HTTP client for the Hikyo delivery surface.
It decodes the delivery response into its OWN small struct rather than the server's generated types: the value slice (#63/#64 WP-A) is landing concurrently and the operator must not break on additive fields — so decoding is lenient (unknown members ignored) over the fields § 0.1 fixes. The transport mirrors internal/cli/client.go's discipline: HTTPS only, TLS ≥ 1.2, a credential is NEVER carried across a redirect.
Index ¶
- type Client
- func (c *Client) Capabilities(ctx context.Context) ([]string, error)
- func (c *Client) Fetch(ctx context.Context, r FetchRequest) (*DeliveryResponse, Outcome, error)
- func (c *Client) Report(ctx context.Context, org, project, environment, bearer string, ...) (int, error)
- func (c *Client) Tombstone(ctx context.Context, org, project, environment, bearer string, ...) (int, error)
- type DeliveredKey
- type DeliveryResponse
- type FetchRequest
- type Option
- type Outcome
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is bound to one HikyoInstance origin and its trust anchors. Instances are immutable, so a caller may cache one per instance UID.
func NewClient ¶
func NewClient(rawURL string, caBundlePEM []byte, userAgent string, options ...Option) (*Client, error)
NewClient builds a client for an instance. rawURL must be https (CEL enforces it on the CRD; this refuses http defensively at the mechanism boundary too). caBundlePEM is the instance's trust anchors, or nil for the host's system roots. userAgent is `hikyo-operator/<version>`.
Options only add policy. WithTLSProfile selects the key-exchange profile and never touches roots, server name or redirect handling.
func (*Client) Capabilities ¶
Capabilities reads the unauthenticated `/meta` protocol capabilities (k8s-condition-reporting ADR D10). Only that member is decoded; a response without it is an error, never an empty capability set.
func (*Client) Fetch ¶
func (c *Client) Fetch(ctx context.Context, r FetchRequest) (*DeliveryResponse, Outcome, error)
Fetch performs one conditional delivery fetch. It returns the decoded response only on OutcomeOK; the other outcomes carry a descriptive error for the CR condition and event, and a nil response.
func (*Client) Report ¶
func (c *Client) Report(ctx context.Context, org, project, environment, bearer string, body apigen.DeliveryTargetReportRequest) (int, error)
Report sends one delivery-target report (ADR D4) under the CR's own credential and returns the answered status. The caller classifies it.
type DeliveredKey ¶
type DeliveredKey struct {
Name string `json:"name"`
Classification string `json:"classification"`
Presence string `json:"presence"`
Value *string `json:"value,omitempty"`
}
DeliveredKey mirrors the § 0.1 wire shape. Value is a pointer so presence-only (no value member) is distinguishable from an empty value: the all-or-nothing refusal turns on exactly that distinction.
type DeliveryResponse ¶
type DeliveryResponse struct {
Current bool `json:"current"`
Cursor string `json:"cursor"`
ChangeToken string `json:"change_token"`
SchemaRevision int64 `json:"schema_revision"`
// Revision is absent on older servers that may ignore parameter inputs.
Revision *int64 `json:"revision,omitempty"`
PinnedRevision *int64 `json:"pinned_revision,omitempty"`
PinExpired bool `json:"pin_expired"`
CredentialExpiresAt *time.Time `json:"credential_expires_at,omitempty"`
Keys []DeliveredKey `json:"keys"`
}
DeliveryResponse is the operator's decode of the delivery response. Only the fields § 0.1 fixes are decoded; any additive member the server grows is ignored (no DisallowUnknownFields).
type FetchRequest ¶
type FetchRequest struct {
Org, Project, Environment string
Cursor string
Projection string
AcknowledgedKeys []string
Parameters map[string]string
// Bearer is presented as `Authorization: Bearer <token>`, only to the bound
// origin — the redirect guard keeps it off any other host.
Bearer string
}
FetchRequest is one conditional fetch. Cursor empty means a full authorized fetch. AcknowledgedKeys is sent comma-joined (§ 0.6) so the server records it.
type Option ¶
type Option func(*clientOptions)
Option adjusts how NewClient builds the transport.
func WithTLSProfile ¶
WithTLSProfile selects the key-exchange policy (#1127). Strict requires TLS 1.3 and the hybrid X25519MLKEM768 group and refuses a classical-only instance before the bearer is sent. It is handshake confidentiality only: certificate authentication is still the instance's CA bundle or system roots, classical.
type Outcome ¶
type Outcome int
Outcome classifies a fetch into the ADR's three answers plus the two non-delivering statuses (§ 0.4). The reconciler maps each to a Secret lifecycle; an unrecognized status is deliberately OutcomeFetchFailed (fail-safe: retain, never scrub on a status we do not understand).
const ( // OutcomeOK is a 200. The reconciler inspects Response.Current / Keys. OutcomeOK Outcome = iota // OutcomeFetchFailed is a transport error, 5xx, 429, or 401 — dead/expired/ // revoked credential, failed TokenRequest, unbound federation. Retain the // last-synced Secret, backoff. Never a staleness scrub. OutcomeFetchFailed // OutcomeScrub is a 404 under an authenticating principal — the scope is // nonexistent or the credential lost `read`. Converge the Secret to empty. OutcomeScrub // OutcomeNotMaterialized is a 409 — no published revision. Retain/empty. OutcomeNotMaterialized )