client

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package client provides a REST admin client for the provisioning API.

Index

Constants

View Source 
const DefaultClientTimeout = 30 * time.Second

DefaultClientTimeout is the default HTTP client timeout.

Variables

View Source 
var (
	ErrAPIBadRequest   = errors.New("API bad request")
	ErrAPIUnauthorized = errors.New("API unauthorized")
	ErrAPIForbidden    = errors.New("API forbidden")
	ErrAPINotFound     = errors.New("API not found")
	ErrAPIConflict     = errors.New("API conflict")
	ErrAPIRateLimited  = errors.New("API rate limited")
	ErrAPIInternal     = errors.New("API internal error")

	// Routing rule conflict errors.
	ErrDuplicateRoutingPattern  = errors.New("routing rule with this pattern already exists")
	ErrDuplicateRoutingPriority = errors.New("routing rule with this priority already exists")

	// Topic errors (ADR-0006 Phase 2).
	ErrTopicAlreadyExists    = errors.New("topic already exists")
	ErrTopicNotFound         = errors.New("topic not found")
	ErrTopicReferencedByRule = errors.New("topic is referenced by a routing rule")
)

Sentinel errors for API responses.

View Source 
var (
	ErrDeviceAuthorizationPending = errors.New("authorization pending")
	ErrDeviceSlowDown             = errors.New("polling too frequently")
	ErrDeviceRateLimited          = errors.New("rate limited")                 // 429 — back off and retry
	ErrDeviceTransient            = errors.New("temporary device-login error") // transport/5xx — retry
	ErrDeviceExpired              = errors.New("device code expired")
	ErrDeviceAccessDenied         = errors.New("authorization request denied")
	ErrDeviceInvalidGrant         = errors.New("invalid or unknown device code")
	ErrDeviceInvalidClient        = errors.New("unrecognized client")
)

Device-grant poll outcomes. The two non-terminal ones (pending/slow_down) and the two transient ones (rate-limited/transient) tell the caller to keep polling; the rest are terminal.

Functions

This section is empty.

Types

type AdminClient 

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

AdminClient communicates with the provisioning REST API.

func New 

func New(cfg Config) (*AdminClient, error)

New creates a new AdminClient.

func (*AdminClient) AddRoutingRule 

func (c *AdminClient) AddRoutingRule(ctx context.Context, tenantID string, rule RoutingRule) (map[string]any, error)

AddRoutingRule adds a single routing rule for a tenant via POST. Returns ErrDuplicateRoutingPattern or ErrDuplicateRoutingPriority on 409 conflicts.

func (*AdminClient) CreateAPIKey 

func (c *AdminClient) CreateAPIKey(ctx context.Context, tenantID string, req map[string]any) (map[string]any, error)

CreateAPIKey creates a new API key for a tenant.

func (*AdminClient) CreateKey 

func (c *AdminClient) CreateKey(ctx context.Context, tenantID string, req map[string]any) (map[string]any, error)

CreateKey registers a new public key for a tenant.

func (*AdminClient) CreateTenant 

func (c *AdminClient) CreateTenant(ctx context.Context, req map[string]any) (map[string]any, error)

CreateTenant creates a new tenant via the provisioning API.

func (*AdminClient) CreateTopic added in v1.1.0 

func (c *AdminClient) CreateTopic(ctx context.Context, tenantID, suffix string) (map[string]any, error)

CreateTopic provisions a non-default topic for a tenant via POST. Returns ErrTopicAlreadyExists on a 409 conflict.

func (*AdminClient) CreateWebhook added in v1.1.0 

func (c *AdminClient) CreateWebhook(ctx context.Context, tenantID string, req CreateWebhookRequest) (map[string]any, error)

CreateWebhook registers a webhook for the tenant.

func (*AdminClient) DeleteChannelRules 

func (c *AdminClient) DeleteChannelRules(ctx context.Context, tenantID string) (map[string]any, error)

DeleteChannelRules deletes channel rules for a tenant.

func (*AdminClient) DeleteRoutingRules 

func (c *AdminClient) DeleteRoutingRules(ctx context.Context, tenantID string) (map[string]any, error)

DeleteRoutingRules deletes routing rules for a tenant.

func (*AdminClient) DeleteTopic added in v1.1.0 

func (c *AdminClient) DeleteTopic(ctx context.Context, tenantID, suffix string) (map[string]any, error)

DeleteTopic removes a provisioned topic via DELETE. Returns ErrTopicNotFound on a 404 and ErrTopicReferencedByRule when a routing rule still references it.

func (*AdminClient) DeleteWebhook added in v1.1.0 

func (c *AdminClient) DeleteWebhook(ctx context.Context, tenantID, webhookID string) (map[string]any, error)

DeleteWebhook removes a webhook registration.

func (*AdminClient) DeprovisionTenant 

func (c *AdminClient) DeprovisionTenant(ctx context.Context, tenantID string) (map[string]any, error)

DeprovisionTenant deprovisions a tenant by ID.

func (*AdminClient) GetChannelRules 

func (c *AdminClient) GetChannelRules(ctx context.Context, tenantID string) (map[string]any, error)

GetChannelRules retrieves channel rules for a tenant.

func (*AdminClient) GetEdition 

func (c *AdminClient) GetEdition(ctx context.Context) (*EditionResponse, error)

GetEdition fetches the edition status from GET /edition. This endpoint does not require authentication — the method makes a direct HTTP call without the Bearer token (unlike doJSON which always adds it).

func (*AdminClient) GetQuota 

func (c *AdminClient) GetQuota(ctx context.Context, tenantID string) (map[string]any, error)

GetQuota retrieves the quota for a tenant.

func (*AdminClient) GetRoutingRules 

func (c *AdminClient) GetRoutingRules(ctx context.Context, tenantID string) (map[string]any, error)

GetRoutingRules retrieves routing rules for a tenant.

func (*AdminClient) GetTenant 

func (c *AdminClient) GetTenant(ctx context.Context, tenantID string) (map[string]any, error)

GetTenant retrieves a tenant by ID.

func (*AdminClient) GetWebhook added in v1.1.0 

func (c *AdminClient) GetWebhook(ctx context.Context, tenantID, webhookID string) (map[string]any, error)

GetWebhook returns a single webhook by ID.

func (*AdminClient) ListAPIKeys 

func (c *AdminClient) ListAPIKeys(ctx context.Context, tenantID string) (map[string]any, error)

ListAPIKeys lists all API keys for a tenant.

func (*AdminClient) ListAdminKeys 

func (c *AdminClient) ListAdminKeys(ctx context.Context) (map[string]any, error)

ListAdminKeys lists active admin keys.

func (*AdminClient) ListKeys 

func (c *AdminClient) ListKeys(ctx context.Context, tenantID string) (map[string]any, error)

ListKeys lists all keys for a tenant.

func (*AdminClient) ListTenants 

func (c *AdminClient) ListTenants(ctx context.Context, params map[string]string) (map[string]any, error)

ListTenants lists tenants with optional filter parameters.

func (*AdminClient) ListTopics added in v1.1.0 

func (c *AdminClient) ListTopics(ctx context.Context, tenantID string) (map[string]any, error)

ListTopics retrieves a tenant's provisioned topics (the default topic is always included first).

func (*AdminClient) ListWebhooks added in v1.1.0 

func (c *AdminClient) ListWebhooks(ctx context.Context, tenantID string) (map[string]any, error)

ListWebhooks returns the tenant's webhook registrations.

func (*AdminClient) PushLicense 

func (c *AdminClient) PushLicense(ctx context.Context, key string) (*LicenseResponse, error)

PushLicense posts a license key to the provisioning service. Returns the applied license details on success, or an actionable error. Handles 429 (rate limited) with Retry-After header extraction.

func (*AdminClient) ReactivateTenant 

func (c *AdminClient) ReactivateTenant(ctx context.Context, tenantID string) (map[string]any, error)

ReactivateTenant reactivates a suspended tenant.

func (*AdminClient) RegisterAdminKey 

func (c *AdminClient) RegisterAdminKey(ctx context.Context, name, algorithm, publicKey string) (map[string]any, error)

RegisterAdminKey registers a new admin public key.

func (*AdminClient) RevokeAPIKey 

func (c *AdminClient) RevokeAPIKey(ctx context.Context, tenantID, keyID string) (map[string]any, error)

RevokeAPIKey revokes an API key by tenant and key ID.

func (*AdminClient) RevokeAdminKey 

func (c *AdminClient) RevokeAdminKey(ctx context.Context, keyID string) error

RevokeAdminKey revokes an admin key by ID.

func (*AdminClient) RevokeKey 

func (c *AdminClient) RevokeKey(ctx context.Context, tenantID, keyID string) (map[string]any, error)

RevokeKey revokes a key by tenant and key ID.

func (*AdminClient) RevokeToken 

func (c *AdminClient) RevokeToken(ctx context.Context, tenantID string, req map[string]any) (map[string]any, error)

RevokeToken revokes a token by jti or sub for a tenant.

func (*AdminClient) SetChannelRules 

func (c *AdminClient) SetChannelRules(ctx context.Context, tenantID string, req map[string]any) (map[string]any, error)

SetChannelRules sets channel rules for a tenant.

func (*AdminClient) SetRoutingRules 

func (c *AdminClient) SetRoutingRules(ctx context.Context, tenantID string, body any) (map[string]any, error)

SetRoutingRules sets routing rules for a tenant.

func (*AdminClient) SuspendTenant 

func (c *AdminClient) SuspendTenant(ctx context.Context, tenantID string) (map[string]any, error)

SuspendTenant suspends a tenant by ID.

func (*AdminClient) TestAccess 

func (c *AdminClient) TestAccess(ctx context.Context, tenantID string, req map[string]any) (map[string]any, error)

TestAccess tests channel access for a tenant with the given parameters.

func (*AdminClient) TestWebhook added in v1.1.0 

func (c *AdminClient) TestWebhook(ctx context.Context, tenantID, webhookID string) (map[string]any, error)

TestWebhook performs a single synchronous test delivery to the webhook's URL.

func (*AdminClient) UpdateQuota 

func (c *AdminClient) UpdateQuota(ctx context.Context, tenantID string, req map[string]any) (map[string]any, error)

UpdateQuota updates the quota for a tenant.

func (*AdminClient) UpdateTenant 

func (c *AdminClient) UpdateTenant(ctx context.Context, tenantID string, req map[string]any) (map[string]any, error)

UpdateTenant updates a tenant by ID.

func (*AdminClient) UpdateWebhook added in v1.1.0 

func (c *AdminClient) UpdateWebhook(ctx context.Context, tenantID, webhookID string, body map[string]any) (map[string]any, error)

UpdateWebhook applies a partial update to a webhook. body carries only the fields to change.

type AuthSigner 

type AuthSigner interface {
	SignRequest(req *http.Request)
}

AuthSigner signs HTTP requests with admin credentials.

type Config 

type Config struct {
	BaseURL string
	Timeout time.Duration
	Signer  AuthSigner
}

Config holds AdminClient configuration.

type CreateWebhookRequest added in v1.1.0 

type CreateWebhookRequest struct {
	URL            string `json:"url"`
	ChannelPattern string `json:"channel_pattern"`
	Secret         string `json:"secret"`
	MaxRetries     int    `json:"max_retries,omitempty"`
}

CreateWebhookRequest is the request body for CreateWebhook.

type DeviceAuthorization added in v1.2.0 

type DeviceAuthorization struct {
	DeviceCode              string
	UserCode                string
	VerificationURI         string
	VerificationURIComplete string
	ExpiresIn               int
	Interval                int
}

DeviceAuthorization is the /device/authorize response.

type DeviceToken added in v1.2.0 

type DeviceToken struct {
	LicenseKey string
	Edition    string
	Exp        int64
}

DeviceToken is the /device/token success response — the issued license key.

type DialOption 

type DialOption func(*dialConfig)

DialOption configures the WebSocket connection.

func WithAPIKey 

func WithAPIKey(apiKey string) DialOption

WithAPIKey sets the API key for authentication.

func WithToken 

func WithToken(token string) DialOption

WithToken sets the JWT token for authentication.

type EditionLimits 

type EditionLimits struct {
	MaxTenants               int `json:"max_tenants"`
	MaxTotalConnections      int `json:"max_total_connections"`
	MaxShards                int `json:"max_shards"`
	MaxTopicsPerTenant       int `json:"max_topics_per_tenant"`
	MaxRoutingRulesPerTenant int `json:"max_routing_rules_per_tenant"`
}

EditionLimits holds the hard limits for the current edition. A value of 0 means unlimited.

type EditionResponse 

type EditionResponse struct {
	Edition   string        `json:"edition"`
	Org       string        `json:"org"`
	ExpiresAt string        `json:"expires_at"`
	Expired   bool          `json:"expired"`
	Limits    EditionLimits `json:"limits"`
	Usage     EditionUsage  `json:"usage"`
}

EditionResponse represents the GET /edition response from the provisioning service.

type EditionUsage 

type EditionUsage struct {
	Tenants     *int `json:"tenants"`
	Connections *int `json:"connections"`
	Shards      *int `json:"shards"`
}

EditionUsage holds live resource usage counts. Nil fields indicate the data source did not provide that metric.

type KeypairSigner 

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

KeypairSigner signs requests with an Ed25519 admin JWT.

func NewKeypairSigner 

func NewKeypairSigner(privateKey ed25519.PrivateKey, keyID, keyName string) *KeypairSigner

NewKeypairSigner creates a KeypairSigner.

func (*KeypairSigner) SignRequest 

func (s *KeypairSigner) SignRequest(req *http.Request)

SignRequest creates a short-lived admin JWT and sets it as the Authorization header.

type LicenseDeviceClient added in v1.2.0 

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

LicenseDeviceClient talks to the hosted license service's public device-grant endpoints (RFC 8628). It is unauthenticated: the device_code is the bearer.

func NewLicenseDeviceClient added in v1.2.0 

func NewLicenseDeviceClient(baseURL string) *LicenseDeviceClient

NewLicenseDeviceClient targets the license service at baseURL (e.g. https://api.sukko.dev).

func (*LicenseDeviceClient) Authorize added in v1.2.0 

func (c *LicenseDeviceClient) Authorize(ctx context.Context) (*DeviceAuthorization, error)

Authorize starts a device-authorization request and returns the codes + poll parameters. A non-201, an unparseable body, or a response missing the fields the flow needs is an error (defense against upstream drift).

func (*LicenseDeviceClient) PollToken added in v1.2.0 

func (c *LicenseDeviceClient) PollToken(ctx context.Context, deviceCode string) (*DeviceToken, error)

PollToken polls once. On success it returns the issued key. Non-terminal and transient outcomes return a retryable sentinel (ErrDeviceAuthorizationPending, ErrDeviceSlowDown, ErrDeviceRateLimited, ErrDeviceTransient); terminal failures return the matching terminal sentinel.

type LicenseResponse 

type LicenseResponse struct {
	Edition   string `json:"edition"`
	Org       string `json:"org"`
	ExpiresAt string `json:"expires_at"`
	Status    string `json:"status"`
}

LicenseResponse holds the server response from a license push.

type RoutingRule 

type RoutingRule struct {
	Pattern      string   `json:"pattern"`
	IngressTopic string   `json:"ingress_topic"`
	EgressTopics []string `json:"egress_topics,omitempty"`
	Priority     int      `json:"priority"`
}

RoutingRule is the request body for AddRoutingRule.

type ServerMessage 

type ServerMessage struct {
	Type    string          `json:"type"`
	Channel string          `json:"channel,omitempty"`
	Data    json.RawMessage `json:"data,omitempty"`
	// Mid is the stable message identity: an opaque string (at most 64 chars)
	// that is identical on every copy of the same message — live broadcast,
	// gap replay, and history. Omitted when the server does not send one
	// (e.g. non-message frames or entries stored before mid was introduced).
	Mid string `json:"mid,omitempty"`
}

ServerMessage represents a message received from the gateway.

type WSClient 

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

WSClient is a WebSocket client for communicating with the Sukko gateway.

func Dial 

func Dial(ctx context.Context, gatewayURL string, opts ...DialOption) (*WSClient, error)

Dial connects to the gateway WebSocket endpoint.

func (*WSClient) Close 

func (c *WSClient) Close() error

Close closes the WebSocket connection. It is safe to call multiple times.

func (*WSClient) Publish 

func (c *WSClient) Publish(channel string, data json.RawMessage) error

Publish sends a publish message on the given channel.

func (*WSClient) ReadMessage 

func (c *WSClient) ReadMessage() (*ServerMessage, error)

ReadMessage reads the next message from the server.

func (*WSClient) SendAuth 

func (c *WSClient) SendAuth(token string) error

SendAuth sends a JWT token for mid-connection auth refresh.

func (*WSClient) Subscribe 

func (c *WSClient) Subscribe(channels []string) error

Subscribe sends a subscribe message for the given channels.

func (*WSClient) Unsubscribe 

func (c *WSClient) Unsubscribe(channels []string) error

Unsubscribe sends an unsubscribe message for the given channels.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
⌂ 换网址