|
| 1 | +--- |
| 2 | +title: Release notes 3.7.0 |
| 3 | +tags: [release_notes] |
| 4 | +published: true |
| 5 | +keywords: release notes, announcements, changelog |
| 6 | +summary: "Version 3.7.0 of Eclipse Ditto, released on 26.02.2025" |
| 7 | +permalink: release_notes_370.html |
| 8 | +--- |
| 9 | + |
| 10 | +The Ditto team is once again happy to announce a new minor release of Eclipse Ditto, namely version 3.7.0 |
| 11 | + |
| 12 | +This release is completely [IP (intellectual property) checked by the Eclipse Foundation](https://www.eclipse.org/projects/handbook/#ip) |
| 13 | +meaning that project code as well as all used dependencies were "[...] reviewed to ensure that the copyrights |
| 14 | +expressed are correct, licensing is valid and compatible, and that other issues have been uncovered and properly |
| 15 | +investigated." |
| 16 | + |
| 17 | + |
| 18 | +## Changelog |
| 19 | + |
| 20 | +Eclipse Ditto 3.7.0 focuses on the following areas: |
| 21 | + |
| 22 | +* Introduce new **Policy decision API** to check with a single request what a logged-in user is allowed to do with a specific resource |
| 23 | +* Include current **entity revision** of a resource (thing and policy) in the response of requests (commands) and in all emitted events |
| 24 | +* Support updating referenced WoT ThingModel based **thing definition** for a Thing by defining a migration payload and when to apply it |
| 25 | + |
| 26 | +The following non-functional work is also included: |
| 27 | + |
| 28 | +* Add option to **configure pre-defined extra fields** (enrichments) to be proactively added internally in Ditto in order to save cluster roundtrips |
| 29 | +* Include **throttling configuration option** for updating the search index as a result of a policy update targeting many things |
| 30 | +* Add namespace to Ditto Helm chart managed Kubernetes resources |
| 31 | + |
| 32 | +The following notable fixes are included: |
| 33 | + |
| 34 | +* Fix flattening of JSON objects in arrays when an exists() RQL condition was used e.g. as a Ditto evaluated condition |
| 35 | + |
| 36 | +### New features |
| 37 | + |
| 38 | +#### Introduce new Policy decision API to check with a single request what a logged-in user is allowed to do with a specific resource |
| 39 | + |
| 40 | +Ditto [Policies](basic-policy.html) are used to manage access control (authorization) to Policies themselves and to |
| 41 | +[Things](basic-thing.html). |
| 42 | +Ditto checks on each API interaction if the logged in "subject" (e.g. a user) is allowed to perform the requested action |
| 43 | +(e.g. `READ` a Thing or `WRITE` a Policy or parts of both). |
| 44 | + |
| 45 | +For UIs it can be very beneficial to know in advance the permissions of the user in order to e.g. hide/show or enable/disable |
| 46 | +certain parts of the frontend dynamically. |
| 47 | + |
| 48 | +Issue [#1137](https://github.com/eclipse-ditto/ditto/issues/1137) described the need and the idea for that. |
| 49 | +Ditto 3.7.0 addresses this via PR [#2047](https://github.com/eclipse-ditto/ditto/pull/2047) and a new HTTP endpoint |
| 50 | +``` |
| 51 | +POST /api/2/checkPermissions |
| 52 | +``` |
| 53 | + |
| 54 | +As this endpoint does not need to be aware of the `policyId` which is used to check permissions, it was added as top-level |
| 55 | +endpoint to Ditto's API, next to `/api/2/policies` and `/api/2/things`. |
| 56 | + |
| 57 | +A frontend can compose a request body with a list of resources to check permissions for and the action to check for. |
| 58 | +For example, it can check in a single request if: |
| 59 | +* the user is allowed to `READ` a specific Policy `org.eclipse.ditto:example-policy` |
| 60 | +* the user is allowed to `READ` a specific Thing `org.eclipse.ditto:example-thing` |
| 61 | +* the user is allowed to `WRITE` the `attributes` of a specific Thing `org.eclipse.ditto:example-thing` |
| 62 | +* the user is allowed to `READ` the `firmware` feature of a specific Thing `org.eclipse.ditto:example-thing` |
| 63 | +* the user is allowed to send a `reboot` message (`WRITE`) to the `admin` feature of a specific Thing `org.eclipse.ditto:example-thing` |
| 64 | + |
| 65 | +Such a request body would look like: |
| 66 | +```json |
| 67 | +{ |
| 68 | + "my_access_control_reader": { |
| 69 | + "resource": "policy:/", |
| 70 | + "entityId": "org.eclipse.ditto:example-policy", |
| 71 | + "hasPermissions": ["READ"] |
| 72 | + }, |
| 73 | + "a_full_thing_reader": { |
| 74 | + "resource": "thing:/", |
| 75 | + "entityId": "org.eclipse.ditto:example-thing", |
| 76 | + "hasPermissions": ["READ"] |
| 77 | + }, |
| 78 | + "one_allowed_to_write_attributes": { |
| 79 | + "resource": "thing:/attributes", |
| 80 | + "entityId": "org.eclipse.ditto:example-thing", |
| 81 | + "hasPermissions": ["WRITE"] |
| 82 | + }, |
| 83 | + "firmware_reader": { |
| 84 | + "resource": "thing:/features/firmware", |
| 85 | + "entityId": "org.eclipse.ditto:example-thing", |
| 86 | + "hasPermissions": ["READ"] |
| 87 | + }, |
| 88 | + "admin_allowed_to_reboot": { |
| 89 | + "resource": "message:/features/admin/inbox/messages/reboot", |
| 90 | + "entityId": "org.eclipse.ditto:example-thing", |
| 91 | + "hasPermissions": ["WRITE"] |
| 92 | + } |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +The "labels" in the request body are arbitrary and can be chosen by the frontend developer to provide semantics (e.g. role descriptions) |
| 97 | +which are maintained in the response to evaluate. |
| 98 | +A response according to the provided example payload would e.g. look like: |
| 99 | +```json |
| 100 | +{ |
| 101 | + "my_access_control_reader": false, |
| 102 | + "a_full_thing_reader": true, |
| 103 | + "one_allowed_to_write_attributes": true, |
| 104 | + "firmware_reader": true, |
| 105 | + "admin_allowed_to_reboot": false |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +With a single request, many "roles" can be checked at once, even for several entities (e.g. also several things). |
| 110 | +Read the full documentation of the new endpoint in the [added documentation](basic-auth-checkpermissions.html) and in the |
| 111 | +[HTTP API docs](http-api-doc.html#/Policies/post_api_2_checkPermissions). |
| 112 | + |
| 113 | + |
| 114 | +#### Include current entity revision in response of requests and emitted events |
| 115 | + |
| 116 | +Issue [#2055](https://github.com/eclipse-ditto/ditto/issues/2055) suggested to provide the current `revision` of Ditto |
| 117 | +managed entities (Things, Policies and Connections) to be included as header to API calls (e.g. in responses). |
| 118 | +This was implemented for Ditto 3.7.0 in PR [#2121](https://github.com/eclipse-ditto/ditto/pull/2121) which adds a header |
| 119 | +`entity-revision` for all API responses, but also all events emitted from Ditto. |
| 120 | + |
| 121 | +This way, a client can always know the current revision of an entity and can e.g. decide if it needs to update its local |
| 122 | +representation of the entity or if it can skip the update. |
| 123 | + |
| 124 | +#### Support updating referenced WoT ThingModel based thing definition for a Thing by defining a migration payload and when to apply it |
| 125 | + |
| 126 | +Ditto 3.6.0 put the focus on adding WoT Thing Model based validation of modifications to things and action/event payloads. |
| 127 | +With that [validation being enabled](basic-wot-integration.html#configuration-of-thing-model-based-validation), Ditto will |
| 128 | +e.g. reject API calls which would modify the state of a Thing in a way which is not allowed by the defined Thing Model. |
| 129 | + |
| 130 | + |
| 131 | +### Changes |
| 132 | + |
| 133 | +#### Add option to configure pre-defined extra fields (enrichments) to be proactively added internally in Ditto in order to save cluster roundtrips |
| 134 | + |
| 135 | +Issue [#2072](https://github.com/eclipse-ditto/ditto/issues/2072) suggested to provide a configuration in Ditto which |
| 136 | +allows to configure certain [extra fields](basic-enrichment.html) to be sent always for things matching a configured namespace and/or RQL `condition`. |
| 137 | + |
| 138 | +This is beneficial in order to reduce Ditto cluster-internal roundtrips to fetch `extraFields` which are requested always (or very often). |
| 139 | +If for example a configured [Connection target configured enrichment](basic-connections.html#target-topics-and-enrichment) of |
| 140 | +emitted thing events to always contain all `attributes` or always contain the thing's `definition`, this would cause for each |
| 141 | +event a roundtrip (from connectivity to things service) to fetch those fields which were not included in the event. |
| 142 | + |
| 143 | +Those roundtrips can now be avoided for "well known" patterns of which fields are always/often needed. Other fields can still |
| 144 | +be retrieved on-demand via the `extraFields` mechanism, but if all requested `extraFields` are already included in an event, |
| 145 | +Ditto can save the roundtrip which improves: |
| 146 | +* reliability (no network issues, no issues because of restarts of Ditto) |
| 147 | +* throughput |
| 148 | +* network costs |
| 149 | + |
| 150 | +PR [#2076](https://github.com/eclipse-ditto/ditto/pull/2076) provides this configuration option - how to configure it was |
| 151 | +added to the [Pre-defined extra fields configuration](installation-operating.html#pre-defined-extra-fields-configuration). |
| 152 | + |
| 153 | +#### Include throttling configuration option for updating the search index as a result of a policy update targeting many things |
| 154 | + |
| 155 | +In issue [#2122](https://github.com/eclipse-ditto/ditto/issues/2122) it was encountered and described that when updating |
| 156 | +a single Policy which is used for many things (like thousands of them), e.g. directly or via a [Policy import](basic-policy.html#policy-imports), |
| 157 | +the load of the resulting updates to the Ditto search index can be very high and can cause crashing Ditto containers if |
| 158 | +they are not scaled properly enough. |
| 159 | + |
| 160 | +To avoid such issues, a throttling mechanism was added in PR [#2125](https://github.com/eclipse-ditto/ditto/pull/2125) and |
| 161 | +throttling configuration was e.g. exposed via the Helm chart values as |
| 162 | +`thingsSearch.config.mongodb.policyModificationCausedSearchIndexUpdateThrottling`: |
| 163 | +```yaml |
| 164 | +# PolicyModificationCausedSearchIndexUpdateThrottling contains throttling configuration for the search Index update after a policy update |
| 165 | +policyModificationCausedSearchIndexUpdateThrottling: |
| 166 | + # enabled defines whether throttling should be applied for search Index update after a policy update. |
| 167 | + enabled: false |
| 168 | + # The time window within which the throttling limit applies. |
| 169 | + interval: 1s |
| 170 | + # The maximum number of updates allowed within each throttling interval. |
| 171 | + limit: 100 |
| 172 | +``` |
| 173 | +
|
| 174 | +
|
| 175 | +### Bugfixes |
| 176 | +
|
| 177 | +#### Fix flattening of JSON objects in arrays when an exists() RQL condition was used e.g. as a Ditto evaluated condition |
| 178 | +
|
| 179 | +PR [#2123](https://github.com/eclipse-ditto/ditto/pull/2123) fixed an issue where a Ditto evaluated predicate using `exists()` |
| 180 | +did not work on JSON structures which contained Json arrays nested in objects, nested in arrays again. |
| 181 | +This did not affect the Ditto search, but e.g. `condition` evaluation in a [Connection](basic-connections.html). |
| 182 | + |
| 183 | + |
| 184 | +### Helm Chart |
| 185 | + |
| 186 | +The Helm chart was enhanced with the configuration options of the added features of this release, no other improvements |
| 187 | +or additions were done. |
| 188 | + |
| 189 | +#### Add namespace to Ditto Helm chart managed Kubernetes resources |
| 190 | + |
| 191 | +PR [#2130](https://github.com/eclipse-ditto/ditto/pull/2130) adds `namespace` configuration to all Kubernetes resources |
| 192 | +managed by the Ditto Helm chart, previously they were missing from the chart. |
| 193 | + |
| 194 | + |
| 195 | +## Migration notes |
| 196 | + |
| 197 | +No migration steps are required for this release. |
0 commit comments