app

Documentation

Overview

Package app is the Motors application component: HTTP handlers plus product-owned subcomponents (interest VPQ, catalog-summary refresher).

Listen is not this package’s job. `caerus-framework-http` is the Runnable; Init builds the mux and calls SetHandler. Jobs never start Runnables, so `--demoapp.job=seed` does not bind :8081.

Subcomponents() exposes children constructed in New; the framework expands them into the registry. main only declares chassis + app.New.

The app also owns the ops jobs (--demoapp.job=seed|doctor|price) via JobRunner: the framework's job-only path initializes this component's dependency closure (core + the whole data plane, including http Init without listen) and runs the named task without starting any background runners.

Index

• Constants
• type API
  • func New(opts Options) *API
  • func (a *API) GetDependencies() []string
  • func (a *API) GetInitOrderStage() cf.Stage
  • func (a *API) Init(ctx context.Context, fw *cf.CaerusFramework) error
  • func (a *API) InterestHandler() func(context.Context, *cf_vpq.BGetObject) error
  • func (a *API) Name() string
  • func (a *API) RegisterConfigSources(conf any) error
  • func (a *API) RunJob(ctx context.Context, task string) error
  • func (a *API) Shutdown(ctx context.Context) error
  • func (a *API) Subcomponents() []cf.CaerusComponent
• type DemoAppConfig
• type Options

Constants

const ComponentStage = cf.Stage("app")

ComponentStage is the app's own plane, above the data plane: components in earlier stages (logs, configuration, observability, postgres, valkey, interest VPQ, catalog-summary) initialize first, and a job targeting this component pulls in that whole closure.

Types

type API

type API struct {
	// contains filtered or unexported fields
}

API is the Caerus Motors HTTP surface and owns product subcomponents.

func New

func New(opts Options) *API

New creates the API component and its product-owned children (not yet Init'd).

func (*API) GetDependencies

func (a *API) GetDependencies() []string

GetDependencies implements cf.Dependencies.

We depend on the *named* VPQ instance "interest" (WithName), not the default "vpq". Get[T] would be ambiguous if more queues appeared later. The configuration component is resolved during Init to read the demoapp source.

func (*API) GetInitOrderStage

func (a *API) GetInitOrderStage() cf.Stage

GetInitOrderStage implements cf.CaerusComponent — the app plane, above data.

func (*API) Init

func (a *API) Init(ctx context.Context, fw *cf.CaerusFramework) error

Init resolves peers. Pool/Client must already be live (deps Init first).

func (*API) InterestHandler

func (a *API) InterestHandler() func(context.Context, *cf_vpq.BGetObject) error

InterestHandler returns the VPQ handler for the "interest" queue. It logs through the framework logger subscribed under the "interest" name so logs.SetLevelFor("interest", …) / logs.json component_levels controls its verbosity.

func (*API) Name

func (a *API) Name() string

Name implements cf.CaerusComponent.

func (*API) RegisterConfigSources

func (a *API) RegisterConfigSources(conf any) error

RegisterConfigSources implements cf.ConfigSourceRegistrar. The framework calls it during argv absorption so this app class owns its configuration source: type DemoAppConfig, file ConfigPath, env DEMOAPP_, owner "motors-api". HTTP listen flags live on the http source (`--http`, `--http-bind`), not here.

func (*API) RunJob

func (a *API) RunJob(ctx context.Context, task string) error

RunJob implements cf.JobRunner. Tasks are the ops shapes behind the --demoapp.job flag: seed, doctor, price. The job-only init path initializes this component's dependency closure first; the tasks return nil when done and the framework tears down and exits. HTTP listen stays closed (cf_http Run never starts).

func (*API) Shutdown

func (a *API) Shutdown(ctx context.Context) error

Shutdown unsubscribes logs. HTTP drain is owned by cf_http.Run.

func (*API) Subcomponents

func (a *API) Subcomponents() []cf.CaerusComponent

Subcomponents implements cf.Subcomponents — interest VPQ and catalog-summary refresher are flattened into the framework registry by AddComponent.

type DemoAppConfig

type DemoAppConfig struct {
	PriceCacheTTLSec int `json:"price_cache_ttl_sec" yaml:"price_cache_ttl_sec" env:"PRICE_CACHE_TTL_SEC"`
}

DemoAppConfig is *our* settings — not postgres, valkey, or HTTP listen. HTTP bind and timeouts live on the http chassis (`config/http.json`, `--http-bind`, `HTTP_BIND`). This file is price-cache TTL only.

Per-component log levels (e.g. interest VPQ debug) live on the logs source: `config/logs.json` → `component_levels` keyed by Name().

Layering (later wins): config/demoapp.json → DEMOAPP_* env → flags.

type Options

type Options struct {
	PriceCacheTTLSec int
	// ConfigSource / ConfigPath name where this app class's own configuration
	// source is registered. New registers it with the configuration component
	// via cf.ConfigSourceRegistrar (source "demoapp", file config/demoapp.json,
	// env DEMOAPP_, owner "motors-api").
	ConfigSource string
	ConfigPath   string
}

Options are construction-time defaults; Init may overlay demoapp.json.