startback 1.2.4 → 2.1.0

data/CHANGELOG.md

@@ -0,0 +1,954 @@
+## 2.1.0 - 2026-09-30
+
+Ruby 4.0 support, docker images for several ruby versions, and the Bunny
+event bus finally under test -- which is how two silent bugs and a RabbitMQ
+4.3 incompatibility came to light.
+
+**Almost nothing here asks anything of you.** Startback's API is unchanged
+and the bus upgrade needs no broker-side migration. The one thing that does
+move: the un-suffixed docker tags go from Ruby 3.3 to Ruby 3.4, a minor
+bump. The details are below because the *reasons* matter, not because there
+is much to do.
+
+### Ruby 4.0 is supported
+
+The test grid now runs **Ruby 3.2, 3.3, 3.4 and 4.0** -- the whole range
+`required_ruby_version` allows, so the floor is a tested claim rather than an
+assumed one. Startback needed no source change for 4.0: the gem,
+`startback-jobs`, `startback-web` and the example application's webspicy
+specs are green on all four, with no deprecation warning from Startback's own
+code.
+
+`required_ruby_version` stays `>= 3.2`.
+
+### Docker images are released for Ruby 3.4 and 4.0
+
+Images are built for each ruby version of the release matrix. The tags that
+name no ruby version follow `DEFAULT_MRI_VERSION`, which is **Ruby 3.4**:
+2.0.0 published them from Ruby 3.3, so `enspirit/startback:api` and `:web`
+move by one minor version here, and stay put from now on.
+
+| Tag | Ruby |
+|---|---|
+| `enspirit/startback:api`, `:api-2.1.0`, `:api-2.1` | 3.4 (was 3.3 in 2.0.0) |
+| `enspirit/startback:api-ruby3.4`, `:api-2.1.0-ruby3.4`, `:api-2.1-ruby3.4` | 3.4 |
+| `enspirit/startback:api-ruby4.0`, `:api-2.1.0-ruby4.0`, `:api-2.1-ruby4.0` | 4.0 |
+
+Same for the `web` target. **No Ruby 3.3 image is published any more**: an
+application pinned to `:api-ruby3.3` stays at 2.0.0 and should move to
+`:api-ruby3.4`. Only `DEFAULT_MRI_VERSION` in the Makefile publishes the
+un-suffixed tags, so adding a ruby version to the matrix can
+never change what `:api` means depending on which release job finished last.
+`make images.all` walks the whole matrix the way the release workflow does.
+
+The `web` image moves from **nodejs 20 to nodejs 22**, node 20 having reached
+end of life in April 2026.
+
+### The Bunny event bus is now covered by the test suite
+
+It was the one part of Startback with no automated coverage, on the grounds
+that the grid had no broker. It now has one, and 19 specs that talk to it for
+real -- mocking bunny would only assert that Startback calls the methods
+Startback calls. They cover connecting, autoconnect, the emit/listen round
+trip, fanout across processor queues, type isolation, adoption of a
+pre-existing topology, and the asynchronous contract that emit errors must
+not reach the emitter.
+
+Without a broker those specs skip, so `make tests` stays green for a
+contributor without docker; `make rabbitmq.up` starts one through the new
+`docker-compose.yml`. CI sets `STARTBACK_SPEC_REQUIRE_BUNNY=1`, which turns
+"no broker" into a failure, because otherwise a broken service container
+would take the coverage away without anything turning red.
+
+### The bus stops working on RabbitMQ 4.3, and now does not
+
+`queue_options` defaulted to `{}`, which declares a *transient non-exclusive*
+queue. RabbitMQ deprecated that, and flips it from `permitted_by_default` to
+`denied_by_default` in 4.3:
+
+| RabbitMQ | transient non-exclusive queues | Startback <= 2.0 bus |
+|---|---|---|
+| 4.0, 4.1, 4.2 | permitted | works |
+| **4.3+** | **denied** | **`listen` receives nothing, then `Timeout::Error`** |
+
+The defaults are now durable for both the exchange and the queue, which is
+also what a named processor queue wants: events waiting in it outlive a
+broker restart instead of being dropped, and a durable queue bound to a
+transient exchange would come back after a restart with nothing routing to
+it.
+
+```ruby
+fanout_options: { durable: true },
+queue_options:  { durable: true },
+```
+
+**No migration is required, deliberately.** AMQP refuses to redeclare an
+object with different properties, so on a broker up since an older Startback
+declared its topology the durable declaration is rejected with
+`PRECONDITION_FAILED`. Rather than make that your problem, the bus *adopts*
+whatever is already there (`passive: true` matches an existing object
+whatever its properties) and logs a warning. Transient objects do not survive
+a broker restart, so the durable declaration takes over by itself at the next
+one, with nobody having done anything.
+
+Left alone that would have been a nasty upgrade: `emit` runs inside
+`stop_errors`, so the rejection was swallowed and the application went on
+returning 200s while silently dropping every event.
+
+Applications already passing their own `queue_options`/`fanout_options` are
+unaffected: explicit options still win.
+
+### Two silent bunny bugs fixed
+
+Both predate this release and neither announced itself:
+
+* **A dead channel was cached forever.** A channel-level error closes the
+  channel, and the bus kept one per thread without checking it was still
+  open. One such error therefore broke the bus for that thread permanently --
+  every later `emit` failing with `cannot use a closed channel`, for *any*
+  event type, swallowed by `stop_errors`. The channel is now renewed when
+  found closed.
+
+* **Declaring could unsubscribe your listeners.** A rejected declaration
+  closes the channel it happened on, which was the shared one carrying the
+  consumers. Topology is now probed on a scratch channel, memoized per
+  connection so `emit` does not pay for it on every call.
+
+### Known wart, documented rather than fixed
+
+A Bunny listener receives the raw JSON `String` off the queue, where a
+`Bus::Memory::Async` listener receives a `Startback::Event`. Listeners are
+not portable between the two busses. The bus even carries a `factor_event`
+method for this, defined and never called. A spec pins the current
+behaviour; changing it would break every existing listener.
+
+### Other changes
+
+* CI housekeeping: `actions/checkout` v2/v3 -> v4, `actions/setup-node` v3
+  -> v4 on nodejs 22 (14 was long end of life, and it is the javascript
+  runtime `startback-web`'s sprockets specs need), `docker/login-action` v1
+  -> v3. The image release workflow reads the version to tag from
+  `github.ref_name` rather than `git describe --contains`, which silently
+  yielded nothing on a shallow checkout and downgraded a release to
+  unversioned tags.
+
+* The 2.0.0 notes said `benchmark`, `json`, `logger` and `ostruct` stop being
+  default gems "in Ruby 3.5". That release became 4.0, and `json` is still a
+  default gem there. Corrected in place.
+
+## 2.0.0 - 2026-09-29
+
+Major dependency upgrade. Sinatra 4 (hence Rack 3) is now required, and the
+ranges of the other dependencies are widened so that their latest major
+release is picked by default while applications remain free to pin an older
+one in their own Gemfile.
+
+**Startback's own API is unchanged.** Every class, require path, constructor
+argument and public method behaves as in 1.2.x. The major bump is about the
+dependency floor, and about what that floor asks of the applications built on
+top -- which is most of what follows.
+
+**See [UPGRADING.md](UPGRADING.md) for the migration guide**: what you will
+see, why, and what to do about it. The short version is that a typical API
+service needs two changes, setting `RACK_ENV` and lowercasing the response
+triples it builds by hand.
+
+### BREAKING: Sinatra 4 and Rack 3 are now required
+
+Startback's own middlewares now rely on `Rack::Headers`, which only exists in
+Rack 3. There is no way to stay on Sinatra 3 with this release.
+
+* **Response headers must be lowercase.** The Rack 3 SPEC states that header
+  keys "must not contain uppercase ASCII characters". Any place where your
+  application builds a response triple by hand, e.g.
+  `[200, {"Content-Type" => "application/json"}, [body]]`, must now use
+  `"content-type"`. Nothing crashes if you don't, but a Rack 3 middleware
+  looking the header up in lowercase will not find it and will happily add its
+  own, so the response goes out with the header twice. This is exactly the bug
+  that `AutoCaching` and `CorsHeaders` had, and that this release fixes.
+
+* **Response bodies must respond to `each` or `call`.** A bare String is no
+  longer a valid body: `[404, {}, "NotFound"]` must become
+  `[404, {}, ["NotFound"]]`.
+
+* Rack 2-only middlewares in your stack (anything using the removed
+  `Rack::Utils::HeaderHash`, or `Rack::File`) will break. This is the usual
+  Rack 2 to 3 migration and is not specific to Startback.
+
+* **`Rack::Protection::HostAuthorization` is enabled by Sinatra 4.** In the
+  `development` environment — which is the one used whenever neither `RACK_ENV`
+  nor `APP_ENV` is set — only `localhost`, `*.localhost`, `*.test` and IP
+  literals are accepted as `Host`. Anything else gets a `403 Host not
+  permitted` before reaching any route. In every other environment the check is
+  disabled, so *production deployments are not affected*. What is affected:
+
+  - local development behind a custom hostname or a docker-compose service name;
+  - test suites, since `Rack::Test` issues requests against `example.org`.
+
+  Set `RACK_ENV` (`test` in test suites, as Startback's own specs now do), or
+  configure the permitted hosts explicitly:
+
+      class MyApi < Startback::Web::Api
+        set :host_authorization, { permitted_hosts: [".my-app.internal"] }
+      end
+
+### BREAKING: Ruby >= 3.2 is now required
+
+Declared through `required_ruby_version`, because that is what bunny 3,
+finitio 1.0, http 6, json 3 and nokogiri 1.19 all require. Ruby 3.1 reached
+end of life in March 2025 and was never part of the test matrix.
+
+### BREAKING: `JSON.fast_generate` is gone
+
+Removed by json 3. Startback used it in `Security::RateLimiter` and
+`Caching::EntityCache#encode_key`, both of which now use `JSON.generate`. The
+generated keys are identical, so caches and rate limit counters are not
+invalidated. Applications calling `JSON.fast_generate` themselves must do the
+same substitution.
+
+### BREAKING: rack-robustness 2 is now required
+
+`Web::Shield` and `Web::CatchAll` subclass it. 2.0.0 requires Rack 3, and
+emits lowercase header names everywhere -- including the last resort
+response, the one returned when error handling itself fails, which is a raw
+Rack triple and so never went through `Rack::Response` normalization. That
+was the only genuinely Rack 3 non-compliant response Startback produced.
+
+It also normalizes the header names given to its DSL, fixing a silent bug
+where `g.headers('content-type' => ...)` lost to the `'Content-Type'`
+default. Startback spells it `content_type` and never hit that one, but
+applications configuring their own `Shield` subclass in lowercase did.
+
+### Dependencies whose major version is now the default
+
+Startback does not use most of these itself: they are shipped as a convenience,
+and their ranges have been widened rather than moved, so `< 4.0` style
+constraints in your own Gemfile keep working. A plain `bundle update` will
+however resolve to the newest of each, and each has its own breaking changes:
+
+* **puma 6 -> 8** (`>= 6.0.2, < 9.0`). Puma 7 renamed every lifecycle hook
+  (`on_worker_boot` -> `before_worker_boot`, and so on), made `preload_app!`
+  the default in clustered mode, and lowercased its response headers. Puma 8
+  changed the default production bind from `0.0.0.0` to `::` when an IPv6
+  interface is available, which matters for container port publishing.
+
+* **jwt 2 -> 3** (`>= 2.1, < 4.0`). This one has teeth: RSA keys must now be at
+  least 2048 bits, base64 decoding follows RFC 4648 strictly, the payload
+  cannot be read before the signature is verified, `HS512256` is dropped, and
+  custom algorithms must include `JWT::JWA::SigningAlgorithm`. Since 3.3, code
+  that rescues `JWT::DecodeError`, `JWT::IncorrectAlgorithm` or `ArgumentError`
+  *around `JWT.encode`* must rescue `JWT::EncodeError` instead. Applications
+  doing anything non-trivial with JWT should read its `UPGRADING.md` and pin
+  `jwt` themselves if they are not ready.
+
+* **bunny 2 -> 3** (`>= 2.14, < 4.0`). Used by `Event::Bus::Bunny::Async`.
+  Versioned delivery tags are removed, passive declarations are no longer
+  replayed by topology recovery, and the `openssl` gem >= 3.3 is now required,
+  which means a native build in slim images.
+
+* **finitio 0.12 -> 1.0** (`>= 0.12, < 2.0`). Two changes affect `.fio`
+  schemas: the `Fixnum` and `Bignum` aliases are removed (use `Integer`), and
+  the `FalseClass` alias is fixed — it used to be an alias of `.TrueClass`, so
+  it accepted `true` and rejected `false`. A schema that worked around that bug
+  now means the opposite of what it did.
+
+* **http 5 -> 6** (`>= 5.0, < 7.0`) and **nokogiri**, **tzinfo**, **i18n**,
+  **mustache**: unchanged ranges or widened, never loaded by Startback itself.
+
+### Other changes
+
+* `Web::HealthCheck` now returns a lowercase `content-type` header, as do
+  `Jobs::Support::JobResult::Embedded` and `::Redirect` in `startback-jobs`.
+  HTTP header names are case-insensitive and every client normalizes them, so
+  this only matters if you assert on the raw Rack triple.
+
+* Development dependency on `webspicy` is dropped from `startback.gemspec`:
+  Startback's own specs never used it. `rack-test`, which used to arrive
+  transitively through it, is now an explicit development dependency.
+
+* `benchmark`, `json`, `logger` and `ostruct` are now explicit runtime
+  dependencies. They are required by `lib/startback.rb` and stop being default
+  gems in Ruby 4.0 -- `json` excepted, which is still one there.
+
+* The example application and both contrib gems moved to webspicy 1.0, whose
+  own ranges are what makes finitio 1.0, http 6 and rack-robustness 2.0
+  reachable at all here: every 0.27.x release capped the three of them. On the
+  way through 0.27 they also started validating unstructured response bodies
+  against `output_schema` instead of skipping them.
+
+### Known gaps
+
+* The Bunny event bus has no automated coverage — the test matrix has no
+  RabbitMQ — so bunny 3 is upgraded but unverified by the suite. Likewise,
+  `http`, `jwt`, `puma`, `nokogiri`, `tzinfo`, `i18n` and `mustache` are never
+  loaded by Startback, so the suite says nothing about their new majors.
+  *(The bus is covered as of 2.1.0.)*
+
+* Applications testing with webspicy must move to its 1.x line. Every 0.27.x
+  release requires `finitio < 0.13`, `http < 6.0` and `rack-robustness < 2.0`,
+  which conflicts with what Startback now asks for: bundler fails to resolve
+  rather than quietly holding a version back.
+
+## 1.2.4 - 2026-09-01
+
+* Allow bmg 0.24.0
+
+## 1.2.3 - 2026-03-31
+
+* Fix redactor when handling invalid string encoding.
+
+## 1.2.2 - 2026-02-03
+
+* Add `emits_on_commit` event hook to avoid race conditions between sender and
+  receiver against the database.
+
+## 1.2.1 - 2025-09-03
+
+* Add :fail strategy and dynamic options to Startback::Security::RateLimiter
+
+## 1.2.0 - 2025-09-03
+
+* BREAKING change: only ruby 3.3 is kept in build & test matrix.
+
+* Don't debug caller on WARN message about default logger.
+
+* Exposed `logger_for` publicly in Robustness module, in addition to `log`.
+
+* Added SpyLogger that helps integration tests wanting to lightly observe
+  call flows.
+
+* Added Startback::Security::RateLimiter to help limiting operation executions
+  as a security measure.
+
+* Added Env#test?, in addition to production? and development?
+
+## 1.1.0 - 2025-02-09
+
+* Added ruby 3.3 to the build & release matrix
+* Ruby dependencies upgraded in a backward compatibility way.
+
+## 1.0.3 - 2024-06-27
+
+* Allow usage of Bmg 0.23.x, that makes no broken API.
+
+## 1.0.2 - 2024-04-24
+
+* The Bus abstraction now exposes a `connected?` method, implemented by the
+  various implementations.
+
+## 1.0.1 - 2023-10-25
+
+* Tracer and LogFormatter now both use the Redactor, that correctly redacts
+  credentials in URLs.
+
+## 1.0 - 2023-06-23
+
+This gem is used in production for several years, so we bump it to 1.x to use
+better semantics versioning schemes. See README for the definition of the public
+API.
+
+* BREAKING: the `base` `api` and `engine` gems have been removed.
+
+  The main `startback` gems provides what base/api/engine already provided (they
+  were actually the same), while `-web` became a contrib, like `-jobs`.
+
+* BREAKING: Only `api` and `web` docker images are kept, while `web` will be
+  discontinued in the future. You can use the api image for engine, as it was
+  the same.
+
+* BREAKING: the images no longer have the startback gem installed. You have to
+  install it yourself as part of your own `bundle`.
+
+* BREAKING: the `engine` default CMD is no longer provided by default.
+  For reference, we used `bundle exec puma -t 1:1 -w 0 -p 3000 config.engine.ru`
+  that you probably want to add to your own docker image. We recommand using
+  a `puma.rb` file instead, and rely on the default command of the `api` image.
+
+* Upgraded dependencies, notably http (5.x), tzinfo (2.x) and webspicy (0.26.x).
+  This may force clients to upgrade them as well.
+
+## 0.19.4 - 2023-06-22
+
+* Fix a bug in EntityCache error handling: do not hide primary key resolution
+  issues.
+
+## 0.19.3 - 2023-06-22
+
+* Fix backward compatibility bug when using entity_cache without loading the
+  entire caching module.
+
+## 0.19.2 - 2023-06-22
+
+* Improved Caching::EntityCache with more observability and error handling.
+
+  A Prometheus listener is now provided and can be installed via options passed at
+  cache construction (or via subclass overriding). An option also allows not raising
+  errors when the cache fails, and loading the entity instead. One is supposed to at
+  least log or monitor those errors.
+
+## 0.19.1 - 2023-06-01
+
+* Startback::Support::Env exposes the development?, staging? & production? helpers
+
+## 0.19.0 - 2023-05-26
+
+* BREAKING: drop support for ruby < 2.7
+* Upgraded webspicy to 0.24.x
+* Upgraded finitio to 0.12.x
+
+## 0.18.2 - 2023-05-19
+
+* Ensure all tracing spans are propagated properly even upon catch.
+
+## 0.18.1 - 2023-05-19
+
+* [startback-jobs] BREAKING: the context may no longer be provided as input to the CreateJob operation (`opContext`). The operation itself dumps the current context. Fork it if required before calling the operation.
+
+## 0.18.0 - 2023-05-19
+
+* BREAKING: Audit::Trailer is removed and replaced by Audit::Tracer, inspired by open telemetry.
+  The following changes are necessary:
+
+    1. Replace `around_run(Audit::Trailer.new)` by `around_run(Audit::OperationTracer.new)`
+    2. (optional) Make sure an instance of `Tracer` is available on the context
+    3. (optional) Make sure you add an instance of `TraceLogger` as listener on that tracer
+    4. (optional) Use the Audit::Middleware to reattach to existing traces provided by api callers
+       through the X-Span-Id and X-Trace-Id HTTP headers.
+
+* [startback-websocket] BREAKING: contribution is discontinued and removed. Please use Pusher instead.
+
+* [startback-jobs] BREAKING: Bmg minimal dependency is now 0.21.0, to get a startback-jobs bug fix.
+
+  The keys of the jobs created by 0.17.x are not the same as those created by 0.18.x. Finding a job
+  by id may fail even if the job exists.
+
+* [startback-jobs] BREAKING: the context may no longer be provided as input to the CreateJob operation (`opContext`). The operation itself dumps the current context. Fork it if required before calling the operation.
+
+* The data logs are now pretty printed by default in development mode.
+
+* Sensitive data sanitization (now called "redacting") now hides emails and adresses. The redactor
+  no longer remove hash entries, but replaces the values by a '---redacted---' string.
+
+## 0.17.4 - 2023-04-20
+
+* Fix wrong return in proc
+
+## 0.17.3 - 2023-04-20
+
+* Allow event emitters to decide not to emit anything at a later time (ignore event data when it is nil).
+
+## 0.17.2 - 2023-04-20
+
+* Adds the possibility to start only :sync or :async agents in Engine#create_agents
+
+## 0.17.1 - 2023-03-07
+
+* API#loaded_body now supports x-www-form-urlencoded and returns
+  a dup of the request params.
+
+* [startback-websocket] Add a way to unsubscribe from a room.
+
+## 0.17.0 - 2023-02-22
+
+* Upgraded sinatra to 3.x
+* Upgraded webspicy to 0.23.x
+
+## 0.16.0 - 2023-01-24
+
+* Upgraded puma to 6.x
+
+* The .api and .web images no longer specify default -t
+  (threads) and -w (workers) options to puma commandline.
+
+  One should use PUMA_MIN_THREADS, PUMA_MAX_THREADS and
+  WEB_CONCURRENCY envionment variables instead. For the record,
+  the default values (under MRI & puma 6.0.x) are 0, 5 and 0
+  (no forking model), respectively.
+
+  Stricly speaking, this is a broken API, even if you will
+  probably not notice the change.
+
+  Also, note that the .engine image now uses `-t 1:1 -w 0`,
+  which should be backward compatible as well. We stopped
+  using the workers mode, since only one worker makes little
+  sense.
+
+* Default ruby version is now 3.1 instead of 2.7
+
+  If you need ruby 2.7, you must say it explicitely, e.g.
+  `enspirit/startback:base-0.16-ruby2.7`
+
+## 0.15.5 - 2023-01-11
+
+* [startback-jobs] add support for job failures. Failed jobs
+are considered ready (`isReady: true`) but have a new flag
+(`hasFailed: true`) that tracks the failure. The failure
+itself is dumped in `opResult`. The API that serves the job
+result always dumps the `opResult` and uses a 200 status code
+in case of success and 272 in case of failure.
+
+## 0.15.4 - 2022-10-13
+
+* BadRequestError and subclasses (40x) are now logged in WARN
+  severity instead of ERROR by the Trailer. This is considered
+  a good idea on almost all Enspirit projects, so we dare doing
+  it on a tiny version bump (angel emoji).
+
+## 0.15.3 - 2022-09-30
+
+* Rebuilding of docker images on latest ruby versions.
+
+## 0.15.2 - 2022-08-03
+
+* Allow finitio 0.11 to be used. It's safe.
+
+## 0.15.1 - 2022-06-22
+
+* Fix Web::CorsHeaders. An empty value is not allowed, the
+  header should simply not be present.
+
+## 0.15.0 - 2022-06-22
+
+* POSSIBLY BREAKING: when a Finitio::TypeError is raised
+  (typically by an operation failing to validate its input),
+  the `location` field of the error is now dumped. This may
+  possibly break webspicy tests that validate error responses
+  very strictly.
+
+* Web::CorsHeaders now support more bouncing options and can be
+  used to whitelist some urls (with wildcards) that are
+  authorized to bounce.
+
+## 0.14.4 - 2022-06-15
+
+* Removed startback-tests.gemspec that is not a valid gem
+  anyway.
+
+## 0.14.3 - 2022-06-15
+
+* [startback-jobs] properly let inspect a job and its embedded
+  results.
+
+
+## 0.14.2 - 2022-06-08
+
+* [startback-websocket] Fix inclusion of javascript files in gem.
+
+## 0.14.1 - 2022-06-08
+
+* Fix the build chain: release of ruby gems.
+
+## 0.14.0 - 2022-06-07
+
+* Fix Engine: memoize the bus and run main agent class in
+  addition to its subclasses.
+
+* BREAKING: Remove serverengine and webrick. Engines should now be started with
+  puma and a config.engine.ru instead of engine.rb
+
+## 0.13.0 - 2022-05-31
+
+* Contributes Startback::Model, Startback::Services, as well
+  as Startback::Support::DataObject and Startback::Support::World
+
+* Added the notion of context world, through Context.world,
+  Context#world and Context#with_world.
+
+* Context.new yields the context instance if a block is given
+
+* Bmg minimal dependency is now 0.20.0
+
+* POSSIBLY BREAKING: Operation now has a default constructor that
+  expects a Hash and installs it under `@input` with an attr_reader.
+
+  This may break the audit trailer and/or bus dump for legacy
+  operations that named their input `request`.
+
+## 0.12.3 - 2022-05-25
+
+* Event.json is idempotent.
+
+## 0.12.2 - 2022-05-20
+
+* See 0.12.0, same release
+
+## 0.12.1 - 2022-05-19
+
+* See 0.12.0, same release
+
+## 0.12.0 - 2022-05-19
+
+This release enhances the event layer of Startback with the
+Event, Bus, Engine and Agent collaborating classes.
+
+Unfortunately it comes with a couple of BREAKING changes:
+
+* `Context::Middleware` now longer takes a context_class
+  option, but simply a Context instance (or subclass). That
+  instance will be duped and result installed in Rack env.
+  Doing so allows building a default context instance with,
+  e.g. a logger, and make sure it will be properly reused.
+
+* `Startback::Bus` is moved to `Startback::Event::Bus`
+
+* `Startback::Event.json` contract has changed. The default
+  contract expects the event type to be a fully classified
+  class name (subclass of Event) and will attempt to factor
+  one. The second argument is no longer a world (Hash) but
+  a context instance to attach to the event. A context fork
+  is made, using the event context data passed through the
+  Context h_factory (if event contains context info).
+
+* `Startback::Engine` constructor takes ServerEngine options
+  under a `:server_engine` key (was the options themselves).
+
+* `Startback::Agent` has a new protocol that relies on agent
+  instances and the presence of an `Engine`. The `listen` class
+  method no longer exists. You must use the `sync` and `async`
+  instance methods instead. Your agent instance should be
+  created withing the engine (see `create_agents` and
+  `auto_create_agents` there)
+
+* `Bus::Bunny` now has `autoconnect: false` by default. You
+  should explicit connect your engine instance instead.
+
+* `Bus::Bunny` now has `abort_on_exception: true` by default.
+  It's much safer but you need a supervisor like Kubernetes
+  in pratice.
+
+## 0.11.6 - Unreleased
+
+* Extend the Bus abstraction with connect/disconnect.
+
+* Bunny::Async now has an autoconnect option (defaulting to true
+  for backward compatibility) that can be used to avoid connecting
+  too early.
+
+* Bunny::Async now has `:abort_on_exception` and
+  `:consumer_pool_size` options that control the main channel
+  behavior. Their default values are chosen to stay backward
+  compatible.
+
+## 0.11.5 - 2022-05-18
+
+* Add Startback::Support::Env with `env` and `env!` helper
+  methods.
+
+* Startback no longer includes a trace in the warning message
+  sometimes seen because one uses the default logger.
+
+* Added Startback::Event::Agent class, for agents reacting to
+  events on a bus.
+
+* Added Startback::Event::Engine class, that runs an infinite
+  loop using ServerEngine and includes a Webrick small rack
+  app with a default and overridable healthcheck behavior.
+
+## 0.11.4 - 2022-05-18
+
+* Allow logging Strings & Exceptions directly in both trailer
+  and Robusness helpers.
+
+## 0.11.3 - 2022-05-10
+
+* Keep allowing `require 'audit/trailer'` alone without an
+  error.
+
+## 0.11.2 - 2022-05-10
+
+* Audit::Trailer and Audit::Prometheus support any op object
+  responding to `op_name` and `op_data` and use them in
+  priority over dedicated logic to extract logging info.
+
+  Their `#call` method are now part of the public API and
+  can thus be called by end-user code.
+
+## 0.11.1 - 2022-05-10
+
+* We no longer let the Sinatra layer dump errors in log.
+
+## 0.11.0 - 2022-04-21
+
+* Require bmg >= 0.19.0
+
+## 0.10.1 - 2021-12-23
+
+* Add support for causes in Startback::Errors::Error
+
+* The Shield rack middleware dumps the causes to json, provided
+  they are subclasses of Startback::Error.
+
+* Error & their causes are now properly dumped in the audit
+  trail.
+
+## 0.10.0 - 2021-12-22
+
+* Add support for operations's transaction policy and transaction
+  manager helper
+
+* Fix audit trail on multi operations. The op_data recursively
+  collect data of sub operations.
+
+## 0.9.1 - 2021-12-13
+
+* Fixing thread safetiness of async bus (bunny channels)
+
+## 0.9.0 - 2021-08-27
+
+* BREAKING CHANGE: all docker images now run Puma as app on port 3000 instead
+of root on port 80.
+
+* Upgrades uglify.js to 4.2, to enable support for ES6.
+
+## 0.8.3 - 2021-05-25
+
+* Update dependencies for security patches.
+
+## 0.8.2
+
+* Release gem in jenkins pipeline.
+
+## 0.8.1
+
+* Web::Api#serve not support Path instances as entities to serve. Sinatra's send_file is
+  then used on the path. DTOs returning Path instances are supported too.
+
+## 0.8.0 - 2021/03/12
+
+- Bumped finitio to 0.10
+- Bumped webspicy to 0.20
+- Bumped bmg to 0.18
+
+## 0.7.6 - 2020/12/11
+
+* Include version.
+
+## 0.7.5 - 2020/12/11
+
+* Prometheus metrics include startback_version and have customisable with prefix and labels.
+
+## 0.7.4 - 2020/12/10
+
+* Move prometheus-client as a dependency for base.
+
+## 0.7.3 - 2020/12/08
+
+* Add prometheus auditor and rack middleware exposing metrics for
+  operations. The auditor implements the around_run contract.
+
+      # Usage example:
+      around_run(Startback::Audit::Prometheus.new)
+
+      # ... in api (exposing /metrics endpoint)
+      use Startback::Web::Prometheus
+
+## 0.7.2 - 2020/08/27
+
+* Api#with_context and Operation#with_context allow running a block
+  with an ephemeral context. The original one is restored after the
+  block execution.
+
+      # With an explicit context created from scratch
+      ctx = ...
+      with_context(ctx) do
+        # will be run using `ctx`, instead of the original one
+        run MyOperation.new
+      end
+      ... # original context is restored here
+
+      # With a context dup
+      with_context do |ctx|
+        ctx.foo = "bar"
+        # will be run using `ctx`, instead of the original one
+        run MyOperation.new
+      end
+      ... # original context restored; foo=bar is no longer true
+
+* DateTime and Time monkey patches are corrected regarding `to_s`
+  when the latter takes a parameter (activesupport does).
+
+* Bmg "0.17.5" is now a minimum.
+
+## 0.7.1
+
+* Context#dup now correctly cleans all factored abstractions.
+
+## 0.7.0
+
+* Bumped bmg dependency to 0.17.x to get recent optimizations and bug
+  fixes.
+
+## 0.6.0
+
+* Docker images now have the startback gem install together with all
+  dependencies. This saves build time of image users, since many gems
+  that require native extensions are already installed and will be
+  reused by bundler.
+
+## 0.5.5
+
+* All docker images now run the software as app:app, for improved security.
+
+## 0.5.4
+
+* Docker images added for the various variants we have: base, api, web,
+  engine.
+
+## 0.5.3 - 2019/10/23
+
+* Added a `Startback::Caching::NoStore` abstraction, the easiest way
+  to disable caching in practice.
+
+## 0.5.2 - 2019/10/23
+
+* Fine-tuned `Robustness` once again, to trace when default logger is
+  (incorrectly?) used.
+
+* Fixed `EntityCache` and `CatchAll` logging to use the context when
+  defined and avoid therefore to end up on the default logger.
+
+## 0.5.1 - 2019/10/19
+
+* Improved `EntityCache` with a protocol to convert candidate keys to
+  primary keys. The class documentation and vocabulary has been improved
+  to be more intuitive for users with a relational database background.
+
+  Methods `full_key` and `load_raw_data` are renamed in a backwards
+  compatible way to `primary_key` and `load_entity`, respectively. The
+  old methods will be removed in 0.6.0.
+
+* Improved `EntityCache` with logging. Cache hits are logged in debug.
+  Cache miss & outdated are logged in info.
+
+* Fine-tuned `Robustness`, log & audit trail to make them easier to use.
+  In particular, the 25 lines of the backtrace are dumped in `op_data`
+  on fatal errors.
+
+## 0.5.0 - 2019/10/16
+
+* BREAKING CHANGE: Operation#bind no longer returns new operation
+  instances, it mutates the operation on which it is called. This is to
+  prevent counterintuitive behaviors when operations are passed around
+  while binding is actually rather hidden.
+
+* BREAKING CHANGE: Web::CatchAll only dumps 10 stacktrace lines, to
+  prevent logs from growing too much, and make sure that logs under
+  passenger do not end up being broken.
+
+* Add support for run `around` hooks in `Web::Api`, through an
+  OperationRunner support module. The same module is included by
+  the `Operation` class itself, since it can run sub operations.
+
+* Before (resp. after) hooks are added to the `Operation` abstraction.
+  They are called right before (resp. after) `call` by operation runners,
+  that is `Web::Api` and `Operation` itself.
+
+* Introduce an `operation_world` overridable method to participate
+  to the world construction in `Web::Api`. This aims at preventing
+  `run` cowboy overriding.
+
+* The `Context` abstraction now has a dump & reload protocol that allows
+  being passed around in a distributed architecture.
+
+* The `Context` abstraction now acts as a factory for related abstractions.
+  That factory has a caching mechanism, to prevent creating the same classes
+  over and over again and reduce memory footprint.
+
+* Add Startback::Web::Middleware helper module, that gives access to the
+  running context installed by Startback::Context::Middleware under a
+  simple `context` method.
+
+* Add eventing support through the `Startback::Event` and `Startback::Bus`
+  abstractions. Please `require 'startback/bus'` explicitely to use them.
+
+* Add `Startback::Caching::EntityCache` abstraction and protocol for making
+  caching and invalidation easier on individual objects.
+  Please `require 'startback/caching/entity_cache'` explicitely to use them.
+
+* Add log & audit trail abstractions, through the `Stackback::Audit::Trailer`
+  class. The class can be registered as an operation's around callback and
+  will dump a json log of operation executions and their timing.
+
+## 0.4.5 - 2019/06/24
+
+* [CatchAll] Log error message and error backtrace as two different lines,
+  to avoid message being stripped because the stacktrace is too long.
+
+## 0.4.4 - 2019/03/12
+
+* Startback::Web::HealthCheck correctly returns an empty array as third
+  rack 204 response, to meet the spec and avoid crashes with webrick.
+
+## 0.4.3 - 2019/03/08
+
+* `Context::Middleware.context(env)` can now be used to return the context
+  installed on an environment. To avoid having to know the key itself that
+  might change in the future.
+
+* The Errors module now expose many utility methods to raise errors without
+  having to know all error classes. Those methods are available in Operation
+  and Api instances. The module can also be included by users to get the new
+  methods available elsewhere.
+
+* The error `No method unsupported_content_type` is now fixed when a media
+  type is unsupported. A correct 415 HTTP error is returned instead.
+
+* Ruby's NotImplementedError are now catched by the Shield and transformed
+  to a 501 HTPP response.
+
+* Severe errors catched by CatchAll are not logged with both the message and
+  the full stack trace.
+
+## 0.4.2 - 2019/03/08
+
+* Startback::Web::AutoCaching no longer overrides Cache-Control headers
+  set down the middleware chain. It trusts existing headers by default.
+
+## 0.4.1 - 2019/03/06
+
+* Add a NgHtmlTransformer tool to MagicAssets. Useful for angular assets
+  with a component folder structure.
+
+## 0.4.0 - 2019/03/06
+
+* BREAKING CHANGE: the various web components are not longer required by
+  default. The user must require each component it uses.
+
+* Add a Startback::Web::AutoCaching rack middleware to help setting
+  the Cache-Control header in development/production environments,
+  according to middleware construction parameters and/or environment
+  variables.
+
+* Add a Startback::Web::CorsHeaders rack middleware to help setting
+  the various Cross-Origin Response Headers correctly, while supporting
+  good default values and configuration through middleware construction
+  parameters and/or environment variables.
+
+* Add a Startback::Web::MagicAssets middleware and application, to help
+  managing js/css assets using Sprockets.
+
+## 0.3.2 - 2018/11/27
+
+* Subclassing error classes keep orginal status codes, unless overriden
+
+## 0.3.1 - 2019/01/30
+
+* Fix file upload raising an exception about `file` not being defined.
+
+## 0.3.0 - 2018/10/12
+
+* Enhanced CatchAll to support an `error_handler` on the context. Fatal
+  exceptions are passed to the error handler when provided.
+
+## 0.2.0 - 2018/09/26
+
+* Context::Middleware now accepts a `context_class` option allowing
+  to specify a subclass of Context as actual context class. This allows
+  application to make the context more specific without monkey patching
+  Startback classes.
+
+* Main abstractions cleaned and documented
+
+## 0.1.0
+
+Birthday