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 Changes
- type Decision
- type Filter
- type Notifier
- type PostgresStore
- func (p *PostgresStore) Decide(ctx context.Context, id string, d Decision) (*Request, 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)
- type RefusedError
- type Request
- type Scripts
- type Service
- 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) Get(ctx context.Context, actor Actor, id string) (*Request, error)
- func (s *Service) List(ctx context.Context, actor Actor, f Filter) ([]Request, error)
- func (s *Service) RecordSelfApproval(ctx context.Context, actor Actor, sc *script.Script, version int) error
- func (s *Service) ResolveScript(ctx context.Context, actor Actor, ref string) (*script.Script, error)
- func (s *Service) Submit(ctx context.Context, actor Actor, in Submit) (*Request, error)
- type Store
- type Submit
Constants ¶
const ( SubjectScriptVersion = "script_version" PurposeFormPublic = "form_public" )
The subject kinds and purposes a request has.
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 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 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 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
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) 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.
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"`
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 ¶
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) List ¶
List is the requests actor may read: an administrator's every one, anyone else's their own.
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.
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)
}
Store keeps requests.
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. |