diff --git a/docs/README.md b/docs/README.md index b35e9b9..9db0b89 100644 --- a/docs/README.md +++ b/docs/README.md @@ -26,6 +26,8 @@ Make your real-time communication fast and [reliable](./anycable-go/reliable_str ## Latest updates 🆕 +- **2024-03-12**: [Standalone mode via signed streams](./anycable-go/signed_streams.md) + - **2023-11-08**: [AnyCable for serverlsess JavaScript applications](./guides/serverless.md) - **2023-11-03**: [NATS JetStream broker](./anycable-go/reliable_streams.md#nats) support is added to AnyCable-Go v1.4.7+. diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 9783c16..f8d8f54 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -12,13 +12,16 @@ * [Using with Rails](/rails/getting_started.md) * [Using with JavaScript (serverless)](/guides/serverless.md) * [Using with Hotwire](/guides/hotwire.md) + * [Broadcasting](/anycable-go/broadcasting.md) + * [Signed streams](/anycable-go/signed_streams.md) * [Reliable streams](/anycable-go/reliable_streams.md) * [Using with Ruby](/ruby/non_rails.md) * [JWT authentication](/anycable-go/jwt_identification.md) -* AnyCable-Go pro +* AnyCable pro * [Going PRO](/pro.md) * [Install PRO](/pro/install.md) + * [AnyCable RPC](/anycable-go/rpc.md) * [Apollo GraphQL](/anycable-go/apollo.md) * [Binary formats](/anycable-go/binary_formats.md) * [Long polling](/anycable-go/long_polling.md) @@ -47,6 +50,7 @@ * [CLI](/ruby/cli.md) * [Configuration](/ruby/configuration.md) * [HTTP RPC](/ruby/http_rpc.md) + * [Rails extensions](/rails/extensions.md) * [Authentication](/rails/authentication.md) * [Channels state](/rails/channels_state.md) * [gRPC middlewares](/ruby/middlewares.md) @@ -60,6 +64,7 @@ * AnyCable-Go * [Getting started](/anycable-go/getting_started.md) * [Configuration](/anycable-go/configuration.md) + * [AnyCable RPC](/anycable-go/rpc.md) * [Server-sent events](/anycable-go/sse.md) * [Broker deep dive](/anycable-go/broker.md) * [Pub/sub (node-node)](/anycable-go/pubsub.md) @@ -82,6 +87,7 @@ * [AnyCable server spec](/misc/how_to_anycable_server.md) * Upgrade Notes + * [From v1.4.x to v1.5.0](/upgrade-notes/1_4_0_to_1_5_0.md) * [From v1.3.x to v1.4.0](/upgrade-notes/1_3_0_to_1_4_0.md) * [From v1.2.x to v1.3.0](/upgrade-notes/1_2_0_to_1_3_0.md) * [From v1.0.x to v1.1.0](/upgrade-notes/1_0_0_to_1_1_0.md) diff --git a/docs/architecture.md b/docs/architecture.md index 8f759e9..93a2595 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -13,11 +13,7 @@ AnyCable **real-time server** (WS, or WebSocket, since it's a primary transport) - subscriptions management - broadcasting messages to clients -WebSocket server should include gRPC client built from AnyCable [`rpc.proto`](misc/rpc_proto.md) or a compatible HTTP implementation (for [RPC over HTTP](../ruby/http_rpc.md)). - -**RPC server** is a connector between the Ruby application (e.g. Rails) and WebSocket server. It’s an instance of your application with a [gRPC](https://grpc.io) endpoint which implements `rpc.proto`. This server is a part of the [`anycable` CLI](ruby/cli.md). - -**NOTE:** It's also possible to use an [HTTP RPC](../ruby/http_rpc.md), which can be embedded into your main web server (e.g. Puma). Thus, you can avoid running a separate RPC server process. +AnyCable can be used in a standalone mode as a typical pub/sub server. However, it was primarily designed to act as a _business-logic proxy_ allowing you to avoid duplicating real-time logic between multiple apps. For that, we use an [RPC protocol](/anycable-go/rpc) to delegate subscriptions, authentication and authorization logic to your backend. The application publish broadcast messages to the WebSocket server (directly via HTTP or via some **queuing service**, see [broadcast adapters](/ruby/broadcast_adapters.md)). In case of running a WebSocket cluster (multiple nodes), there is also can be a **Pub/Sub service** responsible for re-transmitting broadcast messages between nodes. You can use [embedded NATS](/anycable-go/embedded_nats.md) as a pub/sub service to miminalize the number of infrastructure dependencies. See [Pub/Sub documentation](/anycable-go/pubsub.md) for other options. @@ -51,17 +47,3 @@ This results in a slightly different behaviour comparing to persistent, long-liv For example, if you use an Active Record object as an identifier (e.g., `user`), it's _reloaded_ in every RPC action it's used. To use arbitrary Ruby objects as identifiers, you must add GlobalID support for them (see [AnyCable setup demo](https://github.com/anycable/anycable_rails_demo/pull/2)). - -## WebSocket servers - -Since AnyCable uses a well-defined protocol for communication between a WebSocket server and a primary web application (e.g., Rails), any WebSocket server that implements AnyCable [gRPC](https://grpc.io) or HTTP API can be used. - -Since v1.0 the only officially supported (i.e., recommended for production usage) server is [AnyCable-Go](anycable-go/getting_started.md) (written in Golang). AnyCable-Go also supports alternative transports such as Server-Sent Events and long-polling. - -For older versions you can still use [`erlycable`](https://github.com/anycable/erlycable) (Erlang). - -We also have a server written in Ruby–[AnyCable Rack Server](https://github.com/anycable/anycable-rack-server)–which could be used for local experiments to emulate the same architecture as with _real_ AnyCable server. - -> See [the demo](https://github.com/anycable/anycable_rails_demo/pull/1) of how you can use anycable-rack-server to run system tests. - -If you're not happy with the above implementations, you can build your own [AnyCable-compatible server](misc/how_to_anycable_server.md). diff --git a/docs/getting_started.md b/docs/getting_started.md index c058d16..da62905 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,16 +1,14 @@ -# Getting Started +# Getting started -AnyCable acts like a bridge between _logic-less_ real-time server and _Action Cable-like_ Ruby framework (i.e. framework which support [Action Cable protocol](misc/action_cable_protocol.md)). AnyCable is a multi-transport server supporting WebSockets, [Server-Sent Events](/anycable-go/sse.md) and [long-polling](/anycable-go/long_polling.md). +AnyCable is a language-agnostic server for web applications that brings performance and reliability to your real-time features. It follows Rails Action Cable conventions and uses [Action Cable protocol](misc/action_cable_protocol.md) as a primary communication protocol (while supporting others as well). AnyCable is a multi-transport server supporting WebSockets, [Server-Sent Events](/anycable-go/sse.md) and [long-polling](/anycable-go/long_polling.md).
AnyCable diagram AnyCable diagram
-The primary goal of AnyCable is to make it possible to write a high-performant real-time application using Ruby as a language for implementing a business-logic. - -This goal is achieved by _moving_ low-level responsibility (handling connections, parsing frames, broadcasting data) to real-time servers written in other languages (such as Golang or Erlang). +The primary goal of AnyCable is to make it possible to write a high-performant real-time application keeping business-logic in your backend application (whether it's Ruby on Rails or serverless JavaScript or whatever). AnyCable could be used with the existing Action Cable clients (such as [Rails JavaScript client](https://www.npmjs.com/package/actioncable) or [Action Cable CLI](https://github.com/palkan/acli)) without any change. However, for web development we recommend using [AnyCable JS/TS client](https://github.com/anycable/anycable-client), which provides better compatibility with AnyCable-specific features. @@ -18,5 +16,5 @@ You can use AnyCable with: - Action Cable (Rails) applications (see [Using with Rails](rails/getting_started.md)) - Hotwire applications (see [Using with Hotwire](guides/hotwire.md)) +- JavaScript applications (see [Using with JavaScript](/guides/serverless.md)) - [Lite Cable](https://github.com/palkan/litecable) for _plain_ Ruby projects (see [Using with Ruby](ruby/non_rails.md)) -- your own [AnyCable-compatible framework](ruby/non_rails.md). diff --git a/docs/release_notes.md b/docs/release_notes.md index d4ae505..47e66e1 100644 --- a/docs/release_notes.md +++ b/docs/release_notes.md @@ -2,6 +2,18 @@ This page contains combined release notes for major and minor releases of all AnyCable libraries. +## 1.5.0 + +### Highlights + +- **Signed streams and public streams** + +TBD + +- **One secret to rule them all** + +TBD + ## 1.4.0 ### Highlights diff --git a/docs/upgrade-notes/1_4_0_to_1_5_0.md b/docs/upgrade-notes/1_4_0_to_1_5_0.md new file mode 100644 index 0000000..6240428 --- /dev/null +++ b/docs/upgrade-notes/1_4_0_to_1_5_0.md @@ -0,0 +1,49 @@ +# Upgrading from 1.4.x to 1.5.0 + +This document contains only the changes compared to v1.4.x releases. For the new features see the [release notes](../release_notes.md). + +## Upgrade process + +You can upgrade AnyCable server and your backend SDK (Ruby, JS) in any order. As soon you upgrade both, you can migrate your secrets (see below). + +## Secrets management + +TBD + +## AnyCable Rails + +### JWT + +The `anycable-rails-jwt` has been merged into `anycable` and `anycable-rails` gems. Remove `anycable-rails-jwt` from your Gemfile. + +If you used `AnyCable::Rails::JWT` module explicitly in your code, update it to `AnyCable::JWT` and pass identifiers as a Hash: + +```diff +- AnyCable::Rails::JWT.encode(current_user:, expires_at: 10.minutes.from_now) ++ AnyCable::JWT.encode({current_user:}, expires_at: 10.minutes.from_now) +``` + +### Configuration changes + +Some configuration parameters has been renamed as follows: + +- `http_broadcast_secret` -> `broadcast_key` +- `jwt_id_key` -> `jwt_secret` +- `jwt_id_ttl` -> `jwt_ttl` +- `jwt_id_param` -> `jwt_param` + +## AnyCable-Go + +### Configuration changes + +Some configuration parameters has been renamed as follows: + +- `http_broadcast_secret` -> `broadcast_key` +- `jwt_id_key` -> `jwt_secret` +- `jwt_id_ttl` -> `jwt_ttl` +- `jwt_id_param` -> `jwt_param` +- `jwt_id_enforce` -> `enforce_jwt` +- `turbo_rails_key` -> `turbo_secret` + `turbo_streams` +- `cable_ready_key` -> `cable_ready_secret` + `cable_ready` + +Older parameter names are still supported but deprecated and will be removed in v2.