client

package
v1.8.0 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MPL-2.0 Imports: 13 Imported by: 2

Documentation

Overview

Package client implements image factory HTTP API client.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsHTTPErrorCode added in v0.2.1

func IsHTTPErrorCode(err error, code int) bool

IsHTTPErrorCode checks if the error is HTTP error with a specific doe.

func IsInvalidSchematicError

func IsInvalidSchematicError(err error) bool

IsInvalidSchematicError checks if the error is invalid schematic.

func WithHeaders added in v1.3.3

func WithHeaders(headers map[string]string) requestOption

WithHeaders attaches request headers.

func WithQueryParams added in v1.3.3

func WithQueryParams(query url.Values) requestOption

WithQueryParams attaches URL query parameters.

func WithRequestData added in v1.3.3

func WithRequestData(data []byte) requestOption

WithRequestData attaches a request body.

Types

type Actor added in v1.7.0

type Actor string

Actor is a server-defined credential profile. The server expands it into executable and issuable scopes; clients cannot override either scope set when selecting an actor.

const (
	// ActorTalos can fetch generated images, PXE assets, and installer OCI artifacts.
	ActorTalos Actor = "talos"
	// ActorOnPrem can pull source images for mirroring into an on-premises installation.
	ActorOnPrem Actor = "onprem"
	// ActorAutomation can operate schematics and reports and issue bounded Talos or Automation credentials.
	ActorAutomation Actor = "automation"
	// ActorOperator can operate schematics and reports, fetch generated products, and pull source artifacts.
	ActorOperator Actor = "operator"
	// ActorAdmin can manage credentials and issue every actor profile.
	ActorAdmin Actor = "admin"
)

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the Image Factory HTTP API client.

func New

func New(baseURL string, options ...Option) (*Client, error)

New creates a new Image Factory API client.

func (*Client) BaseURL added in v0.5.0

func (c *Client) BaseURL() string

BaseURL returns the base URL of the client.

func (*Client) BrokenVersions added in v1.3.3

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

BrokenVersions gets the list of Talos versions marked as broken by the factory.

func (*Client) DownloadToken added in v1.5.0

func (c *Client) DownloadToken(ctx context.Context, ttl time.Duration) (string, error)

DownloadToken requests a short-lived JWT token carrying image:read, scoped to the authenticated caller's identity. The token can be appended as ?token= to any image download URL, and to a PXE script URL, which forwards it into the asset URLs of the script; one token covers all schematics owned by the caller.

A positive ttl requests that lifetime, which the server accepts only within its configured bounds; zero or less takes the server default.

The token is not stored, so expiry is its only revocation mechanism and its lifetime is bounded by the server's authentication.tokens.ttl.ephemeral policy. Storage is independent of URL use; both stored and ephemeral tokens may travel in a URL when their scopes are URL-safe.

func (*Client) ExtensionsVersions

func (c *Client) ExtensionsVersions(ctx context.Context, talosVersion string) ([]ExtensionInfo, error)

ExtensionsVersions gets the version of the extension for a Talos version.

func (*Client) OverlaysVersions added in v0.3.0

func (c *Client) OverlaysVersions(ctx context.Context, talosVersion string) ([]OverlayInfo, error)

OverlaysVersions gets the version of the extension for a Talos version.

func (*Client) SPDXBundle added in v1.5.1

func (c *Client) SPDXBundle(ctx context.Context, schematicID, talosVersion, arch string) ([]byte, error)

SPDXBundle downloads the SPDX SBOM bundle for the given schematic, Talos version, and architecture, as "application/spdx+json".

func (*Client) ScanReport added in v1.3.3

func (c *Client) ScanReport(ctx context.Context, schematicID, talosVersion, arch, filename string) ([]byte, error)

ScanReport downloads a vulnerability scan report for the given schematic, Talos version, architecture, and report filename. The filename extension selects the report format: ".sarif" → SARIF, ".cdx" → CycloneDX, ".json" → JSON, ".table" → plain-text table.

func (*Client) SchematicCreate

func (c *Client) SchematicCreate(ctx context.Context, sc schematic.Schematic) (string, *schematic.Schematic, error)

SchematicCreate generates new schematic from the configuration.

It returns the schematic ID and the normalized schematic as returned by the factory. The normalized schematic should be considered authoritative as it may differ from the input (for example, the factory may set the owner field for authenticated requests).

func (*Client) SchematicGet added in v0.9.0

func (c *Client) SchematicGet(ctx context.Context, schematicID string) (*schematic.Schematic, error)

func (*Client) TalosctlList added in v1.2.0

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

TalosctlList gets the list of talosctl download URLs for a Talos version.

func (*Client) TokenCreate added in v1.7.0

func (c *Client) TokenCreate(ctx context.Context, opts TokenCreateOptions) (id, token string, err error)

TokenCreate mints a credential, returning its ID and the credential itself. The credential is only returned at creation time and cannot be retrieved afterward.

A stored credential is recorded by the factory, so it can be listed and revoked, requires a name, and counts against the per-org cap. A non-stored credential is retired only by expiry. Actor cannot be combined with Scopes or IssuableScopes; the server expands actor profiles.

func (*Client) TokenList added in v1.7.0

func (c *Client) TokenList(ctx context.Context) ([]TokenInfo, error)

TokenList returns the caller's currently active stored tokens.

func (*Client) TokenRevoke added in v1.7.0

func (c *Client) TokenRevoke(ctx context.Context, id string) error

TokenRevoke revokes the token with the given ID.

func (*Client) VEXDocument added in v1.5.1

func (c *Client) VEXDocument(ctx context.Context, talosVersion string) ([]byte, error)

VEXDocument downloads the VEX document for the given Talos version, as "application/json". VEX data is version-scoped, not schematic-scoped.

func (*Client) Versions

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

Versions gets the list of Talos versions available.

type ExtensionInfo

type ExtensionInfo struct {
	Name        string `json:"name"`
	Ref         string `json:"ref"`
	Digest      string `json:"digest"`
	Author      string `json:"author"`
	Description string `json:"description"`
}

ExtensionInfo defines extensions versions list response item.

type HTTPError added in v0.2.1

type HTTPError struct {
	Message string
	Code    int
}

HTTPError is a generic HTTP error wrapper.

func (*HTTPError) Error added in v0.2.1

func (e *HTTPError) Error() string

Error implements error interface.

type InvalidSchematicError

type InvalidSchematicError struct {
	// contains filtered or unexported fields
}

InvalidSchematicError is parsed from 400 response from the server.

func (*InvalidSchematicError) Error

func (e *InvalidSchematicError) Error() string

Error implements error interface.

type Option

type Option func(*Options)

Option defines a single client option setter.

func WithBasicAuth added in v1.2.0

func WithBasicAuth(username, password string) Option

WithBasicAuth adds basic authentication to each request. It can carry htpasswd credentials or a self-issued API token in the password position for Basic-only clients. For an API token, the signed subject determines the principal; the Basic username does not grant authority.

func WithBearerToken added in v1.5.1

func WithBearerToken(token string) Option

WithBearerToken adds a static bearer token to each request. It may be a configured-provider bearer credential or a self-issued Image Factory API token; the server applies the corresponding identity and scope checks.

func WithClient

func WithClient(client http.Client) Option

WithClient overrides default client instance.

func WithTokenSource added in v1.6.0

func WithTokenSource(ts TokenSource) Option

WithTokenSource sets a token source that is consulted on every request for a bearer token.

Use this instead of WithBearerToken when the provider credential can rotate over the client's lifetime, for example when an Auth0 access token is refreshed in the background.

type Options

type Options struct {
	// ExtraHeaders represents extra headers to be added to each request.
	ExtraHeaders http.Header
	// TokenSource, when set, is called on every request to obtain a bearer token.
	TokenSource TokenSource
	// Client is the http client.
	Client http.Client
}

Options defines client options.

type OverlayInfo added in v0.3.0

type OverlayInfo struct {
	Name   string `json:"name"`
	Image  string `json:"image"`
	Ref    string `json:"ref"`
	Digest string `json:"digest"`
}

OverlayInfo defines overlay versions list response item.

type TokenCreateOptions added in v1.7.0

type TokenCreateOptions struct {
	Name           string
	Subject        string
	Actor          Actor
	Scopes         []string
	IssuableScopes []string
	TTL            time.Duration
	Ephemeral      bool
}

TokenCreateOptions describes a credential to mint. Actor selects a fixed server-owned profile; otherwise Scopes and IssuableScopes define the executable and delegation capabilities directly. Subject is normally empty; only the CLI bootstrap credential may mint for another identity. Credentials are stored and revocable by default; Ephemeral explicitly opts out.

type TokenInfo added in v1.7.0

type TokenInfo struct {
	CreatedAt      time.Time `json:"created_at"`
	ExpiresAt      time.Time `json:"expires_at"`
	ID             string    `json:"id"`
	Name           string    `json:"name"`
	Scopes         []string  `json:"scopes"`
	IssuableScopes []string  `json:"issuable_scopes,omitempty"`
}

TokenInfo defines an API token list response item.

type TokenSource added in v1.6.0

type TokenSource func(ctx context.Context) (string, error)

TokenSource returns the bearer token to use for the next request.

It is called on every request, so it can be backed by a value that rotates over time (for example, a token refreshed in the background). An empty token with a nil error leaves the request unauthenticated.

Jump to

Keyboard shortcuts

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