client

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Jul 11, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package client is the public Go SDK for the Chronos HTTP API.

It is decoupled from internal/domain: the wire types in this package are independent so internal refactors do not break consumers. Functional options keep the constructor stable as configuration grows.

Typical use: 

c, _ := client.New("http://chronos.local:7778",
    client.WithTimeout(10*time.Second),
)
signals, err := c.Signals().Scope(scopeID).List(ctx)

Index

Constants

View Source 
const (
	PatternTypeRecurrence            = "recurrence"
	PatternTypeTrend                 = "trend"
	PatternTypeSpike                 = "spike"
	PatternTypeDrop                  = "drop"
	PatternTypeStall                 = "stall"
	PatternTypeAnomaly               = "anomaly"
	PatternTypeSeasonality           = "seasonality"
	PatternTypeCorrelation           = "correlation"
	PatternTypeChangePoint           = "change_point"
	PatternTypeOutlierCluster        = "outlier_cluster"
	PatternTypeCrossScopeCorrelation = "cross_scope_correlation"
)

PatternType constants mirror the engine's domain.PatternType enum so callers can switch on stable string values without importing internal packages.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Status int
	Body   string
}

APIError is returned for non-2xx HTTP responses. Callers can switch on Status to differentiate "not found" (404) from other failures.

func (*APIError) Error 

func (e *APIError) Error() string

type Client 

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

Client is a thread-safe Chronos HTTP API client. Construct with New; the zero value is unusable.

func New 

func New(baseURL string, opts ...Option) (*Client, error)

New constructs a Client targeting baseURL.

func (*Client) Health 

func (c *Client) Health(ctx context.Context) error

Health calls GET /health and returns nil when the server reports healthy.

func (*Client) Ingest 

func (c *Client) Ingest(ctx context.Context, req IngestRequest) (uuid.UUID, error)

Ingest sends a single observation to /v1/ingest. ID and Timestamp are populated server-side if zero.

func (*Client) Signals 

func (c *Client) Signals() *SignalQuery

Signals returns a fluent builder for the /v1/signals endpoint.

type Evidence 

type Evidence struct {
	Series  uuid.UUID          `json:"series"`
	Time    time.Time          `json:"time"`
	Kind    string             `json:"kind"`
	Score   float64            `json:"score"`
	Metrics map[string]float64 `json:"metrics,omitempty"`
}

Evidence is one piece of supporting evidence for a signal.

type GRPCClient added in v0.3.0 

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

GRPCClient is a gRPC transport implementation of the Chronos client surface. It returns the same Signal and IngestRequest types as the HTTP Client so callers can switch transports without changing business code.

func NewGRPC added in v0.3.0 

func NewGRPC(addr string, opts ...GRPCOption) (*GRPCClient, error)

NewGRPC constructs a GRPCClient targeting addr (e.g. "localhost:7779").

func (*GRPCClient) Close added in v0.3.0 

func (c *GRPCClient) Close() error

Close tears down the underlying gRPC connection.

func (*GRPCClient) Ingest added in v0.3.0 

func (c *GRPCClient) Ingest(ctx context.Context, req IngestRequest) (uuid.UUID, error)

Ingest sends a single observation to the gRPC Ingest RPC.

func (*GRPCClient) Signals added in v0.3.0 

func (c *GRPCClient) Signals() *GRPCSignalQuery

Signals returns a fluent builder for the ListSignals RPC.

type GRPCOption added in v0.3.0 

type GRPCOption func(*GRPCClient)

GRPCOption configures a GRPCClient.

func WithGRPCToken added in v0.3.0 

func WithGRPCToken(tok string) GRPCOption

WithGRPCToken sets a bearer token sent as gRPC metadata on every RPC.

type GRPCSignalQuery added in v0.3.0 

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

GRPCSignalQuery is the gRPC equivalent of SignalQuery.

func (*GRPCSignalQuery) Get added in v0.3.0 

func (q *GRPCSignalQuery) Get(ctx context.Context, id uuid.UUID) (Signal, error)

Get returns a single signal by ID via the GetSignal RPC.

func (*GRPCSignalQuery) Limit added in v0.3.0 

func (q *GRPCSignalQuery) Limit(n int) *GRPCSignalQuery

Limit caps the number of returned signals.

func (*GRPCSignalQuery) List added in v0.3.0 

func (q *GRPCSignalQuery) List(ctx context.Context) ([]Signal, error)

List runs the query via the ListSignals RPC.

func (*GRPCSignalQuery) MinConfidence added in v0.3.0 

func (q *GRPCSignalQuery) MinConfidence(threshold float64) *GRPCSignalQuery

MinConfidence drops signals below threshold.

func (*GRPCSignalQuery) Pattern added in v0.3.0 

func (q *GRPCSignalQuery) Pattern(name string) *GRPCSignalQuery

Pattern filters to a single PatternType (use the PatternType* constants).

func (*GRPCSignalQuery) Scope added in v0.3.0 

func (q *GRPCSignalQuery) Scope(id uuid.UUID) *GRPCSignalQuery

Scope filters by scope ID. Required for List.

func (*GRPCSignalQuery) Series added in v0.3.0 

func (q *GRPCSignalQuery) Series(id uuid.UUID) *GRPCSignalQuery

Series filters to signals about a single entity.

func (*GRPCSignalQuery) Since added in v0.3.0 

func (q *GRPCSignalQuery) Since(t time.Time) *GRPCSignalQuery

Since restricts results to signals detected at or after t.

func (*GRPCSignalQuery) Until added in v0.3.0 

func (q *GRPCSignalQuery) Until(t time.Time) *GRPCSignalQuery

Until restricts results to signals detected before t.

type IngestRequest 

type IngestRequest struct {
	ID        uuid.UUID         `json:"id,omitempty"`
	EntityID  uuid.UUID         `json:"entity_id"`
	ScopeID   uuid.UUID         `json:"scope_id"`
	Timestamp time.Time         `json:"timestamp"`
	Features  []float64         `json:"features"`
	Labels    []string          `json:"labels,omitempty"`
	Meta      map[string]string `json:"meta,omitempty"`
	Adapter   string            `json:"adapter,omitempty"`
}

IngestRequest is the wire shape for POST /v1/ingest. It mirrors the vision's TimeSeriesPoint with Chronos's multi-feature support.

type Option 

type Option func(*Client)

Option configures a Client.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient overrides the underlying *http.Client. The client must be safe for concurrent use; the SDK does not wrap it.

func WithLogger 

func WithLogger(l *slog.Logger) Option

WithLogger attaches an slog.Logger; the client emits debug-level events for each request. Pass nil (or omit the option) to disable.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout applies the given timeout to the underlying http.Client.

func WithToken 

func WithToken(tok string) Option

WithToken sets a bearer token sent on every request as "Authorization: Bearer <token>". Empty tokens are ignored.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent overrides the default User-Agent header.

type Signal 

type Signal struct {
	ID         uuid.UUID          `json:"id"`
	ScopeID    uuid.UUID          `json:"scope_id"`
	Series     uuid.UUID          `json:"series"`
	Pattern    string             `json:"pattern"`
	DetectedAt time.Time          `json:"detected_at"`
	Window     TimeWindow         `json:"window"`
	Strength   float64            `json:"strength"`
	Confidence float64            `json:"confidence"`
	Metrics    map[string]float64 `json:"metrics,omitempty"`
	Evidence   []Evidence         `json:"evidence,omitempty"`
}

Signal is the wire shape of a signal returned by the HTTP API. It mirrors the API's JSON contract; new fields the server adds are picked up automatically as long as their JSON keys match. This type duplicates the internal/api.SignalDTO definition rather than importing it: the SDK is part of the public surface, internal/api is not.

type SignalQuery 

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

SignalQuery is a fluent builder for /v1/signals. Construct via Client.Signals. Chain filters, then call List or Get.

func (*SignalQuery) Get 

func (q *SignalQuery) Get(ctx context.Context, id uuid.UUID) (Signal, error)

Get returns a single signal by ID.

func (*SignalQuery) Limit 

func (q *SignalQuery) Limit(n int) *SignalQuery

Limit caps the number of returned signals.

func (*SignalQuery) List 

func (q *SignalQuery) List(ctx context.Context) ([]Signal, error)

List runs the query.

func (*SignalQuery) MinConfidence 

func (q *SignalQuery) MinConfidence(threshold float64) *SignalQuery

MinConfidence drops signals below threshold.

func (*SignalQuery) Pattern 

func (q *SignalQuery) Pattern(name string) *SignalQuery

Pattern filters to a single PatternType (use the PatternType* constants from this package).

func (*SignalQuery) Scope 

func (q *SignalQuery) Scope(id uuid.UUID) *SignalQuery

Scope filters by scope ID. Required for List.

func (*SignalQuery) Series 

func (q *SignalQuery) Series(id uuid.UUID) *SignalQuery

Series filters to signals about a single entity.

func (*SignalQuery) Since 

func (q *SignalQuery) Since(t time.Time) *SignalQuery

Since restricts results to signals detected at or after t.

func (*SignalQuery) Stream 

func (q *SignalQuery) Stream(ctx context.Context) (<-chan Signal, error)

Stream subscribes to /v1/signals/stream and returns a channel that emits each newly-detected signal until ctx is cancelled or the server closes the stream. Scope is required (the SSE endpoint rejects unscoped streams). Pattern is honoured server-side when set.

The returned channel is closed by the SDK on ctx cancellation, connection drop, or fatal protocol error — `for sig := range ch` is safe.

Streaming bypasses the client's Timeout so connections can outlive the configured per-request deadline; cancel via ctx instead.

For at-most-once gap recovery, pair the stream with a Since-keyed List call: the persisted /v1/signals query is the source of truth, the stream is a courtesy. De-duplicate by Signal.ID.

func (*SignalQuery) Until 

func (q *SignalQuery) Until(t time.Time) *SignalQuery

Until restricts results to signals detected before t.

type TimeWindow 

type TimeWindow struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

TimeWindow is the analysis window over which a signal was detected.

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.