docs: refresh readme and legal info
This commit is contained in:
@@ -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-<hostname>` | 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user