Quickstart

Production looks like this:

1. Create an overlay in Cockpit and copy the master token (MT_...). Keep it on your backend only.
2. From the backend, mint a short-lived access token (AT_...).
3. The client opens the overlay. The SDK picks a nearby edge and connects with the access token.
4. Subscribe and publish.

Want traffic first, no account? Open demo.fastpubsub.com. The demo server issues an access token. The master token stays on that server. See Try the demos.

JavaScript

npm install @fastpubsub-sdk/client

Run the token step on a trusted backend. Do not put the master token in a browser.

import {
  CreateAccessTokenBuilder,
  TenantGrant,
  open,
} from "@fastpubsub-sdk/client";

const session = open("globaltest");

const request = new CreateAccessTokenBuilder()
  .createdBy("my-service")
  .expiresAt("+1h")
  .addTenantGrant(
    new TenantGrant(["my_tenant"])
      .allowPub(["public.#"])
      .allowSub(["public.#"])
  )
  .build();

const token = await session.createAccessToken(process.env.FPS_MASTER_TOKEN, request);

const client = await session.webSocket(token.token)
  .pingIntervalSec(3)
  .build();

const messages = await client.subscribe("my_tenant", "public.#");
await client.publish("my_tenant", "public.hello", "hi");
const message = await messages.recv();

open(overlay) starts a session. webSocket(...).build() selects a nearby edge (or reuses a cached one) and opens the socket.

Rust

[dependencies]
fastpubsub-sdk = "0.3"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

use fastpubsub_sdk::client::{open, FastPubSub};
use fastpubsub_sdk::transport::{SubscribeOptions, WebSocketTransport};
use fastpubsub_sdk::{CreateAccessTokenBuilder, TenantGrant};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let master_token = std::env::var("FPS_MASTER_TOKEN")?;
    let mut session = open("globaltest");
    session.resolve_edge().await?;

    let access_token = CreateAccessTokenBuilder::new()
        .created_by("my-rust-app")
        .expires_at_input("+1h")?
        .tenant_grant(
            TenantGrant::new(vec!["my_tenant".to_string()])
                .allow_pub(vec!["public.#".to_string()])
                .allow_sub(vec!["public.#".to_string()]),
        )
        .create_with_config(session.api_base()?, &master_token, session.http_config())
        .await?;

    let mut client: FastPubSub<WebSocketTransport> =
        session.web_socket(access_token)?.build().await?;

    let mut rx = client
        .subscribe("my_tenant", "public.#", &SubscribeOptions::default())
        .await?;

    client
        .publish("my_tenant", "public.hello", b"hi")
        .await?;

    let _ = rx.recv().await;
    Ok(())
}

Day-one facts

• Overlay, tenant, and channel are three different names. Overlay selects the network. Tenant isolates apps. Channel is the stream inside a tenant.
• Publish targets a concrete channel. Wildcards belong on subscribe and on token rules.
• Delivery is best-effort and online-only. See Delivery semantics.
• Browser WebTransport is available in the SDKs. Node.js WebTransport is not supported yet. See WebTransport.

C# and Java SDKs are not published packages yet. Use JavaScript or Rust.