blackevin 0.1.1

data/lib/blackevin/rest/channels.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Blackevin
+  class Rest
+    # The channels of one client. +get+ returns the same object for the same name.
+    class Channels
+      def initialize(rest)
+        @rest = rest
+        @channels = {}
+        @mutex = Mutex.new
+      end
+
+      # @param name [String]
+      # @return [Blackevin::Rest::Channel]
+      def get(name)
+        name = name.to_s
+
+        raise ConfigurationError, "a channel needs a name" if name.empty?
+
+        @mutex.synchronize { @channels[name] ||= Channel.new(@rest, name) }
+      end
+
+      alias_method :[], :get
+    end
+
+    # One channel: publish, history, presence.
+    class Channel
+      DEFAULT_HISTORY_LIMIT = 100
+
+      # @return [String]
+      attr_reader :name
+
+      # @return [Blackevin::Rest::Presence]
+      attr_reader :presence
+
+      def initialize(rest, name)
+        @rest = rest
+        @name = name
+        @path = "/api/channels/#{Rest.escape(name)}"
+        @presence = Presence.new(rest, @path)
+      end
+
+      # Publishes without a socket — from a job, a cron, or a webhook arriving
+      # at your backend. Subscribers, account queues and integrations see it
+      # exactly as they see a socket publish.
+      #
+      # @param event [String, Symbol] the event name
+      # @param data [Object, nil] anything JSON can carry
+      # @return [true]
+      # @raise [Blackevin::Error]
+      def publish(event, data = nil)
+        body = {"name" => event.to_s}
+        body["data"] = data unless data.nil?
+
+        @rest.request("publish", "POST", "#{@path}/publish", body: body)
+
+        true
+      end
+
+      # Stored messages, newest first.
+      #
+      # @param limit [Integer] clamped by the node to 1..1000
+      # @return [Array<Blackevin::Message>]
+      # @raise [Blackevin::Error]
+      def history(limit: DEFAULT_HISTORY_LIMIT)
+        body = @rest.request("history", "GET", "#{@path}/history", query: {"limit" => limit})
+
+        Array(body["messages"]).map { Message.from_h(_1) }
+      end
+
+      def inspect = "#<Blackevin::Rest::Channel name=#{name.inspect}>"
+    end
+
+    # Presence on one channel.
+    class Presence
+      def initialize(rest, channel_path)
+        @rest = rest
+        @path = "#{channel_path}/presence"
+      end
+
+      # Who is present now.
+      #
+      # @return [Array<Blackevin::PresenceMember>]
+      # @raise [Blackevin::Error]
+      def get
+        body = @rest.request("presence get", "GET", @path)
+
+        Array(body["members"]).map { PresenceMember.from_h(_1) }
+      end
+
+      # Past enter, leave and update events, newest first.
+      #
+      # @param limit [Integer] clamped by the node to 1..1000
+      # @return [Array<Blackevin::PresenceEvent>]
+      # @raise [Blackevin::Error]
+      def history(limit: Channel::DEFAULT_HISTORY_LIMIT)
+        body = @rest.request("presence history", "GET", "#{@path}/history", query: {"limit" => limit})
+
+        Array(body["events"]).map { PresenceEvent.from_h(_1) }
+      end
+    end
+  end
+end

data/lib/blackevin/rest/clients.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Blackevin
+  class Rest
+    # Acting on connected clients.
+    class Clients
+      def initialize(rest)
+        @rest = rest
+      end
+
+      # Closes every connection a client holds — for signing a user out
+      # everywhere, or cutting off one you have just banned.
+      #
+      # @param client_id [String, Integer]
+      # @return [Integer] how many connections were closed
+      # @raise [Blackevin::Error]
+      def disconnect(client_id)
+        client_id = client_id.to_s
+
+        raise ConfigurationError, "disconnect needs a client_id" if client_id.empty?
+
+        path = "/api/clients/#{Rest.escape(client_id)}/connections/close"
+
+        @rest.request("disconnect", "POST", path)["closed"].to_i
+      end
+    end
+  end
+end

data/lib/blackevin/rest/queues.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Blackevin
+  class Rest
+    # Account queues and the rules that feed them. The key needs +amqp-subscribe+.
+    #
+    # A queue is addressed by its id, never its name: the name is the physical
+    # queue on the broker, so a 404 must mean "no such queue".
+    class Queues
+      def initialize(rest)
+        @rest = rest
+      end
+
+      # @param all [Boolean] include paused queues
+      # @return [Array<Blackevin::Queue>]
+      # @raise [Blackevin::Error]
+      def list(all: false)
+        body = @rest.request("list queues", "GET", "/api/queues", query: all ? {"all" => "1"} : nil)
+
+        Array(body["queues"]).map { Queue.from_h(_1) }
+      end
+
+      # Creates a queue, or edits the one already holding this name. Only a new
+      # queue counts against the plan's ceiling.
+      #
+      # @param name [String]
+      # @param max_length [Integer, nil]
+      # @param enabled [Boolean]
+      # @return [Blackevin::Queue]
+      # @raise [Blackevin::Error] with reason "queue_limit" at the plan's ceiling
+      def upsert(name:, max_length: nil, enabled: true)
+        body = {"name" => name.to_s, "enabled" => enabled}
+        body["maxLength"] = max_length unless max_length.nil?
+
+        Queue.from_h(@rest.request("upsert queue", "POST", "/api/queues", body: body).fetch("queue"))
+      end
+
+      alias_method :create, :upsert
+
+      # Pauses, resumes or resizes. Omitted arguments are left as they are;
+      # +max_length: nil+ passed explicitly removes the bound.
+      #
+      # @param id [String]
+      # @param enabled [Boolean]
+      # @param max_length [Integer, nil]
+      # @return [Blackevin::Queue]
+      # @raise [Blackevin::Error]
+      def update(id, **changes)
+        unknown = changes.except(:enabled, :max_length).keys
+
+        raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" unless unknown.empty?
+
+        body = {}
+        body["enabled"] = changes[:enabled] if changes.key?(:enabled)
+        body["maxLength"] = changes[:max_length] if changes.key?(:max_length)
+
+        Queue.from_h(@rest.request("update queue", "PATCH", queue_path(id), body: body).fetch("queue"))
+      end
+
+      # Deletes the queue and whatever is waiting in it.
+      #
+      # @param id [String]
+      # @return [String] the name of the deleted queue
+      # @raise [Blackevin::Error]
+      def delete(id)
+        @rest.request("delete queue", "DELETE", queue_path(id))["deleted"]
+      end
+
+      # @param id [String] the queue's id
+      # @return [Array<Blackevin::QueueRule>]
+      # @raise [Blackevin::Error]
+      def rules(id)
+        body = @rest.request("list queue rules", "GET", "#{queue_path(id)}/rules")
+
+        Array(body["rules"]).map { QueueRule.from_h(_1) }
+      end
+
+      # Copies messages from channels matching the pattern into the queue.
+      #
+      # @param id [String] the queue's id
+      # @param source_pattern [String] a channel name or wildcard pattern
+      # @param filter [String, nil]
+      # @return [Blackevin::QueueRule]
+      # @raise [Blackevin::Error]
+      def add_rule(id, source_pattern:, filter: nil)
+        body = {"sourcePattern" => source_pattern.to_s}
+        body["filter"] = filter unless filter.nil?
+
+        QueueRule.from_h(@rest.request("add queue rule", "POST", "#{queue_path(id)}/rules", body: body).fetch("rule"))
+      end
+
+      # Stops the copies at the source. Messages already enqueued stay.
+      #
+      # @param id [String] the queue's id
+      # @param rule_id [String]
+      # @return [true]
+      # @raise [Blackevin::Error]
+      def delete_rule(id, rule_id)
+        @rest.request("delete queue rule", "DELETE", "#{queue_path(id)}/rules/#{Rest.escape(rule_id)}")
+
+        true
+      end
+
+      private
+
+      def queue_path(id)
+        raise ConfigurationError, "a queue is addressed by its id" if id.to_s.empty?
+
+        "/api/queues/#{Rest.escape(id)}"
+      end
+    end
+  end
+end

data/lib/blackevin/rest.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Blackevin
+  # The REST client: no socket, no reconnection, no state beyond its options.
+  #
+  #   rest = Blackevin::Rest.new(key: ENV.fetch("BLACKEVIN_KEY"))
+  #
+  #   rest.auth.create_token_request(client_id: "bob")
+  #   rest.channels.get("room:42").publish("greeting", {text: "hi"})
+  #
+  # Safe to share across threads: every call opens its own connection and the
+  # instance holds nothing mutable but a channel cache behind a mutex.
+  class Rest
+    USER_AGENT = "blackevin-ruby/#{VERSION} ruby/#{RUBY_VERSION}"
+
+    # @return [Blackevin::Rest::Auth]
+    attr_reader :auth
+
+    # @return [Blackevin::Rest::Channels]
+    attr_reader :channels
+
+    # @return [Blackevin::Rest::Clients]
+    attr_reader :clients
+
+    # @return [Blackevin::Rest::Queues]
+    attr_reader :queues
+
+    # @return [String] the resolved REST base URL
+    attr_reader :rest_endpoint
+
+    # @param key [String, nil] full API key +secret.keyId+; required to sign token requests
+    # @param token [String, nil] a token, when acting as one client rather than as the account
+    # @param rest_endpoint [String, nil] overrides the resolved REST host
+    # @param endpoint [String, nil] socket endpoint; read only to derive the REST base
+    # @param open_timeout [Numeric] seconds
+    # @param read_timeout [Numeric] seconds
+    # @param transport [#call, nil] replaces Net::HTTP; receives a {Request}, returns a {Response}
+    # @param clock [#call] returns milliseconds since the epoch; injected for tests
+    # @param nonce [#call] returns a fresh nonce; injected for tests
+    # @param env [#[]] where the endpoint variables are read from
+    def initialize(key: nil, token: nil, rest_endpoint: nil, endpoint: nil, open_timeout: 5, read_timeout: 10,
+                   transport: nil, clock: nil, nonce: nil, env: ENV)
+      @key = key
+      @token = token
+      @rest_endpoint = Endpoints.resolve(endpoint: endpoint, rest_endpoint: rest_endpoint, env: env).rest_endpoint
+      @transport = transport || Transport.new(open_timeout: open_timeout, read_timeout: read_timeout)
+
+      @auth = Auth.new(self, clock: clock, nonce: nonce)
+      @channels = Channels.new(self)
+      @clients = Clients.new(self)
+      @queues = Queues.new(self)
+    end
+
+    # @return [Blackevin::ApiKey]
+    # @raise [Blackevin::ConfigurationError] when no key was given, or it is malformed
+    def api_key
+      raise ConfigurationError, 'this call needs the API key: pass key: or set BLACKEVIN_KEY' if @key.to_s.strip.empty?
+
+      ApiKey.parse(@key)
+    end
+
+    # A token wins over a key: a client acting as one user must not silently
+    # act as the whole account.
+    #
+    # @return [String, nil]
+    def authorization_header
+      return "Bearer #{@token}" if @token
+      return nil if @key.nil?
+
+      "Basic #{[@key].pack('m0')}"
+    end
+
+    # @api private
+    def request(what, method, path, query: nil, body: nil, authorize: true)
+      headers = { 'accept' => 'application/json', 'user-agent' => USER_AGENT }
+      authorization = authorize ? authorization_header : nil
+
+      headers['authorization'] = authorization if authorization
+      headers['content-type'] = 'application/json' if body
+
+      response = @transport.call(
+        Request.new(method: method, url: url_for(path, query), headers: headers, body: body && JSON.generate(body))
+      )
+
+      raise Error.from_response(what, response.status, response.body) unless (200..299).cover?(response.status)
+
+      parse(what, response)
+    end
+
+    # Percent-encodes one path segment so it decodes back to the exact string.
+    #
+    # Not form encoding: +URI.encode_www_form_component+ turns a space into "+",
+    # which the node reads as a literal plus sign.
+    #
+    # @api private
+    def self.escape(segment) = segment.to_s.b.gsub(/[^A-Za-z0-9\-._~]/) { format('%%%02X', _1.ord) }
+
+    def inspect = "#<Blackevin::Rest rest_endpoint=#{rest_endpoint.inspect}>"
+
+    private
+
+    def url_for(path, query)
+      return "#{rest_endpoint}#{path}" if query.nil? || query.empty?
+
+      "#{rest_endpoint}#{path}?#{URI.encode_www_form(query)}"
+    end
+
+    def parse(what, response)
+      case JSON.parse(response.body.to_s)
+      in Hash => parsed then parsed
+      else {}
+      end
+    rescue JSON::ParserError
+      raise Error.new("#{what} failed: the response was not JSON", response.status)
+    end
+  end
+end

data/lib/blackevin/token_details.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Blackevin
+  # The token a TokenRequest was exchanged for, and what it is good for.
+  class TokenDetails
+    attr_reader :token, :key_name, :issued, :expires, :capability, :client_id
+
+    # @param hash [Hash] the wire body of +requestToken+
+    # @return [Blackevin::TokenDetails]
+    def self.from_h(hash)
+      new(
+        token: hash['token'],
+        key_name: hash['keyName'],
+        issued: hash['issued'],
+        expires: hash['expires'],
+        capability: hash['capability'],
+        client_id: hash['clientId']
+      )
+    end
+
+    def initialize(token:, key_name: nil, issued: nil, expires: nil, capability: nil, client_id: nil)
+      @token = token
+      @key_name = key_name
+      @issued = issued
+      @expires = expires
+      @capability = capability
+      @client_id = client_id
+    end
+
+    # @return [Time, nil]
+    def expires_at = expires&.then { Time.at(_1 / 1000.0) }
+
+    # @return [Time, nil]
+    def issued_at = issued&.then { Time.at(_1 / 1000.0) }
+
+    def expired?(now = Time.now) = !expires.nil? && expires_at <= now
+
+    # The wire shape, as the node sent it.
+    def to_h
+      {
+        'token' => token,
+        'keyName' => key_name,
+        'issued' => issued,
+        'expires' => expires,
+        'capability' => capability,
+        'clientId' => client_id
+      }.compact
+    end
+
+    def as_json(*) = to_h
+
+    def to_json(...) = to_h.to_json(...)
+
+    # Pattern matching, with the Ruby names. The token itself is left out on
+    # purpose: a pattern's bindings end up in logs more easily than a reader.
+    def deconstruct_keys(_keys)
+      { key_name: key_name, issued: issued, expires: expires, capability: capability, client_id: client_id }
+    end
+
+    # The token is a credential; keep it out of logs.
+    def inspect
+      "#<Blackevin::TokenDetails key_name=#{key_name.inspect} client_id=#{client_id.inspect} expires=#{expires.inspect} token=[FILTERED]>"
+    end
+  end
+end

data/lib/blackevin/token_endpoint.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Blackevin
+  # The token endpoint a browser's +authUrl+ points at, as a Rack application —
+  # so the same object mounts in Rails, Sinatra, Hanami or a bare +config.ru+.
+  #
+  # The block receives the Rack env and answers who is asking. Return the
+  # arguments for {Rest::Auth#create_token_request}, or nil to refuse:
+  #
+  #   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
+  #
+  #   # Rails:   mount TOKENS, at: "/blackevin/token"
+  #   # Sinatra: map("/blackevin/token") { run TOKENS }
+  #
+  # This gem does not depend on Rack; a Rack app is only an object with +call+.
+  class TokenEndpoint
+    ALLOWED_METHODS = %w[GET POST].freeze
+
+    HEADERS = {
+      'content-type' => 'application/json',
+      'cache-control' => 'no-store'
+    }.freeze
+
+    # @param rest [Blackevin::Rest, nil] defaults to {Blackevin.rest}, resolved per request
+    # @yieldparam env [Hash] the Rack env
+    # @yieldreturn [Hash, nil] keyword arguments for +create_token_request+, or nil to answer 401
+    def initialize(rest: nil, &identify)
+      raise ArgumentError, 'TokenEndpoint needs a block that identifies the caller' unless identify
+
+      @rest = rest
+      @identify = identify
+    end
+
+    # @param env [Hash] the Rack env
+    # @return [Array(Integer, Hash, Array<String>)]
+    def call(env)
+      unless ALLOWED_METHODS.include?(env['REQUEST_METHOD'])
+        return respond(405, { 'error' => 'method not allowed' }, 'allow' => ALLOWED_METHODS.join(', '))
+      end
+
+      case @identify.call(env)
+      in nil | false
+        respond(401, { 'error' => 'unauthorized' })
+      in Hash => params
+        respond(200, (@rest || Blackevin.rest).auth.create_token_request(**params.transform_keys(&:to_sym)).to_h)
+      in other
+        raise ConfigurationError, "the TokenEndpoint block must return a Hash or nil, got #{other.class}"
+      end
+    end
+
+    private
+
+    def respond(status, body, extra = {})
+      [status, HEADERS.merge(extra), [JSON.generate(body)]]
+    end
+  end
+end

data/lib/blackevin/token_request.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+
+module Blackevin
+  # What your server hands a browser instead of the API key: signed, scoped to a
+  # capability, and dead after its ttl. The browser exchanges it for a token.
+  #
+  # Serialises to the wire shape, so a controller can render it as is:
+  #
+  #   render json: Blackevin.rest.auth.create_token_request(client_id: current_user.id)
+  class TokenRequest
+    # The field ORDER and the newline after each are the wire contract. The node
+    # recomputes exactly this text to verify, and a reordering breaks every
+    # token with an error ("invalid token request mac") that names nothing.
+    SIGNED_FIELDS = %i[key_name ttl capability client_id timestamp nonce].freeze
+
+    WIRE_NAMES = {
+      key_name: 'keyName',
+      ttl: 'ttl',
+      capability: 'capability',
+      client_id: 'clientId',
+      timestamp: 'timestamp',
+      nonce: 'nonce',
+      mac: 'mac'
+    }.freeze
+
+    attr_reader :key_name, :ttl, :capability, :client_id, :timestamp, :nonce, :mac
+
+    # @param key_name [String]
+    # @param timestamp [Integer] milliseconds since the epoch
+    # @param nonce [String] single use, at least 16 characters
+    # @param ttl [Integer, nil] milliseconds
+    # @param capability [String, nil] a capability map serialised as JSON
+    # @param client_id [String, nil]
+    # @param mac [String, nil]
+    def initialize(key_name:, timestamp:, nonce:, ttl: nil, capability: nil, client_id: nil, mac: nil)
+      @key_name = key_name
+      @ttl = ttl
+      @capability = capability
+      @client_id = client_id
+      @timestamp = timestamp
+      @nonce = nonce
+      @mac = mac
+    end
+
+    # Builds one from a wire hash (camelCase keys) or a Ruby hash (snake_case).
+    #
+    # @param hash [Hash]
+    # @return [Blackevin::TokenRequest]
+    def self.from_h(hash)
+      values = WIRE_NAMES.to_h do |attribute, wire|
+        [attribute, hash[wire] || hash[wire.to_sym] || hash[attribute] || hash[attribute.to_s]]
+      end
+
+      new(**values)
+    end
+
+    # The exact text the MAC is computed over.
+    def signing_text = SIGNED_FIELDS.map { "#{public_send(_1)}\n" }.join
+
+    # @param secret [String] the secret half of the API key
+    # @return [Blackevin::TokenRequest] a copy carrying the MAC
+    def sign(secret)
+      digest = OpenSSL::HMAC.digest('SHA256', secret, signing_text)
+
+      self.class.new(**attributes, mac: [digest].pack('m0'))
+    end
+
+    # The wire shape: camelCase keys, absent fields omitted.
+    #
+    # @return [Hash{String => Object}]
+    def to_h
+      WIRE_NAMES.each_with_object({}) do |(attribute, wire), hash|
+        value = public_send(attribute)
+
+        hash[wire] = value unless value.nil?
+      end
+    end
+
+    # Rails' +render json:+ calls this, so the wire shape survives it too.
+    def as_json(*) = to_h
+
+    def to_json(...) = to_h.to_json(...)
+
+    def ==(other) = other.is_a?(self.class) && other.to_h == to_h
+
+    # Pattern matching, with the Ruby names: +in {client_id:, ttl:}+.
+    def deconstruct_keys(_keys) = attributes.merge(mac: mac)
+
+    private
+
+    def attributes = SIGNED_FIELDS.to_h { [_1, public_send(_1)] }
+  end
+end

data/lib/blackevin/transport.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+module Blackevin
+  # One HTTP exchange, as the transport sees it.
+  Request = Struct.new(:method, :url, :headers, :body, keyword_init: true)
+  Response = Struct.new(:status, :body, keyword_init: true)
+
+  # The default transport: Net::HTTP from the standard library, and nothing else.
+  #
+  # Anything responding to +call(request)+ and returning a {Response} can stand
+  # in for it, which is how the specs observe a request without sending one and
+  # how an application can route through its own HTTP stack.
+  class Transport
+    NETWORK_ERRORS = [
+      SocketError,
+      SystemCallError,
+      IOError,
+      Timeout::Error,
+      OpenSSL::SSL::SSLError,
+      Net::HTTPBadResponse,
+      Net::ProtocolError
+    ].freeze
+
+    VERBS = {
+      'GET' => Net::HTTP::Get,
+      'POST' => Net::HTTP::Post,
+      'PUT' => Net::HTTP::Put,
+      'PATCH' => Net::HTTP::Patch,
+      'DELETE' => Net::HTTP::Delete
+    }.freeze
+
+    # @param open_timeout [Numeric] seconds to wait for the connection
+    # @param read_timeout [Numeric] seconds to wait for each read
+    def initialize(open_timeout: 5, read_timeout: 10)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # @param request [Blackevin::Request]
+    # @return [Blackevin::Response]
+    # @raise [Blackevin::ConnectionError] when no response arrived
+    def call(request)
+      uri = URI.parse(request.url)
+      http_request = build(request, uri)
+
+      response = connection(uri).start { |http| http.request(http_request) }
+
+      Response.new(status: response.code.to_i, body: response.body)
+    rescue *NETWORK_ERRORS => e
+      raise ConnectionError, "could not reach #{uri&.host || request.url}: #{e.class}: #{e.message}"
+    end
+
+    private
+
+    def build(request, uri)
+      http_request = VERBS.fetch(request.method).new(uri.request_uri)
+
+      request.headers.each { |name, value| http_request[name] = value }
+      http_request.body = request.body if request.body
+
+      http_request
+    end
+
+    def connection(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+      http.write_timeout = @read_timeout
+
+      http
+    end
+  end
+end