rb-portless 0.1.0.dev.20260630.3812766

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a65f8dfa503c07be5175b77e26b01053bb3b558c6fb642ba98439787a52cece2
+  data.tar.gz: 7c3427fd573855b7ee0e091f5905e4fbcb4d04829d7f0e9b1ffed3aa524f5bab
+SHA512:
+  metadata.gz: b29929df5fa80c3ec1baad36287c11bd738109b94e88b625ffe19601ee14ee530aa7db474ed00e75b1220217bb9a6e0cf13d5f9145fe0a8bcbbab908ba8b8891
+  data.tar.gz: '080a08f1368ce6b369e238a6661f6a473b7e2c5f06ebf859ae98f0ac80f91aca7c856518d9b14a227d8d30c5679e16a3a55c84f2f488a7548c47f5913f02873f'

data/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md — rb-portless
+
+A native-Ruby port of Vercel's **portless** (`references/portless`, a Node/TS
+monorepo). Goal: feature parity, HTTPS by default, framework-agnostic (Rails is
+the first test target). This file is the map; read it before changing things.
+
+## What it does
+
+`rb-portless run <cmd>` runs a dev server through a local reverse proxy reachable
+at `https://<name>.localhost` — no port numbers. A random backend port is
+injected as `PORT`; the proxy routes the named host to it.
+
+## Core mechanisms (ported from portless — keep these invariants)
+
+- **No daemon IPC.** All coordination is files in `~/.rb-portless` (overridable
+  via `PORTLESS_STATE_DIR`): `routes.json` (host→port→pid) under a `mkdir` lock,
+  plus `proxy.pid`/`proxy.port`/CA files. The proxy watches `routes.json`.
+- **Privileged port = re-exec under sudo.** For ports < 1024, re-run the CLI via
+  `sudo env PORTLESS_*=… ruby <cli> proxy start …`; the elevated process binds
+  the socket and chowns state files back to `SUDO_UID`. Fall back to `:1355` if
+  sudo is denied and no explicit port was given. Refuse in CI/no-TTY.
+- **Health header.** Every proxied response carries `X-Portless-Rb`; a HEAD probe
+  is how we tell *our* proxy from any other process on a port.
+- **Wildcard routing.** A route `name.localhost` also serves `*.name.localhost`
+  (exact match first, then `host.end_with?(".#{route}")`). Critical for
+  subdomain-per-tenant apps (e.g. `*.shirabe.org.localhost`).
+- **Per-host SNI certs.** `*.localhost` wildcard certs are invalid at the
+  reserved-TLD boundary, so mint a leaf per hostname on the TLS SNI callback,
+  cached on disk + in memory.
+
+## Module map (`lib/portless/`)
+
+| File | Role | portless source |
+| --- | --- | --- |
+| `constants.rb` | ports, thresholds, state-dir, header, markers | cli-utils.ts |
+| `state.rb` | state-dir paths + chown-back-to-SUDO_UID | utils.ts |
+| `config.rb` | portless.json + name/tld inference | config.ts, auto.ts |
+| `free_port.rb` | random 4000–4999 finder (skip bad ports) | cli-utils.ts findFreePort |
+| `route_store.rb` | routes.json + dir-lock + dead-pid reap | routes.ts |
+| `health.rb` | X-Portless-Rb probe + discoverState | cli-utils.ts |
+| `privilege.rb` | needs-sudo, sudo re-exec, 1355 fallback | cli.ts handleProxy |
+| `hosts.rb` | /etc/hosts marked-block sync/clean | hosts.ts |
+| `certs.rb` | OpenSSL CA + per-host SNI leaf certs | certs.ts |
+| `trust.rb` | OS trust store install/remove | certs.ts trustCA |
+| `proxy.rb` | async-http reverse proxy (h1/h2/tls/ws) | proxy.ts |
+| `daemon.rb` | proxy start/stop, sudo bind, 1355 fallback | cli.ts handleProxy |
+| `service.rb` | launchd / systemd boot service | service.ts |
+| `frameworks.rb` | --port/--host injection (vite/astro/…) | cli-utils.ts |
+| `runner.rb` | run cmd: port→env→spawn→register→supervise | cli.ts runApp |
+| `rails.rb` | opt-in railtie (whitelist *.localhost in dev) | — |
+| `cli.rb` | command dispatch | cli.ts main |
+
+## Status
+
+- **Phase 0 ✅** scaffold + coordination layer (config, state, free_port,
+  route_store, health, privilege, hosts) + CLI dispatch.
+- **Phase 1 ✅** HTTPS proxy on async-http (TLS+SNI, h1+wildcard routing,
+  X-Forwarded-*, loop guard), certs + macOS trust, runner, sudo bind + 1355
+  fallback. **Verified against shirabe** at `https://*.shirabe.org.localhost`.
+- **Phase 2 ✅** HTTP/2, full command surface (doctor/clean/prune/alias/get/hosts),
+  boot service (launchd/systemd), daemon lifecycle.
+- **Phase 3 ✅ (partial)** framework `--port`/`--host` injection, Linux CA trust,
+  optional `portless/rails` railtie.
+
+### Roadmap (not yet built)
+
+- LAN mode (mDNS `.local` publishing) for phones/tablets.
+- Public sharing via `tailscale serve|funnel` and `ngrok`.
+- Monorepo multi-app (one proxy, many named apps).
+- Windows CA trust + Task Scheduler service.
+- WebSocket upgrade relay hardening + HTTP/2 to the backend.
+
+## Conventions
+
+- Stdlib-first; the only runtime deps are `async` + `async-http` (for h1/h2/tls/ws).
+- Minitest + fixtures-free tests in `test/`; isolate state via `PORTLESS_STATE_DIR`.
+- Mirror portless's naming/structure so the two stay diffable against
+  `references/portless`.

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — first release
+
+The full portless workflow for Ruby, validated end-to-end against a real Rails
+app (`rb-portless run bin/rails server` → `https://*.shirabe.org.localhost`).
+
+### Added
+
+- **HTTP/2** with HTTP/1.1 fallback (server-side ALPN negotiation).
+- **Commands:** `run`, `proxy start|stop`, `trust`, `service install|uninstall|status`,
+  `alias`, `get`, `list`, `hosts sync|clean`, `doctor`, `prune`, `clean`.
+- **Boot service** — launchd (macOS) / systemd (Linux) for a no-prompt
+  privileged bind at boot.
+- **CA trust** on macOS (login keychain) and Linux (distro anchors).
+- **Framework `--port`/`--host` injection** for Vite, Astro, Angular, etc.
+- Optional **Rails railtie** (`gem "rb-portless", require: "portless/rails"`)
+  that **auto-detects** when the app runs under `rb-portless` (via `PORTLESS_URL`)
+  and only then whitelists the matching `*.localhost` dev hosts — zero-config,
+  and a no-op when you run Rails normally.
+- **Phase 1 — core.** `rb-portless run <cmd>` runs a dev server behind a local
+  HTTPS reverse proxy reachable at `https://<name>.localhost`:
+  - async-http TLS proxy with per-host SNI certs, Host + wildcard routing
+    (`*.name.localhost` → the app registered as `name.localhost`), `X-Forwarded-*`
+    headers, a loop guard, and a sibling `:80 → https` redirect.
+  - Native-OpenSSL local CA + on-demand per-host leaf certs; macOS keychain trust.
+  - `routes.json` registry (directory-lock + dead-pid reaping), `X-Portless-Rb`
+    health probe, and proxy auto-start.
+  - Privileged-port binding via one-time `sudo` re-exec, with a `:1355` fallback.
+  - Random backend port (4000–4999) injected as `PORT`/`HOST`.
+- **Phase 0 — scaffold.** Gem skeleton, config (`portless.json` + name/tld
+  inference), state dir, CLI dispatch (`run`, `proxy`, `trust`, `list`, …).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Afonso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,177 @@
+<h1 align="center">rb-portless</h1>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/rb-portless"><img src="https://img.shields.io/gem/v/rb-portless" alt="Gem Version"></a>
+  <a href="https://github.com/davafons/rb-portless/actions/workflows/ci.yml"><img src="https://github.com/davafons/rb-portless/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/davafons/rb-portless/blob/main/LICENSE"><img src="https://img.shields.io/github/license/davafons/rb-portless" alt="License"></a>
+  <a href="https://rubygems.org/gems/rb-portless"><img src="https://img.shields.io/gem/dt/rb-portless" alt="Downloads"></a>
+</p>
+
+<p align="center">
+  Stable, named <code>.localhost</code> URLs for local development —<br>
+  a native-Ruby port of <a href="https://github.com/vercel-labs/portless">Vercel's portless</a>.
+</p>
+
+```diff
+- bin/rails server                     # http://localhost:3000
++ rb-portless run bin/rails server     # https://myapp.localhost
+```
+
+Run your dev server through a tiny local reverse proxy and reach it at
+`https://<name>.localhost` instead of juggling ports. HTTPS by default (a local
+CA + per-host certs), a random backend port so you never collide on 3000/3001,
+and wildcard subdomains (`*.myapp.localhost`) so multi-tenant apps Just Work.
+
+## Install
+
+```bash
+gem install rb-portless
+```
+
+- Ruby >= 3.2. macOS or Linux. (Windows: HTTP works; CA trust + boot service are
+  on the roadmap.)
+
+## Use
+
+```bash
+rb-portless run bin/dev            # -> https://<project>.localhost
+rb-portless run bin/rails server   # anything that respects $PORT
+rb-portless run -- npm run dev     # Vite/Astro/etc. get --port injected
+```
+
+A random port (4000–4999) is injected as `PORT` (and `HOST=127.0.0.1`);
+Rails/puma respect it natively. The proxy **auto-starts** on first run: it
+generates a local CA, and binds 443 — a one-time `sudo` on macOS/Linux, exactly
+like portless (falls back to `:1355` if you decline). Run `rb-portless trust`
+once so your browser accepts the certificates.
+
+```bash
+rb-portless trust                  # trust the local CA (HTTPS, no warnings)
+rb-portless service install        # bind 443 at boot — never prompt for sudo again
+```
+
+### Config (`portless.json`)
+
+```json
+{ "name": "shirabe", "tld": "shirabe.org.localhost" }
+```
+
+| Key       | Default     | Meaning |
+| --------- | ----------- | ------- |
+| `name`    | dir/git root | the subdomain label |
+| `tld`     | `localhost` | base host; a multi-label value like `shirabe.org.localhost` gives every `*.shirabe.org.localhost` subdomain, all routed to the one app |
+| `tls`     | `true`      | HTTPS (`false` = plain HTTP on :80) |
+| `appPort` | random      | pin the backend port |
+
+With a custom `tld`, every `*.shirabe.org.localhost` subdomain wildcard-routes to
+the one app — ideal for subdomain-per-tenant apps.
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `run <cmd>` | run a dev server through the proxy |
+| `proxy start \| stop` | manage the proxy daemon |
+| `trust` | install the local CA into the OS trust store |
+| `service install \| uninstall \| status` | bind the privileged port at boot (launchd/systemd) |
+| `alias <name> <port>` | a static route (Docker, Postgres, …) |
+| `get <name>` | print a name's URL (for `$(rb-portless get api)`) |
+| `list` | show active routes |
+| `hosts sync \| clean` | manage `/etc/hosts` (Safari / non-`.localhost` TLDs) |
+| `doctor` | diagnose setup |
+| `prune` | reap stale routes |
+| `clean` | stop the proxy, untrust the CA, remove all state |
+
+## Rails
+
+Rails is first-class: it respects `PORT` and trusts the loopback proxy, so
+`X-Forwarded-Host/Proto/Port` flow through and `request.host`, subdomains, and
+generated URLs all reflect `https://<name>.localhost`.
+
+**Zero-config setup.** Add the gem to your dev group with the railtie required —
+that's the only project change:
+
+```ruby
+# Gemfile
+group :development do
+  gem "rb-portless", require: "portless/rails"
+end
+```
+
+```jsonc
+// portless.json  (optional — name defaults to the dir/git root)
+{ "name": "myapp", "tld": "myapp.localhost" }
+```
+
+```bash
+rb-portless trust            # one-time: trust the local CA
+rb-portless run bin/dev      # → https://myapp.localhost
+```
+
+That's it. The railtie **auto-detects when you're running under `rb-portless`**
+(via the `PORTLESS_URL` env the runner injects) and only then whitelists your
+`*.localhost` hosts in development — so Action Dispatch host authorization doesn't
+`403` your named subdomains. Run `bin/dev` normally and nothing is touched.
+
+> **`bin/dev` note:** `rb-portless run bin/dev` wraps Foreman. Foreman passes the
+> injected `PORT` to the **first** process in `Procfile.dev` — keep `web:` first
+> (the Rails default) so the server binds the port the proxy registered.
+
+Prefer not to add the gem? Skip the railtie and allow the host yourself:
+
+```ruby
+# config/environments/development.rb
+config.hosts << /.+\.localhost/
+```
+
+## Use cases
+
+**Kill the port.** Stop memorizing `:3000` / `:3001`. One stable HTTPS URL per
+app, the same every day:
+
+```bash
+rb-portless run bin/dev      # https://myapp.localhost
+```
+
+**Subdomain-per-tenant apps** (the headline). A multi-label `tld` gives every
+subdomain to one app, so multi-tenant / Classroom-style routing works locally
+exactly like production:
+
+```jsonc
+{ "name": "myapp", "tld": "myapp.localhost" }
+// kobe.myapp.localhost, osaka.myapp.localhost, admin.myapp.localhost → your app
+```
+
+**Several services at once.** Give each its own name; route non-portless
+processes (a database, a container) with a static `alias`:
+
+```bash
+rb-portless run bin/dev                 # https://web.localhost
+rb-portless run -- node api/server.js   # https://api.localhost   (in another tab)
+rb-portless alias pg 5432               # https://pg.localhost     (static)
+```
+
+**HTTPS that matches prod.** Develop against real TLS + HTTP/2, so secure-cookie
+and `X-Forwarded-Proto` behaviour is the same locally as in production.
+
+## How it works
+
+No daemon protocol — coordination is a state dir (`~/.rb-portless`) with a
+`routes.json` registry (host → backend port). The proxy resolves each request's
+host to a backend and forwards it, minting a per-host TLS leaf cert on the SNI
+callback (because `*.localhost` wildcard certs aren't valid at the reserved-TLD
+boundary). For ports < 1024 it re-execs under `sudo` so the elevated process can
+bind the socket, then hands ownership of state files back to you. See
+[`AGENTS.md`](AGENTS.md) for the full architecture.
+
+## Contributing
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+## License
+
+MIT.

data/exe/rb-portless

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "rb-portless"
+rescue LoadError
+  require_relative "../lib/rb-portless"
+end
+
+Portless::CLI.start(ARGV)

data/lib/portless/certs.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "fileutils"
+
+module Portless
+  # Local CA + per-host leaf certs, all in native Ruby OpenSSL (portless shells
+  # out to the openssl binary; we don't have to). Because *.localhost wildcard
+  # certs aren't honoured at the reserved-TLD boundary, every SNI hostname gets
+  # its own leaf, minted on demand and cached on disk + in memory.
+  class Certs
+    CA_SUBJECT = "/CN=rb-portless Local CA"
+    CA_DAYS = 3650
+    LEAF_DAYS = 365
+    CURVE = "prime256v1"
+
+    def initialize
+      @leaves = {} # hostname => [cert, key]
+    end
+
+    # The CA certificate (PEM-loaded), generating + persisting one on first use.
+    def ca_certificate
+      @ca_certificate ||= begin
+        ensure_ca!
+        OpenSSL::X509::Certificate.new(File.read(State.ca_cert))
+      end
+    end
+
+    def ca_key
+      @ca_key ||= begin
+        ensure_ca!
+        OpenSSL::PKey.read(File.read(State.ca_key))
+      end
+    end
+
+    # SHA-256 fingerprint — used by the trust marker + OS trust check.
+    def ca_fingerprint
+      OpenSSL::Digest::SHA256.hexdigest(ca_certificate.to_der)
+    end
+
+    # [cert, key] for an SNI hostname. Cached in memory; persisted under
+    # host-certs/ so a proxy restart doesn't re-mint everything.
+    def leaf_for(hostname)
+      hostname = hostname.to_s.downcase
+      @leaves[hostname] ||= load_leaf(hostname) || generate_leaf(hostname)
+    end
+
+    def ensure_ca!
+      return if File.exist?(State.ca_cert) && File.exist?(State.ca_key)
+
+      State.ensure_dir!
+      key = OpenSSL::PKey::EC.generate(CURVE)
+      cert = OpenSSL::X509::Certificate.new
+      name = OpenSSL::X509::Name.parse(CA_SUBJECT)
+      cert.version = 2
+      cert.serial = random_serial
+      cert.subject = name
+      cert.issuer = name
+      cert.public_key = ec_public(key)
+      cert.not_before = Time.now - 60
+      cert.not_after = Time.now + CA_DAYS * 86_400
+
+      ef = OpenSSL::X509::ExtensionFactory.new
+      ef.subject_certificate = cert
+      ef.issuer_certificate = cert
+      cert.add_extension(ef.create_extension("basicConstraints", "CA:TRUE", true))
+      cert.add_extension(ef.create_extension("keyUsage", "keyCertSign,cRLSign", true))
+      cert.add_extension(ef.create_extension("subjectKeyIdentifier", "hash"))
+      cert.sign(key, OpenSSL::Digest.new("SHA256"))
+
+      write_secret(State.ca_key, key.to_pem)
+      File.write(State.ca_cert, cert.to_pem)
+      State.fix_ownership
+    end
+
+    private
+
+    def generate_leaf(hostname)
+      key = OpenSSL::PKey::EC.generate(CURVE)
+      cert = OpenSSL::X509::Certificate.new
+      cert.version = 2
+      cert.serial = random_serial
+      cert.subject = OpenSSL::X509::Name.new([ [ "CN", hostname ] ])
+      cert.issuer = ca_certificate.subject
+      cert.public_key = ec_public(key)
+      cert.not_before = Time.now - 60
+      cert.not_after = Time.now + LEAF_DAYS * 86_400
+
+      ef = OpenSSL::X509::ExtensionFactory.new
+      ef.subject_certificate = cert
+      ef.issuer_certificate = ca_certificate
+      cert.add_extension(ef.create_extension("basicConstraints", "CA:FALSE", true))
+      cert.add_extension(ef.create_extension("keyUsage", "digitalSignature,keyEncipherment", true))
+      cert.add_extension(ef.create_extension("extendedKeyUsage", "serverAuth"))
+      cert.add_extension(ef.create_extension("subjectAltName", san_for(hostname)))
+      cert.add_extension(ef.create_extension("subjectKeyIdentifier", "hash"))
+      cert.sign(ca_key, OpenSSL::Digest.new("SHA256"))
+
+      persist_leaf(hostname, cert, key)
+      [ cert, key ]
+    end
+
+    # The exact host plus a same-level wildcard (so api.x and x both verify when
+    # one is reached via the other).
+    def san_for(hostname)
+      sans = [ "DNS:#{hostname}" ]
+      parts = hostname.split(".")
+      sans << "DNS:*.#{parts[1..].join('.')}" if parts.length > 2
+      sans.join(",")
+    end
+
+    def load_leaf(hostname)
+      cert_path, key_path = leaf_paths(hostname)
+      return unless File.exist?(cert_path) && File.exist?(key_path)
+
+      cert = OpenSSL::X509::Certificate.new(File.read(cert_path))
+      return if cert.not_after < Time.now + 7 * 86_400 # expiring soon → re-mint
+
+      [ cert, OpenSSL::PKey.read(File.read(key_path)) ]
+    rescue StandardError
+      nil
+    end
+
+    def persist_leaf(hostname, cert, key)
+      cert_path, key_path = leaf_paths(hostname)
+      FileUtils.mkdir_p(State.host_certs_dir)
+      File.write(cert_path, cert.to_pem)
+      write_secret(key_path, key.to_pem)
+      State.fix_ownership(State.host_certs_dir)
+    end
+
+    def leaf_paths(hostname)
+      safe = hostname.gsub(/[^a-z0-9.-]/, "_")
+      [ File.join(State.host_certs_dir, "#{safe}.pem"), File.join(State.host_certs_dir, "#{safe}-key.pem") ]
+    end
+
+    # EC public-only key for embedding in a cert. The `public_key=` setter is
+    # gone in OpenSSL 3, so round-trip through the public PEM.
+    def ec_public(key)
+      OpenSSL::PKey.read(key.public_to_pem)
+    end
+
+    def random_serial = OpenSSL::BN.rand(159)
+
+    def write_secret(path, pem)
+      File.write(path, pem)
+      File.chmod(0o600, path)
+    end
+  end
+end