config

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

vex-config-sdk-go

Typed Go SDK for vex-config, generated from the canonical Smithy spec.

go get github.com/vextura/vex-config-sdk-go

Usage

import "github.com/vextura/vex-config-sdk-go"

func main() {
    client := config.New("https://gate.example.com", "<bearer-token>")
    // typed method per Smithy operation
}

Generated

This package is generated by vexctl clientgen. Do not edit the generated files (client.go, types.go, operations.go, errors.go, doc.go) by hand — regenerate from the Smithy source when the API changes.

License

Apache 2.0 — see LICENSE.

Documentation

Overview

Package config is the typed Go SDK for RIPService.

Usage: 

c := config.New("", "<bearer-token>")
out, err := c.OperationName(ctx, config.OperationNameInput{...})
if err != nil {
    var nf config.ErrorEnvelope
    if errors.As(err, &nf) { ... typed error ... }
}

The SDK shares its wire types with the server's generated handlers by construction — both sides emit from the same Smithy spec, so they cannot drift apart. Add new operations to the .smithy and regenerate both halves.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrValidation   = errors.New("validation failed")
	ErrUnauthorized = errors.New("unauthorized")
	ErrForbidden    = errors.New("forbidden")
	ErrNotFound     = errors.New("not found")
	ErrConflict     = errors.New("conflict")
	ErrInternal     = errors.New("internal error")
)

Sentinel errors callers can match with errors.Is. Decoded from ErrorEnvelope.Code on every non-2xx response.

Functions

This section is empty.

Types

type Client 

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

Client is the typed SDK for RIPService.

Construct with New(); every operation is a typed method on Client. Default HTTPClient has a 30s timeout and follows redirects; override with WithHTTPClient(...) when you need different behavior.

func New 

func New(endpoint, token string, opts ...Option) *Client

New constructs a Client. endpoint is the service base URL (e.g. "http://vex-vault:8200"); token is the bearer credential sent on every request. Either may be empty for tests against httptest.NewServer.

func (*Client) ClearRegistry added in v0.2.0 

func (c *Client) ClearRegistry()

ClearRegistry removes any WithRegistry state associated with the client (used in tests and when reconfiguring at runtime).

func (*Client) CreateRegion 

func (c *Client) CreateRegion(ctx context.Context, in CreateRegionInput) (RegionDetail, error)

CreateRegion calls POST /rip/regions.

func (*Client) DeleteRegion 

func (c *Client) DeleteRegion(ctx context.Context, in RegionIdInput) error

DeleteRegion calls DELETE /rip/regions/{id}.

func (*Client) DeregisterService 

func (c *Client) DeregisterService(ctx context.Context, in DeregisterInput) error

DeregisterService calls DELETE /rip/services.

func (*Client) Endpoint 

func (c *Client) Endpoint() string

Endpoint returns the service base URL the client is targeting.

func (*Client) GetRegionDetail 

func (c *Client) GetRegionDetail(ctx context.Context, in RegionPathInput) (RegionDetail, error)

GetRegionDetail calls GET /rip/regions/{region}.

func (*Client) GetZone 

func (c *Client) GetZone(ctx context.Context) (ZoneOutput, error)

GetZone calls GET /rip/zone.

func (*Client) HeartbeatService 

func (c *Client) HeartbeatService(ctx context.Context, in HeartbeatInput) error

HeartbeatService calls POST /rip/heartbeat.

func (*Client) ListRegionServices 

func (c *Client) ListRegionServices(ctx context.Context, in RegionPathInput) (ServiceListOutput, error)

ListRegionServices calls GET /rip/regions/{region}/services.

func (*Client) ListRegions 

func (c *Client) ListRegions(ctx context.Context) (ListRegionsOutput, error)

ListRegions calls GET /rip/regions.

func (*Client) ListServiceRegions 

func (c *Client) ListServiceRegions(ctx context.Context, in ServicePathInput) (ServiceListOutput, error)

ListServiceRegions calls GET /rip/services/{service}.

func (*Client) ListSubscriptions 

func (c *Client) ListSubscriptions(ctx context.Context, in ListSubscriptionsInput) (SubscriptionsOutput, error)

ListSubscriptions calls GET /rip/subscriptions.

func (*Client) RegisterService 

func (c *Client) RegisterService(ctx context.Context, in ServiceRecord) (ServiceRecord, error)

RegisterService calls POST /rip/register.

func (*Client) ResolveService 

func (c *Client) ResolveService(ctx context.Context, in ResolveInput) (ServiceRecord, error)

ResolveService calls GET /rip/resolve/{service}/{region}.

func (*Client) ResolveServiceRegistryFirst added in v0.2.0 

func (c *Client) ResolveServiceRegistryFirst(ctx context.Context, in ResolveInput) (ServiceRecord, error)

ResolveServiceRegistryFirst attempts a vex-registry lookup before falling back to the generated ResolveService (RIP). Uses the environment-configured registry URL (VEX_REGISTRY_URL) unless the client was constructed with WithRegistry(url).

Not-registered errors from the registry are treated as "try RIP", preserving the migration safety net. Any other registry error is returned as-is so a broken registry doesn't silently fall back to stale RIP data.

func (*Client) Subscribe 

func (c *Client) Subscribe(ctx context.Context, in SubscribeInput) (Subscription, error)

Subscribe calls POST /rip/subscriptions.

func (*Client) Unsubscribe 

func (c *Client) Unsubscribe(ctx context.Context, in SubscriptionIdInput) error

Unsubscribe calls DELETE /rip/subscriptions/{id}.

func (*Client) UpdateServiceLifecycle 

func (c *Client) UpdateServiceLifecycle(ctx context.Context, in UpdateLifecycleInput) error

UpdateServiceLifecycle calls PATCH /rip/services/{vrn}/lifecycle.

type CreateRegionInput 

type CreateRegionInput struct {
	Id          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

CreateRegionInput mirrors the Smithy structure of the same name.

type DeregisterInput 

type DeregisterInput struct {
	Vrn string `json:"vrn"`
}

DeregisterInput mirrors the Smithy structure of the same name.

type ErrorEnvelope 

type ErrorEnvelope struct {
	Code      string         `json:"code"`
	Message   string         `json:"message"`
	RequestID string         `json:"request_id,omitempty"`
	TraceID   string         `json:"trace_id,omitempty"`
	Details   map[string]any `json:"details,omitempty"`
	// Status is the HTTP status code observed on the wire. Not part of the
	// JSON shape; set by the decoder so callers can switch on it.
	Status int `json:"-"`
}

ErrorEnvelope is the wire shape every server returns on error.

func (ErrorEnvelope) Error 

func (e ErrorEnvelope) Error() string

type HeartbeatInput 

type HeartbeatInput struct {
	Vrn    string `json:"vrn"`
	Status string `json:"status"`
}

HeartbeatInput mirrors the Smithy structure of the same name.

type ListRegionsOutput 

type ListRegionsOutput struct {
	Regions []string `json:"regions"`
}

ListRegionsOutput mirrors the Smithy structure of the same name.

type ListSubscriptionsInput 

type ListSubscriptionsInput struct {
	Service string `json:"service,omitempty"`
	Region  string `json:"region,omitempty"`
}

ListSubscriptionsInput mirrors the Smithy structure of the same name.

type Option 

type Option func(*Client)

Option configures a Client at construction time.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient overrides the default http.Client. Use this to plug in custom transports, retry middleware, or test doubles.

func WithRegistry added in v0.2.0 

func WithRegistry(registryURL string) Option

WithRegistry configures the client to use vex-registry as the primary read path for ResolveService. Callers that opt into this wrapper get registry-first behavior without touching per-call code.

Usage: 

sdk := configsdk.New(vexConfigURL, "", configsdk.WithRegistry(regURL))
rec, err := sdk.ResolveServiceRegistryFirst(ctx, in)

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-request timeout on the default http.Client. Ignored if WithHTTPClient already supplied a fully-configured client.

type RegionDetail 

type RegionDetail struct {
	Region       string   `json:"region"`
	ServiceCount int      `json:"service_count"`
	Services     []string `json:"services,omitempty"`
	CreatedAt    string   `json:"created_at,omitempty"`
}

RegionDetail mirrors the Smithy structure of the same name.

type RegionIdInput 

type RegionIdInput struct {
	Id string `json:"id"`
}

RegionIdInput mirrors the Smithy structure of the same name.

type RegionPathInput 

type RegionPathInput struct {
	Region string `json:"region"`
}

RegionPathInput mirrors the Smithy structure of the same name.

type RegistryClient added in v0.2.0 

type RegistryClient struct {
	BaseURL    string       // e.g. "http://vex-registry:9091"
	HTTPClient *http.Client // optional; defaults to 3s timeout
	// contains filtered or unexported fields
}

RegistryClient is a thin vex-registry lookup client used as the read path for ResolveServiceRegistryFirst. Exposed so callers can construct it once and reuse across multiple ResolveService calls.

func NewRegistryClient added in v0.2.0 

func NewRegistryClient(baseURL string) *RegistryClient

NewRegistryClient constructs a RegistryClient from a base URL. Empty base means "no-op" — Resolve returns not-registered so callers must fall back to RIP.

func (*RegistryClient) Resolve added in v0.2.0 

func (r *RegistryClient) Resolve(ctx context.Context, service, region string) (ServiceRecord, error)

Resolve queries vex-registry for healthy instances of the named service in the given region and returns a ServiceRecord that mirrors what ResolveService would have produced from RIP. Region is applied client-side (registry API doesn't yet accept ?region= param); empty region matches all. Region "*" is treated as empty (any region).

type ResolveInput 

type ResolveInput struct {
	Service string `json:"service"`
	Region  string `json:"region"`
}

ResolveInput mirrors the Smithy structure of the same name.

type ServiceListOutput 

type ServiceListOutput struct {
	Services []*ServiceRecord `json:"services"`
	Count    int              `json:"count"`
}

ServiceListOutput mirrors the Smithy structure of the same name.

type ServicePathInput 

type ServicePathInput struct {
	Service string `json:"service"`
}

ServicePathInput mirrors the Smithy structure of the same name.

type ServiceRecord 

type ServiceRecord struct {
	Vrn              string                 `json:"vrn"`
	Service          string                 `json:"service"`
	Region           string                 `json:"region"`
	Env              string                 `json:"env"`
	Scope            string                 `json:"scope"`
	Endpoint         string                 `json:"endpoint"`
	Status           string                 `json:"status"`
	DnsName          string                 `json:"dns_name,omitempty"`
	HealthCheckUrl   string                 `json:"health_check_url,omitempty"`
	LastHeartbeat    string                 `json:"last_heartbeat,omitempty"`
	RegisteredAt     string                 `json:"registered_at,omitempty"`
	Meta             map[string]string      `json:"meta,omitempty"`
	CustomProperties map[string]interface{} `json:"custom_properties,omitempty"`
}

ServiceRecord mirrors the Smithy structure of the same name.

type SubscribeInput 

type SubscribeInput struct {
	Service       string `json:"service"`
	Region        string `json:"region"`
	SubscriberVrn string `json:"subscriber_vrn"`
}

SubscribeInput mirrors the Smithy structure of the same name.

type Subscription 

type Subscription struct {
	Id            string `json:"id"`
	Service       string `json:"service"`
	Region        string `json:"region"`
	SubscriberVrn string `json:"subscriber_vrn"`
	CreatedAt     string `json:"created_at,omitempty"`
}

Subscription mirrors the Smithy structure of the same name.

type SubscriptionIdInput 

type SubscriptionIdInput struct {
	Id string `json:"id"`
}

SubscriptionIdInput mirrors the Smithy structure of the same name.

type SubscriptionsOutput 

type SubscriptionsOutput struct {
	Subscriptions []*Subscription `json:"subscriptions"`
}

SubscriptionsOutput mirrors the Smithy structure of the same name.

type UpdateLifecycleInput 

type UpdateLifecycleInput struct {
	Vrn    string `json:"vrn"`
	Status string `json:"status"`
	Reason string `json:"reason,omitempty"`
}

UpdateLifecycleInput mirrors the Smithy structure of the same name.

type ZoneOutput 

type ZoneOutput struct {
	Body string `json:"body"`
}

ZoneOutput mirrors the Smithy structure of the same name.

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.