@rip-lang/server 1.3.115 → 1.3.116

package/edge/config.rip

@@ -1,75 +1,607 @@
 # ==============================================================================
-# edge/config.rip — declarative multi-app configuration loader
+# edge/config.rip — legacy config.rip and Edgefile.rip loading/validation
 # ==============================================================================
 #
-# Loads config.rip from the app directory and registers apps in the registry.
-#
-# Example config.rip:
-#
-#   export default
-#     apps:
-#       main:
-#         entry: './index.rip'
-#         hosts: ['example.com', 'www.example.com']
-#         workers: 4
-#       api:
-#         entry: './api/index.rip'
-#         hosts: ['api.example.com']
-#         workers: 2
-#         maxQueue: 1024
-
-import { existsSync } from 'node:fs'
-import { join, dirname, resolve } from 'node:path'
+# config.rip remains the legacy app-registry config.
+# Edgefile.rip is the stricter edge config surface for the pure Bun edge work.
+# ==============================================================================
 
-export loadConfig = (configPath) ->
+import { existsSync, statSync } from 'node:fs'
+import { join, dirname, resolve, basename } from 'node:path'
+import { normalizeStreamUpstreams, normalizeStreams, parseHostPort } from '../streams/config.rip'
+
+EDGEFILE_NAME = 'Edgefile.rip'
+LEGACY_CONFIG_NAME = 'config.rip'
+
+isPlainObject = (value) ->
+  value? and typeof value is 'object' and not Array.isArray(value)
+
+toArray = (value) ->
+  if Array.isArray(value) then value else []
+
+pushError = (errors, code, path, message, hint = null) ->
+  errors.push({ code, path, message, hint })
+
+validationError = (label, errors) ->
+  primary = errors[0]
+  err = new Error(primary?.message or "#{label} is invalid")
+  err.code = 'RIP_CONFIG_INVALID'
+  err.validationErrors = errors
+  err.label = label
+  err
+
+export formatConfigErrors = (label, errors) ->
+  lines = ["rip-server: #{label} validation failed (#{errors.length} error#{if errors.length is 1 then '' else 's'})"]
+  for err in errors
+    line = "- [#{err.code}] #{err.path}: #{err.message}"
+    line += " Hint: #{err.hint}" if err.hint
+    lines.push(line)
+  lines.join('\n')
+
+moduleObject = (configPath, label) ->
   return null unless existsSync(configPath)
-  try
-    mod = import!(configPath)
-    await Promise.resolve()
-    config = mod?.default or mod
-    return null unless config and typeof config is 'object'
-    config
-  catch e
-    console.error "rip-server: failed to load config.rip:", e.message
-    null
+  mod = import!(configPath)
+  await Promise.resolve()
+  config = mod?.default or mod
+  if config?.then
+    throw validationError(label, [
+      {
+        code: 'E_CONFIG_ASYNC'
+        path: '$'
+        message: "#{label} must export a plain object, not a promise"
+        hint: "Export `default` as a synchronous object literal."
+      }
+    ])
+  unless isPlainObject(config)
+    throw validationError(label, [
+      {
+        code: 'E_CONFIG_TYPE'
+        path: '$'
+        message: "#{label} must export a plain object"
+        hint: "Use `export default { ... }`."
+      }
+    ])
+  config
 
-export normalizeAppConfig = (appId, appConfig, baseDir) ->
-  entry = if appConfig.entry
+normalizeHosts = (value, path, errors) ->
+  hosts = []
+  unless value?
+    return hosts
+  unless Array.isArray(value)
+    pushError(errors, 'E_HOSTS_TYPE', path, 'hosts must be an array of strings', "Use `hosts: ['example.com']`.")
+    return hosts
+  for host, idx in value
+    unless typeof host is 'string' and host.trim()
+      pushError(errors, 'E_HOST_TYPE', "#{path}[#{idx}]", 'host must be a non-empty string', "Use `'api.example.com'`, `'*.example.com'`, or `'*'`.")
+      continue
+    normalized = host.trim().toLowerCase()
+    if normalized.startsWith('*.')
+      base = normalized.slice(2)
+      labels = base.split('.').filter(Boolean)
+      if labels.length < 2
+        pushError(errors, 'E_HOST_WILDCARD_BASE', "#{path}[#{idx}]", 'wildcard hosts must have a base domain with at least two labels', "Use `'*.example.com'`, not `'*.com'`.")
+        continue
+    hosts.push(normalized)
+  hosts
+
+normalizeEnv = (value, path, errors) ->
+  return {} unless value?
+  unless isPlainObject(value)
+    pushError(errors, 'E_ENV_TYPE', path, 'env must be an object', "Use `env: { FOO: 'bar' }`.")
+    return {}
+  out = {}
+  for key, val of value
+    unless ['string', 'number', 'boolean'].includes(typeof val)
+      pushError(errors, 'E_ENV_VALUE', "#{path}.#{key}", 'env values must be strings, numbers, or booleans', "Convert the value to a string if needed.")
+      continue
+    out[key] = String(val)
+  out
+
+normalizePositiveInt = (value, fallback, path, errors, label) ->
+  return fallback unless value?
+  n = parseInt(String(value))
+  unless Number.isFinite(n) and n >= 0
+    fieldName = path.split('.').slice(-1)[0]
+    pushError(errors, 'E_NUMBER_TYPE', path, "#{label} must be a non-negative integer", "Set #{fieldName}: #{fallback} or another whole number.")
+    return fallback
+  n
+
+normalizeAppConfigInto = (appId, appConfig, baseDir, path, errors) ->
+  unless isPlainObject(appConfig)
+    pushError(errors, 'E_APP_TYPE', path, 'app config must be an object', "Use #{appId}: { entry: './index.rip' }.")
+    appConfig = {}
+  entry = if typeof appConfig.entry is 'string' and appConfig.entry.trim()
     if appConfig.entry.startsWith('/') then appConfig.entry else resolve(baseDir, appConfig.entry)
+  else if appConfig.entry?
+    pushError(errors, 'E_APP_ENTRY', "#{path}.entry", 'entry must be a string path', "Use `entry: './index.rip'`.")
+    null
   else
     null
-  hosts = appConfig.hosts or []
-  workers = appConfig.workers or null
-  maxQueue = appConfig.maxQueue or 512
-  queueTimeoutMs = appConfig.queueTimeoutMs or 30000
-  readTimeoutMs = appConfig.readTimeoutMs or 30000
-
   {
     id: appId
     entry
-    hosts
-    workers
-    maxQueue
-    queueTimeoutMs
-    readTimeoutMs
-    env: appConfig.env or {}
+    hosts: normalizeHosts(appConfig.hosts, "#{path}.hosts", errors)
+    workers: if appConfig.workers? then normalizePositiveInt(appConfig.workers, 0, "#{path}.workers", errors, 'workers') else null
+    maxQueue: normalizePositiveInt(appConfig.maxQueue, 512, "#{path}.maxQueue", errors, 'maxQueue')
+    queueTimeoutMs: normalizePositiveInt(appConfig.queueTimeoutMs, 30000, "#{path}.queueTimeoutMs", errors, 'queueTimeoutMs')
+    readTimeoutMs: normalizePositiveInt(appConfig.readTimeoutMs, 30000, "#{path}.readTimeoutMs", errors, 'readTimeoutMs')
+    env: do ->
+      env = normalizeEnv(appConfig.env, "#{path}.env", errors)
+      if typeof appConfig.root is 'string' and appConfig.root.trim()
+        env.APP_BASE_DIR = if appConfig.root.startsWith('/') then appConfig.root else resolve(baseDir, appConfig.root)
+      env
+  }
+
+normalizeTimeouts = (value, path, errors) ->
+  return {} unless value?
+  unless isPlainObject(value)
+    pushError(errors, 'E_TIMEOUTS_TYPE', path, 'timeouts must be an object', "Use `timeouts: { connectMs: 2000, readMs: 30000 }`.")
+    return {}
+  {
+    connectMs: normalizePositiveInt(value.connectMs, 2000, "#{path}.connectMs", errors, 'connectMs')
+    readMs: normalizePositiveInt(value.readMs, 30000, "#{path}.readMs", errors, 'readMs')
+  }
+
+normalizeVerifyPolicy = (value, path, errors) ->
+  return {
+    requireHealthyUpstreams: true
+    requireReadyApps: true
+    includeUnroutedManagedApps: true
+    minHealthyTargetsPerUpstream: 1
+  } unless value?
+  unless isPlainObject(value)
+    pushError(errors, 'E_VERIFY_TYPE', path, 'verify must be an object', "Use `verify: { requireHealthyUpstreams: true }`.")
+    return {
+      requireHealthyUpstreams: true
+      requireReadyApps: true
+      includeUnroutedManagedApps: true
+      minHealthyTargetsPerUpstream: 1
+    }
+  {
+    requireHealthyUpstreams: if value.requireHealthyUpstreams? then value.requireHealthyUpstreams is true else true
+    requireReadyApps: if value.requireReadyApps? then value.requireReadyApps is true else true
+    includeUnroutedManagedApps: if value.includeUnroutedManagedApps? then value.includeUnroutedManagedApps is true else true
+    minHealthyTargetsPerUpstream: Math.max(1, normalizePositiveInt(value.minHealthyTargetsPerUpstream, 1, "#{path}.minHealthyTargetsPerUpstream", errors, 'minHealthyTargetsPerUpstream'))
+  }
+
+normalizeEdgeSettings = (value, errors) ->
+  unless isPlainObject(value)
+    pushError(errors, 'E_EDGE_REQUIRED', 'edge', 'edge must be an object', "Use `edge: {}` or omit it to use defaults.")
+    value = {}
+  certPath = if typeof value.cert is 'string' and value.cert.trim() then resolve(process.cwd(), value.cert) else null
+  keyPath = if typeof value.key is 'string' and value.key.trim() then resolve(process.cwd(), value.key) else null
+  if (certPath and not keyPath) or (keyPath and not certPath)
+    pushError(errors, 'E_TLS_PAIR', 'edge', 'manual TLS requires both cert and key', "Provide both `edge.cert` and `edge.key`, or remove both and rely on ACME/manual defaults.")
+  acmeDomains = []
+  if value.acmeDomains?
+    unless Array.isArray(value.acmeDomains)
+      pushError(errors, 'E_ACME_DOMAINS', 'edge.acmeDomains', 'acmeDomains must be an array of exact hostnames', "Use `acmeDomains: ['example.com', 'www.example.com']`.")
+    else
+      for domain, idx in value.acmeDomains
+        unless typeof domain is 'string' and domain.trim()
+          pushError(errors, 'E_ACME_DOMAIN_VALUE', "edge.acmeDomains[#{idx}]", 'acme domain must be a non-empty string', "Use `'example.com'`.")
+          continue
+        if domain.includes('*')
+          pushError(errors, 'E_ACME_WILDCARD', "edge.acmeDomains[#{idx}]", 'ACME HTTP-01 cannot issue wildcard certificates', "Remove the wildcard domain or provide `edge.cert` and `edge.key` manually.")
+          continue
+        acmeDomains.push(domain.trim().toLowerCase())
+  {
+    acme: value.acme is true
+    acmeDomains
+    cert: certPath
+    key: keyPath
+    hsts: value.hsts is true
+    trustedProxies: normalizeHosts(value.trustedProxies, 'edge.trustedProxies', errors)
+    timeouts: normalizeTimeouts(value.timeouts, 'edge.timeouts', errors)
+    verify: normalizeVerifyPolicy(value.verify, 'edge.verify', errors)
+  }
+
+normalizeUpstreamConfig = (upstreamId, upstreamConfig, path, errors) ->
+  unless isPlainObject(upstreamConfig)
+    pushError(errors, 'E_UPSTREAM_TYPE', path, 'upstream config must be an object', "Use #{upstreamId}: { targets: ['http://127.0.0.1:3000'] }.")
+    upstreamConfig = {}
+  targets = []
+  unless Array.isArray(upstreamConfig.targets) and upstreamConfig.targets.length > 0
+    pushError(errors, 'E_UPSTREAM_TARGETS', "#{path}.targets", 'upstream must define at least one target URL', "Use `targets: ['http://127.0.0.1:3000']`.")
+  else
+    for target, idx in upstreamConfig.targets
+      unless typeof target is 'string' and /^https?:\/\//.test(target)
+        pushError(errors, 'E_UPSTREAM_TARGET', "#{path}.targets[#{idx}]", 'target must be an absolute http:// or https:// URL', "Use `'http://app.incusbr0:3000'`.")
+        continue
+      targets.push(target)
+  {
+    id: upstreamId
+    targets
+    healthCheck:
+      path: if typeof upstreamConfig.healthCheck?.path is 'string' and upstreamConfig.healthCheck.path.startsWith('/') then upstreamConfig.healthCheck.path else '/health'
+      intervalMs: normalizePositiveInt(upstreamConfig.healthCheck?.intervalMs, 5000, "#{path}.healthCheck.intervalMs", errors, 'healthCheck.intervalMs')
+      timeoutMs: normalizePositiveInt(upstreamConfig.healthCheck?.timeoutMs, 2000, "#{path}.healthCheck.timeoutMs", errors, 'healthCheck.timeoutMs')
+    retry:
+      attempts: normalizePositiveInt(upstreamConfig.retry?.attempts, 2, "#{path}.retry.attempts", errors, 'retry.attempts')
+      retryOn: if Array.isArray(upstreamConfig.retry?.retryOn) and upstreamConfig.retry.retryOn.length > 0 then upstreamConfig.retry.retryOn else [502, 503, 504]
+    timeouts: normalizeTimeouts(upstreamConfig.timeouts or upstreamConfig.timeout, "#{path}.timeouts", errors)
+  }
+
+normalizeRouteConfig = (routeConfig, idx, errors, knownUpstreams, knownApps) ->
+  path = "routes[#{idx}]"
+  unless isPlainObject(routeConfig)
+    pushError(errors, 'E_ROUTE_TYPE', path, 'route must be an object', "Use `{ path: '/api/*', upstream: 'app' }`.")
+    routeConfig = {}
+  actionKeys = ['upstream', 'app', 'static', 'redirect', 'headers'].filter((key) -> routeConfig[key]?)
+  if actionKeys.length isnt 1
+    pushError(errors, 'E_ROUTE_ACTION', path, 'route must define exactly one action: upstream, app, static, redirect, or headers', "Choose one action field per route.")
+  routePath = if typeof routeConfig.path is 'string' and routeConfig.path.startsWith('/') then routeConfig.path else null
+  pushError(errors, 'E_ROUTE_PATH', "#{path}.path", 'route path must be a string starting with /', "Use `path: '/api/*'`.") unless routePath
+  host = if routeConfig.host? then routeConfig.host else '*'
+  if typeof host is 'string' and host.startsWith('*.')
+    labels = host.slice(2).split('.').filter(Boolean)
+    pushError(errors, 'E_ROUTE_HOST_WILDCARD', "#{path}.host", 'wildcard route hosts must have a base domain with at least two labels', "Use `'*.example.com'`, not `'*.com'`.") if labels.length < 2
+  else if typeof host isnt 'string'
+    pushError(errors, 'E_ROUTE_HOST', "#{path}.host", 'route host must be a string', "Use `'api.example.com'` or `'*'`.")
+  if routeConfig.upstream? and not knownUpstreams.has(routeConfig.upstream)
+    pushError(errors, 'E_ROUTE_UPSTREAM_REF', "#{path}.upstream", "unknown upstream #{routeConfig.upstream}", 'Define the upstream under `upstreams` first.')
+  if routeConfig.app? and not knownApps.has(routeConfig.app)
+    pushError(errors, 'E_ROUTE_APP_REF', "#{path}.app", "unknown app #{routeConfig.app}", 'Define the app under `apps` first.')
+  if routeConfig.websocket is true and not routeConfig.upstream?
+    pushError(errors, 'E_ROUTE_WEBSOCKET', "#{path}.websocket", 'websocket routes currently require an upstream action', 'Set `upstream: ...` on the route or remove `websocket: true`.')
+  {
+    id:        routeConfig.id or "route-#{idx + 1}"
+    host:      if typeof host is 'string' then host.toLowerCase() else '*'
+    path:      routePath or '/'
+    methods:   if routeConfig.methods? then routeConfig.methods else '*'
+    priority:  normalizePositiveInt(routeConfig.priority, idx, "#{path}.priority", errors, 'priority')
+    upstream:  routeConfig.upstream or null
+    app:       routeConfig.app or null
+    static:    routeConfig.static or null
+    root:      routeConfig.root or null
+    spa:       routeConfig.spa is true
+    redirect:  routeConfig.redirect or null
+    headers:   routeConfig.headers or null
+    websocket: routeConfig.websocket is true
+    timeouts:  normalizeTimeouts(routeConfig.timeouts, "#{path}.timeouts", errors)
+  }
+
+normalizeSiteConfig = (host, siteConfig, idx, errors, knownUpstreams, knownApps) ->
+  path = "sites.#{host}"
+  unless isPlainObject(siteConfig)
+    pushError(errors, 'E_SITE_TYPE', path, 'site config must be an object', "Use `'api.example.com': { routes: [...] }`.")
+    siteConfig = {}
+  routes = []
+  if siteConfig.routes?
+    unless Array.isArray(siteConfig.routes)
+      pushError(errors, 'E_SITE_ROUTES', "#{path}.routes", 'site.routes must be an array', "Use `routes: [{ path: '/*', upstream: 'app' }]`.")
+    else
+      for routeConfig, routeIdx in siteConfig.routes
+        routes.push(normalizeRouteConfig(routeConfig, routeIdx, errors, knownUpstreams, knownApps))
+  {
+    host: host.toLowerCase()
+    timeouts: normalizeTimeouts(siteConfig.timeouts, "#{path}.timeouts", errors)
+    routes
   }
 
+topLevelKeys = new Set(['version', 'edge', 'hosts', 'upstreams', 'apps', 'streamUpstreams', 'streams'])
+
+VALID_REDIRECT_STATUSES = new Set([301, 302, 307, 308])
+
+normalizeServerRouteConfig = (routeConfig, idx, serverHost, serverRoot, baseDir, errors, knownUpstreams, knownApps) ->
+  path = "hosts.#{serverHost}.routes[#{idx}]"
+  unless isPlainObject(routeConfig)
+    pushError(errors, 'E_ROUTE_TYPE', path, 'route must be an object', "Use `{ path: '/*', static: '.' }`.")
+    routeConfig = {}
+  if routeConfig.host?
+    pushError(errors, 'E_SERVER_ROUTE_HOST', "#{path}.host", 'routes inside a server block must not specify host (inherited from server key)', "Remove the `host` field.")
+  actionKeys = ['upstream', 'app', 'static', 'redirect', 'headers'].filter((key) -> routeConfig[key]?)
+  if actionKeys.length isnt 1
+    pushError(errors, 'E_ROUTE_ACTION', path, 'route must define exactly one action: upstream, app, static, redirect, or headers', "Choose one action field per route.")
+  routePath = if typeof routeConfig.path is 'string' and routeConfig.path.startsWith('/') then routeConfig.path else null
+  pushError(errors, 'E_ROUTE_PATH', "#{path}.path", 'route path must be a string starting with /', "Use `path: '/*'`.") unless routePath
+  if routeConfig.upstream? and not knownUpstreams.has(routeConfig.upstream)
+    pushError(errors, 'E_ROUTE_UPSTREAM_REF', "#{path}.upstream", "unknown upstream #{routeConfig.upstream}", 'Define the upstream under `upstreams` first.')
+  if routeConfig.app? and not knownApps.has(routeConfig.app)
+    pushError(errors, 'E_ROUTE_APP_REF', "#{path}.app", "unknown app #{routeConfig.app}", 'Define the app under `apps` first.')
+  if routeConfig.websocket is true and not routeConfig.upstream?
+    pushError(errors, 'E_ROUTE_WEBSOCKET', "#{path}.websocket", 'websocket routes currently require an upstream action', 'Set `upstream: ...` on the route or remove `websocket: true`.')
+  if routeConfig.static?
+    pushError(errors, 'E_ROUTE_STATIC_TYPE', "#{path}.static", 'static must be a string path', "Use `static: '.'` or `static: '/path/to/dir'`.") unless typeof routeConfig.static is 'string'
+    pushError(errors, 'E_ROUTE_SPA_TYPE', "#{path}.spa", 'spa must be a boolean', "Use `spa: true` or remove it.") if routeConfig.spa? and typeof routeConfig.spa isnt 'boolean'
+    pushError(errors, 'E_ROUTE_ROOT_TYPE', "#{path}.root", 'root must be a string path', "Use `root: '/path/to/dir'`.") if routeConfig.root? and typeof routeConfig.root isnt 'string'
+  if routeConfig.redirect?
+    unless isPlainObject(routeConfig.redirect) and typeof routeConfig.redirect.to is 'string'
+      pushError(errors, 'E_REDIRECT_TO', "#{path}.redirect", 'redirect must have a `to` string', "Use `redirect: { to: 'https://example.com', status: 301 }`.")
+    if routeConfig.redirect?.status? and not VALID_REDIRECT_STATUSES.has(routeConfig.redirect.status)
+      pushError(errors, 'E_REDIRECT_STATUS', "#{path}.redirect.status", 'redirect status must be 301, 302, 307, or 308', "Use `status: 301` or `status: 302`.")
+  effectiveRoot = if typeof routeConfig.root is 'string' then resolve(baseDir, routeConfig.root) else if serverRoot then serverRoot else null
+  {
+    id:        routeConfig.id or "route-#{idx + 1}"
+    host:      serverHost.toLowerCase()
+    path:      routePath or '/'
+    methods:   if routeConfig.methods? then routeConfig.methods else '*'
+    priority:  normalizePositiveInt(routeConfig.priority, idx, "#{path}.priority", errors, 'priority')
+    upstream:  routeConfig.upstream or null
+    app:       routeConfig.app or null
+    static:    routeConfig.static or null
+    root:      effectiveRoot
+    spa:       routeConfig.spa is true
+    browse:    routeConfig.browse is true
+    redirect:  routeConfig.redirect or null
+    headers:   routeConfig.headers or null
+    websocket: routeConfig.websocket is true
+    timeouts:  normalizeTimeouts(routeConfig.timeouts, "#{path}.timeouts", errors)
+  }
+
+normalizeServerBlock = (host, serverConfig, baseDir, errors, knownUpstreams, knownApps) ->
+  path = "hosts.#{host}"
+  unless isPlainObject(serverConfig)
+    pushError(errors, 'E_SERVER_TYPE', path, 'server block must be an object', "Use '#{host}': { routes: [...] }.")
+    return { host: host.toLowerCase(), routes: [], timeouts: {}, certPath: null, keyPath: null, passthrough: null }
+  if serverConfig.passthrough?
+    unless typeof serverConfig.passthrough is 'string' and serverConfig.passthrough.trim()
+      pushError(errors, 'E_SERVER_PASSTHROUGH', "#{path}.passthrough", 'passthrough must be a host:port string', "Use passthrough: '127.0.0.1:8443'.")
+    return {
+      host:        host.toLowerCase()
+      routes:      []
+      timeouts:    {}
+      certPath:    null
+      keyPath:     null
+      passthrough: if typeof serverConfig.passthrough is 'string' then serverConfig.passthrough.trim() else null
+    }
+  hasCert = serverConfig.cert?
+  hasKey = serverConfig.key?
+  if hasCert isnt hasKey
+    pushError(errors, 'E_SERVER_TLS_PAIR', path, 'server block must provide both cert and key or neither', "Add both cert and key, or remove both.")
+  certPath = if hasCert and typeof serverConfig.cert is 'string' then resolve(baseDir, serverConfig.cert) else null
+  keyPath = if hasKey and typeof serverConfig.key is 'string' then resolve(baseDir, serverConfig.key) else null
+  serverRoot = if typeof serverConfig.root is 'string' then resolve(baseDir, serverConfig.root) else null
+  serverSpa = serverConfig.spa is true
+  serverBrowse = serverConfig.browse is true
+  serverApp = null
+  inlineApp = null
+  if typeof serverConfig.app is 'string' and serverConfig.app.trim()
+    serverApp = serverConfig.app.trim()
+    if not knownApps.has(serverApp)
+      pushError(errors, 'E_SERVER_APP_REF', "#{path}.app", "unknown app #{serverApp}", 'Define the app under `apps` first.')
+  else if isPlainObject(serverConfig.app)
+    serverApp = "app-#{host.toLowerCase()}"
+    inlineAppConfig = Object.assign({}, serverConfig.app, { hosts: [host.toLowerCase()] })
+    inlineApp = normalizeAppConfigInto(serverApp, inlineAppConfig, baseDir, "#{path}.app", errors)
+  routes = []
+  if Array.isArray(serverConfig.routes) and serverConfig.routes.length > 0
+    for routeConfig, idx in serverConfig.routes
+      routes.push(normalizeServerRouteConfig(routeConfig, idx, host, serverRoot, baseDir, errors, knownUpstreams, knownApps))
+  else if serverApp
+    routes.push
+      id:        'route-1'
+      host:      host.toLowerCase()
+      path:      '/*'
+      methods:   '*'
+      priority:  0
+      upstream:  null
+      app:       serverApp
+      static:    null
+      root:      null
+      spa:       false
+      browse:    false
+      redirect:  null
+      headers:   null
+      websocket: false
+      timeouts:  {}
+  else if serverRoot
+    routes.push
+      id:        'route-1'
+      host:      host.toLowerCase()
+      path:      '/*'
+      methods:   '*'
+      priority:  0
+      upstream:  null
+      app:       null
+      static:    '.'
+      root:      serverRoot
+      spa:       serverSpa
+      browse:    serverBrowse
+      redirect:  null
+      headers:   null
+      websocket: false
+      timeouts:  {}
+  else
+    pushError(errors, 'E_SERVER_ROUTES', "#{path}", 'server block must define routes, root, app, or passthrough', "Add routes: [...], root: '/path', app: 'name', or passthrough: 'host:port'.")
+  {
+    host:        host.toLowerCase()
+    routes:      routes
+    timeouts:    normalizeTimeouts(serverConfig.timeouts, "#{path}.timeouts", errors)
+    certPath:    certPath
+    keyPath:     keyPath
+    passthrough: null
+    inlineApp:   inlineApp
+  }
+
+normalizeServersConfig = (config, baseDir) ->
+  errors = []
+  for key of config
+    pushError(errors, 'E_UNKNOWN_KEY', key, "unknown top-level key #{key}", 'Allowed keys: version, edge, hosts, upstreams, apps, streamUpstreams, streams.') unless topLevelKeys.has(key)
+  edgeInput = config.edge or {}
+  edge = normalizeEdgeSettings(edgeInput, errors)
+  upstreams = {}
+  if config.upstreams?
+    unless isPlainObject(config.upstreams)
+      pushError(errors, 'E_UPSTREAMS_TYPE', 'upstreams', 'upstreams must be an object keyed by upstream ID', "Use upstreams: { app: { targets: ['http://127.0.0.1:3000'] } }.")
+    else
+      for upstreamId, upstreamConfig of config.upstreams
+        upstreams[upstreamId] = normalizeUpstreamConfig(upstreamId, upstreamConfig, "upstreams.#{upstreamId}", errors)
+  apps = {}
+  if config.apps?
+    unless isPlainObject(config.apps)
+      pushError(errors, 'E_APPS_TYPE', 'apps', 'apps must be an object keyed by app ID', "Use apps: { admin: { entry: './admin/index.rip' } }.")
+    else
+      for appId, appConfig of config.apps
+        apps[appId] = normalizeAppConfigInto(appId, appConfig, baseDir, "apps.#{appId}", errors)
+  knownUpstreams = new Set(Object.keys(upstreams))
+  knownApps = new Set(Object.keys(apps))
+  sites = {}
+  certs = {}
+  passthroughUpstreams = {}
+  passthroughStreams = []
+  unless isPlainObject(config.hosts)
+    pushError(errors, 'E_HOSTS_TYPE', 'hosts', 'hosts must be an object keyed by hostname', "Use hosts: { '*.example.com': { root: '/mnt/site' } }.")
+  else
+    for host, serverConfig of config.hosts
+      normalized = normalizeServerBlock(host, serverConfig, baseDir, errors, knownUpstreams, knownApps)
+      if normalized.passthrough
+        upstreamId = "passthrough-#{normalized.host}"
+        parsed = parseHostPort(normalized.passthrough)
+        if parsed
+          passthroughUpstreams[upstreamId] = { id: upstreamId, targets: [parsed], connectTimeoutMs: 5000 }
+          passthroughStreams.push({ id: upstreamId, order: passthroughStreams.length, listen: 443, sni: [normalized.host], upstream: upstreamId, timeouts: {} })
+        else
+          pushError(errors, 'E_SERVER_PASSTHROUGH', "hosts.#{host}.passthrough", "invalid passthrough target #{normalized.passthrough}", "Use passthrough: '127.0.0.1:8443'.")
+      else
+        sites[normalized.host] = { host: normalized.host, timeouts: normalized.timeouts, routes: normalized.routes }
+        if normalized.certPath and normalized.keyPath
+          certs[normalized.host] = { certPath: normalized.certPath, keyPath: normalized.keyPath }
+        if normalized.inlineApp
+          apps[normalized.inlineApp.id] = normalized.inlineApp
+  streamUpstreams = normalizeStreamUpstreams(config.streamUpstreams, errors)
+  for id, upstream of passthroughUpstreams
+    streamUpstreams[id] = upstream
+  knownStreamUpstreams = new Set(Object.keys(streamUpstreams))
+  streams = normalizeStreams(config.streams, knownStreamUpstreams, errors)
+  streams = passthroughStreams.concat(streams)
+  throw validationError(EDGEFILE_NAME, errors) if errors.length > 0
+  { kind: 'edge', version: config.version or 1, edge, upstreams, apps, routes: [], sites, certs, streamUpstreams, streams }
+
+export createConfigError = (code, path, message, hint = null) ->
+  { code, path, message, hint }
+
+export normalizeAppConfig = (appId, appConfig, baseDir) ->
+  errors = []
+  normalized = normalizeAppConfigInto(appId, appConfig or {}, baseDir, "apps.#{appId}", errors)
+  throw validationError("app #{appId}", errors) if errors.length > 0
+  normalized
+
+export normalizeLegacyConfig = (config, baseDir) ->
+  errors = []
+  unless isPlainObject(config)
+    pushError(errors, 'E_CONFIG_TYPE', '$', 'config.rip must export an object', "Use `export default { apps: { ... } }`.")
+    throw validationError(LEGACY_CONFIG_NAME, errors)
+  for key of config
+    pushError(errors, 'E_LEGACY_KEY', key, "unknown top-level key #{key} in config.rip", 'Use only the `apps` key in config.rip, or migrate to Edgefile.rip.') unless key is 'apps'
+  apps = {}
+  if config.apps?
+    unless isPlainObject(config.apps)
+      pushError(errors, 'E_APPS_TYPE', 'apps', 'apps must be an object keyed by app ID', "Use `apps: { main: { entry: './index.rip' } }`.")
+    else
+      for appId, appConfig of config.apps
+        apps[appId] = normalizeAppConfigInto(appId, appConfig, baseDir, "apps.#{appId}", errors)
+  throw validationError(LEGACY_CONFIG_NAME, errors) if errors.length > 0
+  { kind: 'legacy', version: null, edge: {}, upstreams: {}, apps, routes: [], sites: {} }
+
+export normalizeEdgeConfig = (config, baseDir) ->
+  normalizeServersConfig(config, baseDir)
+
+export summarizeConfig = (configPath, normalized) ->
+  path = resolve(configPath)
+  kind = normalized.kind or (if basename(path) is EDGEFILE_NAME then 'edge' else 'legacy')
+  {
+    kind
+    path
+    version: normalized.version or null
+    counts:
+      upstreams: Object.keys(normalized.upstreams or {}).length
+      apps: Object.keys(normalized.apps or {}).length
+      routes: (normalized.routes or []).length
+      sites: Object.keys(normalized.sites or {}).length
+      streamUpstreams: Object.keys(normalized.streamUpstreams or {}).length
+      streams: (normalized.streams or []).length
+    canonicalShape:
+      version: true
+      edge: true
+      upstreams: true
+      apps: true
+      routes: true
+      sites: true
+      streamUpstreams: true
+      streams: true
+  }
+
+export loadConfig = (configPath) ->
+  return null unless existsSync(configPath)
+  try
+    raw = moduleObject!(configPath, LEGACY_CONFIG_NAME)
+    normalizeLegacyConfig(raw, dirname(configPath))
+  catch e
+    if e.validationErrors
+      console.error formatConfigErrors(LEGACY_CONFIG_NAME, e.validationErrors)
+    else
+      console.error "rip-server: failed to load config.rip: #{e.message}"
+    null
+
+export loadEdgeConfig = (configPath) ->
+  return null unless existsSync(configPath)
+  raw = moduleObject!(configPath, EDGEFILE_NAME)
+  normalizeEdgeConfig(raw, dirname(configPath))
+
+export checkConfigFile = (configPath) ->
+  resolved = resolve(configPath)
+  kind = if basename(resolved) is EDGEFILE_NAME then 'edge' else 'legacy'
+  normalized = if kind is 'edge' then loadEdgeConfig!(resolved) else normalizeLegacyConfig(moduleObject!(resolved, LEGACY_CONFIG_NAME), dirname(resolved))
+  { kind, normalized, summary: summarizeConfig(resolved, normalized) }
+
 export findConfigFile = (appEntry) ->
-  dir = dirname(appEntry)
-  configPath = join(dir, 'config.rip')
+  dir = if existsSync(appEntry) and statSync(appEntry).isDirectory() then appEntry else dirname(appEntry)
+  configPath = join(dir, LEGACY_CONFIG_NAME)
   if existsSync(configPath) then configPath else null
 
+export findEdgeFile = (appEntry) ->
+  dir = if existsSync(appEntry) and statSync(appEntry).isDirectory() then appEntry else dirname(appEntry)
+  edgePath = join(dir, EDGEFILE_NAME)
+  if existsSync(edgePath) then edgePath else null
+
+export resolveConfigSource = (appEntry, edgefilePath = null) ->
+  if edgefilePath
+    resolved = if edgefilePath.startsWith('/') then edgefilePath else resolve(process.cwd(), edgefilePath)
+    return { kind: 'edge', path: resolved }
+  if basename(appEntry) is EDGEFILE_NAME
+    return { kind: 'edge', path: resolve(appEntry) }
+  if basename(appEntry) is LEGACY_CONFIG_NAME
+    return { kind: 'legacy', path: resolve(appEntry) }
+  edgePath = findEdgeFile(appEntry)
+  return { kind: 'edge', path: edgePath } if edgePath
+  legacyPath = findConfigFile(appEntry)
+  return { kind: 'legacy', path: legacyPath } if legacyPath
+  null
+
 export applyConfig = (config, registry, registerAppFn, baseDir) ->
-  apps = config.apps or {}
+  normalized = if config?.kind then config else normalizeLegacyConfig(config or {}, baseDir)
+  apps = normalized.apps or {}
   registered = []
   for appId, appConfig of apps
-    normalized = normalizeAppConfig(appId, appConfig, baseDir)
+    normalizedApp = normalizeAppConfigInto(appId, appConfig, baseDir, "apps.#{appId}", [])
+    registerAppFn(registry, appId,
+      entry: normalizedApp.entry
+      appBaseDir: if normalizedApp.entry then dirname(normalizedApp.entry) else baseDir
+      hosts: normalizedApp.hosts
+      workers: normalizedApp.workers
+      maxQueue: normalizedApp.maxQueue
+      queueTimeoutMs: normalizedApp.queueTimeoutMs
+      readTimeoutMs: normalizedApp.readTimeoutMs
+      env: normalizedApp.env
+    )
+    registered.push(normalizedApp)
+  registered
+
+export applyEdgeConfig = (config, registry, registerAppFn, baseDir) ->
+  registered = []
+  apps = config.apps or {}
+  for appId, appConfig of apps
+    normalizedApp = normalizeAppConfigInto(appId, appConfig, baseDir, "apps.#{appId}", [])
     registerAppFn(registry, appId,
-      hosts: normalized.hosts
-      maxQueue: normalized.maxQueue
-      queueTimeoutMs: normalized.queueTimeoutMs
-      readTimeoutMs: normalized.readTimeoutMs
+      entry: normalizedApp.entry
+      appBaseDir: if normalizedApp.entry then dirname(normalizedApp.entry) else baseDir
+      hosts: normalizedApp.hosts
+      workers: normalizedApp.workers
+      maxQueue: normalizedApp.maxQueue
+      queueTimeoutMs: normalizedApp.queueTimeoutMs
+      readTimeoutMs: normalizedApp.readTimeoutMs
+      env: normalizedApp.env
     )
-    registered.push(normalized)
+    registered.push(normalizedApp)
   registered