KrakenJS Routing Layer and HTTP Server Boot Sequence Interoperability

Direct Answer

KrakenJS does guarantee that all automatically discovered controllers and routes are registered before the HTTP server begins accepting connections. The framework's bootstrapper executes route registration synchronously during the boot phase and only invokes server.listen() after that phase completes without error.

Confirmed Boot Order

1. Configuration loading (synchronous require of config/ files)
2. Service initialization (synchronous constructor execution)
3. Controller discovery and route registration (synchronous filesystem walk + app.use()/app.METHOD() calls)
4. Internal 'boot' event emission
5. server.listen(port, callback) invocation

Steps 1–3 run on the same tick; step 5 occurs only after step 4's listeners return.

Explicit Hook for "Routes Ready"

Listen for the 'boot' event on the Kraken application instance:

const kraken = require('kraken-js');
const app = kraken.create();

app.on('boot', function () {
  // All auto-discovered routes are now registered
  console.log('Routes registered, safe to start custom async work');
});

app.listen(8000); // server.listen called internally after 'boot' fires

This event is the documented signal that the Express router is fully populated.

Async Service Initialization Caveat

The guarantee covers framework-managed discovery only. If a service constructor or a controller's initialize() method starts asynchronous work (database connections, external API calls, file I/O) without returning a promise that the bootstrapper awaits, that work may still be in flight when server.listen fires. KrakenJS does not automatically await arbitrary promises returned from service constructors.

Documented behavior: requests arriving during that window will reach Express middleware and route handlers, but any handler that depends on the unfinished async initialization may crash or return 500. The framework makes no "graceful degradation" promise for this scenario.

Verification Steps

1. Add console.log('boot event') in an app.on('boot', …) listener.
2. Add console.log('controller loaded') in a controller file's top-level code.
3. Start the app and observe log order — controller logs appear before "boot event".
4. Immediately curl a known route; it should return 200 (or handler-specific status), never 404 from missing registration.

One Diagnostic Detail Needed

Are you using any service or controller that performs asynchronous initialization without returning a promise to the bootstrapper (e.g., setTimeout, bare Promise constructor, event-emitter callbacks)? If yes, the race window exists; if no, the guarantee holds.