DF0056: Instance Advertises an External WebSocket Endpoint

Message

This instance advertises an external WebSocket endpoint ({url}), so it serves no socket of its own.

Cause

ws.url on its own is the advertise-only tier: __connection.json names a fully-qualified endpoint the browser dials verbatim, and the server behind that URL owns the transport and its auth — this instance builds neither. There is therefore no socket for attach(server) / handleUpgrade(req, socket, head) to feed.

Example

import { initDevframe } from 'devframe/initiate'

const relayed = initDevframe(def, {
  base: '/__my-tool/',
  ws: { url: 'wss://devtools.example.com/relay/__ws' },
})
relayed.attach(myServer) // ✗ throws DF0056 — an external server owns the socket

// ✓ Serve the socket here, advertised through the relay (the tunnel pattern).
const tunnelled = initDevframe(def, {
  base: '/__my-tool/',
  ws: { url: 'wss://devtools.example.com/relay/__ws', sidecar: true },
})

Fix

Drop ws.url to have the instance serve the socket, or pair it with server / ws.port / ws.sidecar for the tunnel pattern — a local binding that the advertised relay forwards to. To serve RPC from a server you wire yourself, compose createContextRpcServer (devframe/internal) with a WS transport (devframe/rpc/transports/ws-server) against the instance's context and keep ws.url pointed at it.

Source

• packages/devframe/src/node/instance-shell.ts — the shared instance shell throws this from attach / handleUpgrade when the resolved tier is external, for both initDevframe and initHub.