From 0e2da8911e53358981905114e355db034bd073ce Mon Sep 17 00:00:00 2001 From: Juergen Kunz Date: Thu, 7 May 2026 20:22:12 +0000 Subject: [PATCH] docs: refresh readme and legal info --- readme.md | 114 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 60 insertions(+), 54 deletions(-) diff --git a/readme.md b/readme.md index df70754..8c01ca4 100644 --- a/readme.md +++ b/readme.md @@ -1,54 +1,47 @@ # CoreTraffic -CoreTraffic is the serve.zone ingress component that receives routing updates from Coreflow and applies them to `@push.rocks/smartproxy`. It runs as a small TypeScript service inside the cluster and keeps HTTP redirects, HTTPS termination, backend routing, default response headers, and optional basic authentication in sync with the control plane. +CoreTraffic is the serve.zone cluster ingress service. It connects to Coreflow, receives typed routing updates, and applies them to `@push.rocks/smartproxy` for HTTP redirects, TLS termination, reverse proxying, default response headers, and optional basic authentication. ## Issue Reporting and Security For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly. -## What It Does +## Runtime Model -CoreTraffic is intentionally focused: - -- Starts a `SmartProxy` instance for cluster ingress. -- Connects to Coreflow over `@api.global/typedsocket`. -- Registers the `updateRouting` typed request handler. -- Converts `IReverseProxyConfig[]` updates into SmartProxy route configs. -- Adds an HTTP-to-HTTPS redirect route on port `7999`. -- Adds HTTPS reverse-proxy routes on port `8000` with per-domain certificates. -- Adds the `servezone_coretraffic_version` response header to managed routes. - -## Runtime Flow +CoreTraffic is intentionally narrow. It is not the control plane and it does not discover services by itself. Coreflow computes the desired `IReverseProxyConfig[]` list and sends that list to CoreTraffic. ```text -Coreflow +Coreflow internal server at http://coreflow:3000 -> TypedSocket updateRouting - -> CoreflowConnector - -> CoretrafficTaskManager buffered setupRouting task - -> SmartProxy.updateRoutes(...) + -> CoreTraffic CoreflowConnector + -> buffered setupRouting task + -> SmartProxy.updateRoutes(...) ``` -Routing updates are buffered so fast repeated changes collapse into the most recent route state instead of overwhelming the proxy engine. +At startup CoreTraffic: -## Usage +- Creates a `SmartProxy` with an empty route set. +- Starts the proxy engine. +- Registers an `updateRouting` typed handler. +- Connects to `http://coreflow:3000` with `@api.global/typedsocket`. +- Tags its connection as `coretraffic` so Coreflow can target route updates. -```typescript -import { CoreTraffic } from 'coretraffic'; +## Ports and Routes -const coreTraffic = new CoreTraffic(); -await coreTraffic.start(); +CoreTraffic creates two route classes inside SmartProxy: -// later -await coreTraffic.stop(); -``` +| SmartProxy port | Route | Purpose | +| --- | --- | --- | +| `7999` | `http-to-https-redirect` | Redirects HTTP traffic to `https://{domain}{path}` with status `301`. | +| `8000` | `https-` | Terminates TLS and forwards traffic to the destination IP/port pairs from Coreflow. | -In production, CoreTraffic is normally started through `runCli()` and expects Coreflow to be reachable at `http://coreflow:3000`. +In the default Coreflow deployment, Docker maps host port `80` to CoreTraffic's `7999` and host port `443` to `8000`. ## Routing Input -CoreTraffic consumes `@tsclass/tsclass` reverse proxy configs: +CoreTraffic consumes reverse proxy configs from `@serve.zone/interfaces`, which extends the `@tsclass/tsclass` network shape: -```typescript +```ts const reverseConfig = { hostName: 'app.example.com', destinationIps: ['10.0.0.10'], @@ -63,41 +56,54 @@ const reverseConfig = { }; ``` -Each config becomes one HTTPS SmartProxy route with TLS termination and one or more backend targets generated from the destination IP/port combinations. +Every config becomes one HTTPS route. Multiple destination IPs and ports are expanded into SmartProxy forward targets. If `authentication` is present, CoreTraffic enables SmartProxy basic auth for that route. -## Development +Every managed route receives a response header named `servezone_coretraffic_version` with the running package version when available. -Install dependencies with pnpm: +## Buffered Updates -```bash +Route updates are executed through `@push.rocks/taskbuffer` with `bufferMax: 2`. That means fast repeated updates are collapsed instead of causing overlapping proxy reconfiguration. The newest routing data wins when Coreflow sends another update while a previous routing task is still pending or running. + +## Usage + +CoreTraffic is normally started by the platform as a Docker service. For direct use: + +```ts +import { CoreTraffic } from 'coretraffic'; + +const coreTraffic = new CoreTraffic(); +await coreTraffic.start(); + +process.on('SIGTERM', async () => { + await coreTraffic.stop(); +}); +``` + +Repository scripts: + +```sh pnpm install -``` - -Build TypeScript: - -```bash -pnpm run build -``` - -Run tests: - -```bash +pnpm build +pnpm start pnpm test +pnpm run build:docker ``` -Check outdated dependencies: +## Important Files -```bash -pnpm outdated -``` +| Path | Purpose | +| --- | --- | +| `ts/index.ts` | CLI startup wrapper exporting `CoreTraffic`, `runCli`, and `stop`. | +| `ts/coretraffic.classes.coretraffic.ts` | Main lifecycle and SmartProxy instance. | +| `ts/coretraffic.classes.coreflowconnector.ts` | TypedSocket client to Coreflow and `updateRouting` handler. | +| `ts/coretraffic.classes.taskmanager.ts` | Buffered route update task and SmartProxy route generation. | -## Important Dependencies +## Operational Notes -- `@push.rocks/smartproxy`: route-based proxy engine used for redirects, TLS termination, and forwarding. -- `@api.global/typedsocket`: Coreflow connection transport. -- `@api.global/typedrequest`: typed RPC handler registration. -- `@serve.zone/interfaces`: typed Coreflow/CoreTraffic routing request contract. -- `@push.rocks/taskbuffer`: buffered routing update execution. +- Coreflow URL is currently hardcoded as `http://coreflow:3000` in the connector. +- CoreTraffic does not issue certificates; it uses the key/certificate material supplied by Coreflow. +- CoreTraffic replaces the full managed route set on every update. +- If Coreflow cannot find a connection tagged `coretraffic`, routing updates cannot be delivered. ## License and Legal Information