feat: add subscription groups server contract

[kapdon]

Summary

Adds the backend contract for named subscription groups as the first Server-only part of TypeType-Video/TypeType#172.

• creates, renames, lists, and deletes account-scoped groups;
• supports many-to-many membership for existing subscribed channels;
• filters GET /subscriptions and GET /subscriptions/feed by groupId or ungrouped=true;
• preserves the existing global subscription list/feed when no filter is supplied;
• freezes each filtered feed's channel membership for its full cursor session;
• includes groups and memberships in backup export and transactional restore;
• uses a create-only subscription request schema, with subscribedAt generated by the server;
• clears memberships safely when a subscription or replacement import/restore removes the underlying channel;
• serializes membership assignment with unsubscribe and replacement restores so an orphan membership cannot commit.

The branch is rebased onto the current dev base and the history is split into focused commits, each below the requested 290-insertion limit.

Review feedback addressed

Backup round-trip

Backup exports now include subscription groups and their channel memberships. Restore recreates groups with fresh IDs, reconnects memberships by canonical channel URL, and performs the replacement in the same database transaction as subscription restore. Backups created before the new optional subscriptionGroups field remain accepted.

Export captures the subscription list once and filters group memberships against that canonical captured set. A concurrent subscription/group change therefore cannot produce a server-generated backup that the restore validator rejects.

Membership mutation serialization

Group membership assignment, direct unsubscribe, TypeType restore, and PipePipe replacement import now acquire the same account-scoped PostgreSQL transaction advisory lock. The subscription existence check and membership insert cannot straddle a committed deletion, while replacement imports still retain memberships for channel URLs that survive.

Stable feed pagination

A grouped or ungrouped first page derives an immutable membership snapshot used by every continuation cursor. Snapshots are stored in eight fixed, account-scoped Dragonfly slots:

• terminal pages allocate no slot;
• identical membership selections reuse and refresh the same slot;
• atomic SET NX EX claims prevent cross-process lost updates;
• occupied slots are never overwritten, so an issued cursor remains valid for the cache TTL;
• a ninth distinct active session returns documented 429 subscription_feed_cursor_capacity before a cursor is issued.

Cursor resolution remains bound to the authenticated account, filter, visibility, page size, and feed generation.

Subscription creation contract

POST /subscriptions now accepts SubscriptionCreateRequest, which does not expose subscribedAt. The service always assigns the timestamp. An obsolete client-supplied subscribedAt field is ignored by the production JSON configuration and cannot control stored state.

API changes

• GET/POST /subscriptions/groups
• PUT/DELETE /subscriptions/groups/{groupId}
• PUT/DELETE /subscriptions/groups/{groupId}/channels
• GET /subscriptions?groupId=...
• GET /subscriptions?ungrouped=true
• GET /subscriptions/feed?groupId=...
• GET /subscriptions/feed?ungrouped=true

The handwritten OpenAPI contract documents the subscription and group operations, filtered feed cursors, and the capacity response.

Commit structure

Commit	Insertions	Purpose
7c9c93b4	84	group persistence
7ef98087	255	membership persistence and service
61b01ade	116	group API
46126970	67	grouped subscription lists
8665282d	163	stable grouped feed pagination
860d6869	149	backup round-trip
f756bfab	214	OpenAPI contract
8336b003	120	persistence tests
939158ab	161	route tests
af4cd5c1	168	feed stability tests
abd1ae9a	285	bounded cross-process snapshot storage
93a0830a	107	subscription membership mutation serialization
267fda9a	90	consistent subscription/group backup export

Verification

Exact head: 267fda9a7cf7854655b4289f9cf7665c33f26c2f

Using the required JDK 25 toolchain:

./gradlew --no-daemon clean check shadowJar validateOpenApi --console=plain
BUILD SUCCESSFUL
1,068 tests, 0 failures, 0 errors, 0 skipped

This includes OpenAPI validation, compilation, coverage verification, route/service/database regressions, legacy-backup compatibility, cursor/filter isolation, and the shadow JAR build.

Live API QA ran two real shadow-JAR server processes against shared disposable PostgreSQL and Dragonfly instances. It verified concurrent cross-process cursor creation and continuation, identical snapshot reuse, eight-slot saturation, typed 429 for the ninth session, first-cursor survival, server-owned timestamps, backup round-trip, legacy backup acceptance, and cross-account 404 isolation.

Additional exact-head QA held the account advisory lock in real PostgreSQL and issued concurrent authenticated membership assignment and unsubscribe requests. Both requests waited; after release, unsubscribe returned 204, assignment re-checked state and returned 404, and both HTTP and SQL read-back showed zero orphan memberships. A deliberately inconsistent membership fixture was omitted from HTTP backup export, and that server-generated backup restored to a fresh account with 200.

Component follow-up

A separate TypeType-Frontend PR is required to add group management, channel assignment, and filtering UI. No Token, Downloader, or Player change is required.

[Priveetee]

Hey, first thx a lot for taking the time to work on this!

I went through the database changes, routes, account isolation, feed filtering, restore behavior, OpenAPI and tests.

Honestly the base is really good. Groups are correctly isolated per account, one channel can be in multiple groups, the ungrouped feed is handled properly, and reusing the existing subscription feed snapshot makes sense.

I found a few things that need to be fixed before merge:

• The important one is backups. Groups and their channel memberships are not exported right now. Restoring on a fresh instance would restore the subscriptions, but all the organization created by the user would be lost. Both the groups and their memberships need to be included in TypeType backups.

• There is also an edge case with pagination. The cursor only remembers the group ID and filter, while the group membership is loaded again for every page. If someone edits the group between two pages, the next page can skip or repeat videos. The cursor needs to keep the same group membership snapshot for the full pagination session.

• Small OpenAPI mismatch: subscribedAt is required in the subscription creation schema, but Server actually generates it and ignores the submitted value. It would be cleaner to have a separate request schema where this field is not required.

Could u also split the first commit please? It currently contains 1,174 insertions, and I try to keep commits below 290 insertions so it stays easy to understand later why each part changed. Separating the database/model work, group API, feed filtering, backup support and tests would make the history much easier to follow.

I ran the full validation: 998 tests passed, including OpenAPI validation, coverage and the production jar build. I also checked it together with the current Server changes and all 1,036 tests passed there.

So yeah, no need to rebuild everything from scratch at all. The base is good, it just needs these points fixed and I will gladly review it again :)

Thx again, and have a great day!