blackevin 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c81bfd943d2a666cb4708cbf7fb68dda7e9bfa73a4563ad3ec444475031bc62
+  data.tar.gz: ef8433cd9a72fe8429521b93e2724044ec5fac06a94af1053962db3e67468379
+SHA512:
+  metadata.gz: f11f01f55bbc204af64100bffb53e88540c3c8374c80df2d42a68b551279f9f3b80c0fc3611458fcd5643645a6efbad48b8f4a073af44c76c2b96e4811959193
+  data.tar.gz: d4fe938a5b52edfe02b9cf9e86b300b6ebe98fcceb22807dc0c7d7eb937b39f8f010a4a9de9c0f804f61359338934e523f536f9bd15ecac2484729a768d846e6

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.1
+
+- Remove lint from CI
+
+## 0.1.0
+
+First release. Server-side REST client, standard library only.
+
+- `Blackevin::Rest` — `auth.create_token_request` (local HMAC signing), `auth.request_token`,
+  `channels.get(name).publish / history`, `presence.get / history`, `clients.disconnect`,
+  and `queues` (list, upsert, update, delete, rules, add_rule, delete_rule).
+- `Blackevin.configure` and `Blackevin.rest` for a process-wide client; reads `BLACKEVIN_KEY`,
+  `BLACKEVIN_REST_ENDPOINT` and `BLACKEVIN_ENDPOINT`.
+- `Blackevin::TokenEndpoint`, a Rack application for the browser's `authUrl`, mountable in Rails,
+  Sinatra and Hanami.
+- An optional Railtie: `config.blackevin.*` and `credentials.blackevin.key`.
+- `Blackevin::Error` (`status_code`, `reason`, `quota?`), `Blackevin::ConnectionError`,
+  `Blackevin::ConfigurationError`.
+- Pattern matching (`deconstruct_keys`) on errors, token requests, token details and every returned value.
+- Ruby 3.0 and up. The suite runs on 3.0 through 3.4.
+- Tested against the language-neutral contract in `spec/contract`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thadeu Esteves Jr
+
+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,248 @@
+# blackevin
+
+The server-side Ruby SDK for [Blackevin](https://blackevin.com) realtime.
+
+Sign token requests for your browsers, publish from a job or a webhook, read
+history and presence, manage queues.
+
+**No runtime dependencies.** `net/http`, `openssl` and `json` from the standard
+library — nothing that can break under you in an upgrade. Ruby 3.0 and up, in
+Rails, Sinatra, Hanami or a plain script.
+
+```ruby
+gem "blackevin"
+```
+
+## Configure
+
+With `BLACKEVIN_KEY` in the environment there is nothing to configure:
+
+```ruby
+Blackevin.rest.channels.get("room:42").publish("greeting", {text: "hi"})
+```
+
+Or say it explicitly, once, at boot:
+
+```ruby
+Blackevin.configure do |config|
+  config.key = ENV.fetch("BLACKEVIN_KEY")   # secret.keyId, from the console
+  config.open_timeout = 5                   # seconds
+  config.read_timeout = 10
+end
+```
+
+`Blackevin.rest` is one shared, thread-safe client. For more than one key, build
+your own: `Blackevin::Rest.new(key: …)`.
+
+Against a local or self-hosted node, which serves REST and the socket from one
+origin, set `BLACKEVIN_ENDPOINT=ws://localhost:3000` (or `config.endpoint`) and the
+REST base is derived from it.
+
+## Token endpoint — the part every app needs
+
+Your API key is your account, so it never goes to a browser. The browser asks
+**your** server for a TokenRequest: signed with the key, scoped to what this
+user may touch, dead after its `ttl`. Signing is local — no call to Blackevin, so
+your sign-in never depends on us being reachable.
+
+The browser side is the JavaScript SDK with `authUrl: "/blackevin/token"`.
+
+### Rails
+
+```ruby
+# app/controllers/blackevin_tokens_controller.rb
+class BlackevinTokensController < ApplicationController
+  before_action :authenticate_user!
+
+  def show
+    render json: Blackevin.rest.auth.create_token_request(
+      client_id: current_user.id,
+      ttl: 1.hour.in_milliseconds,
+      capability: {
+        "team:#{current_user.team_id}" => %w[subscribe publish],
+        "presence:team:#{current_user.team_id}" => %w[presence]
+      }
+    )
+  end
+end
+
+# config/routes.rb
+resource :blackevin_token, only: :show, path: "blackevin/token"
+```
+
+The key can live in credentials instead of the environment — the Railtie reads
+`credentials.blackevin.key`, and `config.blackevin.*` in an environment file:
+
+```ruby
+# config/environments/development.rb
+config.blackevin.endpoint = "ws://localhost:3000"
+```
+
+### Sinatra
+
+```ruby
+require "sinatra"
+require "blackevin"
+
+get "/blackevin/token" do
+  halt 401 unless current_user
+
+  content_type :json
+  Blackevin.rest.auth.create_token_request(client_id: current_user.id).to_json
+end
+```
+
+### Anything Rack (Hanami, Roda, `config.ru`)
+
+`Blackevin::TokenEndpoint` is a Rack application. The block receives the Rack env
+and answers who is asking; `nil` is a 401.
+
+```ruby
+TOKENS = Blackevin::TokenEndpoint.new do |env|
+  user = env["warden"]&.user
+
+  next unless user
+
+  {client_id: user.id, capability: {"team:#{user.team_id}" => %w[subscribe publish]}}
+end
+
+# Hanami:  mount TOKENS, at: "/blackevin/token"
+# Rails:   mount TOKENS, at: "/blackevin/token"
+# Rack:    map("/blackevin/token") { run TOKENS }
+```
+
+## Publish
+
+```ruby
+channel = Blackevin.rest.channels.get("orders:#{order.id}")
+
+channel.publish("status", {state: "shipped"})
+```
+
+It goes through the same fanout a socket publish does: subscribers, account
+queues and integrations all see it. One HTTP request per publish — from a Rails
+request, prefer a job:
+
+```ruby
+class BlackevinPublishJob < ApplicationJob
+  retry_on Blackevin::ConnectionError, wait: :polynomially_longer
+
+  def perform(channel, event, data)
+    Blackevin.rest.channels.get(channel).publish(event, data)
+  end
+end
+```
+
+## History and presence
+
+```ruby
+channel.history(limit: 50)        # => [Blackevin::Message], newest first
+channel.presence.get              # => [Blackevin::PresenceMember]
+channel.presence.history          # => [Blackevin::PresenceEvent]
+
+message = channel.history.first
+message.name        # "status"
+message.data        # {"state" => "shipped"}
+message.time        # a Time; message.timestamp is the wire value, in ms
+```
+
+## Sign a user out everywhere
+
+```ruby
+Blackevin.rest.clients.disconnect(user.id)   # => how many connections were closed
+```
+
+## Queues
+
+The key needs the `amqp-subscribe` capability. A queue is addressed by its `id`.
+
+```ruby
+queues = Blackevin.rest.queues
+
+queue = queues.upsert(name: "inbox", max_length: 10_000)
+queues.add_rule(queue.id, source_pattern: "orders:*")
+
+queues.update(queue.id, enabled: false)   # pause
+queues.list(all: true)                    # paused ones included
+queues.delete(queue.id)
+```
+
+## Errors
+
+One rescue covers everything the SDK raises:
+
+```ruby
+begin
+  channel.publish("status", payload)
+rescue Blackevin::Error => error
+  error.status_code   # 403, 429, … or nil when no response arrived
+  error.reason        # "queue_limit", "connection_limit", or nil
+  error.quota?        # a plan ceiling — show an upgrade prompt, retry later
+  error.message       # the server's own sentence; do not branch on it
+end
+```
+
+Errors, token requests and every returned value support pattern matching, so a
+rescue can branch by shape:
+
+```ruby
+rescue Blackevin::Error => error
+  case error
+  in {reason: "queue_limit"} then redirect_to upgrade_path
+  in {status_code: 401 | 403} then raise
+  in {status_code: nil} then retry_job wait: 30.seconds
+  end
+```
+
+- `Blackevin::ConnectionError` — DNS, refused, TLS, timeout. Worth retrying.
+- `Blackevin::ConfigurationError` — a missing or malformed key, raised before any request.
+
+## Acting as one client
+
+A token instead of a key restricts the client to that token's capability:
+
+```ruby
+details = Blackevin.rest.auth.request_token(
+  Blackevin.rest.auth.create_token_request(client_id: "worker-1", capability: {"jobs:*" => %w[publish]})
+)
+
+Blackevin::Rest.new(token: details.token).channels.get("jobs:1").publish("done")
+```
+
+## Testing your app
+
+Swap the transport and nothing leaves the process:
+
+```ruby
+Blackevin.configure do |config|
+  config.key = "secret.test"
+  config.transport = ->(request) { Blackevin::Response.new(status: 200, body: "{}") }
+end
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake            # rspec + standard
+bundle exec rake contract:sync   # refresh spec/contract from ../blackevin/spec
+```
+
+### Releasing
+
+Bump `lib/blackevin/version.rb`, add the entry to `CHANGELOG.md`, commit, then:
+
+```sh
+bundle exec rake tag   # tags vX.Y.Z from version.rb and pushes it
+```
+
+The tag runs `.github/workflows/release.yml`: lint, tests, publish to RubyGems by
+Trusted Publishing (no API key), and a GitHub release with the `.gem` attached.
+
+`spec/contract` is a copy of the language-neutral contract — an OpenAPI file and
+JSON fixtures — that every Blackevin SDK is tested against. The suite fails when
+the contract gains an operation this gem does not implement.
+
+## License
+
+MIT.

data/blackevin.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/blackevin/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "blackevin"
+  spec.version = Blackevin::VERSION
+  spec.authors = ["Blackevin"]
+
+  spec.summary = "Blackevin Ruby SDK"
+  spec.description = "Sign token requests, publish, read history and presence, and manage queues on Blackevin. " \
+    "Standard library only: no runtime dependencies. Ruby 3.0 and up. Works in Rails, Sinatra, Hanami or plain Ruby."
+  spec.homepage = "https://blackevin.com"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata = {
+    "rubygems_mfa_required" => "true",
+    "documentation_uri" => "https://docs.blackevin.com",
+    "source_code_uri" => "https://github.com/thadeu/blackevin-ruby",
+    "changelog_uri" => "https://github.com/thadeu/blackevin-ruby/blob/main/CHANGELOG.md"
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["README.md", "CHANGELOG.md", "LICENSE", "blackevin.gemspec", "lib/**/*.rb"]
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", ">= 13.0"
+  spec.add_development_dependency "rspec", ">= 3.13", "< 4.0"
+  spec.add_development_dependency "standard", ">= 1.0"
+  spec.add_development_dependency "railties", ">= 7.0"
+end

data/lib/blackevin/api_key.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Blackevin
+  # An API key, written +secret.keyId+.
+  #
+  # Split on the LAST dot: the keyId carries none, so everything before it is
+  # the secret verbatim. Same rules as the node, pinned by the contract fixtures.
+  class ApiKey
+    attr_reader :key_name, :secret
+
+    # @param raw [String] the key as copied from the console
+    # @raise [Blackevin::ConfigurationError] when it is not +secret.keyId+
+    def self.parse(raw)
+      case raw.to_s.strip.rpartition('.')
+      in [secret, '.', key_name] unless secret.empty? || key_name.empty?
+        new(key_name, secret)
+      else
+        raise ConfigurationError, 'malformed API key: expected secret.keyId'
+      end
+    end
+
+    def initialize(key_name, secret)
+      @key_name = key_name
+      @secret = secret
+    end
+
+    # Never print the secret: this object ends up in logs and error reports.
+    def inspect = "#<Blackevin::ApiKey key_name=#{key_name.inspect} secret=[FILTERED]>"
+  end
+end

data/lib/blackevin/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Blackevin
+  # Process-wide defaults for {Blackevin.rest}.
+  #
+  #   Blackevin.configure do |config|
+  #     config.key = ENV.fetch("BLACKEVIN_KEY")
+  #   end
+  #
+  # Nothing here is required: with +BLACKEVIN_KEY+ in the environment,
+  # {Blackevin.rest} works unconfigured.
+  class Configuration
+    ENV_KEY = 'BLACKEVIN_KEY'
+
+    # @return [String, nil] the full API key, +secret.keyId+
+    attr_writer :key
+
+    # @return [String, nil] REST base URL; see {Blackevin::Endpoints}
+    attr_accessor :rest_endpoint
+
+    # @return [String, nil] socket endpoint, read only to derive the REST base for a single-origin node
+    attr_accessor :endpoint
+
+    # @return [Numeric] seconds
+    attr_accessor :open_timeout, :read_timeout
+
+    # @return [#call, nil] replaces the Net::HTTP transport
+    attr_accessor :transport
+
+    def initialize
+      @open_timeout = 5
+      @read_timeout = 10
+    end
+
+    def key = @key || ENV[ENV_KEY]
+
+    # @return [Hash] the options {Blackevin::Rest.new} takes
+    def to_rest_options
+      {
+        key: key,
+        rest_endpoint: rest_endpoint,
+        endpoint: endpoint,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout,
+        transport: transport
+      }
+    end
+  end
+end

data/lib/blackevin/endpoints.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Blackevin
+  # Which hosts the SDK talks to: explicit option, then environment, then the
+  # production default.
+  #
+  # The REST base is derived from the socket endpoint only when that endpoint
+  # was given, because a dev or self-hosted node serves both from one origin.
+  # Production serves them from two names, so the default never derives.
+  module Endpoints
+    DEFAULT_WS = 'wss://ws.blackevin.com'
+    DEFAULT_REST = 'https://api.blackevin.com'
+
+    ENV_WS = 'BLACKEVIN_ENDPOINT'
+    ENV_REST = 'BLACKEVIN_REST_ENDPOINT'
+
+    Resolved = Struct.new(:endpoint, :rest_endpoint, keyword_init: true)
+
+    module_function
+
+    # @param endpoint [String, nil] socket endpoint, e.g. "ws://localhost:3000"
+    # @param rest_endpoint [String, nil] REST base URL
+    # @param env [#[]] injected for tests; defaults to ENV
+    # @return [Resolved]
+    def resolve(endpoint: nil, rest_endpoint: nil, env: ENV)
+      explicit_ws = present(endpoint) || present(env[ENV_WS])
+
+      rest = present(rest_endpoint) ||
+             present(env[ENV_REST]) ||
+             (explicit_ws ? derive_rest(explicit_ws) : DEFAULT_REST)
+
+      Resolved.new(endpoint: explicit_ws || DEFAULT_WS, rest_endpoint: rest)
+    end
+
+    def derive_rest(ws_endpoint) = ws_endpoint.sub(/\Aws/i, 'http').delete_suffix('/')
+
+    def present(value) = value.to_s.strip.then { _1.empty? ? nil : _1 }
+  end
+end

data/lib/blackevin/errors.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Blackevin
+  # What the server said when it refused.
+  #
+  # Branch on {#status_code} and {#reason}, never on the message: the message
+  # is the server's sentence, written for a person.
+  class Error < StandardError
+    QUOTA_STATUS = 429
+
+    # @return [Integer, nil] the HTTP status, or nil when no response arrived
+    attr_reader :status_code
+
+    # @return [String, nil] a stable slug such as "queue_limit", when the server sent one
+    attr_reader :reason
+
+    def initialize(message, status_code = nil, reason = nil)
+      super(message)
+
+      @status_code = status_code
+      @reason = reason
+    end
+
+    # True when this is a plan ceiling rather than a bug or a bad credential.
+    def quota? = status_code == QUOTA_STATUS
+
+    # Lets a rescue branch by shape instead of by a chain of conditionals:
+    #
+    #   case error
+    #   in {reason: "queue_limit"} then upgrade_prompt
+    #   in {status_code: 401 | 403} then rotate_key
+    #   in {status_code: nil} then retry_later
+    #   end
+    def deconstruct_keys(_keys) = { status_code: status_code, reason: reason, message: message }
+
+    # Builds the error for a non-2xx response, keeping the server's sentence.
+    #
+    # A body that is not JSON degrades to the status alone: a proxy answering
+    # HTML on a 502 must not replace a useful error with a parse failure.
+    #
+    # @param what [String] the operation label, e.g. "publish"
+    # @param status [Integer]
+    # @param body [String, nil] the raw response body
+    # @return [Blackevin::Error]
+    def self.from_response(what, status, body)
+      parsed = parse(body)
+
+      detail = case parsed
+               in { error: String => sentence } unless sentence.empty? then sentence
+               else status
+               end
+
+      reason = case parsed
+               in { reason: String => slug } then slug
+               else nil
+               end
+
+      new("#{what} failed: #{detail}", status, reason)
+    end
+
+    def self.parse(body)
+      case JSON.parse(body.to_s, symbolize_names: true)
+      in Hash => parsed then parsed
+      else {}
+      end
+    rescue JSON::ParserError
+      {}
+    end
+
+    private_class_method :parse
+  end
+
+  # The request never produced a response: DNS, refused connection, TLS, timeout.
+  class ConnectionError < Error
+    def initialize(message)
+      super(message, nil, nil)
+    end
+  end
+
+  # The SDK was given something it cannot work with, before any network call.
+  class ConfigurationError < Error
+    def initialize(message)
+      super(message, nil, nil)
+    end
+  end
+end

data/lib/blackevin/railtie.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Blackevin
+  # Loaded only when Rails is. Lets the key live where a Rails app keeps secrets:
+  #
+  #   # config/credentials.yml.enc
+  #   blackevin:
+  #     key: ck_live_….kAbC
+  #
+  # and lets an environment file set the rest:
+  #
+  #   config.blackevin.rest_endpoint = "http://localhost:3000"
+  #
+  # An explicit +Blackevin.configure+ or +BLACKEVIN_KEY+ still wins over credentials.
+  class Railtie < Rails::Railtie
+    SETTINGS = %i[key rest_endpoint endpoint open_timeout read_timeout transport].freeze
+
+    config.blackevin = ActiveSupport::OrderedOptions.new
+
+    initializer 'blackevin.configure' do |app|
+      options = app.config.blackevin
+      credentials_key = app.credentials.dig(:blackevin, :key) if app.respond_to?(:credentials)
+
+      Blackevin.configure do |config|
+        SETTINGS.each do |setting|
+          value = options[setting]
+
+          config.public_send(:"#{setting}=", value) unless value.nil?
+        end
+
+        config.key = credentials_key if config.key.nil? && credentials_key
+      end
+    end
+  end
+end

data/lib/blackevin/rest/auth.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Blackevin
+  class Rest
+    # Token requests: signing one locally, and exchanging one for a token.
+    class Auth
+      DEFAULT_TTL_MS = 3_600_000
+      DEFAULT_CAPABILITY = {"*" => %w[subscribe publish presence history]}.freeze
+
+      def initialize(rest, clock: nil, nonce: nil)
+        @rest = rest
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) }
+        @nonce = nonce || -> { SecureRandom.hex(16) }
+      end
+
+      # Signs a TokenRequest for a browser to exchange.
+      #
+      # Local: no network call. Your server holds the secret and hands out
+      # something scoped and short-lived, so Blackevin is never on the critical
+      # path of your own sign-in.
+      #
+      # @param client_id [String, Integer, nil] who the token will act as
+      # @param ttl [Integer, nil] milliseconds; default one hour, maximum 48 hours
+      # @param capability [Hash, String, nil] channel pattern to allowed operations.
+      #   A Hash is serialised compactly in insertion order; a String is signed byte for byte.
+      # @param timestamp [Integer, nil] milliseconds since the epoch; default now
+      # @param nonce [String, nil] default random
+      # @return [Blackevin::TokenRequest] signed
+      # @raise [Blackevin::ConfigurationError] without a usable API key
+      def create_token_request(client_id: nil, ttl: nil, capability: nil, timestamp: nil, nonce: nil)
+        api_key = @rest.api_key
+
+        request = TokenRequest.new(
+          key_name: api_key.key_name,
+          ttl: ttl || DEFAULT_TTL_MS,
+          capability: serialise(capability),
+          client_id: client_id&.to_s,
+          timestamp: timestamp || @clock.call,
+          nonce: nonce || @nonce.call
+        )
+
+        request.sign(api_key.secret)
+      end
+
+      # Exchanges a TokenRequest for a token.
+      #
+      # Usually the browser's job. A server wanting a token for its own use —
+      # to act as one client under a narrow capability — does it here.
+      #
+      # @param token_request [Blackevin::TokenRequest, Hash]
+      # @return [Blackevin::TokenDetails]
+      # @raise [Blackevin::Error]
+      def request_token(token_request)
+        wire =
+          case token_request
+          in TokenRequest => signed then signed.to_h
+          in Hash => hash then TokenRequest.from_h(hash).to_h
+          else raise ConfigurationError, "request_token takes a TokenRequest or a Hash, got #{token_request.class}"
+          end
+        path = "/keys/#{Rest.escape(wire.fetch("keyName"))}/requestToken"
+
+        TokenDetails.from_h(@rest.request("requestToken", "POST", path, body: wire, authorize: false))
+      end
+
+      private
+
+      def serialise(capability)
+        case capability
+        in String => signed_as_is then signed_as_is
+        in Hash => map then JSON.generate(map)
+        in nil then JSON.generate(DEFAULT_CAPABILITY)
+        else raise ConfigurationError, "capability must be a Hash or a JSON String, got #{capability.class}"
+        end
+      end
+    end
+  end
+end