Documentation
¶
Overview ¶
Package client provides a typed bounded administrative API client.
Index ¶
- Constants
- Variables
- type APIError
- type APIKeySource
- type AuditQuery
- type Client
- func (c *Client) DesiredStateReader(tenant string) (queue.DesiredStateReader, error)
- func (c *Client) ExecuteCommand(ctx context.Context, tenant string, command apihttp.CommandRequest) (controlplane.CommandResult, error)
- func (c *Client) GetCommand(ctx context.Context, tenant string, key string) (controlplane.CommandResult, error)
- func (c *Client) GetDesiredState(ctx context.Context, tenant string, target queue.Target) (queue.DesiredRecord, error)
- func (c *Client) InspectDeadLetter(ctx context.Context, tenant string, id string, ...) (apihttp.Record, error)
- func (c *Client) InspectDeadLetterWithOptions(ctx context.Context, tenant string, id string, options RecordInspectOptions) (apihttp.Record, error)
- func (c *Client) InspectFailure(ctx context.Context, tenant string, id string, ...) (apihttp.Record, error)
- func (c *Client) InspectFailureWithOptions(ctx context.Context, tenant string, id string, options RecordInspectOptions) (apihttp.Record, error)
- func (c *Client) ListAudit(ctx context.Context, tenant string, query AuditQuery) (apihttp.AuditPage, error)
- func (c *Client) ListCommands(ctx context.Context, tenant string, query CommandQuery) (apihttp.CommandHistoryPage, error)
- func (c *Client) ListDeadLetters(ctx context.Context, tenant string, query RecordQuery) (apihttp.RecordPage, error)
- func (c *Client) ListFailures(ctx context.Context, tenant string, query RecordQuery) (apihttp.RecordPage, error)
- func (c *Client) ListQueues(ctx context.Context, tenant string, query QueueQuery) (apihttp.QueuePage, error)
- func (c *Client) ListWorkers(ctx context.Context, tenant string, query WorkerQuery) (apihttp.WorkerPage, error)
- func (c *Client) ListWorkloads(ctx context.Context, tenant string, query WorkloadQuery) (controlkubernetes.Page, error)
- type CommandQuery
- type Config
- type QueueQuery
- type RecordInspectOptions
- type RecordQuery
- type TokenSource
- type WorkerQuery
- type WorkloadQuery
Examples ¶
Constants ¶
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 ¶
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") )
var ErrInvalidResponse = errors.New("control-plane client: invalid response")
ErrInvalidResponse reports malformed or mismatched successful API output.
Functions ¶
This section is empty.
Types ¶
type APIKeySource ¶
APIKeySource acquires a static API-key identifier and secret for one request context.
type AuditQuery ¶
AuditQuery contains bounded audit-history pagination.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls the versioned administrative API.
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 ¶
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 ¶
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 ¶
TokenSource acquires a bearer token for one request context.
type WorkerQuery ¶
WorkerQuery contains bounded worker-list filters.
type WorkloadQuery ¶
WorkloadQuery contains bounded Kubernetes pagination.