docs: update to describe transactions

README.md

@@ -197,17 +197,26 @@ This can include any number of settings changes.
 apiclient -m PATCH -u /settings -d '{"timezone": "America/Thunder_Bay"}'
 ```
 
-This will *stage* the setting in a "pending" area.
-You can see all the pending settings like this:
+This will *stage* the setting in a "pending" area - a transaction.
+You can see all your pending settings like this:
 ```
-apiclient -u /settings/pending
+apiclient -u /tx
 ```
 
 To *commit* the settings, and let the system apply them to any relevant configuration files or services, do this:
 ```
-apiclient -m POST -u /settings/commit_and_apply
+apiclient -m POST -u /tx/commit_and_apply
 ```
 
+Behind the scenes, these commands are working with the "default" transaction.
+This keeps the interface simple.
+System services use their own transactions, so you don't have to worry about conflicts.
+For example, there's a "thar-boot" transaction used to coordinate changes at startup.
+
+If you want to group sets of changes yourself, pick a transaction name and append a `tx` parameter to the URLs above.
+For example, if you want the name "FOO", you can `PATCH` to `/settings?tx=FOO` and `POST` to `/tx/commit_and_apply?tx=FOO`.
+(Transactions are created automatically when used, and are cleaned up on reboot.)
+
 For more details on using the client, see the [apiclient documentation](workspaces/api/apiclient/).
 
 #### Using user data

workspaces/api/README.md

@@ -53,10 +53,10 @@ storewolf ensures the default values (defined in [defaults.toml](../models/defau
 First, it has to create the data store directories and symlinks if they don’t exist.
 Then, it goes key-by-key through the defaults, and if a key isn’t already set, sets it with the default value.
 
-The settings are written to the *pending* section of the data store, meaning they’re not available until committed later by [settings-committer](#settings-committer).
+The settings are written to the *pending* section of the data store, in a "thar-boot" transaction, which is used for startup coordination.
+This means they’re not available until committed later by [settings-committer](#settings-committer).
 
-If there are any pending settings in the data store, they’re discarded.
-We’re unable to guarantee users that any pending settings they haven’t committed will survive a reboot, because we have to be able to commit changes ourselves during the boot process (see later services), and we don’t yet have a way of separating transactions.
+If there are any pending transactions in the data store when storewolf starts, they’re discarded.
 
 ### apiserver
 
@@ -101,7 +101,7 @@ Pluto generates settings needed for Kubernetes configuration, for example cluste
 
 [Further docs](settings-committer/)
 
-This binary sends a commit request to the API, which moves all the pending settings from the above services into the live part of the data store.
+This binary sends a commit request to the API (by default for the "thar-boot" transaction) which moves all the pending settings from the above services into the live part of the data store.
 It's called as a prerequisite of other services, like [sundog](#sundog) and [settings-applier](#settings-applier), that rely on settings being committed.
 
 ### settings-applier

workspaces/api/apiclient/README.md

@@ -25,16 +25,23 @@ Getting settings:
 
 ```
 apiclient -m GET -u /settings
-apiclient -m GET -u /settings/pending
 ```
 
 Changing settings:
 
 ```
 apiclient -X PATCH -u /settings -d '{"timezone": "OldLosAngeles"}'
-apiclient -m POST -u /settings/commit_and_apply
+apiclient -m POST -u /tx/commit_and_apply
 ```
 
+You can also check what you've changed but not commited by looking at the pending transaction:
+
+```
+apiclient -m GET -u /tx
+```
+
+(You can group changes into transactions by adding a parameter like `?tx=FOO` to the calls above.)
+
 ## apiclient library
 
 The apiclient library provides simple, synchronous methods to query an HTTP API over a

workspaces/api/apiclient/README.tpl

@@ -25,16 +25,23 @@ Getting settings:
 
 ```
 apiclient -m GET -u /settings
-apiclient -m GET -u /settings/pending
 ```
 
 Changing settings:
 
 ```
 apiclient -X PATCH -u /settings -d '{"timezone": "OldLosAngeles"}'
-apiclient -m POST -u /settings/commit_and_apply
+apiclient -m POST -u /tx/commit_and_apply
 ```
 
+You can also check what you've changed but not commited by looking at the pending transaction:
+
+```
+apiclient -m GET -u /tx
+```
+
+(You can group changes into transactions by adding a parameter like `?tx=FOO` to the calls above.)
+
 ## apiclient library
 
 {{readme}}

workspaces/api/apiserver/README.md

@@ -21,12 +21,16 @@ The interface is documented in [OpenAPI format](https://swagger.io/docs/specific
 The Settings APIs are particularly important.
 You can GET settings from the `/settings` endpoint.
 You can also PATCH changes to the `/settings` endpoint.
-Settings are stored as pending until a commit API is called.
-Pending settings can be retrieved from `/settings/pending` to see what will change.
+Settings are stored as a pending transaction until a commit API is called.
+Pending settings can be retrieved from `/tx` to see what will change.
 
-Upon making a `commit` API call, pending settings are made live.
-Upon making an `apply` API call, an external settings applier tool is called to apply the changes to the system and restart services as necessary.
-There's also a `commit_and_apply` API to do both, which is the most common case.
+Upon making a `/tx/commit` POST call, the pending transaction is made live.
+Upon making an `/tx/apply` POST call, an external settings applier tool is called to apply the changes to the system and restart services as necessary.
+There's also `/tx/commit_and_apply` to do both, which is the most common case.
+
+If you don't specify a transaction, the "default" transaction is used, so you usually don't have to think about it.
+If you want to group changes into transactions yourself, you can add a `tx` parameter to the APIs mentioned above.
+For example, if you want the name "FOO", you can `PATCH` to `/settings?tx=FOO` and `POST` to `/tx/commit_and_apply?tx=FOO`.
 
 Requests are directed by `server::router`.
 `server::controller` maps requests into our data model.

workspaces/api/apiserver/src/lib.rs

@@ -18,12 +18,16 @@ The interface is documented in [OpenAPI format](https://swagger.io/docs/specific
 The Settings APIs are particularly important.
 You can GET settings from the `/settings` endpoint.
 You can also PATCH changes to the `/settings` endpoint.
-Settings are stored as pending until a commit API is called.
-Pending settings can be retrieved from `/settings/pending` to see what will change.
+Settings are stored as a pending transaction until a commit API is called.
+Pending settings can be retrieved from `/tx` to see what will change.
 
-Upon making a `commit` API call, pending settings are made live.
-Upon making an `apply` API call, an external settings applier tool is called to apply the changes to the system and restart services as necessary.
-There's also a `commit_and_apply` API to do both, which is the most common case.
+Upon making a `/tx/commit` POST call, the pending transaction is made live.
+Upon making an `/tx/apply` POST call, an external settings applier tool is called to apply the changes to the system and restart services as necessary.
+There's also `/tx/commit_and_apply` to do both, which is the most common case.
+
+If you don't specify a transaction, the "default" transaction is used, so you usually don't have to think about it.
+If you want to group changes into transactions yourself, you can add a `tx` parameter to the APIs mentioned above.
+For example, if you want the name "FOO", you can `PATCH` to `/settings?tx=FOO` and `POST` to `/tx/commit_and_apply?tx=FOO`.
 
 Requests are directed by `server::router`.
 `server::controller` maps requests into our data model.