Skip to content

refactor: V4 - #463

Draft
ammodev wants to merge 770 commits into
version/26.3from
refactor/di-rebuild
Draft

ammodev wants to merge 770 commits into
version/26.3from
refactor/di-rebuild

Conversation

@ammodev

@ammodev ammodev commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Spring migration progress: https://claude.ai/artifact/H4vpCo9eciyX1YNQDMDJ38?sk=q9yUR2cy35fTWbkk0WkEig

The complete API rework planned in surf-api Umbau, as one PR.
The design behind it is in the Modulschnitt.
Supersedes #462, which GitHub closed when its head branch was renamed.

Two things happen here:

  1. The monolithic modules are cut into small -api / -impl pairs behind platform aggregates, so
    dev.slne.surf.api:surf-api-paper keeps its coordinate while the code behind it is split.
  2. The component framework is replaced by a real DI container — constructor injection, resolution
    over interfaces, a root/child hierarchy, scopes, conditions, post processors. requiredService<T>()
    and the scanning SurfComponent framework are gone.

4.0.0 breaks compatibility on purpose, and MIGRATION-4.0.md is the contract.
Read that first if you are here because a downstream repository stopped compiling.

Where to look

1500 files is not reviewable front to back. It is three kinds of change, and only the first needs
reading carefully:

Read this Why
foundation/di/ The whole design. ~2 800 lines of container plus 127 tests. Start at api/.../di/ContainerPlatform.kt and SurfContainer.kt (the two contracts), then impl/.../internal/BeanContainerImpl.kt (scopes and lifecycle) and impl/.../boot/SurfContainerHost.kt (who starts what).
platform/*/impl/.../di/*ContainerPlatform.kt Four adapters, one per platform, each documenting what its platform actually does. The Paper one explains has-open-classloader; the Minestom one explains why getResources could not be used.
foundation/di/impl/src/test/.../ClassLoaderIsolationTest.kt Paper's classloader modelled from real bytecode, with the failure mode Scope.SHARED has to avoid. The reasoning the rest of the design rests on.
MIGRATION-4.0.md Every break, with the reason.
buildSrc/ The three module conventions, checkApiBoundary, checkBeanGraph.
everything under common/*/api, common/*/impl Mostly git mv. Review with git log --follow or --find-renames; the ABI dumps are the real diff.

Each module cut was verified the same way, and that is the claim worth checking: the entries removed
from one ABI dump, with the package prefix rewritten, equal the new module's dump exactly. A move
that lost or added a declaration would show up there and nowhere else.

State

Phase State
Build foundation — conventions, BOM, api/impl boundary check done
Renames and aggregates done
surf-api-registry-keys pulled out done
DI contracts — foundation/di/{api,impl} done
The container, unit-testable without a server done
KSP processor writing META-INF/surf-api/beans/ done
Hierarchy, scopes, platform adapters done
surf-api itself onto the container done
Broker registrars out of scope — other repositories
Inventory framework de-duplicated done
fastutil removed done
surf-api-core cut into domains in progress
Old framework demolished, requiredService gone done
Machine-independent skills under .claude/skills/ done

What is left

  • The last core cuts: event, nbt + reflection, and the leftovers.
  • An integration test with a real Paper server in a container — the only thing that exercises
    Paper's own PluginClassLoader and the Scope.SHARED story end to end.
  • A build-time measurement before/after the registry-keys split.
  • One open decision, in the artifact as di-16: the relocating withSurfRedis /
    withSurfDatabaseR2dbc paths make Scope.SHARED unachievable for the canonical Redis example.
  • One open decision, as build-14: PlayerLookupService is called nowhere and is the only ktor
    user in any api module, so deleting it would take the ktor client out of surf-api-core-api's
    published surface. It removes a feature, so it needs a yes.

Two plan items were deliberately not done, with the reasons recorded as findings: selecting the
NmsProvider through a bean condition (nms-07 — it is a version resolver with a fallback rule the
container cannot express) and splitting the standalone bootstrap into api and impl (platform-14 —
bootstrapping runs before the container exists, so it cannot reach its implementation as a bean).

Do not read the checks per commit. A rebuild PR passes through states where a rename has landed and
its consumers have not; they are meant to be read at the end.

🤖 Generated with Claude Code

- implement main function to bootstrap SurfApiStandalone and connect to NATS server
- create playground function for publishing and subscribing to messages
- define PubSubMessage data class for message structure
- implement request-reply dispatcher for handling messages
- add timeout handling for requests to prevent indefinite waiting
- log received requests and responses for better traceability
- create build.gradle.kts files for surf-nats-api, surf-nats-core, surf-nats-paper, and surf-nats-velocity
- implement publishing configuration to slneReleases repository
- add InternalNatsApi annotation for API validation
- set up dependencies and plugins for each module
- implement NATS connection manager with connect and disconnect methods
- add NATS configuration class for server and authentication settings
- introduce environment variable support for NATS configuration
- add test instance and server for NATS integration testing
- bind the test NATS container client port to a fixed host port so restarts keep the URL valid
- add TestNatsServer.restart() to restart the container
- add test verifying the connection reconnects after a server restart and accepts a flush
- log the last connected server URL on disconnect instead of null
- log IOExceptions from the error listener as a single line without stack trace
- pin the SLF4J provider to log4j for tests so INFO logs are not dropped
- add NatsClient interface with methods for publishing events and service registration
- implement NatsClientFactory for creating NATS client instances
- add extensions for simplified service registration and retrieval
- define WireFormat enum for message serialization formats
…rialization support

- add NatsClient interface and implementation for managing NATS connections
- introduce NatsCodec for encoding and decoding messages in CBOR and JSON formats
- add validation for NATS client names to ensure kebab-case format
- implement tests for NatsClient functionality and codec operations
…assFile API

- implement ListenerInvoker interface for event handling with coroutines
- create ListenerInvokerFactory to generate invoker classes dynamically
- add tests for ListenerInvoker functionality and bytecode verification
…istenerInvokerFactory

- annotate ListenerInvoker and ListenerInvokerFactory with @InternalNatsApi
- indicate that these classes are part of the internal API
… handling

- introduce EventDescriptor class to manage event metadata
- implement NatsEvent annotation for event class definitions
- add EventSubjects utility for subject validation and formatting
- create tests for EventDescriptor and EventSubjects functionality
…atsCodec and EventDescriptor

- rename serializersModul to serializersModule for consistency in NatsCodec
- update EventDescriptor to use the corrected serializer method
…sClientImpl

- add publish method to encode and send events with headers
- include payload size validation against NATS server limits
- create checkPayloadSize method for size validation
- add NatsClientPublishTest for testing publish functionality
- introduce EventListenerRegistration for managing listener lifecycle
- implement EventSubscriptions for handling event subscriptions
- add ListenerMethod utility for discovering listener methods
- enhance NatsClientImpl to support event listener registration
…S RPC handling

- add ArgumentSerializer for serializing and deserializing RPC arguments
- implement ResultKind interface for handling different result types
- create ServiceDescriptor for managing service methods and their metadata
- add NatsService and NatsTimeout annotations for service method configuration
- introduce ResponderMode enum for defining responder behavior
- implement custom serializers for specific use cases
- add RpcCaller interface for handling remote procedure calls
- implement RpcCallerImpl with request timeout and error handling
- introduce NatsRpcException and its subclasses for specific error cases
- add NatsTimeout annotation for specifying timeouts on service methods
- enhance NatsHeaders with new constants for deadline and error handling
… utility

- replace manual mapping of primitive types to their wrapper classes
- utilize Primitives.wrap for cleaner and more maintainable code
- add ServiceRegistration class for managing service lifecycle and subscriptions
- introduce ServiceInvoker interface and factory for dynamic invoker creation
- implement HandleInvokerClasses for generating method handle classes
- add tests for ServiceInvoker and ServiceRegistration functionality
- implement PresenceAnnouncer to manage service presence announcements
- add PresenceTracker to track active service instances
- modify ServiceRegistration to start presence announcer on registration
- update RpcCaller to handle ALL responders with presence tracking
- implement LargePayloadTest for testing large argument and result roundtrips
- introduce PayloadStore for offloading large payloads to object storage
- update NatsHeaders to include PAYLOAD_REF for offloaded messages
- modify RpcCallerImpl and ServiceRegistration to handle offloaded payloads
- add JetStreamProvisioner to handle stream creation and updates
- introduce PayloadBucket enum for transient and persistent payloads
- update PayloadStore to support bucket selection for offloading
- modify RpcCallerImpl to utilize new PayloadBucket for offloading
- enhance tests to cover new functionality and ensure reliability
…osed

- introduce a new scope variable to manage coroutine context
- update coroutine launches to use the new scope for better context management
- introduce ClientOrigin class to store creation time, thread, source, and stack trace
- implement capture method to gather relevant information during NatsClient creation
- update NatsClientImpl to include origin information
- add tests to verify ClientOrigin functionality and ensure accurate metadata capture
- implement NatsMinestomEntrypoint for Minestom integration
- create PaperBootstrap for Paper plugin initialization
- add InstanceImpl and PaperNatsInstance for data path management
- update PaperMain to handle plugin disable logic
- implement Benchmark object for performance measurement of functions
- create ChatListener to log test chat events
- add MicroserviceNatsServiceImpl and MicroserviceNatsTestInstanceImpl for service registration
- introduce PaperNatsServiceImpl and PaperNatsTestInstanceImpl for paper integration
- update build.gradle.kts for new dependencies and configurations
…ng improvements

- rename origin to clientOrigin in NatsClient for clarity
- update event subscription handling to use clientOrigin
- enhance listener methods to support ignoreOwn functionality
- introduce NatsEventContext for better event context management
- update visibility modifiers for several classes and methods to internal
- improve encapsulation and restrict access to implementation details
…method calls

- rename AllRespondersTest to AllNatsRespondersTest for clarity
- update timeout method calls from withNatsTimeout to withNatsCallTimeout
- adjust related test assertions to reflect method name changes
ammodev and others added 27 commits November 9, 2026 13:53
Its source line named `common/core/api/.../core/inventory/framework/internal/`,
which no longer exists -- the platform-neutral half is surf-api-inventory-api
now, internals included. The skill also says which aggregates carry it and
which do not, because that is the one place the core split changed what an
aggregate resolves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both named `common/core/api/.../core/` paths the core split emptied. The events
skill also carried the old FQN inside a failure message it tells people to
expect, which is the worst kind of stale: it would have had someone searching
for a string the container no longer prints.

Each now says the module exists and that no build file names it, and the events
skill says why the implementation stayed in surf-api-core-impl.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`LastSeenMessagesValidator.trackedMessages` is declared as fastutil's
`ObjectList<LastSeenTrackedEntry>` on Paper 26.3, and a `VarHandle` is
resolved by a field's *exact* declared type. Asking for `java.util.List`
therefore failed with `NoSuchFieldException` even though every
`ObjectList` is a `List`.

The failure landed in `V26_3NmsReflectionsImpl`'s static initialiser,
which resolves all 33 handles at once, so it was reached as soon as any
bean touched the v26-3 provider -- `SurfGlowingApiProxy`'s constructor
did, during `startRoot`. The whole root container failed to build and
surf-api's Paper plugin did not load at all on a real 26.3 server.

Every other field, method and constructor the interface declares was
checked against `net/minecraft` in paper-26.3-245; this was the only
mismatch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`ClassLoaderIsolationTest` proves what a mismatched class loader topology
does to a shared bean, but it has to build its loaders itself. Nothing in
the repository started a server, which is how two bootstrap defects
reached a green build.

Three local-only modules close that gap:

- `paper-shared-bean-provider` declares an interface of its own and a
  `@Service(scope = Scope.SHARED)` implementation of it, and runs its own
  child container through all three phases.
- `paper-shared-bean-consumer` declares the provider as a Paper
  dependency with `join-classpath: true`, takes that interface as a
  constructor parameter and logs one line derived from the injected
  instance: the greeting only the provider can produce, plus whether the
  interface the consumer casts to is the one the instance implements.
- `paper-shared-bean-test` assembles a server directory around a pinned
  Paper build with surf-api's shadow jar and the three plugins its
  descriptor requires, starts it, reads its log, asserts on that line and
  shuts the server down.

The test lives in a `paperTest` source set and belongs to no lifecycle
task, so `check`, `test` and CI never reach it; CI does not even see the
modules, since `local/` is only included for a local build. Run it with

    ./gradlew :surf-api-paper-shared-bean-test:paperSharedBeanBootTest

Its inputs are pinned by URL and sha256 and cached under the build
directory together with the assembled server, so a second run reuses
Paper's extracted libraries and the ones LuckPerms fetches for itself. A
missing network, a moved release or a checksum that no longer matches
aborts the test with that reason instead of failing it. Anything after a
successful assembly fails, quoting the log lines about the three plugins
and the tail of the server log.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A real Paper server found that it did not. Routing a shared bean's instance to
the root was never enough: every lookup goes through a container's own
definitions, and those are fixed when the container is built from its owner's
metadata. So a bean one plugin declared was invisible to the next plugin's
resolver, and the consumer failed with "no bean provides it". Dropping the
scope to a plain @service produced a byte-identical failure, which is the
clearest statement of the defect: SHARED made no observable difference to
another application. What it did do was give one instance when two applications
each declared the same bean class.

The declaring container now publishes the provider into the root, beside the
root's own definitions rather than inside them -- the two answer different
questions, and a reader should not have to work out which kind of entry they
are looking at. Resolution carries the ids it has already answered so a bean
reachable from two places in the chain comes back once, and each container
still instantiates its own candidates, because where a bean is cached depends
on which container creates it.

The ordering this cannot escape is now part of the contract: a shared bean is
published when its application starts, so a consumer has to start afterwards.
That is not a limitation to work around -- on Paper the consumer must declare
the publisher as a BEFORE dependency anyway, or the interface is loaded twice
and the instance it gets cannot be cast.

Also fixes a double enable() I introduced with the phase split: an adopted
shared component sits in the root's lifecycle list, so enabling it on adoption
ran it again when the root enabled. It is now brought up to whatever state the
root is already in -- which on Paper means the root enables it, since a plugin
starts its container during the server's load phase.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two string comparisons, and the first one needs no hypothetical release to
bite: `"26.10".startsWith("26.1")` is true, so a server on 26.10 -- the next
minor -- silently selected the 26.1 bindings. It would then start, and the
first reflected member that moved between the two versions would throw
somewhere unrelated to the cause.

The second picks the fallback with `maxByOrNull { it.versionPrefix }`, which
reads like "the newest" and is not: with 26.10 present it answers 26.3, because
'3' > '1'. A fallback that selects the wrong bindings is worse than none.

NmsVersion now keeps its prefix as numbers and matches component by component,
so 26.10 is not 26.1 and 26.3.1 still is 26.3. A version it cannot parse matches
nothing instead of throwing inside a lazy initialiser that every NMS call would
then re-enter.

The comparator is `internal` rather than private so a test can feed it versions
the enum does not list. That is the point: with the four entries that exist
today a text sort produces the same order, so nothing asserted about this enum
could tell the two implementations apart. Restoring either defect now fails a
case.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… too

The fastutil removal rewrote this one declaration in all three version modules,
from ObjectList to MutableList, and all three were correct before it. A
VarHandle is looked up by the field's exact declared type, so every one of them
throws NoSuchFieldException against a server that holds the field as
ObjectList -- in a static initialiser that resolves all 33 handles at once,
reached while the root container is being built. The plugin is then skipped
entirely.

Only 26.3 was fixed, because 26.3 is the version the new boot test starts. The
other two were broken in exactly the same way and nothing would have said so
until someone ran a 26.1 or 26.2 server. Each site now carries the reason, so a
future type sweep reads it before changing it back.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ot itself

`copyMissingBundles(dataFolderResourceBundles, dataFolderResourceBundles)`
passed the same list as both arguments, so step 1 asked which of the data
folder's bundles are missing from the data folder. Nothing ever is.

This does not make the class work -- see the finding. It makes the line say
what the comment above it says, and it is wrong under every reading of the
surrounding code, which the rest is not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three places called `MiniMessage.miniMessage()`, which has none of surf's tags,
so `<primary>`, `<prefix>`, `<note>` and `<small>` were rendered as literal
text: a scoreboard title, a sidebar line, and -- the clearest one -- Velocity's
MiniMessage command argument, which exists to accept MiniMessage from a user
and then refused half of surf's own vocabulary.

The swap is safe because the configured instance is built with `editTags`,
which adds to MiniMessage's standard set rather than replacing it, so the
gradients the first two assemble keep working. The class doc now says that, so
the next reader does not have to check the builder to find out whether reaching
for the vanilla instance costs anything.

Two doc corrections found while reading: the tag list omitted `<note>` and
`<small>`, and `toSmallCaps` claimed uppercase letters are left unchanged. They
are not -- every letter is lowercased before lookup, so `A` comes out as `ᴀ`
and case is lost. That is reasonable for a label and worth knowing before
passing a name through it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ping it

The default suspending click provider launches on the CoroutineScope it was
rendered with. A click arrives whenever the player gets round to it, by which
time a command executor's scope is long finished -- and `launch` on a finished
scope drops the work silently, so the page button does nothing, forever, with
nothing in the log.

This does not fix it: the caller has to pass a scope that outlives the message,
and there is no process-wide scope in this module to fall back on. What it does
is make the failure findable, and say at both declarations which scope is
required and why. Changing the api so the scope cannot be wrong is a decision
for the owner; it has no caller in this repository, so there is time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
All three carried their whole `initialize()` body as a comment, which reads as
"temporarily switched off" and is not. They declare no proxy at all -- the 26.x
modules have none -- and restoring that body would be wrong anyway: it builds a
ReflectionRemapper for *reobfuscated* names, and Paper has shipped Mojang-mapped
since 1.20.5, so there is nothing to translate.

So the comment goes and the reason takes its place, including where a reflective
member belongs now: `@ReflectedField` or `@ReflectedMethod` on the module's
NmsReflections interface, which the processor turns into a VarHandle. Calling
initialize() without declaring anything gets nothing and says nothing, which is
the trap this records.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
PropertyService caught every exception from loading the file, logged a warning
and returned an empty node. So a YAML file that exists and cannot be parsed was
indistinguishable from one that is not there -- after which
@ConditionalOnProperty's matchIfMissing decides, and a server starts with every
guarded feature on whichever side its default happens to be, with a logged
warning nobody reads as the only trace.

It also made documentation I wrote today false: all four ContainerPlatform
implementations promise that a failure to read a file that is there is not
caught. It was, one layer down.

An absent file, and a path that is not a regular file, still mean "not set" --
absence is a legitimate answer to a condition. A present file that will not
parse now throws, naming the path. Caffeine caches nothing for a failed mapping
function, so correcting the file is enough; a test pins that, because it is the
reason for throwing rather than caching an empty node.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- add docker.jvmOptions with HotSpot 25 defaults: G1 with periodic GC and native heap trimming,
  compact object headers, MaxRAMPercentage=60.0, ActiveProcessorCount=2, ExitOnOutOfMemoryError
- add docker.memoryBudget (default 1g), written as SURF_MICROSERVICE_MEMORY_BUDGET and applied as
  -XX:MaxRAM only when cgroup v2 shows no memory limit up to the cgroup root
- generate an entrypoint script at /usr/local/bin/microservice-entrypoint via RUN printf; it starts
  java with jvmOptions, then the budget, then JAVA_OPTS
- set MALLOC_ARENA_MAX=2 in the generated image
- reject jvmOptions with whitespace or shell metacharacters and memory budgets that are no size
- start the spark profiler with the service only when SURF_MICROSERVICE_SPARK_PROFILER=true;
  spark commands stay available and other values fail the start
- document JVM settings, the 2026-11-09 benchmark and spark profiler behavior in README
- add plugin tests for default settings, appending and replacing options, and validation errors
- add AGENTS.md with project instructions for Codex
…line-first admission

- add DeadlineLimiter: caps running handlers per service registration and admits waiting handlers
  earliest deadline first, in arrival order for equal deadlines
- split permits into SHORT and LONG lanes; LONG handlers (fan-outs and calls with more than the
  core default timeout left) may hold at most half of the permits
- run requests and persistent calls in ServiceRegistration only after a permit is granted; drop
  requests whose deadline passes while waiting, terminate such persistent RPCs and nak fire calls
  with backoff
- rank fire calls last by giving them a deadline of FIRE_MAX_DURATION
- add max-concurrent-handlers (default 20, RpcDefaults.MAX_CONCURRENT_HANDLERS) and
  max-concurrent-handlers-by-service config keys, overridable via SURF_NATS_MAX_CONCURRENT_HANDLERS
- document the limit and admission order in README
- add DeadlineLimiterTest and HandlerLimitTest with a LimitedService limited to one handler
…rf-nats process

- add offloadPayload to offload oversized bodies to the payload bucket, stamping Surf-Deadline
  once and rejecting lifetimes above the bucket TTL before the upload
- add awaitRunningHandlers to block until running handlers complete or a deadline passes
- add DeliveryCause and DeliveryDisposition to map how a persistent delivery attempt ended,
  the call flow and the delivery count to ack, nak, term or dead letter
- add ContractResolver with MemberResolver, EnumResolver and ServiceResolver to resolve the
  Kotlin shape of generated messages, enums and services and report problems in a fixed order
- add ProtocGenProcess for protoc-gen-surf-nats with plugin request, response and parameter
  types, ES file and import path helpers and typed protobuf-es externals
- add tests for the rpc helpers, the contract resolver and the problem order
…jvm code

- NatsEventDeduplicator: Object2LongLinkedOpenHashMap -> LinkedHashMap, evict via pollFirstEntry
- DeadlineLimiter: ObjectRBTreeSet waiter queues -> TreeSet
- EventSubscriptions, RpcCallerImpl: Object2ObjectOpenHashMap/ObjectOpenHashSet -> HashMap/HashSet
- NatsClientImpl, ListenerMethods, ServiceDescriptor, GeneratedDescriptors: ObjectArrayList,
  ObjectOpenHashSet, ObjectLinkedOpenHashSet -> ArrayList, HashSet, LinkedHashSet
- replace fastutil isEmpty property calls with isEmpty()
- disable acquire retry (acquireRetry 1 → 0); a retry restarts the acquire timeout at the end of the
  queue
- lower default max-acquire-time-millis from 10000 to 5000
- lower default max-create-connection-time-millis from 30000 to 5000
- document in README that acquires are not retried, that max-acquire-time-millis should stay at or
  below the caller's RPC timeout (5 s for core surf-nats calls), and that initial-size is the pool's
  minimum size
- replace fastutil collections with stdlib LinkedHashSet, HashSet and toMutableList in MigrationSpec
  and FlywayMigrationRunner setup-time code
…e and reliability

- use ArrayList instead of ObjectArrayList in ActiveOperation, CommandLineTokenizer
  and MicroserviceLifecycle
- return events.toList() instead of ObjectImmutableList from ActiveOperation.complete
- remove the now unused fastutil imports
- add KDoc to the api module: client, registration, listener, descriptors, recipients, timeouts,
  idempotency keys and persistent call context, limits, interceptor and reply
- add KDoc to core runtime, rpc delivery, codec, config, connection, jetstream, bytecode
  invokers, payload store and presence tracking
- add KDoc to the js client, its options and errors, and the nats and protobuf-es externals
- expand the TypeScript declarations in index.d.mts with docs and examples per operation
- add KDoc to the protocol module, the gradle plugin tasks and codegen, the platform entry
  points and the type serializers
- README: add sections on microservices, the NATS server, transient failures of persistent
  calls, intercepting persistent calls and the TypeScript client, and rewrite installation
- docs/external-callers.md: rewrite the TypeScript client guide and the wire format reference

- add total and long-lane handler limits via NatsHandlerLimits.setDefaults and NatsConfig
  (max-concurrent-long-handlers, by service, SURF_NATS_MAX_CONCURRENT_LONG_HANDLERS)
- return DeadlineLimiter.Admission (GRANTED, EXPIRED, CLOSED), close the limiter on drain and
  pick the lane per method from its flow and timeout
- reject expired and draining persistent deliveries with DeliveryCause.EXPIRED and DRAINING,
  settle them with dedicated exceptions and summarize no-slot warnings in NotAdmittedLog
- cancel scopes and unregister services in finally blocks on close and drain
- generate a forNumber companion function for enums and use it in the enum serializer
- make js publish fire-and-forget and remove PublishOptions.timeoutMs
- add tests for handler limits, admission, NotAdmittedLog and delivery dispositions

BREAKING CHANGE: js SurfNatsOperations.publish returns void instead of Promise<void> and
PublishOptions no longer accepts timeoutMs.
- rewrite README.md as the v3 guide: modules, build setup, main class and migration discovery,
  name and data directory, database and migrations, NATS handler limits, lifecycle and
  integrations, commands, health checks, command socket, local runs, Dockerfile generation,
  environment variables, logging, transactional services and the upgrade path from v2
- rewrite the KDoc of the api, database, reliability, runtime, processor and gradle plugin
  modules to state contracts, defaults, ordering and failure behavior
- expand DatabaseCustomizer KDoc with the full list of defaults and a usage example
- enable explicitApi() and Kotlin ABI validation in the api, database and reliability modules,
  excluding declarations annotated with @InternalMicroserviceApi, and add public modifiers
  and explicit types to all public declarations
- add the initial .api dumps for the api, database and reliability modules
- enable strict explicit api mode for the reliability test fixtures
- size the default surf-nats handler limits to the database pool after migrations: twice the
  pool size in total, half of it (at least one) for long-running handlers
- add surf-nats-core as a compileOnly dependency of the database module and skip the limits
  when surf-nats is absent, the pool size is unknown or the surf-nats version lacks
  NatsHandlerLimits.setDefaults
- add tests for the pool-sized handler limits and their application in DatabaseIntegration
- use Kotlin multi-dollar string interpolation in the generated Dockerfile entrypoint script
…un in UTC

- add public `poolMaxSize` property to DatabaseApi, set to `pool.sizing.max-size` for config-built
  instances and `null` for instances built on a caller-supplied ConnectionFactory
- add DatabaseApiTest cases for both poolMaxSize variants
- add FlywayTimeZoneIT running SQL and JDBC migrations through the Flyway runner with the JVM zone
  set to America/New_York on MariaDB and PostgreSQL, asserting a UTC session zone and a stored
  wall-clock time within 5 minutes of the run
- add vendor-specific V1__zone_probe.sql migrations creating and filling the zone_probe table
- merge the full history of surf-nats at feat/proto-first-kmp (05ad3d9)
- rewrite every path of that history to live under infra/nats/
- merge the full history of surf-redis at master (dd92333)
- rewrite every path of that history to live under infra/redis/
…ra/database-r2dbc

- merge the full history of surf-database-r2dbc at feat/flyway-migrations (5e24048)
- rewrite every path of that history to live under infra/database-r2dbc/
…icroservice

- merge the full history of surf-microservice at feat/v3 (612e80e)
- rewrite every path of that history to live under infra/microservice/
…f-api build

- include surf-nats, surf-redis, surf-database-r2dbc and surf-microservice from infra/ as project
  trees, renaming every module from surf-* to surf-api-* under group dev.slne.surf.api, version 4.0.0
- turn tooling/gradle-plugin into an included build and move the surf-nats and surf-microservice
  Gradle plugins into it as dev.slne.surf.api.gradle.nats and dev.slne.surf.api.gradle.microservice
- substitute dev.slne.surf.api coordinates with the local projects, selecting the shaded variant for
  modules that publish only their shadow jar, and add the buildSrc helper shadowed(...)
- wire root publish and check to the included plugin build and share processorVersion with it
- set group and version of the infra modules centrally and run the auto-service KSP processor for
  them, which the surf plugin no longer adds
- merge the infra version catalogs into the root catalog and remove their wrappers, settings,
  workflows and IDE files
- adapt the infra sources to surf-api 4: moved packages, ServiceLoader-based requiredService
  helpers, SurfReflection.INSTANCE, no fastutil helpers and no runServer
- replace fastutil with JDK collections in surf-redis
- rename the npm package to @slne/surf-api-nats and the ABI dumps to the new module names
- add surf-api-standalone-testing, which starts the standalone runtime once per test JVM
- add the redis release jars to the publish workflow and document the move in MIGRATION-4.0.md

BREAKING CHANGE: the infra artifacts moved to dev.slne.surf.api:surf-api-*, the surf-nats and
surf-microservice plugin ids changed, Paper/Velocity plugin names gained the surf-api- prefix and
surf-redis returns JDK collections instead of fastutil types.
…n favor of surf-nats

- delete dev.slne.surf.redis.event and dev.slne.surf.redis.request packages, the hidden-class
  invoker templates and the event codec tests
- remove eventBus, requestResponseBus, publishEvent, subscribeToEvents, registerEventCodec,
  registerEventType, sendRequest, registerRequestHandler and redisListenerScope from RedisApi
- remove bus factories and origin/metadata injection from RedisComponentProvider and its impl
- delete now unused Mono.asDeferred, Tuple2 destructuring operators and KotlinSerializerCache
- drop the JMH event transport benchmark, the jmh plugin and the unused
  kotlinx-serialization-json test dependency from surf-redis-core
- keep SyncStreamWakeupBus, which sync structures still use internally
- regenerate the surf-api-redis-api ABI dump (deletions only)
- update README, RedisApi KDoc and MIGRATION-4.0.md to point to surf-nats
- replace the surf-redis example in the InvokerFactory javadoc with SurfSyncEventInvoker

BREAKING CHANGE: surf-redis no longer provides events or request/response messaging; use
surf-nats listeners and services instead.
@twisti-dev twisti-dev changed the title refactor: module restructure and DI container rebuild refactor: V4 Nov 12, 2026
@mergify mergify Bot added the conflict label Nov 14, 2026
@mergify

mergify Bot commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

👋 ammodev your PR is conflicting and needs to be updated to be merged

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants