A small server for a versioned CDN: it serves bash scripts, npm packages and shared configurations from a folder of
frozen versions, with their SHA-256 checksums and a .tar.gz archive of each one. It reads the folder once at startup
and needs no database.
- Versioned URLs,
/<type>/<project>@<version>/<file>:@latestand partial versions (@6,@6.1) resolve to the newest stable release, a pre-release only when no stable one matches or by its exact number (@6.0.0-pre). - Real content types and
nosniff; a strongETag(the SHA-256 of the bytes), conditional requests,RangeandHEADas RFC 9110 says; the files of an exact version are cached for a year (immutable), those reached through@latestor a partial version for 5 minutes. - JSON listings, SHA-256 checksums (
?checksums), a reproducible.tar.gzarchive (?download), a changelog with release dates, a search, a route manifest (/manifest) and a health check (/health). - Optional pages for browsers (
"ui": true): the packages by type, a project with its versions and the README of the latest one, a version with its files, and a search, on the same paths as the JSON listings, and the docs of dropr itself (docs/) at/-/docswithui.docs. - Deprecated projects (a
.deprecated.jsonnext to their versions) stay reachable, and every answer of the project carries aDeprecationheader and aLinkto the successor. - Files are served from inside their version folder only: a symlink is followed only when its target stays inside.
- A rate limit per client and overall (
429withRetry-After; preflights and configured assets are not counted), CORS open to every origin with the useful response headers exposed, and one JSON error body (status,error,message) for every error the server answers itself. - A core that uses no Node API, importable alone as
dropr/core(src/core/, checked bytsc -p tsconfig.core.jsonand run in a context that has only the web globals): only the scan, the file reader and the command line depend on Node.
npm install droprNeeds Node.js 24 or later.
Lay the versions out as packages/<type>/<project>/<version>/ and give each project a .versions.json with the release
date of every version:
packages/bash/hello/.versions.json { "1.0.6": { "date": "2025-09-12" } }
packages/bash/hello/1.0.6/hello
npx dropr check # reports what the server would skip, without listening
npx dropr serve # indexes the packages and listens on port 4000curl -O http://localhost:4000/bash/hello@latest/hello # a file
curl http://localhost:4000/bash/[email protected] # the files of a version, with their size
curl "http://localhost:4000/bash/[email protected]?checksums" # their SHA-256
curl -OJ http://localhost:4000/download/bash/[email protected] # the whole version, as hello-1.0.6.tar.gzdropr serve [config] [--port 4000] [--packages ./packages] [--index file] # index the packages and listen
dropr check [config] [--packages ./packages] # check the config and the packages
dropr index [config] [--packages ./packages] [--out file] # print the index of the packages as JSON- The config is the file named, else
dropr.config.jsonof the working folder, else the defaults. A named file must exist. --portwins over$PORT, which wins overportin the config;--packageswins overpackagesDir.-h,--helpshows the usage and-v,--versionthe version; both exit with0.- Exit codes:
0on success,1for an invalid config, an invalid--port,PORTor--packages, or a port that cannot be taken,2for a command line that is not understood.checkalso exits with1when the packages folder is not a folder or cannot be read, whileserveonly logsNo packages folder at ...and starts with an empty index; entriescheckskips are only reported.indexexits with1in those two cases too, and when--outcannot be written;--portbelongs toserveand--outtoindex. serve --index fileserves an index written bydropr indexinstead of scanning at startup. Each file of the index is looked at once, without being read, and the server refuses to start (exit1, the first problems named) when a file is missing, is not a regular file or has another size. A change of content that keeps the size, and a file the index does not list, go unnoticed: write the index again after any change of the folder.indexprints the index thatservebuilds at startup, or writes it to--out(relative to the working folder, its folders made when missing, outside the packages folder). What the scan skips goes to the error output and stays out of the index, which is read back throughloadIndexbefore it is printed, so the same tree gives the same bytes.
{
"name": "dropr",
"port": 4000,
"packagesDir": "packages",
"clientIp": { "header": "x-real-ip" },
"rateLimit": { "window": 10, "client": 100, "global": 1000 },
"manifest": { "baseUrl": "https://dropr.example.com" },
"assets": { "/robots.txt": "robots.txt" },
"ui": false
}| Key | Default | Description |
|---|---|---|
name |
"dropr" |
Shown by /health, /manifest and the startup banner |
port |
4000 |
Port to listen on, from 0 (a free port) to 65535; --port and PORT take 1 to 65535 |
packagesDir |
"packages" |
Folder of the packages, resolved against the folder of the config file |
clientIp.header |
null |
Header that names the client; set it only behind a proxy that rewrites it |
rateLimit.window |
10 |
Window in seconds |
rateLimit.client |
100 |
Requests per client over a sliding window |
rateLimit.global |
1000 |
Requests over a fixed window, null for no cap |
manifest.baseUrl |
required | Base URL of the instance, http or https, with no trailing slash; without a config file, http://localhost:<port> |
manifest.params |
{} |
Overrides of the texts of /manifest (manifest.routes does the same per route) |
assets |
{} |
A URL path mapped to the file served there, read at startup |
ui |
false |
true, or an object, to answer a browser with pages (see Pages); the JSON stays what every other client gets |
Unknown keys are refused. Without clientIp.header the client is the socket address, and X-Forwarded-For is never
read. A refused request does not count against the limit, and a 429 tells in Retry-After how many seconds to wait.
Assets and OPTIONS preflights are answered before the limit and never count against it.
- A version folder is named
X.Y.ZorX.Y.Z-tagas semver.org writes them (no leadingv, no leading zero, no+build). A type or project is named with letters, digits,.,_and-, starting with a letter, a digit or_; a type may not bedownload,health,manifestorsearch(nor the first segment of a configured asset), and a project may not belist. Any other folder is logged and left out. - Every version needs a day in the
.versions.jsonof its project:{ "1.0.6": { "date": "YYYY-MM-DD" } }. The day must be a real one between 1970-01-01 and today (UTC); a version with a missing, malformed or future day is logged and left out. The day becomes theLast-Modifiedof its files and the date of its archive entries. - A project is deprecated with a
.deprecated.json:{ "date": "YYYY-MM-DD", "message": "...", "successor": "/npm/other" }. All three fields are required, the successor being a URL reference with no space,<,>,"or non-ASCII character; a notice that fails is logged and the project is served without it. - The folder is read once at startup: a version, a file, a
.versions.jsonor a.deprecated.jsonchanged later needs a restart. What the scan leaves out is logged, mostly with a line that starts withSkipping, and never stops the server.dropr checkruns the same scan and reports every logged line as a problem, then printsN problems reported above; it still exits with0.
| Route | Description |
|---|---|
/ |
Every type, project and version |
/<type> |
Projects of a type |
/<type>/<project> |
Versions of a project, latest included |
/<type>/<project>@<version> |
Files of a version, with their size |
/<type>/<project>@<version>/<path> |
A file, or the listing of a folder |
/<type>/<project>@<version>?checksums |
SHA-256 of every file of a version |
/<type>/<project>@<version>?download |
The version as .tar.gz |
/<type>/<project>/changelog |
Versions with their release date |
/download, /download/<type> |
Archive links (latest and every version), of every type or of one |
/download/<type>/<project>@<version> |
The version as .tar.gz, the latest one if omitted |
/search?q=<term> |
Projects whose name contains the term, or every project of a type |
/manifest |
Description of every route |
/health |
Name, status, version, uptime, package count and memory |
Any path listed in assets |
The configured file (GET and HEAD), served before the routes |
With "ui": true, a browser gets a page where every other client gets the JSON, from the same URL. The server reads the
Accept header: a page is sent when text/html (or application/xhtml+xml) is named with a higher quality than
application/json, so curl, fetch() and scripts, which send */* or no Accept, keep the JSON they always had.
The answers of those paths carry Vary: Accept.
ui can be an object that sets the look, as in { "accent": "#1d4ed8", "logo": "/logo.svg", "favicon": "/favicon.ico" }.
accent is a color written #rrggbb, and logo and favicon are the URL path of an entry of assets. The accent
colors the buttons and the focus ring; the links and the ring get the closest shade that reads at 4.5:1 on the light and
the dark theme, and a button gets a white or a dark label, whichever reads better. The logo is shown before the name,
which stays the title. An empty object, like true, keeps the default look.
"docs": true adds the docs of dropr (overview, configuration, routes), written in docs/, at /-/docs. The path
starts with a dash, which no type or project can, so it never hides a package. A docs page has no JSON form, so it is
sent to every client without Vary; with the docs off, /-/docs answers as any route that does not exist.
| Path | Page |
|---|---|
/ |
Every type with its first projects, and a search box |
/search?q=<term> |
The results; an empty search lists every package, not a 400 |
/<type> |
The projects of the type |
/<type>/<project> |
How to use it, its versions, the deprecation and the README |
/<type>/<project>@<version> |
The files of the version, its archive and checksums, README |
/<type>/<project>@<version>/<folder>/ |
The files of a folder |
| A missing route, type, project or version, a bad percent code | A page with the same message as the JSON error and its status |
Files are never pages: a file, a missing file, ?checksums, ?download, /manifest, /health and /download answer
as before, and a file keeps one form and one cache entry. The pages of a deprecated project carry its Deprecation and
Link headers, as its JSON does. The README is the README.md (or README.markdown) at the
root of a version, up to 256 KiB, rendered by a Markdown reader of its own that writes raw HTML as text, drops comments
and follows only http, https and mailto links; relative addresses resolve against the version, so a relative image
shows the file of the version. A README that cannot be read is left out and logged.
A page is one document with its style inline, no script and no font, and carries a Content-Security-Policy that allows
nothing else (images from the site or from https, and the form of the search), nosniff and
Referrer-Policy: same-origin. Its look is the default one unless ui sets an accent, a logo and a favicon: the name from the config is its title, and its footer
links to the home of dropr.
import http from 'node:http';
import { createApp, loadConfig, scan, scanAssets } from 'dropr';
const config = loadConfig('dropr.config.json');
const logger = { request: () => {}, error: console.error };
const app = createApp(config, {
index: scan(config.packagesDir, logger),
packagesDir: config.packagesDir,
assets: scanAssets(config.assets, logger),
version: '1.0.0',
logger,
});
http.createServer(app).listen(config.port);The config needs manifest.baseUrl. dropr serve also keeps a type folder out of the names of the assets (the third
argument of scan, the first segment of each asset URL), so do not name a type like an asset.
createHandler answers a fetch Request with a Response, so the same core can serve a worker or a test:
import { buildManifest, createHandler, createReader, loadIndex, parseConfig, scan } from 'dropr';
const config = parseConfig({ manifest: { baseUrl: 'https://cdn.example.com' } });
const logger = { error: console.error };
const handler = createHandler({
catalog: loadIndex(scan('packages', logger)),
name: config.name,
version: '1.0.0',
manifest: buildManifest(config.manifest, config.name, '1.0.0'),
read: createReader('packages'),
assets: {},
clientHeader: null,
rateLimit: config.rateLimit,
logger,
});
const response = await handler(new Request('http://localhost/health'), '127.0.0.1');The second argument is the address of the client. loadIndex takes the index that scan builds or one read from a JSON
file, and read(path, range?) is any function that returns a stream of the file; createReader is the one over a
folder. createResponder takes the same options and returns the status, headers and body without building a Response.
Add ui: true to the options to answer a browser with the pages, the READMEs being read through read; the same
accent, logo, favicon and docs can be given as an object, where a value that is not safe is ignored. Config.ui is
false or those four settings (docs being a boolean). parseConfig and the types of the API are exported too.
dropr/core exports parseConfig, loadIndex, createHandler, createResponder and buildManifest with their types,
and imports no Node module, so a runtime that has a fetch API and no disk can load it. Write the index ahead with
dropr index --out index.json (or JSON.stringify(scan(...))), read it with loadIndex(JSON.parse(text)), and give
createHandler a read function of your own; the rest of the options are those above.
- The rate limit and the uptime of
/healthlive in the handler, so they are those of one instance, and useDate.now(). /downloadneedsCompressionStream, andparseConfigneedsURL.canParse.memoryis optional: without it,/healthleaves the memory out.
Node.js, strict TypeScript (ESM), @moxon/limiter, @20syldev/logger.ts
| Script | Description |
|---|---|
npm run dev |
Dev server, reloaded on change (tsx watch) |
npm run build |
Compile TypeScript to dist/ |
npm run docs |
Write src/core/pages/guides.ts from docs/*.md; the other scripts run it first |
npm run styles |
Write src/core/pages/style.ts from the CSS files; prepack writes it minified |
npm start |
Production server (dropr serve, after npm run build) on the port of the config or $PORT |
npm run check |
Type checks (Node-free core included), ESLint, Prettier |
npm test |
Route snapshots, config, router, core, HTTP rules, CLI, package |
npm run test:update |
Record the snapshots again after an intended change |
npm run format |
Prettier and ESLint fixes on src/, test/ and scripts/ |
src/core/ Node-free core, exported as dropr/core: index (entry), config, manifest (route texts of /manifest)
src/core/http/ Router, routes, HTTP rules, CORS, errors, paths, responder
src/core/pages/ Pages, UI negotiation, theme, Markdown, HTML escaping, guides
src/core/pages/styles/ The CSS of the pages in numbered files, turned into style.ts (not committed) by scripts/styles.ts
src/core/packages/ Packages, tar archive, semver, ordering, dates, deprecations, checksums, MIME types, streams
src/node/ Node adapter: app, scan, assets, config, disk, folder, indexer, stored, serve, startup
src/cli/ Command line: bin, cli, check
src/types/ Types shared by the core and the adapter
src/index.ts Entry of the package
docs/ The docs of dropr in Markdown, turned into src/core/pages/guides.ts (not committed) by scripts/docs.ts
test/ Snapshots on a generated tree, unit and HTTP tests, the ledger of decided changes of a release