Pool Plutonium keys by game for launches and autoscaling

docs/guides/collections.md

@@ -32,8 +32,9 @@ It fills deficits without changing existing servers' files.
 3. Choose **Save & preview** (or **Preview fleet changes** on a saved collection).
    Choose **Fill missing servers** or **Match collection exactly**, then review
    the server IDs and estimated capacity. Native host ports are assigned later.
-4. Lobbies with a saved key show **Saved key ready** and reuse it automatically.
-   Enter a Plutonium key only for lobbies missing one. Update saved keys in **Keys**.
+4. Launches covered by unused keys show **Game key available**. Each game’s
+   available keys are counted once across the full lineup. Add an unused Plutonium
+   key for each remaining launch, or manage the game pools in **Keys**.
 5. Choose **Queue N servers** (or confirm removals and choose **Apply** in exact
    mode) and follow the collection progress page.
    If every target is already met, choose **Done**; no operation is created.
@@ -48,7 +49,8 @@ servers keep their containers, files, ports, and configuration without a restart
 The option is chosen per launch; opening another preview defaults to fill mode.
 
 Review the removal list and check its confirmation before applying. Removed
-servers lose their containers, files, and registrations; saved keys remain.
+servers lose their containers, files, and registrations; their keys return to the
+game pool only after confirmed removal.
 Unstarted creations are cancelled without booting a container. Running servers
 use the normal removal queue and require a fresh zero-player RCON response.
 Occupied or unreachable servers wait. Already pending removals are reused.
@@ -59,6 +61,11 @@ map, port, or pending-removal change since an exact preview requires a new revie
 Servers added after submission are not included. Applying the same preview again
 returns the same collection without repeating operations.
 
+Keys assigned to pending removals stay reserved until cleanup is confirmed. An
+exact collection that replaces running servers still needs enough currently
+available game keys for every new launch. If the pool is full, complete the
+removals first, then refresh the preview to use the released keys.
+
 Native launches can be queued even when the current port range is full. Removed
 servers retain their ports until cleanup completes; provisioning assigns newly
 available ports as each creation starts. A failed or cancelled removal can leave
@@ -94,11 +101,11 @@ is a warning: provisioning can wait for it. The preview does not reserve resourc
 Apply validates the reviewed configuration, lobby IDs, keys, and fleet changes, saves all jobs in
 one database transaction, and returns the progress page ID. Native jobs initially
 have no host or port; each job performs its capacity checks asynchronously during
-provisioning. If a server lacks a valid key or its reviewed identity changed,
+provisioning. If a server lacks an available game key or its reviewed identity changed,
 no jobs or key changes from that submission are committed. Legacy submissions also
 revalidate their reviewed ports. Refreshing
-the preview retains typed keys only for unchanged server IDs still missing a saved
-key, and resets removal confirmation.
+the preview retains typed keys for launches in the same game that still need
+keys, and resets removal confirmation.
 
 Submitting the same preview again returns the same collection, including after
 a lost response or an application restart. Reusing the collection with a new
@@ -138,13 +145,15 @@ remain visible in Provisioning activity and history.
 2. Choose the current promoted setup and select a game/map, or select a collection.
 3. Choose **Preview launch**. Review the image reference, configuration sources,
    managed files and versions, selected map, lobby, port, and prerequisite checks.
-4. Enter the Plutonium key for the displayed server ID, or reuse its saved key.
+4. Use an available key from the game pool, or enter an unused key for that game.
 5. Choose **Launch server** and follow the operation to verified health.
 
 A preview lasts 30 minutes. It neither reserves capacity nor saves a key. If
 another launch takes the lobby, submission stops before saving the key;
-refresh the preview and review the newly assigned ID. Refreshing a preview clears
-the typed key so it cannot accidentally be saved against a different lobby.
+refresh the preview and review the newly assigned ID. A typed key can follow
+the new lobby within the same game. Pool availability is checked again at
+submission, and keys are reserved atomically so concurrent launches cannot share
+a credential.
 
 Host selection, game-file versions, runtime configuration and lobby availability
 are checked before queueing. Provisioning assigns host capacity and physical
@@ -205,7 +214,8 @@ and drift reconciliation using the server's game/map scopes.
 Container tags can resolve to newer images; use a digest for a fixed image.
 Without a promoted baseline, Plutainer seeds its own defaults on first boot,
 which are not captured. Host, network, game-file volumes, destination directories,
-and RCON/Plutonium credentials use the environment and key store at launch time.
+and RCON/Plutonium credentials use the environment and assigned game-pool key at
+launch time.
 The current main config filename and launch settings apply to new deployments.
 
 Recipes do not include the separately stored Plutonium or integration credentials.
@@ -249,7 +259,9 @@ there while preserving query parameters.
   where mode is `fill` (default) or `exact`. Returns `mode`, `retainedServers`,
   `removals` (name/reason), creation `servers`, and configured `launchConcurrency`.
 - `POST /api/deployment-collections`: atomically queue `{ previewId, keys? }`,
-  where `keys` maps exact preview server IDs to optional replacement keys.
+  where `keys` maps preview server IDs to optional unused keys added to their
+  game's pool and assigned during launch. Omit entries covered by available
+  pool keys; these IDs do not permanently bind a key to a map or lobby.
   A satisfied preview returns `{ ok: true, collectionId: null }` with HTTP 200,
   without creating a collection, saving keys, or kicking the worker.
 - `GET /api/deployment-collections`: list collection progress summaries with