Quick start

This matches the layout used in the cat-demo backend: load QA registrations first, run Express (with CORS for the Gloocan web app), attach inspector correlation on /api routes, then attachCatRPC on the same HTTP server as Socket.IO.

Prerequisites: Installation (@gloocan/cat-inspector, socket.io, express).

1. Host API key

Create a key in Gloocan Cat-Inspector → API Keys (+ Create API key). Copy the secret once—it is not shown again. Put it in .env as GLOOCAN_HOST_API_KEY. See attachCatRPC → secretApiKey.

2. Register handlers

Anything you expose to QA must be registered with cat(), @Cat, or catModule() before attachCatRPC runs. That registration code has to run when your process starts, which means it must be reachable from server.ts:

Direct — call cat(...) (or load a decorated class) in server.ts, or
Nested — import './some-module.js' at the top of server.ts where that file (or its imports) calls cat() / @Cat / catModule().

If the import chain from server.ts never executes your registration, the catalog will be empty. See Registration for how to define handlers.

3. `server.ts`


import 'reflect-metadata'
 
import http from 'node:http'
import { fileURLToPath } from 'node:url'
 
import express from 'express'
import { Server as SocketIOServer } from 'socket.io'
import {
	attachCatRPC,
	createInspectorCorrelationMiddleware,
} from '@gloocan/cat-inspector/socket-io'
 
const HTTP_PORT = Number(process.env.PORT ?? 5050)
const QA_WEB_ORIGIN = process.env.QA_WEB_ORIGIN ?? 'http://localhost:3013'
const GLOOCAN_HOST_API_KEY = process.env.GLOOCAN_HOST_API_KEY?.trim() ?? ''
 
const app = express()
 
app.use((req, res, next) => {
	res.setHeader('Access-Control-Allow-Origin', QA_WEB_ORIGIN)
	res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
	res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Socket-Id')
	if (req.method === 'OPTIONS') {
		res.sendStatus(204)
		return
	}
	next()
})
app.use(express.json())
app.get('/health', (_req, res) => res.json({ ok: true }))
 
// Links HTTP runs to the inspector Socket.IO tab (X-Socket-Id header from QA web).
app.use('/api', createInspectorCorrelationMiddleware())
// app.use('/api', yourExpressRouter)
 
const server = http.createServer(app)
const io = new SocketIOServer(server, {
	cors: { origin: QA_WEB_ORIGIN },
})
 
const catRpc = attachCatRPC(io, {
	scanRoots: [fileURLToPath(new URL('.', import.meta.url))],
	serverId: 'my-app-backend',
	isDevelopment: process.env.NODE_ENV !== 'production',
	...(GLOOCAN_HOST_API_KEY ? { secretApiKey: GLOOCAN_HOST_API_KEY } : {}),
	upload: {
		enabled: true,
		maxSizeBytes: 50 * 1024 * 1024,
		idleTimeoutMs: 60_000,
	},
	bootstrap: {
		logLevel: 'info',
	},
})
 
server.listen(HTTP_PORT, () => {
	console.log(`Backend listening on http://localhost:${HTTP_PORT}`)
})
 
process.on('SIGTERM', () => {
	catRpc.detach()
	server.close()
})

What each piece does

Piece	Why
Registration import	Ensures `cat()` / `@Cat` / `catModule()` ran before `attachCatRPC` builds the catalog (direct or nested from `server.ts`).
CORS on Express	Lets the Gloocan QA web app (e.g. port `3013`) call your REST API during tests.
`createInspectorCorrelationMiddleware()`	On `/api`, reads `X-Socket-Id` from QA and ties HTTP handler runs to the right inspector socket (correlation).
`attachCatRPC(io, …)`	Serves catalog + RPC over Socket.IO on the same server as Express.
`scanRoots`	AST scan of `.ts` under your backend folder to enrich catalog types (handlers must already be registered).
`secretApiKey`	Tenant host key for Gloocan catalog verification—from env only, never committed.
`upload.enabled`	Allows file parameters via Socket.IO ref uploads (default wire mode `ref`).

4. Environment


GLOOCAN_HOST_API_KEY=qa_sk_live_…   # Cat-Inspector → API Keys
QA_WEB_ORIGIN=http://localhost:3013 # must match Socket.IO CORS + Express CORS
PORT=5050
NODE_ENV=development

Checklist

Step	What you did
1	Installed the package and peers (Installation)
2	Registered handlers (`cat()` etc.) so they run from `server.ts` (direct or nested import) before `attachCatRPC`
3	Mounted `createInspectorCorrelationMiddleware()` on `/api` if you use Express routes with QA
4	Called `attachCatRPC` with `scanRoots` + `secretApiKey` on your Socket.IO server
5	In Gloocan, pointed the host profile at this backend’s URL

Next steps

attachCatRPC — rate limits, file URL mode, hostMinio, expandParamTypes, production auth.
Express correlation — X-Socket-Id and pipeline routing.
cat() registration — fnKeys, schemas, Express api routes.