@xpulse/http – Component Spec

Status: CONCEPT · Erstellt März 2026 Übergeordnet: GLOBAL_concept-ecosystem.md, GLOBAL_concept-web.md

Übersicht

HTTP Server für das xPulse Ökosystem. Stellt Server, Request und Response bereit.

Eine Aufgabe: HTTP – nicht mehr.

Kennt kein Routing-Konzept, keine Controller, kein Template. Kann standalone genutzt werden – für minimale Projekte ohne MVC Stack.

Dependencies

1 @xpulse/http
2   ├── @xpulse/event    ← http:request, http:response feuern
3   └── @xpulse/logger   ← internes Logging

API

Initialisieren

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

env, debug und Port kommen aus .env via @xpulse/config – http.init() hat keine Parameter.

Starten / Stoppen

1 http.start(); // blockierend
2 http.stop();  // graceful shutdown – laufende Requests noch abschliessen

Route registrieren

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

Handler-Signatur:

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

Minimales Beispiel ohne 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

Eigenschaft / Methode	Beschreibung
`req.method`	HTTP Methode – `GET`, `POST`
`req.path`	URL-Pfad ohne Query-String – `/tool/chat`
`req.params`	URL-Parameter aus Pattern – `{ id: '42' }`
`req.query`	Query-String Parameter – `{ lang: 'de' }`
`req.body`	Request Body – geparst bei `POST`
`req.headers`	Request Headers

URL-Parameter Beispiel

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 Beispiel

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

Methode	Beschreibung
`res.send(html)`	HTML senden, Status 200
`res.status(code)`	Status Code setzen, gibt `res` zurück (chainable)
`res.header(name, value)`	Response Header setzen, gibt `res` zurück (chainable)

Chaining Beispiel

1 res.status(404).send('<h1>Nicht gefunden</h1>');
2 res.status(301).header('Location', '/neu').send('');

Gefeuerte Events

Event	Payload	Wann
`http:request`	`{ method, path, params, query }`	bei jedem eingehenden Request
`http:response`	`{ method, path, status, duration }`	nach jeder gesendeten Response

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

.env Konfiguration

Variable	Default	Beschreibung
`PORT`	`3000`	Server Port
`HOST`	`0.0.0.0`	Server Host

Debug Integration

Wenn @xpulse/debug als devDependency installiert ist, stellt @xpulse/http automatisch einen DataCollector bereit. @xpulse/debug discovert ihn via node_modules/@xpulse/http/src/datacollectors/ – keine Konfiguration nötig.

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

Der HttpCollector (name: 'http', icon: '🌐') zeigt im Web Profiler:

Request (kv): Method, Path, Status, Duration, Content-Type, Scheme, Host
Request Headers (table): alle HTTP-Request-Header
Params (kv): URL-Parameter – nur wenn vorhanden
Query (kv): Query-String-Parameter – nur wenn vorhanden
Server Metrics (kv): Memory RSS/Heap, CPU User/System, Uptime

Außerdem schreibt der HttpCollector einen Waterfall-Span (kind: 'http') der die gesamte Request-Dauer abbildet – breitester Balken im Waterfall.

Badge in der Toolbar: 200 · 12ms

Paket-Struktur

1 @xpulse/http/
2   src/
3     index.js      ← default export: http-Objekt
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 ← http:request, http:response feuern
3	└── @xpulse/logger ← internes Logging

1	http.start(); // blockierend
2	http.stop(); // graceful shutdown – laufende Requests noch abschliessen

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>Nicht gefunden</h1>');
2	res.status(301).header('Location', '/neu').send('');

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

1	@xpulse/http/
2	src/
3	index.js ← default export: http-Objekt
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