finesse 0.0.1 → 0.1.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f788a2956c44f5c8691e1f860f1d8087c3ca98959c227a37a6bb1134128060e9
-  data.tar.gz: ba6afdc9b27030849ca07267c465bba8a890e5a9eba973625fbd73ea7e9400c2
+  metadata.gz: 4063a626a91837c3ad59b9dd687af6548bcbb16ada46f5b3c01e768bea5dc73b
+  data.tar.gz: 25cebe7a2f3a2206ae2704d44a78943b92c1e45b4f4b68d7e3884d9d7f8a50e7
 SHA512:
-  metadata.gz: '093eaf11240daad7ee22c45c61da3e636b85cad7a8834b605d929ce9caa755ae49f1f639db5d3a938a8c926e99e5bd403df944d617f30a41501e3810c9c8ecd5'
-  data.tar.gz: 7e9a02dceff25be3138042276674d5ac1391e3ab2988151af1da93e2c082214b82809f80e3be3cecf2d3d2fdf39baf49dad3573ae171d96406800d1932af2bf2
+  metadata.gz: '068fd87c382d4ca33b17a0687ebed2d742c234bd23f017bb05e83a6728ecc495e8b98f718b09d6e21ee10cc14f45292f709f7abdcb95f0a8ad77666e367832d9'
+  data.tar.gz: dc5a0732991394c1cea7abb149e639c12b07b26749923ca281d4f1533136994657fa883fec434f93fb175821b8d240b0ae4331ddebc96c4d52607a375323432e

data/README.md

@@ -0,0 +1,211 @@
+<p align="center">
+  <img src="finesse-logo.png" alt="Finesse" width="200">
+</p>
+
+# Finesse
+
+Finesse replaces ActionCable's WebSocket transport with a lightweight Go binary that polls SolidCable's SQLite table and streams Turbo updates to browsers via Server-Sent Events (SSE). No WebSocket infrastructure needed — just a single binary alongside your Rails app.
+
+## Prerequisites
+
+Finesse currently supports **SolidCable with SQLite** only. Your Rails app needs:
+
+- **[SolidCable](https://github.com/rails/solid_cable)** as your ActionCable adapter, with a `cable:` database configured in `config/database.yml`
+- **[turbo-rails](https://github.com/hotwired/turbo-rails)** (>= 2.0) — Finesse uses Turbo's signed stream tokens for authentication
+
+PostgreSQL and other adapters are on the [roadmap](#roadmap).
+
+## Quick Start
+
+1. Add to your Gemfile:
+   ```ruby
+   gem "finesse"
+   ```
+
+2. Install:
+   ```sh
+   bundle install
+   ```
+
+3. Add to your `Procfile.dev`:
+   ```
+   sse: bundle exec finesse --allow-origin http://localhost:3000
+   ```
+   For multiple origins (e.g., accessing from another device on your network), repeat the flag:
+   ```
+   sse: bundle exec finesse --allow-origin http://localhost:3000 --allow-origin http://192.168.1.10:3000
+   ```
+
+4. Start your app:
+   ```sh
+   bin/dev
+   ```
+
+## How It Works
+
+```
+Browser <turbo-stream-source> ──GET /events?signed_stream=…──> Finesse (Go binary, :4000)
+                                                                     │
+Rails app ──broadcast_append_to──> SolidCable ──INSERT──> SQLite ←──POLL─┘
+```
+
+Finesse polls the `solid_cable_messages` table for new rows and streams them as SSE events to connected browsers. It uses SQLite WAL mode for concurrent read access alongside Rails writes.
+
+Key design choices:
+- **Polling over triggers** — simple, no SQLite extensions required, 10ms default interval
+- **Per-channel fan-out** — each channel gets its own broadcaster with a ring buffer for reconnection catch-up
+- **Pure Go SQLite** — uses `modernc.org/sqlite` (no CGO), enabling easy cross-compilation
+
+## CLI Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port` | `4000` | HTTP listen port |
+| `--db-path` | auto from `config/database.yml` | Path to SolidCable SQLite database |
+| `--table-name` | `solid_cable_messages` | SolidCable messages table name |
+| `--poll-interval` | `10` | Database poll interval (integer, milliseconds) |
+| `--allow-origin` | *(required)* | `Access-Control-Allow-Origin` header value |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FINESSE_SIGNING_KEY` | Hex-encoded HMAC key for signed stream verification (auto-derived from Rails when using `bundle exec finesse`) |
+| `BINDING` | Bind address (default: `127.0.0.1`) |
+
+## Endpoints
+
+| Path | Description |
+|------|-------------|
+| `GET /up` | Health check (returns 200) |
+| `GET /events?signed_stream=<token>` | SSE stream for the given signed stream |
+
+The SSE endpoint supports the `Last-Event-ID` header for automatic reconnection catch-up. Stream tokens use the same `ActiveSupport::MessageVerifier` format as Turbo's signed streams.
+
+## Development
+
+### Compiling from source
+
+Requires Go 1.24+.
+
+```sh
+bundle exec rake build:local   # Build for current platform
+bundle exec rake build:all     # Cross-compile for all platforms
+```
+
+### Running tests
+
+All build and test commands should be run via `bundle exec`:
+
+```sh
+bundle exec rake test          # Run Go + Ruby tests
+bundle exec rake test:go       # Go tests only
+bundle exec rake test:ruby     # Ruby tests only
+```
+
+### Running locally
+
+```sh
+./exe/arm64-darwin/finesse --port 4000 --db-path ../your-app/storage/development_cable.sqlite3
+```
+
+## Security
+
+Finesse verifies every SSE connection using Turbo's signed stream tokens (HMAC-SHA256). CORS is restricted to the origins you specify with `--allow-origin`, and the server binds to `127.0.0.1` by default.
+
+### Signing Key Flow
+
+**TL;DR:** Finesse needs the same HMAC key that Turbo uses to sign stream names. The Ruby wrapper extracts it from Rails automatically — zero config in development.
+
+The problem: Finesse is a standalone Go binary, but it needs to verify tokens that Rails signs. Rails derives its signing key from `SECRET_KEY_BASE` via PBKDF2, and that secret lives in encrypted credentials (`config/credentials.yml.enc`) which require Ruby's `Marshal` deserializer to read. Reimplementing that in Go would be fragile and version-dependent.
+
+The solution: let Ruby do the Ruby parts, then hand the result to Go.
+
+```
+        Rails Boot                           Finesse Boot
+        ──────────                           ────────────
+
+config/credentials.yml.enc           exe/finesse (Ruby wrapper)
+           │                                    │
+           ▼                                    ▼
+      SECRET_KEY_BASE                rails runner "Finesse.signing_key"
+           │                                    │
+           ▼                                    ▼
+      PBKDF2-HMAC-SHA256             Turbo.signed_stream_verifier_key
+      salt: "turbo/signed_                      │
+            stream_verifier_key"                ▼
+      iterations: 65,536             hex-encode the derived key
+      output: 64 bytes                          │
+           │                                    ▼
+           ▼                         ENV["FINESSE_SIGNING_KEY"] = hex
+      Turbo.signed_stream_                      │
+        verifier_key                            ▼
+           │                         exec(go_binary)
+           ▼                           ├── reads env, decodes hex
+      turbo_stream_from @chat          └── verifies HMAC on every
+      signs channel name ─────────▶  /events?signed_stream=<token>
+```
+
+**Token format** (Rails `ActiveSupport::MessageVerifier`):
+```
+base64strict(json(channel_name))--hex(hmac_sha256(base64_data, derived_key))
+```
+
+The Go binary splits the token on `--`, recomputes the HMAC over the base64 data, and compares using constant-time `hmac.Equal`. If it matches, the channel name is trusted.
+
+**In development**, this is fully automatic — Rails writes `secret_key_base` to `tmp/local_secret.txt` and the wrapper reads it. **In production**, either let the wrapper derive the key at boot (slower — spawns a `rails runner`), or set `FINESSE_SIGNING_KEY` directly as a hex-encoded env var to skip the Rails boot entirely.
+
+## Production Deployment
+
+Finesse binds to `127.0.0.1` by default and should **not** be exposed directly on port 80/443. Run it alongside your app server (Puma, etc.) on the same host and proxy to it from your web server. For example, with Nginx:
+
+```nginx
+upstream finesse {
+  server 127.0.0.1:4000;
+}
+
+location /finesse/ {
+  proxy_pass http://finesse/;
+  proxy_set_header Host $host;
+  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+
+  # SSE requires unbuffered responses
+  proxy_buffering off;
+  proxy_cache off;
+  proxy_read_timeout 86400s;
+}
+```
+
+### Kamal
+
+If you deploy with [Kamal](https://kamal-deploy.org), add Finesse as a separate server role in `config/deploy.yml`. kamal-proxy automatically detects `Content-Type: text/event-stream` responses and disables buffering — no extra proxy configuration needed.
+
+```yaml
+servers:
+  web:
+    - <your-public-server-ip>
+  sse:
+    hosts:
+      - <your-public-server-ip>
+    cmd: bundle exec finesse --allow-origin "https://yourapp.com"
+    proxy:
+      ssl: true
+      host: sse.yourapp.com
+      app_port: 4000
+      healthcheck:
+        path: /up
+```
+
+Point a DNS record for `sse.yourapp.com` at your server and kamal-proxy handles TLS and routing.
+
+Set `FINESSE_SIGNING_KEY` as a hex-encoded env var in production to avoid a `rails runner` invocation on every boot. The `--allow-origin` flag should match your production domain.
+
+## Roadmap
+
+- **Rails generator** — `rails g finesse:install` for config, initializer, and binstub
+- **Engine/Railtie** — view helpers (`finesse_sse_url`)
+- **PostgreSQL support** — `LISTEN/NOTIFY` adapter as alternative to SQLite polling. 8KB limit may not be worth it, but polling in PostgreSQL would still be on the roadmap.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/exe/finesse

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'English'
+require_relative '../lib/finesse/platforms'
+
+args = ARGV.dup
+
+# If --db-path wasn't explicitly provided, try to resolve it from config/database.yml
+unless args.any? { |a| a.start_with?('--db-path') }
+  db_path = Finesse::Platforms.cable_db_path
+  args.unshift('--db-path', db_path) if db_path
+end
+
+# Derive FINESSE_SIGNING_KEY via Rails if not already set.
+if ENV['FINESSE_SIGNING_KEY'].nil? || ENV['FINESSE_SIGNING_KEY'].empty?
+  key = `bundle exec rails runner "print Finesse.signing_key" 2>/dev/null`.strip
+  ENV['FINESSE_SIGNING_KEY'] = key if $CHILD_STATUS.success? && !key.empty?
+end
+
+exec(Finesse::Platforms.executable, *args)

data/lib/finesse/platforms.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Finesse
+  # Platform detection, binary resolution, and database.yml parsing.
+  module Platforms
+    SUPPORTED_PLATFORMS = %w[
+      arm64-darwin
+      x86_64-darwin
+      aarch64-linux
+      x86_64-linux
+    ].freeze
+
+    class UnsupportedPlatformError < StandardError; end
+
+    class << self
+      # Root directory of the gem (two levels up from lib/finesse/).
+      def root
+        File.expand_path('../..', __dir__)
+      end
+
+      PLATFORM_MAP = {
+        %w[arm64 darwin] => 'arm64-darwin',
+        %w[x86_64 darwin] => 'x86_64-darwin',
+        %w[aarch64 linux] => 'aarch64-linux',
+        %w[x86_64 linux] => 'x86_64-linux'
+      }.freeze
+
+      def platform
+        cpu = Gem::Platform.local.cpu
+        os = Gem::Platform.local.os
+
+        PLATFORM_MAP.fetch([cpu, os]) do
+          raise UnsupportedPlatformError,
+                "Finesse does not support #{cpu}-#{os}. " \
+                "Supported platforms: #{SUPPORTED_PLATFORMS.join(', ')}"
+        end
+      end
+
+      def executable
+        exe = File.join(root, 'exe', platform, 'finesse')
+
+        unless File.exist?(exe)
+          raise UnsupportedPlatformError,
+                "Finesse binary not found at #{exe}. " \
+                'Run `rake build:go` to compile from source.'
+        end
+
+        exe
+      end
+
+      # Resolve the cable database path from config/database.yml.
+      # Returns nil if the file doesn't exist or no cable DB is configured.
+      def cable_db_path
+        config = load_database_yml
+        return nil unless config
+
+        env_config = config.dig(ENV.fetch('RAILS_ENV', 'development'), 'cable')
+        env_config['database'] if env_config.is_a?(Hash)
+      end
+
+      private
+
+      def load_database_yml
+        config_path = File.join(Dir.pwd, 'config', 'database.yml')
+        return nil unless File.exist?(config_path)
+
+        require 'yaml'
+        require 'erb'
+
+        yaml = ERB.new(File.read(config_path)).result
+        YAML.safe_load(yaml, permitted_classes: [Symbol], aliases: true)
+      end
+    end
+  end
+end

data/lib/finesse/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Finesse
-  VERSION = "0.0.1"
+  VERSION = '0.1.0.beta1'
 end

data/lib/finesse.rb

@@ -1,4 +1,14 @@
-require_relative "finesse/version"
+# frozen_string_literal: true
 
+require_relative 'finesse/version'
+require_relative 'finesse/platforms'
+
+# SSE server gem for ActionCable via SolidCable.
 module Finesse
+  # Returns the Turbo signed stream verifier key as a hex string.
+  # Called by the exe wrapper via `rails runner` to set FINESSE_SIGNING_KEY.
+  def self.signing_key
+    require 'turbo-rails'
+    Turbo.signed_stream_verifier_key.unpack1('H*')
+  end
 end

metadata

@@ -1,27 +1,51 @@
 --- !ruby/object:Gem::Specification
 name: finesse
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0.beta1
 platform: ruby
 authors:
 - scudco
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Finesse replaces ActionCable's default WebSocket transport with a lightweight
-  Go binary
-executables: []
+  Go binary that polls SolidCable's SQLite table and streams Turbo updates to browsers
+  via Server-Sent Events.
+executables:
+- finesse
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README.md
+- exe/aarch64-linux/finesse
+- exe/arm64-darwin/finesse
+- exe/finesse
+- exe/x86_64-darwin/finesse
+- exe/x86_64-linux/finesse
 - lib/finesse.rb
+- lib/finesse/platforms.rb
 - lib/finesse/version.rb
 homepage: https://github.com/scudco/finesse
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -36,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.3
 specification_version: 4
 summary: SSE server for ActionCable in Rails
 test_files: []