Docs
rpm is the registry for Auk packages, the ones raft installs. Anyone can browse and download. Publishing needs an account.
What a package is
A folder with a raft.toml, a src/lib.auk, and usually a README.md. Those files and everything else under src/ are what gets published, and exactly what raft's checksum covers.
[package]
name = "geo" # a-z, 0-9, _; starts with a letter
version = "0.1.0" # MAJOR.MINOR.PATCH
effects = ["fs"] # the most this package and its dependencies may do
# optional, shown on the package's page
description = "Shapes and areas"
license = "MIT"
repository = "https://example.com/you/geo"
keywords = ["math", "geometry"]
[deps]
json = "^0.1"
Effects
A package lists what it can touch. raft checks every dependency edge, so a package can never do more than the project that installs it allows. Each page here shows them up front; pure means none at all.
| Effect | Lets a package |
|---|---|
| fs | read and write files |
| net | open network connections |
| time | read the clock and sleep |
| rand | use random numbers |
| env | read arguments, environment variables and stdin |
| proc | run other programs and exit the process |
| audio_out | play sound |
| gui | open windows |
| ffi | call C code, which can do anything |
Publishing
In the browser: sign in, open Publish and choose the package's folder.
From a terminal or CI: create a token on your account page, then run the registry's own client from a checkout of rpm:
RPM_TOKEN=rpm_… auk run src/main.auk publish path/to/package --to http://rpm.auk-lang.org
The rules:
- A version is permanent. It can be yanked, never changed or replaced.
- The first to publish a name owns it; owners can add other owners.
- Every dependency must already be in the registry with a version that matches, and its effects must be among the ones your package lists.
- Path dependencies (
{ path = "../x" }) can't be published. - At most 500 files and 4 MB per version.
Publishing from a git repository
Instead of uploading, point the registry at a repository: on Publish for a new package, or in a package's settings. It works with GitHub, GitLab and any public https repository.
- A release is a tag that names a version:
v1.2.3or1.2.3. In a repository of several packages,<name>-v1.2.3,<name>/v1.2.3or<name>@1.2.3, with the package's folder given when linking. - The tag's
raft.tomlmust say the same version, or the release is skipped. Every other publishing rule applies too. - A linked package is checked every 30 minutes (unless you turn that off). To publish the moment you tag, have CI ask:
curl -X POST http://rpm.auk-lang.org/api/v1/pull \
-H "Authorization: Bearer $RPM_TOKEN" \
-d '{"url": "https://github.com/you/geo"}'
Private repositories aren't supported: the registry never sends credentials.
Yanking hides a version from new installs without breaking projects that already lock it. Do it in the package's settings.
Installing
raft add <name> reads a registry directory today. This server keeps one, always holding the newest unyanked version of every package, at <data>/registry. On the machine that runs the registry:
RAFT_REGISTRY=/path/to/rpm/data/registry raft add geo
Fetching over the network isn't in raft yet. The API below serves everything it needs: the index, every version's files, and the checksum raft.lock records.
API
JSON under /api/v1. Reading needs no account. Writing needs Authorization: Bearer <token>.
| Request | Answers |
|---|---|
GET /api/v1/packages?q=&effect=&sort= | search: up to 100 packages |
GET /api/v1/index | every package with all its versions, dependencies, effects and checksums |
GET /api/v1/packages/<name> | one package and its versions |
GET /api/v1/packages/<name>/<version> | one version (latest works) |
GET /api/v1/packages/<name>/<version>/download | its files, base64-encoded, with the checksum |
POST /api/v1/packages | publish: {"files": [{"path": "raft.toml", "base64": "…"}, …]} |
POST /api/v1/packages/<name>/<version>/yank · /unyank | yank or restore a version |
POST /api/v1/pull | pull releases from a git repository: {"url": "https://…", "dir": ""}; answers where to watch (/api/v1/pulls/<id>) |
GET /api/v1/me | who a token belongs to |
Errors come back as {"error": "…"} with a 4xx status.