diff --git a/openspec/changes/add-open-party-joining/.openspec.yaml b/openspec/changes/add-open-party-joining/.openspec.yaml new file mode 100644 index 0000000..4bfa670 --- /dev/null +++ b/openspec/changes/add-open-party-joining/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-30 diff --git a/openspec/changes/add-open-party-joining/design.md b/openspec/changes/add-open-party-joining/design.md new file mode 100644 index 0000000..a6027db --- /dev/null +++ b/openspec/changes/add-open-party-joining/design.md @@ -0,0 +1,175 @@ +# Design + +## Context + +Builds on `add-party-service` (its specs are the base of the deltas here; that change is not archived yet, so a delta +against its requirements may warn). Parties and invites live in Dragonfly. `PartyService` mutates a party under the lock +`party:`. An invite targets a player by name through `PresenceStore.findByName`, which reads the network-wide +name index, so a target on another proxy resolves the same way as one on the leader's proxy. The plugin answers every +command through `PartyActions` and reacts to events in `EventHandler`. + +## Goals / Non-Goals + +Goals: a player can ask a party to let them in; a leader can open the party to everyone; the leader keeps control +(a kicked player does not come back on their own; a leadership change never leaves an open party to a new leader who +did not choose it). +Non-goals: discovery of public parties, passwords, bans that outlive a party, a request history. + +## Decisions + +### D1. The permission is checked on the proxy only + +`quelea.party.public` is a Velocity permission, needed to open a party only. The plugin checks it before it calls +`POST /v1/parties/{partyId}/public` with `public: true`. Closing (`public: false`) needs no permission: closing is the +safe direction, and a leader who lost the permission must still be able to close the party. +The backend has no idea of Minecraft permissions (principle 2 and the Minecraft-independence principle); it trusts the +authenticated client, as it already trusts the client for every other command. +Rejected: a permission model in the backend (it would need the proxy's permission data in Dragonfly or a call back to +the proxy, both against principle 2). + +### D2. Leadership change closes a public party + +Promote and automatic succession clear `public`, bump the version, and publish the event as usual. The backend cannot +know whether the new leader holds `quelea.party.public`, so it does not guess. The new leader reopens the party if +allowed. Members stay, even above the private limit; new joins are then answered `party-full`. The same applies when a +leader closes a party above the private limit: the members stay, new joins are rejected as full. +Rejected: a stored "may open" flag per player (a second permission model in the backend); kicking the surplus members +(a leader closing the party must not remove people). + +A leader who lost the permission while the party is open can still close it: closing needs no permission (D1). + +D2 also applies when a public party drops to one member through a leave or a kick (see D10). A non-leader leaving +leaves the party public and starts its alone period. A leader leaving makes the successor leader, and that closes the +party as above. + +### D3. An explicit invite lifts the kick ban + +The ban only blocks self-service entry (`join`, `requests`). An invite from the leader removes the target from the ban +set in the same locked command that creates the invite. The leader's explicit act outranks the ban. +Rejected: a ban that also blocks invites (the leader could never undo a kick by inviting again). + +### D4. Request on a public party joins directly; join on a private party is refused + +`POST /v1/players/{playerId}/party/requests` on a public party performs the join and answers `200 Party`. On a private +party it creates a request and answers `201 JoinRequest`. The plugin tells the two apart by the status code. The player +therefore never sees an error for asking a public party. `POST /v1/players/{playerId}/party/join` on a private party +answers `409 party-not-public`, whose message points to `/party request`. +Rejected: one endpoint that always creates a request (a public party would then need a second answer step for nothing). + +### D5. Target and requester checks + +The target is resolved by name through presence, as an invite does (`player-not-online` when offline). A target that is +not in a party answers `404 target-not-in-party`. The reused code `not-in-party` would say "You are not in a party" to +the requester, which is wrong, so a new code is used. A requester already in a party answers `already-in-party`. A +requester who is not online answers `player-not-online`. + +### D6. Lonely-party expiry applies to public parties unchanged + +A public party with only one member expires after `QUELEA_PARTY_ALONE_TIMEOUT` like any other, counted from its alone +period (`aloneSince`, see D10; the creation time when it was never alone since). Rejected: exempting open parties, which +would leave forgotten open parties around for ever. + +### D7. State: Dragonfly only, TTL keys, the version covers the party + +- Public flag: the field `public` on the `Party` record. Every change bumps the version, so ETags and `If-Match` cover it + as they cover membership. +- Join requests: key `join-request::`, JSON, `px` = `QUELEA_JOIN_REQUEST_TTL`. The key is + the duplicate check and the expiry. +- Cooldown: key `join-cooldown::`. Its three writes give these exact rules (each is a scenario + in the `party-management` delta, "Request cooldown"): + - Creating a request sets `px` to TTL + cooldown. While the request is pending it is the duplicate check; after an + expiry, which publishes nothing, it blocks the player until exactly the cooldown has passed since the expiry. + - A rejection overwrites the key with `px` = cooldown, so a fresh cooldown of exactly that length starts at the + moment of the denial. + - An accepted request deletes the key, so a player who joined, later left, and asks again is not held back. +- Ban set: a Redis set `party::bans` with the player ids, deleted in `disbandParty`. Deviation from + "on the party": the ban set is not in the party JSON, so the proxies do not receive the ids of kicked players. The + kick that adds a ban already bumps the version in the same locked command, so `If-Match` and ETags cover the change. +- Writes follow the existing `Idempotency-Key` and `If-Match` behaviour. The API change is additive (new routes, a new + field, new problem codes), so oasdiff stays green. + +Rejected: a join-request list in the party JSON (the leader would then see requests of people who are not in the party +state, and the field would grow with every request); a relational table (principle 1). + +### D8. New events for the prompt and the answer + +Names follow the existing `party.` convention: +- `party.join-requested` (payload `requesterId`, `requesterName`, `expiresAt`): the plugin tells the leader, if local. +- `party.join-request-answered` (payload `requesterId`, `requesterName`, `outcome` = `accepted` or `denied`): the plugin + tells the requester, if local. + +Follow, warp and chat are unchanged. A warp with 20 members can hit a full server; the existing connect-failure handling +applies to every member, unchanged. +Accepted requests also publish `party.joined` to the members, as an invite does. Expiry publishes nothing (see Risks). + +### D9. Metrics: no new meter + +The existing `quelea_party_operations_total{operation,result}` counts the new operations by name (`public`, `join`, +`request`, `accept`, `reject`). That is enough to see requests and answers without a new meter, and no player id is ever +a tag. `observability` does not change. + +### D10. Interaction with keep-parties-after-members-leave + +`keep-parties-after-members-leave` (merged as a proposal, fix in progress) keeps a party that a leave or a kick reduces +to one member. The party keeps its id, and its alone period starts at the departure, stored as `aloneSince`; the alone +end is `(aloneSince ?? createdAt) + QUELEA_PARTY_ALONE_TIMEOUT`. This change builds on it as follows: + +- **Non-leader departure keeps a public party open.** When a member other than the leader leaves or is kicked and one + member remains, the party stays public. It keeps its id, its ban set and its flag, and starts the alone period at the + departure. +- **Leader departure closes it.** When the leader leaves or is kicked, the successor becomes leader, and D2 clears + `public`. The alone period still starts at the departure. +- **Expiry is unchanged (D6).** It reads the same `aloneSince ?? createdAt` value; this change adds no field. +- **A join ends the alone period** as keep-parties specifies, for public and private parties alike. +- **Overlap.** The keep-parties design says the two changes do not touch the same branch. They do share + `PartyService.removeMember`, where the leadership change clears `public`. Whichever change lands second rebases onto + the first; the test for the leader departure (task 3.9) covers that path. + +Rejected: a separate alone period for public parties, which would make a party's expiry depend on its visibility. + +### Command and endpoint names + +| Concept | Name | +|---|---| +| Open (permission) or close (any leader) | `POST /v1/parties/{partyId}/public`, body `{actorId, public}`, `If-Match` | +| Direct join | `POST /v1/players/{playerId}/party/join`, body `{targetName}` | +| Request | `POST /v1/players/{playerId}/party/requests`, body `{targetName}`: 201 request or 200 party | +| Accept request | `POST /v1/parties/{partyId}/join-requests/accept`, body `{actorId, requesterName}`, `If-Match` | +| Reject request | `POST /v1/parties/{partyId}/join-requests/reject`, body `{actorId, requesterName}` | +| Problems | `party-not-public` (409), `join-request-pending` (409), `join-request-cooldown` (429, `Retry-After`), `join-request-not-found` (404), `party-banned` (403), `target-not-in-party` (404) | +| Events | `party.join-requested`, `party.join-request-answered` | +| Commands | `/party public on|off`, `/party request `, `/party join `, `/party approve `, `/party reject ` | + +The leader's clickable prompt runs `/party approve ` and `/party reject `. The name is resolved by the +backend, as invites are, so the proxy keeps no request state. `/party accept` and `/party deny` stay the invitee's +commands. + +Rejected for the answer: a request id in the path (the plugin would have to cache the id from the event, and a proxy +restart would lose it). + +## Mixed-version compatibility + +Checked in the code on `origin/main`: + +- **Unknown event types are ignored.** `EventHandler.handle` has a `default` branch that does nothing, with a comment + saying so on purpose. An old plugin receiving `party.join-requested` or `party.join-request-answered` ignores them. +- **Unknown JSON fields are ignored.** `QueleaJson` and `PartyEvent.parse` read named keys from Gson `JsonObject`s and + never reject extra keys. A new `public` field on the party JSON and new payload keys are ignored by a 0.4.x plugin. +- **New plugin, old backend.** The new routes answer `404 not-found`; the plugin shows the existing `problem.not-found` + text. Nothing else changes for the old backend. +- **Old plugin, new backend.** Old plugins never call the new routes, so they cannot create requests or public parties. +- **Real gap: a leader on an old proxy.** A request made through a new proxy reaches the leader's proxy only through the + event. If that proxy runs an old plugin, the prompt is silently dropped and the request expires. The requester sees + "request sent" and nothing else. Mitigation is part of the rollout: install the new plugin on every proxy before the + first player uses `/party request`. Nothing in the backend can detect the old plugin. + +## Risks / Trade-offs + +- A requester whose request expires gets no message, and the leader's prompt expires silently. The request answer + says how long the request lasts, so the requester is not left guessing. Publishing an expiry event would need a + scheduled job like the lonely-party expiry; that is a later change if players ask for it. +- A public party above 8 members that the leader then closes keeps its members, with no way to add more until the size + drops. Accepted: no member is removed by a setting change. +- A player who was kicked can still be targeted by a leader's invite at any time; the invite lifts the ban, by design (D3). +- A party disbanded with a request still open leaves the request and cooldown keys to expire on their own, within the + request TTL and cooldown. Their party id is never reused, so they cannot block a later party. diff --git a/openspec/changes/add-open-party-joining/proposal.md b/openspec/changes/add-open-party-joining/proposal.md new file mode 100644 index 0000000..7ed4877 --- /dev/null +++ b/openspec/changes/add-open-party-joining/proposal.md @@ -0,0 +1,65 @@ +# Proposal + +**Ships as:** `feat(party)`: one code pull request `feat(party): let players ask to join and open parties to everyone`. + +## Why + +Today a player can only enter a party through an invite from its leader. A player who wants to join a friend has to ask +in chat, and the friend then has to find the right command. Streamers cannot let their viewers in at all without +inviting each one by hand, which does not scale past a handful of people. + +Two things are asked for. A player should be able to ask a party to let them in, and the leader should be able to say +the party is open, so that anyone who knows the leader's name can walk in. Both must keep the party under the control of +its leader: a join request is answered by the leader, and a kicked player does not come back on their own. + +## What Changes + +- **Join requests.** `/party request ` sends a request to the party of that player. The leader gets a clickable + prompt and accepts or rejects it. A request expires after 60 seconds, like an invite. A player has at most one open + request per party, and after an expiry or a rejection may ask again only after a cooldown (60 seconds by default). +- **Public parties.** A leader with the Velocity permission `quelea.party.public` opens the party with `/party public on`. + Any leader may close it with `/party public off`, so a leader who lost the permission can still close. While it is + open, `/party join ` puts the player straight in, with no request. +- **Own size for public parties.** A public party holds up to `QUELEA_PARTY_PUBLIC_MAX_SIZE` members (20 by default). + Private parties keep `QUELEA_PARTY_MAX_SIZE` (8). A full party answers with the existing `party-full` problem. +- **Discovery by name only.** There is no list and no broadcast of public parties. +- **Kick ban.** A kicked player cannot join or request that party while it exists. An explicit invite from the leader + lifts the ban for that player. The ban list belongs to the party and disappears with it. +- **Velocity plugin** gains the commands `public`, `request`, `join`, `approve` and `reject`, the help lines for them, and + the messages in English and German. + +## Capabilities + +### New Capabilities +None. + +### Modified Capabilities +- `party-management`: join requests, public parties, kick ban, public size limit, leadership change closes a public party. +- `party-events`: two new events for the leader's prompt and the requester's answer. +- `velocity-plugin`: the new commands, the permission check, the messages. +- `problem-details`: six new documented codes. + +The metrics need no new meter. The existing `quelea_party_operations_total{operation,result}` counts the new operations +by name, so `observability` does not change. + +## Out of Scope + +- Listing or announcing public parties (no `/party list public`, no broadcast in chat). +- Password-protected parties. +- Party bans that outlive the party. A ban ends with the party. +- Redirecting chat with `@name` to a join request. +- Notifying the members when the leader opens or closes the party. The party state carries the flag; no event is added. +- Telling the leader that a request expired. Expiry is a TTL in Dragonfly and publishes nothing. + +## Impact + +- Backend: `api/PartyController` (public, join, join-requests), `api/PlayerController` (join, requests), `party/Party` + (public flag), `party/PartyService`, `party/PartySettings`, `party/port/PartyStore` and its Redis adapter, `event` + (two types), `problem/PartyProblem` (six codes), OpenAPI (generated from annotations; no committed client exists). +- Velocity: `command/PartyCommands`, `command/PartyActions`, `command/HelpText`, `event/EventHandler`, + `player/LocalPlayer` (permission check), `http/QueleaGateway` and `HttpQueleaGateway`, `lang/messages_en` and + `messages_de`. +- Documentation: `docs/problems.md` (a section per new code, enforced by `ProblemDocsTest`), README command and + configuration tables. +- Configuration: `QUELEA_PARTY_PUBLIC_MAX_SIZE`, `QUELEA_JOIN_REQUEST_TTL`, `QUELEA_JOIN_REQUEST_COOLDOWN`, with defaults + in `application.yml`. No Kubernetes change is needed. diff --git a/openspec/changes/add-open-party-joining/specs/party-events/spec.md b/openspec/changes/add-open-party-joining/specs/party-events/spec.md new file mode 100644 index 0000000..963ea19 --- /dev/null +++ b/openspec/changes/add-open-party-joining/specs/party-events/spec.md @@ -0,0 +1,36 @@ +# Spec Delta + +## Purpose +Event model for join requests and their answers. + +## ADDED Requirements + +### Requirement: Join request events +When a player requests a join to a private party, the service SHALL publish `party.join-requested` with the requester's id and name and the expiry time. When the leader answers the request, the service SHALL publish `party.join-request-answered` with the requester's id, the requester's name and the outcome `accepted` or `denied`. Both events carry the party's members, the leader and the party version, as the other party events do. Clients SHALL ignore event types they do not know. + +#### Scenario: Leader is prompted +- **WHEN** B requests a join to private party P led by A +- **THEN** a `party.join-requested` event with B's id, B's name and the expiry is published, and the leader's plugin prompts A + +#### Scenario: Requester is told the answer +- **GIVEN** B holds a request to P +- **WHEN** A rejects it +- **THEN** a `party.join-request-answered` event with outcome `denied` names B as requester + +#### Scenario: Accepted request +- **GIVEN** B holds a request to P +- **WHEN** A accepts it +- **THEN** a `party.join-request-answered` event with outcome `accepted` and a `party.joined` event are published + +#### Scenario: Expiry publishes nothing +- **GIVEN** B's request to P expires unanswered +- **WHEN** the expiry passes +- **THEN** no event is published for it + +### Requirement: Public join event +A join to a public party SHALL publish `party.joined` like an accepted invite does, so the members learn of the new member. + +#### Scenario: Public join event +- **GIVEN** public party P with leader A +- **WHEN** B joins P directly +- **THEN** a `party.joined` event naming B is published diff --git a/openspec/changes/add-open-party-joining/specs/party-management/spec.md b/openspec/changes/add-open-party-joining/specs/party-management/spec.md new file mode 100644 index 0000000..7fffd7e --- /dev/null +++ b/openspec/changes/add-open-party-joining/specs/party-management/spec.md @@ -0,0 +1,163 @@ +# Spec Delta + +## Purpose +Party membership rules: join requests, public parties, kick ban and the size limits. + +## ADDED Requirements + +### Requirement: Join requests +A player who is not in a party SHALL be able to ask the party of an online player to let them in. The service SHALL resolve the target name case-insensitively against the network presence and keep at most one open request per party and requester, for `QUELEA_JOIN_REQUEST_TTL` (default 60 seconds). The leader SHALL accept or reject it. + +#### Scenario: Request accepted +- **GIVEN** party P is private with leader A, and player B is not in a party +- **WHEN** B requests a join to "a" and A accepts B +- **THEN** B is a member of P and the request is gone + +#### Scenario: Request denied +- **GIVEN** B holds an open request to P +- **WHEN** A rejects B +- **THEN** the request is gone and B is in no party + +#### Scenario: Request expires +- **GIVEN** B requested P 60 seconds ago and A did not answer +- **WHEN** A accepts B now +- **THEN** the service answers 404 `join-request-not-found` and the party is unchanged + +#### Scenario: Duplicate request +- **GIVEN** B holds an open request to P +- **WHEN** B requests P again +- **THEN** the service answers 409 `join-request-pending` and holds one request only + +#### Scenario: Requester already in a party +- **WHEN** a player who is in a party requests another party +- **THEN** the service answers 409 `already-in-party` + +#### Scenario: Target without a party +- **WHEN** a player requests the party of a target who is online but not in a party +- **THEN** the service answers 404 `target-not-in-party` + +#### Scenario: Offline target +- **WHEN** a player requests a name that is not online on any proxy +- **THEN** the service answers 404 `player-not-online` + +#### Scenario: Answer by someone else +- **WHEN** a member who is not the leader accepts or rejects a request +- **THEN** the service answers 403 `not-leader` + +### Requirement: Request cooldown +After a request ends by rejection or by expiry, the service SHALL refuse a new request from the same player to the same party for `QUELEA_JOIN_REQUEST_COOLDOWN` (default 60 seconds), answering 429 `join-request-cooldown` with `Retry-After`. An accepted request SHALL clear the cooldown. The cooldown is measured from the denial after a rejection, and from the expiry, which is the end of the request's TTL, after an expiry. + +#### Scenario: Cooldown after a denial +- **GIVEN** A rejects B's request to P at 10:00:00 +- **WHEN** B requests P at 10:00:59 +- **THEN** the service answers 429 `join-request-cooldown` with `Retry-After: 1` +- **AND** a request at 10:01:00 is held as a new request (201) + +#### Scenario: Cooldown after an expiry +- **GIVEN** B's request to P was created at 10:00:00 and expired unanswered at 10:01:00 +- **WHEN** B requests P at 10:01:59 +- **THEN** the service answers 429 `join-request-cooldown` with `Retry-After: 1` +- **AND** a request at 10:02:00 is held as a new request (201) + +#### Scenario: Accepted request clears the cooldown +- **GIVEN** B's request to P was accepted and B later left P +- **WHEN** B requests P at once +- **THEN** the request is held (201) and no cooldown applies + +#### Scenario: Pending request is not a cooldown +- **GIVEN** B holds an open request to P +- **WHEN** B requests P again +- **THEN** the answer is 409 `join-request-pending`, not 429 + +### Requirement: Public parties +The service SHALL open or close a party on `POST /v1/parties/{partyId}/public`, from the party leader only. While a party is public, any online player not in a party SHALL be able to join it directly, answered 200 with the party. Every change of the flag SHALL bump the party version. The service needs no permission to close; the proxy checks it for opening only. + +#### Scenario: Public join +- **GIVEN** party P is public with leader A +- **WHEN** B joins P by name "a" +- **THEN** B is a member of P and a `party.joined` event is published + +#### Scenario: Request on a public party joins directly +- **GIVEN** party P is public +- **WHEN** B requests P by name +- **THEN** the service answers 200 with the party, B is a member, and no request is held + +#### Scenario: Join on a private party refused +- **GIVEN** party P is private +- **WHEN** B joins P by name +- **THEN** the service answers 409 `party-not-public` and B is in no party + +#### Scenario: Public party full at 20 +- **GIVEN** public party P with 20 members +- **WHEN** B joins P +- **THEN** the service answers 409 `party-full` and P is unchanged + +#### Scenario: Only the leader changes the flag +- **WHEN** a member who is not the leader sets the public flag +- **THEN** the service answers 403 `not-leader` + +#### Scenario: Closing after the permission was lost +- **GIVEN** leader A has a public party and no longer holds `quelea.party.public` +- **WHEN** A closes the party +- **THEN** the service accepts the change and the party is not public + +### Requirement: Kick ban +A player kicked from a party SHALL NOT join or request that party while it exists. An invite from the leader to that player SHALL lift the ban for that player. The ban SHALL end with the party. + +#### Scenario: Kicked player blocked from join +- **GIVEN** B was kicked from public party P +- **WHEN** B joins P +- **THEN** the service answers 403 `party-banned` + +#### Scenario: Kicked player blocked from request +- **GIVEN** B was kicked from private party P +- **WHEN** B requests P +- **THEN** the service answers 403 `party-banned` and no request is held + +#### Scenario: Invite lifting the ban +- **GIVEN** B was kicked from P +- **WHEN** the leader of P invites B +- **THEN** B holds the invite, and B can join P through it + +#### Scenario: Ban ends with the party +- **GIVEN** B was kicked from P and P is disbanded +- **WHEN** the same leader creates a new party and B asks to join it +- **THEN** B is not banned from the new party + +## MODIFIED Requirements + +### Requirement: Size limit +If a party already has the maximum number of members for its visibility, then the service SHALL reject invites, accepts, join requests and joins for it with 409 `party-full`. The maximum is `QUELEA_PARTY_PUBLIC_MAX_SIZE` for a public party and `QUELEA_PARTY_MAX_SIZE` for a private one. A party that is above the private maximum when it is closed keeps its members and rejects new members. + +#### Scenario: Full party +- **GIVEN** a private party with the maximum number of members +- **WHEN** an invited player accepts +- **THEN** the service answers 409 `party-full` and the party is unchanged + +#### Scenario: Closed above the private limit +- **GIVEN** a public party with 12 members that the leader closes +- **WHEN** B is invited to it +- **THEN** the service answers 409 `party-full` and the 12 members stay + +### Requirement: Leaving and leadership +When a member leaves, is kicked or disconnects, the service SHALL remove them from the party; when that member was the leader, the service SHALL make the longest-standing remaining member leader; when no member remains, the service SHALL disband the party. A party left with one member stays open as `keep-parties-after-members-leave` specifies. A change of leader SHALL clear the public flag of the party. + +#### Scenario: Leader leaves +- **GIVEN** a party with leader A and members B (joined first) and C +- **WHEN** A leaves +- **THEN** B is leader and the party has members B and C + +#### Scenario: Only member leaves +- **GIVEN** a party whose only member is A +- **WHEN** A leaves +- **THEN** the party is disbanded with reason `last-member-left` and A is in no party + +#### Scenario: Leader leaves a public party +- **GIVEN** a public party of A, B and C +- **WHEN** A leaves +- **THEN** B is leader, the party is not public, and members B and C stay + +#### Scenario: Promotion closes a public party +- **GIVEN** a public party led by A with member B +- **WHEN** A promotes B +- **THEN** B is leader and the party is not public diff --git a/openspec/changes/add-open-party-joining/specs/problem-details/spec.md b/openspec/changes/add-open-party-joining/specs/problem-details/spec.md new file mode 100644 index 0000000..f7e4f46 --- /dev/null +++ b/openspec/changes/add-open-party-joining/specs/problem-details/spec.md @@ -0,0 +1,52 @@ +# Spec Delta + +## Purpose +New documented error codes for join requests, public parties and kick bans. + +## ADDED Requirements + +### Requirement: Codes for joining a party +The service SHALL answer `party-not-public` (409) when a join targets a private party, `party-banned` (403) when a kicked player joins or requests the party, and `target-not-in-party` (404) when the target of a join or request is in no party. + +#### Scenario: Private party join +- **WHEN** a player joins a private party by name +- **THEN** the response is 409 with code `party-not-public` and a message that names `/party request` + +#### Scenario: Banned player +- **WHEN** a kicked player joins or requests the party +- **THEN** the response is 403 with code `party-banned` + +#### Scenario: Target in no party +- **WHEN** a player requests the party of a target who is in no party +- **THEN** the response is 404 with code `target-not-in-party` + +### Requirement: Codes for join requests +The service SHALL answer `join-request-pending` (409) for a duplicate request, `join-request-cooldown` (429, with a `Retry-After` header of the whole seconds left) for a request inside the cooldown, and `join-request-not-found` (404) when the leader answers a request that is not open. + +#### Scenario: Duplicate request +- **WHEN** a player requests a party that already holds an open request of theirs +- **THEN** the response is 409 with code `join-request-pending` + +#### Scenario: Cooldown carries Retry-After +- **WHEN** the service answers `join-request-cooldown` +- **THEN** the response has a `Retry-After` header with the whole seconds left + +#### Scenario: Answer to an expired request +- **WHEN** the leader accepts or rejects a request that has expired +- **THEN** the response is 404 with code `join-request-not-found` + +### Requirement: Every new code is documented and translated +Every new code SHALL have a section of its own in `docs/problems.md`, a `problem.` key in the English and the German message bundle, and a row in `MessagesTest`. A code without an English key is reported to Sentry by the plugin as undocumented; with the key present, `join-request-cooldown` (429) and the other new codes are not reported. + +#### Scenario: Documented in the docs +- **WHEN** a new code is added to `PartyProblem` +- **THEN** `docs/problems.md` has a `## ` section for it + +#### Scenario: Translated in both bundles +- **WHEN** a new code is added +- **THEN** `messages_en.properties` and `messages_de.properties` each contain `problem.` + +#### Scenario: Cooldown is not reported to Sentry +- **GIVEN** the English bundle has `problem.join-request-cooldown` +- **WHEN** the plugin receives a 429 `join-request-cooldown` answer +- **THEN** `FailureReports` does not send it to Sentry diff --git a/openspec/changes/add-open-party-joining/specs/velocity-plugin/spec.md b/openspec/changes/add-open-party-joining/specs/velocity-plugin/spec.md new file mode 100644 index 0000000..546f969 --- /dev/null +++ b/openspec/changes/add-open-party-joining/specs/velocity-plugin/spec.md @@ -0,0 +1,65 @@ +# Spec Delta + +## Purpose +The proxy side: the new commands, the permission check, the prompts and the messages. + +## ADDED Requirements + +### Requirement: Public party command +The plugin SHALL offer `/party public on` and `/party public off`. `on` SHALL be sent to the service only when the player holds the Velocity permission `quelea.party.public`; otherwise the proxy SHALL refuse it and the service SHALL NOT be called. `off` SHALL be sent for any leader, with no permission check, so a leader who lost the permission can close the party. The check is made by the plugin because the service has no notion of Minecraft permissions. + +#### Scenario: Opening without the permission +- **GIVEN** a leader without `quelea.party.public` +- **WHEN** the leader runs `/party public on` +- **THEN** the proxy answers that the player may not open a party, and no request reaches the service + +#### Scenario: Opening with the permission +- **GIVEN** a leader with `quelea.party.public` +- **WHEN** the leader runs `/party public on` +- **THEN** the service is asked to open the party and the leader reads that it is open + +#### Scenario: Closing without the permission +- **GIVEN** a leader without `quelea.party.public` who leads an open party +- **WHEN** the leader runs `/party public off` +- **THEN** the service is asked to close the party and the leader reads that it is closed + +### Requirement: Join and request commands +The plugin SHALL offer `/party join ` and `/party request ` to players who are not in a party. Their answers SHALL be shown in the player's language. A request to a public party answers that the player joined. A join to a private party answers with the `party-not-public` text, which names `/party request`. + +#### Scenario: Request sent +- **WHEN** B runs `/party request a` for a private party +- **THEN** B reads that the request was sent and how long it stays open + +#### Scenario: Join refused for a private party +- **WHEN** B runs `/party join a` for a private party +- **THEN** B reads the `party-not-public` text that names `/party request` + +### Requirement: Approve and reject commands +The plugin SHALL offer `/party approve ` and `/party reject ` to the leader. The leader's prompt for a join request SHALL contain a clickable `[Approve]` that runs `/party approve ` and a clickable `[Reject]` that runs `/party reject `. + +#### Scenario: Leader approves from the prompt +- **GIVEN** the leader received a prompt for B +- **WHEN** the leader clicks `[Approve]` +- **THEN** the service is asked to accept B's request and B becomes a member + +### Requirement: Join request messages +When the plugin receives `party.join-requested` for a party whose leader is a local player, it SHALL prompt the leader with the requester's name and the two buttons. When it receives `party.join-request-answered`, it SHALL tell the requester, if local, that the request was accepted or denied. + +#### Scenario: Leader prompt +- **WHEN** `party.join-requested` arrives for a local leader +- **THEN** the leader reads that B asks to join, with `[Approve]` and `[Reject]` + +#### Scenario: Requester told of a denial +- **WHEN** `party.join-request-answered` arrives with outcome `denied` for a local requester +- **THEN** the requester reads that the party declined the request + +#### Scenario: Unknown event type +- **WHEN** an event type the plugin does not know arrives +- **THEN** the plugin ignores it + +### Requirement: Help lists the new commands +The `/party` help SHALL list `public`, `request`, `join`, `approve` and `reject` with a hover text in each language, and the English and German bundles SHALL carry the same keys. + +#### Scenario: Help shows the new lines +- **WHEN** a player runs `/party` without arguments +- **THEN** the help lists the new commands in the player's language diff --git a/openspec/changes/add-open-party-joining/tasks.md b/openspec/changes/add-open-party-joining/tasks.md new file mode 100644 index 0000000..f4c6dc6 --- /dev/null +++ b/openspec/changes/add-open-party-joining/tasks.md @@ -0,0 +1,103 @@ +# Tasks + +Tests follow F.I.R.S.T.: unit tests use the in-memory fakes and an injected `Clock`; Redis tests are tagged `integration`. +No sleeps. Each test asserts one behaviour. + +## 1. Configuration and model (backend) + +- [ ] 1.1 `PartySettings`: `publicMaxSize` (`QUELEA_PARTY_PUBLIC_MAX_SIZE`, 20, minimum equal to `maxSize`), + `joinRequestTtl` (`QUELEA_JOIN_REQUEST_TTL`, 60s), `joinRequestCooldown` (`QUELEA_JOIN_REQUEST_COOLDOWN`, 60s); + defaults in `application.yml`. +- [ ] 1.2 `Party` gets `public` (boolean, default false). `withLeader` clears it. Tests: a promotion clears the flag, a + member change keeps it, both bump the version. +- [ ] 1.3 `JoinRequest` record (partyId, requesterId, requesterName, expiresAt), `@Serdeable`. + +## 2. Store port and Redis adapter (backend) + +- [ ] 2.1 `PartyStore` methods: `saveJoinRequest(JoinRequest, Duration)`, `findJoinRequest`, `deleteJoinRequest`, + `setCooldown(partyId, playerId, Duration)`, `cooldownLeft(partyId, playerId)`, `ban`, `unban`, `isBanned`, + `deleteBans(partyId)`. +- [ ] 2.2 `InMemoryPartyStore` in tests implements them with an injected `Clock` for expiry. +- [ ] 2.3 `RedisKeys`: `join-request::`, `join-cooldown::`, `party::bans`. +- [ ] 2.4 `RedisPartyStore` adapter, with an `integration` test: request key expires at its TTL; the cooldown key is + overwritten by a rejection; the ban set is deleted with the party. + +## 3. Service rules (backend) + +- [ ] 3.1 Failing tests first, in `PartyServiceTest` with a fixed `Clock`: + request accepted, request denied, request expired, duplicate request, requester already in a party, target without + a party, offline target, not-leader answer. Cooldown: denial at 10:00:00 gives 429 at 10:00:59 and 201 at + 10:01:00; expiry at 10:01:00 of a request created at 10:00:00 gives 429 at 10:01:59 and 201 at 10:02:00; an + accepted request, later left, allows an immediate new request; a pending request answers `join-request-pending`, + not 429. +- [ ] 3.2 `PartyService.requestJoin(requesterId, targetName)`: resolves the target by presence, creates the request + under the party lock, or joins directly when the party is public (answers the party, not a request). +- [ ] 3.3 `PartyService.join(playerId, targetName)`: public parties only (`party-not-public` otherwise), ban check, + `ensureRoom` with the public limit, publishes `party.joined`. +- [ ] 3.4 `PartyService.acceptRequest` and `rejectRequest` (leader only, `requesterName` resolved by presence): accept + joins through the same path as an invite and deletes the request and the cooldown keys; reject deletes the request + key and overwrites the cooldown with `px` = cooldown. +- [ ] 3.5 `PartyService.setPublic(partyId, actorId, public, precondition)`: leader only, bumps the version. +- [ ] 3.6 Kick: failing test first (kicked player blocked from join and request, ban ends with the party), then the ban + write in the same locked command as the member removal. +- [ ] 3.7 Invite lifts the ban: failing test first (kicked player invited, then joins through the invite), then + `unban` in the locked invite. +- [ ] 3.8 `ensureRoom` uses `publicMaxSize` for a public party and `maxSize` otherwise; a public party above the + private limit rejects new members (test: closed with 12 members, invite answered `party-full`). +- [ ] 3.9 Leadership change (promote and succession) clears `public`; test for both. Keep-parties interaction (D10), + failing tests first: a non-leader leave or kick that leaves one member keeps `public` and starts the alone period + at the departure; a leader leave that leaves one member clears `public` and starts the alone period; a join ends + the alone period. +- [ ] 3.10 Events: `JOIN_REQUESTED` (`party.join-requested`) and `JOIN_REQUEST_ANSWERED` (`party.join-request-answered`) + added to `PartyEventType` with payloads as in the spec. + +## 4. Problems (backend) + +- [ ] 4.1 `PartyProblem`: `PARTY_NOT_PUBLIC`, `JOIN_REQUEST_PENDING`, `JOIN_REQUEST_COOLDOWN` (429), `JOIN_REQUEST_NOT_FOUND`, + `PARTY_BANNED`, `TARGET_NOT_IN_PARTY`. +- [ ] 4.2 `Retry-After` header on `join-request-cooldown`; test with the seconds left. +- [ ] 4.3 `docs/problems.md`: one section per code (enforced by `ProblemDocsTest`). + +## 5. API (backend) + +- [ ] 5.1 `PartyController`: `POST /v1/parties/{partyId}/public` (`If-Match`), `POST /v1/parties/{partyId}/join-requests/accept` + (`If-Match`), `POST /v1/parties/{partyId}/join-requests/reject`. Each with its OpenAPI annotations and the same + `Idempotency-Key` behaviour as the other commands. +- [ ] 5.2 `PlayerController`: `POST /v1/players/{playerId}/party/join` (200 party) and + `POST /v1/players/{playerId}/party/requests` (201 `JoinRequest` or 200 party for a public party). +- [ ] 5.3 `RouteCoverageTest` and `ConditionalRequestsTest` extended for the new routes; `oasdiff` run locally against + `origin/main` (additive changes only). + +## 6. Velocity plugin + +- [ ] 6.1 `LocalPlayer.hasPermission(String)`; `VelocityLocalPlayers` implements it through Velocity; `FakeLocalPlayer` + in tests answers from a set. Tests: `on` without the permission makes no call to the service; `off` without the + permission calls the service. +- [ ] 6.2 `QueleaGateway` and `HttpQueleaGateway`: `setPublic`, `join`, `request` (a sealed result: request or party by + status code), `acceptRequest`, `rejectRequest`. Tests with a local HTTP server for the 201/200 split and the 429 + `Retry-After`. +- [ ] 6.3 `PartyActions`: `publicOn`, `publicOff`, `join`, `request`, `approve`, `reject`. `FakeQueleaGateway` extended. +- [ ] 6.4 `PartyCommands`: `public on|off`, `request `, `join `, `approve `, `reject `; + `HelpText` lines for them. +- [ ] 6.5 `EventHandler`: `party.join-requested` prompts the local leader with `[Approve]` and `[Reject]`; + `party.join-request-answered` tells the local requester. Test each, plus an unknown type. +- [ ] 6.6 `messages_en.properties` and `messages_de.properties`: every new key, including `problem.party-not-public`, + `problem.join-request-pending`, `problem.join-request-cooldown`, `problem.join-request-not-found`, + `problem.party-banned` and `problem.target-not-in-party` in both (`FailureReports` treats a code without an English + key as undocumented). `MessagesTest` `PROBLEM_CODES` extended with the six new codes. + +## 7. Documentation + +- [ ] 7.1 README: player command table (five new rows), configuration table (three new variables), the event list and + the join rules under "How it works". + +## 8. Verification + +- [ ] 8.1 `./gradlew :backend:test -PexcludeTags=integration` and `./gradlew :velocity:test` green, no sleeps, no + wall-clock reads in the new tests. +- [ ] 8.2 `./gradlew build` green. + +## 9. Pull request + +- [ ] 9.1 Open the code pull request `feat(party): let players ask to join and open parties to everyone` from a branch + cut from the remote main branch that already contains the merged proposal. It contains no file under `openspec/`.