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 once verified.
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 NormalizeHost(hostname string) string
- func SameOrUnder(host, domain string) bool
- func ValidateEnvironment(name string) error
- func ValidateHostname(hostname string) error
- func ValidateName(name string) error
- func ValidateRedirect(r Redirect) error
- type Deployment
- type Domain
- type Environment
- type File
- type Pointer
- type Redirect
- type Release
- type Route
- type Site
- type Store
Constants ¶
const ( EnvDev = "dev" EnvProd = "prod" )
The environment a publish lands in when none is named, and the one created requiring approval.
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 PreviewSeparator = "--"
PreviewSeparator divides a preview hostname's first label into environment and site. Neither name may contain it, so the label reads one way.
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") )
Errors a caller reads by identity.
Functions ¶
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 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 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"`
// Token is what the verification step looks for. It is public by design:
// it says nothing but "this deployment asked".
Token string `json:"token"`
VerifiedAt *time.Time `json:"verified_at,omitempty"`
VerifiedBy string `json:"verified_by,omitempty"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
}
Domain maps one hostname to a site environment or to an application.
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 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 verified hostname as stored, empty for a preview.
Hostname string
}
Route is what a verified hostname or a preview 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"`
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 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)
MarkVerified(ctx context.Context, hostname, by string) error
RemoveDomain(ctx context.Context, hostname string) error
// RouteHost is what a verified hostname serves, ErrNoDomain for none.
RouteHost(ctx context.Context, hostname string) (*Route, error)
// RoutePreview is what an environment's preview hostname serves.
RoutePreview(ctx context.Context, siteName, environment string) (*Route, error)
}
Store keeps sites, releases and domains.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package sitecert is the built-in certificate option for verified domains (#2518): ACME through autocert, a listener of its own, and a certificate cache in PostgreSQL shared by every replica.
|
Package sitecert is the built-in certificate option for verified domains (#2518): ACME through autocert, a listener of its own, and a certificate cache in PostgreSQL shared by every replica. |
|
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 siteverify checks that the person mapping a hostname controls it (#2518), by a DNS TXT record or by a token the hostname serves over HTTP.
|
Package siteverify checks that the person mapping a hostname controls it (#2518), by a DNS TXT record or by a token the hostname serves over HTTP. |
|
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. |