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 built file set under its own object-storage prefix), and the hostnames that route to an environment or to an application's endpoints.
Publishing adds a release. 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 NormalizeEmail(email string) string
- func NormalizeHost(hostname string) 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 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 gives nothing else. 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 ( 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.
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 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"`
}
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 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"`
// Files is filled by a read that asks for them.
Files []File `json:"files,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 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.
RecordRelease(ctx context.Context, r *Release) 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(ctx context.Context, releaseID 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 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 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. |