apichange

package
v1.158.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package apichange keeps an API catalog's specs current and says what changed (#2469): a spec's upstream checked on a schedule or on request, the difference from the copy in use as a report of operations added, removed, changed and newly deprecated (#2483), an uploaded or pasted spec compared with an upstream it is never replaced by (#2484), which scripts, prompts and endpoints use each operation (#2485), and what upstreams say about an operation in their answers: Deprecation, Sunset, and a removal (#2486).

Everything read from an upstream is untrusted text: a spec's operation ids, summaries and version, and a header's value, are cleaned and bounded before they are stored or sent.

Index

Constants

View Source
const (
	PartParameters  = "parameters"
	PartRequestBody = "request_body"
	PartResponses   = "responses"
)

The parts of an operation a change report names as changed.

View Source
const (
	StatusApplied    = "applied"    // the fetched spec replaced the copy in use
	StatusPending    = "pending"    // held for an administrator
	StatusDiscarded  = "discarded"  // an administrator discarded a held change
	StatusReported   = "reported"   // an upstream_url difference, never applied
	StatusSuperseded = "superseded" // a held change replaced by a newer one
)

Change statuses (#2483, #2484).

View Source
const (
	TriggerSchedule = "schedule"
	TriggerManual   = "manual"
)

Triggers of a check.

View Source
const (
	CallerScript   = "script"
	CallerEndpoint = "endpoint"
	CallerPrompt   = "prompt"

	ViaSource = "source" // the script's saved source names the operation
	ViaRun    = "run"    // a run of the script called it
	ViaPrompt = "prompt" // the prompt's text names it
)

Caller kinds, and how a caller was found (#2485).

View Source
const (
	WarningDeprecation = "deprecation"
	WarningSunset      = "sunset"
	WarningRemoved     = "removed"
)

Warning kinds (#2486).

View Source
const LockKey int64 = 4713210231

LockKey is the advisory lock a pass holds, so one replica checks at a time.

View Source
const SettingsSection = "api_changes"

SettingsSection is the platform_settings section holding where change reports and upstream warnings are sent.

Variables

View Source
var ErrNoChange = errors.New("apichange: no such change")

ErrNoChange is a change id that names no change of the spec.

View Source
var ErrNotOpenAPI = errors.New("apichange: only an OpenAPI or WSDL spec can be compared with an upstream")

ErrNotOpenAPI is an upstream_url on a spec whose operations are not read from an OpenAPI document (a GraphQL schema), which a report cannot compare.

View Source
var ErrNotPending = errors.New("apichange: the change is not waiting for review")

ErrNotPending is a decision on a change that is not waiting for one.

View Source
var ErrNotRefreshable = errors.New("apichange: the spec has no source URL and no upstream URL to check")

ErrNotRefreshable is a check of a spec with nowhere to read it from: not URL-sourced, and no upstream_url.

Functions

func ChangeBody

func ChangeBody(c Change) string

ChangeBody is a change report as markdown. Every value read from the spec or a caller is a code span, so none of it is read as markup.

func FetchFailed

func FetchFailed(err error) bool

FetchFailed reports whether err is a check that could not read the upstream; its text names the spec and never the URL.

func NewSettings

func NewSettings(db *sql.DB) *settingsjson.Section[Settings]

NewSettings is the api_changes section over db.

func PruneCallers

func PruneCallers(ctx context.Context, db *sql.DB) error

PruneCallers forgets callers no run has made within the retention window.

Types

type Caller

type Caller struct {
	Kind       string     `json:"kind"`
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	Via        string     `json:"via"`
	Connection string     `json:"connection,omitempty"`
	LastSeenAt *time.Time `json:"last_seen_at,omitempty"`
}

Caller is one script, endpoint or prompt that uses an operation.

type Callers

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

Callers is an audit decorator recording which script called which API operation in a run (#2485). Only the run's script, the connection and the operation are kept, never the call's arguments.

func NewCallers

func NewCallers(inner audit.Logger, db *sql.DB, key OperationKeyer) *Callers

NewCallers wraps inner.

func (*Callers) Close

func (c *Callers) Close() error

Close passes through to the audit store.

func (*Callers) Log

func (c *Callers) Log(ctx context.Context, event audit.Event) error

Log writes the event, then records the operation a script run's API call addressed. The audit write's outcome is what is returned.

func (*Callers) Query

func (c *Callers) Query(ctx context.Context, filter audit.QueryFilter) ([]audit.Event, error)

Query passes through to the audit store.

type Catalogs

type Catalogs interface {
	GetSpec(ctx context.Context, catalogID, specName string) (*apicatalog.SpecEntry, error)
	ReferencingConnections(ctx context.Context, catalogID string) ([]apicatalog.ConnectionRef, error)
}

Catalogs reads specs and the connections that reference a catalog (apicatalog.Store).

type Change

type Change struct {
	ID             string     `json:"id"`
	CatalogID      string     `json:"catalog_id"`
	SpecName       string     `json:"spec_name"`
	Status         string     `json:"status"`
	Trigger        string     `json:"trigger"`
	Report         Report     `json:"report"`
	Summary        string     `json:"summary"`
	CreatedAt      time.Time  `json:"created_at"`
	DecidedBy      string     `json:"decided_by,omitempty"`
	DecidedAt      *time.Time `json:"decided_at,omitempty"`
	PendingContent string     `json:"-"`
	PendingETag    string     `json:"-"`
}

Change is one check that found the upstream different.

type ChangeStore

type ChangeStore interface {
	GetWatch(ctx context.Context, k SpecKey) (Watch, error)
	RecordCheck(ctx context.Context, k SpecKey, rec CheckRecord) error
	Due(ctx context.Context, limit int) ([]SpecKey, error)
	AddChange(ctx context.Context, c Change) error
	GetChange(ctx context.Context, k SpecKey, id string) (Change, error)
	PendingFor(ctx context.Context, catalogID string) (map[string]string, error)
	Decide(ctx context.Context, k SpecKey, id, status, by string) error
}

ChangeStore keeps watches and change reports (*Store).

type Changed

type Changed struct {
	Op
	Parts []string `json:"parts"`
}

Changed is an operation present in both versions whose contract moved.

type ChannelNotifier

type ChannelNotifier struct {
	Settings *settingsjson.Section[Settings]
	Sender   Sender
	// PortalBase is the portal's public address, for the link back.
	PortalBase string
}

ChannelNotifier sends change reports and new warnings to the channels the api_changes settings name. Nothing is sent while none are named.

func (*ChannelNotifier) Changed

func (n *ChannelNotifier) Changed(ctx context.Context, c Change)

Changed sends a change report.

func (*ChannelNotifier) Warned

func (n *ChannelNotifier) Warned(ctx context.Context, w Warning)

Warned sends a new upstream warning.

type CheckRecord

type CheckRecord struct {
	Err string
	// Upstream is set when the check read a new upstream copy to keep.
	Upstream     bool
	UpstreamETag string
	UpstreamBody string
}

CheckRecord is what one check leaves on the watch.

type Loop

type Loop struct {
	Refresher *Refresher
	DB        *sql.DB
	// contains filtered or unexported fields
}

Loop checks every spec whose scheduled check has come (#2483).

func (*Loop) RunOnce

func (l *Loop) RunOnce(ctx context.Context) error

RunOnce checks the due specs under the advisory lock, and forgets run-recorded callers past their retention. It returns bgloop.ErrSkipped when another replica holds the lock. A spec whose check fails is stamped with the failure and checked again one interval on; the pass goes on to the next.

func (*Loop) Start

func (l *Loop) Start(ctx context.Context)

Start begins the loop; it checks at once.

func (*Loop) Stop

func (l *Loop) Stop()

Stop ends the loop and waits for a pass in progress.

type Notifier

type Notifier interface {
	Changed(ctx context.Context, c Change)
}

Notifier sends a change report to the channels an administrator chose.

type Op

type Op struct {
	ID      string   `json:"id"`
	Method  string   `json:"method"`
	Path    string   `json:"path"`
	Summary string   `json:"summary,omitempty"`
	UsedBy  []Caller `json:"used_by,omitempty"`
}

Op is one operation as a report names it. ID is the spec's operationId, or "METHOD path" when the spec gives none, which is also how a script and a warning address it. UsedBy is filled when the report is written.

type OperationIndex

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

OperationIndex resolves an address a caller uses to the operation a report names: an operation id, or a method and a concrete or template path.

func NewOperationIndex

func NewOperationIndex(contents ...string) OperationIndex

NewOperationIndex indexes the operations of each spec content. A content that does not parse contributes nothing: the index answers for what can be read.

func (OperationIndex) Ops

func (x OperationIndex) Ops() []Op

Ops is every indexed operation, in id order.

func (OperationIndex) Resolve

func (x OperationIndex) Resolve(operationID, method, path string) (Op, bool)

Resolve returns the operation an address reaches. An id is looked up as written; a method and path match the operation whose template the path fits, the most literal one when several do, and failing that the path with its leading base-path segments removed.

type OperationKeyer

type OperationKeyer func(ctx context.Context, connection, method, path, operationID string) string

OperationKeyer names the catalog operation an API call addresses: its operation id, or "METHOD template", or "" when the catalog declares none (the API gateway toolkits).

func OperationKeyOf

func OperationKeyOf(all func() []registry.Toolkit) OperationKeyer

OperationKeyOf asks the API gateway toolkits all lists which catalog operation a call addresses; all is read on every call, since connections come and go while the platform runs.

type Preparer

type Preparer func(entry *apicatalog.SpecEntry) error

Preparer validates a spec and renders the OpenAPI document it serves (catalogapi.PrepareSpec).

type Refresher

type Refresher struct {
	Catalogs Catalogs
	Write    Writer
	Prepare  Preparer
	// Store keeps watches and reports; nil (no database) checks and applies
	// with no report kept and no hold.
	Store ChangeStore
	// Usage fills each reported operation's callers; nil leaves them out.
	Usage *Usage
	// Notify sends each stored report; nil sends nothing.
	Notify Notifier
	// Fetch is the base fetch options: the operator's private prefixes.
	Fetch apicatalog.FetchOptions
	// contains filtered or unexported fields
}

Refresher checks a spec's upstream and acts on what changed. The manual refresh route and the schedule both go through Check.

func (*Refresher) Apply

func (r *Refresher) Apply(ctx context.Context, k SpecKey, id, by string) (Result, error)

Apply settles a held change by putting its document in use.

func (*Refresher) Check

func (r *Refresher) Check(ctx context.Context, k SpecKey, trigger, _ string) (Result, error)

Check reads the spec's upstream and acts on it: a URL-sourced spec that changed is applied, or held when the spec holds changes; an uploaded or pasted spec with an upstream_url is compared with it and the difference reported, never applied. Every check is stamped on the spec's watch, failure included.

func (*Refresher) Discard

func (r *Refresher) Discard(ctx context.Context, k SpecKey, id, by string) error

Discard settles a held change by dropping its document.

type Report

type Report struct {
	FromVersion string    `json:"from_version,omitempty"`
	ToVersion   string    `json:"to_version,omitempty"`
	Added       []Op      `json:"added"`
	Removed     []Op      `json:"removed"`
	Changed     []Changed `json:"changed"`
	Deprecated  []Op      `json:"deprecated"`
	// Truncated is true when a list was cut at its bound.
	Truncated bool `json:"truncated,omitempty"`
}

Report is what one version of a spec changed from the one before it.

func Compare

func Compare(prev, next string) (Report, error)

Compare reports what next changed from prev. Both are OpenAPI documents, the effective content a spec serves; either failing to parse is an error.

func (Report) Counts

func (r Report) Counts() string

Counts is the report in one line: "3 added, 1 removed, 2 changed, 1 deprecated", with the version change when there is one.

func (Report) Empty

func (r Report) Empty() bool

Empty reports whether the two versions differ in nothing a report names: no operation and no info.version. A formatting change is empty.

type Result

type Result struct {
	Spec        *apicatalog.SpecEntry
	Change      *Change
	NotModified bool
}

Result is what one check did. Spec is the copy in use afterwards; Change is the report recorded, or the held one an unchanged check found waiting.

type Sender

type Sender interface {
	Send(ctx context.Context, names []string, key string, p notification.Payload) int
}

Sender posts a document to named channels (levelalert.Sender, the notification substrate's channel sender).

type Settings

type Settings struct {
	Channels []string `json:"channels"`
}

Settings is where change reports and warnings go: notification channels by name, none by default.

func ReadSettings

func ReadSettings(ctx context.Context, s *settingsjson.Section[Settings]) (Settings, error)

ReadSettings returns the stored settings, the defaults when none are.

type SpecKey

type SpecKey struct {
	CatalogID string
	SpecName  string
}

SpecKey names one spec of one catalog.

type Store

type Store struct {
	DB *sql.DB
}

Store is the PostgreSQL store of watches, changes, warnings and callers.

func (Store) AddChange

func (s Store) AddChange(ctx context.Context, c Change) error

AddChange records a change. A pending one first retires the change the spec already holds, in the same transaction, so a spec holds one at a time.

func (Store) Decide

func (s Store) Decide(ctx context.Context, k SpecKey, id, status, by string) error

Decide moves a pending change to status (applied or discarded).

func (Store) Due

func (s Store) Due(ctx context.Context, limit int) ([]SpecKey, error)

Due returns up to limit specs whose scheduled check has come.

func (Store) GetChange

func (s Store) GetChange(ctx context.Context, k SpecKey, id string) (Change, error)

GetChange returns one change of a spec, or ErrNoChange.

func (Store) GetWatch

func (s Store) GetWatch(ctx context.Context, k SpecKey) (Watch, error)

GetWatch returns a spec's watch; a spec never configured is its zero value.

func (Store) ListChanges

func (s Store) ListChanges(ctx context.Context, k SpecKey, limit int) ([]Change, error)

ListChanges returns a spec's changes, newest first, at most limit.

func (Store) PendingFor

func (s Store) PendingFor(ctx context.Context, catalogID string) (map[string]string, error)

PendingFor reports which of a catalog's specs hold a change for review.

func (Store) RecordCheck

func (s Store) RecordCheck(ctx context.Context, k SpecKey, rec CheckRecord) error

RecordCheck stamps a check on the spec's watch.

func (Store) SaveSettings

func (s Store) SaveSettings(ctx context.Context, w Watch, by string) error

SaveSettings stores an administrator's settings for a spec.

type Usage

type Usage struct {
	DB *sql.DB
}

Usage answers which scripts, endpoints and prompts use the operations of a set of connections.

func (Usage) Callers

func (u Usage) Callers(ctx context.Context, connections []string, idx OperationIndex) (map[string][]Caller, error)

Callers returns, for each operation of idx that connections reach, what uses it: scripts whose source names it, scripts a run of which called it, the endpoints bound to either, and prompts whose text names it. An operation nothing uses is absent.

type Warning

type Warning struct {
	Connection  string     `json:"connection"`
	Operation   string     `json:"operation"`
	Kind        string     `json:"kind"`
	Detail      string     `json:"detail,omitempty"`
	FirstSeenAt time.Time  `json:"first_seen_at"`
	LastSeenAt  time.Time  `json:"last_seen_at"`
	SeenCount   int64      `json:"seen_count"`
	NotifiedAt  *time.Time `json:"notified_at,omitempty"`
}

Warning is what an upstream said about one operation of a connection.

func ListWarnings

func ListWarnings(ctx context.Context, db *sql.DB, connection string) ([]Warning, error)

ListWarnings returns a connection's warnings, the most recent first.

type WarningNotifier

type WarningNotifier interface {
	Warned(ctx context.Context, w Warning)
}

WarningNotifier sends a new warning to the channels an administrator chose.

type Warnings

type Warnings struct {
	DB     *sql.DB
	Notify WarningNotifier
	// contains filtered or unexported fields
}

Warnings records upstream warnings from the answers the outbound chain hands it (upstreamwarn.Observer). Writes leave the request at once: each runs on its own goroutine, bounded, and throttled per replica so a busy operation costs a write an hour.

func NewWarnings

func NewWarnings(db *sql.DB, notify WarningNotifier) *Warnings

NewWarnings builds the recorder.

func (*Warnings) Observe

func (w *Warnings) Observe(ctx context.Context, connection, operation string, status int, header http.Header)

Observe reads one answer: a 2xx records the operation's success, a Deprecation or Sunset header a warning, and a 404 or 410 a removal when the operation answered 2xx before.

type Watch

type Watch struct {
	SpecKey
	// RefreshInterval is how often the upstream is checked; zero is never.
	RefreshInterval time.Duration
	HoldChanges     bool
	// UpstreamURL is what an uploaded or pasted spec is compared with.
	UpstreamURL     string
	UpstreamETag    string
	UpstreamContent string
	NextCheckAt     *time.Time
	LastCheckedAt   *time.Time
	LastError       string
	UpdatedBy       string
	UpdatedAt       time.Time
}

Watch is how one spec is kept current.

type Writer

type Writer func(ctx context.Context, catalogID string, entry apicatalog.SpecEntry) error

Writer saves a spec as the copy in use: stores it, re-embeds its operations and reloads the connections that read it, on every replica. catalogapi.Config.WriteSpec is the one implementation, shared with the admin API's own spec writes.

Jump to

Keyboard shortcuts

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