site

package
v1.159.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 14 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 (
	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 (
	ActionPublish     = "publish"
	ActionPromote     = "promote"
	ActionRollback    = "rollback"
	ActionApplication = "application"
)

The actions a deployment records.

View Source
const (
	MaxDescription = 2000
	MaxNote        = 2000
)

Limits on a record's fields.

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

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

func IsRef(s string) bool

IsRef reports whether s is a site reference.

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 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.

func ValidateRedirect

func ValidateRedirect(r Redirect) error

ValidateRedirect checks one rule.

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: the first of its domains, otherwise its address on the pages domain, "" for none.

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.

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 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"`
	CreatedAt   time.Time `json:"created_at"`
}

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

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:"-"`
	CreatedBy       string    `json:"created_by"`
	CreatedAt       time.Time `json:"created_at"`
}

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.

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"`
	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) 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
	// 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 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 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
}

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"`
	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.

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
}

Route is what a hostname serves.

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
	// 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
	// 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 siteconfig is the sites: configuration section (#2517, #2518).
Package siteconfig is the sites: configuration section (#2517, #2518).
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 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 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 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 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