Port Authority

What it is

Port Authority assigns and tracks TCP ports for development services on your machine. Ask it for a port by project name and it hands you a stable one; ask for an ephemeral port for a test run and it gives you a lease you release when finished.

The problem it solves

Port collisions are a small, recurring tax: two projects hardcode 3000, a test run leaves a server bound, and someone restarts their machine to untangle it. The fix is not a bigger port number - it is an allocator with a memory.

My contribution

I designed and built it: the assignment algorithm, the persistent SQLite store, the HTTP server, and the pa CLI that works offline against the same database.

How it behaves

• Persistent assignments: the same port every time for a given project name - the kind you bookmark or expose on your LAN.
• Ephemeral assignments: unique ports for test runs, released when done.
• Idempotent requests: asking again for an assigned project returns the existing port.
• Offline mode: the CLI falls back to direct SQLite access when the server is not running.

Engineering decisions

One database, two access paths. The HTTP API and the offline CLI read and write the same SQLite store, so the server is an accelerator, not a dependency.

Names, not numbers, in scripts. Projects integrate by project name (pa lookup my-app), so configurations never hardcode a port that a colleague’s machine may already use.

Release as a first-class operation. Ephemeral leases have an explicit release path, which is what keeps the range from silting up.

Annotated command example

The following is an illustrative session (annotated, not a captured transcript):

# Request a persistent port for a service you visit daily
$ pa assign my-web-app --lan -d "Main web dashboard"
my-web-app -> 8042 (persistent, lan)

# Request an ephemeral port for a test run
$ pa assign temp-test -t ephemeral
temp-test -> 9137 (ephemeral)

# Look up a project's port from a script
$ pa lookup my-web-app
8042

# List all assignments
$ pa ls

# Release the ephemeral lease when the test run finishes
$ pa release temp-test
released temp-test (9137)

This portfolio’s own build scripts use Port Authority: development uses a persistent project name, tests request unique ephemeral names and release them afterward.

Stack

Python 3.12+, SQLite, a small HTTP API on localhost.