site

package
v1.163.0 Latest Latest
Warning

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

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

Documentation

Overview

Package site is the record of a static site served by the platform (#2518): a site with named environments, each pointing at one immutable release (a file set whose objects are kept by digest, per site), and the hostnames that route to an environment or to an application's endpoints.

Publishing adds a release, from a complete file set or derived from another release by changing part of it. Promoting and rolling back only move an environment's pointer, so no file is copied and the move takes effect on the next request. The serving layer is internal/site/sitegw, and it is the same layer that serves an application's browser pages (#2517).

Index

Constants

View Source
const (
	// LevelManage publishes, promotes, rolls back, adds domains and shares
	// view access. It cannot add people who manage, change the owner or delete
	// the site.
	LevelManage = "manage"
	// LevelView opens the site's own address and reads the files it serves now
	// through manage_asset. It changes nothing and sees no earlier release.
	LevelView = "view"
)

The levels of access someone can be given to a site.

View Source
const (
	DomainServe    = "serve"
	DomainRedirect = "redirect"
)

The modes of a domain (#2687).

View Source
const (
	StatusOnline   = "online"
	StatusOffline  = "offline"
	StatusRedirect = "redirect"
)

An environment's status (#2631, #2632): what every one of its addresses answers. Online serves the release; offline answers 503 with a message; redirect answers 302 to another https site. Exactly one applies at a time, the release pointer is never touched by any, and dev is always online. The rules a status is checked and answered by are internal/site/sitestatus.

View Source
const (
	ActionOffline  = "offline"
	ActionOnline   = "online"
	ActionRedirect = "redirect"
)

The actions History records for a status change.

View Source
const (
	JobPublish = "publish"
	JobCrawl   = "crawl"
)

The kinds of work that run apart from the request that started them.

View Source
const (
	JobRunning = "running"
	JobDone    = "done"
	JobFailed  = "failed"
	JobStopped = "stopped"
)

The states a job is in.

View Source
const (
	TreeOutput = "output"
	TreeSource = "source"
	TreeRender = "render"
)

The trees of a release. Output is what is served. A rendered release also has its source, which is what is edited, and the record of what each output read.

View Source
const (
	RedirectsFile = "_redirects"
	HeadersFile   = "_headers"
)

Data files are the release files a publish reads into the release rather than serving: the redirect map (_redirects), the headers each path carries (_headers, #2557) and the application contract (_application, #2679). Each reads back as the text it became, so it is edited like any file.

View Source
const (
	ActionPublish     = "publish"
	ActionPromote     = "promote"
	ActionRollback    = "rollback"
	ActionApplication = "application"
	// ActionRename records an environment renamed (#2630).
	ActionRename = "rename"
)

The actions a deployment records.

View Source
const (
	MaxDescription = 2000
	MaxNote        = 2000
)

Limits on a record's fields.

View Source
const (
	DecidedByElicitation = "elicitation"
	DecidedByApproval    = "approval"
	DecidedByEnvironment = "environment_setting"
)

Whose decision carried out a move an agent asked for (#2643).

View Source
const AliasNote = `"default" is now "dev": the working copy every publish and edit lands in. "default" is accepted until the next minor release.`

AliasNote is what a response says when it read the old name.

View Source
const ApplicationFile = "_application"

ApplicationFile is the release file a contract is declared in. It is read at publish and kept on the release, not served.

View Source
const EnvAlias = "default"

EnvAlias is the name EnvDev had before #2604, accepted for one minor release.

View Source
const EnvDev = "dev"

EnvDev is the working copy (#2604): every publish, patch and in-place edit lands here and nowhere else, and people use the environments a release is promoted to. It is always a site's first environment.

View Source
const EnvProd = "prod"

EnvProd is the environment a release reaches last (#2617). A new site starts with it, holding the main address, and it is always a site's last environment.

View Source
const FramingDefault = "frame-ancestors 'self'"

FramingDefault is the policy an answer carries when its release declares no framing rule of its own: only pages of the same origin may frame it.

View Source
const (
	MaxMounts = 20
)

MaxMounts bounds a site's mounts, and maxPathLen a prefix or folder.

View Source
const RefPrefix = "mcp:site:"

RefPrefix starts the reference that names a site's files to the tools that read and edit content.

Variables

View Source
var (
	ErrNotFound      = errors.New("no such site")
	ErrNameTaken     = errors.New("a site with that name exists")
	ErrNoEnvironment = errors.New("the site has no such environment")
	ErrNoRelease     = errors.New("the site has no such release")
	// ErrPruned is a release whose files a sweep removed (#2602): its record
	// stays as history, and nothing can serve, compare or move to it.
	ErrPruned      = errors.New("the release was removed by the release limit")
	ErrNotAllowed  = errors.New("not allowed")
	ErrStale       = errors.New("another change to the environment was recorded first")
	ErrNoDomain    = errors.New("no such domain")
	ErrDomainTaken = errors.New("that hostname is already mapped")
	ErrNoGrant     = errors.New("that person has no access to this site")
	ErrNoJob       = errors.New("no such job")
	// ErrEnvironmentInUse is an environment that cannot be renamed to a name
	// in use, or removed while something is attached to it (#2630); every
	// InUseError is one, saying what.
	ErrEnvironmentInUse = errors.New("environment in use")
)

Errors a caller reads by identity.

Functions

func CanonicalEnvironment added in v1.158.0

func CanonicalEnvironment(name string) (canonical string, aliased bool)

CanonicalEnvironment is name with the old alias read as EnvDev; aliased reports that it was, so the caller can say so.

func EnvLabel added in v1.158.0

func EnvLabel(siteName, env string) string

EnvLabel is the one DNS label <site>--<env> under the pages domain: every environment's own address.

func EnvironmentNameRoom added in v1.162.0

func EnvironmentNameRoom(siteName string) int

EnvironmentNameRoom is how long an environment name a site of this name leaves room for: the longest ValidateEnvironment admits, or less when the site name and "--" leave fewer characters of a label (#2636).

func HeaderNames added in v1.159.0

func HeaderNames() []string

HeaderNames is the headers a release's _headers file may set, as a refusal lists them.

func IsDataFile added in v1.163.0

func IsDataFile(name string) bool

IsDataFile reports whether a release path is one of its data files.

func IsRef added in v1.157.0

func IsRef(s string) bool

IsRef reports whether s is a site reference.

func Matches added in v1.162.1

func Matches(st *Site, domains []Domain, query string) bool

Matches reports whether query names st: a case-insensitive part of its name, description, owner or one of its domains' hostnames (#2658). An empty query names every site.

func NameFrom added in v1.162.0

func NameFrom(input string) string

NameFrom is the site name the text a person typed becomes (#2636): lowercased, every space, underscore and other separator a hyphen, any other character outside a-z and 0-9 dropped, repeated hyphens collapsed, and hyphens at either end removed. "My Website" becomes "my-website". The result is checked with ValidateName like any other name.

func NormalizeEmail added in v1.156.0

func NormalizeEmail(email string) string

NormalizeEmail is the form a grant is stored and matched in.

func NormalizeHost

func NormalizeHost(hostname string) string

NormalizeHost is hostname as a request's Host names it, lowercased, with no port or trailing dot.

func ParseEnvLabel added in v1.158.0

func ParseEnvLabel(label string) (siteName, env string, ok bool)

ParseEnvLabel splits a <site>--<env> label. Neither name may hold "--", so the first is the separator.

func PlaceRefusal added in v1.159.0

func PlaceRefusal(name string, choices []Place) string

PlaceRefusal is the refusal of a new environment whose place is not said when there is more than one: the environments it could go after.

func Placed added in v1.159.0

func Placed(order []string, name string, p *Place) ([]string, error)

Placed is order with name put at p: added when order lacks it, moved when it holds it. A nil p puts a new environment last before prod and leaves an existing one where it is. prod always goes last and dev first, whatever p says.

func RenderHeaders added in v1.159.0

func RenderHeaders(rules []HeaderRule) string

RenderHeaders is a release's header rules as the _headers file that parses back to them, which is what an edit of that file reads.

func RenderRedirects added in v1.157.0

func RenderRedirects(rules []Redirect) string

RenderRedirects is a redirect map as the _redirects file that parses back to it, which is what an edit of that file reads: the rules, without the comments the file they were first parsed from may have held.

func ReservedLabel added in v1.159.0

func ReservedLabel(label string) bool

ReservedLabel reports whether a DNS label has "--" as its 3rd and 4th characters: RFC 5891 §4.2.3.1 reserves that form (the one "xn--" takes), and certificate authorities refuse to issue for it. The composed label of a site whose name is two characters always has it (#2611).

func ReservedLabelNote added in v1.159.0

func ReservedLabelNote(siteName, pagesDomain string) string

ReservedLabelNote is what a site whose composed addresses are reserved labels is told, "" for any other site: why its environments other than the main one have no address on the pages domain, and what to do instead (#2611).

func RollbackTarget added in v1.159.0

func RollbackTarget(env *Environment, history []Deployment, to int, gone map[int]bool) (int, error)

RollbackTarget is the release a rollback returns an environment to: the one named, which the environment must have served and which must not be pruned (ErrPruned), or, with to 0, the newest kept release it served before the current one. A release it never served is reached by promote.

func SameOrUnder

func SameOrUnder(host, domain string) bool

SameOrUnder reports whether host is domain or a name beneath it.

func ValidLevel added in v1.156.0

func ValidLevel(level string) bool

ValidLevel reports whether level is one a grant can hold.

func ValidMode added in v1.163.0

func ValidMode(m string) bool

ValidMode reports whether m is a domain mode.

func ValidateEnvironment

func ValidateEnvironment(name string) error

ValidateEnvironment checks an environment's name.

func ValidateHostname

func ValidateHostname(hostname string) error

ValidateHostname checks a hostname a domain may map: a plain DNS name of at least two labels, with no wildcard or address.

func ValidateLabel added in v1.158.0

func ValidateLabel(siteName, env string) error

ValidateLabel refuses an environment of a site whose address could not be one DNS label: longer than 63, or a form DNS reserves (ReservedLabel).

func ValidateName

func ValidateName(name string) error

ValidateName checks a site's name: its form, and that both environments a new site starts with have an address that is one DNS label (ValidateLabel), which is where its length limit comes from (#2636). A name no environment could be added to is refused here, not when the environment is added.

func ValidateRedirect

func ValidateRedirect(r Redirect) error

ValidateRedirect checks one rule. Status 200 is a rewrite: the path is answered with the file the target names, in place, which is how a single-page application answers its own routes (/* /index.html 200).

Types

type Access added in v1.156.0

type Access struct {
	OwnerEmail string
	// InternalView is the environment's own setting.
	InternalView bool
	// ByEmail is true when a grant to the person's email opens the
	// environment: they manage the site, or a view grant names it.
	ByEmail bool
	// ByPersona is true when a view grant to the person's persona opens it.
	ByPersona bool
}

Access is what the store knows about one person and one environment of a site: read fresh on every request to a private environment, so that removing someone, or changing a persona, takes effect on their next request.

type Addressing added in v1.159.0

type Addressing struct {
	PagesDomain string
	Scheme      string
	Port        string
}

Addressing is where a deployment's sites and page origins answer: the pages domain, and the scheme and port an address is written with. Every address a response names is worked out here, so the portal, manage_site and the application views name the same ones (#2607).

func (Addressing) Address added in v1.159.0

func (a Addressing) Address(st *Site, environment string, domains []Domain) string

Address is where people reach an environment: its primary domain first (#2687), then a public domain mapped to it, then any other domain that serves it, otherwise its address on the pages domain, "" for none (#2658). A domain that redirects is never the address, since it only sends people on. Domains of one kind are taken in hostname order, so the answer does not move between reads.

func (Addressing) AddressNote added in v1.159.0

func (a Addressing) AddressNote(st *Site) string

AddressNote is why a site's environments have no address on the pages domain, "" for a site whose addresses answer or a deployment with no pages domain (#2611).

func (Addressing) Addresses added in v1.159.0

func (a Addressing) Addresses(st *Site, domains []Domain) map[string]string

Addresses is Address for each environment of st, by name.

func (Addressing) Origin added in v1.159.0

func (a Addressing) Origin(host string) string

Origin is the browser origin a hostname answers at.

func (Addressing) OwnAddress added in v1.159.0

func (a Addressing) OwnAddress(st *Site) string

OwnAddress is where a site's main address answers, "" with no pages domain or when the main address is given to no environment.

func (Addressing) PageOrigin added in v1.159.0

func (a Addressing) PageOrigin(applicationName string) string

PageOrigin is where an application's pages answer, "" with no pages domain.

func (Addressing) PagesAddress added in v1.159.0

func (a Addressing) PagesAddress(st *Site, environment string) string

PagesAddress is an environment's address on the pages domain: the main address for the environment holding it, otherwise <site>--<env>; "" with no pages domain, and "" for a <site>--<env> no certificate can be issued for (ReservedLabel, #2611).

func (Addressing) PagesAddresses added in v1.159.0

func (a Addressing) PagesAddresses(st *Site) map[string]string

PagesAddresses is every environment's address on the pages domain, by name.

func (Addressing) ProductionAddress added in v1.162.1

func (a Addressing) ProductionAddress(st *Site, domains []Domain) (address string, more int)

ProductionAddress is the site's address people use: Address for the environment holding the main address, and how many other domains that environment answers at besides the one named (#2658). "" with no main environment.

type ClaimRules added in v1.159.0

type ClaimRules struct {
	PagesDomain  string
	PortalHost   string
	Reserved     []string
	CookieDomain string
}

ClaimRules are what a hostname a domain maps must stay clear of: the pages domain the platform assigns, the hostnames it answers on itself, and the session cookie's domain, under which a served page would receive the portal's session.

type Contract added in v1.163.0

type Contract struct {
	Application string `json:"application"`
	Range       string `json:"contract"`
}

Contract is what a site release's _application file declares (#2679): the application it is a front end of, and the range of that application's contract versions it works with, written as space-separated clauses (">=2 <4", "=3", "2"). A release with no _application file, or one naming no range, works with every contract.

func ParseContract added in v1.163.0

func ParseContract(text string) (*Contract, error)

ParseContract reads an _application file: a JSON object with application and contract (a range). An empty file declares nothing.

func (*Contract) Accepts added in v1.163.0

func (c *Contract) Accepts(v int) bool

Accepts reports whether the release works with the application's contract version v. An application that declares none (0), and a release that names no range, are compatible with everything.

func (*Contract) For added in v1.163.0

func (c *Contract) For(application string) bool

For reports whether the contract is about the named application: a release declaring another application's contract says nothing about this one.

func (*Contract) Render added in v1.163.0

func (c *Contract) Render() string

Render writes the contract back as the _application file it was read from.

type Deployment

type Deployment struct {
	Environment string `json:"environment"`
	Action      string `json:"action" example:"promote"`
	From        int    `json:"from_release"`
	To          int    `json:"to_release"`
	Actor       string `json:"actor"`
	// Detail is what a status change said: the offline message or the
	// redirect target (#2631, #2632); a rename's old name (#2630).
	Detail string `json:"detail,omitempty"`
	// DecidedBy is whose decision carried out a move an agent asked for
	// (#2643), absent for a move a person made.
	DecidedBy string `json:"decided_by,omitempty"`
	// Removed is a move of an environment that was removed (#2630).
	Removed   bool      `json:"removed,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

Deployment is one recorded move of an environment's pointer.

func (Deployment) MovesRelease added in v1.162.0

func (d Deployment) MovesRelease() bool

MovesRelease reports whether the deployment moved the environment's pointer, rather than recording a status change or a rename.

type Domain

type Domain struct {
	Hostname    string `json:"hostname" example:"www.example.com"`
	SiteID      string `json:"site_id,omitempty"`
	Site        string `json:"site,omitempty" example:"marketing"`
	Environment string `json:"environment,omitempty" example:"prod"`
	// ApplicationID and Application name the application whose endpoints the
	// hostname serves.
	ApplicationID string `json:"application_id,omitempty"`
	Application   string `json:"application,omitempty" example:"shop"`
	// Public answers anyone at this hostname (#2619): the one way a site
	// environment opens to someone who has not signed in. A domain is added
	// private unless public is asked for.
	Public bool `json:"public"`
	// AccessChangedAt is when Public last changed; an approval to make the
	// domain public is for the access it was asked against.
	AccessChangedAt time.Time `json:"-"`
	// Primary marks the environment's canonical hostname (#2687): at most one
	// domain of an environment is primary, and the domains that redirect send
	// their visitors to it.
	Primary bool `json:"primary"`
	// Mode is DomainServe (the release is served here) or DomainRedirect
	// (every request is answered with a permanent redirect to the primary).
	Mode string `json:"mode" enums:"serve,redirect"`
	// RedirectsTo is the primary hostname a redirect domain sends visitors to,
	// read with the domain, empty for one that serves.
	RedirectsTo string `json:"redirects_to,omitempty" example:"example.com"`

	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
	// Routing is the Site routing script's status for the hostname (#2659),
	// absent when no script is chosen.
	Routing *Routing `json:"routing,omitempty"`
	// contains filtered or unexported fields
}

Domain maps one hostname to a site environment or to an application. It routes as soon as it is added: the platform does not check DNS, certificates or who owns the name, and whoever runs the deployment adds its ingress.

func (*Domain) Claimable added in v1.159.0

func (d *Domain) Claimable(r ClaimRules) error

Claimable refuses a domain whose hostname is not a plain name, or is one ClaimRules keep clear. The gateway answers an added hostname before the platform's own routes, so a name the platform uses must never be added.

func (*Domain) PublicStamp added in v1.159.0

func (d *Domain) PublicStamp() string

PublicStamp fixes an approval to make the domain public to the access it was asked against: a later change to private and back asks again.

func (*Domain) RedirectRoute added in v1.163.0

func (d *Domain) RedirectRoute() *Route

RedirectRoute is what a redirect domain answers: a permanent redirect to its environment's primary, answered to anyone when the primary is public and to those who may open the environment when it is not. It never reads a release.

func (*Domain) SetPrimaryAccess added in v1.163.0

func (d *Domain) SetPrimaryAccess(public bool)

SetPrimaryAccess records whether the primary a redirect domain points at is public, as the store reads it beside the domain.

type Environment

type Environment struct {
	Name string `json:"name" example:"prod"`
	// Release is the number of the release served, 0 before the first.
	Release int `json:"release" example:"3"`
	// KeepReleases is the environment's own release limit, nil when it
	// follows the deployment's default (#2602).
	KeepReleases *int `json:"-"`
	// Keep is the limit in force: the last Keep distinct releases the
	// environment pointed at are kept, and 0 keeps every one.
	Keep int `json:"keep_releases" example:"50"`
	// KeepDefault is true when Keep is the deployment's default.
	KeepDefault bool `json:"keep_releases_default"`
	// Kept is how many releases the limit keeps for this environment now.
	Kept int `json:"releases_kept" example:"37"`
	// RequiresApproval makes a promotion here, and making one of its domains
	// public, a request in the Approvals queue.
	RequiresApproval bool `json:"requires_approval"`
	// PublicDomains are the domains added to the environment that answer
	// anyone (#2619). Every other address it has, its addresses on the pages
	// domain included, answers only to administrators, the owner, the people
	// who manage the site and whoever it is shared with, after they sign in.
	PublicDomains []string `json:"public_domains"`
	// InternalView opens the environment's private addresses to everyone
	// signed in whose persona is not external: a company intranet.
	InternalView bool `json:"internal_view"`
	// Status is what every address of the environment answers (#2631,
	// #2632): online, offline or redirect.
	Status string `json:"status" example:"online"`
	// StatusMessage is an offline environment's message.
	StatusMessage string `json:"message,omitempty"`
	// TileFailure is why the release the environment serves could not be
	// drawn as its tile, as the tile worker recorded it (#2664); empty while
	// it is drawn, being drawn, or not tried yet.
	TileFailure string `json:"tile_failure,omitempty"`
	// BackAt is when an offline environment's visitors are told it is
	// expected back.
	BackAt *time.Time `json:"back_at,omitempty"`
	// RedirectTo and RedirectKeepPath are a redirecting environment's
	// target, and whether the request's path and query are kept.
	RedirectTo       string     `json:"redirect_to,omitempty"`
	RedirectKeepPath bool       `json:"keep_path"`
	StatusChangedBy  string     `json:"status_changed_by,omitempty"`
	StatusChangedAt  *time.Time `json:"status_changed_at,omitempty"`
	// AgentsMayPromote lets an agent's promote, rollback or public domain
	// here go ahead without a person's decision (#2643). Off by default;
	// only an administrator turns it on.
	AgentsMayPromote bool      `json:"agents_may_promote"`
	UpdatedBy        string    `json:"updated_by,omitempty"`
	UpdatedAt        time.Time `json:"updated_at"`
}

Environment is one named place a release is served from.

func (*Environment) AnswersAnyone added in v1.159.0

func (e *Environment) AnswersAnyone() bool

AnswersAnyone reports whether the environment answers someone who has not signed in at any of its addresses: whether one of its domains is public.

func (*Environment) Online added in v1.162.0

func (e *Environment) Online() bool

Online reports whether the environment serves its release.

func (*Environment) TakesApprovalOff added in v1.159.0

func (e *Environment) TakesApprovalOff(requiresApproval *bool) bool

TakesApprovalOff reports whether setting requiresApproval removes the environment's approval rule.

type EnvironmentSettings added in v1.158.0

type EnvironmentSettings struct {
	RequiresApproval *bool
	InternalView     *bool
	// AgentsMayPromote sets #2643's setting; an administrator's alone.
	AgentsMayPromote *bool
	// Place is where the environment goes in the site's order (#2617): a new
	// one there, an existing one moved there. Nil leaves an existing one
	// where it is, and puts a new one last before prod.
	Place *Place
	// Keep changes the release limit when set; KeepDefault, when Keep is nil,
	// returns it to the deployment's default.
	Keep        *int
	KeepDefault bool
}

EnvironmentSettings is a change to an environment; a nil field is left alone, and a new environment takes false for each.

type EnvironmentStatus added in v1.162.0

type EnvironmentStatus struct {
	Status string
	// Message is what an offline environment's page says, cleaned.
	Message string
	// BackAt is when visitors are told an offline environment is expected
	// back; it is only what they are told (#2631 rule 7).
	BackAt *time.Time
	// RedirectTo is a redirecting environment's target, as checked and
	// written back when it was set.
	RedirectTo string
	// KeepPath appends the request's cleaned path and query to RedirectTo.
	KeepPath bool
}

EnvironmentStatus is what an environment answers in place of its release.

type File

type File struct {
	Path        string `json:"path" example:"css/site.3f2a9c1b.css"`
	SHA256      string `json:"sha256"`
	ContentType string `json:"content_type" example:"text/css"`
	Size        int64  `json:"size"`
	// GzipSize and BrotliSize are the stored variants' sizes, 0 for a file
	// with no such variant.
	GzipSize   int64 `json:"gzip_size,omitempty"`
	BrotliSize int64 `json:"brotli_size,omitempty"`
	// StoredIn is the release whose own prefix holds this file's objects, for
	// a file written before objects were kept by digest; "" for every other.
	StoredIn string `json:"-"`
}

File is one file of a release.

type Grant added in v1.156.0

type Grant struct {
	Email   string `json:"email" example:"pat@client.example"`
	Persona string `json:"persona" example:"finance-team"`
	Level   string `json:"level" example:"view"`
	// Environments are the private environments a view grant opens; none is
	// every private environment. A manage grant is site-wide.
	Environments []string  `json:"environments"`
	GrantedBy    string    `json:"granted_by" example:"jane@example.com"`
	CreatedAt    time.Time `json:"created_at"`
}

Grant is access to a site for one person, keyed to the email the identity provider reports, or for everyone holding a persona. A persona grant is always view, matched against the viewer's persona on every request.

func (*Grant) Opens added in v1.158.0

func (g *Grant) Opens(env string) bool

Opens reports whether a view grant opens env.

type Header struct {
	Name  string `json:"name" example:"Content-Security-Policy"`
	Value string `json:"value" example:"default-src 'self'"`
}

Header is one header a rule sets.

func HeadersFor added in v1.159.0

func HeadersFor(rules []HeaderRule, p string) []Header

HeadersFor is every header the rules set for a path, in file order, a later rule's header replacing an earlier one's of the same name; then the framing default, unless one of them declares framing (frame-ancestors in an enforced Content-Security-Policy, or X-Frame-Options).

type HeaderRule added in v1.159.0

type HeaderRule struct {
	Path    string   `json:"path" example:"/*"`
	Headers []Header `json:"headers"`
}

HeaderRule is one block of a release's _headers file: a path pattern, as a redirect's from is written ("/*" ending matches everything beneath), and the headers every answer under it carries (#2557).

func ParseHeaders added in v1.159.0

func ParseHeaders(text string) ([]HeaderRule, error)

ParseHeaders reads a release's _headers file: a path line starting with "/", then each header the path carries on an indented "Name: value" line, with blank lines and # comments skipped. A header outside the allowed set, a value holding a control character, or a header with no path above it refuses the file, naming the line.

type InUseError added in v1.162.0

type InUseError struct{ Msg string }

InUseError is ErrEnvironmentInUse in the words a person reads: what is in the way, and what to do first.

func (*InUseError) Error added in v1.162.0

func (e *InUseError) Error() string

func (*InUseError) Is added in v1.162.0

func (*InUseError) Is(target error) bool

Is makes every InUseError an ErrEnvironmentInUse.

type Job added in v1.156.0

type Job struct {
	ID          string `json:"id" example:"sjob_01J9"`
	SiteID      string `json:"site_id"`
	Kind        string `json:"kind" example:"publish"`
	Status      string `json:"status" example:"running"`
	Phase       string `json:"phase" example:"Writing files"`
	Environment string `json:"environment" example:"default"`
	Source      string `json:"source"`
	// Done and Total count the files written, or the pages copied.
	Done  int `json:"done"`
	Total int `json:"total"`
	Pages int `json:"pages"`
	// Bytes is what a copy has downloaded; SkippedCount the addresses it could
	// not bring across so far, listed in Skipped when it ends.
	Bytes        int64     `json:"bytes"`
	SkippedCount int       `json:"skipped_count"`
	Redirects    int       `json:"redirects"`
	Skipped      []Skipped `json:"skipped"`
	Release      int       `json:"release"`
	Error        string    `json:"error,omitempty"`
	CreatedBy    string    `json:"created_by"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
}

Job is a publish or a copy running in the background.

type JobProgress added in v1.156.0

type JobProgress struct {
	Phase     string
	Done      int
	Total     int
	Pages     int
	Bytes     int64
	Redirects int
	Skipped   int
}

JobProgress is one report of a running job's state.

type JobResult added in v1.156.0

type JobResult struct {
	Status    string
	Release   int
	Pages     int
	Redirects int
	Skipped   []Skipped
	Error     string
}

JobResult is how a job ended.

type KeepSetting added in v1.159.0

type KeepSetting struct {
	// Keep is the new limit; nil with Default false changes nothing.
	Keep *int
	// Default returns the environment to the deployment's default.
	Default bool
}

KeepSetting is a change to an environment's release limit (#2602).

func ParseKeep added in v1.159.0

func ParseKeep(raw json.RawMessage) (KeepSetting, error)

ParseKeep reads keep_releases as a caller sends it: a whole number, a string of digits, or "default". Absent or null changes nothing.

type Mount added in v1.159.0

type Mount struct {
	// Prefix is where the folder answers, "/media/": it starts and ends with a
	// slash and is never the site's root.
	Prefix string `json:"prefix" example:"/media/"`
	// Scope and ScopeID name the resource library: global, persona with the
	// persona's name, or user with the person's subject.
	Scope   string `json:"scope" example:"global"`
	ScopeID string `json:"scope_id,omitempty"`
	// Folder is the folder in that library, "sites/marketing/media".
	Folder    string    `json:"folder" example:"sites/marketing/media"`
	CreatedBy string    `json:"created_by,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

Mount serves a managed-resource folder at a URL prefix on every environment of a site (#2591). Media sits outside releases: publish, promote and rollback leave it alone. A release file at the same path wins over a mount.

func MountFor added in v1.159.0

func MountFor(mounts []Mount, p string) (Mount, string, bool)

MountFor is the mount serving p, the longest prefix, and the path under it; false when no mount serves p or p names the prefix itself.

func ValidateMount added in v1.159.0

func ValidateMount(m Mount) (Mount, error)

ValidateMount refuses a prefix or a folder a mount cannot have, and returns the mount as it is stored: the prefix and folder in their one form.

func ValidateMounts added in v1.159.0

func ValidateMounts(in []Mount) ([]Mount, error)

ValidateMounts checks every mount and that no two share a prefix.

type Place added in v1.159.0

type Place struct {
	After string `json:"after"`
}

Place is where an environment goes in a site's order (#2617): immediately after another one. dev is always first and prod always last, so every place there is lies after dev or after an environment between them, and nothing goes after prod.

func PlaceChoices added in v1.159.0

func PlaceChoices(order []string, name string) []Place

PlaceChoices is the places a new environment, or one being moved, can go in an order: after each environment but prod and itself. A single choice means there is nowhere else for it.

func PlaceNew added in v1.159.0

func PlaceNew(order []string, name string, p *Place) (*Place, error)

PlaceNew is where a new environment goes: the place asked for, or nil for the one place there is, refusing a choice left unsaid when there are more.

func (Place) String added in v1.159.0

func (p Place) String() string

String is a place as a sentence names it.

type Pointer

type Pointer struct {
	SiteID      string
	Environment string
	// After is the release the move was decided against.
	After  int
	To     int
	Action string
	Actor  string
	// DecidedBy is whose decision carried out a move an agent asked for
	// (#2643): DecidedByElicitation, DecidedByApproval or
	// DecidedByEnvironment; "" for a move a person made.
	DecidedBy string
}

Pointer is one move of an environment's pointer.

type Redirect

type Redirect struct {
	From   string `json:"from" example:"/old/*"`
	To     string `json:"to" example:"/new/:splat"`
	Status int    `json:"status" example:"301"`
}

Redirect is one rule of a release's redirect map. From ending in "/*" matches the path and everything beneath it, and ":splat" in To is what the "*" matched.

func ParseRedirects

func ParseRedirects(text string) ([]Redirect, error)

ParseRedirects reads a release's _redirects file: one rule per line, "from to [status]", with blank lines and # comments skipped. Status defaults to 301 and must be a redirect status. A target is a local path or an http(s) URL, and a rule with a control character in it is refused, so nothing in the file can write a header of its own.

type Ref added in v1.157.0

type Ref struct {
	Site        string
	Environment string
	Path        string
}

Ref names part of an environment's file tree: one file, a folder when Path ends in a slash, or the whole tree when Path is empty.

func ParseRef added in v1.157.0

func ParseRef(s string) (Ref, error)

ParseRef reads mcp:site:<site>/<environment>[/<path>].

func (Ref) IsFile added in v1.157.0

func (r Ref) IsFile() bool

IsFile reports whether the reference names one file.

type Release

type Release struct {
	ID         string `json:"id"`
	SiteID     string `json:"site_id"`
	Number     int    `json:"number" example:"3"`
	Source     string `json:"source,omitempty"`
	Note       string `json:"note,omitempty"`
	FileCount  int    `json:"file_count"`
	TotalBytes int64  `json:"total_bytes"`
	// ManifestSHA256 fixes the file set: the digest of every path and content
	// digest, in path order.
	ManifestSHA256 string     `json:"manifest_sha256"`
	Redirects      []Redirect `json:"redirects"`
	// Headers is what the release's _headers file declared (#2557).
	Headers []HeaderRule `json:"headers"`
	// Contract is what the release's _application file declared (#2679),
	// nil for none: the application it is a front end of and the contract
	// versions it works with.
	Contract  *Contract `json:"contract,omitempty"`
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
	// Base is the number of the release this one was derived from, 0 for a
	// release built from a complete file set.
	Base int `json:"base,omitempty" example:"41"`
	// Files is filled by a read that asks for them. Written with a
	// ManifestParent it holds only what differs from the parent.
	Files []File `json:"files,omitempty"`
	// ManifestParent is the release whose file set this one amends, "" for a
	// release that holds its whole file set. ManifestDepth counts the links
	// back to one that does.
	ManifestParent string `json:"-"`
	ManifestDepth  int    `json:"-"`
	// Removed is the paths this release takes out of its parent's file set.
	Removed []string `json:"-"`
	// Rendered is true for a release with a source tree of its own; a release
	// without one serves the files it was published with.
	Rendered bool `json:"rendered,omitempty"`
	// SourceFiles and SourceRemoved are Files and Removed for the source tree.
	SourceFiles   []File   `json:"-"`
	SourceRemoved []string `json:"-"`
	// RenderIndex is the file holding what each output read.
	RenderIndex *File `json:"-"`
	// Pruned is true once a sweep removed the release's files (#2602); its
	// record stays so the deployments and approvals naming it read as before.
	Pruned   bool       `json:"pruned,omitempty"`
	PrunedAt *time.Time `json:"pruned_at,omitempty"`
}

Release is one immutable file set.

func (*Release) DataFile added in v1.163.0

func (r *Release) DataFile(name string) (text, contentType string, present bool)

DataFile is the text a release's data file reads back as and its type; present is false when the release declares nothing in it.

func (*Release) SameData added in v1.163.0

func (r *Release) SameData(o *Release) bool

SameData reports whether two releases declare the same data files.

func (*Release) SetDataFile added in v1.163.0

func (r *Release) SetDataFile(name, text string) error

SetDataFile reads a data file's text into the release; "" declares nothing, which is what deleting the file does.

type Route

type Route struct {
	SiteID      string
	Site        string
	Environment string
	// Release is the release served, nil for an environment with none.
	Release *Release
	// Application is the application whose endpoints and pages the host
	// serves, empty for a site.
	Application string
	// Hostname is the added hostname as stored, empty for an address on the
	// pages domain.
	Hostname string
	// Private is true unless the host is a public domain (#2619): every address
	// on the pages domain is private, whatever the environment's domains are.
	// A private host answers only to people who have signed in and may open
	// the environment.
	Private bool
	// PartOf is the application this environment is a part of, "" for none;
	// its endpoints answer on the environment's own hosts.
	PartOf string
	// Status is what the environment answers in place of its release, after
	// the access check (#2631, #2632); its zero value is online.
	Status EnvironmentStatus
	// PrimaryHost is set for a redirect domain (#2687): every request is
	// answered with a permanent redirect to it, after the access check.
	PrimaryHost string
}

Route is what a hostname serves.

type Routing added in v1.162.2

type Routing struct {
	Status       string     `json:"status" enums:"pending,ready,failed"`
	Message      string     `json:"message"`
	CheckedAt    *time.Time `json:"checked_at,omitempty"`
	ScriptFailed bool       `json:"script_failed,omitempty"`
	RunID        string     `json:"run_id,omitempty"`
	RunScriptID  string     `json:"run_script_id,omitempty"`
	RunError     string     `json:"run_error,omitempty"`
}

Routing is the Site routing integration's status for one hostname (#2659): pending until the script answers, then ready or failed with the script's message. When the script itself failed, Message is one sentence and ScriptFailed is set; RunID, RunScriptID (where the run's page is) and RunError, the run's own error, are filled for an administrator only.

type RoutingRetry added in v1.162.2

type RoutingRetry struct {
	Site    string `json:"site"`
	Retried bool   `json:"retried"`
}

RoutingRetry is the answer to a Site routing retry (#2659).

type Site

type Site struct {
	ID          string `json:"id" example:"site_01J9"`
	Name        string `json:"name" example:"marketing"`
	Description string `json:"description"`
	OwnerEmail  string `json:"owner_email" example:"jane@example.com"`
	// MainEnvironment is the environment the main address,
	// <site>.<pages domain>, serves; "" is none, and the address answers not
	// found.
	MainEnvironment string        `json:"main_environment" example:"prod"`
	Environments    []Environment `json:"environments"`
	// Media is the resource folders the site serves at URL prefixes (#2591),
	// filled by a read of one site.
	Media     []Mount   `json:"media"`
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Site is the record.

func (*Site) Environment

func (s *Site) Environment(name string) *Environment

Environment is the named environment, nil for none.

func (*Site) Order added in v1.159.0

func (s *Site) Order() []string

Order is the names of the site's environments in its order.

func (*Site) PassedGated added in v1.159.0

func (s *Site) PassedGated(before, after []string, name string) string

PassedGated is an environment requiring approval that a move puts name after when it was before it, "" for none: what name serves would then feed the environments the gated one guards.

func (*Site) Previous added in v1.159.0

func (s *Site) Previous(name string) *Environment

Previous is the environment immediately before name in the site's order, nil for dev or an environment the site does not have.

func (*Site) Validate

func (s *Site) Validate() error

Validate checks the record's own fields: its name, its description and each environment's name.

type Skipped added in v1.156.0

type Skipped struct {
	Address string `json:"address" example:"/old/report.pdf"`
	Reason  string `json:"reason" example:"answered 404"`
}

Skipped is one address a copy of a site could not bring across, and why.

type Store

type Store interface {
	Create(ctx context.Context, s *Site) error
	Get(ctx context.Context, id string) (*Site, error)
	GetByName(ctx context.Context, name string) (*Site, error)
	List(ctx context.Context) ([]Site, error)
	Update(ctx context.Context, s *Site) error
	Delete(ctx context.Context, id string) error
	// SetEnvironment creates an environment, or changes its settings.
	SetEnvironment(ctx context.Context, siteID, name string, set EnvironmentSettings, actor string) error
	// SetStatus changes what an environment answers and records it (#2631,
	// #2632).
	SetStatus(ctx context.Context, siteID, env string, st EnvironmentStatus, actor string) error
	// RenameEnvironment moves every reference to an environment's name, and
	// RemoveEnvironment removes one with nothing attached (#2630).
	RenameEnvironment(ctx context.Context, siteID, from, to, actor string) error
	RemoveEnvironment(ctx context.Context, siteID, name string) error
	// SetMainEnvironment gives the main address to an environment, "" to none.
	SetMainEnvironment(ctx context.Context, siteID, env string) error
	// SetDomainPublic makes a site's domain answer anyone, or only those who
	// sign in (#2619).
	SetDomainPublic(ctx context.Context, hostname string, public bool) error
	// SetDomainRole makes a site's domain its environment's primary or not and
	// sets its mode (#2687), taking the mark from the previous primary.
	SetDomainRole(ctx context.Context, hostname string, primary bool, mode string) error
	// RecordRelease writes a release and its files, numbering it next. With a
	// move it also points the environment at the new release, in the one
	// transaction, so a move that loses to another leaves no release behind.
	RecordRelease(ctx context.Context, r *Release, move *Pointer) error
	Release(ctx context.Context, siteID string, number int) (*Release, error)
	ReleaseByID(ctx context.Context, id string) (*Release, error)
	Releases(ctx context.Context, siteID string) ([]Release, error)
	// Files is what a release serves, in path order, however it is stored.
	Files(ctx context.Context, releaseID string) ([]File, error)
	// Tree is one tree of a release, in path order.
	Tree(ctx context.Context, releaseID, tree string) ([]File, error)
	// StoredFiles lists what a site holds in object storage, each object once,
	// whichever releases share it.
	StoredFiles(ctx context.Context, siteID string) ([]File, error)
	// Point moves an environment, failing with ErrStale when another move
	// got there first, and records the deployment.
	Point(ctx context.Context, p Pointer) error
	Deployments(ctx context.Context, siteID, environment string, limit int) ([]Deployment, error)
	AddDomain(ctx context.Context, d *Domain) error
	Domain(ctx context.Context, hostname string) (*Domain, error)
	Domains(ctx context.Context) ([]Domain, error)
	SiteDomains(ctx context.Context, siteID string) ([]Domain, error)
	RemoveDomain(ctx context.Context, hostname string) error
	// RouteHost is what an added hostname serves, ErrNoDomain for none.
	RouteHost(ctx context.Context, hostname string) (*Route, error)
	// RouteOwn is what a site's main address serves, ErrNoDomain for none.
	RouteOwn(ctx context.Context, siteName string) (*Route, error)
	// RouteEnv is what <site>--<env> serves, ErrNoDomain for none.
	RouteEnv(ctx context.Context, siteName, env string) (*Route, error)
	// SiteAccess reads what decides whether a person may open one
	// environment, fresh.
	SiteAccess(ctx context.Context, siteID, env, email, persona string) (*Access, error)
	Grants(ctx context.Context, siteID string) ([]Grant, error)
	GrantLevel(ctx context.Context, siteID, email string) (string, error)
	// SetGrant adds a person or persona, or changes their grant.
	SetGrant(ctx context.Context, siteID string, g *Grant) error
	// RemoveGrant removes the grant to an email or, with email "", a persona.
	RemoveGrant(ctx context.Context, siteID, email, persona string) error
	CreateJob(ctx context.Context, j *Job) error
	Job(ctx context.Context, id string) (*Job, error)
	ActiveJobs(ctx context.Context, siteID string) ([]Job, error)
	// ReportJob records a running job's progress and says whether it was asked
	// to stop.
	ReportJob(ctx context.Context, id string, p JobProgress) (stop bool, err error)
	FinishJob(ctx context.Context, id string, r JobResult) error
	StopJob(ctx context.Context, id string) error
}

Store keeps sites, releases and domains.

Directories

Path Synopsis
Package siteaddr is every hostname the deployment answers on for a site or an application, as the system administrator's ingress rules need them: each site's addresses on the pages domain and every domain added, with a site domain's role (#2687).
Package siteaddr is every hostname the deployment answers on for a site or an application, as the system administrator's ingress rules need them: each site's addresses on the pages domain and every domain added, with a site domain's role (#2687).
Package siteconfig is the sites: configuration section (#2517, #2518).
Package siteconfig is the sites: configuration section (#2517, #2518).
Package sitecontract is where a site release's contract meets the application it is a front end of (#2679): a release's _application file declares the application's contract versions it works with, a promotion into an environment that is a part of that application is refused when the release excludes the application's contract, and an application release reads what each of its site parts serves.
Package sitecontract is where a site release's contract meets the application it is a front end of (#2679): a release's _application file declares the application's contract versions it works with, a promotion into an environment that is a part of that application is refused when the release excludes the application's contract, and an application release reads what each of its site parts serves.
Package sitecrawl copies an existing site into the files of a release (#2518), so a site moved off a CMS keeps its URLs: every page is filed at the path it answered at, an address that redirected becomes a rule of the release's redirect map, and the sitemap and robots file come along.
Package sitecrawl copies an existing site into the files of a release (#2518), so a site moved off a CMS keeps its URLs: every page is filed at the path it answered at, an address that redirected becomes a rule of the release's redirect map, and the sitemap and robots file come along.
Package siteenv carries out the operations on a site's environments that came after the core service (#2648): what an environment answers (online, offline, redirect, #2631, #2632), renaming and removing one (#2630), the check of a new site's name (#2636), reading one file for the portal's viewer (#2629), and the rule that an agent's move of an environment people use waits on a person (#2643).
Package siteenv carries out the operations on a site's environments that came after the core service (#2648): what an environment answers (online, offline, redirect, #2631, #2632), renaming and removing one (#2630), the check of a new site's name (#2636), reading one file for the portal's viewer (#2629), and the rule that an agent's move of an environment people use waits on a person (#2643).
Package sitefs presents a list of stored files as an fs.FS, reading a file only when it is opened: a tree can hold thousands of files, and a render opens few of them on most changes.
Package sitefs presents a list of stored files as an fs.FS, reading a file only when it is opened: a tree can hold thousands of files, and a render opens few of them on most changes.
Package sitegw is the serving layer for everything the platform answers on a hostname other than its own (#2517, #2518): the static sites' environments and an application's browser pages.
Package sitegw is the serving layer for everything the platform answers on a hostname other than its own (#2517, #2518): the static sites' environments and an application's browser pages.
Package siteprune is release retention for sites (#2602): the sweep that prunes each site's releases past its environments' limits, deletes the objects only those releases named, and removes objects no release names once they are older than a grace.
Package siteprune is release retention for sites (#2602): the sweep that prunes each site's releases past its environments' limits, deletes the objects only those releases named, and removes objects no release names once they are older than a grace.
Package siterender renders a site's source tree: a pure function from the files of the tree to the files it serves.
Package siterender renders a site's source tree: a pure function from the files of the tree to the files it serves.
Package siterouting is the Site routing integration's items (#2659): every hostname the platform serves for sites and applications, computed from what is stored, never from what a call site says it changed.
Package siterouting is the Site routing integration's items (#2659): every hostname the platform serves for sites and applications, computed from what is stored, never from what a call site says it changed.
Package sitestatus holds the rules an environment's status is checked and answered by (#2631, #2632): an offline message cleaned of the runes that hide or reorder text, a redirect target that is an https URL on a host the platform does not answer on, where a redirected request lands, and the Retry-After an offline answer carries.
Package sitestatus holds the rules an environment's status is checked and answered by (#2631, #2632): an offline message cleaned of the runes that hide or reorder text, a redirect target that is an https URL on a host the platform does not answer on, where a redirected request lands, and the Retry-After an offline answer carries.
Package sitestore is the PostgreSQL store of sites, releases and domains (#2518).
Package sitestore is the PostgreSQL store of sites, releases and domains (#2518).
Package sitesvc is what can be done to a site (#2518): the one service the manage_site tool and an application's release use.
Package sitesvc is what can be done to a site (#2518): the one service the manage_site tool and an application's release use.
Package sitetile keeps a site environment's tile (#2658): a picture of the release the environment serves, drawn by the tile worker in the headless renderer (internal/site/sitetile/tilepage builds the page) and redrawn when the environment's release changes.
Package sitetile keeps a site environment's tile (#2658): a picture of the release the environment serves, drawn by the tile worker in the headless renderer (internal/site/sitetile/tilepage builds the page) and redrawn when the environment's release changes.
tilepage
Package tilepage builds the page a site environment's tile is drawn from (#2658): the release, served in process by the rules the environment's own address serves it with, so the tile shows what a visitor who has not signed in sees there.
Package tilepage builds the page a site environment's tile is drawn from (#2658): the release, served in process by the rules the environment's own address serves it with, so the tile shows what a visitor who has not signed in sees there.
Package sitetool is the manage_site MCP tool (#2518): a site's record, its environments, publishing a release, promoting and rolling back, mapping hostnames and the migration crawl, over the one service.
Package sitetool is the manage_site MCP tool (#2518): a site's record, its environments, publishing a release, promoting and rolling back, mapping hostnames and the migration crawl, over the one service.
Package sitetraffic records each site's traffic and latency by environment and by replica in the platform's own database (#2647), so a site's people see it in the portal and in manage_site with no Prometheus backend and no grant beyond seeing the site.
Package sitetraffic records each site's traffic and latency by environment and by replica in the platform's own database (#2647), so a site's people see it in the portal and in manage_site with no Prometheus backend and no grant beyond seeing the site.
Package sitewire assembles sites (#2518) from the stores the platform holds and registers manage_site.
Package sitewire assembles sites (#2518) from the stores the platform holds and registers manage_site.

Jump to

Keyboard shortcuts

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