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
- Variables
- func ChangeBody(c Change) string
- func FetchFailed(err error) bool
- func NewSettings(db *sql.DB) *settingsjson.Section[Settings]
- func PruneCallers(ctx context.Context, db *sql.DB) error
- type Caller
- type Callers
- type Catalogs
- type Change
- type ChangeStore
- type Changed
- type ChannelNotifier
- type CheckRecord
- type Loop
- type Notifier
- type Op
- type OperationIndex
- type OperationKeyer
- type Preparer
- type Refresher
- type Report
- type Result
- type Sender
- type Settings
- type SpecKey
- type Store
- func (s Store) AddChange(ctx context.Context, c Change) error
- func (s Store) Decide(ctx context.Context, k SpecKey, id, status, by string) error
- func (s Store) Due(ctx context.Context, limit int) ([]SpecKey, error)
- func (s Store) GetChange(ctx context.Context, k SpecKey, id string) (Change, error)
- func (s Store) GetWatch(ctx context.Context, k SpecKey) (Watch, error)
- func (s Store) ListChanges(ctx context.Context, k SpecKey, limit int) ([]Change, error)
- func (s Store) PendingFor(ctx context.Context, catalogID string) (map[string]string, error)
- func (s Store) RecordCheck(ctx context.Context, k SpecKey, rec CheckRecord) error
- func (s Store) SaveSettings(ctx context.Context, w Watch, by string) error
- type Usage
- type Warning
- type WarningNotifier
- type Warnings
- type Watch
- type Writer
Constants ¶
const ( PartParameters = "parameters" PartRequestBody = "request_body" PartResponses = "responses" )
The parts of an operation a change report names as changed.
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).
const ( TriggerSchedule = "schedule" TriggerManual = "manual" )
Triggers of a check.
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).
const ( WarningDeprecation = "deprecation" WarningSunset = "sunset" WarningRemoved = "removed" )
Warning kinds (#2486).
const LockKey int64 = 4713210231
LockKey is the advisory lock a pass holds, so one replica checks at a time.
const SettingsSection = "api_changes"
SettingsSection is the platform_settings section holding where change reports and upstream warnings are sent.
Variables ¶
var ErrNoChange = errors.New("apichange: no such change")
ErrNoChange is a change id that names no change of the spec.
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.
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.
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 ¶
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 ¶
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.
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 ¶
NewCallers wraps inner.
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 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.
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 ¶
Loop checks every spec whose scheduled check has come (#2483).
func (*Loop) RunOnce ¶
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.
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 ¶
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) Check ¶
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.
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 ¶
Compare reports what next changed from prev. Both are OpenAPI documents, the effective content a spec serves; either failing to parse is an error.
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 ¶
ReadSettings returns the stored settings, the defaults when none are.
type Store ¶
Store is the PostgreSQL store of watches, changes, warnings and callers.
func (Store) AddChange ¶
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) ListChanges ¶
ListChanges returns a spec's changes, newest first, at most limit.
func (Store) PendingFor ¶
PendingFor reports which of a catalog's specs hold a change for review.
func (Store) RecordCheck ¶
RecordCheck stamps a check on the spec's watch.
type Usage ¶
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.
type WarningNotifier ¶
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.