Portless
A Portless learning project: a read-only route and origin explorer
Design a proposed teaching tool that explains matching priority, browser origins and exposure boundaries without silently configuring certificates or sharing apps.
What you will learn
- Make the invisible routing decision visible
- Keep observation distinct from mutation
- Turn the source experiment into a regression specification
Before you start
- Basic HTTP origins, ports and command-line concepts
- Ability to distinguish loopback, LAN and public exposure
Trace a named request, choose explicit setup boundaries and separate observed behavior from untested integrations.
Key takeaways
- A proposed explorer should explain real matching tiers with synthetic data.
- Read-only visualization must not conceal system configuration actions.
- Measure learner understanding rather than animation complexity.
Make the invisible routing decision visible
A useful extension would let a learner enter a synthetic Host header and step through the pinned matching tiers. Show the original authority, normalized authority, exact-name candidates, tailnet authority candidates and optional wildcard fallback. Highlight the first selected route and explain why a later, more specific suffix did not win. This is a proposed educational interface, not a shipped Portless feature.
Use synthetic routes and ports by default. The exercise should never discover private app names, read real tokens or contact a typed hostname merely to animate a diagram. A 2D SVG flow and an accessible ordered explanation are enough for this relationship; a Three.js scene would add rendering and interaction work without inherently making a four-tier priority chain clearer.
Keep observation distinct from mutation
A second view could compare browser origins across HTTP, HTTPS, proxy-port changes and worktree names. It should explain that scheme, hostname and port all matter, while cookie scope and provider allowlists require their own application rules. It must not claim to validate CORS or OAuth just because two displayed URLs differ.
If real route import is later added, make it explicit, local and read-only, and redact sensitive names before export. Do not put buttons for certificate trust, force replacement, service installation or public sharing inside a harmless-looking visualizer. Those actions need separate authorization and clear consequences; an educational diagram is not a reason to grant them.
Turn the source experiment into a regression specification
The current 24-case probe can provide fixture expectations for the route explorer, including strict rejection, exact-name precedence and first-suffix selection. Keep an explicit source-version selector so a behavior change does not silently invalidate the lesson. A parser or display error should be visible as an error, not converted to a plausible invented route.
The next implementation milestone would be an accessible static prototype with keyboard navigation, localized labels and fixture-based checks. After that, test whether learners can predict an unfamiliar route and distinguish local from public exposure. No interactive explorer, 3D animation or learner study was delivered by this article; the included SVG illustrates the proposal and the existing probe supplies its evidence boundary.
Implementation steps
- 1
Define synthetic routes and expected matches from the fixed probe.
- 2
Build a keyboard-readable 2D explanation before considering animation.
- 3
Keep real-state import optional and redact exports.
- 4
Test prediction tasks and label proposals separately from shipped behavior.
Copy-ready example
{
"proposal": "read-only route explorer",
"status": "not implemented",
"input": "synthetic Host and route table",
"networkRequests": false,
"readMachineTokens": false,
"modifyCertificatesOrServices": false,
"learningCheck": "predict route and explain exposure"
}Frequently asked questions
Is this explorer already part of Portless?
No. It is an editorial project proposal derived from the inspected source and fixture results, not a claim about an existing interface.
Why not use Three.js immediately?
The essential relationship is an ordered routing decision. An accessible 2D diagram communicates it with less complexity; 3D should be added only for a demonstrated learning benefit.
Sources
- packages/portless/src/proxy.tsSource checked 2026-09-08
- packages/portless/src/types.tsSource checked 2026-09-08
- README.mdSource checked 2026-09-08