alt/services/worker

ALT Worker Service

The Worker service handles background tasks, such as market data imports, data normalization, and backtest execution.

Market Data Provider Boundary

ALT starts with KIS/Korea daily bars as the first provider and venue validation path, but the worker boundary should keep the canonical model equity venue-agnostic. KRX-specific or KIS-specific fields belong in provider adapters, venue metadata, raw payload storage, or explicit extension metadata instead of becoming required core columns.

Crypto is out of scope for the current stock-oriented market model. If a later crypto data domain is added, it may reuse generic import-run, provider mapping, raw-payload, and OHLCV pipeline concepts, but pair/funding/24-7 market semantics should not be forced into the equity model.

Provider Reference and Mock Fixtures

KIS adapter mapping should start from the locally cached official sample repository, not from a required Postman export. The cache path is documented in the private rules because it is local machine state, not an ALT source dependency.

• Store mock-provider request/response fixtures under services/worker/testdata/providers/kis/.
• Remove app keys, tokens, account numbers, personal identifiers, and live secret references before committing any fixture.
• Prefer JSON for initial adapter mapping because it is readable, diffable, and close to the KIS REST payload shape.
• Consider SQLite only after the fixture corpus is large enough to need indexed lookup or query-based comparison.

Provider credentials are not required for mock tests. When live KIS smoke tests are added later, KIS agent runtime secrets should come from SOPS + age and be injected only for the command lifetime.

Redis Usage Guidelines

Purpose

Redis is used as a lightweight, high-performance messaging, coordination, and caching layer for background jobs. It is not a source of truth. All critical system states and historical datasets reside in PostgreSQL.

Key Prefixing Standard

To avoid key collisions and maintain organization, all keys created by the worker must use the designated helper package internal/rediskeys and strictly follow the format:

<prefix>:worker:<purpose>:<id>

• <prefix>: Configured via ALT_REDIS_KEY_PREFIX (defaults to alt). This segregates environments or local dev workspaces.
• worker: Hardcoded namespace denoting worker-owned keys.
• <purpose>: Lowercase segment describing the domain or usage (e.g. job, lock, cache).
• <id>: Unique identifier for the specific object (e.g., job ID, lock name).

Always utilize rediskeys.WorkerKey(prefix, purpose, id) instead of assembling key strings manually.

Configuration

Environment variables can be used to customize worker runtime:

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgres://alt:alt@localhost:15430/alt?sslmode=disable
REDIS_URL	Redis connection string	redis://localhost:16330/0
ALT_WORKER_HOST	Worker bind host	127.0.0.1
ALT_WORKER_PORT	Worker listen port	18031
ALT_WORKER_SOCKET_PATH	Worker WebSocket path	/socket
ALT_REDIS_KEY_PREFIX	Namespace prefix for Redis keys	alt
ALT_WORKER_QUEUE	Target worker queue to consume from	default