Documentation
¶
Overview ¶
Package approval is the Approvals queue (#2437): a request for a decision, made by the person who needs it and decided by an administrator. This release carries one subject, a managed script's version, for one purpose: serving a form to callers with no session (#2494). A request names the version by number and fixes it by the sha256 of its source, so what is approved is exactly what the approver was shown, and it says what changed since the version last approved for the same purpose.
Administrators decide. An administrator may decide their own request, and the record says so; nobody else may decide one, their own included.
Index ¶
- Constants
- Variables
- func NewID() string
- func SourceHash(source string) string
- type Actor
- type Allowance
- type AllowanceStore
- type CallRequest
- type CallSubject
- type Changes
- type Decision
- type Filter
- type HandlerAsk
- type HeldCall
- type Notifier
- type PostgresStore
- func (p *PostgresStore) Decide(ctx context.Context, id string, d Decision) (*Request, error)
- func (p *PostgresStore) EnvironmentApproved(ctx context.Context, siteID, target, stamp string) (bool, error)
- func (p *PostgresStore) Get(ctx context.Context, id string) (*Request, error)
- func (p *PostgresStore) Insert(ctx context.Context, r *Request) error
- func (p *PostgresStore) LatestApproved(ctx context.Context, scriptID, purpose string) (*Request, error)
- func (p *PostgresStore) List(ctx context.Context, f Filter) ([]Request, error)
- func (p *PostgresStore) PendingRollup(ctx context.Context, staleBefore time.Time) (QueueRollup, error)
- func (p *PostgresStore) ReleaseApproved(ctx context.Context, releaseID, target, digest string) (bool, error)
- func (p *PostgresStore) Spend(ctx context.Context, requester, connection, operation string) (id string, ok bool, err error)
- type QueueRollup
- type RefusedError
- type Request
- type Ruling
- type RunAs
- type Scripts
- type Service
- func (s *Service) ApproveForHandlers(ctx context.Context, actor Actor, sc *script.Script, version int) error
- func (s *Service) Approved(ctx context.Context, scriptID, purpose string) int
- func (s *Service) Decide(ctx context.Context, actor Actor, id, decision, comment string) (*Request, error)
- func (s *Service) DecideAllowance(ctx context.Context, actor Actor, id string, r Ruling) (*Request, error)
- func (s *Service) EnvironmentApproved(ctx context.Context, siteID, target, stamp string) bool
- func (s *Service) Get(ctx context.Context, actor Actor, id string) (*Request, error)
- func (s *Service) HandlerRunAs(ctx context.Context, scriptID string) (RunAs, bool)
- func (s *Service) HandlerVersionSaved(ctx context.Context, actor Actor, sc *script.Script, version int) error
- func (s *Service) List(ctx context.Context, actor Actor, f Filter) ([]Request, error)
- func (s *Service) PendingHandlerVersion(ctx context.Context, scriptID string) int
- func (s *Service) RecordReleaseSelfApproval(ctx context.Context, actor Actor, in SubmitRelease) error
- func (s *Service) RecordSelfApproval(ctx context.Context, actor Actor, sc *script.Script, version int) error
- func (s *Service) ReleaseApproved(ctx context.Context, releaseID, target, digest string) bool
- func (s *Service) ResolveScript(ctx context.Context, actor Actor, ref string) (*script.Script, error)
- func (s *Service) SpendAllowance(ctx context.Context, requester, connection, operation string) (string, bool)
- func (s *Service) Submit(ctx context.Context, actor Actor, in Submit) (*Request, error)
- func (s *Service) SubmitCall(ctx context.Context, actor Actor, in CallRequest) (*Request, error)
- func (s *Service) SubmitEnvironment(ctx context.Context, actor Actor, in SubmitEnvironment) (*Request, error)
- func (s *Service) SubmitRelease(ctx context.Context, actor Actor, in SubmitRelease) (*Request, error)
- type Store
- type Submit
- type SubmitEnvironment
- type SubmitRelease
Constants ¶
const ( SubjectScriptVersion = "script_version" SubjectSiteRelease = "site_release" // SubjectSiteEnvironment is one environment of a site, by SiteID and // Target (#2604). SubjectSiteEnvironment = "site_environment" PurposeFormPublic = "form_public" PurposeSitePromote = "site_promote" // PurposeSitePublic makes a site environment that requires approval // public; SourceSHA256 is the access it was asked against. PurposeSitePublic = "site_public" // SubjectCall is a held tool call (#2437): approved, it is an allowance // of calls of one operation, for one person, on one connection, until a // deadline. SubjectCall = "call" // PurposeCallAllowance is a call request's purpose. PurposeCallAllowance = "call_allowance" // PurposeCallHandler approves a script version to run as a tool-call // handler (#2436): a policy, transform or watch runs the highest version // approved for it, with the roles of the administrator who approved it. PurposeCallHandler = "call_handler" )
The subject kinds and purposes a request has.
const ( KindCall = "call" KindHandlerVersion = "handler_version" KindForm = "form" KindSite = "site" )
The kinds a list filters requests by.
const ( StatusPending = "pending" StatusApproved = "approved" StatusDenied = "denied" StatusWithdrawn = "withdrawn" )
The statuses a request moves through. A request is decided once.
const ( DecisionApprove = "approve" DecisionDeny = "deny" )
The decisions an administrator makes.
const ( // MaxCalls is the most calls one allowance holds. MaxCalls = 10000 // DefaultAllowance is how long an approved allowance lasts when the // approver sets no deadline. DefaultAllowance = 24 * time.Hour // MaxAllowance is the furthest deadline an approver may set. MaxAllowance = 90 * 24 * time.Hour // Administrators is how a policy names every administrator as its // approver. Administrators = "administrators" )
Bounds on a call request's allowance.
const MaxReason = 2000
MaxReason bounds the reason a requester gives and the comment a decision carries.
Variables ¶
var ( ErrNotFound = errors.New("approval: no such request") ErrNotAllowed = errors.New("approval: not allowed") ErrDecided = errors.New("approval: the request was already decided") ErrPending = errors.New("approval: a request for this version is already waiting") )
Errors a caller reads by identity.
Functions ¶
func SourceHash ¶
SourceHash is the sha256 a version's source is fixed by.
Types ¶
type Actor ¶
type Actor struct {
Email string
Persona string
Admin bool
// Roles are the actor's roles: what a handler version an administrator
// approves runs with.
Roles []string
}
Actor is who is asking.
type Allowance ¶ added in v1.161.0
Allowance is what an approver grants: a number of calls until a deadline. Zero values take what was asked and DefaultAllowance.
type AllowanceStore ¶ added in v1.161.0
type AllowanceStore interface {
// Spend uses one call of the oldest approved allowance requester holds
// for operation on connection that has calls left and has not passed
// its deadline, returning its id; ok is false when none does.
Spend(ctx context.Context, requester, connection, operation string) (id string, ok bool, err error)
}
AllowanceStore spends approved allowances (PostgresStore).
type CallRequest ¶ added in v1.161.0
type CallRequest struct {
Tool string
Connection string
Operation string
// Arguments are the call's arguments as the caller sent them, before
// any stored secret is filled.
Arguments map[string]any
Rendering string
Handlers []HandlerAsk
Approvers []string
Calls int
Reason string
}
CallRequest is a held call to file (#2437): what the platform read of it and what its policies asked.
type CallSubject ¶ added in v1.161.0
type CallSubject struct {
CallTool string `json:"tool,omitempty" example:"api_invoke_endpoint"`
CallConnection string `json:"connection,omitempty" example:"billing-api"`
CallOperation string `json:"operation,omitempty" example:"addSubscribers"`
CallArguments map[string]any `json:"arguments,omitempty"`
// Rendering is the platform's own reading of the call, which the
// approver reads, never only a summary someone wrote.
Rendering string `json:"rendering,omitempty"`
// Handlers are the policies that held the call, with what each said.
Handlers []HandlerAsk `json:"handlers,omitempty"`
// Approvers are the people or personas the policies named; empty is an
// administrator.
Approvers []string `json:"approvers,omitempty"`
CallsAsked int `json:"calls_asked,omitempty"`
CallsApproved int `json:"calls_approved,omitempty"`
CallsUsed int `json:"calls_used,omitempty"`
Until *time.Time `json:"until,omitempty"`
}
CallSubject is a call request's subject (#2437): the call as the caller sent it, frozen when filed, what the platform made of it, the handlers that held it, who may decide it, and the allowance.
type Changes ¶
type Changes struct {
// ApprovedVersion is the version approved before, 0 for none.
ApprovedVersion int `json:"approved_version"`
// Diff is the unified diff of the source from that version, empty for a
// first request; Truncated says it was cut at the bound.
Diff string `json:"diff,omitempty"`
Truncated bool `json:"truncated,omitempty"`
// Added and Removed count the diff's changed lines.
Added int `json:"added"`
Removed int `json:"removed"`
}
Changes is what changed since the version last approved for the same purpose: none approved before is a first request.
type Decision ¶
type Decision struct {
Status string
By string
Comment string
SelfApproved bool
At time.Time
// Roles are the approver's roles, recorded for a handler version.
Roles []string
// CallsApproved and Until are an allowance's count and deadline.
CallsApproved int
Until *time.Time
}
Decision is what an administrator decided about a request.
type Filter ¶
type Filter struct {
// Status is one status, empty for every one.
Status string
// Requester is one requester's requests, empty for everyone's.
Requester string
// ScriptID is one script's requests, empty for every script's.
ScriptID string
// SiteReleaseID is one site release's requests, empty for every one's.
SiteReleaseID string
// SiteID is one site's environment requests, empty for every site's.
SiteID string
// Approver and ApproverPersona widen a requester's listing to the call
// requests whose policies name them, by address or persona.
Approver string
ApproverPersona string
// Kind is one kind of request (call, handler_version, form, site),
// empty for every kind; Purpose one purpose.
Kind string
Purpose string
Limit int
}
Filter narrows a listing.
type HandlerAsk ¶ added in v1.161.0
type HandlerAsk struct {
ID string `json:"id"`
Script string `json:"script"`
Summary string `json:"summary,omitempty"`
}
HandlerAsk is one policy that held a call, and what it said.
type HeldCall ¶ added in v1.161.0
type HeldCall struct {
User, Persona, Tool string
Arguments map[string]any
Calls int
Reason string
}
HeldCall is a call a person was told is held, as manage_approval submit names it: who made it, under which persona, the tool and its arguments as the call was made, how many calls to ask for and why.
type Notifier ¶
type Notifier interface {
Requested(ctx context.Context, r *Request, approvers []string)
Decided(ctx context.Context, r *Request)
}
Notifier tells approvers a request is waiting and a requester how theirs was decided. Its failures are its own: a request stands whether or not the mail went out.
type PostgresStore ¶
type PostgresStore struct {
// contains filtered or unexported fields
}
PostgresStore keeps requests in approval_requests.
func NewPostgresStore ¶
func NewPostgresStore(db *sql.DB) *PostgresStore
NewPostgresStore builds the store over db.
func (*PostgresStore) Decide ¶
Decide records a pending request's decision. A call request's frozen arguments are deleted with it (#2437): the approver read them to decide, the allowance is spent by connection and operation, and the platform's rendering stays as the record of what was asked.
func (*PostgresStore) EnvironmentApproved ¶ added in v1.158.0
func (p *PostgresStore) EnvironmentApproved(ctx context.Context, siteID, target, stamp string) (bool, error)
EnvironmentApproved reports whether making a site environment public is approved for the access stamp the approver was shown.
func (*PostgresStore) Insert ¶
func (p *PostgresStore) Insert(ctx context.Context, r *Request) error
Insert stores a new pending request.
func (*PostgresStore) LatestApproved ¶
func (p *PostgresStore) LatestApproved(ctx context.Context, scriptID, purpose string) (*Request, error)
LatestApproved is the highest version approved for a script and purpose.
func (*PostgresStore) PendingRollup ¶ added in v1.161.0
func (p *PostgresStore) PendingRollup(ctx context.Context, staleBefore time.Time) (QueueRollup, error)
PendingRollup is the approvals queue's rollup (reviewalert.ApprovalSource), staleBefore deciding which requests are stale.
func (*PostgresStore) ReleaseApproved ¶ added in v1.155.0
func (p *PostgresStore) ReleaseApproved(ctx context.Context, releaseID, target, digest string) (bool, error)
ReleaseApproved reports whether a site release is approved for a target at the digest the approver was shown.
type QueueRollup ¶ added in v1.161.0
QueueRollup is the approvals queue as its staleness alert reads it: every pending request, those filed before a time, and when the oldest was filed.
type RefusedError ¶
type RefusedError struct{ Msg string }
RefusedError is a request refused for a reason the caller can act on.
func (*RefusedError) Error ¶
func (e *RefusedError) Error() string
type Request ¶
type Request struct {
ID string `json:"id" example:"apr_0f3c9d2e"`
SubjectKind string `json:"subject_kind" example:"script_version"`
Purpose string `json:"purpose" example:"form_public"`
ScriptID string `json:"script_id"`
ScriptName string `json:"script_name,omitempty" example:"order-intake"`
Version int `json:"version" example:"2"`
SourceSHA256 string `json:"source_sha256"`
RequesterEmail string `json:"requester_email" example:"jane@example.com"`
RequesterPersona string `json:"requester_persona,omitempty"`
Reason string `json:"reason,omitempty"`
Changes Changes `json:"changes"`
// SiteReleaseID and Target name a site release a promotion waits on and
// the environment it would serve (#2518); SourceSHA256 is then the
// release's manifest digest and Version its number.
SiteReleaseID string `json:"site_release_id,omitempty"`
Target string `json:"target,omitempty" example:"prod"`
// SiteID is the site an environment request is about (#2604).
SiteID string `json:"site_id,omitempty"`
// SiteName is the site the release or environment belongs to.
SiteName string `json:"site_name,omitempty" example:"marketing"`
Status string `json:"status" example:"pending"`
DecidedBy string `json:"decided_by,omitempty"`
DecidedAt *time.Time `json:"decided_at,omitempty"`
DecisionComment string `json:"decision_comment,omitempty"`
SelfApproved bool `json:"self_approved"`
CreatedAt time.Time `json:"created_at"`
// Kind is what the request is about: call, handler_version, form or
// site.
Kind string `json:"kind"`
// DecidedRoles are the roles of the administrator who approved a
// handler version, which the handler runs with. They are never shown.
DecidedRoles []string `json:"-"`
CallSubject
}
Request is one request for a decision.
type Ruling ¶ added in v1.161.0
Ruling is one decision on a request: approve or deny, a comment for the requester, and on a call request what an approval grants.
type RunAs ¶ added in v1.161.0
type RunAs struct {
Version int
Approver string
Roles []string
// SelfApproved says the approver saved or bound it themselves.
SelfApproved bool
}
RunAs is what a script's tool-call handlers run (#2436): the highest version approved for call_handler, and the administrator who approved it, whose roles it runs with.
type Scripts ¶
type Scripts interface {
GetByID(ctx context.Context, id string) (*script.Script, error)
GetByName(ctx context.Context, ownerEmail, name string) (*script.Script, error)
GetVersion(ctx context.Context, scriptID string, version int) (*script.Version, error)
}
Scripts reads the scripts and versions a request names.
type Service ¶
type Service struct {
Store Store
Scripts Scripts
// IsForm reports whether a version's source defines a form; a
// form_public request names a form's version.
IsForm func(source string) bool
// Approvers lists the administrators' addresses; nil notifies nobody.
Approvers func(ctx context.Context) []string
// Notifier sends the two notices; nil sends none.
Notifier Notifier
// Now is the clock; nil is time.Now.
Now func() time.Time
// Allowances spends approved call allowances; nil spends none.
Allowances AllowanceStore
}
Service is the queue's operations.
func (*Service) ApproveForHandlers ¶ added in v1.161.0
func (s *Service) ApproveForHandlers(ctx context.Context, actor Actor, sc *script.Script, version int) error
ApproveForHandlers records an administrator's approval of a version of sc for its tool-call handlers (version 0 is the latest), with their roles, marked self-approved: an administrator saving or binding a handler's script approves what they saved or bound. A version already approved, or older than one approved, records nothing.
func (*Service) Approved ¶
Approved is the version approved for a script and purpose, 0 for none. A failure to read is logged and reads as none, which serves nothing publicly.
func (*Service) Decide ¶
func (s *Service) Decide(ctx context.Context, actor Actor, id, decision, comment string) (*Request, error)
Decide records an administrator's decision. A non-administrator is refused whatever the request, their own included; an administrator deciding their own request is recorded as self-approved.
func (*Service) DecideAllowance ¶ added in v1.161.0
func (s *Service) DecideAllowance(ctx context.Context, actor Actor, id string, r Ruling) (*Request, error)
DecideAllowance is Decide with what an approval of a call request grants (#2437): a call request is decided by the approvers its policies named or an administrator, never by its requester unless an administrator; every other request by an administrator.
func (*Service) EnvironmentApproved ¶ added in v1.158.0
EnvironmentApproved reports whether making a site environment public is approved for the stamp. A failure to read is logged and reads as not approved, which makes nothing public.
func (*Service) HandlerRunAs ¶ added in v1.161.0
HandlerRunAs is what sc's tool-call handlers run; ok is false when no version is approved, and then nothing runs. A failure to read is logged and reads as none.
func (*Service) HandlerVersionSaved ¶ added in v1.161.0
func (s *Service) HandlerVersionSaved(ctx context.Context, actor Actor, sc *script.Script, version int) error
HandlerVersionSaved is what a save of a script holding tool-call handlers does: an administrator's save approves the version, anyone else's files a request an administrator decides, and the approved version keeps running meanwhile.
func (*Service) List ¶
List is the requests actor may read: an administrator's every one, anyone else's their own.
func (*Service) PendingHandlerVersion ¶ added in v1.161.0
PendingHandlerVersion is the newest version of a script waiting for an administrator's approval for handlers, 0 for none.
func (*Service) RecordReleaseSelfApproval ¶ added in v1.155.0
func (s *Service) RecordReleaseSelfApproval(ctx context.Context, actor Actor, in SubmitRelease) error
RecordReleaseSelfApproval records an administrator's approval of a release they promote themselves, and the record says it was self-approved.
func (*Service) RecordSelfApproval ¶
func (s *Service) RecordSelfApproval(ctx context.Context, actor Actor, sc *script.Script, version int) error
RecordSelfApproval records an administrator's approval of a version they serve publicly without a request: an administrator binding a form public approves the version served, and the record says it was self-approved. A version already approved records nothing.
func (*Service) ReleaseApproved ¶ added in v1.155.0
ReleaseApproved reports whether a release is approved for a target at the digest. A failure to read is logged and reads as not approved, which promotes nothing.
func (*Service) ResolveScript ¶
func (s *Service) ResolveScript(ctx context.Context, actor Actor, ref string) (*script.Script, error)
ResolveScript reads the script a request names: by id, or by the name of one of the actor's own scripts.
func (*Service) SpendAllowance ¶ added in v1.161.0
func (s *Service) SpendAllowance(ctx context.Context, requester, connection, operation string) (string, bool)
SpendAllowance uses one call of an approved allowance requester holds for operation on connection, returning its id; ok is false when none has a call left before its deadline, and then the policy decides again.
func (*Service) Submit ¶
Submit files a request for actor: the script's owner, or an administrator, asking for one of its versions.
func (*Service) SubmitCall ¶ added in v1.161.0
SubmitCall files a held call for actor, who made it. A request is frozen when filed: nothing changes its arguments afterward.
func (*Service) SubmitEnvironment ¶ added in v1.158.0
func (s *Service) SubmitEnvironment(ctx context.Context, actor Actor, in SubmitEnvironment) (*Request, error)
SubmitEnvironment files a request to make a site environment public, or returns the one already waiting.
func (*Service) SubmitRelease ¶ added in v1.155.0
func (s *Service) SubmitRelease(ctx context.Context, actor Actor, in SubmitRelease) (*Request, error)
SubmitRelease files a request to serve a site release in an environment that requires approval (#2518), or returns the one already waiting.
type Store ¶
type Store interface {
Insert(ctx context.Context, r *Request) error
Get(ctx context.Context, id string) (*Request, error)
List(ctx context.Context, f Filter) ([]Request, error)
// Decide records a pending request's decision, refusing one that is not
// pending with ErrDecided.
Decide(ctx context.Context, id string, d Decision) (*Request, error)
// LatestApproved is the highest version approved for a script and
// purpose, ErrNotFound for none.
LatestApproved(ctx context.Context, scriptID, purpose string) (*Request, error)
// ReleaseApproved reports whether a site release is approved for a
// target at the digest.
ReleaseApproved(ctx context.Context, releaseID, target, digest string) (bool, error)
// EnvironmentApproved reports whether making a site environment public
// is approved for the access stamp.
EnvironmentApproved(ctx context.Context, siteID, target, stamp string) (bool, error)
}
Store keeps requests.
type Submit ¶
type Submit struct {
// Script is the script's id, or the name of one of the requester's own.
Script string
Version int
Purpose string
Reason string
}
Submit is what a requester asks for.
type SubmitEnvironment ¶ added in v1.158.0
type SubmitEnvironment struct {
SiteID string
Site string
Target string
// Stamp is the environment's access when asked: an approval holds for it
// alone.
Stamp string
Reason string
}
SubmitEnvironment asks to make a site environment that requires approval public (#2604).
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apprhttp serves the Approvals queue on the portal (#2437, #2494): a person's own requests, every request for an administrator, filing one and deciding one, through the service manage_approval uses and under its rules.
|
Package apprhttp serves the Approvals queue on the portal (#2437, #2494): a person's own requests, every request for an administrator, filing one and deciding one, through the service manage_approval uses and under its rules. |
|
Package apprtool is the manage_approval MCP tool (#2437, #2494): submitting a request, listing requests and deciding one are commands of one tool, over the service the portal's Approvals page uses.
|
Package apprtool is the manage_approval MCP tool (#2437, #2494): submitting a request, listing requests and deciding one are commands of one tool, over the service the portal's Approvals page uses. |