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 will write the lock file and ael pack install will install it. From then on, the package will work like any other: offline, pinned by the lock file, and verified.

Your project will always point to a built package file. AEL will never build 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 will use https, and it will point at one file that never changes: the download for one version, never a link that moves to the newest one.
• The address will carry no user name, password, query or fragment.
• The file will have to match the fingerprint every time it is fetched. If the file at the address ever changes, AEL will refuse it.
• If your host redirects the download, AEL will never send 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 will be relative to the project root and use /. It will stay inside the project: no .., no absolute paths and no links that lead outside.
• It will always be 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 will be the file's fingerprint: its SHA-256 value, written sha256: followed by 64 lower-case hex digits. It will be computed over the file's bytes, so any standard SHA-256 tool gives the same value.

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

Access tokens

Access tokens for your private host will stay outside your project files. They will never be written to your manifest, your lock file, a package file or AEL's output, and never sent to the official registry. How you will provide a token to AEL is not settled yet.

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 will never host or list private packages, and you will not be able to upload to it.
• AEL will never treat an external package as an official one, even if its name matches. A private package's publisher will be your own name, never openeng.
• If a private package cannot be reached, AEL will never fall back to an official package of the same name.
• AEL will verify every package before using it, whatever its host: its fingerprint, its contents and how it was built. See Security and provenance.