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
- Variables
- func CanonicalEnvironment(name string) (canonical string, aliased bool)
- func EnvLabel(siteName, env string) string
- func EnvironmentNameRoom(siteName string) int
- func HeaderNames() []string
- func IsRef(s string) bool
- func NameFrom(input string) string
- func NormalizeEmail(email string) string
- func NormalizeHost(hostname string) string
- func ParseEnvLabel(label string) (siteName, env string, ok bool)
- func PlaceRefusal(name string, choices []Place) string
- func Placed(order []string, name string, p *Place) ([]string, error)
- func RenderHeaders(rules []HeaderRule) string
- func RenderRedirects(rules []Redirect) string
- func ReservedLabel(label string) bool
- func ReservedLabelNote(siteName, pagesDomain string) string
- func RollbackTarget(env *Environment, history []Deployment, to int, gone map[int]bool) (int, error)
- func SameOrUnder(host, domain string) bool
- func ValidLevel(level string) bool
- func ValidateEnvironment(name string) error
- func ValidateHostname(hostname string) error
- func ValidateLabel(siteName, env string) error
- func ValidateName(name string) error
- func ValidateRedirect(r Redirect) error
- type Access
- type Addressing
- func (a Addressing) Address(st *Site, environment string, domains []Domain) string
- func (a Addressing) AddressNote(st *Site) string
- func (a Addressing) Addresses(st *Site, domains []Domain) map[string]string
- func (a Addressing) Origin(host string) string
- func (a Addressing) OwnAddress(st *Site) string
- func (a Addressing) PageOrigin(applicationName string) string
- func (a Addressing) PagesAddress(st *Site, environment string) string
- func (a Addressing) PagesAddresses(st *Site) map[string]string
- type ClaimRules
- type Deployment
- type Domain
- type Environment
- type EnvironmentSettings
- type EnvironmentStatus
- type File
- type Grant
- type Header
- type HeaderRule
- type InUseError
- type Job
- type JobProgress
- type JobResult
- type KeepSetting
- type Mount
- type Place
- type Pointer
- type Redirect
- type Ref
- type Release
- type Route
- type Site
- type Skipped
- type Store
Constants ¶
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.
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.
const ( ActionOffline = "offline" ActionOnline = "online" ActionRedirect = "redirect" )
The actions History records for a status change.
const ( JobPublish = "publish" JobCrawl = "crawl" )
The kinds of work that run apart from the request that started them.
const ( JobRunning = "running" JobDone = "done" JobFailed = "failed" JobStopped = "stopped" )
The states a job is in.
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.
const ( ActionPublish = "publish" ActionPromote = "promote" ActionRollback = "rollback" ActionApplication = "application" // ActionRename records an environment renamed (#2630). ActionRename = "rename" )
The actions a deployment records.
const ( MaxDescription = 2000 MaxNote = 2000 )
Limits on a record's fields.
const ( DecidedByElicitation = "elicitation" DecidedByApproval = "approval" DecidedByEnvironment = "environment_setting" )
Whose decision carried out a move an agent asked for (#2643).
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.
const EnvAlias = "default"
EnvAlias is the name EnvDev had before #2604, accepted for one minor release.
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.
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.
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.
const (
MaxMounts = 20
)
MaxMounts bounds a site's mounts, and maxPathLen a prefix or folder.
const RefPrefix = "mcp:site:"
RefPrefix starts the reference that names a site's files to the tools that read and edit content.
Variables ¶
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
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
EnvLabel is the one DNS label <site>--<env> under the pages domain: every environment's own address.
func EnvironmentNameRoom ¶ added in v1.162.0
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 NameFrom ¶ added in v1.162.0
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
NormalizeEmail is the form a grant is stored and matched in.
func NormalizeHost ¶
NormalizeHost is hostname as a request's Host names it, lowercased, with no port or trailing dot.
func ParseEnvLabel ¶ added in v1.158.0
ParseEnvLabel splits a <site>--<env> label. Neither name may hold "--", so the first is the separator.
func PlaceRefusal ¶ added in v1.159.0
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
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
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
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
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 ¶
SameOrUnder reports whether host is domain or a name beneath it.
func ValidLevel ¶ added in v1.156.0
ValidLevel reports whether level is one a grant can hold.
func ValidateEnvironment ¶
ValidateEnvironment checks an environment's name.
func ValidateHostname ¶
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
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 ¶
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 ¶
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
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"`
// 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:"-"`
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
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"`
// 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"`
// 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.
type Header ¶ added in v1.159.0
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
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
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
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
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
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.
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 ¶
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
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.
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
// Status is what the environment answers in place of its release, after
// the access check (#2631, #2632); its zero value is online.
Status EnvironmentStatus
}
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) PassedGated ¶ added in v1.159.0
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.
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
// 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.
Source Files
¶
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 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 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 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. |