spike(npm): distribute proxy via npx stash proxy#398
Draft
coderdan wants to merge 6 commits into
Draft
Conversation
Proof-of-concept for shipping the proxy via npm as `npx stash proxy`, using the esbuild/Biome/SWC pattern (per-platform packages + os/cpu-filtered optionalDependencies + a thin JS launcher) -- NOT native N-API bindings, since proxy is a standalone server we only need to distribute and launch. Verified end-to-end locally on darwin-arm64: npx -> stash shim -> exec native cipherstash-proxy binary, with --version/--help passthrough, correct exit-code forwarding (0 / clap's 2), signal forwarding, and os/cpu platform resolution. Binaries are git-ignored build artifacts (build-binaries.sh / demo.sh regenerate them). Packages are private + 0.0.0-prototype to prevent publish. See npm/README.md for how this maps to a production CI matrix and the code-signing rationale (skips notarization/Developer-ID; keeps free ad-hoc signing on Apple Silicon).
`stash proxy --psql ...` starts the proxy, waits for it to report its listen address (parsing the OS-assigned port when the default is in use), then launches psql connected to the proxy with the target db/user/password. psql is the foreground session; the proxy is torn down when it exits. Falls back with a clear message if psql is not on PATH. Connection details are taken from --database-url, then --db-* flags, then CS_DATABASE__* env. Validated against a local dev DB.
When `--psql` is used and psql isn't on PATH (or STASH_USE_BUILTIN_SQL=1 is set), open a small built-in SQL shell (lib/repl.js) instead of failing. It uses the pure-JS `pg` driver (no native binaries) and runs SQL through the proxy with tabular output and a few meta-commands (\l, \dt, \d, \?, \q). Not a psql replacement -- a convenience fallback. Real psql is still preferred when installed. Validated end-to-end against a local dev DB via the proxy. Background: bundling real psql isn't viable off-the-shelf -- the @embedded-postgres/* packages ship initdb/pg_ctl/postgres but strip psql -- so a pure-JS shell is the pragmatic no-native-deps fallback.
Visually distinguishes a via-proxy session from a direct psql connection: the prompt becomes e.g. `stash:mydb=>` with "stash" in cyan (on a TTY). Applied to both real psql (via PROMPT1/PROMPT2 --set) and the built-in shell. Override with STASH_PSQL_PROMPT (set empty to use psql's default / ~/.psqlrc); colour honours NO_COLOR and is disabled off a TTY.
A literal ESC byte in PROMPT1 was stripped by psql's variable parser, so the prompt showed in the default colour. psql's own %033 octal escape produces the ESC reliably (verified: \001 ESC[36m \002 stash \001 ESC[0m \002 -- 'stash' wrapped in cyan).
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Prototype of distributing CipherStash Proxy via npm so people can run it with a single command:
npx stash proxy --database-url postgres://user:pass@host:5432/db npx stash proxy --psql --database-url ... # also opens a SQL session through the proxyApproach
Follows the esbuild distribution pattern rather than native bindings:
stash) with a pure-JSbin/launcher that resolves and execs the right prebuilt binary, forwarding argv / stdio / exit codes / signals.@cipherstash/proxy-{darwin,linux}-{arm64,x64}) carrying just the binary, selected automatically viaos/cpu-filteredoptionalDependencies.What's here
npm/packages/stash/— launcher (bin/stash.js), binary resolver (lib/resolve.js), and a pure-JS SQL shell fallback (lib/repl.js) used whenpsqlisn't on PATH.npm/packages/proxy-*/— the four platform package manifests.npm/build-binaries.sh— builds + stages the host binary into its platform package.npm/demo.sh— end-to-end local proof (build → install → run via npx and via thestashbin).npm/release-workflow.example.yml— sketch of the CI matrix that would build all four targets and publish.DX niceties (depend on #397)
--psqllaunches the proxy, waits for it to report its listen port, then opens psql (or the built-in shell) connected through it, with a branded cyanstash:<db>=>prompt.Status
Proven end-to-end locally on macOS. Not wired into release CI yet; platform binaries are not published. Opening as a draft to capture the approach and gather feedback on whether to productionize.