coretraffic/readme.md

# CoreTraffic

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.

## Runtime Model

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 internal server at http://coreflow:3000
  -> TypedSocket updateRouting
      -> CoreTraffic CoreflowConnector
          -> buffered setupRouting task
              -> SmartProxy.updateRoutes(...)
```

At startup CoreTraffic:

- 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.

## Ports and Routes

CoreTraffic creates two route classes inside SmartProxy:

| SmartProxy port | Route | Purpose |
| --- | --- | --- |
| `7999` | `http-to-https-redirect` | Redirects HTTP traffic to `https://{domain}{path}` with status `301`. |
| `8000` | `https-<hostname>` | Terminates TLS and forwards traffic to the destination IP/port pairs from Coreflow. |

In the default Coreflow deployment, Docker maps host port `80` to CoreTraffic's `7999` and host port `443` to `8000`.

## Routing Input

CoreTraffic consumes reverse proxy configs from `@serve.zone/interfaces`, which extends the `@tsclass/tsclass` network shape:

```ts
const reverseConfig = {
  hostName: 'app.example.com',
  destinationIps: ['10.0.0.10'],
  destinationPorts: [3000],
  privateKey: '-----BEGIN PRIVATE KEY-----...',
  publicKey: '-----BEGIN CERTIFICATE-----...',
  authentication: {
    type: 'Basic',
    user: 'admin',
    pass: 'secret',
  },
};
```

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.

Every managed route receives a response header named `servezone_coretraffic_version` with the running package version when available.

## Buffered Updates

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
pnpm build
pnpm start
pnpm test
pnpm run build:docker
```

## Important Files

| 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. |

## Operational Notes

- 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

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH  
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.