Help us shape the future of Go! Take the 2026 Go Developer Survey

client

package
v3.1.1 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package client provides a typed bounded administrative API client.

Index

Examples

Constants

View Source
const (
	// APIKeyIDHeader carries the non-secret static key identifier accepted by
	// the deployable control-plane server.
	// #nosec G101 -- public HTTP header name, not a credential; credential values come from caller-owned authentication
	APIKeyIDHeader = "X-Queue-Control-Key-ID"
	// APIKeySecretHeader carries the static key credential accepted by the
	// deployable control-plane server.
	// #nosec G101 -- public HTTP header name, not a credential; credential values come from caller-owned authentication
	APIKeySecretHeader = "X-Queue-Control-Key"
)

Variables

View Source
var (
	ErrInvalidConfiguration = errors.New("control-plane client: invalid configuration")
	ErrInvalidRequest       = errors.New("control-plane client: invalid request")
	ErrInvalidToken         = errors.New("control-plane client: invalid bearer token")
	ErrInvalidAPIKey        = errors.New("control-plane client: invalid API key")
	ErrResponseTooLarge     = errors.New("control-plane client: response too large")
)
View Source
var ErrInvalidResponse = errors.New("control-plane client: invalid response")

ErrInvalidResponse reports malformed or mismatched successful API output.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	Status int
	Code   string
}

APIError is a stable non-success administrative response.

func (*APIError) Error

func (e *APIError) Error() string

type APIKeySource

type APIKeySource interface {
	APIKey(context.Context) (string, string, error)
}

APIKeySource acquires a static API-key identifier and secret for one request context.

type AuditQuery

type AuditQuery struct {
	After uint64
	Limit uint32
}

AuditQuery contains bounded audit-history pagination.

type Client

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

Client calls the versioned administrative API.

func New

func New(config Config) (*Client, error)

New creates a typed administrative API client.

func (*Client) DesiredStateReader

func (c *Client) DesiredStateReader(tenant string) (queue.DesiredStateReader, error)

DesiredStateReader binds one tenant for use by a queue reconciler.

Example
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"

	"github.com/faustbrian/go-queue-control-plane/v3/client"
	queue "github.com/faustbrian/go-queue/management"
)

func main() {
	target := queue.Target{Kind: queue.TargetQueue, Name: "critical"}
	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
		_ = json.NewEncoder(writer).Encode(queue.DesiredRecord{
			Target: target, State: queue.DesiredPaused, Revision: 3,
			ChangedAt: time.Date(2026, 7, 16, 10, 0, 0, 0, time.UTC),
			CommandID: "pause-critical-3",
		})
	}))
	defer server.Close()

	api, err := client.New(client.Config{
		BaseURL: server.URL,
		APIKeys: exampleAPIKeySource{},
	})
	if err != nil {
		panic(err)
	}
	reader, err := api.DesiredStateReader("tenant-1")
	if err != nil {
		panic(err)
	}
	reconciler, err := queue.NewDesiredStateReconciler(
		queue.DesiredStateReconcilerConfig{
			Reader: reader, Applier: exampleDesiredApplier{},
			Targets: []queue.Target{target},
		},
	)
	if err != nil {
		panic(err)
	}
	if err := reconciler.Reconcile(context.Background()); err != nil {
		panic(err)
	}
}

type exampleAPIKeySource struct{}

func (exampleAPIKeySource) APIKey(context.Context) (string, string, error) {
	return "worker-1", "example-secret", nil
}

type exampleDesiredApplier struct{}

func (exampleDesiredApplier) ApplyDesiredState(
	_ context.Context,
	record queue.DesiredRecord,
) error {
	fmt.Printf(
		"apply %s to %s at revision %d\n",
		record.State,
		record.Target.Name,
		record.Revision,
	)
	return nil
}
Output:
apply paused to critical at revision 3

func (*Client) ExecuteCommand

func (c *Client) ExecuteCommand(
	ctx context.Context,
	tenant string,
	command apihttp.CommandRequest,
) (controlplane.CommandResult, error)

ExecuteCommand submits one actor-free command request for a tenant.

func (*Client) GetCommand

func (c *Client) GetCommand(
	ctx context.Context,
	tenant string,
	key string,
) (controlplane.CommandResult, error)

GetCommand returns one tenant-scoped durable command outcome.

func (*Client) GetDesiredState

func (c *Client) GetDesiredState(
	ctx context.Context,
	tenant string,
	target queue.Target,
) (queue.DesiredRecord, error)

GetDesiredState returns one validated tenant-scoped convergence record.

func (*Client) InspectDeadLetter

func (c *Client) InspectDeadLetter(
	ctx context.Context,
	tenant string,
	id string,
	visibility queue.PayloadVisibility,
) (apihttp.Record, error)

InspectDeadLetter returns one tenant dead letter at the requested visibility.

func (*Client) InspectDeadLetterWithOptions

func (c *Client) InspectDeadLetterWithOptions(
	ctx context.Context,
	tenant string,
	id string,
	options RecordInspectOptions,
) (apihttp.Record, error)

InspectDeadLetterWithOptions returns a dead letter with explicit privileged fields.

func (*Client) InspectFailure

func (c *Client) InspectFailure(
	ctx context.Context,
	tenant string,
	id string,
	visibility queue.PayloadVisibility,
) (apihttp.Record, error)

InspectFailure returns one tenant failure at the requested visibility.

func (*Client) InspectFailureWithOptions

func (c *Client) InspectFailureWithOptions(
	ctx context.Context,
	tenant string,
	id string,
	options RecordInspectOptions,
) (apihttp.Record, error)

InspectFailureWithOptions returns a failure with explicit privileged fields.

func (*Client) ListAudit

func (c *Client) ListAudit(
	ctx context.Context,
	tenant string,
	query AuditQuery,
) (apihttp.AuditPage, error)

ListAudit returns one bounded tenant audit-history page.

func (*Client) ListCommands

func (c *Client) ListCommands(
	ctx context.Context,
	tenant string,
	query CommandQuery,
) (apihttp.CommandHistoryPage, error)

ListCommands returns one bounded tenant command-history page.

func (*Client) ListDeadLetters

func (c *Client) ListDeadLetters(
	ctx context.Context,
	tenant string,
	query RecordQuery,
) (apihttp.RecordPage, error)

ListDeadLetters returns one bounded tenant dead-letter page.

func (*Client) ListFailures

func (c *Client) ListFailures(
	ctx context.Context,
	tenant string,
	query RecordQuery,
) (apihttp.RecordPage, error)

ListFailures returns one bounded tenant failure page.

func (*Client) ListQueues

func (c *Client) ListQueues(
	ctx context.Context,
	tenant string,
	query QueueQuery,
) (apihttp.QueuePage, error)

ListQueues returns one bounded tenant queue-status page.

func (*Client) ListWorkers

func (c *Client) ListWorkers(
	ctx context.Context,
	tenant string,
	query WorkerQuery,
) (apihttp.WorkerPage, error)

ListWorkers returns one bounded tenant worker page.

func (*Client) ListWorkloads

func (c *Client) ListWorkloads(
	ctx context.Context,
	tenant string,
	query WorkloadQuery,
) (controlkubernetes.Page, error)

ListWorkloads returns one bounded tenant workload page.

type CommandQuery

type CommandQuery struct {
	Cursor string
	Limit  uint32
}

CommandQuery contains bounded command-history pagination.

type Config

type Config struct {
	BaseURL          string
	HTTPClient       *http.Client
	Tokens           TokenSource
	APIKeys          APIKeySource
	MaxResponseBytes int64
}

Config defines the API endpoint, authentication, and response bounds.

type QueueQuery

type QueueQuery struct {
	Cursor string
	Limit  uint32
}

QueueQuery contains bounded queue-status pagination.

type RecordInspectOptions

type RecordInspectOptions struct {
	Payload           queue.PayloadVisibility
	RevealDiagnostics bool
}

RecordInspectOptions controls independently privileged record fields.

type RecordQuery

type RecordQuery struct {
	Cursor    string
	Limit     uint32
	Search    string
	Sort      queue.SortField
	Direction queue.SortDirection
}

RecordQuery contains bounded failure and dead-letter list controls.

type TokenSource

type TokenSource interface {
	Token(context.Context) (string, error)
}

TokenSource acquires a bearer token for one request context.

type WorkerQuery

type WorkerQuery struct {
	Limit uint32
	After string
	State fleet.State
	Queue string
}

WorkerQuery contains bounded worker-list filters.

type WorkloadQuery

type WorkloadQuery struct {
	Limit    int64
	Continue string
}

WorkloadQuery contains bounded Kubernetes pagination.

Jump to

Keyboard shortcuts

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