cent 3.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fadf11a9b2cdfa2b9c490e59adbf052515c9a0c4f5091405ffd3bca4f345bfb
-  data.tar.gz: 07e0c29ede9d249c0d8b36d3d432a37fa8048c82e54c7540b8ef67131b103d76
+  metadata.gz: ad578d47b0681afc90300faa480857bdb5dd94bb7e7e3462aec750da5ea1a8b6
+  data.tar.gz: 158a26a1c14e98e31e43c288969dc1686dd461bdbaccdcf7df6855b73093760b
 SHA512:
-  metadata.gz: f99f6ab6178fda5cce7adcac441e35313c2c2990fcfedbf685ddbfd4fc2c70bcd1098231c3ee1580b39154cca836ef590d05a8ac5032e8ca8946e16666ab6716
-  data.tar.gz: 6158ba6dc6ccd667b206f2d50ce7c7a832412bf5360686de0f0c8948df219c8a84d5d273a31fcaeb819e4474580a554eb40545e5512628a2eee445c7e5cba9b9
+  metadata.gz: 46b906c03002c52bda6bd4f5d6ccb082d05b23927b108030a175f6cd0782fc7e82bd2d93cb6494c457966a45736f245ca32136ffd413e073d773e4baf292d7cc
+  data.tar.gz: 6bbcee3e1b4407d69f15ebfa660e41dcc980c2ed3b02895d628cb743159e568638d856915004d046074b6ba9612ae517de8f9fdb8e1676e0ea4055115567f445

data/CHANGELOG.md

@@ -1,3 +1,96 @@
+v5.0.0
+======
+
+cent 5 is a rewrite, to the [Centrifugo server SDK specification](https://github.com/centrifugal/gocent/blob/master/spec.md), version 0.4, which gocent and the other Centrifugo server SDKs follow too. It needs Ruby 3.4 or newer and supports Centrifugo v6 - OSS and PRO; the map and shared poll methods need v6.8.0 or newer, `ApiError#temporary?` v6.10.0 or newer. The json gem is its only dependency: Faraday and jwt are gone. Migrating from cent 4: see [MIGRATING.md](https://github.com/centrifugal/rubycent/blob/master/MIGRATING.md); an application which needs time to move can stay on `gem "cent", "~> 4.0"`.
+
+Generated from Centrifugo's protos at [e21aeb50](https://github.com/centrifugal/centrifugo/commit/e21aeb50ab6fc4d525fc817473574f728da6c3ad) on its master, after v6.10.2: the same messages as v6.10.2, with the comments the constants are generated from, and `ConnectResult.profile` for the connect proxy, which Centrifugo PRO newer than v6.10.2 reads.
+
+**Client and calls**
+
+* A method for every API method, generated from Centrifugo's `api.proto` with its documentation - the map, shared poll and Centrifugo PRO methods included - taking its request's fields as keyword arguments: `client.publish(channel: "news", data: ...)`. A nested message is its class or a Hash of its fields; an unknown keyword or field is refused, with a suggestion.
+* Results are `Data` objects - `res.offset`, not `res["result"]["offset"]` - with `to_h`, `as_json` and `to_json` giving wire names, nested results too: `render json: result` in Rails.
+* Fields the protos mark required are required keywords, of the methods and of the nested messages' classes - `Cent::RateLimitPolicy.new(rate:, interval_ms:)` - and are checked for a value before sending: given `nil`, `""`, `0`, `[]` or a message with nothing set, a call raises `InvalidRequestError` naming the field's path, `limit_strategy.rate_limit.policies[0].rate is required`.
+* A field at its zero value is not sent, nor a nested message with nothing set - but for `device_update`'s `user_update`, `timezone_update`, `locale_update` and `meta_update`, sent whenever given, even empty: `timezone_update: { timezone: "" }` clears the timezone, `user_update: { user: "" }` detaches the devices from their user. `BoolValue` fields are `true`, `false` or nil, which leaves the server's setting alone.
+* The client is created once and shared: safe for concurrent use from threads, and under a fiber scheduler (Async, Falcon) calls wait without blocking other fibers. A client used in a forked process - Puma's `preload_app!`, a Sidekiq swarm - starts its own connections and batch threads there.
+* Its configuration is checked when it is created, `InvalidConfigError` naming the option and the fix: `api_endpoint:` (required, no default) or `api_endpoint_func:`, `api_key:` (nil for none) or `bearer_token_func:`, `headers:`, `request_timeout:`, `http_options:`, `http_client:`, `auto_batch:`, `on_request:`, `batch_context:`. `inspect` hides credentials.
+* An endpoint from `api_endpoint_func`, or a token from `bearer_token_func`, which cannot be sent fails the call with `InvalidConfigError` before sending. An exception of either function's own fails the call with `Cent::FunctionError`: its `function` is the option's name, its `cause` the exception, and `Cent.retryable?` judges it by that cause.
+* Net::HTTP connections kept alive in a pool, up to 256 to a host, idle ones closed after 50 seconds. Redirects are not followed: a redirect is an `HTTPError` hinting to check `api_endpoint`'s scheme and path. `http_options:` for TLS settings, `http_client:` for another HTTP library or a fake in tests.
+* `close` refuses new calls with `ClosedError` and waits for those in progress, automatic batches included; with `timeout:` it raises `TimeoutError` when they have not finished, leaving them to go on. It may be called again, concurrently too, each call waiting alike; `broadcast_with_retry` stops at its next attempt with `ClosedError`.
+
+**Timeouts**
+
+* `request_timeout` - 10 seconds, also when nil - bounds every call: connecting and TLS, sending, and the reply, however slowly it comes. A watchdog thread finishes a connection at its call's deadline through Net::HTTP's public `finish`, so a reply's headers trickling in no longer outlast it; it starts afresh in a forked process. However a call times out, it raises `Cent::TimeoutError`.
+* A call's `timeout:` replaces `request_timeout` for that call, longer or shorter. Ruby has no deadline a call runs under for cent to read: a `Timeout.timeout` around a call only cuts it short.
+* A timeout cannot be turned off: `request_timeout: 0` is refused with `InvalidConfigError`, and a call's `timeout: 0` with `InvalidRequestError`, as negative values are.
+
+**Errors**
+
+* `Cent::ApiError` with a subclass per known code - `UnknownChannelError`, `NotFoundError`, `BadRequestError`, `NotAvailableError`, `TooManyRequestsError`, `UnrecoverablePositionError`, `ConflictError`, `InternalError` - and `code`, `server_message`, `temporary?`; an unknown code is an `ApiError` itself.
+* `HTTPError` (`status_code`, `body`, `headers`) and its `UnauthorizedError` for rejected credentials, `DecodeError`, `InvalidRequestError`, `InvalidConfigError`, `FunctionError`, `NetworkError`, `TimeoutError`, `ClosedError`, `BatchSentError`, `BatchNotSentError`: all `Cent::Error`. Messages carry hints: a 404 says whether the endpoint lacks the API prefix or the server is Centrifugo OSS answering a PRO method.
+* Centrifugo's transport error mode gives the same errors as a 200 reply.
+
+**Retries and idempotency**
+
+* `Cent.retryable?(err)` says whether a new attempt may succeed; `Cent.exponential_backoff(base, limit)` for waits.
+* `broadcast_with_retry` retries only the channels which failed for a temporary reason, with one `idempotency_key` on every attempt - made for the call when none is given - up to `max_attempts:`. `timeout:` bounds the whole call, waits included; `attempt_timeout:` is each attempt's own timeout, replacing `request_timeout`, the call's `timeout:` still ending an attempt sooner. Its block sees each failed attempt, returns the wait, and raises to stop.
+* The docs say how to choose keys: one per publication, reused only to retry it, naming the event; the memory, Redis and PostgreSQL brokers keep keys, the NATS broker ignores them.
+
+**Broadcast and batch**
+
+* **Breaking:** a broadcast or batch in which some parts failed raises `BroadcastFailedChannelsError` or `BatchFailedCommandsError`, whose `result` holds every part's outcome and whose `failed` lists the failed parts, also when every part failed - cent 4 returned the response with the errors inside. Rescue them for best-effort sends: see [MIGRATING.md](https://github.com/centrifugal/rubycent/blob/master/MIGRATING.md#broadcasts-and-batches-now-raise). A broadcast or batch failing as a whole raises its own error instead, and every pending command of a batch returns that error.
+* `client.new_batch` has the client's methods, each adding a command and returning a `Cent::Pending` whose `value` is its result; `batch.send`, once; `client.new_batch(parallel: true)` for Centrifugo to run the commands concurrently. A command the client can tell is invalid fails the batch before sending, naming its index.
+
+**Automatic batching**
+
+* `auto_batch: Cent::AutoBatch.new(max_in_flight:, max_batch_size:)`: below `max_in_flight` concurrent requests every call goes alone, at once; at the cap, calls queue and go out together in one batch request as one returns. Every call keeps its own result, error and timeout; a batch lasts until the latest of its calls' deadlines, at least `request_timeout`. `batch_context:` carries values such as a tracing span into the batch's thread.
+
+**Pages and positions**
+
+* `history_all`, `device_list_all`, `device_topic_list_all`, `user_topic_list_all` and `map_read_state_all` read page after page, with a block or as an `Enumerator` reading a page when the iteration reaches it. `page_timeout:` bounds each page's request, replacing `request_timeout` for it; an iteration lasts as long as the caller's loop.
+* `history_all` yields each publication as a `Cent::HistoryItem`, with its `position`; it needs a `limit` of 1 or more and reads forward only. `map_read_state_all` yields each entry as a `Cent::MapStateItem`, with the state's `position`, and reads every page after the first at the first one's revision, so that a map reset between pages raises `UnrecoverablePositionError` instead of mixing two states.
+* `position`, a `Cent::StreamPosition`, on the results of `publish`, `history`, `map_publish`, `map_remove`, `map_read_state` and `map_read_stream`: what a publish returned is the `since:` of the history call reading what came after it.
+
+**Constants**
+
+* A constant per value of the fields with a fixed set of values, named as the specification pins them for every SDK: `Cent::PROVIDER_FCM`, `Cent::PLATFORM_IOS`, `Cent::OP_ADD`, `Cent::STATUS_DELIVERED`, `Cent::KEY_MODE_IF_NEW`, `Cent::FILTER_NODE_OP_AND`, `Cent::CMP_EQ`, and in `Cent::Proxy` `PROTOCOL_JSON`, `ENCODING_BINARY`, `ALLOW_SUB`, `CAPABILITY_MATCH_WILDCARD`, `CHANNEL_EVENT_TYPE_OCCUPIED` and the rest. The fields stay strings: a value Centrifugo adds can be sent before cent names it.
+
+**Payloads**
+
+* `data`, `info`, `meta` and the other payloads are Ruby values `JSON.generate` writes, or a `JSON::Fragment` sent as its text; a payload from a reply sent back unchanged is the same JSON value. NaN, infinities, binary strings, invalid UTF-8 and values JSON cannot hold are refused before sending, naming where they are. nil is no payload: JSON null is `JSON::Fragment.new("null")`.
+
+**Tokens and JWKS**
+
+* `Cent::Token.connection` and `Cent::Token.subscription` with every claim Centrifugo reads - `profile:` included, the compression profile of Centrifugo PRO - signed with `Cent::Token::Key.hmac`, `.rsa`, `.ecdsa`, `.ed25519` or `.from_pem` (HS256, RS256, ES256/384/512, EdDSA) from Ruby's OpenSSL. RSA keys are of 2048 bits or more, ECDSA keys on P-256, P-384 or P-521: others are refused with `Cent::Token::Error` when the key is made. An expiry is required: a `Time`, or `:never` chosen explicitly.
+* `Cent::Token.jwks(*keys)` and the `Cent::Endpoints::JWKS` Rack app serve the public keys for Centrifugo's [`client.token.jwks_public_endpoint`](https://centrifugal.dev/docs/server/authentication), for key rotation without a restart.
+
+**API tokens (Centrifugo PRO)**
+
+* `Cent::Token.api` signs server API tokens; `Cent::Token::ApiTokenSource` issues them for `bearer_token_func:`, reusing each for half its lifetime, its key fixed or from `current_key:` as keys rotate.
+
+**Endpoints for client SDKs**
+
+* `Cent::Endpoints::ConnectionToken`, `SubscriptionToken` and `SharedPollSignature`: the endpoints the `getToken` and `getSignature` callbacks of client SDKs call, as Rack apps with a framework-free core. Raising `Cent::Endpoints::ForbiddenError` answers 403, on which client SDKs stop asking - they report it as their `UnauthorizedError`; it is not `Cent::UnauthorizedError`, the API refusing your credentials.
+
+**Shared poll**
+
+* `Cent::SharedPoll.sign` for shared poll signatures, its expiry required: a `Time`, or `:never`.
+
+**Proxy handlers**
+
+* `Cent::Proxy`: a handler for every proxy type - `ConnectHandler`, `RefreshHandler`, `SubscribeHandler`, `PublishHandler`, `RPCHandler`, `SubRefreshHandler`, `MapPublishHandler`, `MapRemoveHandler`, `SharedPollRefreshHandler`, and Centrifugo PRO's `NotifyCacheEmptyHandler` and `NotifyChannelStateHandler` - with the request and result types generated from `proxy.proto`, `ConnectResult#profile` included. A block returns a result, or raises `Cent::Proxy::ProxyError` or `Cent::Proxy::Disconnect`; anything else, or a block returning nil, is a 500 reported to `on_error:`. Each is a Rack app.
+
+**Commands for async consumers**
+
+* `Cent::Command.publish(...)` and a method like it for every API method, checked as a call is: `method` and `payload` for an outbox table, `to_json` for a Kafka message, `as_json` with the payload as a Hash.
+
+**Observability**
+
+* `on_request:` is called after every HTTP request with a `Cent::RequestInfo`: method, commands, failed, automatic batch or not, duration, status, error.
+
+**Testing**
+
+* A fake `http_client:` answers as Centrifugo does, without stubbing HTTP. `Cent::Pending.resolved` and the public constructors of `BroadcastFailedChannelsError`, `BatchFailedCommandsError`, `BroadcastResult` and `ChannelResult` make test doubles of your own.
+
 3.0.0
 =====
 

data/MIGRATING.md

@@ -0,0 +1,305 @@
+# Migrating from cent 4 to cent 5
+
+cent 5 is a rewrite, to the
+[Centrifugo server SDK specification](https://github.com/centrifugal/gocent/blob/master/spec.md),
+version 0.4.
+It needs Ruby 3.4 or newer and Centrifugo v6, and depends on nothing but the
+json gem: Faraday and the jwt gem are gone. An application which needs time to
+move can stay on `gem "cent", "~> 4.0"`, which keeps working.
+
+What changes:
+
+- **Every API method** still takes keyword arguments, now every field of its
+  request - generated from Centrifugo's `api.proto`, each documented - and
+  returns a typed result: `res.offset` instead of `res["result"]["offset"]`.
+  Every method of Centrifugo v6's API is there, the PRO ones included.
+- **Errors** are Centrifugo's codes as classes - `Cent::UnknownChannelError`,
+  `Cent::NotFoundError`, ... all `Cent::ApiError` - instead of
+  `Cent::ResponseError`. **Broadcasts and batches raise** when parts of them
+  failed: see [below](#broadcasts-and-batches-now-raise).
+- **The client** takes `api_endpoint:`, which is required, and
+  `request_timeout:`, which bounds every call whole; a call's `timeout:`
+  replaces it. The Faraday block is gone: TLS settings go in `http_options:`,
+  extra headers in `headers:`, another HTTP library in `http_client:`.
+- **Requests are checked before sending**: a missing or empty required field,
+  a publication without data, a payload which is not JSON raise
+  `Cent::InvalidRequestError` instead of reaching Centrifugo: see
+  [below](#other-changes-you-may-notice).
+- **Tokens** are made with `Cent::Token.connection` and
+  `Cent::Token.subscription`, with every claim Centrifugo reads, and HMAC, RSA,
+  ECDSA or Ed25519 keys. An expiry is required: `:never` for a token accepted
+  forever.
+- **New:** batches with a result per command, automatic batching, retries,
+  proxy handlers and the endpoints client SDKs call as Rack apps, JWKS,
+  Centrifugo PRO's API tokens, shared poll signatures, commands for async
+  consumers.
+
+## Broadcasts and batches now raise
+
+This is the change most likely to break code which moved over unchanged.
+
+cent 4 returned Centrifugo's response for a broadcast or a batch, and a
+channel or command which failed was only an `"error"` inside it. Code which
+didn't look - most code - went on as if everything had been published.
+
+cent 5 raises when any part failed, even when the others succeeded:
+`Cent::BroadcastFailedChannelsError` for a broadcast,
+`Cent::BatchFailedCommandsError` for a batch. Not rescuing it means an error
+where cent 4 was silent - in a web request, an error page, although most
+channels got the publication.
+
+Decide, for each broadcast and batch, which you want:
+
+- **A failure is an error** - an unknown channel is a bug, a broker failure
+  needs attention: let it raise, and your error reporting sees it.
+- **Best effort, as cent 4 behaved** - publish where it can, log the rest:
+  rescue the error. It holds every part's outcome, and the parts which
+  succeeded were published.
+
+```ruby
+begin
+  client.broadcast(channels:, data:)
+rescue Cent::BroadcastFailedChannelsError => e
+  e.failed.each { logger.warn("broadcast to #{it.channel} failed: #{it.error.message}") }
+end
+```
+
+## Other changes you may notice
+
+**Timeouts bound the whole call.** cent 4's `timeout:` set Faraday's open and
+read timeouts, each operation's own, so a reply arriving slowly could take
+longer. cent 5's `request_timeout:` - 10 seconds by default - bounds every
+call whole, a reply's headers trickling in included, and raises
+`Cent::TimeoutError` at it. A call's `timeout:` replaces it, longer or shorter;
+zero is refused, so a call cannot be left unbounded:
+
+```ruby
+# cent 4
+client = Cent::Client.new(api_key: "k", endpoint: "http://localhost:8000/api", timeout: 5)
+# cent 5
+client = Cent::Client.new(api_endpoint: "http://localhost:8000/api", api_key: "k", request_timeout: 5)
+client.history(channel: "news", limit: 1000, timeout: 30)   # this call may take longer
+```
+
+**Wrong requests fail before sending.** cent 4 sent what it was given, and
+Centrifugo answered with an error - `Cent::ResponseError`, code 107 or 102.
+cent 5 raises `Cent::InvalidRequestError` without sending: a field the protos
+mark required left out or empty (`channel: ""`), a publication without `data`
+or `b64data`, a payload which is not JSON (NaN, a `Time`, a binary string). It
+is not retryable: fix the call.
+
+```ruby
+# cent 4: sent; Centrifugo refused it with Cent::ResponseError
+client.publish(channel: "", data: { text: "hi" })
+# cent 5: not sent
+client.publish(channel: "", data: { text: "hi" })   # raises Cent::InvalidRequestError: channel is required
+```
+
+**nil is no value.** A keyword given nil is not sent, as in cent 4 - so
+`publish(data: nil)` now raises `InvalidRequestError`. To publish JSON null,
+pass `data: JSON::Fragment.new("null")`. A nested message with nothing set is
+left out too: `since: {}` is not sent.
+
+**Nested messages take Symbols.** `since: { "offset" => 5 }` is refused,
+naming the fix: write `since: { offset: 5, epoch: "x" }`, or
+`Cent::StreamPosition.new(offset: 5, epoch: "x")`. A position also comes from
+a result: `client.publish(...).position`.
+
+**The endpoint has no default.** cent 4 used `http://localhost:8000/api` when
+`endpoint:` was left out; cent 5 requires `api_endpoint:`, and refuses one
+with a query, credentials or a method name at the end (`/api/publish`), with
+`Cent::InvalidConfigError`. `api_key:` is optional: nil when requests are
+authenticated another way.
+
+**Headers go in `headers:`.** Without the Faraday block, extra headers - a
+`User-Agent` of your own, which replaces cent's, a header a proxy needs - go in
+`headers: { "User-Agent" => "my-app/1.0" }`. `X-API-Key`, `Authorization` and
+`Content-Type` are refused there: use `api_key:` or `bearer_token_func:`.
+
+**HMAC tokens are HS256.** `Cent::Notary.new(secret:, algorithm: "HS512")` has
+no counterpart: `Cent::Token::Key.hmac(secret)` signs HS256, which every
+Centrifugo verifies. RSA, ECDSA and Ed25519 keys are `Key.rsa`, `Key.ecdsa`,
+`Key.ed25519`, or `Key.from_pem`.
+
+## Side by side
+
+Each pair prints the same, run against Centrifugo.
+
+### Calls and errors
+
+cent 4:
+
+```ruby
+require "cent"
+
+client = Cent::Client.new(api_key: "api_key", endpoint: "http://localhost:8000/api", timeout: 5)
+
+res = client.publish(channel: "news", data: { text: "hello" })
+puts "published at offset #{res["result"]["offset"]}"
+
+res = client.history(channel: "news", limit: 1, reverse: true)
+puts "last: #{res["result"]["publications"][0]["data"]["text"]}"
+
+# Centrifugo's errors are raised.
+begin
+  client.publish(channel: "unknown:news", data: { text: "hello" })
+rescue Cent::ResponseError => e
+  puts "error #{e.code}: #{e.message}"
+end
+```
+
+cent 5:
+
+```ruby
+require "cent"
+
+client = Cent::Client.new(api_endpoint: "http://localhost:8000/api", api_key: "api_key", request_timeout: 5)
+
+res = client.publish(channel: "news", data: { text: "hello" })
+puts "published at offset #{res.offset}"
+
+res = client.history(channel: "news", limit: 1, reverse: true)
+puts "last: #{res.publications[0].data["text"]}"
+
+# Centrifugo's errors are raised, a class per code.
+begin
+  client.publish(channel: "unknown:news", data: { text: "hello" })
+rescue Cent::ApiError => e
+  puts "error #{e.code}: #{e.server_message}"
+end
+```
+
+### Broadcast
+
+A channel which failed is an error to rescue, not an entry to look for.
+
+cent 4:
+
+```ruby
+require "cent"
+
+client = Cent::Client.new(api_key: "api_key", endpoint: "http://localhost:8000/api")
+
+channels = ["news", "unknown:alerts", "sport"]
+res = client.broadcast(channels:, data: { text: "hello" })
+res["result"]["responses"].each_with_index do |r, i|
+  if r["error"]
+    puts "#{channels[i]}: error #{r["error"]["code"]}"
+  else
+    puts "#{channels[i]}: offset #{r["result"]["offset"]}"
+  end
+end
+```
+
+cent 5:
+
+```ruby
+require "cent"
+
+client = Cent::Client.new(api_endpoint: "http://localhost:8000/api", api_key: "api_key")
+
+begin
+  res = client.broadcast(channels: ["news", "unknown:alerts", "sport"], data: { text: "hello" })
+rescue Cent::BroadcastFailedChannelsError => e
+  # Some channels failed; the others got the publication.
+  res = e.result
+end
+res.channels.each do |ch|
+  if ch.error
+    puts "#{ch.channel}: error #{ch.error.code}"
+  else
+    puts "#{ch.channel}: offset #{ch.result.offset}"
+  end
+end
+```
+
+### Batch
+
+A batch has the client's methods, each adding a command with its own result.
+
+cent 4:
+
+```ruby
+require "cent"
+
+client = Cent::Client.new(api_key: "api_key", endpoint: "http://localhost:8000/api")
+
+res = client.batch(commands: [
+  { "publish" => { "channel" => "news", "data" => { "text" => "hi" } } },
+  { "presence_stats" => { "channel" => "news" } }
+])
+puts "published at offset #{res["replies"][0]["publish"]["offset"]}"
+puts "clients: #{res["replies"][1]["presence_stats"]["num_clients"] || 0}"
+```
+
+cent 5:
+
+```ruby
+require "cent"
+
+client = Cent::Client.new(api_endpoint: "http://localhost:8000/api", api_key: "api_key")
+
+batch = client.new_batch
+pub = batch.publish(channel: "news", data: { text: "hi" })
+stats = batch.presence_stats(channel: "news")
+batch.send
+puts "published at offset #{pub.value.offset}"
+puts "clients: #{stats.value.num_clients}"
+```
+
+### Tokens
+
+The claims are named for what they mean; the expiry is a `Time`, or `:never`.
+
+cent 4:
+
+```ruby
+require "cent"
+require "json"
+
+notary = Cent::Notary.new(secret: "secret")
+token = notary.issue_connection_token(sub: "42", exp: 1_900_000_000, info: { name: "Alice" }, channels: ["news"])
+puts JSON.parse(token.split(".")[1].unpack1("m")).slice("sub", "exp", "info", "channels")
+
+token = notary.issue_channel_token(sub: "42", channel: "news", exp: 1_900_000_000)
+puts JSON.parse(token.split(".")[1].unpack1("m")).slice("sub", "exp", "channel")
+```
+
+cent 5:
+
+```ruby
+require "cent"
+
+key = Cent::Token::Key.hmac("secret")
+token = Cent::Token.connection(key, user: "42", expires_at: Time.at(1_900_000_000), info: { name: "Alice" },
+                                    channels: ["news"])
+puts JSON.parse(token.split(".")[1].unpack1("m")).slice("sub", "exp", "info", "channels")
+
+token = Cent::Token.subscription(key, user: "42", channel: "news", expires_at: Time.at(1_900_000_000))
+puts JSON.parse(token.split(".")[1].unpack1("m")).slice("sub", "exp", "channel")
+```
+
+## Mapping
+
+| cent 4 | cent 5 |
+|---|---|
+| `Cent::Client.new(api_key:, endpoint:, timeout:)` | `Cent::Client.new(api_endpoint:, api_key:, request_timeout:)`; `api_endpoint` is required, without a default; `request_timeout` bounds every call whole |
+| the Faraday block: `conn.options...`, `conn.adapter` | `http_options: { ca_file:, cert:, key:, ... }`, or `http_client:` for another HTTP library; `timeout:` on a call replaces `request_timeout` for it |
+| `conn.headers["User-Agent"] = ...` | `headers: { "User-Agent" => ... }` |
+| `Cent::ResponseError` for a request Centrifugo refused as invalid (code 107) | often `Cent::InvalidRequestError`, raised before sending |
+| `publish(channel:, data:, ...)` and the other methods | the same names and keywords, every field of the request; a result object instead of the response Hash |
+| `history(..., since: { "offset" => 5, "epoch" => "x" })` | `since: { offset: 5, epoch: "x" }`, or `Cent::StreamPosition.new(...)`: field names are Symbols |
+| `disconnect(whitelist:)` | gone from Centrifugo v6 |
+| `broadcast(...)` with errors in `responses` | raises `BroadcastFailedChannelsError` when a channel failed; `broadcast_with_retry` |
+| `batch(commands: [...])` | `batch = client.new_batch; p = batch.publish(...); batch.send; p.value` |
+| `Cent::ResponseError` (`code`, `message`) | `Cent::ApiError` (`code`, `server_message`, `temporary?`), a subclass per known code |
+| `Cent::TransportError` (`status`) | `Cent::HTTPError` (`status_code`, `body`, `headers`) |
+| `Cent::TimeoutError`, `Cent::NetworkError`, `Cent::UnauthorizedError`, `Cent::DecodeError` | the same names |
+| `Cent::Notary.new(secret:, algorithm:)` | `Cent::Token::Key.hmac(secret)`, `.rsa(pkey)`, `.ecdsa(pkey)`, `.ed25519(pkey)`, `.from_pem(pem)`; HMAC tokens are HS256 |
+| `issue_connection_token(sub:, exp:, iat:, jti:, aud:, iss:, ...)` | `Cent::Token.connection(key, user:, expires_at:, issued_at:, id:, audience:, issuer:, ...)` |
+| `issue_channel_token(sub:, channel:, ...)` | `Cent::Token.subscription(key, user:, channel:, expires_at:, ...)` |
+| a token without `exp`, which never expired | `expires_at: :never`, chosen explicitly |
+| `expire_at:` claims as Unix seconds | `connection_expires_at:`, `subscription_expires_at:` as a `Time`, or `:never` |
+
+For tests, give the client a fake `http_client:` instead of stubbing HTTP: a
+callable returning `[status, headers, body]`.