sitesvc

package
v1.166.2 Latest Latest
Warning

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

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

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

View Source
const (
	StatusPromoted         = "promoted"
	StatusAwaitingApproval = "awaiting_approval"
)

The statuses a promotion answers with.

View Source
const DefaultTreeLimit = 1000

DefaultTreeLimit is how many files a listing returns unless asked for fewer.

View Source
const StatusDone = "done"

StatusDone is a change that took effect.

Variables

View Source
var ErrNoFolder = errors.New("no such folder")

ErrNoFolder is a folder the caller cannot read or the library does not hold.

View Source
var ErrStopped = errors.New("stopped")

ErrStopped is what a copy returns when it was asked to stop.

Functions

func CleanPath

func CleanPath(name string) (string, error)

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 Digest

func Digest(files []site.File) string

Digest fixes a file set: every path and content digest, in path order.

func GrantOpens added in v1.166.1

func GrantOpens(actor Actor, a *site.Access) bool

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

func ObjectKey(siteID string, f site.File, encoding string) string

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

type ApprovalRequest = approval.Request

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

type CopyResult struct {
	Files     []InputFile
	Pages     int
	Redirects int
	Skipped   []site.Skipped
}

CopyResult is what a copy of a site brought across.

type CopyStats added in v1.156.0

type CopyStats struct {
	Pages     int
	Known     int
	Bytes     int64
	Redirects int
	Skipped   int
}

CopyStats is how far a copy has got.

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 FileText added in v1.157.0

type FileText struct {
	Environment string
	Release     int
	Path        string
	ContentType string
	Body        string
}

FileText is one file as an environment serves it.

type GrantRequest added in v1.158.0

type GrantRequest struct {
	Email        string
	Persona      string
	Level        string
	Environments []string
}

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 InputFile

type InputFile struct {
	Path string
	Body []byte
	// contains filtered or unexported fields
}

InputFile is one file a publish was handed.

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

type MediaFolders interface {
	CheckFolder(ctx context.Context, m site.Mount) error
}

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

type PromoteRequest struct {
	Site    string
	From    string
	To      string
	Release int
	Reason  string
}

PromoteRequest is one promotion: the release an environment serves, or one named by number, moved to another environment.

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

type RefusedError struct {
	Msg string
	Err error
}

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

func (s *Service) ActiveJobs(ctx context.Context, ref string) ([]site.Job, error)

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

func (s *Service) Address(ctx context.Context, st *site.Site, environment string) string

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

func (s *Service) CheckNewEnvironment(ctx context.Context, st *site.Site, name string) error

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

func (s *Service) Compare(ctx context.Context, ref string, from, to int) (*Comparison, error)

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

func (s *Service) Delete(ctx context.Context, actor Actor, ref string) error

Delete removes a site. Administrators only: a site can hold live domains.

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

func (s *Service) EnvironmentOwner(ctx context.Context, ref, environment string) (string, error)

EnvironmentOwner is the owner of the site holding the environment, for an application adding the environment as a part.

func (*Service) Find

func (s *Service) Find(ctx context.Context, ref string) (*site.Site, error)

Find reads a site by name or id.

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

func (s *Service) Grants(ctx context.Context, actor Actor, ref string) ([]site.Grant, error)

Grants lists who has access to a site, for someone who manages it.

func (*Service) JobOf added in v1.156.0

func (s *Service) JobOf(ctx context.Context, ref, id string) (*site.Job, error)

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) MayEdit added in v1.162.0

func (s *Service) MayEdit(ctx context.Context, actor Actor, st *site.Site) error

MayEdit refuses anyone who does not manage the site.

func (*Service) MayPublish added in v1.156.0

func (s *Service) MayPublish(ctx context.Context, actor Actor, ref, environment string) error

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

func (s *Service) PatchFile(ctx context.Context, actor Actor, req PatchRequest) (*Patched, error)

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

func (s *Service) Promote(ctx context.Context, actor Actor, req PromoteRequest) (*Promoted, error)

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

func (s *Service) Publish(ctx context.Context, actor Actor, req PublishRequest) (*Published, error)

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

func (s *Service) ReadFile(ctx context.Context, actor Actor, ref site.Ref) (*FileText, error)

ReadFile is one text file of what an environment serves.

func (*Service) ReleaseExists

func (s *Service) ReleaseExists(ctx context.Context, ref string, number int) bool

ReleaseExists reports whether a site has the numbered release.

func (*Service) RemoveDomain

func (s *Service) RemoveDomain(ctx context.Context, actor Actor, hostname string) error

RemoveDomain stops routing a hostname.

func (*Service) Revoke added in v1.156.0

func (s *Service) Revoke(ctx context.Context, actor Actor, ref, email, persona string) error

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

func (s *Service) StartCopy(ctx context.Context, actor Actor, in CopyJob) (*site.Job, error)

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

func (s *Service) StartPublish(ctx context.Context, actor Actor, in PublishJob) (*site.Job, error)

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

func (s *Service) StepRelease(ctx context.Context, ref, environment string) (int, error)

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.

func (*Service) StopJob added in v1.156.0

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

StopJob asks a copy to stop.

func (*Service) Tree added in v1.157.0

func (s *Service) Tree(ctx context.Context, actor Actor, ref site.Ref, offset, limit int) (*TreeListing, error)

Tree lists the files a tree or folder reference names, including the _redirects file when the release has a redirect map.

func (*Service) Update

func (s *Service) Update(ctx context.Context, actor Actor, ref string, u UpdateRequest) (*site.Site, error)

Update changes a site's record: the description and the owner, which are the owner's and administrators'.

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.

type UpdateRequest added in v1.156.0

type UpdateRequest struct {
	Description *string
	Owner       *string
	// Media, when set, makes the site's mounts exactly these (#2591).
	Media *[]site.Mount
}

UpdateRequest is a change to a site's record; a nil field is left alone.

Jump to

Keyboard shortcuts

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