# JavaScript Core Systems - RPC Server Architecture

## Overview
JavaScript parsing and transformation use long-running Node.js RPC servers via Unix sockets to avoid spawning 1000+ Node processes during builds.

## JS Parser - RPC Server

### Components
- `Js_Parser.php` - PHP client, manages parser server lifecycle
- `js-parser-server.js` - Node.js RPC server, processes batch parse requests
- `js-parser.js` - Legacy single-file parser (kept for compatibility)

### Server Lifecycle
1. **Lazy start:** Server spawns on first JS file parse during manifest build
2. **Startup:** Checks for stale socket, force-kills if found, starts fresh server
3. **Wait:** Polls socket with ping (50ms intervals, 10s max), fatal error if timeout
4. **Usage:** All JS parsing during build goes through RPC (batched when possible)
5. **Shutdown:** Graceful shutdown on manifest build completion (registered shutdown handler)

### Socket
- **Path:** `storage/rsx-tmp/js-parser-server.sock`
- **Protocol:** Line-delimited JSON over Unix domain socket

### RPC Methods
- `ping` → `"pong"` - Health check
- `parse` → `{file: result, ...}` - Batch parse multiple files
- `shutdown` → Graceful server termination

### PHP API
```php
Js_Parser::start_rpc_server();        // Lazy init, auto-called
Js_Parser::stop_rpc_server($force);   // Clean shutdown
Js_Parser::parse_via_rpc($files);     // Batch parse (future)
```

## JS Transformer (Babel) - RPC Server

### Components
- `Js_Transformer.php` - PHP client, manages transformer server lifecycle
- `js-transformer-server.js` - Node.js RPC server, processes batch Babel transformations
- `js-transformer.js` - Legacy single-file transformer (kept for compatibility)

### Server Lifecycle
1. **Lazy start:** Server spawns on first JS transformation during bundle compilation
2. **Startup:** Checks for stale socket, force-kills if found, starts fresh server
3. **Wait:** Polls socket with ping (50ms intervals, 10s max), fatal error if timeout
4. **Usage:** All JS transformations during bundle builds go through RPC
5. **Shutdown:** Graceful shutdown when bundle compilation completes (registered shutdown handler)

### Socket
- **Path:** `storage/rsx-tmp/js-transformer-server.sock`
- **Protocol:** Line-delimited JSON over Unix domain socket

### RPC Methods
- `ping` → `"pong"` - Health check
- `transform` → `{file: {status, result, hash}, ...}` - Batch transform multiple files
- `shutdown` → Graceful server termination

### PHP API
```php
Js_Transformer::start_rpc_server();        // Lazy init, auto-called
Js_Transformer::stop_rpc_server($force);   // Clean shutdown
Js_Transformer::_transform_via_rpc(...);   // Internal RPC transformation
```

### Transformation Details
- Preprocesses `@decorator` on standalone functions
- Applies Babel transformations: decorators, class properties, optional chaining, nullish coalescing
- Prefixes generated helper functions with file hash to prevent namespace collisions
- Uses target presets: `modern`, `es6`, `es5`
- Generates inline source maps for debugging

## Common RPC Pattern

### Force Parameter
`stop_rpc_server($force = false)`:
- `false` (default): Send shutdown command, return immediately
- `true`: Send shutdown + wait + SIGTERM if needed (used for stale server cleanup)

### Cache Integration
Cache checked before RPC call - only uncached files sent to server for processing.

### Error Handling
Server failure → fatal error (no fallback). Server must start or build/compilation fails.

### Performance Impact
**Before RPC:** N Node.js process spawns (where N = number of files needing processing)
**After RPC:** Single persistent Node.js process per server type (~1-2s startup overhead)

## Future: Other RPC Servers
This pattern is reusable for other expensive Node operations. See implementation guide in project summary.