[mgaffigan]

The current API does not permit atomic writes to configuration maps. Two unsynchronized writers overwrite each other's settings. Add an atomic write endpoint.

With current endpoint:

User 1	User 2	State after
Read = { A: 1, B: 1 }	Read = { A: 1, B: 1 }	{ A: 1, B: 1 }
Write A = 2	nop	{ A: 2, B: 1 }
nop	Write B = 2	{ A: 1, B: 2 }

With new endpoint:

User 1	User 2	State after
Read = { A: 1, B: 1 }	Read = { A: 1, B: 1 }	{ A: 1, B: 1 }
Write A = 2	nop	{ A: 2, B: 1 }
nop	Write B = 2	{ A: 2, B: 2 }

Blocking for #449

[github-actions]

Test Results

131 files  +  2  131 suites  +2   3m 9s ⏱️ +28s
807 tests + 70  807 ✅ + 70  0 💤 ±0  0 ❌ ±0 
963 runs  +136  957 ✅ +136  6 💤 ±0  0 ❌ ±0 

Results for commit ccbc629. ± Comparison against base commit fbda474.

♻️ This comment has been updated with latest results.

[NicoPiel]

• Empty request body breaks the database setup. In database mode, an empty body (a null property) gets saved before the code crashes. The database then holds a bad entry. On restart, loading the config map fails and the server runs with an empty map. The endpoint should reject an empty body or blank key with a 400.

• Keys containing / can't be updated through the new /configurationMap/{key} path.

• "Atomic" only holds on one server. It relies on a lock inside one Java process. In database mode each server keeps its own copy of the map, loaded once. Several servers sharing one database would still overwrite each other's changes, the same problem the PR is meant to fix.

• There's no matching delete endpoint, so removing an entry still means rewriting the whole map, with the same race.

• The Configuration Map settings panel in the admin UI (SettingsPanelMap.java:127) still saves the whole map, so UI users still have the race.

[mgaffigan]

• Empty request body breaks the database setup. In database mode, an empty body (a null property) gets saved before the code crashes. The database then holds a bad entry. On restart, loading the config map fails and the server runs with an empty map. The endpoint should reject an empty body or blank key with a 400.

This appears to be a bug of the pre-existing endpoint. @tonygermano opened #520 to track this. The same fix is applicable both endpoints, since the validation should catch both.

• Keys containing / can't be updated through the new /configurationMap/{key} path.

Path components should be escaped. PUT /configurationMap/foo%2Fbar sets foo/bar.

• "Atomic" only holds on one server. It relies on a lock inside one Java process. In database mode each server keeps its own copy of the map, loaded once. Several servers sharing one database would still overwrite each other's changes, the same problem the PR is meant to fix.

Agreed - that may be the subject of future work. That's a larger architectural change than this PR contemplates, and the lore I'm aware of is that two mirth servers do not play nicely on the same database.

• There's no matching delete endpoint, so removing an entry still means rewriting the whole map, with the same race.

Agreed - that may be the subject of future work.

• The Configuration Map settings panel in the admin UI (SettingsPanelMap.java:127) still saves the whole map, so UI users still have the race.

Agreed - that may be the subject of future work.

[tonygermano]

Thanks, the per-key endpoint is a real improvement. Right now two writers changing different keys can erase each other, and doing the read-modify-write on the server under the controller's lock fixes that. Rather than send you a list of changes, I pushed four commits to the branch. Please look them over.

Blank keys and request body examples

• Reject blank keys. The endpoint now responds with 400 for a blank key, as UserServlet does for a blank username. That covers the blank-key half of @NicoPiel's first point. In file mode, saving drops blank keys while they stay in memory, so a blank key would work until the next restart and then disappear. The key description also says a / has to be encoded as %2F.
• Request body examples. Added XML/JSON @ExampleObject refs for the single ConfigurationProperty body, like the neighbouring endpoints.

Stale-write check

Channels, code templates and their groups/libraries all refuse a stale save unless the caller passes override=true. The configuration map had nothing like that, so two writers on the same key still lost one update silently. A stored revision number doesn't fit, because file mode keeps the map in a hand-editable configuration.properties. The new commits use a content-based version instead:

• ConfigurationProperty.versionOf(property) is the lowercase hex SHA-256 of the UTF-8 bytes of value + "\u001F" + comment (a unit separator rather than NUL, which C strings and shell variables can't easily hold), with a null value or a null/blank comment treated as empty, and "" for a missing entry. Blank comments count as empty because file mode saves them as null, so a restart doesn't cause false conflicts. Clients compute it from what GET /configurationMap returned, so the GET response doesn't change.
• PUT /configurationMap/{key} takes an optional expectedVersion query parameter and now returns a boolean. If the version doesn't match, nothing is changed and it returns false, the same way updateChannel, updateChannelGroups and updateCodeTemplate report a stale revision. An empty string means "the key must not exist yet", and leaving it out keeps last-write-wins. The comparison ignores case, so clients whose hex encoders produce uppercase don't need to convert. The operation description spells out the algorithm for REST callers.
• A query parameter is used instead of ETag/If-Match because the Client proxy only exposes response bodies, so Java callers could never read an ETag.

This changes the Client signature and return type, so it has to go in before the endpoint ships.

Tests

DefaultConfigurationControllerTest covers keeping the other entries and the version matching rules, and ConfigurationPropertyTest checks known hash values. A ConfigurationMapEntryTest smoketest covers what needs a live server: the blank key, how a null or empty expectedVersion is sent, a version calculated from the GET response, and a rejected update coming back as false. Claude ran it in both file and database mode.

As you said, #520 applies to both endpoints. I'll send the fix as a follow-up PR once this one merges.

---

🤖 Drafted with Claude Code