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 IsRef(s string) bool
- func NormalizeEmail(email string) string
- func NormalizeHost(hostname string) string
- func RenderRedirects(rules []Redirect) string
- func SameOrUnder(host, domain string) bool
- func ValidLevel(level string) bool
- func ValidateEnvironment(name string) error
- func ValidateHostname(hostname string) error
- func ValidateName(name string) error
- func ValidateRedirect(r Redirect) error
- type Access
- type Deployment
- type Domain
- type Environment
- type File
- type Grant
- type Job
- type JobProgress
- type JobResult
- 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 ( 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" )
The actions a deployment records.
const ( MaxDescription = 2000 MaxNote = 2000 )
Limits on a record's fields.
const EnvDefault = "default"
EnvDefault is the environment a new site starts with: the one its own address serves and a publish that names none lands in.
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") 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 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 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 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.
Types ¶
type Access ¶ added in v1.156.0
type Access struct {
OwnerEmail string
InternalView bool
// Level is the person's grant, "" for none.
Level string
}
Access is what the store knows about one person and one site: read fresh on every request to a site's own address, so that removing someone takes effect on their next request.
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"`
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.
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"`
// RequiresApproval makes a promotion here a request in the Approvals queue.
RequiresApproval bool `json:"requires_approval"`
UpdatedBy string `json:"updated_by,omitempty"`
UpdatedAt time.Time `json:"updated_at"`
}
Environment is one named place a release is served from.
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"`
Level string `json:"level" example:"view"`
GrantedBy string `json:"granted_by" example:"jane@example.com"`
CreatedAt time.Time `json:"created_at"`
}
Grant is one person's access to a site, keyed to the email the identity provider reports.
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 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 ¶
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"`
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:"-"`
}
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 a site's own address.
Hostname string
// Private is true on a site's own address: it answers only to people who
// have signed in and may open the site.
Private bool
}
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"`
// InternalView lets everyone whose persona is not external open the
// site's own address: a company intranet.
InternalView bool `json:"internal_view"`
Environments []Environment `json:"environments"`
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.
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 whether it requires
// approval.
SetEnvironment(ctx context.Context, siteID, name string, requiresApproval bool, actor 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 own address serves, ErrNoDomain for none.
RouteOwn(ctx context.Context, siteName string) (*Route, error)
Grants(ctx context.Context, siteID string) ([]Grant, error)
GrantLevel(ctx context.Context, siteID, email string) (string, error)
// SetGrant adds a person or changes their level.
SetGrant(ctx context.Context, siteID string, g *Grant) error
RemoveGrant(ctx context.Context, siteID, email 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 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. |