client

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 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.
	APIKeyIDHeader = "X-Queue-Control-Key-ID" //nolint:gosec // A protocol header name, not a credential.
	// APIKeySecretHeader carries the static key credential accepted by the
	// deployable control-plane server.
	APIKeySecretHeader = "X-Queue-Control-Key" //nolint:gosec // A protocol header name, not a credential.
)

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/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