site

package
v1.156.1 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 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.

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

View Source
const (
	JobPublish = "publish"
	JobCrawl   = "crawl"
)

The kinds of work that run apart from the request that started them.

View Source
const (
	JobRunning = "running"
	JobDone    = "done"
	JobFailed  = "failed"
	JobStopped = "stopped"
)

The states a job is in.

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

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

func NormalizeEmail(email string) string

NormalizeEmail is the form a grant is stored and matched in.

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 ValidLevel added in v1.156.0

func ValidLevel(level string) bool

ValidLevel reports whether level is one a grant can hold.

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

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

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

Jump to

Keyboard shortcuts

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