whadmin

package
v1.146.1 Latest Latest
Warning

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

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

Documentation

Overview

Package whadmin is what an administrator does to a webhook source (#1870): create one, change it, rotate its secret, read its status, and delete it.

Creating a source is more than writing its record. Its tables and view are created on the connection it names, and the connection is proved able to hold them -- its catalog reads the managed-resources bucket and allows register_partition -- before the source is stored, so a source the platform accepts is one whose events can be queried. The table is recorded as a registration, which is how the table listing and every surface reading registrations sees it.

Index

Constants

View Source
const SilentAfter = 24 * time.Hour

SilentAfter is how long an enabled source may go without an event before it is reported silent.

View Source
const SpoolStale = 2 * time.Minute

SpoolStale is how long a receiver may go without reporting its spool before it is shown as not reporting: many times the stats flush it reports on.

Variables

View Source
var (
	ErrNotFound  = whsource.ErrNotFound
	ErrExists    = whsource.ErrExists
	ErrNameTaken = errors.New("a table with this source's name is already registered on that connection")
	// ErrUnusable wraps the reason a connection could not hold the source's
	// tables, as the query engine gave it.
	ErrUnusable = errors.New("the connection cannot hold this source's table")
)

Refusals a request can meet, beyond whsource.ErrInvalid and the table package's connection refusals.

Functions

This section is empty.

Types

type Deps

type Deps struct {
	Sources       Sources
	Tables        Tables
	Registrations Registrations
	Windows       Windows
	Objects       Objects
	Resources     Resources
	Bucket        string
	// Changed is called after every write, so this replica's receiver
	// serves the change at once rather than at its next refresh.
	Changed func()
	// PersonaExists reports whether a persona is defined, so a source cannot
	// name one nobody belongs to. Nil accepts any name.
	PersonaExists func(name string) bool
	NewID         func() (string, error)
	Logger        *slog.Logger
	Now           func() time.Time
}

Deps are what the service acts through.

type Health added in v1.138.2

type Health string

Health is a source's overall state on the overview of every source (#1979).

const (
	// HealthDisabled is a source an administrator turned off.
	HealthDisabled Health = "disabled"
	// HealthFailing is a source with one or more windows whose last
	// compaction failed.
	HealthFailing Health = "failing"
	// HealthSilent is an enabled source that received no event in the last
	// SilentAfter, including one that never received any. A sender that
	// stops produces no error on the receiving side, so this is how it shows.
	HealthSilent Health = "silent"
	// HealthReceiving is an enabled source that received an event within
	// SilentAfter and has no failing window.
	HealthReceiving Health = "receiving"
)

The states a source can be in. When more than one applies, the first in this order is reported: Disabled, Failing, Silent, Receiving. A disabled source receives nothing by choice, so neither its silence nor its windows are news; a failing source is losing data it did receive, which outranks silence; a source that is neither is receiving.

func HealthOf added in v1.138.2

func HealthOf(src whsource.Source, sum whstore.Summary, now time.Time) Health

HealthOf is a source's health at now, from its summary.

type Objects

type Objects interface {
	ListKeys(ctx context.Context, bucket, prefix string) ([]string, error)
	DeleteObject(ctx context.Context, bucket, key string) error
}

Objects lists and deletes what a source wrote outside the resource store.

type Overview added in v1.138.2

type Overview struct {
	Now        time.Time
	Since      time.Time
	Step       time.Duration
	Sources    []SourceOverview
	Volume     []whstore.VolumePoint
	Rejections []whstore.Rejection
	Spools     []SpoolOverview
}

Overview is the status of every source at Now, the request series from Since in buckets of Step, the newest rejections of every source, and every receiver's spool.

type Registrations

type Registrations interface {
	Insert(ctx context.Context, r tableregister.Registration) error
	ByName(ctx context.Context, connection, catalog, schema, table string) (*tableregister.Registration, error)
	BySource(ctx context.Context, kind, sourceID string) ([]tableregister.Registration, error)
	Delete(ctx context.Context, id string) error
}

Registrations records the source's table. tableregister's store satisfies it.

type Resources

type Resources interface {
	Delete(ctx context.Context, id string) error
}

Resources deletes a compacted window's resource.

type Service

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

Service manages sources.

func New

func New(d Deps) *Service

New builds the service.

func (*Service) Create

func (s *Service) Create(ctx context.Context, src whsource.Source) (whsource.Source, error)

Create makes a source: its tables, the proof its connection can hold them, its record and its registration. A failure part-way removes what was made.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, name string) error

Delete removes a source and everything it wrote: its tables, its windows' resources, its raw segments, its registration and its record.

func (*Service) Get

Get returns one source with its status.

func (*Service) List

func (s *Service) List(ctx context.Context) ([]whsource.Source, error)

List returns every source.

func (*Service) Overview added in v1.138.2

func (s *Service) Overview(ctx context.Context, source string, span, step time.Duration) (Overview, error)

Overview reads the status of every source, or of the source named when source is not empty, in one pass: the sources, ordered by name, each with its health; the request series over span before now in buckets of step; and the newest rejections within that span. A source named that does not exist is ErrNotFound.

func (*Service) SyncPartitions added in v1.146.1

func (s *Service) SyncPartitions(ctx context.Context, name string) error

SyncPartitions makes a source's raw partitions match the window directories in the bucket by listing them all. Retention keeps the partitions by name and never lists (#2133); this is the repair an administrator runs when the two have drifted, a restore for one.

func (*Service) Update

func (s *Service) Update(ctx context.Context, name string, u Update) (whsource.Source, error)

Update changes a source's settings. The name, the connection and the persona stay: the table was created on that connection under a name derived from the source's, and the windows already written are in that persona's library. An empty secret keeps the stored one, so a form never has to carry it.

func (*Service) Warnings added in v1.146.1

func (s *Service) Warnings(ctx context.Context, src whsource.Source) []string

Warnings returns what a save of src should tell the administrator who made it without refusing it: a slow read of its partitions, which an uncached file metastore causes, and settings under which the open window holds more segments between rollups than a reader should have to read. A check that cannot be made says so rather than staying silent.

type SourceOverview added in v1.138.2

type SourceOverview struct {
	Source  whsource.Source
	Health  Health
	Summary whstore.Summary
}

SourceOverview is one source on the overview: its settings, its health and its summary.

type Sources

type Sources interface {
	List(ctx context.Context) ([]whsource.Source, error)
	Get(ctx context.Context, name string) (whsource.Source, error)
	Create(ctx context.Context, src whsource.Source) error
	// Update writes src and returns the updated_at it stamped.
	Update(ctx context.Context, src whsource.Source) (time.Time, error)
	Delete(ctx context.Context, name string) error
}

Sources is the source record store. whsource.Store satisfies it.

type SpoolOverview added in v1.146.0

type SpoolOverview struct {
	State     whstore.SpoolState
	Reporting bool
}

SpoolOverview is one receiver's spool (#2121): what it last reported, and whether it still reports. A receiver that stopped with events waiting is shown that way, since they are drained only when it, or a replica given its volume, starts again.

type Tables

type Tables interface {
	TargetFor(connection string) (whtable.Target, error)
	S3Location(prefix string) string
	Create(ctx context.Context, tg whtable.Target, src whsource.Source) error
	Probe(ctx context.Context, tg whtable.Target, src whsource.Source) error
	Drop(ctx context.Context, tg whtable.Target, src whsource.Source) error
	SyncRaw(ctx context.Context, tg whtable.Target, src whsource.Source) error
	PartitionReadTime(ctx context.Context, tg whtable.Target, src whsource.Source) (time.Duration, error)
}

Tables is the query-engine side. whtable.Tables satisfies it.

type Update

type Update struct {
	Enabled *bool
	Auth    whsource.Auth
	Config  whsource.Config
	// RotationOverlap keeps the previous secret valid this long when Auth
	// carries a new one. Zero ends it at once.
	RotationOverlap time.Duration
}

Update is what an administrator can change on a source.

type Windows

type Windows interface {
	Status(ctx context.Context, source string, now time.Time) (whstore.Status, error)
	Overview(ctx context.Context, source string, now time.Time, span, step time.Duration) (whstore.Overview, error)
	ResourceIDs(ctx context.Context, source string) ([]string, error)
	// SpoolStates reads every receiver's spool state (#2121).
	SpoolStates(ctx context.Context) ([]whstore.SpoolState, error)
}

Windows reads a source's status, the overview of every source, and the resources a source's windows were written as.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL