workspaces 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c580535eeb20692a3454144150752141b76eeed504ca7f13d59f2ee498e5e8eb
-  data.tar.gz: dc5fbe433b8ffd2c485bdbf91bcb2aae72bf4010926f4c0106361cc5a1369ce6
+  metadata.gz: 1974af7e7acc6d19fe556efa4af5e2f9e05635d8df564aa6b3e7e7f8a9096370
+  data.tar.gz: d819cb05a41259c8f9b0c7e49d42155f7b072daa88bd839b44351ddec7445b51
 SHA512:
-  metadata.gz: 3287a5de3b491b3df3573494b43afa9a099aae057e535943fd4fd277b09e4b3755b37bf566894cab253804eb39ae009ed21f887414c4dad51b81f4ce816bbba8
-  data.tar.gz: 623e7caec5c6bdc116c350efe7ffde325e3cdb66e22c473f69cbe6efecc65de12c1d3e794c8625e9a01c24db6f783e828105e52cfa03b6005f5409fabe5f9131
+  metadata.gz: ad1115622e9f3c85fb12c63ba8268161054cca32675a081b6d43b5a11b1b5f1a55c0491a143631277c12aa2d019e10eb228acfcdb26fecce719a45f0336c8f3f
+  data.tar.gz: 236ca0df90dc5e0403fca4d494bcbeabf90117aabbd12c12175d3eecf4d2475fc36e432430e3ece7c61c651188c234daeef041ed148812d80ef71e983fda5afe

data/README.md

@@ -143,6 +143,64 @@ The front door is not an authentication boundary. Its host and same-origin check
 protect routing and POST actions, but a publicly reachable instance still needs
 access control such as VPN or SSO. Do not expose workspace backend ports directly.
 
+### Proxy middleware
+
+The front door can run Rack middleware around traffic that is forwarded to a workspace
+backend. The gem knows nothing about what a middleware does: the container or host
+that runs `serve` registers its own. Typical uses are injecting a script tag, adding a
+header, or logging.
+
+```ruby
+# my_middleware.rb
+Workspaces.configure_proxy do
+  use MyMiddleware, option: 'value'
+end
+```
+
+Load it with `serve --require FILE` (repeatable) or by setting `WORKSPACES_REQUIRE` to
+one or more paths separated like `PATH` entries. Environment entries load first, then
+`--require` files in order. A missing file or an error while loading stops `serve` with
+a non-zero exit instead of silently running without it. These files are executed with
+the front door's privileges, so only name files the operator controls. With nothing
+registered, the front door behaves exactly as before.
+
+Blocks run in registration order and the first `use` is outermost. The stack wraps only
+the step that forwards a request to a ready workspace backend. The dashboard, redirects
+for workspaces that are not ready, and error pages never pass through it. For each
+proxied request, two Rack env keys are available:
+
+| Key | Value |
+| --- | --- |
+| `workspaces.workspace_id` | The workspace ID, such as `main-1ae4815f` |
+| `workspaces.workspace` | The workspace snapshot hash (branch, status, related PR, and so on) |
+
+Two details matter when rewriting response bodies. The proxy passes the browser's
+`Accept-Encoding` to the backend, so a compressed response arrives compressed; set
+`env['HTTP_ACCEPT_ENCODING'] = 'identity'` before calling the app, or skip responses
+with a `Content-Encoding` header. If you change the body, drop the stale `Content-Length`
+header. An example that appends a script tag to HTML pages:
+
+```ruby
+class ScriptInjector
+  TAG = '<script src="https://example.test/widget.js" data-thread-id="%<id>s"></script>'
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    env['HTTP_ACCEPT_ENCODING'] = 'identity'
+    status, headers, body = @app.call(env)
+    return [status, headers, body] unless headers['content-type'].to_s.start_with?('text/html')
+
+    html = body.each.to_a.join.sub('</body>', format(TAG, id: env['workspaces.workspace_id']) + '</body>')
+    [status, headers.reject { |key, _| key.casecmp?('content-length') }, [html]]
+  end
+end
+
+Workspaces.configure_proxy { use ScriptInjector }
+```
+
 ### Local HTTPS
 
 To serve TLS directly, install/trust a local CA and create a certificate covering
@@ -198,6 +256,7 @@ and forwarded scheme/host headers; it does not change the internal listener to T
 | `WORKSPACES_PUBLIC_ORIGIN` | `http://localhost:4747` | Browser-facing dashboard origin and scheme |
 | `WORKSPACES_BASE_DOMAIN` | `localhost` | Preview hostname suffix |
 | `WORKSPACES_SUBDOMAIN_PREFIX` | `ws-` | Prefix before the workspace ID on preview hosts |
+| `WORKSPACES_REQUIRE` | none | Ruby files, separated like `PATH`, loaded by `serve` to register proxy middleware |
 
 Keep the project root, public origin, preview domain, and storage settings consistent
 across CLI and server processes. Changing the browser-facing origin requires restarting

data/lib/workspaces/cli.rb

@@ -5,6 +5,7 @@ require 'rack/handler/puma'
 require_relative 'registry'
 require_relative 'coordinator'
 require_relative 'front_door'
+require_relative 'proxy_middleware'
 require_relative 'tls'
 require_relative 'child_env'
 
@@ -86,6 +87,7 @@ module Workspaces
     end
 
     def parse_tls_options(parser, options)
+      parser.on('--require PATH') { |value| (options[:require] ||= []) << value }
       parser.on('--secure') { options[:secure] = true }
       parser.on('--tls-cert PATH') { |value| options[:tls_cert] = value }
       parser.on('--tls-key PATH') { |value| options[:tls_key] = value }
@@ -93,6 +95,7 @@ module Workspaces
 
     def serve(_id, options)
       tls = Tls.from_serve_options(options)&.validate!
+      ProxyMiddleware.load_files(ProxyMiddleware.env_paths + options.fetch(:require, []))
 
       if tls
         tls.apply_env_defaults { serve_with_tls(tls) }
@@ -196,7 +199,7 @@ module Workspaces
     end
 
     def usage
-      'Usage: bin/workspaces serve | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
+      'Usage: bin/workspaces serve [--require FILE] | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
         'list [--pr NUMBER] [--json] | show/start/prepare/restart ID [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | stop ID | ' \
         'exec ID -- COMMAND... | remove ID [--force]'
     end

data/lib/workspaces/front_door.rb

@@ -5,15 +5,22 @@ require 'net/http'
 require_relative 'coordinator'
 require_relative 'dashboard_view'
 require_relative 'environment_overrides'
+require_relative 'proxy_middleware'
 
 module Workspaces
   class FrontDoor
     WORKSPACE_ROUTE = %r{\A/workspaces/([a-z0-9]+(?:-[a-z0-9]+)*)
                           (?:/(status|start|prepare|restart|stop|remove|update-pr|environment))?\z}x
 
+    # Rack env keys set on requests that reach a ready workspace backend, for use by
+    # middleware registered with Workspaces.configure_proxy.
+    WORKSPACE_ID_ENV = 'workspaces.workspace_id'.freeze
+    WORKSPACE_ENV = 'workspaces.workspace'.freeze
+
     def initialize(coordinator: Coordinator.new, registry: Registry.new)
       @coordinator = coordinator
       @registry = registry
+      @forwarder = ProxyMiddleware.build(method(:forward_to_backend))
     end
 
     def call(env)
@@ -230,7 +237,9 @@ module Workspaces
       snapshot = @coordinator.snapshot(id, include_log: false)
       return unavailable(id, request) unless snapshot['status'] == 'ready' && !snapshot['active']
 
-      forward(id, request)
+      request.env[WORKSPACE_ID_ENV] = id
+      request.env[WORKSPACE_ENV] = snapshot
+      @forwarder.call(request.env)
     rescue IOError, SystemCallError, Timeout::Error => e
       response(502, "Workspace backend unavailable: #{e.class}")
     end
@@ -241,6 +250,11 @@ module Workspaces
       response(503, "Workspace not ready. Visit #{Config.dashboard_url(id)}")
     end
 
+    # Innermost app of the proxy stack: sends the request to the workspace backend.
+    def forward_to_backend(env)
+      forward(env.fetch(WORKSPACE_ID_ENV), Rack::Request.new(env))
+    end
+
     def forward(id, request)
       uri = URI("http://127.0.0.1:#{Backend.new(id).port}#{request.fullpath}")
       upstream = upstream_request(id, request, uri)

data/lib/workspaces/proxy_middleware.rb

@@ -0,0 +1,77 @@
+require 'rack'
+
+module Workspaces
+  # Adds a Rack middleware stack around workspace preview traffic.
+  #
+  # The gem stays unaware of what any middleware does: the process hosting the front
+  # door registers its own, for example from a file named by WORKSPACES_REQUIRE:
+  #
+  #   Workspaces.configure_proxy do
+  #     use MyMiddleware, option: 'value'
+  #   end
+  #
+  # Blocks are replayed in registration order into a Rack::Builder, so the first
+  # `use` is the outermost middleware. The stack wraps only the step that forwards a
+  # request to a ready workspace backend. The dashboard, redirects for workspaces that
+  # are not ready, and error responses never pass through it.
+  module ProxyMiddleware
+    ENV_VAR = 'WORKSPACES_REQUIRE'
+
+    # Raised for unusable configuration; the CLI reports it and exits non-zero.
+    class ConfigurationError < ArgumentError; end
+
+    @blocks = []
+
+    def self.register(&block)
+      raise ConfigurationError, 'Workspaces.configure_proxy requires a block' unless block
+
+      @blocks << block
+      self
+    end
+
+    def self.any?
+      !@blocks.empty?
+    end
+
+    def self.reset!
+      @blocks.clear
+    end
+
+    # Returns the endpoint untouched when nothing is registered, so an unconfigured
+    # front door behaves exactly as it did before this seam existed.
+    def self.build(endpoint)
+      blocks = @blocks.dup
+      return endpoint if blocks.empty?
+
+      Rack::Builder.new do
+        blocks.each { |block| instance_exec(&block) }
+        run endpoint
+      end.to_app
+    end
+
+    # Paths from WORKSPACES_REQUIRE, separated like PATH entries.
+    def self.env_paths
+      ENV.fetch(ENV_VAR, '').split(File::PATH_SEPARATOR).map(&:strip).reject(&:empty?)
+    end
+
+    # Executes the given Ruby files so they can register middleware. These files run
+    # with the privileges of the front door; only name files the operator controls.
+    def self.load_files(paths)
+      paths.each do |path|
+        full_path = File.expand_path(path)
+        raise ConfigurationError, "Proxy middleware file not found: #{path}" unless File.file?(full_path)
+
+        begin
+          require full_path
+        rescue ScriptError, StandardError => e
+          raise ConfigurationError, "Could not load proxy middleware #{path}: #{e.class}: #{e.message}"
+        end
+      end
+      paths
+    end
+  end
+
+  def self.configure_proxy(&block)
+    ProxyMiddleware.register(&block)
+  end
+end

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.9'
+  VERSION = '0.1.10'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -88,6 +88,7 @@ files:
 - lib/workspaces/paths.rb
 - lib/workspaces/port_allocator.rb
 - lib/workspaces/presentation.rb
+- lib/workspaces/proxy_middleware.rb
 - lib/workspaces/recipe.rb
 - lib/workspaces/registry.rb
 - lib/workspaces/state_store.rb