# ThreadForge

A multi-threaded Node.js service runtime framework. Deploy multiple services on the same machine, intelligently distributed across available CPU cores, with built-in IPC messaging, metrics, and lifecycle management.

## Why ThreadForge?

Node.js runs on a single thread. Modern servers have 16, 32, 64+ cores. ThreadForge bridges that gap by giving you a declarative way to run multiple services across all available cores — with zero-overhead inter-service communication via IPC instead of HTTP.

**Key features:**

- **Declarative service config** — define services, ports, thread allocation, and topology in one file
- **Smart thread allocation** — auto-distributes cores by weight, or set fixed counts
- **3-tier IPC resolution** — colocated (direct call) → Unix Domain Socket → HTTP fallback
- **Colocation groups** — pack lightweight services into a shared process for zero-overhead calls
- **TC39 decorators** — `@Route`, `@Expose`, `@Emit`, `@On`, `@Validate` and more
- **Plugin system** — Redis, PostgreSQL, S3, CORS, Cron, Realtime — with custom plugin support
- **Auto-restart** — crashed workers are automatically replaced
- **Runtime scaling** — scale services up/down without restarting
- **RequestContext propagation** — correlation IDs, auth, deadlines, and baggage across services
- **Built-in metrics** — Prometheus-compatible endpoint with HTTP, RPC, and event loop lag metrics
- **Multi-machine deployment** — grow from one machine to a full cluster with `forge.deploy.js`

## Quick Start

### Option 1: Install from npm (Recommended)

```bash
# Create and scaffold a new project
mkdir my-app && cd my-app
npm init -y
npm install threadforge
npx forge init . --source npm
npm install

# Start in development mode (hot reload)
npm run dev

# Start in production mode
npm run start
```

`forge dev` / `forge start` now auto-start ForgeProxy by default and generate local route manifests under `.threadforge/routes`.
Use `--no-proxy` to bypass proxy orchestration (for example, when ForgeProxy is not installed locally):

```bash
npx forge dev --no-proxy
npx forge start --no-proxy
```

### Option 2: Local Development (ThreadForge contributors only)

```bash
# Clone and link ThreadForge locally
git clone https://github.com/ChrisBland/threadforge.git
cd threadforge
npm install
npm link

# Create your project
mkdir my-app && cd my-app
npm link threadforge
forge init . --source local
npm install

# Start
npm run dev
```

If `forgeproxy` is installed outside your `PATH`, set `FORGEPROXY_BIN`:

```bash
FORGEPROXY_BIN=/absolute/path/to/forgeproxy npm run dev
```

`forge init` is backend-only by default. Add static frontend scaffolding with `npx forge scaffold frontend` (or `npx forge init . --with-frontend`), or generate Vite + React with `npx forge scaffold frontend --react` (or `npx forge init . --with-react`).

Create `forge.config.js`:

```javascript
import { defineServices, ServiceType } from 'threadforge';

export default defineServices({
  api: {
    entry: './services/api.js',
    type: ServiceType.EDGE,
    port: 3000,
    threads: 'auto',
    connects: ['users'],
  },

  users: {
    entry: './services/users.js',
    type: ServiceType.INTERNAL,
  },
});
```

Create `services/api.js`:

```javascript
import { HttpMethod, Service, Route } from 'threadforge';

export default class ApiService extends Service {
  @Route(HttpMethod.GET, '/users/:id')
  async getUser(body, params) {
    return await this.users.getUser(params.id);
  }
}
```

Create `services/users.js`:

```javascript
import { Service, Expose } from 'threadforge';

export default class UsersService extends Service {
  async onStart(ctx) {
    this.store = new Map([['1', { id: '1', name: 'Alice' }]]);
  }

  @Expose()
  async getUser(id) {
    return this.store.get(String(id)) ?? null;
  }
}
```

```bash
npm run start
# curl http://localhost:3000/users/1
# → {"id":"1","name":"Alice"}
```

With proxy orchestration enabled (default), you can also hit the local ForgeProxy ingress (typically `http://127.0.0.1:8080` when free).

## Platform Mode Quick Flow

For multi-site projects (multiple apps/domains with per-app services/frontends):

```bash
mkdir platform-app && cd platform-app
npm init -y
npm install threadforge
npx forge platform init
npx forge platform add sitea
npx forge platform add siteb

# then edit forge.platform.js:
# - add platform.apps.<appId> with domains/services/frontend
# - add top-level '<appId>-api' service entries with unique ports
# - register frontendPlugins (for example: viteFrontend())
# - create each frontend project (for example: apps/sitea/web and apps/siteb/web)

# install frontend deps for each site before build
# (example)
# cd apps/sitea/web && npm install
# cd ../../siteb/web && npm install
# cd ../../../

npx forge build
npx forge platform generate
npx forge platform start
```

`forge platform start` auto-manages ForgeProxy by default. If ForgeProxy is unavailable locally, use:

```bash
npx forge platform start --no-proxy
```

See:
- `docs/guides/plugins.md` for frontend plugin config (`viteFrontend`)
- `docs/reference/configuration.md` for `definePlatform()` schema
- `docs/reference/cli.md` for all `forge platform` subcommands
- `examples/platform-two-app-react-date-time/README.md` for a runnable two-site date/time + React example
- `examples/platform-kitchen-sink/README.md` for shared auth/users + event-driven multi-site example
- `examples/threads-overprovision/README.md` for graceful handling when requested threads exceed host CPU capacity

## Documentation

Full documentation is in the [`docs/`](./docs/) directory:

- [**Getting Started**](./docs/getting-started.md) — Install, create your first service, and run it
- [**Architecture**](./docs/architecture.md) — Process model, communication layers, request lifecycle
- **Guides:**
  - [Single-App React Date/Time Quickstart](./docs/guides/single-app-react-date-time.md) — One app with `/time`, `/date`, and a React frontend
  - [Services](./docs/guides/services.md) — Types, lifecycle, colocation, plain JS fallback
  - [IPC & Communication](./docs/guides/ipc.md) — Proxy clients, events, interceptors
  - [Plugins](./docs/guides/plugins.md) — Redis, PostgreSQL, S3, CORS, Cron, Realtime
  - [Platform Two-App React Quickstart](./docs/guides/platform-two-app-react.md) — Multi-site apps with per-site API + frontend
  - [Deployment](./docs/guides/deployment.md) — Single machine to multi-machine scaling
- **Reference:**
  - [Configuration](./docs/reference/configuration.md) — All `forge.config.js` options
  - [Decorators](./docs/reference/decorators.md) — Full decorator API
  - [CLI](./docs/reference/cli.md) — Commands, options, metrics endpoints
  - [API](./docs/reference/api.md) — All public exports
- [**ForgeProxy**](./docs/architecture.md#three-layer-production-architecture) — Rust gateway architecture and ingress role

## License

MIT