Migrating from v1

Migrating from v1

v2.0 is a ground-up rewrite of the transport and server bus. Wire-format compatibility with v1 is intentionally broken — a v1 bundle cannot talk to a v2 server, and vice versa. Plan for a coordinated upgrade of server and bundles together, not a rolling one.

Full detail: CHANGELOG.md.

---

1. What was deleted

Removed	Replacement
v1 bundle transport — EventoSocketConnection, EventoServerClient, ClusterConnection, EventoSocketConfig, MessageHandler, ResponseSender, RequestHandler, EventoResponseSender (1 634 LOC)	BundleClient + the Netty transport
MessageBus.java in evento-server (1 099 LOC)	Composable BusLifecycle
v1 abstract ConsumerStateStore class and the v1 Postgres/MySQL modules	Five focused SPIs + evento-consumer-state-store-jdbc
Autoscale protocol — BundleDeployService, ClusterNodeIs{Bored,Suffering,Kill}Message, /spawn + /kill	Nothing. Your orchestrator owns scaling
evento-cli (2.0.0)	Automatic ASM self-discovery at startup
evento-parser (2.0.0)	Nothing — last consumer of the parser-based BundleDescription removed
Deploy-by-upload, docker-spawn.py, per-bundle env/VM options, autorun / deployable flags	External orchestration
JWT stack — AuthFilter, AuthService, TokenRole, AuthController	HTTP Basic against the Spring in-memory user

---

2. Configuration renames

v1	v2
evento.server.bus.v2.*	evento.server.bus.*
Gradle module evento-consumer-state-store-jdbc-v2	evento-consumer-state-store-jdbc

---

3. What changed conceptually

The protocol. JSON over a hand-rolled socket became CBOR over Netty, with 4-byte length-prefixed frames, a sealed Message hierarchy, transparent chunking (so no message size limit) and optional TLS. See Wire Protocol.

The server stopped understanding payloads. It routes on payloadType: String and carries payload: byte[] opaquely. No business class loading server-side.

Consumer state stopped being one class. The v1 abstract ConsumerStateStore became five interfaces — ConsumerStateStore, ConsumerLock, SagaStateStore, DeadEventQueue, DedupeStore — each independently implementable, with in-memory and JDBC implementations shipping.

The framework stopped managing instances. No deploy-by-upload, no spawn/kill, no autoscaling. It emits performance metrics; k8s or Nomad does the rest.

The CLI stopped being necessary. Bundles now publish full self-description at startup — component/handler/payload source paths and line numbers, repositoryUrl + linePrefix for clickable source links, and @EventoDescription for human-readable text — so the static-analysis publish and version-bump step is gone.

Tracing became honest. TracingAgent's default is a genuine no-op (telemetry and metrics only). Wire a custom agent or SentryTracingAgent for real distributed tracing.

---

4. Toolchain jump

	v1	v2.0	Current (2.4.0)
Java	21	25	25
Gradle	8.5	9.0	9.6.1
Spring Boot	3.2	3.5.5	4.1.0
Jackson	2.15	2.18.2 (+ CBOR)	2.22.1
Netty	—	4.1	4.2.16.Final

The v2.0 column is the rewrite baseline; the current column reflects the dependency sweeps that landed in 2.2.0 and 2.4.0.

---

5. Migration checklist

• Upgrade to JDK 25
• Replace any direct use of the deleted v1 transport classes with BundleClient / the gateways
• Rewrite custom consumer state stores against the five SPIs, or adopt evento-consumer-state-store-jdbc
• Run the Flyway V1 migration to create the evento_v2_* tables
• Rename evento.server.bus.v2.* properties to evento.server.bus.*
• Rename the Gradle dependency evento-consumer-state-store-jdbc-v2 → -jdbc
• Remove evento-cli from your build and drop the static-analysis publish step
• Replace deploy-by-upload / autoscaling with orchestrator-managed deployment
• Replace JWT-based API access with HTTP Basic (and set a real password)
• Set evento.server.bus.auth-token, since the default accepts all bundles
• Upgrade the server and all bundles together — the wire is incompatible
• Size the connection pool for one connection per active consumer — see Consumer State Store § 5

---

6. Then read these

Two behaviours introduced after 2.0 will affect how you run the system, and neither has a v1 equivalent:

• Parallel Consumers — opt-in; changes delivery and ordering guarantees when used
• Throughput and Capacity — the capacity model and its collapse mode

---

See also

• Release History — what landed when
• Architecture Overview — what replaced the v1 design