Documentation
¶
Overview ¶
Package sharedproxy is contract:cli.shared-proxy v1: the registration file a project writes under a shared host proxy's nginx/shared/ directory.
Purpose: EPIC ADOPT D2 (P7-ADOPT-03; read again by P7-ADOPT-21 and doctor). The owner of a shared nginx (NGINX_MODE=shared) keeps `_owner.json`; every fronted project nested under it keeps `<project>.json`. Both say which server names, services and files the project put on the proxy, so no project deletes or shadows another's. Inputs: registration bytes, or the nginx/shared/ directory. Outputs: Registration, Marshal (deterministic bytes), Parse (validated), Load (every registration), RegisteredFiles (a set of owner-relative paths). Constraints: keys are sorted and arrays sorted, `_generated` first; the file name must equal `<project>.json`; a duplicate project is refused; project_dir must resolve under the owner dir. Imports the standard library and internal/nginxtopo (L0) only.
Index ¶
- Constants
- Variables
- func Detach(ctx context.Context, ownerDir string, regs ...Registration) error
- func DirOf(ownerRoot string) string
- func FileName(project string) string
- func Leave(ctx context.Context, ownerDir, project string) ([]string, error)
- func Lock(ctx context.Context, ownerDir string) (func(), error)
- func Marshal(r Registration) ([]byte, error)
- func OwnerNginx(ctx context.Context, ownerDir string) (string, error)
- func Quarantine(ownerDir string, set Set, reg Registration) ([]string, error)
- func Restore(ownerDir string, reg Registration) ([]string, error)
- func Unregister(ownerDir, project string) ([]string, error)
- func ValidFile(rel string) bool
- func ValidProject(name string) bool
- func Write(dir, name string, r Registration) error
- type Outcome
- type Registration
- type Role
- type Set
- type Site
Constants ¶
const ( Generated = "GENERATED BY nself build - DO NOT HAND EDIT" SchemaVersion = "1" OwnerFile = "_owner.json" Dir = "shared" )
Generated is the `_generated` marker; SchemaVersion the contract version; OwnerFile the owner's file name; Dir the directory under the owner's nginx/.
const CertMarker = ".nself-project"
CertMarker is the file installCert writes into a certificate directory it created for a project; it holds the project name. A certificate file is removable only from a directory carrying this marker (a hand-made registration cannot name the owner's own pair).
const LockFile = ".lock"
LockFile is the lock file name inside nginx/shared/.
const QuarantineDir = "quarantine"
QuarantineDir is the directory name under nginx/shared/ that holds quarantined files.
Variables ¶
var ErrOwnerNotRunning = errors.New("the shared proxy owner's nginx is not running")
ErrOwnerNotRunning is returned (wrapped) when the owner's nginx container is not running. Match with errors.Is.
Functions ¶
func Detach ¶
func Detach(ctx context.Context, ownerDir string, regs ...Registration) error
Detach is detach under the owner lock.
func DirOf ¶
DirOf returns the registration directory of the owner project at ownerRoot: <ownerRoot>/nginx/shared (the nginx dir comes from nginxtopo, the one owner of that path).
func Lock ¶
Lock takes the exclusive lock of ownerDir's shared proxy and returns its release function. A caller that writes into the owner outside this package (the fronted build) takes it too.
func Marshal ¶
func Marshal(r Registration) ([]byte, error)
Marshal returns the deterministic file bytes (two-space indent, final newline).
func OwnerNginx ¶
OwnerNginx returns the name of the owner's running nginx container.
func Quarantine ¶
func Quarantine(ownerDir string, set Set, reg Registration) ([]string, error)
Quarantine is quarantine under the owner lock.
func Restore ¶
func Restore(ownerDir string, reg Registration) ([]string, error)
Restore is restore under the owner lock.
func Unregister ¶
Unregister is unregister under the owner lock.
func ValidFile ¶
ValidFile reports whether rel is a path a registration may list: exactly nginx/sites/<name> or ssl/certificates/<dir>/fullchain.pem|privkey.pem, every element plain (no `..`, `.`, empty, backslash), never absolute.
func ValidProject ¶
ValidProject reports whether name may be a project in a registration: a plain token that cannot reach the reserved owner file (`_owner.json`) or leave the directory when used as `<project>.json` or as the `<project>.` file prefix.
func Write ¶
func Write(dir, name string, r Registration) error
Write writes r as `<project>.json` (or `_owner.json` for name) into dir, creating dir, via a temp file and rename.
Types ¶
type Outcome ¶
type Outcome struct {
Attached []string // projects the owner nginx is connected to after the call
Missing []string // projects skipped because their network does not exist
Quarantined []string // projects whose files were moved out of the owner
Reloaded bool
}
Outcome describes one Attach call.
type Registration ¶
type Registration struct {
Generated string `json:"_generated"`
Files []string `json:"files"`
Network string `json:"network"`
Project string `json:"project"`
ProjectDir string `json:"project_dir"`
SchemaVersion string `json:"schema_version"`
ServerNames []string `json:"server_names"`
ServiceNames []string `json:"service_names"`
UpstreamHosts []string `json:"verbatim_upstream_hosts"`
}
Registration is one project's entry. Field order is the key order of the written file (sorted; `_generated` sorts first).
func Implicated ¶
func Implicated(set Set, text string) []Registration
Implicated returns the registered projects (never the owner) that own a file the nginx output names. A site file matches by its base name (the container path differs from the host path), a certificate file by `certificates/<dir>/<file>`. Sorted by project.
func New ¶
func New(project, projectDir string) Registration
New returns a Registration for project with the constant fields set.
func Parse ¶
func Parse(name string, data []byte, ownerDir string) (Registration, error)
Parse decodes and validates data read from file name `name` (the base name) of an owner directory ownerDir. The owner file's project is not checked against its name, every other file's must equal `<project>.json`.
func (*Registration) Sort ¶
func (r *Registration) Sort()
Sort sorts and de-duplicates every list and replaces nil with an empty list.
type Set ¶
type Set struct {
Owner *Registration // _owner.json, nil when absent
Projects []Registration // sorted by project
}
Set is every registration found in one nginx/shared/ directory.
func Load ¶
Load reads dir (`<owner>/nginx/shared`). A missing dir is an empty Set. A file that does not validate, or a second registration of one project, is an error naming the file: a fail-closed read, never a skipped entry.
func (Set) Find ¶
func (s Set) Find(project string) *Registration
Find returns the registration of project, or nil.
func (Set) Others ¶
func (s Set) Others(project string) []Registration
Others returns the project registrations other than project's own.
func (Set) RegisteredFiles ¶
RegisteredFiles returns every path (relative to the owner dir) any project registration lists, as a set. The owner's own file lists none.
func (Set) Removable ¶
Removable reports whether project may delete rel (owner-relative): a valid registered path that no other project lists, that does not pass through a symlink (an ACME-managed pair is a symlink, and is never removed here) and, for a certificate file, that sits in a directory this project created and, for a site file, that is named `<project>.*` and carries this project's generated-by marker (siteOwnedBy). A registration alone never makes another project's file, or the owner's own, removable.
Source Files