ply Worker — https://ply.ivar.workers.dev
A Cloudflare Worker that exposes ply as an HTTP API against any smart-HTTP git host. The git client is github:ivarvong/ply#af5cac0372df6caf774d108cbf9229b04af45eb6 (an exact commit of ply main; an operator moves the pin with npm run cd -- bump). The /v1 git API has no storage. GET /view is a public repository viewer, rate-limited by client through a SQLite Durable Object. One Artifacts namespace, public-v0, is served read-only with no token (/r/<repo>, see Public namespace). Feature flags are one R2 object and a service binding (Feature flags). GET / prints the usage text.
Auth
- Gate:
Authorization: Bearer <PLY_TOKEN>on/v1.GET /,GET /view,GET /view.css,GET /r/<repo>, and the/v1reads of the public namespace are public. The token is a Worker secret (cf workers secrets update PLY_TOKEN --worker ply --type secret_text) and is compared in constant time (SHA-256 of both sides, thencrypto.subtle.timingSafeEqual). A missing or wrong token returns 401{code: "unauthorized"}. - Git credential (optional; public repos need none):
Git-Authorization: <value>is sent upstream verbatim asAuthorization.Git-Token: <token>is mapped by host:github.com→Basic x-access-token:<token>,gitlab.*→Basic oauth2:<token>, anything else (Cloudflare Artifacts included) →Bearer <token>. Artifacts accepts Bearer and Basic; both were checked in the smoke run.- Sending both headers is a 400.
- Neither credential appears in a response, trace, error message or log line. ply never records them, and the Worker scrubs every outgoing string as a second layer (
test/worker.test.jsgreps all of these, including a hostile upstream that echoes the header back).
- Remote rules:
remotemust behttps:, on the default port, with no userinfo, query, or fragment. The host is canonicalised (lowercase, no trailing dot —github.com.is rejected rather than stripped). IP literals are refused in every encoding the URL parser accepts (dotted, zero-padded, octal, hex, decimal2130706433, IPv6, IPv4-mapped, IPv4-compatible). So are single-label hosts,localhost/.local/.internal/.lan/.home.arpa/… names, and wildcard-DNS names (nip.io,sslip.io,localtest.me, and the same shape of zone). A path segment of.or.., or an encoded slash, backslash, or dot (%2f,%5c,%2e), is rejected before normalisation. Redirects follow git'shttp.followRedirects=initial: ply follows a 3xx only on the firstGET info/refs(at most three hops, and only when theLocationkeeps the/info/refs?service=…suffix), and every later request, POSTs included, goes to the rewritten base. ply'sallowUrlhook (remoteAllowUrl,src/remote.ts) vets each new base with the same check, on the same origin. A 3xx on a POST, a loop past three hops, or aLocationgit would not rebase to is a 400 with codehttpnaming the target (git cannot use such a remote either). The Worker's fetch wrapper (createGuardedFetch) re-checks every request and never follows a 3xx itself; a 3xx whoseLocationis on another origin or fails the check is a 400bad_requestbefore ply sees it, so a credential never leaves the origin (test/worker.test.js, "redirects").ALLOW_REMOTE_ORIGINS(comma-separated origins) exempts those origins from the public-host rules (http, an IP, a non-default port). Only the tests use it.
Endpoints
| Method | Path | Input | Output |
|---|---|---|---|
| GET | /v1/refs | remote, prefix? | {refs: {name: oid}, head, peeled: {tag: commit}}. An empty repository adds {empty:true, unborn:"refs/heads/main"} and leaves head null |
| GET | /v1/discover | remote | protocol v2 capabilities (agent, fetch, filter, caps, …) |
| GET | /v1/read | remote, ref?, path | the blob, streamed. Headers: content-length, x-ply-ref, x-ply-commit, x-ply-blob, x-ply-mode, x-ply-size. A directory is 400 bad_request (list it with GET /v1/tree), not 404 |
| GET | /v1/tree | remote, ref?, path? | {ref, commit, tree, entries: [{name, mode, oid, type}]} (modes as git ls-tree prints them) |
| GET | /v1/commit | remote, ref? | born: {ref, oid, tree, parents, author, committer, message, signed}. author/committer are {name, email, time, epoch, tz} (time ISO-8601 UTC, epoch the raw seconds, tz as written, e.g. +0530). message is the raw body. signed means a gpgsig header is present (not verified). Fetches the commit only (tree:0, deepen 1; blob:none when the server refuses that). Empty repository (unborn HEAD, or that same branch by name): {empty:true, ref:"refs/heads/main", oid:null, tree:null, parents:[], author:null, committer:null, message:null, signed:false}. A different missing ref stays 404. A born response does not grow an empty field |
| POST | /v1/edit | {remote, ref?, base?, author, committer?, message, head?, changes?} or the one-file form {path, find?, replace?, content?, delete?, to?, mode?} | {outcome, ref, oid, oldOid, noop, tree, newCommit, oldCommit}. newCommit/oldCommit alias oid/oldOid. A root commit and any newly created ref have oldOid: null |
| POST | /v1/branch | {remote, ref, from?} | 201 {outcome:"created", ref, oid, oldOid:null}. from is a branch or a 40-hex commit. Omit from only when HEAD is born |
| DELETE | /v1/branch | {remote, ref, oid?} | {outcome:"deleted", ref, deleted}. CAS on oid (default: the oid ls-refs shows now) |
| POST | /v1/tag | {remote, name, target, annotated?, message?, tagger?} | 201 {outcome:"tag", ref, oid, commit, annotated}. Lightweight unless annotated, message, or tagger is set. target is a branch or a commit id |
| DELETE | /v1/tag | {remote, name, oid?} | same compare-and-swap as DELETE /v1/branch |
| POST | /v1/merge | {remote, ref?, from, author?, committer?, message?, fastForwardOnly?, noFastForward?} | {outcome, ref, oid, oldOid, noop, …} where outcome is merge, fast_forward, or up_to_date. from is a branch or a 40-hex commit. author and committer are separate stamps, each with its own time and tz |
| POST | /v1/rebase | {remote, ref, onto?, committer, author?, squash?, message?} | {outcome, ref, oid, oldOid, …} where outcome is rebase, squash, fast_forward, or up_to_date. onto is a branch or a 40-hex commit. author.time and committer.time are independent |
| POST | /v1/cherry-pick, /v1/revert | {remote, ref?, commit, committer, message?, allowEmpty?} | {outcome, ref, oid, oldOid, noop, tree?}. A patch already applied, and only when both sides added and deleted the same paths, is {outcome:"empty", noop:true, oid:<tip>}. allowEmpty:true writes that empty commit. If the target also has its own adds or deletes, the response is 409 merge_conflict (allowEmpty does not override it) |
| GET | /v1/flags | the cached flag ruleset {revision, cache, environment, flags}. Writes are not this route | |
| POST | /v1/flags/eval | {unit, attributes?, keys?} | {revision, cache, flags:[{key, variant, reason, bucket}]}. Per-unit; the response is no-store |
Flag writes are not HTTP (PUT/POST/PATCH/DELETE /v1/flags are 405). Operators call scripts/flags, which talks to the ply-flag-operator Worker. That Worker checks FLAG_OPERATOR_TOKEN and calls FlagControl (setRollout, setTargeting, getConfig) over a service binding. The design, the basis-point allocation, and the staleness bound are in Feature flags.
refdefaults to the remote's HEAD branch. On an empty repository HEAD is an unborn symref (refs/heads/mainon Artifacts and ongit init -b main).GET /v1/commitreports that asempty: trueand names the symref.POST /v1/editwith norefcreates the root commit on that branch. Merge, rebase, cherry-pick, revert, and branch-from cannot use an unborn HEAD: the response is 400 naming the missing field (ref,onto, orfrom). Naming that unborn ref explicitly is 404ref refs/heads/main is unborn; create a commit before ….- On reads, short names resolve the way
git rev-parsedoes: tags win over branches, and a 40-hex commit oid is also accepted. An abbreviated oid (7–39 hex) resolves only when it matches one advertised ref (a branch tip, a tag tip, or a peeled tag commit); otherwise the response is400bad_requestasking for the full oid. On writes, short names meanrefs/heads/<name>. A 40-hex string is a commit id, never a branch of that name. The zero oid is 400; omit the field to mean "no parent" or "HEAD". authorandcommitterare{name, email, tz?, time?}.tzis+HHMMor-HHMMin the civil range −12:00 through +14:00 (ply'svalidateIdent; a bad zone is 400bad_request).timeis unix seconds. Omittedtzis+0000. Omittedtimeis now. Merge and rebase write each stamp with its own time and zone.- One edit is
{path, find, replace}. An empty or omittedfindcreates the file (content, orreplace, or empty).delete: truedeletes it.torenames it.modeis100644(default),100755, or120000. Several changes go inchanges: [{op, path, content?, find?, replace?, to?, mode?}]withopofcreate,write,edit,delete, orrename, applied in order. Passchangesor a singlepath, not both. A distinctcommitteris written on the commit. One find/replace of an existing file still streams through ply. baseomitted on a missing ref is a root commit (no parent), pushed with compare-and-swap old oid all zeros.baseas another branch, or as a 40-hex commit, starts a new ref whose parent is that commit.baseof zeros is 400 and nothing is fetched. On an existing branch, omitbaseto commit on the tip.- Every
/v1response iscache-control: no-store(a credentialed API: nothing it answers is stored, not even atree/read/commitat a full oid). Every response carriesx-ply-version(the Workers version id, which the canary checks) andx-ply-build(ply=<commit> ply-web=<commit>, injected at build time).x-ply-traceis omitted when it would be empty. headon edit is a precondition: if the branch is not athead, the response is 409cas_conflictand nothing is pushed.headof zeros means the ref must not exist yet.hintis ply's soft head hint for a one-file edit.- Every write shares
{outcome, ref, oid, oldOid, noop}.newCommitandoldCommitare deprecated aliases ofoidandoldOid.ontois a deprecated alias of the commit the write was based on.noopis true fornoop,empty, andup_to_date.
Empty repository, in order
This is the whole lifecycle against a brand-new repository. Nothing is seeded with stock git. Replay it against Artifacts after deploy (Git-Token is the Artifacts bearer). Pass oids from responses into later requests.
GET /v1/commit?remote=→ 200{empty:true, ref:"refs/heads/main", oid:null, tree:null, parents:[], author:null, committer:null, message:null, signed:false}.GET /v1/commit?remote=&ref=mainis the same body.GET /v1/commit?remote=&ref=nopeis 404.POST /v1/edit{remote, message, author:{name, email, tz, time}, changes:[{op:"create", path, content, mode?}, …]}→ 200{outcome:"commit", ref:"refs/heads/main", oid, oldOid:null, newCommit, oldCommit:null, noop:false, tree}. The ref is created with compare-and-swap old oid000…0and the commit has no parent. A 40-hexbaseis that parent commit.000…0is 400.POST /v1/edit{remote, message, author, committer:{name, email, tz, time}, changes:[{op:"edit", path, find, replace}, {op:"create", …}, {op:"delete", path}, {op:"rename", path, to}]}.POST /v1/branch{remote, ref, from}→ 201{outcome:"created", ref, oid}.fromis a branch or a 40-hex commit. Omitfromonly when HEAD is born.000…0is 400 and nothing is pushed. An existing ref is 409{code:"ref_exists", retry:"no", oid}.DELETE /v1/branch{remote, ref, oid}— a stale oid is 409{code:"stale_expected", retry:"fresh", expected, actual, oid:actual}.POST /v1/tag{remote, name, target, annotated?, message?, tagger?}andDELETE /v1/tag{remote, name, oid?}.POST /v1/merge{remote, ref?, from, author, message?}.POST /v1/rebase{remote, ref, onto?, committer, squash?, message?}.POST /v1/cherry-pick{remote, ref?, commit, committer, message?, allowEmpty?}— a patch already applied, when both sides added and deleted the same paths, is 200{outcome:"empty", noop:true, oid:<tip>}.allowEmpty:truewrites an empty commit (same tree, new commit). A target branch that also has its own adds or deletes is 409merge_conflict: ply will not guess which rename git would pair.allowEmptydoes not apply to that 409.POST /v1/revert{remote, ref?, commit, committer, message?, allowEmpty?}.
An empty repository's HEAD is an unborn symref only when the server advertises ls-refs=unborn (git's default, and git's own client sends the argument only then). The first HEAD read against an origin in an isolate pays one info/refs GET so ply can see that bit (git.upload-pack discover in the trace, phase ls-refs in x-artifacts-ray and Server-Timing). The bit is remembered for the isolate and passed back to ply, so later HEAD reads on that origin are the ls-refs alone. A server configured lsrefs.unborn=allow or ignore is reported as an absent HEAD, matching git ls-remote.
GET / prints the same sequence.
- JSON request bodies are capped at 1 MiB (413 above that).
WRITES(a text binding incloudflare.config.ts) must beonfor the POST/DELETE endpoints; otherwise they return 501unsupported.
Errors
Every failure is JSON {code, message, retry}. code comes from ply's error table (src/errors.ts), and retry is that table's policy: yes, fresh (re-read, then retry), no, or read (the push may have landed; read the ref back first). Merge conflicts add conflicts and reasons. match_count adds matches. auth adds upstreamStatus. cas_conflict adds expected and actual when known (null means the ref was to be, or is, absent). push_partial adds landed and rejected. The table below covers every ply code (src/status.ts is type-checked exhaustive against ply's CODES).
| code | HTTP | why this status |
|---|---|---|
bad_request | 400 | input, including a refused remote |
auth | 401 or 403, the upstream's own status | the caller needs to know whether its credential was missing or not good enough |
not_found | 404 | ref, path or repo |
cas_conflict | 409 | the branch moved, so re-read and retry (retry: fresh). git 2.50 and later say incorrect old value provided; ply classifies that string as cas_conflict |
ref_exists | 409 | creating a branch or tag that already exists (retry: no). The body includes oid, the current target. Checked before the push, so a lost race that Artifacts reports as stale ref is mapped here too |
stale_expected | 409 | deleting a ref whose oid is not the current target (retry: fresh). The body includes expected, actual, and oid (the actual) |
merge_conflict, not_fast_forward, push_rejected, push_partial | 409 | conflict with the repository's current state |
match_count, lfs_pointer, not_linear, unrelated_histories | 422 | the request is well-formed but cannot apply to this content. Retrying it unchanged cannot work, even against a fresh state. That is the difference from 409 |
limit_exceeded | 413 | |
rate_limited | 429 | |
upstream_5xx, network, protocol, pack_corrupt, not_git, remote_error, http, ambiguous | 502 | the upstream misbehaved. Check retry before retrying: ambiguous is read |
timeout | 504 | |
aborted | 499 | the caller went away |
unsupported | 501 | including writes when they are disabled |
read_only | 403 | a write whose remote is in the public namespace, with or without a bearer or git credential |
internal | 500 | a bug; an error without a known code is reported as this |
Tracing
?trace=1on a JSON endpoint addstrace: [{name, ms, status, attrs, events}]with ply's spans: the spans ply's Tracer hands itsonEnd(the plain-value form of the OTLP spans ply emits anywhere; no OTLP is built for a request)./v1/readstreams raw bytes and has no JSON to carry spans. Instead,?trace=1adds anx-ply-traceheader summarising every span that finished before the first byte, asname;dur=ms, …. The blob's own span finishes after the response is sent, so it shows up only in the request's log line (stream: ok|error).Every request writes one structured log line (
msg: "ply.request") with id, method, path, upstream host (never the path or the credential), status, ms, round trips, how many fetches used the blob:none fallback, and pack-cache hits. Workers Observability logs and traces are enabled, andredact_query_stringkeepsremote=out of the platform's request records. Each response carriesx-ply-request-id.Every
/v1response that talked to the remote, including 4xx and 5xx, carriesx-artifacts-rayandServer-Timing. The ray header is the upstreamcf-rayof each git HTTP exchange, in start order:ray-header = entry *( ", " entry ) [ ", " overflow ] entry = phase "=" ray ";dur=" duration overflow = "overflow=" 1*DIGIT phase = "ls-refs" / "fetch" / "receive-pack" ray = cf-ray / "-" / "no-response" cf-ray = 16HEX "-" 3ALPHA duration = 1*DIGITls-refsis info/refs and v2 ls-refs.fetchis each upload-pack fetch, including a blob:none retry.receive-packis the advertisement and the push.-is a response with no ray id (the raw header is not echoed).no-responseis a call that failed before headers. Past 32 entries the rest areoverflow=<count>.Server-Timingrepeats the same phases and durations, thentotalfor the Worker. The matching spans gaingit.upstream.cf_ray,git.upstream.phase, andgit.upstream.dur_ms. The viewer sends the same header. It contains no URL, credential, or repository name.
Servers that refuse filter tree:0
Cloudflare Artifacts refuses filter tree:0. ply learns this from the 400 and falls back to blob:none, which brings more trees per fetch (see ply's README). The Worker keeps what it learned per origin for the life of the isolate, so only the first request on an isolate pays for the 400.
Public viewer (/view)
GET /view is a server-rendered browser for a public smart-HTTP repository. It does not use PLY_TOKEN and it never reads Authorization, Git-Token, Git-Authorization, or Cookie. A URL with userinfo is rejected, not turned into a credential. /v1 is unchanged: same gate, same credential headers. /v1 and the viewer share one isolate-wide, per-origin quirks map (src/quirks.ts): a server that rejects filter tree:0 costs that 400 and the blob:none retry once per isolate, and later pages ask for blob:none directly (the waterfall says which). Until 2026-10-31 the viewer re-learned it on every page; on Artifacts that 400 was ~110–150 ms of every page.
The home form accepts an https URL, github.com/owner/repo, owner/repo (github.com), or git@host:path (the ssh user is dropped, then the allowlist runs). Shareable URLs: /view/<host>/<repo path>?ref=&path= (path may use / or %2F). A path segment of . or .., a backslash, or an encoded slash, backslash, or dot in the URL path (and an encoded dot or backslash in ?path=) is rejected on the r …