site

package
v1.155.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 10 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 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

View Source
const (
	EnvDev  = "dev"
	EnvProd = "prod"
)

The environment a publish lands in when none is named, and the one created requiring approval.

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

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

func NormalizeHost(hostname string) string

NormalizeHost is hostname as a request's Host names it, lowercased, with no port or trailing dot.

func SameOrUnder

func SameOrUnder(host, domain string) bool

SameOrUnder reports whether host is domain or a name beneath it.

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

func (Domain) Verified

func (d Domain) Verified() bool

Verified reports whether the hostname routes.

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

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

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL