Channels

Publish from a job or a webhook, read history and presence, and sign a user out everywhere.

Publish

channel = Blackevin::Rest::Channel.new("orders:#{order.id}")

channel.publish('status', {state: 'shipped'})

It goes through the same fanout a socket publish does: subscribers receive it, it is written to history, and it reaches the account's queues and integrations. Nothing about the message says it arrived over HTTP.

The channel name is encoded into the path for you — a colon, a slash, a space and non-ASCII all survive.

One HTTP request per publish. From a Rails request, prefer a job:

app/jobs/blackevin_publish_job.rb

class BlackevinPublishJob < ApplicationJob
  retry_on Blackevin::ConnectionError, wait: :polynomially_longer

  def perform(channel, event, data)
    Blackevin::Rest::Channel.new(channel).publish(event, data)
  end
end

History

messages = channel.history(limit: 50)   # newest first; the node clamps to 1..1000

message = messages.first

message.name        # 'status'
message.data        # {'state' => 'shipped'}
message.time        # a Time
message.timestamp   # the wire value, in milliseconds

Presence

channel.presence.get       # => [Blackevin::PresenceMember], who is there now
channel.presence.history   # => [Blackevin::PresenceEvent], past enter / leave / update

member = channel.presence.get.first

member.client_id
member.data

A server reads presence; it does not enter it. Entering is a socket's job.

Sign a user out everywhere

Blackevin::Rest::Clients.new.disconnect(user.id)   # => how many connections were closed

Closes every connection that client_id holds — for a sign-out that has to reach every open tab, or for a user you have just banned.

What the key needs

call	capability on the channel
`publish`	`publish`
`history`, `presence.history`	`history`
`presence.get`	`presence`

Without it the call raises a Blackevin::Error with status 403.