bellhop-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1927cc2855283474e17da014fdcb1f995f1204315a74d19ccd55ba280cf604a1
+  data.tar.gz: 647ab3f40a1d4f59b7522ba81e072e0c22544da07f6940113f9fb3ff8c9e4fed
+SHA512:
+  metadata.gz: c03cef5dfaae91754005bbcfed545b4af33ebc0114f8f5345444301edf1ee39a21edd4f980e335deaaaf3b731f97a7eb74b543e2bc89d7ffc66af24e7fb688b4
+  data.tar.gz: e267b73e0d9b43c5b4d016a40f24aa5ae29b92bf4e73ba061fd6de0ce07cbc821a6e5fb8d73d25c813c9cf5f046985650e364e86f83e0df574a0c74593e7bbf9

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+First release.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Fae Software Limited
+
+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,270 @@
+# Bellhop for Rails
+
+Print to the label printers and read the USB scales at a physical location,
+from your Rails application. The connection runs from your server to the
+machine at that location, and nothing sits in the middle of it.
+
+You need an app on [bellhop.dev](https://bellhop.dev). That is where agents
+are licensed and where your secret key comes from.
+
+```bash
+bundle add bellhop-rails
+bin/rails generate bellhop:install
+bin/rails db:migrate
+bin/rails bellhop:doctor
+```
+
+The generator writes the initializer and the migration, and mounts the engine
+at `/bellhop`. Two settings in the initializer matter.
+
+`secret_key` is on your app's page on bellhop.dev. Keep it in credentials.
+
+`public_url` is your application's public base URL. Its host is the **pairing
+host**: it goes in every pairing link, every credential is bound to it, and
+the agent compares it byte for byte. Pick it once. Changing it after agents
+have paired means all of them re-pair. Your socket can live on another host;
+the `transports` block in the claim response is for that.
+
+Ruby 3.2 and Rails 7.2 or later.
+
+## Using it
+
+```ruby
+# Add a location, then put the link in front of whoever is at the desk.
+agent = Bellhop::Agent.provision(label: "Shipping Desk")
+agent.pairing_link       # bellhop://pair?server=…&claim=…
+
+agent.print(kind: "label", format: :zpl, data: zpl)
+
+# Anything large goes by URL. The block runs once the job exists, so a
+# signed URL can name it.
+agent.print(kind: "packing_slip", format: :pdf) { |job| document_url(job, sig: sign(job)) }
+
+# Name a printer, and say how, when the desk's default is not what you want.
+agent.print(
+  kind: "packing_slip", format: :pdf,
+  printer: "Office_HP_LaserJet",
+  options: { copies: 2, duplex: "long-edge", paper: "Letter" }
+) { |job| document_url(job, sig: sign(job)) }
+
+# What the desk shared in its most recent hello.
+agent.printers
+# => [{ "id" => "Office_HP_LaserJet", "name" => "Office HP LaserJet",
+#       "capabilities" => { "papers" => ["Letter", "Legal", "A4"], "duplex" => true, ... } }]
+
+# Hear back from it.
+ActiveSupport::Notifications.subscribe("weight.bellhop") do |event|
+  ShippingForm.fill(event.payload[:agent], grams: event.payload[:grams])
+end
+
+ActiveSupport::Notifications.subscribe("ack.bellhop") do |event|
+  job = event.payload[:job]
+  Rails.logger.warn("#{job.id} failed: #{job.error}") if job.status == "failed"
+end
+```
+
+`kind` is yours; the agent never reads it. Formats are `zpl`, `pdf`, `gif`,
+and `raw`. Raw delivers any byte stream to the queue untouched: ESC/POS
+receipts, EPL, whatever your hardware speaks.
+
+A job that names a `printer` goes to it, by the `id` from the agent's
+inventory. A job that names none routes by format to the printer the operator
+picked for labels or for documents. If the agent is offline the job stays
+pending and goes out at its next handshake. Machines sleep overnight; that is
+normal.
+
+`options` is a closed set: `copies`, `duplex`, `paper`, `bin`, `dpi`,
+`color`, `pages`, `rotate`, `fit`, `collate`, `nup`. An option you leave out
+means whatever the printer does by default.
+
+Anything the gem can check without an agent, it checks before sending, and
+raises `Bellhop::AgentError` at your own line: a format the agent has not
+advertised, a printer its last hello did not report, an option the protocol
+does not define, an option that does not apply to the format, a value outside
+its range, a malformed page range, an inline document over 50 MB. What only
+the desk can know (does that laser printer hold Letter?) the agent checks
+before printing and reports in the ack, with an `error_code` your code can
+branch on.
+
+## When it does not pair
+
+```
+$ bin/rails bellhop:doctor
+
+  ✓ pairing host  deliver.example.com
+  ✓ secret key    authenticated as "Deliver"
+  ✓ plan          fleet, 34/100 agents
+  ✓ scales        allowed on this plan
+  ✓ signing keys  https://bellhop.dev publishes 2026-08
+  ✓ cable adapter solid_cable
+  ✓ transports    websocket and http
+  ✓ poll budget   poll_seconds is 0, so no request is ever held
+```
+
+Every one of those failures looks the same from the outside. Start here.
+
+## Transports
+
+Both are mounted. The agent prefers the socket and falls back to HTTP by
+itself after three failed upgrades, which is what gets a shipping desk behind
+a corporate proxy working.
+
+The socket is Action Cable's server with Action Cable's protocol stripped off.
+The wire carries flat JSON: no subscription handshake, no channel identifier,
+no JSON inside JSON, and no welcome message. What Action Cable provides is
+connection lifecycle and a pubsub backplane, so a print created on one Puma
+worker reaches a socket held by another. The engine runs its own
+`ActionCable::Server::Base`, so your application's cable configuration is
+untouched. Request forgery protection is off on that instance only. The agent
+is a native application and sends no `Origin` header, and Action Cable
+refuses a connection without one. There is no browser and no cookie in play,
+so there is nothing to protect.
+
+No Action Cable at all, as in an API-only or `--minimal` application? The
+engine skips the socket route, advertises HTTP alone, and `doctor` says so.
+
+### `poll_seconds` is 0 by default
+
+Rails serves requests from a fixed Puma thread pool, three per worker out of
+the box. A held poll occupies one thread for its whole duration. Three agents
+on a 25 second poll would park every thread and your application would stop
+serving.
+
+At 0 the request returns at once, the agent settles into polling every 3
+seconds, and a label comes out within 3 seconds of being created. Nobody
+standing at a printer notices that. Raise it only after counting your
+threads; `doctor` does the arithmetic against your agent count.
+
+## Running more than one process
+
+The socket needs a real pubsub adapter: `solid_cable` on a default Rails 8
+app, or Redis. With the `async` adapter a print created by one worker cannot
+reach a socket held by another, and `doctor` warns you. HTTP has no such
+need. Its queue is a table row, so any process can write to it.
+
+One caveat on `solid_cable`. It polls the database from every process, and
+this gem subscribes one channel per connected agent, so the backplane itself
+becomes database load as the fleet grows. It is fine to about a thousand
+agents. Plan on Redis beyond that; `doctor` tracks your fleet size and says
+when.
+
+Bellhop's socket server inherits the app's cable adapter. To give it its
+own, set `config.cable` to a hash in the shape of `cable.yml`. An app on
+AnyCable has to: AnyCable's adapter only broadcasts to the Go server and
+cannot subscribe from Rails, so a print created on one worker would never
+reach a socket held by another, and the engine refuses to boot on it.
+Point Bellhop at Solid Cable or Redis instead:
+
+```ruby
+config.cable = { adapter: "solid_cable" }
+config.cable = { adapter: "redis", url: ENV["REDIS_URL"] }
+```
+
+Solid Cable reads `connects_to` and its polling settings from `cable.yml`
+whatever adapter line that file carries, so those stay put. The agent's
+socket stays on Puma and never touches AnyCable.
+
+## Plan changes
+
+Entitlements live in the credential and are read when it is minted. On its
+own, a plan change waits for the next renewal. Renewal is automatic as agents
+connect, and `rails bellhop:renew` sweeps on demand.
+
+Register `https://deliver.example.com/bellhop/webhook` on your app's page on
+bellhop.dev and the wait goes away. bellhop.dev calls when the plan changes,
+the engine verifies the delivery against the published signing keys, and
+every paired agent is pushed a credential with the new entitlements.
+bellhop.dev also calls when an agent is removed there, and the engine retires
+it here too: connection closed, row gone. There is no webhook secret to hold.
+Behind it are `Bellhop.refresh!` and `Bellhop.retire_deactivated!`, which you
+can also call by hand. Each runs from Active Job when your app has it and
+inline when it does not.
+
+## The admin
+
+It is at the engine's mount point. It is open in development and refuses to
+render anywhere else until you say who may see it:
+
+```ruby
+config.admin_authenticator = ->(controller) { controller.current_user&.admin? }
+```
+
+It lists your agents and can print to them or unpair them, so it should not
+become reachable just because the engine is mounted.
+
+It ships with its own standalone layout and a `<style>` block, in the same
+plum and blush as bellhop.dev. Nothing to precompile, nothing that leaks into
+the rest of your application. The fonts load from Google Fonts; delete that
+`<link>` from the layout and the stacks fall back to Georgia and the system
+sans.
+
+To change how it looks, or to put it inside your own layout:
+
+```bash
+bin/rails generate bellhop:admin
+```
+
+That copies the controllers and views into your application, stylesheet
+partial included. Rails resolves your paths ahead of an engine's, so from
+then on yours render.
+
+### The test label
+
+The admin's **Label** button prints `Bellhop.test_label`: the Bellhop mark and
+two lines of text, anchored to the top left corner so it comes out whole on
+anything from 1.25in stock up. ZPL has no way to ask a printer how wide its
+stock is, so the default never assumes a width.
+
+When you know the width, say so in dots and the label is centred across it:
+
+```ruby
+Bellhop.test_label(width: 812)   # 4in at 203 dpi
+```
+
+## Testing
+
+Printing to a real agent is the right way to check that a label comes out.
+For CI, where no agent exists:
+
+```ruby
+require "bellhop/testing"
+
+agent = Bellhop::Agent.provision(label: "Test")
+agent = Bellhop::Testing::FakeAgent.claim(agent)
+
+agent.print(kind: "label", format: :zpl, data: zpl)
+
+assert_equal 1, agent.printed.size
+assert_includes agent.printed.first[:data], "^XA"
+```
+
+`FakeAgent` speaks the protocol the way the real agent does. It deduplicates
+by job id and answers `ping`. `fail_prints:` exercises your error path,
+`capabilities:` exercises the gate on formats an agent cannot handle,
+`printers:` shapes the inventory it advertises, and `default_printers:` sets
+the role map. Each entry in `printed` carries the `printer` and `options` the
+job named.
+
+## What it will not do
+
+**Validate inbound messages against the schemas.** Both sides ignore what
+they do not recognise. That rule is the protocol's only forward-compatibility
+mechanism, and enforcing schemas would break it.
+
+**Log tokens.** Claim tokens, agent tokens, credentials, and the
+`Authorization` header stay out of log lines. `bellhop:pair` prints a link
+that nothing else records, because the link is the claim token.
+
+**Redeliver on every `hello`.** A `hello` arrives mid-session whenever an
+operator changes a printer. Re-sending outstanding jobs each time can outrun
+the agent's deduplication ledger and print the same label several times. Only
+the first `hello` on a connection redelivers. A reconnect is a new
+connection, so at-least-once delivery still holds.
+
+## Reference
+
+The protocol reference at https://bellhop.dev/docs/protocol is normative.
+Where this gem disagrees with it, the gem is wrong. The integration guide is
+at https://bellhop.dev/docs.
+
+MIT licence.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+  t.warning = false
+end
+
+task default: :test

data/app/controllers/bellhop/admin/agents_controller.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Bellhop
+  module Admin
+    class AgentsController < BaseController
+      def index
+        @agents = Agent.order(:id)
+        @jobs   = PrintJob.recent.limit(20).includes(:agent)
+      end
+
+      def create
+        @agent = Agent.provision(label: params.require(:label))
+        render :pair
+      rescue LicensingError => e
+        @error = e
+        render :problem, status: :bad_gateway
+      end
+
+      def repair
+        @agent = Agent.find(params[:id]).repair!
+        render :pair
+      end
+
+      def print
+        Agent.find(params[:id]).print(kind: "label", format: :zpl, data: Bellhop.test_label)
+        redirect_to agents_path
+      rescue AgentError => e
+        redirect_to agents_path, alert: e.message
+      end
+
+      def remove
+        Agent.find(params[:id]).decommission!
+        redirect_to agents_path
+      end
+    end
+  end
+end

data/app/controllers/bellhop/admin/base_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Bellhop
+  module Admin
+    # Open in development, and refuses to render anywhere else until
+    # `config.admin_authenticator` is set. `rails generate bellhop:admin`
+    # copies these controllers and views into your application.
+    class BaseController < ActionController::Base
+      protect_from_forgery with: :exception
+
+      layout "bellhop/admin"
+
+      before_action :authenticate_admin
+
+      private
+        def authenticate_admin
+          authenticator = Bellhop.config.admin_authenticator
+
+          if authenticator
+            head :forbidden unless authenticator.call(self)
+          elsif !Rails.env.local?
+            render plain: <<~MESSAGE, status: :forbidden
+              The Bellhop admin is not configured.
+
+              It lists your agents and can print to them or unpair them, so it
+              refuses to render outside development until you say who may see it:
+
+                Bellhop.configure do |config|
+                  config.admin_authenticator = ->(controller) { controller.current_user&.admin? }
+                end
+
+              Or stop mounting the engine's admin and use your own.
+            MESSAGE
+          end
+        end
+    end
+  end
+end

data/app/controllers/bellhop/claims_controller.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Bellhop
+  # Pairing. Runs once per agent, in front of a person at a printer, and is
+  # the only unauthenticated route the engine owns. The exchange itself lives
+  # in Bellhop::ClaimExchange; this is the HTTP shell around it.
+  class ClaimsController < ActionController::API
+    before_action :enforce_rate_limit
+
+    def create
+      if params[:claim_token].blank?
+        return fail_with(:bad_request, "invalid_request", "That pairing link is missing its claim token.")
+      end
+
+      result = ClaimExchange.perform(params[:claim_token])
+
+      render json: {
+        # Appears in this response and nowhere else.
+        agent_token:  result.agent_token,
+        agent_name:   result.agent.label,
+        app_name:     result.agent.app_name.presence || Bellhop.config.app_name || "Bellhop",
+        accent_color: result.agent.accent_color.presence || Bellhop.config.accent_color,
+        credential:   result.activation["credential"],
+        transports:   transports
+      }.compact
+    rescue ClaimExchange::ExpiredClaim
+      fail_with(:not_found, "claim_expired", "That pairing link has expired. Ask for a new one.")
+    rescue LicensingError => e
+      Bellhop.logger.warn { "[bellhop] activation failed (#{e.code}); the claim token stays valid" }
+      fail_with(:bad_gateway, e.code, e.operator_message)
+    end
+
+    private
+      # Where to connect, most preferred first. This is the hook for moving
+      # the socket to another host; the credential does not care where it is.
+      def transports
+        list = []
+        list << { type: "websocket", url: Bellhop.config.socket_url } if Bellhop.cable_available?
+        list << { type: "http", url: Bellhop.config.http_url }
+        list
+      end
+
+      # The agent shows `message` to whoever is at the printer.
+      def fail_with(status, code, message)
+        render status: status, json: { error: { code: code, message: message } }
+      end
+
+      def enforce_rate_limit
+        limit = Bellhop.config.claim_rate_limit
+        return if limit.blank?
+
+        key = "bellhop:claim:#{request.remote_ip}"
+        Rails.cache.write(key, 0, expires_in: 1.minute, unless_exist: true)
+        count = Rails.cache.increment(key, 1) || 1
+        return if count <= limit
+
+        fail_with(:too_many_requests, "too_many_requests", "Too many pairing attempts. Wait a minute and try again.")
+      end
+  end
+end

data/app/controllers/bellhop/transport_controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Bellhop
+  # The HTTP transport: three routes and a table. This is what works behind
+  # corporate proxies that break WebSocket upgrades, and it is the whole
+  # transport on a host with no Action Cable.
+  class TransportController < ActionController::API
+    before_action :authenticate
+    before_action :find_session, except: :create
+
+    # POST /sessions. The body is `hello`.
+    def create
+      hello = params.to_unsafe_h.slice(*%w[type protocol_version agent_version platform session_id capabilities printers default_printers])
+      return render(status: :bad_request, json: { error: "expected_hello" }) if hello["type"] != "hello"
+
+      if hello["protocol_version"].to_i != PROTOCOL_VERSION
+        return render(status: :upgrade_required, json: { error: "unsupported_version" })
+      end
+
+      session    = Session.open!(@agent)
+      connection = HttpConnection.new(session, handshake: true)
+
+      # Protocol.receive queues `ready` and then any outstanding jobs. `ready`
+      # goes inline in this response; the rest waits for the first poll.
+      Protocol.receive(@agent, connection, hello)
+      queued = session.drain
+      ready  = queued.shift
+      queued.each { |message| session.push(message) }
+
+      render status: :created, json: {
+        session_id:   session.id,
+        poll_seconds: Bellhop.config.poll_seconds,
+        message:      ready
+      }
+    end
+
+    # GET /sessions/:id/messages. An empty result is normal.
+    def index
+      render json: { messages: @session.drain }
+    end
+
+    # POST /sessions/:id/messages, batched. Anything queued meanwhile rides
+    # back in the response.
+    def update
+      connection = HttpConnection.new(@session, handshake: false)
+      Array(params[:messages]).each do |message|
+        Protocol.receive(@agent, connection, message.to_unsafe_h)
+      end
+
+      render json: { messages: @session.drain }
+    end
+
+    # DELETE /sessions/:id. Expiry covers the case where it never arrives.
+    def destroy
+      @session.destroy
+      render json: {}
+    end
+
+    private
+      def authenticate
+        @agent = Agent.authenticate(Tokens.bearer(request.headers["Authorization"]))
+        render(status: :unauthorized, json: { error: "unauthorized" }) unless @agent
+      end
+
+      # A 404 means "open a new one".
+      def find_session
+        @session = @agent.sessions.find_by(id: params[:id])
+        render(status: :not_found, json: { error: "no_such_session" }) unless @session
+      end
+  end
+end

data/app/controllers/bellhop/webhooks_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Bellhop
+  # bellhop.dev's webhook. The event name is signed, so a verified delivery is
+  # safe to dispatch on. `agent.deactivated` retires the removed agents.
+  # Anything else, including events this version has never heard of, means
+  # entitlements moved: re-mint every paired agent's credential. The work runs
+  # from a job so this answers at once however large the fleet.
+  class WebhooksController < ActionController::API
+    def create
+      unless WebhookVerifier.valid?(request.headers["Bellhop-Signature"],
+        event: params[:event].to_s, app: params[:app].to_s)
+        return render status: :unauthorized, json: { error: "invalid_signature" }
+      end
+
+      case params[:event]
+      when "agent.deactivated"
+        Bellhop.logger.info { "[bellhop] webhook received (#{params[:event]}); retiring removed agents" }
+        Bellhop.retire_deactivated_later
+      else
+        Bellhop.logger.info { "[bellhop] webhook received (#{params[:event]}); refreshing credentials" }
+        Bellhop.refresh_later
+      end
+
+      render status: :accepted, json: { ok: true }
+    rescue LicensingError
+      # The key set could not be fetched. A 5xx makes bellhop.dev redeliver.
+      head :service_unavailable
+    end
+  end
+end