Documentation
¶
Overview ¶
Package static deploys a built site to a hosted altengine static instance.
THE UPLOAD IS THREE CALLS AND THE MIDDLE ONE DOES NOT TOUCH THE PLATFORM:
- send a manifest — every file's path, size and sha256
- PUT the files it says it does not already have, straight to storage
- activate, which points the site at the new deployment
Files are content-addressed, so step 1 is what makes a redeploy cheap: an unchanged asset is never uploaded again, and a docs site where one page changed uploads one page. That is also why the hashing happens here rather than on the server — the server can only tell you what it is missing if you tell it what you have.
Activation is a pointer move, so a rollback is the same call with an older deployment id and costs nothing: that deployment's files are still stored.
Index ¶
- Constants
- func GitDescribe(dir string) string
- func Manifest(files []File) map[string]manifestEntry
- func PutAll(uploads []Upload, byHash map[string]File, onDone func()) error
- type Activated
- type Config
- func (c Config) Activate(deploymentID string) (*Activated, error)
- func (c Config) Create(files []File, message string) (*Created, error)
- func (c Config) Deployments(cursor string) ([]Deployment, string, string, error)
- func (c Config) Info() (*Site, error)
- func (c Config) UploadPage(deploymentID, cursor string) ([]Upload, string, error)
- type Created
- type Deployment
- type File
- type Site
- type Upload
Constants ¶
const UploadParallel = 8
UploadParallel is how many files are PUT at once. Enough to keep a link busy on a site of small assets, low enough not to look like an attack from one machine.
Variables ¶
This section is empty.
Functions ¶
func GitDescribe ¶
GitDescribe returns a short commit sha for the working directory, or "" when there is no git here. Used as the default deployment label: a list of deployments is only useful if the rows can be told apart, and nobody types a message on every deploy.
func PutAll ¶
PutAll uploads a page of files. `byHash` maps a content hash to the local file holding those bytes — one file may be at several paths, and only one upload is needed for all of them.
Errors are collected and the FIRST is returned rather than aborting mid-flight, because a half-uploaded deployment is not a broken state: it was never activated, nothing points at it, and the next run re-uses everything that did land.
Types ¶
type Activated ¶
type Activated struct {
DeploymentID string `json:"deployment_id"`
FileCount int `json:"file_count"`
TotalBytes int64 `json:"total_bytes"`
URL string `json:"url"`
}
Activated is the answer to publishing a deployment.
type Config ¶
type Config struct {
BaseURL string // e.g. https://api.altengine.net
APIKey string
Instance string // the static instance name, as shown in the console
}
Config is everything needed to reach an instance. Flags win over environment.
func (Config) Activate ¶
Activate points the site at a deployment. Also the rollback: an older id is the same call.
func (Config) Deployments ¶
Deployments lists deploy history, newest first, with the live one named.
type Created ¶
type Created struct {
DeploymentID string `json:"deployment_id"`
FileCount int `json:"file_count"`
TotalBytes int64 `json:"total_bytes"`
MissingCount int `json:"missing_count"`
Uploads []Upload `json:"uploads"`
Cursor string `json:"cursor"`
}
Created is the answer to opening a deployment.
type Deployment ¶
type Deployment struct {
ID string `json:"id"`
// Sequential per site and never reused: the version in `{slug}--v{n}-web`.
Number int `json:"number"`
// That address. Empty unless the deployment is ready and the server has a tenant host.
URL string `json:"url"`
CreatedAt int64 `json:"created_at"`
CreatedBy string `json:"created_by"`
Status string `json:"status"`
FileCount int `json:"file_count"`
TotalBytes int64 `json:"total_bytes"`
Message string `json:"message"`
}
Deployment is one row of deploy history.
type File ¶
type File struct {
// Path as it will be served, always rooted: "/index.html".
Path string
// Absolute path on disk, so the upload step can read it back without walking again.
Local string
Size int64
Hash string
}
File is one file of a site, as walked from disk.
func Walk ¶
Walk hashes every file under root and returns the manifest to send.
NOTHING IS SKIPPED, and dotfiles least of all. A CLI that quietly ignored them would break `.well-known/` — ACME challenges, apple-app-site-association, security.txt — which is exactly the kind of file whose absence is discovered weeks later by something else failing. If a file is in the build output, it is part of the site.
Symlinks — to files AND to directories — are followed when they resolve inside the root and REFUSED when they do not, which is exactly what `altengine dev --static` serves: a site that works locally must not lose a directory on deploy. Following one out of the tree would publish whatever it points at, which on a developer's machine is a short walk from an SSH key; refusing names the file rather than silently dropping it. A directory link back into its own ancestry is refused too, since it would make the site infinitely deep.
type Site ¶
type Site struct {
Name string `json:"name"`
Slug string `json:"slug"`
URL string `json:"url"`
ActiveDeployment string `json:"active_deployment"`
Deployments int `json:"deployments"`
Files int `json:"files"`
StoredBytes int64 `json:"stored_bytes"`
}
Site is what the instance looks like right now.