Subscription APIs with Bun

📡 Subscription APIs with Bun

Subscription APIs are a powerful way to keep clients updated in real time, especially in apps like chats, dashboards, or live tracking systems. With Bun, you can implement subscription APIs efficiently thanks to its lightning-fast performance and native WebSocket support. Let's dive into building real-time subscription APIs using Bun 🚀.

🔄 What is a Subscription API?

A Subscription API enables clients to receive data updates from the server automatically — without polling. It's often powered by WebSockets, Server-Sent Events (SSE), or libraries like GraphQL Subscriptions.

In contrast to traditional REST APIs where the client makes a request, here the server can proactively send data when something changes 🔔.

⚙️ Bun + WebSockets: The Real-Time Backbone

Bun supports websocket natively via its Bun.serve() function. Let’s build a simple subscription system that broadcasts messages to all connected clients 📢.

🧪 Basic WebSocket Server Example

const clients = new Set();

Bun.serve({
  port: 3000,
  fetch(req, server) {
    if (server.upgrade(req)) return;
    return new Response("WebSocket Server is running");
  },
  websocket: {
    open(ws) {
      clients.add(ws);
      console.log("🔌 Client connected");
    },
    message(ws, message) {
      console.log("📨 Message received:", message);
      for (const client of clients) {
        if (client !== ws) client.send(message);
      }
    },
    close(ws) {
      clients.delete(ws);
      console.log("❌ Client disconnected");
    }
  }
});

This creates a simple chat-like subscription API. Every message received from a client gets broadcast to others in real time 🔄.

📥 Subscribing from the Client

const ws = new WebSocket("ws://localhost:3000");

ws.onmessage = (event) => {
  console.log("📬 New update:", event.data);
};

ws.onopen = () => {
  ws.send("Hello from client!");
};

Once connected, the client receives any broadcast messages from the server. Instant updates, no polling, no hassle ⚡.

🧠 Use Cases for Subscription APIs

• 💬 Real-time chat apps
• 📈 Live analytics dashboards
• 📦 Order status tracking
• 🎮 Multiplayer game states
• 📲 Push notifications for apps

🧰 Adding Context: Identifying Users

In real-world apps, we usually need to know who’s connected. You can enhance the open handler with headers or query params:

open(ws, req) {
  const url = new URL(req.url);
  const username = url.searchParams.get("user") || "anonymous";
  ws.username = username;
  console.log(`🙋 ${username} connected`);
}

Now you can personalize subscriptions or filter messages per user.

🔐 Securing Subscription APIs

Security is crucial in real-time systems. Here’s how to harden your WebSocket setup:

• 🔑 Authenticate users via tokens in headers or query params
• 🛡️ Sanitize all incoming messages
• 📏 Enforce message size limits
• ⏱️ Implement heartbeat pings for idle timeouts

🚀 Advanced: GraphQL Subscriptions in Bun

Want a GraphQL-style subscription layer? You can implement it using graphql-ws with Bun’s WebSocket server. Here’s a simplified idea:

import { useServer } from "graphql-ws/lib/use/ws";
import { WebSocketServer } from "ws";

const schema = buildSchema(`type Subscription { counter: Int }`);

let count = 0;

const server = new WebSocketServer({ port: 4000 });
useServer({
  schema,
  execute,
  subscribe,
  roots: {
    Subscription: {
      counter: {
        subscribe: async function* () {
          while (true) {
            await Bun.sleep(1000);
            yield { counter: ++count };
          }
        }
      }
    }
  }
}, server);

Now your Bun app can serve proper GraphQL subscriptions — ideal for frontend frameworks like Apollo or Relay 🎯.

📦 Message Queues & Subscriptions

You can even plug subscription events into queues like Redis Pub/Sub or Kafka to distribute updates across multiple servers for scale and resilience.

🧪 Testing Your Subscription API

For local testing, use tools like:

• 🔗 wscat – WebSocket CLI for testing
• 🧪 In-browser dev tools – Inspect WebSocket frames
• 🔍 Custom logging – Log messages and events

🏁 Wrapping Up

Subscription APIs add a powerful real-time layer to your Bun applications. With built-in WebSocket support and blazing speed, Bun makes building and scaling live updates easier than ever ⚡. Whether you're syncing live scores, updating dashboards, or chatting in real-time — Bun has you covered.