attachCatRPC (host)

New here? Start with Quick start for a minimal copy-paste server, then return here for every option.

For Gloocan QA web and the cat-demo stack, the supported integration is attachCatRPC from @gloocan/cat-inspector/socket-io: your HTTP server creates a Socket.IO Server, then you attach catalog refresh, RPC invoke, uploads, and optional host-media wiring in one call.

The SDK still runs an internal catalog build (filesystem scan, AST merge, registry) when serving the catalog; you configure that through scanRoots, the nested bootstrap object.

import 'reflect-metadata'
import { Server as SocketIOServer } from 'socket.io'
import { attachCatRPC } from '@gloocan/cat-inspector/socket-io'
 
const io = new SocketIOServer(/* … */)
 
const cat = attachCatRPC(io, {
	scanRoots: [new URL('.', import.meta.url).pathname],
	// …see tables below
})
 
// on shutdown: cat.detach()

attachCatRPC wires catalog:bootstrap, catalog:refresh, rpc:call, upload events, optional host Minio over Socket.IO (v10+ when URL mode + host media + hostMinio are configured), and optional inspector broadcast fan-out. It returns { detach() } to unregister listeners and related policy hooks.

secretApiKey (required for Gloocan)

The TypeScript field is optional so local-only demos can start without a tenant key. For any deployment where QA traffic goes through Gloocan (tenant web verifies the host), treat secretApiKey as mandatory:

• Pass the host API key your tenant was issued (same concept as GLOOCAN_HOST_API_KEY in examples)—always from environment or a secret manager, never hardcoded in source.
• When set (non-empty after trim), the SDK merges it into each emitted catalog:bootstrap payload so the QA client can confirm this backend matches the expected tenant.
• If you omit it, the catalog payload has no secretApiKey; Gloocan-side verification will fail or be unsafe depending on product configuration.

Obtaining the key and wiring attachCatRPC

In your Gloocan Cat-Inspector tenant dashboard, open API Keys in the sidebar, then use + Create API key. Copy the full secret when it is shown—it is only displayed once and cannot be retrieved later from the list (you will only see a prefix on the keys table).

Put that value in your backend environment (for example GLOOCAN_HOST_API_KEY), then pass it into attachCatRPC as the top-level secretApiKey option—never commit the literal key to source control:

attachCatRPC(io, {
	// …scanRoots, bootstrap, etc.
	secretApiKey: process.env.GLOOCAN_HOST_API_KEY,
})

If the variable may be unset in local tooling, you can mirror the cat-demo pattern and only set the field when the env var is non-empty: ...(process.env.GLOOCAN_HOST_API_KEY ? { secretApiKey: process.env.GLOOCAN_HOST_API_KEY } : {}).

Example

scanRoots, serverId, isDevelopment, secretApiKey, top-level upload, nested bootstrap (AST expansion, file wire, URL fetch policy, host Minio—credentials stay server-side and are not serialized on the wire).

import { attachCatRPC } from '@gloocan/cat-inspector/socket-io'
 
attachCatRPC(io, {
	scanRoots: [new URL('.', import.meta.url).pathname],
	serverId: 'cat-demo-backend',
	isDevelopment: process.env.NODE_ENV !== 'production',
	secretApiKey: process.env.GLOOCAN_HOST_API_KEY!, // required when using Gloocan QA
	// When isDevelopment is false, also set e.g. rpcAuth: { token: process.env.QA_AUTH_TOKEN! },
 
	upload: {
		enabled: true,
		maxSizeBytes: 50 * 1024 * 1024,
		idleTimeoutMs: 60_000,
	},
	bootstrap: {
		expandParamTypes: true,
		expandParamTypesOptions: {
			maxDepth: 6,
			maxProps: 80,
			maxUnion: 10,
			maxLen: 10_000,
		},
		qaFileWire: { mode: 'url' },
		qaMediaUpload: { target: 'host' },
		fileUrl: {
			allowedHosts: ['localhost'],
			maxDownloadBytes: Number(process.env.QA_FILE_URL_MAX_BYTES ?? String(50 * 1024 * 1024)),
			timeoutMs: Number(process.env.QA_FILE_URL_TIMEOUT_MS ?? '30000'),
			maxRedirects: Number(process.env.QA_FILE_URL_MAX_REDIRECTS ?? '5'),
			allowHttp: true, // dev only; omit or false in production
		},
		hostMinio: {
			endpoint: 'localhost:9004',
			accessKeyId: process.env.MINIO_ACCESS_KEY!,
			secretAccessKey: process.env.MINIO_SECRET_KEY!,
			bucket: 'qa-app-media',
			forcePathStyle: true,
		},
	},
})

With qaFileWire.mode: 'url', qaMediaUpload.target: 'host', and bootstrap.hostMinio set, the SDK may advertise qaHostMediaUploadViaSocket on the catalog payload (v10+): bytes can flow over Socket.IO for host-held media without a separate HTTP upload URL.

Top-level attachCatRPC options

Nested bootstrap object (catalog build)

Nested options.bootstrap is a partial of the catalog-related fields from BootstrapOptions (there is no wsPort here—your Socket.IO server owns the transport).

Registration vs types: catalog build first ensures handlers exist in the registry (runtime import), then scanRoots reads .ts on disk for types. You only need importEntryUrls when QA registration modules are not already loaded from server.ts (routers, import './qa/load.js', etc.).

Validation helpers

These apply when you configure storage or URL file wire (including under attachCatRPC):

• validateBootstrapStorage(storage) — throws QA_STORAGE_NOT_CONFIGURED if artifactThresholdBytes > 0 without an adapter.
• validateBootstrapFileWire({ qaFileWire, fileUrl }) — when qaFileWire.mode === 'url', fileUrl.allowedHosts must be non-empty.

See also

• AST scanner
• Registration → @Cat decorator
• RPC pipeline
• Socket.IO transport (imports and event names)