static

package
v0.2.37 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 16 Imported by: 0

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:

  1. send a manifest — every file's path, size and sha256
  2. PUT the files it says it does not already have, straight to storage
  3. 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

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

func GitDescribe(dir string) string

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 Manifest

func Manifest(files []File) map[string]manifestEntry

Manifest turns walked files into the request body's `files` map.

func PutAll

func PutAll(uploads []Upload, byHash map[string]File, onDone func()) error

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

func (c Config) Activate(deploymentID string) (*Activated, error)

Activate points the site at a deployment. Also the rollback: an older id is the same call.

func (Config) Create

func (c Config) Create(files []File, message string) (*Created, error)

Create opens a deployment and returns the first page of files to upload.

func (Config) Deployments

func (c Config) Deployments(cursor string) ([]Deployment, string, string, error)

Deployments lists deploy history, newest first, with the live one named.

func (Config) Info

func (c Config) Info() (*Site, error)

Info reports where the site lives and which build is answering.

func (Config) UploadPage

func (c Config) UploadPage(deploymentID, cursor string) ([]Upload, string, error)

UploadPage fetches the next page of presigned URLs.

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

func Walk(root string) ([]File, error)

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.

type Upload

type Upload struct {
	Hash            string            `json:"path_hash"`
	Size            int64             `json:"size"`
	URL             string            `json:"upload_url"`
	Method          string            `json:"method"`
	RequiredHeaders map[string]string `json:"required_headers"`
}

Upload is one presigned PUT the client must perform.

Jump to

Keyboard shortcuts

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