client

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MPL-2.0 Imports: 17 Imported by: 0

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

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

func (c *Client) Capabilities(ctx context.Context) ([]string, error)

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

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.

func (*Client) Tombstone

func (c *Client) Tombstone(ctx context.Context, org, project, environment, bearer string, body apigen.DeliveryTargetTombstoneRequest) (int, error)

Tombstone removes the caller's row for one deleted target (ADR D6).

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

func WithTLSProfile(profile tlspolicy.Profile) Option

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
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL