Private packages

How it works

1. Build the package file with ael package; see Creating a package.
2. Host it where the projects that use it can reach it.
3. Record it in the pack.ael of each project that uses it: its address or path, and its fingerprint.
4. Lock and install: ael pack lock writes the lock file and ael pack install installs it. From then on, the package works like any other: offline, pinned by the lock file, and verified.

Your project always points to a built package file. AEL never builds a package from source when it installs it.

A package file at an https address

{ name = "acme/billing"; version = "=0.3.1"; kind = "runtime"; publisher = "acme";
  source = { kind = "https";
             url = "https://git.example.com/acme/billing/releases/download/v0.3.1/acme-billing-0.3.1.zip";
             digest = "sha256:<64 hex digits>"; };
  features = []; targets = []; capabilities = []; }

• The address uses https, and it points at one file that never changes: the download for one version, never a link that moves to the newest one.
• The address carries no user name, password, query or fragment.
• The file has to match the fingerprint every time it is fetched. If the file at the address ever changes, AEL refuses it.
• If your host redirects the download, AEL never sends your access token to a different host.

A package file inside your project

{ name = "acme/billing"; version = "=0.3.1"; kind = "runtime"; publisher = "acme";
  source = { kind = "local";
             path = "vendor/acme-billing-0.3.1.zip";
             digest = "sha256:<64 hex digits>"; };
  features = []; targets = []; capabilities = []; }

• The path is relative to the project root and uses /. It stays inside the project: no .., no absolute paths and no links that lead outside.
• It is always a built package file, never a folder of source. To change the package, build a new file with ael package, replace the old one, and update the fingerprint.

The fingerprint

The digest field is the file's fingerprint: its SHA-256 value, written sha256: followed by 64 lower-case hex digits. It is computed over the file's bytes, so any standard SHA-256 tool gives the same value.

A fingerprint proves that the file is the one you recorded. It does not prove who made the file: that is your decision when you add a private package from someone else.

Access tokens

Access tokens for your private host stay outside your project files. They are never written to your manifest, your lock file, a package file or AEL's output, and never sent to the official registry.

A new version

1. Build the new version with ael package.
2. Host it at a new address, or at a new path inside the project.
3. Update version, url or path, and digest in each project that uses it.
4. Run ael pack lock and ael pack install.

Leave the old file where it is, so projects still locked to it can install it again, for example on a new machine.

Kept apart from the official registry

• The official registry never hosts or lists private packages, and you cannot upload to it.
• AEL never treats an external package as an official one, even if its name matches. A private package's publisher is your own name, never openeng.
• If a private package cannot be reached, AEL never falls back to an official package of the same name.
• AEL verifies every package before using it, whatever its host: its fingerprint, its contents and how it was built. See Security and provenance.