HTTP Server

NotFound vs Response Control

Two mechanisms for handling requests that don't match any registered route: visual presentation vs functional control.

Feature	notFound (Visual)	responseControl (Functional)
Primary Goal	Render a branded 404 page for humans.	Control HTTP behaviour (JSON, status, logic).
Default Status	404 Not Found	Customizable (403, 410, 500, etc.)
Content Type	text/html (Fixed)	application/json, text/plain, etc.
Mode Support	XS-M (Global)	XS-M & XM-M (Per Instance)
Priority	Low (Last Resort)	High (Hijacks the response)

Priority Rule

If both systems are enabled, responseControl takes precedence. XyPriss first checks if a custom response is defined. If it handles the request, the process stops. Otherwise, it falls back to notFound.

notFound: Visual Template

The notFound configuration is designed for web applications that need a branded error page. It uses a built-in template engine to inject titles, messages, and themes.

typescript

notFound: {
  enabled: true,
  title: "Oops! Lost in space",
  themeClass: "dark",
  redirectTo: "/home"
}

Use this when:you want a themed 404 page, a "Go back home" button with countdown, or custom CSS injection into the error page.

responseControl: Behavioural Control

The responseControl system is a powerful, low-level interceptor. It is designed for APIs or security-conscious applications that need to control the actual HTTP response payload and status.

typescript

responseControl: {
  enabled: true,
  statusCode: 403,
  content: { status: "denied", message: "Unauthorized path access" },
  contentType: "application/json"
}

Use this when: you are building a JSON API, want to return 403 for unknown routes (security by obscurity), or need to execute a server-side function (log the event, block an IP).

Dynamic vs Static

notFound is largely static (configured at startup). responseControl is dynamic — use app.setResponseControl() to hot-swap error handling logic in real-time (e.g. trigger maintenance mode or security lockdown).

XM-M (Multi-Server) Usage

In Multi-Server mode, each instance should use responseControl for isolation, while notFound typically serves as the global system fallback.

Dynamic Hot-Swapping

You can update responseControl at runtime without restarting the server:

typescript

// Emergency maintenance switch
app.setResponseControl({
  enabled: true,
  statusCode: 503,
  content: "System is undergoing scheduled updates."
});

Multi-Server Setup

Configure per-instance response control and route isolation with XMS.