Skip to main content

Services

A Service in an Andera Worker is a long-running component that manages resources or background processes, such as launching a browser or a server. Services are defined in the src/services/ directory and are auto-discovered and started at Worker startup.

Structure of a Service​

A service is defined using defineService from @andera-top/worker-core. Each service specifies:

  • config: (optional) Service-specific configuration (e.g., restart on failure)
  • start: An async function to initialize the service
  • stop: (optional) An async function to clean up resources
  • status: (optional) A function to report service status

Example​

This service launches Chromium with Playwright when the Worker starts. If the browser crashes, status throws, so the Worker stops and restarts the service:

// src/services/playwright.ts
import { defineService } from '@andera-top/worker-core'
import { chromium, Browser } from 'playwright'

let browser: Browser | null = null

export default defineService({
config: { restartOnFailure: true },
start: async () => {
browser = await chromium.launch({ headless: true })
// ...create one browser context per slot, see Helpers
},
stop: async () => {
if (browser) await browser.close()
browser = null
},
status: async () => {
if (!browser?.isConnected()) throw new Error('Browser unavailable')
return { browserVersion: browser.version() }
},
})

The Screenshot Worker uses this pattern with a pool of browser contexts.

Logging in Services​

You can use the logging utilities to monitor your service lifecycle and errors (see Logging):

import { log, warn, error } from '@andera-top/worker-core/dist/utils/logger'

export default defineService({
start: async () => {
log('[MYSERVICE]', 'Service starting...')
// ...
},
stop: async () => {
log('[MYSERVICE]', 'Service stopping...')
// ...
},
status: async () => {
// ...
warn('[MYSERVICE]', 'Status check warning')
return { ok: true }
}
})

Service Config Options​

The config object for a service can have the following options:

OptionTypeDescriptionExample
restartOnFailurebooleanWhether to automatically restart the service if it crashestrue

Creating a New Service​

  1. Create a new file in src/services/, e.g. myService.ts.
  2. Export your service using defineService as shown above, either as the default export or as a named export matching the file name.
  3. The service will be auto-registered and started at Worker startup. Files whose name starts with . or _ are ignored.

Service Lifecycle​

  • Services are started automatically when the Worker starts.
  • They are stopped gracefully when the Worker shuts down (SIGTERM or SIGINT).
  • The Worker calls each status callback every second. When it throws, the service is marked down, stop is called, and, if restartOnFailure is set, start is called again.
  • While a service is down, the Worker reports unavailable in /health and queued tasks wait until it is up again.

A status callback must throw when the service is unavailable. Returning { ok: false } is still a successful check. Without a status callback, the runtime can retry a failed start, but cannot detect a later service failure.