yes 1.3.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f6e32695a2368de9dbfcae480f960fba0e04261861593b172efb09c7122b723
-  data.tar.gz: c71415bdf839dd8eab46c16e3b11b1220ba9bfd04f8d0313f8a3194d197a6f0e
+  metadata.gz: 91e44ef887d4626f5a871e1a4ddccf41f45e58ff6c9e7d21500e3e04c6a252f6
+  data.tar.gz: 076b44cc8d84038b6720b9cf67f2404ff8f4a27f6e3b78e76778cf8de8f59785
 SHA512:
-  metadata.gz: 59af9e5d4773472bc52a809de3b4439ebbbb08fdccee010c9e324abacc5283820858bf7c337ab6b0ad7b956064a08536f1a6ebfe20ec5190a36cf52d120a03d7
-  data.tar.gz: b4456e11e06600b7123cc3640f6b6d32cead2d5199476a2593e87acb38e5608737bf7473c9a6dc2ef680561fe420f8dcdccc90d073a4ed33e2ae866c89b897a1
+  metadata.gz: 6b81da070eceb08e313a7c102758f77a622a4d2e1c61505c4975b041c381338319e1f2412e3b2e2386dad651d3cbccc2b1e6fd8751a63f59b0240fc1a6f1aa57
+  data.tar.gz: c45327b8bc188c4860e9befcdb07358ca328daa5010339d89abac247a0533090c04b4638435aef7a93bcda4fb9dcce7c941c4c6fd409f8119360ef4547e3a3b5

data/CHANGELOG.md

@@ -2,6 +2,198 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.3.0] - 2026-09-03
+
+### yes-core
+
+#### Added
+- `CommandHandling::RevisionConflictBackoff` and `RevisionConflictWaiting`: an
+  exponential, jittered backoff (10 ms → 1 s per attempt, 2 s in total) applied
+  between revision-conflict retries while the read model still lags the stream.
+
+#### Changed
+- `CommandExecutor` and `CommandGroupExecutor` wait for the read model to catch up
+  before retrying a `PgEventstore::WrongExpectedRevisionError` instead of retrying
+  immediately; conflicts the same process caused still retry at once.
+- The `ConcurrentUpdateError` retries take their delay from
+  `RevisionConflictBackoff.schedule`; timing unchanged.
+
+#### Fixed
+- `EventPublisher#verify_external_revisions!` and `Stateless::Handler#revision_error!`
+  raise `WrongExpectedRevisionError` with pg_eventstore's field order: `revision` is the
+  store's value, `expected_revision` the caller's. Both were inverted.
+
+## [2.2.0] - 2026-09-01
+
+### yes-core
+
+#### Added
+- `Authorization::LookupCache` — scoped memoization for the read-only lookups an
+  authorization pass repeats.
+
+  Caching is opt-in per scope: outside `LookupCache.with_scope` its `fetch` just yields,
+  so nothing changes for callers that do not open a scope. The store lives in
+  `ActiveSupport::IsolatedExecutionState`, so it is per thread/fiber, and `with_scope`
+  clears it on the way out — including when the block raises — so nothing leaks into the
+  next request. Nested scopes reuse the outermost cache.
+
+#### Changed
+- `Authorization::CommandCerbosAuthorizer` resolves the principal data and the
+  authorized resource through `LookupCache`.
+
+  Authorizing a batch of commands used to repeat both lookups once per command. The
+  principal data is derived purely from the request's auth data, and the commands of a
+  batch commonly act on the same resource, so both were re-read from the database for
+  every command — for an N-command batch, N times the queries for N identical results.
+  In production traces the two lookups accounted for the large majority of the authorize
+  span, dwarfing the Cerbos call itself.
+
+  This is safe because a batch is authorized in full before any of its commands is
+  executed, so no write can invalidate either lookup while the pass is running. Cached
+  values are shared between the commands of a pass and must be treated as read-only;
+  the per-command Cerbos payload is still built, and checked, per command.
+
+- The `Cerbos Authorize Command` span now tracks SQL, so the time it spends in-process
+  can be attributed to queries rather than guessed at.
+
+### yes-command-api
+
+#### Changed
+- `Commands::BatchAuthorizer` authorizes a batch inside a single
+  `Yes::Core::Authorization::LookupCache` scope, which is what lets the authorizers of
+  one batch share their principal and resource lookups.
+
+## [2.1.1] - 2026-08-22
+
+### yes-core
+
+- `Types::UUID` now accepts any RFC 9562 UUID version (1-8), not only v4.
+
+  pg_eventstore 3.0.0 moved event-id generation off the database's `gen_random_uuid()`
+  (always v4) to `SecureRandom.uuid_v7`. Those ids reach the gem as `causation_id` /
+  `correlation_id`, and a v4-only pattern makes `TransactionDetails.new` raise
+  `Dry::Struct::Error` — which fails the event handler and kills the subscription once
+  its restarts are exhausted.
+
+  Still a real constraint: version must be 1-8 and the variant nibble 8/9/a/b, so
+  arbitrary hex in UUID shape is rejected as before.
+
+  **Required for anything running pg_eventstore 3.x.**
+
+- Register a `failed_subscription_notifier` so a dead subscription reports to Sentry.
+
+  `config.failed_subscription_notifier` is pg_eventstore's only death signal — it is
+  called once, when a subscription exhausts its restarts and stays dead. Without it that
+  death is silent: per-failure errors are only recorded on the subscription row and are
+  never raised, so a subscription can stop processing indefinitely with no alert.
+
+  Registered only when the host application has loaded Sentry.
+
+  Shipped alongside the UUID fix deliberately: that fix addresses a bug which *kills*
+  subscriptions, and this is what tells you when one has died.
+
+## [2.1.0] - 2026-07-31
+
+### yes-core
+
+#### Added
+- `Middlewares::WriteEncryptor` — encrypts on `#serialize` exactly like `Middlewares::Encryptor`
+  (it subclasses it), but its `#deserialize` is a no-op.
+- `Middlewares.register_encryptor(key_repository, config:)` — registers `:encryptor` and
+  `:write_encryptor` together. Host applications should call this instead of assigning
+  `config.middlewares[:encryptor]` by hand; registering the decrypting encryptor on its own doubles
+  the encryptor round trips of every encrypted append.
+- `Middlewares.for_write` — the middleware keys to pass to `#append_to_stream`: every configured
+  middleware, with `:encryptor` swapped for `:write_encryptor`. Derived from the live config rather
+  than hard-coded, because `PgEventstore::Client` resolves a passed list with
+  `config.middlewares.slice(*list)`, which silently drops unregistered names — a literal list could
+  therefore resolve to one with no encryptor at all and write plaintext at rest. Falls back to the
+  full list when `:write_encryptor` is missing, and the railtie warns about that at boot.
+- `Middlewares::ENCRYPTOR` / `Middlewares::WRITE_ENCRYPTOR` config-key constants, and
+  `DataEncryptor::CIPHERTEXT_KEY` for the `es_encrypted` data key.
+
+#### Changed
+- Every write site now appends with `middlewares: Middlewares.for_write`, so an append no longer
+  decrypts the event it returns: `CommandHandling::EventPublisher`,
+  `CommandHandling::CommandGroupExecutor`, `Commands::Stateless::Handler` and
+  `TestSupport::EventHelpers#append_event`. This covers both `PgEventstore#multiple` paths, whose
+  sub-events publish through those same call sites.
+
+  pg_eventstore 3.0 runs every registered middleware's `#deserialize` on the events returned by
+  `#append_to_stream`, not only on reads. Nothing in yes-core reads `data` off that returned event —
+  `otl_record_response` records only type, revision, stream and positions, and `ReadModelUpdater`
+  always receives the command payload on the write path — so each encrypted append was paying an
+  uncached key lookup plus a decrypt against the encryptor service for a payload it discarded. Those
+  calls also ran inside the SERIALIZABLE transaction opened by `#multiple`, widening the window for
+  `PG::TRSerializationFailure` and its retries.
+
+  ⚠️ Consumers that relied on the appended event coming back decrypted must read the event instead.
+
+#### Fixed
+- `Middlewares::Encryptor#serialize` is now idempotent: it returns the event untouched when the data
+  is already encrypted. Required because the default middleware list holds two serialize-capable
+  encryptors once `:write_encryptor` is registered, so an append that omits `middlewares:` would
+  otherwise encrypt twice — the second pass encrypting the first pass's sentinels and overwriting the
+  real ciphertext irrecoverably. It also makes re-appending an event that was read at rest
+  (`middlewares: Middlewares.without(:encryptor)`) safe, which it was not before.
+
+## [2.0.0] - 2026-07-28
+
+Major bump because `yes-core` now requires `pg_eventstore` v3, whose schema is
+incompatible with v1. Released as 2.0.0 rather than 1.5.0 deliberately: consumers
+constrain these gems at `~> 1.3`, which 1.5.0 would satisfy, so a minor bump could
+be pulled in by an unrelated `bundle update` and put v3 code against a v1 store.
+2.0.0 makes that impossible.
+
+⚠️ **Do not adopt until your event store has been migrated to v3.** Migrating is a
+one-way, downtime-requiring operation — see the `pg_eventstore` upgrade notes.
+
+### yes-core
+
+#### Changed
+- **Breaking change**: `pg_eventstore` dependency `~> 1.0` → `~> 3.0`.
+- **Breaking change**: OpenTelemetry span attribute `event.link_id` is now
+  `event.link_global_position`, in `Commands::Stateless::Handler` and
+  `CommandHandling::EventPublisher`. `pg_eventstore` v3 drops `events.link_id`
+  (migration 13) in favour of the bigint `link_global_position`, so `Event#link_id`
+  raises `NoMethodError`.
+  **Update any dashboards or trace queries keyed on `event.link_id`.**
+
+### yes-auth
+
+#### Changed
+- **Breaking change**: `yes-core` dependency `~> 1.0` → `~> 2.0`, required to stay
+  resolvable alongside yes-core 2.0.0.
+
+## [1.4.0] - 2026-06-24
+
+### yes-command-api
+
+#### Added
+- Dispatch aggregate-DSL command groups over the HTTP command API. The deserializer now resolves the `<Context>::<Subject>::CommandGroups::<Name>::Command` class-name convention (generated by the `command_group` macro) in addition to the legacy top-level group, V2, and V1 conventions. The controller expands a `Yes::Core::Commands::CommandGroup` into its sub-commands for batch authorization and validation, while still passing the wrapped group to the command bus so the Processor dispatches it as one atomic unit.
+
+### yes-core
+
+#### Added
+- `Yes::Core::Commands::CommandGroup#to_h` now returns the flat input payload merged with reserved keys, so a group round-trips cleanly through `Class.new(to_h)` (used by the command bus' `add_metadata` and by the ActiveJob serializer). Reserved keys (`origin`, `batch_id`, `command_id`, `metadata`, `transaction`) now propagate to the aggregate group method through that round-trip.
+- `Yes::Core::ActiveJobSerializers::CommandGroupSerializer` now serializes aggregate-DSL `CommandGroup`s as well as the legacy stateless `Group`, so groups survive the async command queue.
+- `Yes::Core::Configuration#command_group_guard_evaluator_class` resolves a command group's guard evaluator from the `:command_group_guard_evaluator` registry, and `Processor#guard_evaluator_exists?` uses it for `CommandGroup` instances. A group registers its guard evaluator under that dedicated registry type, so without this the existence check raised `UnregisteredCommand` when a group was dispatched.
+
+#### Changed
+- `Yes::Core::Commands::Processor#run_command` no longer special-cases `CommandGroup` payloads; the flat `#to_h` makes a single code path correct for both single commands and groups (drops the `reinstantiate_with_reserved_keys` helper).
+
+## [1.3.1] - 2026-06-16
+
+### yes-auth
+
+#### Added
+- Rebuild the principals mirror rows on resource-access `Restored` events, so a restored read/write resource access re-materializes the principal it grants.
+
+### yes-core
+
+#### Fixed
+- `Yes::Core::Utils::HashUtils.deep_flatten_hash` now applies the `prefix` to array-valued keys, consistently with scalar and nested-hash keys. Previously an array value was keyed by its bare name (e.g. `deep_flatten_hash({ tags: [...] }, 'span')` produced `"tags"` instead of `"span.tags"`), so callers passing a prefix got a mix of namespaced and un-namespaced keys. Callers that pass no prefix are unaffected.
+
 ## [1.3.0] - 2026-05-18
 
 ### yes-core

data/README.md

@@ -365,14 +365,18 @@ command :change, :ssn, :string, encrypt: true
 
 Encryption is performed by a PgEventstore middleware that delegates the actual key management and cryptography to a `key_repository` object you provide. *Yes* does not ship a concrete implementation — you plug in any object that satisfies the interface below.
 
-Register the middleware:
+Register the middlewares:
 
 ```ruby
 PgEventstore.configure do |config|
-  config.middlewares[:encryptor] = Yes::Core::Middlewares::Encryptor.new(key_repository)
+  Yes::Core::Middlewares.register_encryptor(key_repository, config:)
 end
 ```
 
+This registers two middlewares against your repository: `:encryptor`, which decrypts events as they are read, and `:write_encryptor`, which encrypts identically but does not decrypt. pg_eventstore runs `#deserialize` on the event returned by `#append_to_stream` too, and nothing on the write path reads that event's data — so *Yes* appends with `middlewares: Yes::Core::Middlewares.for_write`, and your `key_repository` is never asked to decrypt a payload that is about to be discarded. Always register through `register_encryptor`: registering `:encryptor` alone silently costs a key lookup and a decrypt on every encrypted write.
+
+One consequence worth knowing: **the event returned by a command is encrypted**. Read the event back when you need its plaintext.
+
 The `key_repository` must respond to the following methods, each returning a [`Dry::Monads::Result`](https://dry-rb.org/gems/dry-monads/) (or any object responding to `success?`, `failure?`, and `value!`):
 
 | Method | Purpose | Returns (on success) |
@@ -833,6 +837,28 @@ A `command_group :foo` macro on `Context::Aggregate` generates:
 
 The legacy stateless `Yes::Core::Commands::Group` / `Yes::Core::Commands::Stateless::GroupHandler` are untouched and continue to serve cross-aggregate use cases declared outside the aggregate DSL.
 
+**Invoking via the Command API:** command groups are dispatchable over HTTP exactly like regular commands. POST to `/v1/commands` with the standard request shape — `command` is the group name (camelized), `data` is the flat payload (same as the Ruby invocation form):
+
+```json
+{
+  "commands": [
+    {
+      "context": "Companies",
+      "subject": "Apprenticeship",
+      "command": "CreateApprenticeship",
+      "data": {
+        "company_id": "...",
+        "user_id": "...",
+        "name": "Acme Apprenticeship",
+        "description": "Software dev role"
+      }
+    }
+  ]
+}
+```
+
+The Deserializer resolves the group's `Command` class via the registered `Context::Aggregate::CommandGroups::<Name>::Command` namespace. Authorization and validation run per-sub-command (each sub-command's existing `Authorizer` and `Validator` are invoked, exactly like the legacy stateless `Group` flow), and the group dispatches as a single atomic unit through the bus.
+
 ### Read Models
 
 Each aggregate automatically gets a corresponding read model (ActiveRecord model) that persists its current state. This is how you access attribute values from an aggregate.

data/lib/yes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yes
-  VERSION = '1.3.0'
+  VERSION = '2.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: 'yes'
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Nico Ritsche
@@ -15,56 +15,56 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 2.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 2.3.0
 - !ruby/object:Gem::Dependency
   name: yes-command-api
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 2.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 2.3.0
 - !ruby/object:Gem::Dependency
   name: yes-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 2.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 2.3.0
 - !ruby/object:Gem::Dependency
   name: yes-read-api
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 2.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 2.3.0
 description: Event sourcing framework for Ruby on Rails applications
 email:
 - nico.ritsche@yousty.ch