@rip-lang/server 0.5.0

package/README.md

@@ -0,0 +1,336 @@
+<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/rip.svg" style="width:50px" /> <br>
+
+# Rip Server - @rip-lang/server
+
+> **Pure Rip application server — multi-worker, hot reload, HTTPS, mDNS**
+
+## Overview
+
+`@rip-lang/server` is a production-grade application server written entirely in Rip. It provides multi-worker process management, hot module reloading, automatic HTTPS, and mDNS service discovery — all in a single ~1,100 line file.
+
+- **`server.rip`** (~1,082 lines) — Complete server: CLI, workers, load balancing, TLS, mDNS
+
+**Core Philosophy**: Application servers should be simple, fast, and reliable. No complex configuration files. No dependency on external process managers. Just run your app.
+
+### Key Features
+
+- **Multi-Worker Architecture** — Automatic worker spawning based on CPU cores
+- **Hot Module Reloading** — File-watch based reloading in development
+- **Rolling Restarts** — Zero-downtime deployments
+- **Automatic HTTPS** — TLS with mkcert or self-signed certificates
+- **mDNS Discovery** — `.local` hostname advertisement
+- **Request Queue** — Built-in request buffering and load balancing
+- **CLI Interface** — Simple command-line operation
+
+> **See Also**: For the API framework, see [@rip-lang/api](../api/README.md).
+
+## Quick Start
+
+### Installation
+
+```bash
+# Local (per-project)
+bun add @rip-lang/server
+
+# Global (use rip-server from anywhere)
+bun add -g rip-lang @rip-lang/server
+```
+
+### Running Your App
+
+```bash
+# Basic usage (HTTPS on port 443 or fallback)
+rip-server ./app.rip
+
+# HTTP only mode
+rip-server http ./app.rip
+
+# With mDNS alias
+rip-server ./app.rip@myapp
+```
+
+### Example App
+
+Create `app.rip`:
+
+```coffee
+import { get, post, read, startHandler } from '@rip-lang/api'
+
+get '/', ->
+  'Hello from Rip Server!'
+
+get '/json', ->
+  { message: 'It works!', timestamp: Date.now() }
+
+get '/users/:id', ->
+  id = read 'id', 'id!'
+  { user: { id, name: "User #{id}" } }
+
+# Export the handler for rip-server
+export default startHandler()
+```
+
+Run it:
+
+```bash
+rip-server http app.rip
+```
+
+Test it:
+
+```bash
+curl http://localhost/
+# Hello from Rip Server!
+
+curl http://localhost/json
+# {"message":"It works!","timestamp":1234567890}
+
+curl http://localhost/users/42
+# {"user":{"id":42,"name":"User 42"}}
+
+curl http://localhost/status
+# {"status":"healthy","app":"myapp","workers":5,"ports":{"http":80}}
+```
+
+## CLI Reference
+
+### Basic Syntax
+
+```bash
+rip-server [flags] <app-path>[@alias1,alias2,...]
+```
+
+### Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `http` | HTTP-only mode (no HTTPS) | HTTPS enabled |
+| `https` | HTTPS mode (explicit) | Auto |
+| `http:<port>` | Set HTTP port | 80 or 5700 |
+| `https:<port>` | Set HTTPS port | 443 or 5700 |
+| `w:<n>` | Worker count (`auto`, `half`, `2x`, `3x`, or number) | `half` of cores |
+| `r:<policy>` | Restart policy (e.g., `1000,3600s,10r`) | `10000,3600s,10r` |
+| `--cert=<path>` | TLS certificate path | Auto-generated |
+| `--key=<path>` | TLS private key path | Auto-generated |
+| `--auto-tls` | Use mkcert for TLS | Fallback to self-signed |
+| `--hsts` | Enable HSTS headers | Disabled |
+| `--no-redirect-http` | Don't redirect HTTP to HTTPS | Redirects enabled |
+| `--reload=<mode>` | Reload mode: `none`, `process`, `module` | `process` |
+| `--json-logging` | Output JSON access logs | Human-readable |
+| `--no-access-log` | Disable access logging | Enabled |
+
+### Subcommands
+
+```bash
+# Stop running server
+rip-server stop
+
+# List registered hosts
+rip-server list
+```
+
+### Examples
+
+```bash
+# Development: HTTP on any available port
+rip-server http app.rip
+
+# Development: HTTPS with mkcert
+rip-server --auto-tls app.rip
+
+# Production: 8 workers, HTTPS
+rip-server w:8 https app.rip
+
+# Custom ports
+rip-server http:3000 app.rip
+
+# With mDNS aliases (accessible as myapp.local and api.local)
+rip-server app.rip@myapp,api
+
+# Restart after 5000 requests or 1 hour
+rip-server r:5000,3600s app.rip
+```
+
+## Architecture
+
+### Self-Spawning Design
+
+The server uses a single-file, self-spawning architecture:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Main Process                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
+│  │   Server    │  │   Manager   │  │  Control Socket │  │
+│  │ (HTTP/HTTPS)│  │  (Workers)  │  │   (Commands)    │  │
+│  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘  │
+└─────────┼────────────────┼──────────────────┼───────────┘
+          │                │                  │
+          ▼                ▼                  │
+    ┌──────────┐    ┌──────────────┐          │
+    │ Requests │    │ Spawn/Monitor│          │
+    └────┬─────┘    └──────┬───────┘          │
+         │                 │                  │
+         ▼                 ▼                  │
+┌─────────────────────────────────────────────│───┐
+│              Worker Processes               │   │
+│  ┌────────┐ ┌────────┐ ┌────────┐           │   │
+│  │Worker 0│ │Worker 1│ │Worker N│  ◄────────┘   │
+│  │(Unix)  │ │(Unix)  │ │(Unix)  │               │
+│  └────────┘ └────────┘ └────────┘               │
+└─────────────────────────────────────────────────┘
+```
+
+When `RIP_WORKER_MODE=1` is set, the same `server.rip` file runs as a worker instead of the main server.
+
+### Request Flow
+
+1. **Main Process** receives HTTP/HTTPS request
+2. **Server** selects available worker from pool
+3. **Request** forwarded via Unix socket
+4. **Worker** processes request, returns response
+5. **Server** forwards response to client
+
+### Hot Reloading
+
+Two modes available:
+
+- **`process` mode** (default): File changes trigger rolling restart of all workers
+- **`module` mode**: Each worker reloads the app module on file change (faster, but uses more memory)
+
+### Worker Lifecycle
+
+Workers are recycled based on configurable limits:
+
+- **maxRequests**: Restart after N requests (default: 10,000)
+- **maxSeconds**: Restart after N seconds (default: 3,600)
+- **maxReloads**: Maximum hot reloads before restart (default: 10)
+
+## Built-in Endpoints
+
+The server provides these endpoints automatically:
+
+| Endpoint | Description |
+|----------|-------------|
+| `/status` | Health check with worker count and uptime |
+| `/server` | Simple "ok" response for load balancer probes |
+
+## TLS Certificates
+
+### Automatic Certificate Generation
+
+When HTTPS is enabled without explicit certificates, the server will:
+
+1. Try **mkcert** (if installed and `--auto-tls` flag used)
+2. Fall back to **self-signed** certificate via OpenSSL
+
+Certificates are stored in `~/.rip/certs/`.
+
+### Custom Certificates
+
+```bash
+rip-server --cert=/path/to/cert.pem --key=/path/to/key.pem app.rip
+```
+
+## mDNS Service Discovery
+
+The server automatically advertises itself via mDNS (Bonjour/Zeroconf):
+
+```bash
+# App accessible at myapp.local
+rip-server app.rip@myapp
+
+# Multiple aliases
+rip-server app.rip@myapp,api,backend
+```
+
+Requires `dns-sd` (available on macOS by default).
+
+## App Requirements
+
+Your app must export a fetch handler. Two patterns are supported:
+
+### Pattern 1: Export `startHandler()` (Recommended)
+
+```coffee
+import { get, startHandler } from '@rip-lang/api'
+
+get '/', -> 'Hello!'
+
+export default startHandler()
+```
+
+### Pattern 2: Export fetch function directly
+
+```coffee
+export default (req) ->
+  new Response('Hello!')
+```
+
+### Pattern 3: Export object with fetch method
+
+```coffee
+export default
+  fetch: (req) -> new Response('Hello!')
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `RIP_WORKER_MODE` | Set by server when spawning workers |
+| `RIP_DEBUG` | Enable debug logging |
+| `RIP_MAX_REQUESTS` | Default max requests per worker |
+| `RIP_MAX_SECONDS` | Default max seconds per worker |
+| `RIP_MAX_RELOADS` | Default max reloads per worker |
+| `RIP_MAX_QUEUE` | Maximum request queue size |
+| `RIP_QUEUE_TIMEOUT_MS` | Queue timeout in milliseconds |
+| `RIP_RELOAD` | Reload mode override |
+
+## Dashboard
+
+The server includes a built-in dashboard accessible at `http://rip.local/` (when mDNS is active). The dashboard shows server status, worker count, and registered hosts.
+
+## Troubleshooting
+
+**Port 80 requires sudo**: Use `http:3000` or another high port, or run with sudo.
+
+**mDNS not working**: Ensure `dns-sd` is available (built into macOS). On Linux, install Avahi.
+
+**Workers keep restarting**: Check `RIP_DEBUG=1` for import errors in your app.
+
+## Comparison with Other Servers
+
+| Feature | rip-server | PM2 | Nginx |
+|---------|------------|-----|-------|
+| Pure Rip | ✅ | ❌ | ❌ |
+| Single File | ✅ (~1,076 lines) | ❌ | ❌ |
+| Hot Reload | ✅ | ✅ | ❌ |
+| Multi-Worker | ✅ | ✅ | ✅ |
+| Auto HTTPS | ✅ | ❌ | ❌ |
+| mDNS | ✅ | ❌ | ❌ |
+| Zero Config | ✅ | ❌ | ❌ |
+| Built-in LB | ✅ | ❌ | ✅ |
+
+## TODO
+
+> *Planned improvements for future releases:*
+
+- [ ] "Try it Now" section with clone-and-run example
+- [ ] Dashboard screenshots and feature description
+- [ ] Performance benchmarks (req/s, latency)
+- [ ] Scaling guidelines
+- [ ] More troubleshooting scenarios
+- [ ] Static file serving
+- [ ] Rate limiting
+- [ ] Graceful shutdown improvements
+
+## License
+
+MIT
+
+## Links
+
+- [Rip Language](https://github.com/shreeve/rip-lang)
+- [@rip-lang/api](../api/README.md)
+- [Report Issues](https://github.com/shreeve/rip-lang/issues)

package/bin/rip-server

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const serverRip = join(__dirname, '..', 'server.rip');
+const args = process.argv.slice(2).join(' ');
+
+try {
+  execSync(`rip ${serverRip} ${args}`, { stdio: 'inherit' });
+} catch (error) {
+  process.exit(error.status || 1);
+}