sitehttp

package
v1.162.1 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 48 Imported by: 0

Documentation

Overview

Package sitehttp assembles the serving layer for sites and browser pages (#2517, #2518) over the platform's mux: the Host-routing gateway the listener is wrapped in, the portal routes that hand a signed-in person to a page origin or a site's own address, and the REST routes of the portal's Sites section and its administration (#2559).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PortalRegistrar added in v1.156.0

func PortalRegistrar(d PortalDeps) func(*http.ServeMux)

PortalRegistrar registers the portal's Sites routes; nil where the deployment has no sites.

func Registrar added in v1.156.0

func Registrar(p *platform.Platform, resolver portal.PersonaResolver, notify *notifydelivery.Handle) func(*http.ServeMux)

Registrar is the portal's Sites routes, nil where the deployment serves no sites (#2559).

Types

type AccessList added in v1.156.0

type AccessList struct {
	Owner  string       `json:"owner_email"`
	Grants []site.Grant `json:"grants"`
	// Personas are every persona an environment can be shared with, for the
	// Share dialog.
	Personas []string `json:"personas"`
}

AccessList is who has access to a site, for someone who manages it.

type AddressList added in v1.156.0

type AddressList struct {
	Addresses []DeploymentAddress `json:"addresses"`
}

AddressList is every site address and domain on the deployment.

type AdminDomainBody added in v1.156.0

type AdminDomainBody struct {
	Hostname         string `json:"hostname" example:"shop.example.com"`
	Site             string `json:"site,omitempty"`
	Environment      string `json:"environment,omitempty"`
	RequiresApproval *bool  `json:"requires_approval,omitempty"`
	Application      string `json:"application,omitempty"`
	// Public opens a site's domain to anyone (#2619); private otherwise.
	Public bool `json:"public,omitempty"`
}

AdminDomainBody maps a hostname to a site environment or an application.

type ApplicationAddresses added in v1.156.0

type ApplicationAddresses struct {
	PageOrigin string   `json:"page_origin"`
	Domains    []string `json:"domains"`
}

ApplicationAddresses is where an application answers.

type CopyBody added in v1.156.0

type CopyBody struct {
	URL         string `json:"url" example:"https://www.example.com"`
	Environment string `json:"environment,omitempty" example:"dev"`
	Note        string `json:"note"`
	MaxPages    int    `json:"max_pages,omitempty"`
	MaxBytes    int64  `json:"max_bytes,omitempty"`
	// FormMap names, for a page path, the platform form that replaces its forms.
	FormMap map[string]string `json:"form_map,omitempty"`
}

CopyBody names a site to copy into a release.

type DeploymentAddress added in v1.156.0

type DeploymentAddress struct {
	Hostname    string `json:"hostname" example:"marketing.pages.example.net"`
	Kind        string `json:"kind" example:"site_address"`
	Site        string `json:"site,omitempty" example:"marketing"`
	Environment string `json:"environment,omitempty" example:"default"`
	Application string `json:"application,omitempty"`
	CreatedBy   string `json:"created_by"`
	CreatedAt   string `json:"created_at"`
}

DeploymentAddress is one hostname the deployment answers on for a site or an application. Each needs an ingress rule, added by a system administrator.

type DeploymentList added in v1.156.0

type DeploymentList struct {
	Deployments []site.Deployment `json:"deployments"`
}

DeploymentList is every move of a site's environments, newest first.

type DomainAccessBody added in v1.159.0

type DomainAccessBody struct {
	Public bool `json:"public"`
	// Reason goes with a request to make it public.
	Reason string `json:"reason,omitempty"`
}

DomainAccessBody makes a domain public or private (#2619).

type DomainBody added in v1.156.0

type DomainBody struct {
	Hostname    string `json:"hostname" example:"www.example.com"`
	Environment string `json:"environment" example:"prod"`
	// Public opens the domain to anyone (#2619): the owner's or an
	// administrator's, through Approvals where the environment requires
	// approval. A domain is added private otherwise.
	Public bool   `json:"public,omitempty"`
	Reason string `json:"reason,omitempty"`
	// RequiresApproval sets whether the environment requires approval, on
	// one the request creates or one that exists; After is where a new
	// environment goes (#2617).
	RequiresApproval *bool  `json:"requires_approval,omitempty"`
	After            string `json:"after,omitempty"`
}

DomainBody adds a domain to a site.

type EnvironmentBody added in v1.156.0

type EnvironmentBody struct {
	RequiresApproval *bool `json:"requires_approval,omitempty"`
	// Public is refused (#2619): public is a setting of a domain.
	Public       *bool `json:"public,omitempty"`
	InternalView *bool `json:"internal_view,omitempty"`
	// After places a new environment, or moves one, immediately after the
	// environment it names: dev or one between dev and prod (#2617).
	After string `json:"after,omitempty"`
	// KeepReleases is how many releases the environment keeps: a whole number
	// (0 keeps every release), or "default" for the deployment's default
	// (#2602). The owner and administrators only.
	KeepReleases json.RawMessage `json:"keep_releases,omitempty" swaggertype:"string" example:"50"`
	// Status is what every address of the environment answers (#2631,
	// #2632): online, offline (with message and back_at) or redirect (with
	// redirect_to and keep_path).
	Status     string     `json:"status,omitempty" enums:"online,offline,redirect"`
	Message    string     `json:"message,omitempty"`
	BackAt     *time.Time `json:"back_at,omitempty"`
	RedirectTo string     `json:"redirect_to,omitempty" example:"https://status.example.com"`
	KeepPath   bool       `json:"keep_path,omitempty"`
	// Reason goes with a redirect that waits on Approvals.
	Reason string `json:"reason,omitempty"`
	// RenameTo renames an environment between dev and prod, alone (#2630).
	RenameTo string `json:"rename_to,omitempty" example:"qa"`
	// AgentsMayPromote lets an agent's promote, rollback or public domain here
	// go ahead without a person's decision (#2643). Administrators only.
	AgentsMayPromote *bool `json:"agents_may_promote,omitempty"`
}

EnvironmentBody creates, places or changes an environment; a field left out is left alone.

type EnvironmentResponse added in v1.158.0

type EnvironmentResponse struct {
	Site   SiteView `json:"site"`
	Status string   `json:"status" example:"done"`
	Note   string   `json:"note,omitempty"`
	// Approval is the request a redirect waits on (status awaiting_approval).
	Approval *sitesvc.ApprovalRequest `json:"approval,omitempty"`
}

EnvironmentResponse is what creating or changing an environment did.

type FileDiffView added in v1.159.0

type FileDiffView struct {
	From int    `json:"from" example:"14"`
	To   int    `json:"to" example:"15"`
	Path string `json:"path"`
	Diff string `json:"diff"`
}

FileDiffView is one file's change between two releases.

type FileSaveBody added in v1.159.0

type FileSaveBody struct {
	Path string `json:"path" example:"pricing/index.html"`
	// Content is the whole file: text, or base64 with encoding "base64".
	Content  string `json:"content"`
	Encoding string `json:"encoding,omitempty" example:"utf-8"`
	// Base is the release the editor read, which dev must still serve.
	Base int    `json:"base" example:"14"`
	Note string `json:"note,omitempty"`
	// DryRun checks the save, renders a rendered site, and stores nothing.
	DryRun bool `json:"dry_run,omitempty"`
}

FileSaveBody saves one file into dev.

type FileTextView added in v1.159.0

type FileTextView struct {
	Environment string `json:"environment" example:"dev"`
	Release     int    `json:"release" example:"14"`
	Path        string `json:"path" example:"pricing/index.html"`
	ContentType string `json:"content_type" example:"text/html; charset=utf-8"`
	Body        string `json:"body"`
}

FileTextView is one file's text as dev serves it.

type FormList added in v1.156.0

type FormList struct {
	Forms []string `json:"forms"`
}

FormList is the platform forms a copied page's forms can post to.

type GrantBody added in v1.156.0

type GrantBody struct {
	Email   string `json:"email,omitempty" example:"pat@example.com"`
	Persona string `json:"persona,omitempty" example:"finance-team"`
	Level   string `json:"level" example:"view"`
	// Environments are the private environments a view grant opens; none is
	// every private environment.
	Environments []string `json:"environments,omitempty"`
	// Notify emails them the site's address.
	Notify bool `json:"notify,omitempty"`
}

GrantBody gives a person, by email, or a persona access.

type JobList added in v1.156.0

type JobList struct {
	Jobs []site.Job `json:"jobs"`
}

JobList is a site's running jobs.

type Layer

type Layer struct {
	// contains filtered or unexported fields
}

Layer is the assembled serving layer; a nil one passes everything through.

func Build

func Build(mux *http.ServeMux, p *platform.Platform, adminAuth func() func(http.Handler) http.Handler, author func(*http.Request) string) (*Layer, error)

Build assembles the layer, nil where the deployment has no sites.

func (*Layer) Start

func (l *Layer) Start(ctx context.Context, instance string) (stop func())

Start begins the handoff sweep, the reading of saved settings, the release sweep's schedule and the traffic flush, and returns what stops them. instance is this process's X-Platform-Instance, the name its traffic is recorded under.

func (*Layer) Wrap

func (l *Layer) Wrap(next http.Handler) http.Handler

Wrap sends a served hostname to the gateway.

type MainEnvironmentBody added in v1.158.0

type MainEnvironmentBody struct {
	Environment string `json:"environment" example:"prod"`
}

MainEnvironmentBody gives the main address to an environment, "" to none.

type PortalDeps added in v1.156.0

type PortalDeps struct {
	Runtime *sitewire.Runtime
	// Persona is the caller's resolved persona, nil for none.
	Persona func(roles []string) *portal.PersonaInfo
	IsAdmin func(roles []string) bool
	// Audit records each write; nil records none.
	Audit audit.Logger
	// Sharer emails a person a site was shared with; nil sends nothing.
	Sharer Sharer
	// Forms lists the endpoints that are forms; nil offers none.
	Forms func(ctx context.Context) ([]string, error)
	// Personas lists every persona an environment can be shared with; nil
	// offers none.
	Personas func() []string
}

PortalDeps is what the portal routes act through.

type PromoteBody added in v1.156.0

type PromoteBody struct {
	From    string `json:"from,omitempty" example:"stage"`
	To      string `json:"to" example:"prod"`
	Release int    `json:"release,omitempty"`
	Reason  string `json:"reason,omitempty"`
}

PromoteBody moves a release to an environment.

type PublishBody added in v1.156.0

type PublishBody struct {
	// Environment is always dev, and may be left out.
	Environment string `json:"environment,omitempty" example:"dev"`
	Note        string `json:"note"`
	Archive     string `json:"archive,omitempty"`
	Folder      string `json:"folder,omitempty"`
	Scope       string `json:"scope,omitempty"`
	ScopeID     string `json:"scope_id,omitempty"`
	// FromBucket is the objects under a prefix of a bucket on an S3
	// connection the caller's persona may use, inside its bucket_prefix
	// (#2593).
	FromBucket *bucketsource.Source `json:"from_bucket,omitempty"`
	// Source is what the release says it came from, the file's name when
	// given; only ever displayed.
	Source string `json:"source,omitempty" example:"site-1108.zip"`
}

PublishBody names what to publish: a managed-resource archive or folder, or a bucket prefix on an S3 connection, read as the caller, so someone cannot publish a file they could not open.

type ReleaseDetail added in v1.156.0

type ReleaseDetail struct {
	ReleaseView
	Files []site.File `json:"files"`
}

ReleaseDetail is one release with its files and redirect map. A file's bytes are never read back through the portal origin.

type ReleaseList added in v1.156.0

type ReleaseList struct {
	Releases []ReleaseView `json:"releases"`
}

ReleaseList is a site's releases and where each is served.

type ReleaseView added in v1.156.0

type ReleaseView struct {
	site.Release
	ServedIn []string `json:"served_in"`
	// KeptBy is the environments whose release limit keeps it, an
	// "application <name>" release pinning it, or "approval" for a pending
	// request; empty for a release the next sweep removes, or one it removed.
	KeptBy []string `json:"kept_by"`
}

ReleaseView is a release, the environments serving it, and what keeps it from the next sweep (#2602).

type ReplicaTraffic added in v1.162.0

type ReplicaTraffic struct {
	Instance string `json:"instance" example:"platform-7d9f-abc:8080"`
	sitetraffic.Totals
}

ReplicaTraffic is one replica's figures across every site.

type ReplicasView added in v1.162.0

type ReplicasView struct {
	Range     string           `json:"range" example:"24h"`
	Recording bool             `json:"recording"`
	Replicas  []ReplicaTraffic `json:"replicas"`
}

ReplicasView is each replica's traffic over a range.

type RetentionView added in v1.159.0

type RetentionView struct {
	// KeepDefault is how many releases an environment with no limit of its
	// own keeps; 0 keeps every release.
	KeepDefault int `json:"keep_default" example:"50"`
	// Mode is "delete" or "report".
	Mode string `json:"mode" example:"delete"`
	// OrphanGrace is how old an object no release names must be before a
	// sweep deletes it, and Every how often the sweep runs.
	OrphanGrace string            `json:"orphan_grace" example:"24h0m0s"`
	Every       string            `json:"every" example:"24h0m0s"`
	Sweeps      []sitestore.Sweep `json:"sweeps"`
}

RetentionView is release retention as it stands (#2602).

type RollbackBody added in v1.156.0

type RollbackBody struct {
	Environment string `json:"environment" example:"prod"`
	Release     int    `json:"release,omitempty"`
}

RollbackBody returns an environment to an earlier release.

type Sharer added in v1.156.0

type Sharer interface {
	Notify(ctx context.Context, recipient, category string, p notification.Payload) (bool, error)
}

Sharer emails someone that a site was shared with them; nil sends nothing.

type SiteLimits added in v1.156.0

type SiteLimits struct {
	MaxFiles        int   `json:"max_release_files" example:"20000"`
	MaxFileBytes    int64 `json:"max_file_bytes" example:"67108864"`
	MaxReleaseBytes int64 `json:"max_release_bytes" example:"2147483648"`
	CrawlMaxPages   int   `json:"crawl_max_pages" example:"2000"`
	CrawlMaxBytes   int64 `json:"crawl_max_bytes" example:"536870912"`
}

SiteLimits is what a release may hold, shown before an upload.

type SiteList added in v1.156.0

type SiteList struct {
	Sites []SiteView `json:"sites"`
	Total int        `json:"total"`
	// PagesDomain is "" when the deployment has none, so sites have no address
	// of their own.
	PagesDomain string     `json:"pages_domain"`
	Limits      SiteLimits `json:"limits"`
	// CanCreate is whether the caller's persona may create a site.
	CanCreate bool `json:"can_create"`
	// Admin is whether the caller is an administrator.
	Admin bool `json:"admin"`
}

SiteList is the Sites page.

type SiteRequest added in v1.156.0

type SiteRequest struct {
	Name        string `json:"name" example:"careers"`
	Description string `json:"description"`
}

SiteRequest creates a site.

type SiteSettings added in v1.156.0

type SiteSettings struct {
	siteconfig.Settings
	UpdatedBy string `json:"updated_by,omitempty"`
	UpdatedAt string `json:"updated_at,omitempty"`
}

SiteSettings is the Sites section of the settings page.

type SiteTraffic added in v1.162.0

type SiteTraffic struct {
	Requests int64   `json:"requests_24h" example:"1200"`
	P95      float64 `json:"p95_ms" example:"48"`
}

SiteTraffic is the Sites list's figures for one site: its last 24 hours.

type SiteUpdate added in v1.156.0

type SiteUpdate struct {
	Description *string `json:"description,omitempty"`
	Owner       *string `json:"owner_email,omitempty"`
	// Media, when set, is every resource folder the site serves at a URL
	// prefix (#2591); [] removes them all. Anyone who manages the site, for a
	// folder they can read.
	Media *[]site.Mount `json:"media,omitempty"`
}

SiteUpdate changes a site's record; a field left out is left alone.

type SiteView added in v1.156.0

type SiteView struct {
	site.Site
	// Address is the site's production address: where the environment
	// holding the main address is reached, its public domain first, then
	// another domain, then its pages address (#2658); "" when the main address
	// is given to no environment.
	Address string `json:"address"`
	// MoreDomains is how many other domains that environment answers at.
	MoreDomains int `json:"more_domains"`
	// Addresses is where people reach each environment, by name: the first
	// of its domains, otherwise its address on the pages domain, "" for
	// none. manage_site get answers the same (#2607).
	Addresses map[string]string `json:"addresses"`
	// PagesAddresses is each environment's address on the pages domain, by
	// name: the main address for the environment holding it, otherwise
	// <site>--<env>; "" with no pages domain or for an address no certificate
	// can be issued for. It answers only where the deployment's ingress
	// routes it.
	PagesAddresses map[string]string `json:"pages_addresses"`
	// AddressNote says why the site's environments have no address on the
	// pages domain: a two-character site name (#2611). Absent otherwise.
	AddressNote string `json:"address_note,omitempty"`
	// EnvironmentNameRoom is the longest environment name the site can add:
	// its name and "--" leave the rest of one DNS label (#2636).
	EnvironmentNameRoom int           `json:"environment_name_room" example:"32"`
	Domains             []site.Domain `json:"domains"`
	// Permissions is what the caller may do to this site.
	Permissions sitesvc.Permissions `json:"permissions"`
	// Traffic is the site's last 24 hours over the environments the caller
	// sees (#2647), on the Sites list; absent elsewhere.
	Traffic *SiteTraffic `json:"traffic,omitempty"`
}

SiteView is a site as the portal shows it.

type SweepBody added in v1.159.0

type SweepBody struct {
	// Mode is "report", which deletes nothing, or "delete".
	Mode string `json:"mode" example:"report"`
	// Site, when set, sweeps that site alone, by name.
	Site string `json:"site,omitempty"`
}

SweepBody asks for one sweep.

type TrafficPoint added in v1.162.0

type TrafficPoint struct {
	At time.Time `json:"at"`
	sitetraffic.Totals
}

TrafficPoint is one step of the Traffic view's series.

type TrafficView added in v1.162.0

type TrafficView struct {
	Range string `json:"range" example:"24h"`
	// StepSeconds is the width of each point of Series.
	StepSeconds int64 `json:"step_seconds" example:"900"`
	// Recording is false where sites.traffic.enabled is off; nothing is
	// recorded then.
	Recording    bool                          `json:"recording"`
	Environment  string                        `json:"environment,omitempty"`
	Total        sitetraffic.Totals            `json:"total"`
	Series       []TrafficPoint                `json:"series"`
	Environments map[string]sitetraffic.Totals `json:"environments"`
}

TrafficView is a site's traffic over a range (#2647): requests by status class and latency percentiles over time, the range's totals, and the same by environment. Its figures are the platform's own, recorded by every replica into shared rows, so it needs no Prometheus backend.

Jump to

Keyboard shortcuts

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