idempotency: docs table, pitfall 9, changelog; lock scan fix

This commit is contained in:
CRTkafa 2026-10-12 04:03:23 +08:00
parent 8f41ed4c02
commit d5bc7b8889
4 changed files with 54 additions and 2 deletions

View file

@ -2,6 +2,39 @@
## Unreleased ## Unreleased
- Idempotency: every store write is an upsert; running a command twice, or again after a crash or a lost answer,
leaves exactly one of each thing (table of every write path: `docs/idempotency.md`).
- New `cli/lib/upsert.ts`: `findOrCreate` looks again with a fresh GET right before a create and asks a journal of
recent creates (`.storebound/created.json`, a direct GET by id) so a re-run during the store's list lag reuses what
the last run made; `createOnce` treats 409 / ALREADY_EXISTS as found and never sends a create blindly again after
a timeout or 5xx (it looks first; only keys the store keeps unique get one more try).
- The App Store Connect, Google Play, RevenueCat and `storebound api` clients retry 5xx / network errors only for
requests that are safe twice (GET, PUT, PATCH, DELETE, relationship adds, state actions, price schedules); a POST
create without a clear answer throws `AmbiguousWriteError`. Plan runners treat a 409 duplicate as done and stop on
an unclear create instead of retrying.
- Uses it in `apple iap`, `apple subscriptions` (groups, subscriptions, localizations, promotional offers, offer code
campaigns, custom codes, review screenshot by MD5), `apple offer-codes`, `apple cpp create`, `apple events create`,
`apple ppo create`, `apple testflight groups`, `apple bundle`, `apple review-details` (only changed fields),
`apple release --phased on`, `apple adhoc register` / `profile`, `apple signing ensure` (a lost certificate answer
keeps the key and finds the certificate by its public key), `apple upload` (a COMPLETE build upload is not sent
again, an unfinished one is resumed), `analytics setup`, `reviews send`, `revenuecat sync`, `play subscriptions`
(subscriptions and offers).
- Review submissions (`apple iap-submit`, `cpp submit`, `events submit`): the draft is reused or created once, an
item already in it is not added again.
- Screenshot and preview sets keep the leading files that already match (MD5, position, delivered), replace the rest
in order and fix the order if Apple shows another; a crash midway converges on the next run without duplicates.
- Play edits: one open at a time per run, deleted on every error path, committed only on success, deleted instead of
committed when nothing changed (`ctl.unchanged()`); redone only when nothing went live, never after a commit
without a clear answer. `play images` compares sha256 first and replaces only changed image types; `play release`
reuses a versionCode Play already has and skips identical track releases; `play rollout` commits nothing when the
track is already like that; `play upload` is done when the versionCode is on the track already.
- One writer per app and store: write runs take `.storebound/locks/<store>-<app>.lock` (dry runs and reads do not);
a second run stops with who holds it; a lock of a process that is gone is taken over; `--force-unlock`.
- `tests/idempotency.test.ts` with stateful store doubles (`tests/helpers/fake-stores.ts`): write commands run twice
with zero writes on the second run, a crash in the middle of a screenshot set, IAP and subscription creates whose
answer is lost, 409 duplicates, the list lag after a crash, Play edit error paths and an unclear commit, the lock.
Pitfall 9 in `docs/pitfalls.md` and the store-pitfalls skill.
- Faster `shots capture` (web) and `shots render` (a 22-language game took about 50 min to capture, serially, with a - Faster `shots capture` (web) and `shots render` (a 22-language game took about 50 min to capture, serially, with a
new context and a full game boot per frame): new context and a full game boot per frame):
- `--concurrency N` (and `shots.capture.concurrency`): parallel browser contexts in one Chromium; defaults from the - `--concurrency N` (and `shots.capture.concurrency`): parallel browser contexts in one Chromium; defaults from the

View file

@ -66,7 +66,9 @@ const READ_SUBS = new Set(['status', 'list', 'devices', 'diff', 'export', 'pull'
* writes, both for `prices import`, `revenuecat-<project>` for revenuecat sync. Pure. * writes, both for `prices import`, `revenuecat-<project>` for revenuecat sync. Pure.
*/ */
export function lockKeys(command: string, args: Args, config: ShipConfig): string[] { export function lockKeys(command: string, args: Args, config: ShipConfig): string[] {
if (args.has('dry')) return []; // a dry run never writes, so it never waits for (or blocks) a writer
const readOnly = args.has('dry');
if (readOnly) return [];
const sub = args._[0]; const sub = args._[0];
const apple = config.apple?.bundleId ? [`apple-${config.apple.bundleId}`] : []; const apple = config.apple?.bundleId ? [`apple-${config.apple.bundleId}`] : [];
const play = config.play?.packageName ? [`play-${config.play.packageName}`] : []; const play = config.play?.packageName ? [`play-${config.play.packageName}`] : [];

View file

@ -9,6 +9,7 @@ fails without the fix.
| # | date | lesson | guard | | # | date | lesson | guard |
|---|---|---|---| |---|---|---|---|
| 9 | 2026-10 | A retried or repeated write can duplicate on a live store: a POST create retried after a timeout or 5xx, a re-run during the list lag right after a create, two runs at once, a Play edit redone after an unclear commit, a crash in the middle of a screenshot set. | Every write is an upsert (`cli/lib/upsert.ts`: findOrCreate with a fresh re-check and a journal of recent creates, createOnce treating 409 as found, no blind retry of a create); API clients retry only requests that are safe twice; Play edits are all or nothing; asset sets keep the matching prefix; one lock per app and store (`cli/lib/lock.ts`, `--force-unlock`). Table: `docs/idempotency.md`; `tests/idempotency.test.ts` runs every write twice and asserts zero writes on the second run. |
| 8 | 2026-10 | Capacitor plugins in a monorepo live in `apps/native/node_modules`, so `scan` missed them. | `scan` / `privacy-manifest` resolve workspace packages (`cli/lib/scan/project.ts`, `cli/lib/node-packages.ts`). | | 8 | 2026-10 | Capacitor plugins in a monorepo live in `apps/native/node_modules`, so `scan` missed them. | `scan` / `privacy-manifest` resolve workspace packages (`cli/lib/scan/project.ts`, `cli/lib/node-packages.ts`). |
| 7 | 2026-10 | Console UIs: the App Store Connect sign-in runs in an `idmsa.apple.com` iframe; "User Access" is a plain heading, not a labeled group; Chrome drops session cookies without `--restore-last-session`. | `console` session and fill (`cli/console/`), `tests/console-*.test.ts`. | | 7 | 2026-10 | Console UIs: the App Store Connect sign-in runs in an `idmsa.apple.com` iframe; "User Access" is a plain heading, not a labeled group; Chrome drops session cookies without `--restore-last-session`. | `console` session and fill (`cli/console/`), `tests/console-*.test.ts`. |
| 6 | 2026-10 | Screenshot fonts: only part of the glyphs a language needs were available, so Turkish / Polish / Vietnamese characters fell back to another font silently. | `shots fonts` / `shots check` check every language's characters against the fonts (`tests/glyphs.test.ts`). | | 6 | 2026-10 | Screenshot fonts: only part of the glyphs a language needs were available, so Turkish / Polish / Vietnamese characters fell back to another font silently. | `shots fonts` / `shots check` check every language's characters against the fonts (`tests/glyphs.test.ts`). |

View file

@ -1,6 +1,6 @@
--- ---
name: store-pitfalls name: store-pitfalls
description: Known pitfalls with App Store Connect, Google Play and storebound itself, learned from real releases, and what to do about each - store lists that lag right after a create, dry runs that print a count instead of a plan, App Store names taken on a storefront, keyword limits in bytes, Data safety answers without code evidence, missing font glyphs in screenshots, console sign-in and sessions, Capacitor monorepo plugins. Read it before any store task, and when a store command does something you did not expect. description: Known pitfalls with App Store Connect, Google Play and storebound itself, learned from real releases, and what to do about each - store lists that lag right after a create, dry runs that print a count instead of a plan, App Store names taken on a storefront, keyword limits in bytes, Data safety answers without code evidence, missing font glyphs in screenshots, console sign-in and sessions, Capacitor monorepo plugins, duplicates from retries, re-runs and parallel runs. Read it before any store task, and when a store command does something you did not expect.
--- ---
# Store pitfalls # Store pitfalls
@ -67,6 +67,22 @@ Each entry: **symptom** → cause → what to do → what guards it now. The ful
- **Do:** run `scan` from the project root; check that the stack line lists the plugins. - **Do:** run `scan` from the project root; check that the stack line lists the plugins.
- **Guard:** `storebound scan` and `privacy-manifest` resolve packages through workspace folders too. - **Guard:** `storebound scan` and `privacy-manifest` resolve packages through workspace folders too.
## 9. A second run (or a retry) creates a duplicate
- **Symptom:** two in-app purchases or subscription groups with the same name, a screenshot twice in a set, an
offer code campaign or a custom product page twice, after a timeout, a crash, a re-run a minute later, or two runs
at once.
- **Cause:** a POST create retried after a timeout or a 5xx may have been applied the first time; the store's lists lag
right after a create, so a re-run does not see what the last run made; two writers race; a Play edit redone after
a commit whose answer was lost.
- **Do:** just run the command again: every write command is an upsert and converges (`docs/idempotency.md`). Never
retry a create by hand (`storebound api`) without a GET first. If a run says another storebound run holds the lock,
wait for it; use `--force-unlock` only when that run is really gone. Never run two write commands for the same app
in parallel.
- **Guard:** `cli/lib/upsert.ts` (findOrCreate: fresh re-check + journal `.storebound/created.json`; createOnce: 409
= found, an unclear answer is looked up, never re-sent blindly), retries only for requests that are safe twice,
Play edits deleted on every error and never redone after an unclear commit, screenshot / preview sets keep the
matching prefix in order, `.storebound/locks/` per app and store. `tests/idempotency.test.ts`.
## Adding a lesson ## Adding a lesson
Every bug found in real use gets an entry in `docs/pitfalls.md` and here, and, where possible, a check or a test Every bug found in real use gets an entry in `docs/pitfalls.md` and here, and, where possible, a check or a test
that fails without the fix (see CONTRIBUTING.md). that fails without the fix (see CONTRIBUTING.md).