Chenile 2.1.30

Chenile 2.1.30 is the follow-on release to 2.1.29. It adds opt-in workflow persistence selection, a startup-loaded JDBC Query Catalog, reliable process-worker failure reporting, and Azure Event Hubs delivery extensions. Existing deployments retain their prior behavior unless they enable a new feature.

Deployment summary

There is no broad framework database migration. The only framework-owned schema introduced in this release is the optional Query Catalog schema described below.

JDBC Query Catalog

The optional catalog loads MyBatis mapper XML and query metadata from a deployment-managed database once, during application startup. It is intended for reviewed operational promotion of query definitions, not live editing: there is no write API, polling loop, or hot reload.

Enablement and migration

Apply chenile-query-catalog-schema.sql with Liquibase, Flyway, or the application’s approved schema migration process. It creates:

• chenile_query_mapper_source for global mapper XML, keyed by namespace.
• chenile_query_definition_source for base or tenant query definitions, keyed by (scope_key, query_name).

The runtime service account needs SELECT on these tables only. Use a separate migration/admin identity for inserts and updates. Then expose a dedicated read-only Spring DataSource and enable the catalog:

query:
  catalog:
    jdbc:
      enabled: true
      dataSource: queryCatalogDataSource
      baseScope: __base__

With the catalog enabled, query.mapperFiles and query.definitionFiles may be omitted for a catalog-only deployment. During migration, catalog rows override matching packaged mapper namespaces or matching (scope, external query name) definitions; unrelated packaged definitions remain available.

Invalid enabled XML/JSON, duplicate mapper namespaces, scope/name mismatches, a missing catalog datasource, or a query definition whose statement is absent fails application startup. Promote catalog SQL first, then restart or roll out the application. Roll back by disabling query.catalog.jdbc.enabled and deploying the previous packaged configuration; catalog rows are not mutated by runtime code.

See Chenile Query and JDBC Query Catalog for table rules, tenant overrides, and validation examples.

Workflow EntityStore selection

Workflow persistence can now select a different Spring EntityStore per request without modifying the base workflow module. Selection is evaluated for declared EntityStore interface operations in this order:

1. Tenant-prefixed store, for example tenant2VehicleEntityStore.
2. Context-prefixed store using the configured chenile.workflow.entity-store.context-keys order.
3. An application EntityStoreSelectionStrategy bean.
4. The original base store.

Only a tenant that differs needs an override bean. For example, an application with five tenants can define only tenant2VehicleEntityStore; the other four still use vehicleEntityStore. Missing, empty, invalid, or incompatible candidates continue through the selection chain safely.

chenile:
  workflow:
    entity-store:
      context-keys: x-chenile-region-id,x-chenile-apt

For custom operations, declare an application interface extending EntityStore; do not expose the operation only on the concrete implementation. This keeps future interface methods automatically eligible for selection. Test tenant override and base fallback with create, retrieve, and workflow processing before promotion.

See Extending STM workflows for the full store contract and tenant/context strategy examples.

Process-worker failures now reach the daemon

Worker payload failures are now reported to the process daemon instead of merely being logged while the worker reports success. A malformed payload, incompatible known field type, missing payload type, or worker invocation failure completes the matching work as an error, rather than leaving a run indefinitely in a pending state without an error record.

Unknown JSON properties are accepted for worker payload deserialization. This allows additive producer payload evolution, but known properties with incompatible types still fail and are reported correctly.

After rollout, verify a controlled malformed payload in non-production produces the expected daemon error event and local worker log. Update monitoring to alert on process errors; a previously silent stalled run now becomes an observable failed work item. No configuration is required. Rolling back restores the previous worker behavior and should be avoided while untriaged failures are being investigated.

Azure Event Hubs

Per-message partition routing

Publishers may choose the Event Hubs partition behavior for an individual message through the properties passed to asyncPublish:

Only one routing mode may be selected. partition-id and partition-key cannot be combined, and auto cannot be combined with either. Invalid combinations fail before send; an invalid explicit partition id falls back to partition 0 for compatibility. Use a partition key for per-aggregate ordering and auto for throughput-oriented independent events.

Logical-topic message handlers

Applications can register a transport-neutral ChenileMessageHandler for a logical topic. Azure dispatches to exactly one matching handler before the legacy EventProcessor path. If no handler matches, the existing processor remains responsible for the message. More than one matching handler is a failure, and handlers must be idempotent because broker delivery can be retried before checkpoint commit.

Verify topic ownership at startup/integration-test time and monitor handler failures using the existing consumer retry/checkpoint behavior. See the Azure configuration guide for routing examples and tenant Event Hub naming guidance.

Meaningful Git changelog

All other synchronized 2.1.30 module commits are version alignment only and are excluded from this meaningful changelog.

Recommended rollout order

1. Promote 2.1.29 first if applications will use numeric JPA IDs; perform any application-owned schema/data work separately.
2. Apply and validate the Query Catalog schema before enabling that optional 2.1.30 feature.
3. Deploy 2.1.30 with Query Catalog and custom store selection disabled unless the application is explicitly configured and integration-tested for them.
4. Validate process-worker error reporting and Azure consumer health in a non-production tenant.
5. Promote feature flags/configuration incrementally and retain the previous deployable artifact for rollback.