axiosleo/node-koapp/koapp-apps

@axiosleo/koapp Application Classes

@axiosleo/koapp exposes three runtime application classes, all extending a shared Application base. Pick one based on the transport you need.

Which class do I need?

All three accept { port, routers, debug, app_id } at minimum; see the per-class docs for full options:

• http-server.md - KoaApplication
• socket-server.md - SocketApplication
• websocket-server.md - WebSocketApplication
• examples.md - full server examples

Shared config keys

All three apps normalize config through Configuration from @axiosleo/cli-tool:

{
  port: 8080,            // Port to listen on
  listen_host: 'localhost', // '0.0.0.0' for public access (Koa only)
  routers: [],           // Array of Router instances
  app_id: '',            // Optional stable ID; auto uuid-v4 if empty
  debug: false           // Verbose logging
}

Shared events

All apps extend EventEmitter and emit:

• starting - before the server binds
• response - after each response is produced (framework uses this internally to write the response)

Socket apps also expose a separate app.event EventEmitter emitting:

• connection - new client connected
• listen - server bound to the port

Shared lifecycle

const app = new KoaApplication({ ... });
app.on('starting', () => console.log('about to listen'));
await app.start();       // all three classes implement .start()

Connection management (Socket + WebSocket)

SocketApplication implements the following methods, inherited by WebSocketApplication:

• broadcast(data, msg, code, connections) - send to many; pass null for all
• send(connection, data, msg, code) - send to one raw connection
• close(connection) - close one raw connection
• sendByConnectionId(id, data, msg, code) - send by tracked connection ID
• closeByConnectionId(id) - close by tracked connection ID
• getConnection(id) - returns the raw connection or null
• ping(id) - send a ping payload to one connection

Connections are tracked in app.connections keyed by an auto-generated connection_id (_uuid_salt('connect:' + app_id)).

Ping heartbeat

Socket apps support opt-in periodic ping:

new SocketApplication({
  port: 8801,
  routers: [root],
  ping: {
    open: true,              // default false
    interval: 1000 * 60 * 5, // default 5min
    data: 'this is a ping'
  }
});

When ping.open is true, the app broadcasts data to all active connections every interval ms.

Protocol differences

Common pitfalls

• Calling new KoaApplication({ static: false }) disables the built-in

static server. Set static: { rootDir: './public' } to enable it.

• SocketApplication requires every inbound message to end with @@@@@@.

Clients must append that delimiter.

• WebSocketApplication.ping.open = true triggers broadcast every

interval even when there are zero connections - the call is a no-op but still schedules.

• Do not call app.start() inside a route handler - the app is already

running at that point.

Quick jump

If you just need to build one server, start with the matching doc:

• Building an HTTP API → http-server.md
• Building a TCP service → socket-server.md
• Building a WebSocket service → websocket-server.md
• Copy-paste-ready examples → examples.md
• Typing contexts and configs in TypeScript → koapp-typescript