extensions

e9 - a worked example: discord

a discord app needs two things from outside the webapp: who you are, and what is happening in your voice channel.

identity comes from the settings page. it builds the authorize url with scopes identify rpc, calls settings.auth.authorize, exchanges the code with settings.fetch, and writes the tokens with settings.config.set. the whole thing is in connect an account.

ask for both scopes. discord refuses AUTHENTICATE and SUBSCRIBE on a token without rpc.

voice state comes from the extension, over a unix socket owned by the discord desktop client:

// extension/main.ts, on the desktop
import { defineExtension, json, type ExtensionContext } from '@bridgething/extension';

const CLIENT_ID = '…'; // the discord application id the settings page uses
const TOKEN_KEY = 'discord_access_token';

const socket = `${Deno.env.get('XDG_RUNTIME_DIR') ?? '/tmp'}/discord-ipc-0`;

let latest = { type: 'voice', speaking: false, channel: null as string | null };
let session: Promise<void> | null = null;
let live: Deno.Conn | null = null;
let lastToken: string | null = null;

function frame(op: number, payload: unknown): Uint8Array {
  const body = new TextEncoder().encode(JSON.stringify(payload));
  const out = new Uint8Array(8 + body.length);
  const head = new DataView(out.buffer);
  head.setUint32(0, op, true);
  head.setUint32(4, body.length, true);
  out.set(body, 8);
  return out;
}

// readFrames is yours: 4 byte op, 4 byte length, then json
async function pump(ctx: ExtensionContext, conn: Deno.Conn) {
  for await (const event of readFrames(conn)) {
    if (event.evt !== 'VOICE_STATE_UPDATE') continue;
    latest = { type: 'voice', speaking: event.data.speaking, channel: event.data.channel_id };
    ctx.broadcast(json(latest));
  }
}

async function open(ctx: ExtensionContext, token: string) {
  const conn = await Deno.connect({ transport: 'unix', path: socket });
  live = conn;
  try {
    await conn.write(frame(0, { v: 1, client_id: CLIENT_ID }));
    await conn.write(frame(1, { cmd: 'AUTHENTICATE', args: { access_token: token }, nonce: crypto.randomUUID() }));
    await conn.write(frame(1, { cmd: 'SUBSCRIBE', evt: 'VOICE_STATE_UPDATE', nonce: crypto.randomUUID() }));
    await pump(ctx, conn);
  } finally {
    if (live === conn) { // skip the close when a rotation already took the socket
      live = null;
      conn.close();
    }
  }
}

// one socket per process, cleared on any exit so the next event reopens it
function connect(ctx: ExtensionContext) {
  if (!lastToken || session) return;
  session = open(ctx, lastToken)
    .catch(err => ctx.log.error('discord ipc: ' + err))
    .finally(() => {
      session = null;
    });
}

// a rotated token needs a new socket, discord will not re-auth the live one
async function use(ctx: ExtensionContext, token: string | null) {
  if (token !== lastToken) {
    lastToken = token;
    const closing = session;
    live?.close();
    live = null;
    await closing;
  }
  connect(ctx);
}

defineExtension({
  start(ctx) {
    // ctx.devices is empty here, so read the config off the event
    ctx.on('device', event => {
      if (event.type === 'disconnected') return;
      event.device.send(json(latest)); // late joiners get current state instead of the next change
      void use(ctx, ctx.config(event.device)[TOKEN_KEY] ?? lastToken);
    });

    ctx.on('config', (device, key, value) => {
      if (key !== TOKEN_KEY) return;
      void use(ctx, value); // hold the last token so a reconnect skips the settings page
    });
  },
});

when the socket ends, the next event reopens it. a cleared token closes it.

permissions for this one are env:XDG_RUNTIME_DIR plus read and write on the socket path. the desktop app spawns deno with --no-prompt, so a missing permission crashes the extension.