site

package
v1.157.0 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 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

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

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

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.

View Source
const RefPrefix = "mcp:site:"

RefPrefix starts the reference that names a site's files to the tools that read and edit content.

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 IsRef added in v1.157.0

func IsRef(s string) bool

IsRef reports whether s is a site reference.

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 RenderRedirects added in v1.157.0

func RenderRedirects(rules []Redirect) string

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

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"`
	// 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

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 Ref added in v1.157.0

type Ref struct {
	Site        string
	Environment string
	Path        string
}

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.

func ParseRef added in v1.157.0

func ParseRef(s string) (Ref, error)

ParseRef reads mcp:site:<site>/<environment>[/<path>].

func (Ref) IsFile added in v1.157.0

func (r Ref) IsFile() bool

IsFile reports whether the reference names one file.

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.

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

Jump to

Keyboard shortcuts

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