v0.2.0

✨ Highlights

Kafka — choose your subscriber delivery guarantee

Kafka subscribers can now pick how the consumer offset is committed relative to handler processing, via SubscriberConfigBuilder.DeliveryGuarantee:

• AtMostOnce — the default and unchanged behavior: the offset is committed on read, before handlers run, with the parallel per-key worker pool. Fastest, but in-flight messages are lost on shutdown/crash. Existing subscribers are unaffected.
• AtLeastOnce — opt-in: the offset is committed only after a handler returns nil, so nothing is lost on SIGTERM / scale-down / crash — uncommitted messages are redelivered. A failing or panicking handler is retried on the same message, commits are forced synchronous and still land during graceful shutdown, and an unrecognized guarantee is rejected at AddSubscriber. Messages are processed sequentially, so handlers must be idempotent.

broker.AddSubscriber(ctx,
    kafka.NewTopicCfgBuilder("orders").Build(),
    kafka.NewSubscriberCfgBuilder().
        GroupId("my-service").
        DeliveryGuarantee(kafka.AtLeastOnce).
        Build(),
    handler,
)

⚠️ Breaking changes

• Root-package mocks renamed. mocks/kit_mocks.go → mocks/jet_mocks.go, and KitAppErrBuilder / KitCLogger / … → JetAppErrBuilder / JetCLogger / …. All other mock names are unchanged.
• Error code KIT-001 → JET-001 (ErrCodeAdapterConfigInvalid).

🧹 Maintenance

• Removed the original internal kit package name throughout — import aliases (kit* → jet*), docs, the jet-toolkit skill and the agents. The project now references only github.com/zloevil/jet.
• Added a checked-in .mockery.yaml (mockery v3) so make mock works out of the box; all mocks were regenerated from it.

Full Changelog: v0.1.1...v0.2.0

v0.1.1 — AI agent specs refresh + jet-toolkit skill

v0.1.1 — AI agent specs refresh + jet-toolkit skill

Tooling / developer-experience release. No library code or API changes — every .go file is identical to v0.1.0. This release reworks the two bundled AI agent specs and adds a Claude Code skill for building services on jet.

New: jet-toolkit Claude Code skill

skills/jet-toolkit/ — an always-on skill that keeps an AI coding agent from reinventing what jet already ships. Where the .agents/ specs are heavyweight personas you hand a whole service to, the skill is a lightweight reflex: before writing infrastructure (logging, errors, config, retries, goroutines, a Kafka consumer, a DB pool…) it checks the toolkit first, and on review/refactor it hunts down hand-rolled boilerplate and swaps in the jet equivalent.

• SKILL.md — trigger rules, the "check the catalog before writing infra" reflex, and the build-new / refactor-out-boilerplate workflows
• references/catalog.md — the "don't build it, jet has it" map: an about-to-hand-roll-X → use jet's Y table plus package-by-package capabilities
• references/conventions.md — idiomatic use of the core primitives (AppError, the CLoggerFunc pattern, request context, the cluster lifecycle, layering, storage conventions, concurrency, config, testing)

Install: copy skills/jet-toolkit/ into your Claude Code skills directory (e.g. ~/.claude/skills/). It activates automatically on a Go service that imports github.com/zloevil/jet.

Reworked agents — jet-service-agent & jet-gateway-agent

Both specs were audited against the jet source and hardened.

Accuracy. Re-verified every API signature against source and fixed the misleading ones — e.g. kafka AddProducer/AddSubscriber take a *TopicConfig (built via NewTopicCfgBuilder(...).Build()), not a topic string; gRPC Listen(ctx) blocks while ListenAsync(ctx) does not; redis.UnLock takes no TTL; the real monitoring.MetricsProvider / MetricsCollector shape.

Self-correcting by default. The preamble no longer tells the agent to avoid jet's source and trust the inlined signatures verbatim. They're now framed as a verified snapshot with the source as the tiebreaker (go doc github.com/zloevil/jet/<pkg>), so the specs don't silently rot as jet evolves.

Gateway lifecycle hardening — concrete guidance on the failure modes that actually bite a session-pool service:

• the upstream SDK read-loop is a second goroutine and must also be panic-safe
• goroutine.WithRetry restarts only on a panic, so reconnection must be an explicit loop (a normal disconnect is not a panic)
• back-pressure when a blocking producer.Send drains the inbound events channel
• a single-writer / run-lock so two replicas don't double-connect the same session on restore
• backoff jitter to avoid a thundering herd on mass reconnect
• the request-context-from-metadata behavior is unary-only — stream handlers must build their own

Service additions — retry (RPCConfig/Do) for egress calls, a graceful goroutine-shutdown pattern, in-cluster migration application (db-up as an initContainer/Job), and a clearer config-binding story (most jet config structs are untagged; viper binds case-insensitively with a .→_ env override).

Leaner & sharper. Collapsed the repeated rule-sets into single canonical "invariants + checklist" blocks, and tightened the trigger descriptions so the domain-service and gateway archetypes don't mis-route.

Edits were applied per file and independently cross-checked against the jet source, including an adversarial verification pass.

Upgrade

Nothing to do for the library: go get github.com/zloevil/jet@v0.1.1 is byte-identical Go to v0.1.0. The value here lives in .agents/ and skills/ for anyone building on jet with an AI coding agent.

Full Changelog: v0.1.0...v0.1.1

v0.1.0

jet is a pragmatic Go toolkit for building microservices — extracted from an internal kit that has run 20+ production services for several years. It favors boring, explicit building blocks so you stop rewriting the same logger, graceful shutdown, database pool and Kafka consumer in every service.

What's inside
Core (jet) — structured logger over log/slog, typed config loader, request context, AppError model, healthcheck, JWT, crypto, validators, generics helpers
cluster — service lifecycle (Bootstrap + CLI), config loading, DB migrations
goroutine / retry — panic-safe goroutines & error groups, bounded retry with backoff
kafka — producer/subscriber (segmentio/kafka-go) with SASL, workers, context propagation
http / grpc — servers with middleware
storages/* — PostgreSQL (GORM), Redis, MongoDB, ClickHouse, MinIO, Aerospike, migrations
event / batch — in-process event bus, batch writer
monitoring / profile — Prometheus metrics, pprof
Integrations — AWS (S3/SQS), Elasticsearch, Centrifugo, memcache, and more
.agents/ — two expert subagent definitions for building services on top of jet
Install
go get github.com/zloevil/jet@v0.1.0
Requires Go 1.26+.

Status
Early release (v0.x): the API is still stabilizing and may change between minor versions. Issues and feedback are welcome.