@rip-lang/server 1.1.7 → 1.1.9

package/README.md

@@ -311,7 +311,12 @@ The server uses a single-file, self-spawning architecture:
 └─────────────────────────────────────────────────┘
 ```
 
-When `RIP_WORKER_MODE=1` is set, the same `server.rip` file runs as a worker instead of the main server.
+When `RIP_SETUP_MODE=1` is set, the same file runs the one-time setup phase. When `RIP_WORKER_MODE=1` is set, it runs as a worker.
+
+### Startup Lifecycle
+
+1. **Setup** — If `setup.rip` exists next to the entry file, it runs once in a temporary process before any workers spawn. Use this for database migrations, table creation, and seeding.
+2. **Workers** — N worker processes are spawned, each loading the entry file and serving requests.
 
 ### Request Flow
 
@@ -323,12 +328,10 @@ When `RIP_WORKER_MODE=1` is set, the same `server.rip` file runs as a worker ins
 
 ### Hot Reloading
 
-In development mode, the server watches for file changes:
-
-- **Default**: Only the entry file is watched
-- **With `-w`**: All matching files in the app directory are watched
+Two layers of hot reload work together in development:
 
-When a change is detected, a rolling restart of all workers is triggered — zero downtime.
+- **API changes** (`-w` flag) — The Manager watches for `.rip` file changes in the API directory and triggers rolling worker restarts (zero downtime, server-side).
+- **UI changes** (`watch: true` in `ripUI`) — Workers register their app's component directories with the Manager via the control socket. The Manager watches those directories and broadcasts SSE reload events to connected browsers (client-side). SSE connections are held by the long-lived Server process, not by workers.
 
 Use `--static` in production to disable hot reload entirely.
 
@@ -409,6 +412,24 @@ export default
   fetch: (req) -> new Response('Hello!')
 ```
 
+## One-Time Setup
+
+If a `setup.rip` file exists next to your entry file, rip-server runs it
+automatically **once** before spawning any workers. This is ideal for database
+migrations, table creation, and seeding.
+
+```coffee
+# setup.rip — runs once before workers start
+export setup = ->
+  await createTables()
+  await seedData()
+  console.log 'Database ready'
+```
+
+The setup function can export as `setup` or `default`. If the file doesn't
+exist, the setup phase is skipped entirely (no overhead). If setup fails,
+the server exits immediately.
+
 ## Environment Variables
 
 Most settings are configured via CLI flags, but environment variables provide an alternative for containers, CI/CD, or system-wide defaults.
@@ -501,14 +522,16 @@ This gives you:
 
 When running with `-w`, two layers of hot reload work together:
 
-1. **rip-server file watching** (`-w` flag) — watches for `.rip` file changes
-   and triggers rolling worker restarts (server-side reload)
-2. **ripUI SSE watching** (`watch: true`) — watches the `pages/` and `includes`
-   directories and notifies connected browsers via SSE (client-side reload)
+1. **API hot reload** (`-w` flag) — The Manager watches for `.rip` file changes
+   in the API directory and triggers rolling worker restarts (server-side).
+2. **UI hot reload** (`watch: true`) — Workers register their component
+   directories with the Manager via the control socket. The Manager watches
+   those directories and tells the Server to broadcast SSE reload events to
+   connected browsers (client-side).
 
-For development, the SSE hot-reload is usually sufficient — it recompiles
-components in the browser without restarting workers. The `-w` flag is useful
-when server-side code changes (routes, middleware, etc.).
+SSE connections are held by the long-lived Server process, not by recyclable
+workers, ensuring stable hot-reload connections. Each app prefix gets its own
+SSE pool for multi-app isolation.
 
 ## Comparison with Other Servers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rip-lang/server",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "Pure Rip application server — multi-worker, hot reload, HTTPS, mDNS",
   "type": "module",
   "main": "server.rip",

package/server.rip

@@ -352,6 +352,18 @@ parseFlags = (argv) ->
 # Worker Mode
 # ==============================================================================
 
+runSetup = ->
+  setupFile = process.env.RIP_SETUP_FILE
+  try
+    mod = import!(setupFile)
+    await Promise.resolve()
+    fn = mod?.setup or mod?.default
+    if typeof fn is 'function'
+      await fn()
+  catch e
+    console.error "rip-server: setup failed:", e
+    process.exit(1)
+
 runWorker = ->
   workerId = parseInt(process.env.WORKER_ID or '0')
   maxRequests = parseInt(process.env.MAX_REQUESTS or '10000')
@@ -485,14 +497,32 @@ class Manager
     @nextWorkerId = -1
     @retiringIds = new Set()
     @currentVersion = 1
-    @onFileChange = null
-    @_broadcastTimer = null
+    @server = null
+    @appWatchers = new Map()
 
     process.on 'SIGTERM', => @shutdown!
     process.on 'SIGINT', => @shutdown!
 
   start: ->
     @stop!
+
+    # Run one-time setup if setup.rip exists next to the entry file
+    setupFile = join(dirname(@flags.appEntry), 'setup.rip')
+    if existsSync(setupFile)
+      setupEnv = Object.assign {}, process.env,
+        RIP_SETUP_MODE: '1'
+        RIP_SETUP_FILE: setupFile
+      proc = Bun.spawn ['rip', import.meta.path],
+        stdout: 'inherit'
+        stderr: 'inherit'
+        stdin: 'ignore'
+        cwd: process.cwd()
+        env: setupEnv
+      code = await proc.exited
+      if code isnt 0
+        console.error "rip-server: setup exited with code #{code}"
+        process.exit(1)
+
     @workers = []
     for i in [0...@flags.workers]
       w = @spawnWorker!(@currentVersion)
@@ -534,13 +564,6 @@ class Manager
               utimesSync(entryFile, now, now)
             catch
               null
-            # Debounced SSE broadcast to connected clients
-            if @onFileChange
-              clearTimeout(@_broadcastTimer) if @_broadcastTimer
-              @_broadcastTimer = setTimeout =>
-                @_broadcastTimer = null
-                @onFileChange()
-              , debounceMs
         catch e
           console.warn "rip-server: directory watch failed: #{e.message}"
 
@@ -550,6 +573,25 @@ class Manager
       try unlinkSync(w.socketPath) catch then null
     @workers = []
 
+  watchDirs: (prefix, dirs) ->
+    return if @appWatchers.has(prefix)
+    timer = null
+    watchers = []
+    broadcast = =>
+      clearTimeout(timer) if timer
+      timer = setTimeout =>
+        timer = null
+        @server?.broadcastChange(prefix)
+      , 250
+    for dir in dirs
+      try
+        w = watch dir, { recursive: true }, (event, filename) ->
+          broadcast() if filename?.endsWith('.rip')
+        watchers.push(w)
+      catch e
+        console.warn "rip-server: watch failed for #{dir}: #{e.message}"
+    @appWatchers.set prefix, { watchers, timer }
+
   spawnWorker: (version) ->
     workerId = ++@nextWorkerId
     socketPath = getWorkerSocketPath(@flags.socketPrefix, workerId)
@@ -683,7 +725,8 @@ class Server
     @httpsActive = false
     @hostRegistry = new Set(['localhost', '127.0.0.1', 'rip.local'])
     @mdnsProcesses = new Map()
-    @sseClients = new Set()
+    @watchGroups = new Map()
+    @manager = null
     try
       pkg = JSON.parse(readFileSync(import.meta.dir + '/package.json', 'utf8'))
       @serverVersion = pkg.version
@@ -773,7 +816,12 @@ class Server
       return new Response Bun.file(import.meta.dir + '/server.html')
 
     return @status() if url.pathname is '/status'
-    return @watch() if url.pathname is '/watch'
+
+    # SSE hot-reload: intercept /{prefix}/watch for registered watch groups
+    path = url.pathname
+    if path.endsWith('/watch')
+      watchPrefix = path.slice(0, -6)  # strip '/watch'
+      return @handleWatch(watchPrefix) if @watchGroups.has(watchPrefix)
 
     if url.pathname is '/server'
       headers = new Headers({ 'content-type': 'text/plain' })
@@ -818,31 +866,39 @@ class Server
     @maybeAddSecurityHeaders(headers)
     new Response(body, { headers })
 
-  watch: ->
+  registerWatch: (prefix) ->
+    return if @watchGroups.has(prefix)
+    @watchGroups.set prefix, { sseClients: new Set() }
+
+  handleWatch: (prefix) ->
+    group = @watchGroups.get(prefix)
+    return new Response('not-found', { status: 404 }) unless group
     encoder = new TextEncoder()
     client = null
     new Response new ReadableStream(
-      start: (controller) =>
+      start: (controller) ->
         send = (event) ->
           try controller.enqueue encoder.encode("event: #{event}\n\n")
           catch then null
         client = { send }
-        @sseClients.add(client)
+        group.sseClients.add(client)
         send('connected')
-      cancel: =>
-        @sseClients.delete(client) if client
+      cancel: ->
+        group.sseClients.delete(client) if client
     ),
       headers:
         'Content-Type': 'text/event-stream'
         'Cache-Control': 'no-cache'
         'Connection': 'keep-alive'
 
-  broadcastChange: ->
+  broadcastChange: (prefix) ->
+    group = @watchGroups.get(prefix)
+    return unless group
     dead = []
-    for client as @sseClients
+    for client as group.sseClients
       try client.send('reload')
       catch then dead.push(client)
-    @sseClients.delete(c) for c in dead
+    group.sseClients.delete(c) for c in dead
 
   getNextAvailableSocket: ->
     while @availableWorkers.length > 0
@@ -979,6 +1035,17 @@ class Server
         null
       return new Response(JSON.stringify({ ok: false }), { status: 400, headers: { 'content-type': 'application/json' } })
 
+    if req.method is 'POST' and url.pathname is '/watch'
+      try
+        j = req.json!
+        if j?.op is 'watch' and typeof j.prefix is 'string' and Array.isArray(j.dirs)
+          @registerWatch(j.prefix)
+          @manager?.watchDirs(j.prefix, j.dirs) if j.dirs.length > 0
+          return new Response(JSON.stringify({ ok: true }), { headers: { 'content-type': 'application/json' } })
+      catch
+        null
+      return new Response(JSON.stringify({ ok: false }), { status: 400, headers: { 'content-type': 'application/json' } })
+
     if url.pathname is '/registry' and req.method is 'GET'
       return new Response(JSON.stringify({ ok: true, hosts: Array.from(@hostRegistry.values()) }), { headers: { 'content-type': 'application/json' } })
 
@@ -1214,7 +1281,8 @@ main = ->
 
   svr = new Server(flags)
   mgr = new Manager(flags)
-  mgr.onFileChange = -> svr.broadcastChange()
+  svr.manager = mgr
+  mgr.server = svr
 
   cleanup = ->
     console.log 'rip-server: shutting down...'
@@ -1243,7 +1311,9 @@ main = ->
 # Entry Point
 # ==============================================================================
 
-if process.env.RIP_WORKER_MODE
+if process.env.RIP_SETUP_MODE
+  runSetup()
+else if process.env.RIP_WORKER_MODE
   runWorker()
 else
   main!