CoreTraffic is the serve.zone ingress service. In its default Coreflow mode 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. In standalone mode it exposes an ht-docker-smartproxy-compatible admin API for orchestrators such as Onebox.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit 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/ account to submit Pull Requests directly.

Runtime Modes

CORETRAFFIC_MODE selects the runtime mode:

Mode	Purpose
`coreflow`	Default. Connects to Coreflow and receives typed routing updates.
`standalone`	Starts SmartProxy from `SMARTPROXY_CONFIG` and exposes the SmartProxy admin API.

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

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.

Coreflow Ports and Routes

In Coreflow mode, 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. This route also enables QUIC/HTTP/3 with `transport: 'all'` and advertises Alt-Svc on host port `443`.

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:

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 Coreflow-mode use:

import { CoreTraffic } from 'coretraffic';

const coreTraffic = new CoreTraffic();
await coreTraffic.start();

process.on('SIGTERM', async () => {
  await coreTraffic.stop();
});

Repository scripts:

pnpm install
pnpm build
pnpm start
pnpm test
pnpm run build:docker

Standalone Mode

Standalone mode is compatible with the ht-docker-smartproxy daemon contract used by Onebox:

CORETRAFFIC_MODE=standalone node cli.js

Environment variables:

CORETRAFFIC_MODE: set to standalone to enable the standalone daemon path.
SMARTPROXY_CONFIG: config path, default /etc/smartproxy/config.json.
SMARTPROXY_ADMIN_HOST: admin bind host, default 127.0.0.1.
SMARTPROXY_ADMIN_PORT: admin bind port, default 3000.
SMARTPROXY_ADMIN_TOKEN: optional bearer token for loopback admin binds; required when SMARTPROXY_ADMIN_HOST is not loopback. When set, it protects all admin endpoints except unauthenticated health probes (GET /health and GET /ready).

Admin API:

GET /health: health status.
GET /ready: readiness status.
GET /routes: current raw routes and active routes.
PUT /routes or POST /routes: replace routes with either an array or { "routes": [...] }.
POST /reload: reload config from SMARTPROXY_CONFIG and restart SmartProxy.
POST /security-policy: update global SmartProxy security policy.
GET /statistics: SmartProxy runtime statistics.
GET /listening-ports: currently listening proxy ports.

The config is regular ISmartProxyOptions JSON with one standalone extension: httpToHttpsRedirect.

{
  "httpToHttpsRedirect": {
    "enabled": true,
    "httpPort": 80,
    "httpsPort": 443,
    "statusCode": 301
  },
  "routes": [
    {
      "name": "app-example-com",
      "match": {
        "ports": 443,
        "domains": "app.example.com",
        "protocol": "http"
      },
      "action": {
        "type": "forward",
        "targets": [{ "host": "app", "port": 3000 }],
        "tls": {
          "mode": "terminate",
          "certificate": {
            "key": "-----BEGIN PRIVATE KEY-----\\n...",
            "cert": "-----BEGIN CERTIFICATE-----\\n..."
          }
        }
      }
    }
  ]
}

Check commands:

CORETRAFFIC_MODE=standalone node cli.js --check
node cli.js --check-admin-security

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.
`ts/coretraffic.classes.standaloneservice.ts`	Standalone SmartProxy config loader and admin API.

Operational Notes

Coreflow URL is currently hardcoded as http://coreflow:3000 in the connector.
Standalone mode starts with empty routes when SMARTPROXY_CONFIG does not exist.
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 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.

readme.md

CoreTraffic