Documentation
¶
Overview ¶
Package sitesvc is what can be done to a site (#2518): the one service the manage_site tool and an application's release use. It decides who may do what, writes a release's files once under their own prefix, and moves an environment's pointer for a promote or a rollback, which copies nothing.
Index ¶
- Constants
- Variables
- func CleanPath(name string) (string, error)
- func Digest(files []site.File) string
- func GrantOpens(actor Actor, a *site.Access) bool
- func ObjectKey(siteID string, f site.File, encoding string) string
- type Actor
- type Applications
- type ApprovalRequest
- type Approvals
- type Comparison
- type CopyJob
- type CopyResult
- type CopyStats
- type Diffed
- type DomainRequest
- type DomainResult
- type EnvironmentChange
- type EnvironmentResult
- type FileMatches
- type FileText
- type GrantRequest
- type InputFile
- type Invalidate
- type MediaFolders
- type MediaStore
- type Objects
- type PatchRequest
- type Patched
- type Permissions
- type PromoteRequest
- type Promoted
- type PublishJob
- type PublishRequest
- type Published
- type RefusedError
- type Service
- func (s *Service) ActiveJobs(ctx context.Context, ref string) ([]site.Job, error)
- func (s *Service) AddDomain(ctx context.Context, actor Actor, req DomainRequest) (*DomainResult, error)
- func (s *Service) Address(ctx context.Context, st *site.Site, environment string) string
- func (s *Service) Addressing() site.Addressing
- func (s *Service) ApplyPin(ctx context.Context, actorEmail, siteRef, environment string, number int) error
- func (s *Service) CheckNewEnvironment(ctx context.Context, st *site.Site, name string) error
- func (s *Service) Compare(ctx context.Context, ref string, from, to int) (*Comparison, error)
- func (s *Service) Create(ctx context.Context, actor Actor, name, description string) (*site.Site, error)
- func (s *Service) Delete(ctx context.Context, actor Actor, ref string) error
- func (s *Service) Diff(ctx context.Context, actor Actor, ref site.Ref, from, to int) (*Diffed, error)
- func (s *Service) EnvironmentOwner(ctx context.Context, ref, environment string) (string, error)
- func (s *Service) Find(ctx context.Context, ref string) (*site.Site, error)
- func (s *Service) Grant(ctx context.Context, actor Actor, ref string, req GrantRequest) (*site.Grant, error)
- func (s *Service) Grants(ctx context.Context, actor Actor, ref string) ([]site.Grant, error)
- func (s *Service) JobOf(ctx context.Context, ref, id string) (*site.Job, error)
- func (s *Service) LocateTree(ctx context.Context, actor Actor, ref site.Ref, q textpatch.LocateQuery) (*TreeMatches, error)
- func (s *Service) MayEdit(ctx context.Context, actor Actor, st *site.Site) error
- func (s *Service) MayPublish(ctx context.Context, actor Actor, ref, environment string) error
- func (s *Service) OpenableEnvironments(ctx context.Context, actor Actor, st *site.Site) ([]site.Environment, error)
- func (s *Service) PatchFile(ctx context.Context, actor Actor, req PatchRequest) (*Patched, error)
- func (s *Service) PermissionsOf(ctx context.Context, actor Actor, st *site.Site) (Permissions, error)
- func (s *Service) Promote(ctx context.Context, actor Actor, req PromoteRequest) (*Promoted, error)
- func (s *Service) Publish(ctx context.Context, actor Actor, req PublishRequest) (*Published, error)
- func (s *Service) ReadFile(ctx context.Context, actor Actor, ref site.Ref) (*FileText, error)
- func (s *Service) ReleaseExists(ctx context.Context, ref string, number int) bool
- func (s *Service) RemoveDomain(ctx context.Context, actor Actor, hostname string) error
- func (s *Service) Revoke(ctx context.Context, actor Actor, ref, email, persona string) error
- func (s *Service) Rollback(ctx context.Context, actor Actor, ref, environment string, to int) (*Promoted, error)
- func (s *Service) SetDomainAccess(ctx context.Context, actor Actor, hostname string, public bool, reason string) (*DomainResult, error)
- func (s *Service) SetEnvironment(ctx context.Context, actor Actor, ref, name string, c EnvironmentChange) (*EnvironmentResult, error)
- func (s *Service) SetMainEnvironment(ctx context.Context, actor Actor, ref, env string) (*site.Site, error)
- func (s *Service) SiteEnvironments(ctx context.Context) ([]application.SiteEnvironment, error)
- func (s *Service) StartCopy(ctx context.Context, actor Actor, in CopyJob) (*site.Job, error)
- func (s *Service) StartPublish(ctx context.Context, actor Actor, in PublishJob) (*site.Job, error)
- func (s *Service) StepRelease(ctx context.Context, ref, environment string) (int, error)
- func (s *Service) StopJob(ctx context.Context, actor Actor, ref, id string) error
- func (s *Service) Tree(ctx context.Context, actor Actor, ref site.Ref, offset, limit int) (*TreeListing, error)
- func (s *Service) Update(ctx context.Context, actor Actor, ref string, u UpdateRequest) (*site.Site, error)
- type TreeListing
- type TreeMatches
- type UpdateRequest
Constants ¶
const ( StatusPromoted = "promoted" StatusAwaitingApproval = "awaiting_approval" )
The statuses a promotion answers with.
const DefaultTreeLimit = 1000
DefaultTreeLimit is how many files a listing returns unless asked for fewer.
const StatusDone = "done"
StatusDone is a change that took effect.
Variables ¶
var ErrNoFolder = errors.New("no such folder")
ErrNoFolder is a folder the caller cannot read or the library does not hold.
var ErrStopped = errors.New("stopped")
ErrStopped is what a copy returns when it was asked to stop.
Functions ¶
func CleanPath ¶
CleanPath is a file's path as the release keys it, or a refusal: relative, forward-slashed, with no parent reference, no control character, and no dotted segment other than .well-known, so a source tree's .env or .git never becomes a public URL.
func GrantOpens ¶ added in v1.166.1
GrantOpens reports whether a grant opens an environment for the actor: one to their persona, or one to their email once it is verified. It is the part of the access check a grant decides, which the list of environments shared with a person reads too (#2718).
func ObjectKey ¶
ObjectKey is where one form of a file is stored: "" for the file itself, "gz" or "br" for a compressed variant. Objects are kept by digest, per site, so a release that keeps a file costs nothing and a caller's path never reaches a key; a file written before that stays under its release's prefix.
Types ¶
type Actor ¶
type Actor struct {
Email string
Persona string
Admin bool
// EmailUnverified is true when the identity provider said in so many words
// that it has not verified Email, which then matches no owner or grant.
EmailUnverified bool
// Agent, Decided and DecidedBy: an agent's moves wait on a person (#2643, siteenv).
Agent bool
Decided string
DecidedBy string
}
Actor is who is acting.
type Applications ¶
type Applications interface {
GetByName(ctx context.Context, name string) (*application.Application, error)
}
Applications finds the application a hostname maps to.
type ApprovalRequest ¶ added in v1.158.0
ApprovalRequest is the request a change waits on in Approvals, named here so the layers above read it through the service.
type Approvals ¶
type Approvals interface {
SubmitRelease(ctx context.Context, actor approval.Actor, in approval.SubmitRelease) (*approval.Request, error)
ReleaseApproved(ctx context.Context, releaseID, target, digest string) bool
RecordReleaseSelfApproval(ctx context.Context, actor approval.Actor, in approval.SubmitRelease) error
// SubmitEnvironment files a request to make an environment public.
SubmitEnvironment(ctx context.Context, actor approval.Actor, in approval.SubmitEnvironment) (*approval.Request, error)
// EnvironmentApproved reports whether making an environment public is
// approved for the access it was asked against.
EnvironmentApproved(ctx context.Context, siteID, target, stamp string) bool
}
Approvals is the queue a promotion that requires approval goes through.
type Comparison ¶ added in v1.156.0
type Comparison struct {
From int `json:"from" example:"9"`
To int `json:"to" example:"11"`
Changed []string `json:"changed"`
Added []string `json:"added"`
Removed []string `json:"removed"`
RedirectsAdded []site.Redirect `json:"redirects_added"`
RedirectsRemoved []site.Redirect `json:"redirects_removed"`
}
Comparison is what moving from one release to another changes, read from each release's file digests.
type CopyJob ¶ added in v1.156.0
type CopyJob struct {
Site string
Environment string
Source string
Note string
Copy func(ctx context.Context, progress func(CopyStats) bool) (*CopyResult, error)
}
CopyJob copies an existing site in the background. Copy reports progress and is told to stop when its Progress returns true.
type CopyResult ¶ added in v1.156.0
CopyResult is what a copy of a site brought across.
type Diffed ¶ added in v1.157.0
type Diffed struct {
From, To int
Diff string
Comparison *Comparison
}
Diffed compares two releases: a unified diff of one file, or the paths that differ across a whole tree.
type DomainRequest ¶
type DomainRequest struct {
Hostname string
Site string
Environment string
// Public makes the domain answer anyone (#2619). It is the owner's or an
// administrator's, and where the environment requires approval someone
// who is not an administrator adds the domain private and the request
// goes to Approvals.
Public bool
// Reason goes with a request to make the domain public.
Reason string
// RequiresApproval, Keep and Place are applied to the environment the
// domain names, whether the request creates it or it exists: whether it
// requires approval, the release limit (nil leaves it, #2602) and where
// it goes (#2617). A field left nil is left alone.
RequiresApproval *bool
Keep *int
Place *site.Place
Application string
}
DomainRequest maps one hostname.
type DomainResult ¶ added in v1.159.0
type DomainResult struct {
*site.Domain
// Status is StatusDone, or StatusAwaitingApproval when making the domain
// public waits on Approvals; the domain is private meanwhile.
Status string `json:"status"`
Approval *approval.Request `json:"approval,omitempty"`
}
DomainResult is what adding a domain, or changing its access, did: the domain as it now stands, and whether making it public waits on Approvals.
type EnvironmentChange ¶ added in v1.158.0
type EnvironmentChange struct {
RequiresApproval *bool
// Public is refused (#2619): public is a setting of a domain. It is read
// only so the refusal can say so.
Public *bool
InternalView *bool
// AgentsMayPromote is #2643's setting, checked by siteenv.
AgentsMayPromote *bool
// Keep sets how many releases the environment keeps (0 keeps every one),
// and KeepDefault returns it to the deployment's default (#2602).
Keep *int
KeepDefault bool
// Place is where a new environment goes, or where an existing one moves
// to (#2617).
Place *site.Place
}
EnvironmentChange creates an environment or changes it; a nil field is left alone.
type EnvironmentResult ¶ added in v1.158.0
type EnvironmentResult struct {
Site *site.Site `json:"site"`
// Status is StatusDone.
Status string `json:"status"`
// Note says the old environment name was read as dev.
Note string `json:"note,omitempty"`
}
EnvironmentResult is what setting an environment did.
type FileMatches ¶ added in v1.157.0
type FileMatches struct {
Path string `json:"path"`
Count int `json:"count"`
Matches []textpatch.Match `json:"matches"`
Truncated bool `json:"truncated,omitempty"`
}
FileMatches is what a search found in one file.
type GrantRequest ¶ added in v1.158.0
GrantRequest gives a person, by email, or a persona access. A persona is always given view. Environments narrow a view grant to those private environments; none is every private environment.
type Invalidate ¶
type Invalidate func(hostOrSite string)
Invalidate tells this replica's gateway a route changed; nil does nothing.
type MediaFolders ¶ added in v1.159.0
MediaFolders checks a folder a caller mounts, reading the caller from ctx.
type MediaStore ¶ added in v1.159.0
type MediaStore interface {
SetMedia(ctx context.Context, siteID string, mounts []site.Mount, actor string) error
}
MediaStore keeps a site's mounts.
type Objects ¶
type Objects interface {
PutObject(ctx context.Context, bucket, key string, data []byte, contentType string) error
GetObject(ctx context.Context, bucket, key string) ([]byte, string, error)
DeleteObject(ctx context.Context, bucket, key string) error
}
Objects stores a release's files.
type PatchRequest ¶ added in v1.157.0
type PatchRequest struct {
Ref site.Ref
// Base is the release the edit was made against, 0 for whichever the
// environment serves now.
Base int
Edits []textpatch.Edit
Summary string
DryRun bool
}
PatchRequest is an anchored edit of one file.
type Patched ¶ added in v1.157.0
type Patched struct {
Result textpatch.Result
Path string
ContentType string
Release int
Address string
// Unchanged is true when the edits left the file as it was, so no release
// was written.
Unchanged bool
// OutputsChanged is how many served files a dry run would change.
OutputsChanged int
}
Patched is what a patch did.
type Permissions ¶ added in v1.156.0
type Permissions struct {
// Manage publishes, promotes, rolls back, adds domains and shares view access.
Manage bool `json:"manage"`
// Own edits the description, moves the owner, and adds or removes the
// people who manage.
Own bool `json:"own"`
// Delete removes the site.
Delete bool `json:"delete"`
}
Permissions is what one person may do to one site.
type PromoteRequest ¶
PromoteRequest is one promotion: the release an environment serves, or one named by number, moved to another environment.
type Promoted ¶
type Promoted struct {
Environment string `json:"environment"`
Release int `json:"release"`
URL string `json:"address,omitempty"`
Status string `json:"status" example:"promoted"`
Approval *approval.Request `json:"approval,omitempty"`
// DecidedBy is whose decision carried an agent's move out (#2643).
DecidedBy string `json:"decided_by,omitempty"`
}
Promoted is what a promotion answers: the move, or the request it waits on.
type PublishJob ¶ added in v1.156.0
type PublishJob struct {
Site string
Environment string
Source string
Note string
Read func(ctx context.Context) ([]InputFile, error)
}
PublishJob is a publish to run in the background. Read supplies the files and runs as the caller: ctx carries who is asking.
type PublishRequest ¶
type PublishRequest struct {
Site string
Environment string
Source string
Note string
Files []InputFile
// Base, when not 0, makes Files an overlay on that release, which must be
// the one the default environment serves. Files it does not name carry over.
Base int
// Remove is the paths taken out of Base.
Remove []string
// DryRun does everything but store a file or write a release.
DryRun bool
// Progress is told each time a file is stored, and Phase when the work
// moves on; nil reports nothing.
Progress func(done, total int)
Phase func(phase string)
}
PublishRequest is one publish.
type Published ¶
type Published struct {
Release *site.Release `json:"release"`
Env string `json:"environment"`
// Address is where the environment answers, "" before it has one.
Address string `json:"address"`
// Unchanged is true when the overlay changed nothing: no release was
// written, and Release is the one the environment already serves.
Unchanged bool `json:"unchanged,omitempty"`
// OutputsChanged is how many served files a dry run would add, change or
// remove.
OutputsChanged int `json:"outputs_changed,omitempty"`
}
Published is what a publish answers.
type RefusedError ¶
RefusedError is a command refused for a reason the caller can act on. Err, when set, is the error it stands for, read by identity.
func (*RefusedError) Error ¶
func (e *RefusedError) Error() string
func (*RefusedError) Unwrap ¶ added in v1.159.0
func (e *RefusedError) Unwrap() error
Unwrap is the error the refusal stands for, nil for none.
type Service ¶
type Service struct {
Store site.Store
Objects Objects
Bucket string
Config siteconfig.Config
// Live, when set, is the configuration in force and Config only its seed.
Live *siteconfig.Live
Apps Applications
Approvals Approvals
// CheckPromote refuses a promotion of a release into an environment the
// release cannot serve (sitecontract.Check, #2679); nil refuses none.
CheckPromote func(ctx context.Context, st *site.Site, env string, rel *site.Release) error
// External reports whether the person at an address is external; nil is
// no one.
External func(ctx context.Context, email string) bool
// PersonaExists reports whether a persona a grant names exists; nil takes
// any name.
PersonaExists func(name string) bool
// MediaFolders checks a folder a site mounts and MediaStore keeps the
// mounts (#2591); either nil refuses every mount.
MediaFolders MediaFolders
MediaStore MediaStore
// PortalHost is the portal's hostname, which no domain may claim.
PortalHost string
// ReservedHosts are the other hostnames the platform answers on itself.
ReservedHosts []string
// CookieDomain is the session cookie's Domain, under which no served
// origin may sit.
CookieDomain string
// PublicScheme and PublicPort are what an address is written with.
PublicScheme, PublicPort string
Invalidate Invalidate
// contains filtered or unexported fields
}
Service carries out the commands.
func (*Service) ActiveJobs ¶ added in v1.156.0
ActiveJobs lists the site's jobs still running.
func (*Service) AddDomain ¶
func (s *Service) AddDomain(ctx context.Context, actor Actor, req DomainRequest) (*DomainResult, error)
AddDomain maps a hostname to one of a site's environments, creating the environment when it does not exist, or to an application. It routes as soon as it is added, private unless public is asked for; the platform does not check who owns the name. A site's owner and the people who manage it add its domains, and only an administrator maps one to an application.
func (*Service) Address ¶ added in v1.156.0
Address is where people reach an environment: the first of its domains, otherwise its address on the pages domain, "" for none.
func (*Service) Addressing ¶ added in v1.159.0
func (s *Service) Addressing() site.Addressing
Addressing is where the deployment's sites answer, as the configuration in force names it.
func (*Service) ApplyPin ¶
func (s *Service) ApplyPin(ctx context.Context, actorEmail, siteRef, environment string, number int) error
ApplyPin points an environment at the release an application's release or rollback pins. An application release is an administrator's act, so it needs no separate approval.
func (*Service) CheckNewEnvironment ¶ added in v1.162.0
CheckNewEnvironment refuses a name that is not one, whose address could not be one DNS label, or whose address an application holds.
func (*Service) Compare ¶ added in v1.156.0
Compare says what serving release to changes for someone served release from; from 0 is an environment with no release yet.
func (*Service) Create ¶
func (s *Service) Create(ctx context.Context, actor Actor, name, description string) (*site.Site, error)
Create makes a site with dev, its working copy, and prod, holding the main address (#2617); its creator is its owner. A site and an application share the name space of the pages domain, so a name one of them holds is refused, and so is a site whose dev or prod address could not be one DNS label.
func (*Service) Diff ¶ added in v1.157.0
func (s *Service) Diff(ctx context.Context, actor Actor, ref site.Ref, from, to int) (*Diffed, error)
Diff compares two releases of a file or a tree. Earlier releases can hold what a later one took out, so it is for the people who manage the site. to defaults to the environment's release and from to the release to was derived from.
func (*Service) EnvironmentOwner ¶
EnvironmentOwner is the owner of the site holding the environment, for an application adding the environment as a part.
func (*Service) Grant ¶ added in v1.156.0
func (s *Service) Grant(ctx context.Context, actor Actor, ref string, req GrantRequest) (*site.Grant, error)
Grant gives a person or a persona access. The people who manage a site share view access; only its owner and administrators add or change someone who manages it, and that person must be internal.
func (*Service) Grants ¶ added in v1.156.0
Grants lists who has access to a site, for someone who manages it.
func (*Service) JobOf ¶ added in v1.156.0
JobOf reads a job of the site, reading one nobody has reported on for a while as failed.
func (*Service) LocateTree ¶ added in v1.157.0
func (s *Service) LocateTree(ctx context.Context, actor Actor, ref site.Ref, q textpatch.LocateQuery) (*TreeMatches, error)
LocateTree searches every text file a tree or folder reference names. It takes a literal or a pattern: a section or selector means nothing across files of different kinds.
func (*Service) MayPublish ¶ added in v1.156.0
MayPublish refuses a caller who could not publish to the environment, so that a copy fetches nothing on their behalf before being refused.
func (*Service) OpenableEnvironments ¶ added in v1.158.0
func (s *Service) OpenableEnvironments(ctx context.Context, actor Actor, st *site.Site) ([]site.Environment, error)
OpenableEnvironments is the environments of a site the actor can open: each one with a public domain, which anyone opens there (#2619), and each other one the access check opens for them. It is what someone who does not manage the site is shown.
func (*Service) PatchFile ¶ added in v1.157.0
PatchFile applies anchored edits to one file and writes the result as a new release derived from the current one, moving the environment to it. It is the one way an edit reaches a site: nothing is written unless every edit resolves.
func (*Service) PermissionsOf ¶ added in v1.156.0
func (s *Service) PermissionsOf(ctx context.Context, actor Actor, st *site.Site) (Permissions, error)
PermissionsOf is what actor may do to st.
func (*Service) Promote ¶
Promote points an environment at the release the environment immediately before it serves (#2617): a release moves one environment at a time, from dev to prod. Where the target requires approval, an administrator's promotion records its own approval; anyone else's files a request and is carried out when they promote again after it is approved. An approval names the release's manifest digest.
func (*Service) Publish ¶
Publish writes a new release and points the environment at it. An environment that requires approval is reached by promote, never by publish.
func (*Service) ReadFile ¶ added in v1.157.0
ReadFile is one text file of what an environment serves.
func (*Service) ReleaseExists ¶
ReleaseExists reports whether a site has the numbered release.
func (*Service) RemoveDomain ¶
RemoveDomain stops routing a hostname.
func (*Service) Revoke ¶ added in v1.156.0
Revoke takes access away from a person by email or, with email "", from a persona; it applies on their next request.
func (*Service) Rollback ¶
func (s *Service) Rollback(ctx context.Context, actor Actor, ref, environment string, to int) (*Promoted, error)
Rollback repoints an environment at an earlier release it served, the one before the current when to is 0. A release the environment served has been through whatever the environment requires, so it needs no new approval; a release it never served is reached by promote.
func (*Service) SetDomainAccess ¶ added in v1.159.0
func (s *Service) SetDomainAccess(ctx context.Context, actor Actor, hostname string, public bool, reason string) (*DomainResult, error)
SetDomainAccess makes a site's domain public or private (#2619). Making it public names that one domain and is the owner's or an administrator's; where the environment requires approval, someone who is not an administrator files a request and the domain opens when they ask again after it is approved. Anyone who manages the site makes a domain private.
func (*Service) SetEnvironment ¶
func (s *Service) SetEnvironment(ctx context.Context, actor Actor, ref, name string, c EnvironmentChange) (*EnvironmentResult, error)
SetEnvironment adds an environment or changes its settings or its place. A new environment is placed between dev and prod: where the caller says, or, when there is only one such place, there. dev never requires approval, and dev and prod never move. Taking the approval rule off is an administrator's, and so is moving an environment forward past one that requires approval.
func (*Service) SetMainEnvironment ¶ added in v1.158.0
func (s *Service) SetMainEnvironment(ctx context.Context, actor Actor, ref, env string) (*site.Site, error)
SetMainEnvironment gives the site's main address to an environment, or to none with env "". It changes what people reach at the site's main address, so it is the owner's or an administrator's.
func (*Service) SiteEnvironments ¶ added in v1.159.0
func (s *Service) SiteEnvironments(ctx context.Context) ([]application.SiteEnvironment, error)
SiteEnvironments is every environment of every site, for an application's search for parts to add, which chooses among them by its own rule (#2613).
func (*Service) StartCopy ¶ added in v1.156.0
StartCopy checks the caller may publish, records the job, and copies the site apart from the request.
func (*Service) StartPublish ¶ added in v1.156.0
StartPublish checks the caller may publish, records the job, and runs it apart from the request: closing the dialog does not stop it.
func (*Service) StepRelease ¶ added in v1.159.0
StepRelease is the release an application release pins a site environment part at (#2617): what the environment before it serves, so an application release moves each environment one step as a promotion does, or the site's newest release for dev, which has nothing before it. 0 is none to pin.
type TreeListing ¶ added in v1.157.0
type TreeListing struct {
Environment string `json:"environment"`
Release int `json:"version"`
Files []site.File `json:"files"`
Total int `json:"total"`
Truncated bool `json:"truncated"`
}
TreeListing is the files under a reference, one page of them.
type TreeMatches ¶ added in v1.157.0
type TreeMatches struct {
Environment string `json:"environment"`
Release int `json:"version"`
Files []FileMatches `json:"files"`
Count int `json:"count"`
FilesScanned int `json:"files_scanned"`
FilesSkipped int `json:"files_skipped"`
Truncated bool `json:"truncated"`
}
TreeMatches is a search across a tree. FilesSkipped counts what was not searched, so a search that could not reach a file does not read as a clean result.