approval

package
v1.155.0 Latest Latest
Warning

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

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

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

View Source
const (
	SubjectScriptVersion = "script_version"
	SubjectSiteRelease   = "site_release"
	PurposeFormPublic    = "form_public"
	PurposeSitePromote   = "site_promote"
)

The subject kinds and purposes a request has.

View Source
const (
	StatusPending   = "pending"
	StatusApproved  = "approved"
	StatusDenied    = "denied"
	StatusWithdrawn = "withdrawn"
)

The statuses a request moves through. A request is decided once.

View Source
const (
	DecisionApprove = "approve"
	DecisionDeny    = "deny"
)

The decisions an administrator makes.

View Source
const MaxReason = 2000

MaxReason bounds the reason a requester gives and the comment a decision carries.

Variables

View Source
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 NewID

func NewID() string

NewID is a request id.

func SourceHash

func SourceHash(source string) string

SourceHash is the sha256 a version's source is fixed by.

Types

type Actor

type Actor struct {
	Email   string
	Persona string
	Admin   bool
}

Actor is who is asking.

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
}

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
	Limit         int
}

Filter narrows a listing.

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

func (p *PostgresStore) Decide(ctx context.Context, id string, d Decision) (*Request, error)

Decide records a pending request's decision.

func (*PostgresStore) Get

func (p *PostgresStore) Get(ctx context.Context, id string) (*Request, error)

Get reads one request.

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) List

func (p *PostgresStore) List(ctx context.Context, f Filter) ([]Request, error)

List reads requests newest first.

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 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"`
	// SiteName is the site the release 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"`
}

Request is one request for a decision.

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
}

Service is the queue's operations.

func (*Service) Approved

func (s *Service) Approved(ctx context.Context, scriptID, purpose string) int

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) Get

func (s *Service) Get(ctx context.Context, actor Actor, id string) (*Request, error)

Get is one request actor may read.

func (*Service) List

func (s *Service) List(ctx context.Context, actor Actor, f Filter) ([]Request, error)

List is the requests actor may read: an administrator's every one, anyone else's their own.

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

func (s *Service) ReleaseApproved(ctx context.Context, releaseID, target, digest string) bool

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) Submit

func (s *Service) Submit(ctx context.Context, actor Actor, in Submit) (*Request, error)

Submit files a request for actor: the script's owner, or an administrator, asking for one of its versions.

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)
}

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 SubmitRelease added in v1.155.0

type SubmitRelease struct {
	ReleaseID string
	Site      string
	Number    int
	Target    string
	Digest    string
	Reason    string
}

SubmitRelease names the site release a promotion waits on.

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.

Jump to

Keyboard shortcuts

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