fix(server): fail fast on startup hangs and chunked logs

Author: dekaravanhoc

README.md

@@ -123,6 +123,7 @@ require('opencode').setup({
     command = { 'opencode' }, -- Base runtime command, array-only
     serve_args = { 'serve' }, -- Optional, defaults to {'serve'}
     version_args = { '--version' }, -- Optional, defaults to {'--version'}
+    startup_timeout_ms = 15000, -- Optional startup timeout before failing with an error
     path = {
       to_server = nil, -- Optional fun(path) -> server path
       to_local = nil, -- Optional fun(path) -> local path

lua/opencode/config.lua

@@ -17,6 +17,7 @@ M.defaults = {
     command = { 'opencode' },
     serve_args = { 'serve' },
     version_args = { '--version' },
+    startup_timeout_ms = 15000,
     path = {
       to_server = nil,
       to_local = nil,

lua/opencode/opencode_server.lua

@@ -1,6 +1,7 @@
 local util = require('opencode.util')
 local safe_call = util.safe_call
 local Promise = require('opencode.promise')
+local config = require('opencode.config')
 
 --- @class OpencodeServer
 --- @field job any The vim.system job handle
@@ -26,18 +27,33 @@ local function extract_server_url(data)
     return nil
   end
 
-  local lower = data:lower()
-  if not lower:find('listening', 1, true) then
-    return nil
-  end
+  local url = data:match('opencode server listening on%s+([^%s]+)')
+    or data:match('server listening at%s+([^%s]+)')
+    or data:match('listening on%s+([^%s]+)')
 
-  local url = data:match('opencode server listening on ([^%s]+)')
-    or data:match('server listening at ([^%s]+)')
-    or data:match('(https?://[^%s]+)')
+  if not url then
+    local lower = data:lower()
+    if lower:find('listen', 1, true) then
+      url = data:match('(https?://[^%s%]"\']+)')
+    end
+  end
 
   return url
 end
 
+local function append_chunk(buffer, chunk)
+  if type(chunk) ~= 'string' or chunk == '' then
+    return buffer
+  end
+
+  local next_buffer = buffer .. chunk
+  if #next_buffer > 8192 then
+    next_buffer = next_buffer:sub(-8192)
+  end
+
+  return next_buffer
+end
+
 local vim_leave_setup = false
 local function ensure_vim_leave_autocmd()
   if vim_leave_setup then
@@ -126,6 +142,25 @@ end
 function OpencodeServer:spawn(opts)
   opts = opts or {}
   local log = require('opencode.log')
+  local ready = false
+  local stdout_buf = ''
+  local stderr_buf = ''
+
+  local function mark_ready(url, from_stderr)
+    if ready then
+      return
+    end
+    ready = true
+    self.url = normalize_server_url(url)
+    self.spawn_promise:resolve(self)
+    safe_call(opts.on_ready, self.job, self.url)
+
+    if from_stderr then
+      log.debug('spawn: server ready at url=%s (detected from stderr)', self.url)
+    else
+      log.debug('spawn: server ready at url=%s', self.url)
+    end
+  end
 
   local cmd = util.get_runtime_serve_command()
   local system_opts = {
@@ -135,32 +170,35 @@ function OpencodeServer:spawn(opts)
   self.job = vim.system(cmd, vim.tbl_extend('force', system_opts, {
     stdout = function(err, data)
       if err then
+        if not ready then
+          self.spawn_promise:reject(err)
+        end
         safe_call(opts.on_error, err)
         return
       end
+
       if data then
-        local url = extract_server_url(data)
+        stdout_buf = append_chunk(stdout_buf, data)
+        local url = extract_server_url(stdout_buf)
         if url then
-          self.url = normalize_server_url(url)
-          self.spawn_promise:resolve(self)
-          safe_call(opts.on_ready, self.job, self.url)
-          log.debug('spawn: server ready at url=%s', self.url)
+          mark_ready(url, false)
         end
       end
     end,
     stderr = function(err, data)
       if err then
-        self.spawn_promise:reject(err)
+        if not ready then
+          self.spawn_promise:reject(err)
+        end
         safe_call(opts.on_error, err)
         return
       end
+
       if data then
-        local url = extract_server_url(data)
+        stderr_buf = append_chunk(stderr_buf, data)
+        local url = extract_server_url(stderr_buf)
         if url then
-          self.url = normalize_server_url(url)
-          self.spawn_promise:resolve(self)
-          safe_call(opts.on_ready, self.job, self.url)
-          log.debug('spawn: server ready at url=%s (detected from stderr)', self.url)
+          mark_ready(url, true)
           return
         end
 
@@ -181,6 +219,10 @@ function OpencodeServer:spawn(opts)
       end
     end,
   }), function(exit_opts)
+    if not ready then
+      self.spawn_promise:reject(string.format('opencode server exited before ready (code=%s signal=%s)', tostring(exit_opts.code), tostring(exit_opts.signal)))
+    end
+
     -- Clear fields if not already cleared by shutdown()
     self.job = nil
     self.url = nil
@@ -191,6 +233,29 @@ function OpencodeServer:spawn(opts)
 
   self.handle = self.job and self.job.pid
 
+  local startup_timeout_ms = tonumber(config.runtime and config.runtime.startup_timeout_ms) or 15000
+  vim.defer_fn(function()
+    if ready then
+      return
+    end
+
+    if self.job and self.job.kill then
+      pcall(self.job.kill, self.job, 15)
+      pcall(self.job.kill, self.job, 9)
+    end
+
+    local err = string.format(
+      'Timed out waiting for opencode server startup after %dms. command=%s stdout=%s stderr=%s',
+      startup_timeout_ms,
+      vim.inspect(cmd),
+      vim.inspect(vim.trim(stdout_buf)),
+      vim.inspect(vim.trim(stderr_buf))
+    )
+
+    self.spawn_promise:reject(err)
+    safe_call(opts.on_error, err)
+  end, startup_timeout_ms)
+
   log.debug('spawn: started job with pid=%s', tostring(self.job and self.job.pid))
   return self.spawn_promise
 end

lua/opencode/types.lua

@@ -204,6 +204,7 @@
 ---@field command string[] Base command used to run opencode
 ---@field serve_args? string[] Arguments appended when starting the server (defaults to {'serve'})
 ---@field version_args? string[] Arguments appended when checking CLI version (defaults to {'--version'})
+---@field startup_timeout_ms? integer Time to wait for server ready URL before failing startup (defaults to 15000)
 ---@field path? OpencodeRuntimePathConfig
 
 ---@class OpencodeConfig

tests/unit/opencode_server_spec.lua

@@ -50,6 +50,34 @@ describe('opencode.opencode_server', function()
     assert.equals('http://127.0.0.1:7777', server.url)
   end)
 
+  it('spawn resolves when server URL is split across stdout chunks', function()
+    local server = OpencodeServer.new()
+    local resolved
+
+    vim.system = function(_, opts)
+      vim.schedule(function()
+        opts.stdout(nil, 'opencode server li')
+        opts.stdout(nil, 'stening on http://127.0.0.1:7878')
+      end)
+      return { pid = 1, kill = function() end }
+    end
+
+    server:spawn({
+      cwd = '.',
+      on_ready = function(_, url)
+        resolved = url
+      end,
+      on_error = function() end,
+      on_exit = function() end,
+    })
+
+    vim.wait(100, function()
+      return resolved ~= nil
+    end)
+
+    assert.equals('http://127.0.0.1:7878', resolved)
+  end)
+
   it('spawn uses configured runtime command and normalizes 0.0.0.0 url', function()
     local server = OpencodeServer.new()
     local captured_cmd
@@ -325,4 +353,36 @@ describe('opencode.opencode_server', function()
     assert.is_nil(server.url)
     assert.is_nil(server.handle)
   end)
+
+  it('fails startup with timeout when no server url is emitted', function()
+    local server = OpencodeServer.new()
+    local called = { on_error = false, killed = false }
+    config.runtime.startup_timeout_ms = 10
+
+    vim.system = function()
+      return {
+        pid = 45,
+        kill = function()
+          called.killed = true
+        end,
+      }
+    end
+
+    server:spawn({
+      cwd = '.',
+      on_ready = function() end,
+      on_error = function(err)
+        called.on_error = true
+        assert.is_truthy(tostring(err):find('Timed out waiting for opencode server startup', 1, true))
+      end,
+      on_exit = function() end,
+    })
+
+    vim.wait(200, function()
+      return called.on_error
+    end)
+
+    assert.is_true(called.on_error)
+    assert.is_true(called.killed)
+  end)
 end)