We are launching all new Klivolks 3.0See what is new

init kgate

nexler init kgate

local only
nexler init kgate [-dir <app-dir>]

Adds a client for KGate (Klivolks' message broker): kgate/kgate.go (Subscribe/Unsubscribe/ResumeAll/Publish/HandleWebhook/Register — pure infrastructure, never hand-edited), a one-time-written companion at services/kgate/kgate.go (Init/HandleEvent — this is where your own logic goes), and five blank env vars — KGATE_CLIENT_ID, KGATE_WS_SERVER, KGATE_HTTP_SERVER, KGATE_ORIGIN, KGATE_WEBHOOK_SECRET. Also auto-wires a POST /webhooks/kgate fallback route, plus a blank services/kgate import, into routes/public/public.go.

Requires the app to already have a core database connection (-db at create app time) — channel subscriptions aren't static/env-driven: Subscribe(ctx, channel) records the channel and adds it to a single shared WebSocket connection multiplexing every subscribed channel (with dial-timeout and ping/pong keepalive), durable across restarts via ResumeAll(ctx), which is already wired automatically (Register kicks it off in the background the moment it runs, followed by OnStartup — services/kgate's Init, once you've run init kgate — and Register(mux) is called from main.go's own routes.Register(mux) — no manual wiring needed). All subscribed channels share one connection, rather than one per channel, because kgate's gateway allows only one live connection per X-Client-Id — opening several concurrently under the same client ID causes each new one to evict another, an endless reconnect churn. Every event, live or via the HMAC-verified webhook fallback, is dispatched (panic-safely, via dispatchEvent) to services/kgate's HandleEvent — a payload that will never decode should return a permanent error (see kgate.go's own permanentf) so it's acked once and logged rather than redelivered forever. Structured connection-lifecycle logging (log/slog, JSON, never including payload data) goes to stdout tagged component=kgate. Needs go mod tidy once and nexler init db before subscriptions will work.

Register also documents POST /webhooks/kgate in /openapi.json/Swagger UI (previously invisible there, unlike every route nexler create <route> generates), and calls OnStartup — services/kgate's Init, by default a Subscribe to a channel literally named "test" — alongside ResumeAll on startup, a built-in smoke test that the whole pipeline (core DB registry + WebSocket connectivity) works end to end. Safe to leave in (Subscribe is idempotent for an already-subscribed channel) or edit services/kgate/kgate.go's Init to your app's real startup channels once you've confirmed kgate is wired correctly.

nexler init kgate -dir ./myapp

Usage — subscribe from anywhere (a handler, a startup routine, mid-workflow), publish from anywhere, and process every delivered event (live or via the webhook fallback) in services/kgate/kgate.go's HandleEvent — never in kgate/kgate.go itself, which stays nexler-owned infrastructure:

// start listening for a channel, e.g. when an order is created
if err := kgate.Subscribe(ctx, "orders.created"); err != nil {
	log.Printf("kgate: subscribing: %v", err)
}

// publish an event to that channel from anywhere else
if err := kgate.Publish(ctx, "orders.created", map[string]any{"order_id": id}); err != nil {
	log.Printf("kgate: publishing: %v", err)
}

// services/kgate/kgate.go — edit HandleEvent for your own processing logic
func HandleEvent(ctx context.Context, channel string, payload json.RawMessage) error {
	switch channel {
	case "orders.created":
		// ... handle it
	}
	return nil
}