[runnable] add registration helper

[capcom6]

Summary by CodeRabbit

• New Features
  • Added utilities to register and run long‑running background tasks as part of the application lifecycle.
  • Tasks are started in the proper lifecycle phase, run with cancellable contexts, and are monitored for errors that trigger coordinated shutdowns.
  • Ensures graceful stop behavior by waiting for tasks to finish or cancel before completing shutdown.

[coderabbitai]

Walkthrough

Adds a new Runnable interface and a generic RegisterRunnable[T Runnable] helper in package fxutil that registers an FX lifecycle hook to run Run(ctx) in a goroutine, handle errors via fx.Shutdown(), and coordinate cancellation and wait on shutdown.

Changes

Cohort / File(s)

Summary

Runnable lifecycle utility runnable.go

Adds type Runnable interface { Run(ctx context.Context) error } and func RegisterRunnable[T Runnable]() func(lc fx.Lifecycle, sh fx.Shutdowner, r T) which registers FX start/stop hooks: starts r.Run(ctx) in a goroutine with cancellable context, invokes fx.Shutdown() on run error, closes a wait channel when finished, and on stop cancels the context and waits for either completion or the stop context.

Sequence Diagram(s)

sequenceDiagram
    participant FX as FX Lifecycle
    participant Reg as RegisterRunnable
    participant Task as Runnable
    participant Gor as Goroutine

    rect rgba(0, 120, 200, 0.5)
    Note over FX,Reg: FX startup
    FX->>Reg: start hook
    Reg->>Gor: launch goroutine with cancellable ctx
    Gor->>Task: call Task.Run(ctx)
    end

    rect rgba(200, 80, 0, 0.5)
    Note over FX,Reg: FX shutdown
    FX->>Reg: stop hook
    Reg->>Gor: cancel ctx
    alt Task finishes before stop deadline
        Gor->>Reg: close waitCh (done)
    else stop context deadline reached
        Reg->>FX: stop hook returns due to stop ctx done
    end
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: adding a registration helper for Runnable types in the fxutil package.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

No actionable comments were generated in the recent review. 🎉

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@runnable.go`:
- Around line 25-32: The OnStop closure currently shadows the outer ctx and
swallows stop-timeouts; rename the OnStop parameter (e.g., change OnStop:
func(ctx context.Context) to OnStop: func(stopCtx context.Context)) to avoid
shadowing the outer cancellable context and update the select to return the stop
context's error when its deadline/cancellation fires (i.e., return stopCtx.Err()
in the <-stopCtx.Done() branch) while still calling cancel() and waiting on
waitCh; reference the OnStop func, cancel(), and waitCh symbols when making the
change.

🧹 Nitpick comments (1)

runnable.go (1)

9-11: Consider having Run return an error.

If a Runnable fails, there's currently no way to propagate that failure back to the FX application (e.g., to trigger a graceful shutdown via fx.Shutdowner). A signature like Run(ctx context.Context) error would allow RegisterRunnable to observe the result and optionally shut down the app on failure.

This is a public API choice that will be harder to change later without breaking consumers.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@runnable.go`:
- Around line 20-25: The goroutine calling r.Run currently ignores both the Run
error and the return value of sh.Shutdown(), which trips errcheck and hides
failures; update the goroutine (the anonymous func that invokes r.Run(ctx)) to
(1) capture the error returned by r.Run and either set it as the process exit
code via fx.ExitCode or log it using the existing logger, (2) call sh.Shutdown()
and handle its returned error (either log it or explicitly discard it by
assigning to _ to satisfy errcheck), and (optionally) only call Shutdown when
ctx.Err() == nil to avoid shutdown on expected context cancellation; reference
the r.Run call, the sh.Shutdown invocation, waitCh close, and
fx.ExitCode/logging for where to make the changes.