@xpulse/http – Component Spec

Status: CONCEPT · Created March 2026 Parent: GLOBAL_concept-ecosystem.md, GLOBAL_concept-web.md

Overview

HTTP server for the xPulse ecosystem. Provides server, request, and response.

One responsibility: HTTP – nothing more.

Has no knowledge of routing concepts, controllers, or templates. Can be used standalone – for minimal projects without an MVC stack.

Dependencies

1 @xpulse/http
2   ├── @xpulse/event    ← fire http:request, http:response
3   └── @xpulse/logger   ← internal logging

API

Initialising

1 import http from '@xpulse/http';
2  
3 await http.init();

env, debug, and port come from .env via @xpulse/config – http.init() takes no parameters.

Starting / Stopping

1 http.start(); // blocking
2 http.stop();  // graceful shutdown – finish in-flight requests first

Registering a route

1 http.route('GET',  '/path',  handler);
2 http.route('POST', '/path',  handler);

Handler signature:

1 (req, res) => {
2     res.send('<h1>Hello</h1>');
3 }

Minimal example without MVC

1 import http from '@xpulse/http';
2  
3 await http.init();
4  
5 http.route('GET', '/', (req, res) => {
6     res.send('<h1>xPulse</h1>');
7 });
8  
9 http.route('GET', '/health', (req, res) => {
10     res.status(200).send('ok');
11 });
12  
13 http.start();
14 process.on('SIGTERM', () => http.stop());

Request API

Property / Method	Description
`req.method`	HTTP method – `GET`, `POST`
`req.path`	URL path without query string – `/tool/chat`
`req.params`	URL parameters from pattern – `{ id: '42' }`
`req.query`	Query string parameters – `{ lang: 'de' }`
`req.body`	Request body – parsed for `POST`
`req.headers`	Request headers

URL Parameters Example

1 http.route('GET', '/tool/:tool/:page?', (req, res) => {
2     const { tool, page } = req.params;
3     // /tool/chat        → { tool: 'chat', page: undefined }
4     // /tool/chat/guide  → { tool: 'chat', page: 'guide'  }
5     res.send(`Tool: ${tool}`);
6 });

Query String Example

1 http.route('GET', '/doc', (req, res) => {
2     const lang = req.query.lang ?? 'de';
3     // /doc?lang=en → lang = 'en'
4     res.send(`Lang: ${lang}`);
5 });

Response API

Method	Description
`res.send(html)`	Send HTML, status 200
`res.status(code)`	Set status code, returns `res` (chainable)
`res.header(name, value)`	Set response header, returns `res` (chainable)

Chaining Example

1 res.status(404).send('<h1>Not found</h1>');
2 res.status(301).header('Location', '/new').send('');

Emitted Events

Event	Payload	When
`http:request`	`{ method, path, params, query }`	on every incoming request
`http:response`	`{ method, path, status, duration }`	after every response sent

1 import event from '@xpulse/event';
2  
3 event.on('http:request', ({ method, path }) => {
4     // automatically logged by @xpulse/logger
5 });

.env Configuration

Variable	Default	Description
`PORT`	`3000`	Server port
`HOST`	`0.0.0.0`	Server host

Debug Integration

When @xpulse/debug is installed as a devDependency, @xpulse/http automatically provides a DataCollector. @xpulse/debug discovers it via node_modules/@xpulse/http/src/datacollectors/ – no configuration needed.

1 "optionalDependencies": {
2   "@xpulse/debug": "^1.0.0"
3 }

The HttpCollector (name: 'http', icon: '🌐') shows in the Web Profiler:

Request (kv): Method, Path, Status, Duration, Content-Type, Scheme, Host
Request Headers (table): all HTTP request headers
Params (kv): URL parameters – only when present
Query (kv): query string parameters – only when present
Server Metrics (kv): Memory RSS/Heap, CPU User/System, Uptime

In addition the HttpCollector writes a Waterfall Span (kind: 'http') that represents the total request duration – the widest bar in the waterfall.

Badge in the toolbar: 200 · 12ms

Package Structure

1 @xpulse/http/
2   src/
3     index.js      ← default export: http object
4     server.js     ← Node http.createServer wrapper
5     request.js    ← request wrapper
6     response.js   ← response wrapper
7   test/
8     http.test.js
9     request.test.js
10     response.test.js
11   docs/
12     index.md
13     api.md
14     _meta.json
15   Dockerfile
16   Makefile
17   README.md
18   package.json
19   xpulse.json

1	@xpulse/http
2	├── @xpulse/event ← fire http:request, http:response
3	└── @xpulse/logger ← internal logging

1	http.start(); // blocking
2	http.stop(); // graceful shutdown – finish in-flight requests first

1	http.route('GET', '/path', handler);
2	http.route('POST', '/path', handler);

1	import http from '@xpulse/http';
2
3	await http.init();
4
5	http.route('GET', '/', (req, res) => {
6	res.send('<h1>xPulse</h1>');
7	});
8
9	http.route('GET', '/health', (req, res) => {
10	res.status(200).send('ok');
11	});
12
13	http.start();
14	process.on('SIGTERM', () => http.stop());

1	http.route('GET', '/tool/:tool/:page?', (req, res) => {
2	const { tool, page } = req.params;
3	// /tool/chat → { tool: 'chat', page: undefined }
4	// /tool/chat/guide → { tool: 'chat', page: 'guide' }
5	res.send(`Tool: ${tool}`);
6	});

1	http.route('GET', '/doc', (req, res) => {
2	const lang = req.query.lang ?? 'de';
3	// /doc?lang=en → lang = 'en'
4	res.send(`Lang: ${lang}`);
5	});

1	res.status(404).send('<h1>Not found</h1>');
2	res.status(301).header('Location', '/new').send('');

1	import event from '@xpulse/event';
2
3	event.on('http:request', ({ method, path }) => {
4	// automatically logged by @xpulse/logger
5	});

1	@xpulse/http/
2	src/
3	index.js ← default export: http object
4	server.js ← Node http.createServer wrapper
5	request.js ← request wrapper
6	response.js ← response wrapper
7	test/
8	http.test.js
9	request.test.js
10	response.test.js
11	docs/
12	index.md
13	api.md
14	_meta.json
15	Dockerfile
16	Makefile
17	README.md
18	package.json
19	xpulse.json