forked from mtusi2026/mtusi2026lab2
Carry over the agent context and openspec history from lab 4
Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 4 specs and the
archived lab 1 to lab 4 changes into the lab 5 skeleton, so lab 5
continues the same spec history instead of starting from scratch. The
files come from the lab 4 solution commit d2744bc.
Rewrite AGENTS.md and the openspec context and rules for lab 5: upload
answers 202 queued after the original is in a private staging prefix
and the attachment, the job and the outbox row are committed in one
transaction, a separate relay publishes the outbox to RabbitMQ with
publisher confirms, a separate worker built from the same image
consumes the queue through FastStream with a manual ack after the
result commit, PostgreSQL stays the source of truth for job states,
Out of scope moves to labs 6-7, track 1 and broker HA, and the rules
add the failure windows between PostgreSQL and the broker, the effect
key and the lease to specs and designs.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
276dbdad8a
commit
1210dd899c
@@ -0,0 +1,181 @@
|
||||
---
|
||||
name: "OPSX: Apply"
|
||||
description: "Implement tasks from an OpenSpec change (Experimental)"
|
||||
allowed-tools: Bash(openspec:*)
|
||||
category: "Workflow"
|
||||
tags: ["workflow", "artifacts", "experimental"]
|
||||
---
|
||||
|
||||
Implement tasks from an OpenSpec change.
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Select the change**
|
||||
|
||||
If a name is provided, use it. Otherwise:
|
||||
- Infer from conversation context if the user mentioned a change
|
||||
- Auto-select if only one active change exists
|
||||
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
|
||||
|
||||
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
|
||||
|
||||
2. **Check status to understand the schema**
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
Parse the JSON to understand:
|
||||
- `schemaName`: The workflow being used (e.g., "spec-driven")
|
||||
- `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
|
||||
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
|
||||
|
||||
3. **Get apply instructions**
|
||||
|
||||
```bash
|
||||
openspec instructions apply --change "<name>" --json
|
||||
```
|
||||
|
||||
This returns:
|
||||
- `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
|
||||
- Progress (total, complete, remaining)
|
||||
- Task list with status
|
||||
- Dynamic instruction based on current state
|
||||
- Optional `context`: current required project instruction input from the selected root
|
||||
- Optional `operationGuidance`: current advisory guidance for apply
|
||||
|
||||
**Handle states:**
|
||||
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue` (if it is not installed, run `openspec status --change "<name>" --json` to see the next artifact and `openspec instructions <artifact-id> --change "<name>" --json` for how to create it)
|
||||
- If `state: "all_done"`: congratulate, suggest archive
|
||||
- Otherwise: proceed to implementation
|
||||
|
||||
Treat `context` as a required prompt-level input. Read and consider it, and
|
||||
apply relevant project facts, conventions, and constraints while implementing.
|
||||
Treat `operationGuidance` as optional additive advice. Read and consider every
|
||||
entry, and follow entries that are applicable and compatible with the built-in
|
||||
workflow.
|
||||
|
||||
Keep both fields separate from CLI-returned state, missing artifacts, tasks,
|
||||
progress, `contextFiles`, and the built-in `instruction`. They are not
|
||||
evidence of task completion, do not replace the built-in instruction, and do
|
||||
not permit bypassing a blocked state. If context conflicts with the built-in
|
||||
instruction, an explicit user choice, or a CLI-controlled value, report the
|
||||
conflict and preserve the controlling value. If guidance is inapplicable or
|
||||
conflicts with those controlling inputs, do not follow it and explain why.
|
||||
These are prompt-level behavior contracts, not enforceable checks.
|
||||
|
||||
4. **Read context files**
|
||||
|
||||
Read every file path listed under `contextFiles` from the apply instructions output.
|
||||
The files depend on the schema being used:
|
||||
- **spec-driven**: proposal, specs, design, tasks
|
||||
- Other schemas: follow the contextFiles from CLI output
|
||||
|
||||
Do not copy `context` or `operationGuidance` verbatim into implementation
|
||||
files or planning artifacts unless the user separately asks for that content.
|
||||
|
||||
5. **Show current progress**
|
||||
|
||||
Display:
|
||||
- Schema being used
|
||||
- Progress: "N/M tasks complete"
|
||||
- Remaining tasks overview
|
||||
- Dynamic instruction from CLI
|
||||
|
||||
6. **Implement tasks (loop until done or blocked)**
|
||||
|
||||
For each pending task:
|
||||
- Show which task is being worked on
|
||||
- Make the code changes required
|
||||
- Keep changes minimal and focused
|
||||
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
|
||||
- Continue to next task
|
||||
|
||||
**Pause if:**
|
||||
- Task is unclear → ask for clarification
|
||||
- Implementation reveals a design issue → suggest updating artifacts
|
||||
- Error or blocker encountered → report and wait for guidance
|
||||
- User interrupts
|
||||
|
||||
7. **On completion or pause, show status**
|
||||
|
||||
Display:
|
||||
- Tasks completed this session
|
||||
- Overall progress: "N/M tasks complete"
|
||||
- If all done: suggest archive
|
||||
- If paused: explain why and wait for guidance
|
||||
|
||||
**Output During Implementation**
|
||||
|
||||
```
|
||||
## Implementing: <change-name> (schema: <schema-name>)
|
||||
|
||||
Working on task 3/7: <task description>
|
||||
[...implementation happening...]
|
||||
✓ Task complete
|
||||
|
||||
Working on task 4/7: <task description>
|
||||
[...implementation happening...]
|
||||
✓ Task complete
|
||||
```
|
||||
|
||||
**Output On Completion**
|
||||
|
||||
```
|
||||
## Implementation Complete
|
||||
|
||||
**Change:** <change-name>
|
||||
**Schema:** <schema-name>
|
||||
**Progress:** 7/7 tasks complete ✓
|
||||
|
||||
### Completed This Session
|
||||
- [x] Task 1
|
||||
- [x] Task 2
|
||||
...
|
||||
|
||||
All tasks complete! You can archive this change with `/opsx:archive`.
|
||||
```
|
||||
|
||||
**Output On Pause (Issue Encountered)**
|
||||
|
||||
```
|
||||
## Implementation Paused
|
||||
|
||||
**Change:** <change-name>
|
||||
**Schema:** <schema-name>
|
||||
**Progress:** 4/7 tasks complete
|
||||
|
||||
### Issue Encountered
|
||||
<description of the issue>
|
||||
|
||||
**Options:**
|
||||
1. <option 1>
|
||||
2. <option 2>
|
||||
3. Other approach
|
||||
|
||||
What would you like to do?
|
||||
```
|
||||
|
||||
**Guardrails**
|
||||
- Keep going through tasks until done or blocked
|
||||
- Always read context files before starting (from the apply instructions output)
|
||||
- If task is ambiguous, pause and ask before implementing
|
||||
- If implementation reveals issues, pause and suggest artifact updates
|
||||
- Keep code changes minimal and scoped to each task
|
||||
- Update task checkbox immediately after completing each task
|
||||
- Pause on errors, blockers, or unclear requirements - don't guess
|
||||
- Use contextFiles from CLI output, don't assume specific file names
|
||||
- Do not use context or operation guidance as proof that a task is complete
|
||||
- Apply relevant project context; report conflicts with controlling workflow inputs
|
||||
- Consider every guidance entry; explain any inapplicable or conflicting advice
|
||||
- Do not copy runtime context or operation guidance into implementation files or planning artifacts
|
||||
- Preserve CLI-controlled blocked/ready/all-done behavior and completion criteria
|
||||
|
||||
**Fluid Workflow Integration**
|
||||
|
||||
This skill supports the "actions on a change" model:
|
||||
|
||||
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
|
||||
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
|
||||
@@ -0,0 +1,225 @@
|
||||
---
|
||||
name: "OPSX: Archive"
|
||||
description: "Archive a completed change in the experimental workflow"
|
||||
allowed-tools: Bash(openspec:*)
|
||||
category: "Workflow"
|
||||
tags: ["workflow", "archive", "experimental"]
|
||||
---
|
||||
|
||||
Archive a completed change in the experimental workflow.
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
|
||||
|
||||
**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Select the change**
|
||||
|
||||
If a name is provided, use it. Otherwise:
|
||||
- Infer from conversation context if the user mentioned a change
|
||||
- Auto-select if only one active change exists
|
||||
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
|
||||
|
||||
When prompting, show only active changes (not already archived).
|
||||
Include the schema used for each change if available.
|
||||
|
||||
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:archive <other>`).
|
||||
|
||||
**Load current archive inputs before the existing archive checks:**
|
||||
|
||||
After resolving the selected change and planning root, run:
|
||||
```bash
|
||||
openspec instructions archive --change "<name>" --json
|
||||
```
|
||||
Keep the same selected-root flags on this command. This lookup is advisory and
|
||||
optional: it only supplies extra prompt inputs, so it must never block archiving.
|
||||
If it exits non-zero or returns invalid JSON — for example on an older CLI that
|
||||
does not support this command yet — continue the archive workflow with no
|
||||
context and no operation guidance. Do not report an error and do not stop.
|
||||
|
||||
A successful response may omit both optional fields. Treat `context` as a
|
||||
required prompt-level input: read and consider it, and apply relevant project
|
||||
facts, conventions, and constraints. Treat `operationGuidance` as optional
|
||||
additive advice: read and consider every entry, and follow entries that are
|
||||
applicable and compatible with the built-in archive workflow.
|
||||
|
||||
Keep both fields separate from built-in steps, explicit user choices, resolved
|
||||
paths, CLI checks, and command contracts. If context conflicts with one of those
|
||||
controlling inputs, report the conflict and preserve the controlling value. If
|
||||
guidance is inapplicable or conflicts with a controlling input, do not follow it
|
||||
and explain why. Do not infer replacement paths, skipped prompts, or flags from
|
||||
either field, and do not copy their text verbatim into specs, change artifacts,
|
||||
or archive summaries unless the user separately asks for it. These are
|
||||
prompt-level behavior contracts, not enforceable checks.
|
||||
|
||||
2. **Check artifact completion status**
|
||||
|
||||
Run `openspec status --change "<name>" --json` to check artifact completion.
|
||||
|
||||
Parse the JSON to understand:
|
||||
- `schemaName`: The workflow being used
|
||||
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
|
||||
- `artifacts`: List of artifacts with their status (`done`, `skipped`, or other)
|
||||
|
||||
**If any artifacts are neither `done` nor `skipped`** (skipped artifacts satisfy the requirement - the change declares skip_specs):
|
||||
- Display warning listing incomplete artifacts
|
||||
- Prompt user for confirmation to continue
|
||||
- Proceed if user confirms
|
||||
|
||||
3. **Check task completion status**
|
||||
|
||||
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
|
||||
|
||||
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
|
||||
|
||||
**If incomplete tasks found:**
|
||||
- Display warning showing count of incomplete tasks
|
||||
- Prompt user for confirmation to continue
|
||||
- Proceed if user confirms
|
||||
|
||||
**If no tasks file exists:** Proceed without task-related warning.
|
||||
|
||||
4. **Assess delta spec sync state**
|
||||
|
||||
Use `artifactPaths.specs.existingOutputPaths` from status JSON as the only
|
||||
delta-spec source. If the `specs` entry is missing or
|
||||
`existingOutputPaths` is empty, proceed without a sync prompt and do not infer
|
||||
delta specs from other artifacts.
|
||||
|
||||
**If delta specs exist:**
|
||||
- Compare each delta spec with its corresponding main spec at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (use the store-aware `planningHome.root` from step 2, not a hardcoded repo path)
|
||||
- Determine what changes would be applied (adds, modifications, removals, renames)
|
||||
- Show a combined summary before prompting
|
||||
|
||||
**Prompt options:**
|
||||
- If changes needed: "Sync now (recommended)", "Archive without syncing"
|
||||
- If already synced: "Archive now", "Sync anyway", "Cancel"
|
||||
|
||||
Route on the answer:
|
||||
- "Cancel" — stop, do not archive
|
||||
- "Archive without syncing" or "Archive now" — proceed to archive
|
||||
- "Sync now" or "Sync anyway" — sync, then verify (below)
|
||||
- Anything else — ask again rather than archiving
|
||||
|
||||
Before a selected sync writes any main spec, run
|
||||
`openspec instructions specs --change "<name>" --json` once with the same
|
||||
selected-root flags. Require a zero exit status and valid artifact-instruction
|
||||
JSON. If the lookup fails or returns invalid JSON, report the error and stop
|
||||
before writing any main spec or moving the change. A valid response with omitted
|
||||
`rules` is the no-rules case. Apply returned `rules` only to the content and
|
||||
form of main specs produced by this merge; do not use them as archive guidance,
|
||||
change CLI behavior, or copy the rule text into any output file.
|
||||
|
||||
Then run the `/opsx:sync` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching `specs` instructions again. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
|
||||
|
||||
Then re-run the comparison from the top of this step against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
|
||||
- ADDED requirements present
|
||||
- MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
|
||||
- REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving `## Requirements` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
|
||||
- RENAMED requirements present under the new name and absent under the old one
|
||||
|
||||
If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and `changeRoot` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
|
||||
|
||||
5. **Perform the archive**
|
||||
|
||||
Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
|
||||
```bash
|
||||
mkdir -p "<planningHome.changesDir>/archive"
|
||||
```
|
||||
|
||||
Generate the target name: use the change name as-is when it already starts with a `YYYY-MM-DD-` prefix; otherwise prepend the current date as `YYYY-MM-DD-<change-name>`. Never stack a second date (same rule as `openspec archive`).
|
||||
|
||||
**Check if target already exists:**
|
||||
- If yes: Fail with error, suggest renaming existing archive or using different date
|
||||
- If no: Move `changeRoot` to the archive directory
|
||||
|
||||
```bash
|
||||
mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
|
||||
```
|
||||
|
||||
6. **Display summary**
|
||||
|
||||
Show archive completion summary including:
|
||||
- Change name
|
||||
- Schema that was used
|
||||
- Archive location
|
||||
- Spec sync status (synced / sync skipped / no delta specs)
|
||||
- Note about any warnings (incomplete artifacts/tasks)
|
||||
|
||||
**Output On Success**
|
||||
|
||||
```markdown
|
||||
## Archive Complete
|
||||
|
||||
**Change:** <change-name>
|
||||
**Schema:** <schema-name>
|
||||
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
|
||||
**Specs:** ✓ Synced to main specs
|
||||
|
||||
All artifacts complete. All tasks complete.
|
||||
```
|
||||
|
||||
**Output On Success (No Delta Specs)**
|
||||
|
||||
```markdown
|
||||
## Archive Complete
|
||||
|
||||
**Change:** <change-name>
|
||||
**Schema:** <schema-name>
|
||||
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
|
||||
**Specs:** No delta specs
|
||||
|
||||
All artifacts complete. All tasks complete.
|
||||
```
|
||||
|
||||
**Output On Success With Warnings**
|
||||
|
||||
```markdown
|
||||
## Archive Complete (with warnings)
|
||||
|
||||
**Change:** <change-name>
|
||||
**Schema:** <schema-name>
|
||||
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
|
||||
**Specs:** Sync skipped (user chose to skip)
|
||||
|
||||
**Warnings:**
|
||||
- Archived with 2 incomplete artifacts
|
||||
- Archived with 3 incomplete tasks
|
||||
- Delta spec sync was skipped (user chose to skip)
|
||||
|
||||
Review the archive if this was not intentional.
|
||||
```
|
||||
|
||||
**Output On Error (Archive Exists)**
|
||||
|
||||
```markdown
|
||||
## Archive Failed
|
||||
|
||||
**Change:** <change-name>
|
||||
**Target:** the archive path derived from `planningHome.changesDir`/<target-name>/
|
||||
|
||||
Target archive directory already exists.
|
||||
|
||||
**Options:**
|
||||
1. Rename the existing archive
|
||||
2. Delete the existing archive if it's a duplicate
|
||||
3. Wait until a different date to archive
|
||||
```
|
||||
|
||||
**Guardrails**
|
||||
- Announce the selected change; prompt for selection when it is ambiguous
|
||||
- Use artifact graph (openspec status --json) for completion checking
|
||||
- Don't block archive on warnings - just inform and confirm
|
||||
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
|
||||
- Show clear summary of what happened
|
||||
- If sync is requested, run the `/opsx:sync` workflow inline (agent-driven)
|
||||
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving `changeRoot`
|
||||
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
|
||||
- Apply relevant runtime context and report conflicts; operation guidance remains advisory
|
||||
- Consider every guidance entry and explain any inapplicable or conflicting advice
|
||||
- Existing CLI checks, resolved paths, prompts, and command contracts are unchanged
|
||||
- Artifact rules constrain only the specs being written and are never operation guidance
|
||||
- Never copy runtime context, operation guidance, or artifact-rule text verbatim into output files
|
||||
@@ -0,0 +1,193 @@
|
||||
---
|
||||
name: "OPSX: Explore"
|
||||
description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
|
||||
allowed-tools: Bash(openspec:*)
|
||||
category: "Workflow"
|
||||
tags: ["workflow", "explore", "experimental", "thinking"]
|
||||
---
|
||||
|
||||
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
|
||||
|
||||
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. For a new change, scaffold it first as described below.
|
||||
|
||||
**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
|
||||
- A vague idea: "real-time collaboration"
|
||||
- A specific problem: "the auth system is getting unwieldy"
|
||||
- A change name: "add-dark-mode" (to explore in context of that change)
|
||||
- A comparison: "postgres vs sqlite for this"
|
||||
- Nothing (just enter explore mode)
|
||||
|
||||
---
|
||||
|
||||
## The Stance
|
||||
|
||||
- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
|
||||
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
|
||||
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
|
||||
- **Adaptive** - Follow interesting threads, pivot when new information emerges
|
||||
- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
|
||||
- **Grounded** - Explore the actual codebase when relevant, don't just theorize
|
||||
|
||||
---
|
||||
|
||||
## What You Might Do
|
||||
|
||||
Depending on what the user brings, you might:
|
||||
|
||||
**Explore the problem space**
|
||||
- Ask clarifying questions that emerge from what they said
|
||||
- Challenge assumptions
|
||||
- Reframe the problem
|
||||
- Find analogies
|
||||
|
||||
**Investigate the codebase**
|
||||
- Map existing architecture relevant to the discussion
|
||||
- Find integration points
|
||||
- Identify patterns already in use
|
||||
- Surface hidden complexity
|
||||
|
||||
**Compare options**
|
||||
- Brainstorm multiple approaches
|
||||
- Build comparison tables
|
||||
- Sketch tradeoffs
|
||||
- Recommend a path (if asked)
|
||||
|
||||
**Visualize**
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Use ASCII diagrams liberally │
|
||||
├─────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────┐ ┌────────┐ │
|
||||
│ │ State │────────▶│ State │ │
|
||||
│ │ A │ │ B │ │
|
||||
│ └────────┘ └────────┘ │
|
||||
│ │
|
||||
│ System diagrams, state machines, │
|
||||
│ data flows, architecture sketches, │
|
||||
│ dependency graphs, comparison tables │
|
||||
│ │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Surface risks and unknowns**
|
||||
- Identify what could go wrong
|
||||
- Find gaps in understanding
|
||||
- Suggest spikes or investigations
|
||||
|
||||
---
|
||||
|
||||
## OpenSpec Awareness
|
||||
|
||||
You have full context of the OpenSpec system. Use it naturally, don't force it.
|
||||
|
||||
### Check for context
|
||||
|
||||
At the start, quickly check what exists:
|
||||
```bash
|
||||
openspec list --json
|
||||
```
|
||||
|
||||
This tells you:
|
||||
- If there are active changes
|
||||
- Their names, schemas, and status
|
||||
- What the user might be working on
|
||||
|
||||
Then read the project's own context from the resolved root - `<root.path>/openspec/config.yaml` (or `config.yml`). Use the `root.path` returned above, and skip this if neither file exists:
|
||||
- `context`: project background - tech stack, conventions, constraints
|
||||
- `rules`: keyed by artifact id - the entries for an artifact apply only when you write that artifact
|
||||
|
||||
Ground your thinking in these. They are constraints for you to follow, not content to reproduce: do NOT copy them into the conversation or into any artifact you create.
|
||||
|
||||
If the user mentioned a specific change name, read its artifacts for context.
|
||||
|
||||
### When no change exists
|
||||
|
||||
Think freely. When insights crystallize, you might offer:
|
||||
|
||||
- "This feels solid enough to start a change. Want me to create a proposal?"
|
||||
- Or keep exploring - no pressure to formalize
|
||||
|
||||
If the user asks you to capture the exploration as a new change, transition seamlessly into the requested capture:
|
||||
|
||||
1. Run `openspec new change "<name>"` (with `--store <id>` when applicable) before creating any artifacts. Never create a new change directory under `openspec/changes/` by hand; the CLI scaffold creates required metadata such as `.openspec.yaml`. Keep the selected `--store <id>` on every applicable follow-up `status` and `instructions` command.
|
||||
2. Run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is `ready`, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own `instruction` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run `openspec instructions "<prerequisite-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) for that prerequisite whether it is `ready` or `blocked`. If its own `instruction` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
|
||||
3. Follow the returned `template` and `instruction` fields. Read completed dependency files listed in `dependencies`, and apply `context` and `rules` as constraints without copying them into the artifact. If the instruction delegates creation to a specific skill or command, invoke it; otherwise write the artifact to `resolvedOutputPath`, using the instruction to choose a concrete path when it is a glob. Verify that the selected concrete output exists.
|
||||
4. After creating each artifact, re-run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) and continue until every requested artifact is `done`, `skipped`, or was deliberately skipped because its own `instruction` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still `blocked` only because you deliberately skipped a conditional prerequisite, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
|
||||
|
||||
Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status.
|
||||
|
||||
### When a change exists
|
||||
|
||||
If the user mentions a change or you detect one is relevant:
|
||||
|
||||
1. **Resolve and read existing artifacts for context**
|
||||
- Run `openspec status --change "<name>" --json`.
|
||||
- Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
|
||||
- Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
|
||||
|
||||
2. **Reference them naturally in conversation**
|
||||
- "Your design mentions using Redis, but we just realized SQLite fits better..."
|
||||
- "The proposal scopes this to premium users, but we're now thinking everyone..."
|
||||
|
||||
3. **Offer to capture when decisions are made**
|
||||
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
|
||||
|
||||
| Insight Type | Where to Capture |
|
||||
|----------------------------|-------------------------------------|
|
||||
| New requirement discovered | `specs/<capability-path>/spec.md` |
|
||||
| Requirement changed | `specs/<capability-path>/spec.md` |
|
||||
| Design decision made | `design.md` |
|
||||
| Scope changed | `proposal.md` |
|
||||
| New work identified | `tasks.md` |
|
||||
| Assumption invalidated | Relevant artifact |
|
||||
|
||||
Example offers:
|
||||
- "That's a design decision. Capture it in design.md?"
|
||||
- "This is a new requirement. Add it to specs?"
|
||||
- "This changes scope. Update the proposal?"
|
||||
|
||||
4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
|
||||
|
||||
---
|
||||
|
||||
## What You Don't Have To Do
|
||||
|
||||
- Follow a script
|
||||
- Ask the same questions every time
|
||||
- Produce a specific artifact
|
||||
- Reach a conclusion
|
||||
- Stay on topic if a tangent is valuable
|
||||
- Be brief (this is thinking time)
|
||||
|
||||
---
|
||||
|
||||
## Ending Discovery
|
||||
|
||||
There's no required ending. Discovery might:
|
||||
|
||||
- **Flow into a proposal**: "Ready to start? I can create a change proposal."
|
||||
- **Result in artifact updates**: "Updated design.md with these decisions"
|
||||
- **Just provide clarity**: User has what they need, moves on
|
||||
- **Continue later**: "We can pick this up anytime"
|
||||
|
||||
When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
|
||||
|
||||
---
|
||||
|
||||
## Guardrails
|
||||
|
||||
- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
|
||||
- **Don't fake understanding** - If something is unclear, dig deeper
|
||||
- **Don't rush** - Discovery is thinking time, not task time
|
||||
- **Don't force structure** - Let patterns emerge naturally
|
||||
- **Don't auto-capture** - Offer to save insights, don't just do it
|
||||
- **Don't manually scaffold changes** - Never create a new change directory under `openspec/changes/` by hand. Always use `openspec new change "<name>"` (with `--store <id>` when applicable) so required metadata such as `.openspec.yaml` is created before writing artifacts.
|
||||
- **Do visualize** - A good diagram is worth many paragraphs
|
||||
- **Do explore the codebase** - Ground discussions in reality
|
||||
- **Do question assumptions** - Including the user's and your own
|
||||
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: "OPSX: Propose"
|
||||
description: "Propose a new change - create it and generate all artifacts in one step"
|
||||
allowed-tools: Bash(openspec:*)
|
||||
category: "Workflow"
|
||||
tags: ["workflow", "artifacts", "experimental"]
|
||||
---
|
||||
|
||||
Propose a new change - create the change and generate all artifacts in one step.
|
||||
|
||||
**Planning boundary**: This workflow creates planning artifacts only. The user request that selected or triggered this workflow authorizes planning only, even if it asks to build or fix something. Do not edit project code. After the planning artifacts are complete, stop. Do not start implementation in the same response, even if the initial request asks for it. Wait for a new user request after the artifacts are presented; then start the apply workflow.
|
||||
|
||||
I'll create a change with the artifacts your schema defines. With the default spec-driven schema that is:
|
||||
- proposal.md (what & why)
|
||||
- `specs/<capability-path>/spec.md` (what the system must do - a delta, not the main spec)
|
||||
- design.md (how)
|
||||
- tasks.md (implementation steps)
|
||||
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
|
||||
|
||||
When the user is ready to implement, they must start the apply workflow explicitly.
|
||||
|
||||
---
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Understand the request and clarify material ambiguity**
|
||||
|
||||
If no input is provided, ask the user (open-ended, no preset options):
|
||||
> "What change do you want to work on? Describe what you want to build or fix."
|
||||
|
||||
From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
|
||||
|
||||
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
|
||||
|
||||
If the request contains ambiguity that would materially affect scope, externally observable behavior, compatibility, or acceptance criteria, ask the user before creating the change. For minor details, make a reasonable assumption and record it in the planning artifacts.
|
||||
|
||||
2. **Determine the workflow schema**
|
||||
|
||||
Use the configured default schema unless the user explicitly requests a different workflow.
|
||||
|
||||
**Use a different schema only if the user:**
|
||||
- Explicitly requests a specific schema by name → use `--schema <schema-name>`
|
||||
- Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running `openspec context --json` from the current working directory. If the user explicitly selected a registered store, use `openspec context --json --store "<store-id>"`. Then run `openspec schemas --json` with its working directory set to the returned `root.path` and let them choose. This preserves roots selected by a local `store:` pointer or the global `defaultStore`; `schemas` does not accept `--store`. If context reports only `no_openspec_root`, run `openspec schemas --json` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
|
||||
|
||||
Otherwise, omit `--schema` to preserve the configured default.
|
||||
|
||||
3. **Create the change directory**
|
||||
|
||||
Choose one schema form below. If a registered store is selected, append `--store "<store-id>"` to that command and each later OpenSpec command shown below that accepts `--store`.
|
||||
|
||||
Using the configured default:
|
||||
```bash
|
||||
openspec new change "<name>"
|
||||
```
|
||||
|
||||
Using an explicitly requested schema:
|
||||
```bash
|
||||
openspec new change "<name>" --schema "<schema-name>"
|
||||
```
|
||||
This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
|
||||
|
||||
4. **Get the artifact build order**
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
Parse the JSON to get:
|
||||
- `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
|
||||
- `artifacts`: list of all artifacts, each with its `status` and its `requires` edges (the artifact IDs it directly depends on)
|
||||
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
|
||||
|
||||
5. **Create every artifact in the required set**
|
||||
|
||||
Use a todo list to track progress through the artifacts.
|
||||
|
||||
Loop through artifacts in dependency order (artifacts with no pending dependencies first):
|
||||
|
||||
a. **For each artifact that is `ready` (dependencies satisfied)**:
|
||||
- Get instructions:
|
||||
```bash
|
||||
openspec instructions <artifact-id> --change "<name>" --json
|
||||
```
|
||||
- The instructions JSON includes:
|
||||
- `context`: Project background (constraints for you - do NOT include in output)
|
||||
- `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
|
||||
- `template`: The structure to use for your output file
|
||||
- `instruction`: Schema-specific guidance for this artifact type
|
||||
- `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact
|
||||
- `resolvedOutputPath`: Resolved path or pattern to write the artifact
|
||||
- `dependencies`: Completed artifacts to read for context
|
||||
- Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
|
||||
- If the `instruction` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at `resolvedOutputPath`
|
||||
- Otherwise create the artifact file using `template` as the structure and write it to `resolvedOutputPath`. If `resolvedOutputPath` is a glob, follow `instruction` to choose the concrete file path
|
||||
- Apply `context` and `rules` as constraints - but do NOT copy them into the file
|
||||
- Show brief progress: "Created <artifact-id>"
|
||||
|
||||
b. **Continue until every artifact in the required set exists (not just `apply.requires`)**
|
||||
- After creating each artifact, re-run `openspec status --change "<name>" --json`
|
||||
- The required set is `applyRequires` plus every artifact reachable from those by following the `requires` edges in `status --json` - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone
|
||||
- `status` is file-existence only, so an `applyRequires` artifact reading `done` does NOT mean its dependencies exist - writing `tasks.md` early marks `tasks` done while `specs` was never written. Use each artifact's `requires` edges, not its `status`, to build the required set: a `done` artifact still lists what it depends on
|
||||
- An artifact already reading `status: "skipped"` is satisfied: the change declares `skip_specs` in `.openspec.yaml`, so its files must NOT exist. Never try to create one
|
||||
- Create every artifact in the required set that is missing, then re-check - creating one can unblock others
|
||||
- Skip one only when `status` already reports it `skipped`, or when its own `instruction` says it is conditional: run `openspec instructions <artifact-id> --change "<name>" --json` and skip only if its `instruction` field marks it optional (e.g. "create only if..."). Spec-driven's `design.md` qualifies; `specs` qualifies only via the `skipped` status above, never by your own judgment. Tell the user, and do not reconsider it
|
||||
- Dependencies are enablers, not gates: if a required artifact is still `blocked` only because you skipped a conditional dependency, write it anyway
|
||||
- Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped
|
||||
|
||||
c. **If an artifact requires user input** (unclear context):
|
||||
- Ask the user to clarify
|
||||
- Then continue with creation
|
||||
|
||||
6. **Show final status**
|
||||
```bash
|
||||
openspec status --change "<name>"
|
||||
```
|
||||
|
||||
**Output**
|
||||
|
||||
After completing all artifacts, summarize:
|
||||
- Change name and location
|
||||
- List of artifacts created with brief descriptions, plus any conditional artifact you skipped and why
|
||||
- What's ready: "All artifacts needed for implementation are ready."
|
||||
- Prompt: "The artifacts are ready for review. When you are ready, run `/opsx:apply`."
|
||||
|
||||
**Artifact Creation Guidelines**
|
||||
|
||||
- Follow the `instruction` field from `openspec instructions` for each artifact type - it is the authoritative guidance, even for familiar artifact names
|
||||
- If the `instruction` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
|
||||
- The schema defines what each artifact should contain - follow it
|
||||
- Read dependency artifacts for context before creating new ones
|
||||
- Use `template` as the structure for your output file - fill in its sections
|
||||
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
|
||||
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
|
||||
- These guide what you write, but should never appear in the output
|
||||
|
||||
**Guardrails**
|
||||
- The request that invoked this workflow authorizes planning only. Any implementation or apply instruction in that request does not carry forward. Do NOT implement the change, start the apply workflow, or edit project code during this workflow. After presenting the artifacts, stop and wait for a new user request to start the apply workflow
|
||||
- Create every artifact the apply phase transitively depends on, not just the ids listed in `apply.requires`
|
||||
- Always read dependency artifacts before creating a new one - re-read from disk, not from conversation memory (files may have changed since you last saw them)
|
||||
- Ask about ambiguities that would materially change scope, externally observable behavior, compatibility, or acceptance criteria; for minor details, make reasonable assumptions and record them
|
||||
- If a change with that name already exists, ask if user wants to continue it or create a new one
|
||||
- Verify each artifact file exists after writing before proceeding to next
|
||||
@@ -0,0 +1,258 @@
|
||||
---
|
||||
name: "OPSX: Sync"
|
||||
description: "Sync delta specs from a change to main specs"
|
||||
allowed-tools: Bash(openspec:*)
|
||||
category: "Workflow"
|
||||
tags: ["workflow", "specs", "experimental"]
|
||||
---
|
||||
|
||||
Sync delta specs from a change to main specs.
|
||||
|
||||
This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
|
||||
|
||||
**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Select the change**
|
||||
|
||||
If a name is provided, use it. Otherwise:
|
||||
- Infer from conversation context if the user mentioned a change
|
||||
- Auto-select if only one active change exists
|
||||
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
|
||||
|
||||
When prompting, show changes that have delta specs (under `specs/` directory).
|
||||
|
||||
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:sync <other>`).
|
||||
|
||||
2. **Resolve change context**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
|
||||
The JSON includes `planningHome.root`. Main specs live under `<planningHome.root>/openspec/specs/` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
|
||||
|
||||
3. **Find delta specs**
|
||||
|
||||
Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the
|
||||
only source of delta spec paths. If the `specs` entry is missing or
|
||||
`existingOutputPaths` is empty, report that there are no delta specs to sync,
|
||||
do not infer them from other artifacts, and stop without requesting artifact
|
||||
instructions or writing a main spec.
|
||||
|
||||
Sync every path in `existingOutputPaths` unless the caller narrowed the set.
|
||||
A caller narrows it by naming an explicit list of complete entries from
|
||||
`existingOutputPaths` — copy those absolute values verbatim. Archive does
|
||||
this inline, and a user can too (for example, by selecting the entry ending
|
||||
in `/specs/billing/invoices/spec.md`).
|
||||
Then sync only the named paths and leave the remaining delta specs untouched:
|
||||
bulk archive excludes a delta whose implementation it could not find, and
|
||||
syncing it anyway would write a main spec the caller deliberately withheld.
|
||||
Carry that narrowed selection through step 4; never widen it back to the full
|
||||
list. If a named path is not in `existingOutputPaths`, do not sync it —
|
||||
report it and stop, rather than dropping it silently. If the named list is
|
||||
empty, report that there is nothing to sync and stop without writing a main
|
||||
spec.
|
||||
|
||||
Each delta spec file contains sections like:
|
||||
- `## ADDED Requirements` - New requirements to add
|
||||
- `## MODIFIED Requirements` - Changes to existing requirements
|
||||
- `## REMOVED Requirements` - Requirements to remove
|
||||
- `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
|
||||
|
||||
If no delta specs found, inform user and stop.
|
||||
|
||||
4. **For each delta spec, apply changes to main specs**
|
||||
|
||||
Before the first main-spec write, obtain one current specs-rule snapshot:
|
||||
- If archive invoked this workflow inline and supplied a valid snapshot from
|
||||
`openspec instructions specs --change "<name>" --json`, reuse it and do not
|
||||
fetch the same instructions again.
|
||||
- Otherwise run that command once now with the same selected-root flags.
|
||||
- If the direct lookup exits non-zero or returns invalid artifact-instruction
|
||||
JSON, report the error and stop before writing any main spec. Do not treat the
|
||||
failure as an absent rule set.
|
||||
- A valid response with omitted `rules` means no artifact rules are configured
|
||||
and the existing semantic merge continues.
|
||||
|
||||
Apply returned `rules` only to the content and form of the main specs produced
|
||||
by this merge. Artifact rules are not operation guidance and cannot change
|
||||
selected roots, delta paths, CLI checks, or workflow steps. Use their text as
|
||||
constraints without copying it verbatim into a main spec or summary.
|
||||
|
||||
For each capability delta spec path selected in step 3 — the full `existingOutputPaths` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
|
||||
|
||||
a. **Read the delta spec** to understand the intended changes
|
||||
|
||||
b. **Read the main spec** at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (may not exist yet)
|
||||
|
||||
c. **Apply changes intelligently**:
|
||||
|
||||
**ADDED Requirements:**
|
||||
- If requirement doesn't exist in main spec → add it
|
||||
- If requirement already exists → update it to match (treat as implicit MODIFIED)
|
||||
|
||||
**MODIFIED Requirements:**
|
||||
- Find the requirement in main spec
|
||||
- Apply the changes - this can be:
|
||||
- Adding new scenarios the main spec does not have yet
|
||||
- Modifying existing scenarios
|
||||
- Changing the requirement description
|
||||
- Preserve scenarios/content not mentioned in the delta
|
||||
|
||||
**REMOVED Requirements:**
|
||||
- Remove the entire requirement block from main spec
|
||||
- Retiring the capability. Delete the whole `spec.md` - and the directory once
|
||||
nothing else is left in it - only when ALL of these hold:
|
||||
1. removing the requirements *this run* left no requirement blocks;
|
||||
2. the rest of the spec is well-formed (it still has a `## Purpose`);
|
||||
3. the main spec was not already empty before this sync - if you removed
|
||||
nothing, change nothing;
|
||||
4. every other nonblank line in the whole file is accounted for as the
|
||||
title, Purpose, Requirements header, or a canonical requirement's
|
||||
statement, scenarios, or fenced examples;
|
||||
5. the change's `.openspec.yaml` declares `retire_capabilities: true`;
|
||||
6. the `spec.md` resolves inside the real specs root (do not follow a
|
||||
capability-directory symlink to delete an external file).
|
||||
If removing the selected requirements would leave no requirement blocks and
|
||||
any retirement condition is not satisfied, do not modify the main spec. Stop
|
||||
the sync for that capability, report the blocking condition, and tell the user
|
||||
how to resolve it. Never write or leave an empty `## Requirements` section.
|
||||
When only the marker is missing, say that too - it is the one thing the user
|
||||
can add to make the retirement go through.
|
||||
- Deleting the file also deletes its `## Purpose`; any other section blocks
|
||||
retirement. Name Purpose when you report the retirement. Include a pasteable
|
||||
`git checkout` only when the spec lived in the caller's checkout;
|
||||
otherwise give checkout-scoped recovery guidance.
|
||||
|
||||
**RENAMED Requirements:**
|
||||
- Find the FROM requirement, rename to TO
|
||||
|
||||
**`## Purpose` in the delta:**
|
||||
- The main spec already has one and it is authoritative - leave it alone
|
||||
(this is what `openspec archive` does; it warns and moves on)
|
||||
|
||||
d. **Create new main spec** if capability doesn't exist yet:
|
||||
- Create `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
|
||||
- Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one
|
||||
(this is what `openspec archive` does); only write a brief TBD placeholder when it does not
|
||||
- Add Requirements section with the ADDED requirements
|
||||
- Follow the **Main Spec Format Reference** below
|
||||
|
||||
5. **Validate updated main specs**
|
||||
|
||||
Run `openspec validate --specs` with the same selected-root flags used earlier.
|
||||
If validation fails, report the problems and do not claim the sync succeeded.
|
||||
|
||||
6. **Show summary**
|
||||
|
||||
After applying all changes, summarize:
|
||||
- Which capabilities were updated
|
||||
- What changes were made (requirements added/modified/removed/renamed)
|
||||
- Any new main spec left with a TBD Purpose placeholder, so it gets written
|
||||
now rather than lingering
|
||||
- Any capability retired, naming the deleted `spec.md`, its Purpose, and
|
||||
either a pasteable `git checkout` or checkout-scoped recovery guidance
|
||||
|
||||
**Delta Spec Format Reference**
|
||||
|
||||
```markdown
|
||||
## Purpose
|
||||
|
||||
Only on a delta that introduces a brand-new capability. Seeds the new main spec.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: New Feature
|
||||
The system SHALL do something new.
|
||||
|
||||
#### Scenario: Basic case
|
||||
- **WHEN** user does X
|
||||
- **THEN** system does Y
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Existing Feature
|
||||
The system SHALL keep doing the existing thing, now also handling A.
|
||||
|
||||
#### Scenario: Scenario the main spec already has
|
||||
- **WHEN** user does X
|
||||
- **THEN** system does Y
|
||||
|
||||
#### Scenario: New scenario to add
|
||||
- **WHEN** user does A
|
||||
- **THEN** system does B
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Deprecated Feature
|
||||
|
||||
## RENAMED Requirements
|
||||
|
||||
- FROM: `### Requirement: Old Name`
|
||||
- TO: `### Requirement: New Name`
|
||||
```
|
||||
|
||||
**Main Spec Format Reference**
|
||||
|
||||
Main specs are what the delta merges INTO. They must never contain delta operation headers (`## ADDED/MODIFIED/REMOVED/RENAMED Requirements`) - after syncing, every requirement lives under a single `## Requirements` section:
|
||||
|
||||
```markdown
|
||||
# <capability> Specification
|
||||
|
||||
## Purpose
|
||||
Short description of what this capability does and why it exists.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: New Feature
|
||||
The system SHALL do something new.
|
||||
|
||||
#### Scenario: Basic case
|
||||
- **WHEN** user does X
|
||||
- **THEN** system does Y
|
||||
```
|
||||
|
||||
**Key Principle: Intelligent Merging**
|
||||
|
||||
Unlike programmatic merging, you merge rather than overwrite:
|
||||
- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. `openspec validate` and `openspec archive` both reject one that drops a scenario the main spec still has.
|
||||
- Keep anything the delta does not mention, in the main spec's existing order
|
||||
- Use your judgment to merge changes sensibly
|
||||
|
||||
**Output On Success**
|
||||
|
||||
```markdown
|
||||
## Specs Synced: <change-name>
|
||||
|
||||
Updated main specs:
|
||||
|
||||
**<capability-1>**:
|
||||
- Added requirement: "New Feature"
|
||||
- Modified requirement: "Existing Feature" (added 1 scenario)
|
||||
|
||||
**<capability-2>**:
|
||||
- Created new spec file
|
||||
- Added requirement: "Another Feature"
|
||||
|
||||
Main specs are now updated. The change remains active - archive when implementation is complete.
|
||||
```
|
||||
|
||||
**Guardrails**
|
||||
- Read both delta and main specs before making changes
|
||||
- Preserve existing content not mentioned in delta
|
||||
- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
|
||||
- If something is unclear, ask for clarification
|
||||
- Show what you're changing as you go
|
||||
- The operation should be idempotent - running twice should give same result
|
||||
- Use only `artifactPaths.specs.existingOutputPaths`; never infer delta specs from unrelated artifacts
|
||||
- Honor a caller-supplied subset of `existingOutputPaths`; never widen it back to the full list
|
||||
- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
|
||||
- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
|
||||
- Artifact rules constrain only the specs being written and are never copied into output files
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
name: "OPSX: Update"
|
||||
description: "Update a change - revise existing planning artifacts and keep them coherent (Experimental)"
|
||||
allowed-tools: Bash(openspec:*)
|
||||
category: "Workflow"
|
||||
tags: ["workflow", "artifacts", "experimental"]
|
||||
---
|
||||
|
||||
Revise a change's existing planning artifacts and keep them coherent. Never edit code.
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
**Input**: Optionally specify a change name after `/opsx:update` (e.g., `/opsx:update add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||
|
||||
`/opsx:continue` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, `openspec status --change "<name>" --json` shows the next artifact and `openspec instructions "<artifact-id>" --change "<name>" --json` explains how to create it.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Select the change**
|
||||
|
||||
If a name is provided, use it. Otherwise:
|
||||
- Infer from conversation context if the user mentioned a change
|
||||
- Auto-select if only one active change exists
|
||||
- If ambiguous, run `openspec list --json` to get available changes sorted by most recently modified, and ask the user to select one
|
||||
|
||||
When prompting, present the top 3-4 most recently modified changes as options, showing:
|
||||
- Change name
|
||||
- Schema (from `schema` field if present, otherwise "spec-driven")
|
||||
- Status (e.g., "0/5 tasks", "complete", "no tasks")
|
||||
- How recently it was modified (from `lastModified` field)
|
||||
|
||||
Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
|
||||
|
||||
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:update <other>`).
|
||||
|
||||
2. **Get the change's artifacts**
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
Parse the JSON to understand current state. The response includes:
|
||||
- `schemaName`: The workflow schema being used (e.g., "spec-driven")
|
||||
- `artifacts`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
|
||||
- `isPlanningComplete`: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as `isComplete`.
|
||||
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
|
||||
|
||||
The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
|
||||
|
||||
The files to edit are `artifactPaths.<id>.existingOutputPaths` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. `specs/**/*.md`). Do NOT write to `resolvedOutputPath`: for a glob artifact it is still the glob pattern, not a real file.
|
||||
|
||||
3. **Understand the request**
|
||||
- If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
|
||||
- If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
|
||||
|
||||
4. **Read and reconcile**
|
||||
- Read the artifact(s) the request touches and the change's other existing artifacts.
|
||||
- Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
|
||||
- Note everything that is now inconsistent, missing, or contradictory.
|
||||
- Revise only files that already exist (`existingOutputPaths`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to `/opsx:continue` to create them.
|
||||
- If the change is already coherent, say so and make no edits.
|
||||
|
||||
5. **Confirm and apply, one artifact at a time**
|
||||
- Show each proposed revision and why. Write only after the user confirms.
|
||||
- If the user rejects a revision, do not write it - leave that artifact unchanged.
|
||||
- When a substantial rewrite is needed, get that artifact's rules and template first:
|
||||
```bash
|
||||
openspec instructions "<artifact-id>" --change "<name>" --json
|
||||
```
|
||||
|
||||
6. **Point to the next step (guidance only - NEVER act on it)**
|
||||
- Artifacts still missing -> suggest `/opsx:continue` to create them.
|
||||
- Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest `/opsx:apply` to carry the delta into code.
|
||||
- Everything done and implemented -> suggest `/opsx:archive`.
|
||||
|
||||
**Output**
|
||||
|
||||
After each invocation, show:
|
||||
- Which artifacts were revised (and which proposed revisions were rejected)
|
||||
- Anything deferred to `/opsx:continue` (not-yet-created artifacts or files)
|
||||
- Where the change stands and the recommended next command
|
||||
|
||||
**Guardrails**
|
||||
- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `/opsx:apply`.
|
||||
- Use the artifact ids and paths reported by `openspec status`; never branch on hardcoded artifact names.
|
||||
- Edit only the concrete files in `existingOutputPaths`; never write to a glob `resolvedOutputPath`.
|
||||
- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is `/opsx:continue`'s job.
|
||||
- Confirm every edit with the user before writing.
|
||||
- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile `/opsx:new` workflow is available. If it is, recommend starting fresh with `/opsx:new` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend `openspec new change "<new-change-name>"` instead.
|
||||
Executable
+45
@@ -0,0 +1,45 @@
|
||||
#!/usr/bin/env bash
|
||||
set -uo pipefail
|
||||
|
||||
ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
|
||||
PAYLOAD=$(cat)
|
||||
FILE=$(printf '%s' "$PAYLOAD" | /usr/bin/python3 -c 'import json,sys
|
||||
try:
|
||||
d = json.load(sys.stdin)
|
||||
except Exception:
|
||||
sys.exit(0)
|
||||
t = d.get("tool_input") or {}
|
||||
r = d.get("tool_response") or {}
|
||||
p = r.get("filePath") or t.get("file_path") or ""
|
||||
print(p)
|
||||
' 2>/dev/null)
|
||||
|
||||
case "$FILE" in
|
||||
"") exit 0 ;;
|
||||
*.py) ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
|
||||
case "$FILE" in
|
||||
"$ROOT"/src/*) ;;
|
||||
src/*) FILE="$ROOT/$FILE" ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
|
||||
[ -f "$FILE" ] || exit 0
|
||||
[ -x "$ROOT/.venv/bin/ruff" ] || exit 0
|
||||
|
||||
OUT=$(
|
||||
cd "$ROOT" || exit 0
|
||||
"$ROOT/.venv/bin/ruff" check --fix --quiet "$FILE" 2>&1
|
||||
"$ROOT/.venv/bin/ruff" format --quiet "$FILE" 2>&1
|
||||
if [ -x "$ROOT/.venv/bin/ty" ]; then
|
||||
"$ROOT/.venv/bin/ty" check --quiet "$FILE" 2>&1 | grep -v "^All checks passed" || true
|
||||
fi
|
||||
)
|
||||
|
||||
if [ -n "$OUT" ]; then
|
||||
printf 'ruff/ty по %s:\n%s\n' "${FILE#"$ROOT"/}" "$OUT" >&2
|
||||
exit 2
|
||||
fi
|
||||
exit 0
|
||||
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit|MultiEdit|NotebookEdit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lint-python.sh",
|
||||
"timeout": 60,
|
||||
"statusMessage": "ruff + ty по src/"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: openspec-apply-change
|
||||
description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
|
||||
allowed-tools: Bash(openspec:*)
|
||||
license: MIT
|
||||
compatibility: Requires openspec CLI.
|
||||
metadata:
|
||||
author: openspec
|
||||
version: "1.0"
|
||||
generatedBy: "1.8.0"
|
||||
---
|
||||
|
||||
Implement tasks from an OpenSpec change.
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Select the change**
|
||||
|
||||
If a name is provided, use it. Otherwise:
|
||||
- Infer from conversation context if the user mentioned a change
|
||||
- Auto-select if only one active change exists
|
||||
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
|
||||
|
||||
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
|
||||
|
||||
2. **Check status to understand the schema**
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
Parse the JSON to understand:
|
||||
- `schemaName`: The workflow being used (e.g., "spec-driven")
|
||||
- `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
|
||||
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
|
||||
|
||||
3. **Get apply instructions**
|
||||
|
||||
```bash
|
||||
openspec instructions apply --change "<name>" --json
|
||||
```
|
||||
|
||||
This returns:
|
||||
- `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
|
||||
- Progress (total, complete, remaining)
|
||||
- Task list with status
|
||||
- Dynamic instruction based on current state
|
||||
- Optional `context`: current required project instruction input from the selected root
|
||||
- Optional `operationGuidance`: current advisory guidance for apply
|
||||
|
||||
**Handle states:**
|
||||
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue` (if it is not installed, run `openspec status --change "<name>" --json` to see the next artifact and `openspec instructions <artifact-id> --change "<name>" --json` for how to create it)
|
||||
- If `state: "all_done"`: congratulate, suggest archive
|
||||
- Otherwise: proceed to implementation
|
||||
|
||||
Treat `context` as a required prompt-level input. Read and consider it, and
|
||||
apply relevant project facts, conventions, and constraints while implementing.
|
||||
Treat `operationGuidance` as optional additive advice. Read and consider every
|
||||
entry, and follow entries that are applicable and compatible with the built-in
|
||||
workflow.
|
||||
|
||||
Keep both fields separate from CLI-returned state, missing artifacts, tasks,
|
||||
progress, `contextFiles`, and the built-in `instruction`. They are not
|
||||
evidence of task completion, do not replace the built-in instruction, and do
|
||||
not permit bypassing a blocked state. If context conflicts with the built-in
|
||||
instruction, an explicit user choice, or a CLI-controlled value, report the
|
||||
conflict and preserve the controlling value. If guidance is inapplicable or
|
||||
conflicts with those controlling inputs, do not follow it and explain why.
|
||||
These are prompt-level behavior contracts, not enforceable checks.
|
||||
|
||||
4. **Read context files**
|
||||
|
||||
Read every file path listed under `contextFiles` from the apply instructions output.
|
||||
The files depend on the schema being used:
|
||||
- **spec-driven**: proposal, specs, design, tasks
|
||||
- Other schemas: follow the contextFiles from CLI output
|
||||
|
||||
Do not copy `context` or `operationGuidance` verbatim into implementation
|
||||
files or planning artifacts unless the user separately asks for that content.
|
||||
|
||||
5. **Show current progress**
|
||||
|
||||
Display:
|
||||
- Schema being used
|
||||
- Progress: "N/M tasks complete"
|
||||
- Remaining tasks overview
|
||||
- Dynamic instruction from CLI
|
||||
|
||||
6. **Implement tasks (loop until done or blocked)**
|
||||
|
||||
For each pending task:
|
||||
- Show which task is being worked on
|
||||
- Make the code changes required
|
||||
- Keep changes minimal and focused
|
||||
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
|
||||
- Continue to next task
|
||||
|
||||
**Pause if:**
|
||||
- Task is unclear → ask for clarification
|
||||
- Implementation reveals a design issue → suggest updating artifacts
|
||||
- Error or blocker encountered → report and wait for guidance
|
||||
- User interrupts
|
||||
|
||||
7. **On completion or pause, show status**
|
||||
|
||||
Display:
|
||||
- Tasks completed this session
|
||||
- Overall progress: "N/M tasks complete"
|
||||
- If all done: suggest archive
|
||||
- If paused: explain why and wait for guidance
|
||||
|
||||
**Output During Implementation**
|
||||
|
||||
```
|
||||
## Implementing: <change-name> (schema: <schema-name>)
|
||||
|
||||
Working on task 3/7: <task description>
|
||||
[...implementation happening...]
|
||||
✓ Task complete
|
||||
|
||||
Working on task 4/7: <task description>
|
||||
[...implementation happening...]
|
||||
✓ Task complete
|
||||
```
|
||||
|
||||
**Output On Completion**
|
||||
|
||||
```
|
||||
## Implementation Complete
|
||||
|
||||
**Change:** <change-name>
|
||||
**Schema:** <schema-name>
|
||||
**Progress:** 7/7 tasks complete ✓
|
||||
|
||||
### Completed This Session
|
||||
- [x] Task 1
|
||||
- [x] Task 2
|
||||
...
|
||||
|
||||
All tasks complete! You can archive this change with `/opsx:archive`.
|
||||
```
|
||||
|
||||
**Output On Pause (Issue Encountered)**
|
||||
|
||||
```
|
||||
## Implementation Paused
|
||||
|
||||
**Change:** <change-name>
|
||||
**Schema:** <schema-name>
|
||||
**Progress:** 4/7 tasks complete
|
||||
|
||||
### Issue Encountered
|
||||
<description of the issue>
|
||||
|
||||
**Options:**
|
||||
1. <option 1>
|
||||
2. <option 2>
|
||||
3. Other approach
|
||||
|
||||
What would you like to do?
|
||||
```
|
||||
|
||||
**Guardrails**
|
||||
- Keep going through tasks until done or blocked
|
||||
- Always read context files before starting (from the apply instructions output)
|
||||
- If task is ambiguous, pause and ask before implementing
|
||||
- If implementation reveals issues, pause and suggest artifact updates
|
||||
- Keep code changes minimal and scoped to each task
|
||||
- Update task checkbox immediately after completing each task
|
||||
- Pause on errors, blockers, or unclear requirements - don't guess
|
||||
- Use contextFiles from CLI output, don't assume specific file names
|
||||
- Do not use context or operation guidance as proof that a task is complete
|
||||
- Apply relevant project context; report conflicts with controlling workflow inputs
|
||||
- Consider every guidance entry; explain any inapplicable or conflicting advice
|
||||
- Do not copy runtime context or operation guidance into implementation files or planning artifacts
|
||||
- Preserve CLI-controlled blocked/ready/all-done behavior and completion criteria
|
||||
|
||||
**Fluid Workflow Integration**
|
||||
|
||||
This skill supports the "actions on a change" model:
|
||||
|
||||
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
|
||||
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
|
||||
@@ -0,0 +1,182 @@
|
||||
---
|
||||
name: openspec-archive-change
|
||||
description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
|
||||
allowed-tools: Bash(openspec:*)
|
||||
license: MIT
|
||||
compatibility: Requires openspec CLI.
|
||||
metadata:
|
||||
author: openspec
|
||||
version: "1.0"
|
||||
generatedBy: "1.8.0"
|
||||
---
|
||||
|
||||
Archive a completed change in the experimental workflow.
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
|
||||
|
||||
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Select the change**
|
||||
|
||||
If a name is provided, use it. Otherwise:
|
||||
- Infer from conversation context if the user mentioned a change
|
||||
- Auto-select if only one active change exists
|
||||
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
|
||||
|
||||
When prompting, show only active changes (not already archived).
|
||||
Include the schema used for each change if available.
|
||||
|
||||
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:archive <other>`).
|
||||
|
||||
**Load current archive inputs before the existing archive checks:**
|
||||
|
||||
After resolving the selected change and planning root, run:
|
||||
```bash
|
||||
openspec instructions archive --change "<name>" --json
|
||||
```
|
||||
Keep the same selected-root flags on this command. This lookup is advisory and
|
||||
optional: it only supplies extra prompt inputs, so it must never block archiving.
|
||||
If it exits non-zero or returns invalid JSON — for example on an older CLI that
|
||||
does not support this command yet — continue the archive workflow with no
|
||||
context and no operation guidance. Do not report an error and do not stop.
|
||||
|
||||
A successful response may omit both optional fields. Treat `context` as a
|
||||
required prompt-level input: read and consider it, and apply relevant project
|
||||
facts, conventions, and constraints. Treat `operationGuidance` as optional
|
||||
additive advice: read and consider every entry, and follow entries that are
|
||||
applicable and compatible with the built-in archive workflow.
|
||||
|
||||
Keep both fields separate from built-in steps, explicit user choices, resolved
|
||||
paths, CLI checks, and command contracts. If context conflicts with one of those
|
||||
controlling inputs, report the conflict and preserve the controlling value. If
|
||||
guidance is inapplicable or conflicts with a controlling input, do not follow it
|
||||
and explain why. Do not infer replacement paths, skipped prompts, or flags from
|
||||
either field, and do not copy their text verbatim into specs, change artifacts,
|
||||
or archive summaries unless the user separately asks for it. These are
|
||||
prompt-level behavior contracts, not enforceable checks.
|
||||
|
||||
2. **Check artifact completion status**
|
||||
|
||||
Run `openspec status --change "<name>" --json` to check artifact completion.
|
||||
|
||||
Parse the JSON to understand:
|
||||
- `schemaName`: The workflow being used
|
||||
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
|
||||
- `artifacts`: List of artifacts with their status (`done`, `skipped`, or other)
|
||||
|
||||
**If any artifacts are neither `done` nor `skipped`** (skipped artifacts satisfy the requirement - the change declares skip_specs):
|
||||
- Display warning listing incomplete artifacts
|
||||
- Ask the user to confirm they want to proceed
|
||||
- Proceed if user confirms
|
||||
|
||||
3. **Check task completion status**
|
||||
|
||||
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
|
||||
|
||||
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
|
||||
|
||||
**If incomplete tasks found:**
|
||||
- Display warning showing count of incomplete tasks
|
||||
- Ask the user to confirm they want to proceed
|
||||
- Proceed if user confirms
|
||||
|
||||
**If no tasks file exists:** Proceed without task-related warning.
|
||||
|
||||
4. **Assess delta spec sync state**
|
||||
|
||||
Use `artifactPaths.specs.existingOutputPaths` from status JSON as the only
|
||||
delta-spec source. If the `specs` entry is missing or
|
||||
`existingOutputPaths` is empty, proceed without a sync prompt and do not infer
|
||||
delta specs from other artifacts.
|
||||
|
||||
**If delta specs exist:**
|
||||
- Compare each delta spec with its corresponding main spec at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (use the store-aware `planningHome.root` from step 2, not a hardcoded repo path)
|
||||
- Determine what changes would be applied (adds, modifications, removals, renames)
|
||||
- Show a combined summary before prompting
|
||||
|
||||
**Prompt options:**
|
||||
- If changes needed: "Sync now (recommended)", "Archive without syncing"
|
||||
- If already synced: "Archive now", "Sync anyway", "Cancel"
|
||||
|
||||
Route on the answer:
|
||||
- "Cancel" — stop, do not archive
|
||||
- "Archive without syncing" or "Archive now" — proceed to archive
|
||||
- "Sync now" or "Sync anyway" — sync, then verify (below)
|
||||
- Anything else — ask again rather than archiving
|
||||
|
||||
Before a selected sync writes any main spec, run
|
||||
`openspec instructions specs --change "<name>" --json` once with the same
|
||||
selected-root flags. Require a zero exit status and valid artifact-instruction
|
||||
JSON. If the lookup fails or returns invalid JSON, report the error and stop
|
||||
before writing any main spec or moving the change. A valid response with omitted
|
||||
`rules` is the no-rules case. Apply returned `rules` only to the content and
|
||||
form of main specs produced by this merge; do not use them as archive guidance,
|
||||
change CLI behavior, or copy the rule text into any output file.
|
||||
|
||||
Then run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching `specs` instructions again. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
|
||||
|
||||
Then re-run the comparison from the top of this step against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
|
||||
- ADDED requirements present
|
||||
- MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
|
||||
- REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving `## Requirements` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
|
||||
- RENAMED requirements present under the new name and absent under the old one
|
||||
|
||||
If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and `changeRoot` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
|
||||
|
||||
5. **Perform the archive**
|
||||
|
||||
Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
|
||||
```bash
|
||||
mkdir -p "<planningHome.changesDir>/archive"
|
||||
```
|
||||
|
||||
Generate the target name: use the change name as-is when it already starts with a `YYYY-MM-DD-` prefix; otherwise prepend the current date as `YYYY-MM-DD-<change-name>`. Never stack a second date (same rule as `openspec archive`).
|
||||
|
||||
**Check if target already exists:**
|
||||
- If yes: Fail with error, suggest renaming existing archive or using different date
|
||||
- If no: Move `changeRoot` to the archive directory
|
||||
|
||||
```bash
|
||||
mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
|
||||
```
|
||||
|
||||
6. **Display summary**
|
||||
|
||||
Show archive completion summary including:
|
||||
- Change name
|
||||
- Schema that was used
|
||||
- Archive location
|
||||
- Whether specs were synced (if applicable)
|
||||
- Note about any warnings (incomplete artifacts/tasks)
|
||||
|
||||
**Output On Success**
|
||||
|
||||
```markdown
|
||||
## Archive Complete
|
||||
|
||||
**Change:** <change-name>
|
||||
**Schema:** <schema-name>
|
||||
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
|
||||
**Specs:** <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped">
|
||||
|
||||
<"All artifacts complete. All tasks complete." — or, if archived with warnings, list them instead (e.g. "Archived with 2 incomplete tasks")>
|
||||
```
|
||||
|
||||
**Guardrails**
|
||||
- Announce the selected change; prompt for selection when it is ambiguous
|
||||
- Use artifact graph (openspec status --json) for completion checking
|
||||
- Don't block archive on warnings - just inform and confirm
|
||||
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
|
||||
- Show clear summary of what happened
|
||||
- If sync is requested, run the `openspec-sync-specs` workflow inline (agent-driven)
|
||||
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving `changeRoot`
|
||||
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
|
||||
- Apply relevant runtime context and report conflicts; operation guidance remains advisory
|
||||
- Consider every guidance entry and explain any inapplicable or conflicting advice
|
||||
- Existing CLI checks, resolved paths, prompts, and command contracts are unchanged
|
||||
- Artifact rules constrain only the specs being written and are never operation guidance
|
||||
- Never copy runtime context, operation guidance, or artifact-rule text verbatim into output files
|
||||
@@ -0,0 +1,308 @@
|
||||
---
|
||||
name: openspec-explore
|
||||
description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
|
||||
allowed-tools: Bash(openspec:*)
|
||||
license: MIT
|
||||
compatibility: Requires openspec CLI.
|
||||
metadata:
|
||||
author: openspec
|
||||
version: "1.0"
|
||||
generatedBy: "1.8.0"
|
||||
---
|
||||
|
||||
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
|
||||
|
||||
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. For a new change, scaffold it first as described below.
|
||||
|
||||
**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
---
|
||||
|
||||
## The Stance
|
||||
|
||||
- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
|
||||
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
|
||||
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
|
||||
- **Adaptive** - Follow interesting threads, pivot when new information emerges
|
||||
- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
|
||||
- **Grounded** - Explore the actual codebase when relevant, don't just theorize
|
||||
|
||||
---
|
||||
|
||||
## What You Might Do
|
||||
|
||||
Depending on what the user brings, you might:
|
||||
|
||||
**Explore the problem space**
|
||||
- Ask clarifying questions that emerge from what they said
|
||||
- Challenge assumptions
|
||||
- Reframe the problem
|
||||
- Find analogies
|
||||
|
||||
**Investigate the codebase**
|
||||
- Map existing architecture relevant to the discussion
|
||||
- Find integration points
|
||||
- Identify patterns already in use
|
||||
- Surface hidden complexity
|
||||
|
||||
**Compare options**
|
||||
- Brainstorm multiple approaches
|
||||
- Build comparison tables
|
||||
- Sketch tradeoffs
|
||||
- Recommend a path (if asked)
|
||||
|
||||
**Visualize**
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Use ASCII diagrams liberally │
|
||||
├─────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────┐ ┌────────┐ │
|
||||
│ │ State │────────▶│ State │ │
|
||||
│ │ A │ │ B │ │
|
||||
│ └────────┘ └────────┘ │
|
||||
│ │
|
||||
│ System diagrams, state machines, │
|
||||
│ data flows, architecture sketches, │
|
||||
│ dependency graphs, comparison tables │
|
||||
│ │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Surface risks and unknowns**
|
||||
- Identify what could go wrong
|
||||
- Find gaps in understanding
|
||||
- Suggest spikes or investigations
|
||||
|
||||
---
|
||||
|
||||
## OpenSpec Awareness
|
||||
|
||||
You have full context of the OpenSpec system. Use it naturally, don't force it.
|
||||
|
||||
### Check for context
|
||||
|
||||
At the start, quickly check what exists:
|
||||
```bash
|
||||
openspec list --json
|
||||
```
|
||||
|
||||
This tells you:
|
||||
- If there are active changes
|
||||
- Their names, schemas, and status
|
||||
- What the user might be working on
|
||||
|
||||
Then read the project's own context from the resolved root - `<root.path>/openspec/config.yaml` (or `config.yml`). Use the `root.path` returned above, and skip this if neither file exists:
|
||||
- `context`: project background - tech stack, conventions, constraints
|
||||
- `rules`: keyed by artifact id - the entries for an artifact apply only when you write that artifact
|
||||
|
||||
Ground your thinking in these. They are constraints for you to follow, not content to reproduce: do NOT copy them into the conversation or into any artifact you create.
|
||||
|
||||
### When no change exists
|
||||
|
||||
Think freely. When insights crystallize, you might offer:
|
||||
|
||||
- "This feels solid enough to start a change. Want me to create a proposal?"
|
||||
- Or keep exploring - no pressure to formalize
|
||||
|
||||
If the user asks you to capture the exploration as a new change, transition seamlessly into the requested capture:
|
||||
|
||||
1. Run `openspec new change "<name>"` (with `--store <id>` when applicable) before creating any artifacts. Never create a new change directory under `openspec/changes/` by hand; the CLI scaffold creates required metadata such as `.openspec.yaml`. Keep the selected `--store <id>` on every applicable follow-up `status` and `instructions` command.
|
||||
2. Run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is `ready`, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own `instruction` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run `openspec instructions "<prerequisite-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) for that prerequisite whether it is `ready` or `blocked`. If its own `instruction` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
|
||||
3. Follow the returned `template` and `instruction` fields. Read completed dependency files listed in `dependencies`, and apply `context` and `rules` as constraints without copying them into the artifact. If the instruction delegates creation to a specific skill or command, invoke it; otherwise write the artifact to `resolvedOutputPath`, using the instruction to choose a concrete path when it is a glob. Verify that the selected concrete output exists.
|
||||
4. After creating each artifact, re-run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) and continue until every requested artifact is `done`, `skipped`, or was deliberately skipped because its own `instruction` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still `blocked` only because you deliberately skipped a conditional prerequisite, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
|
||||
|
||||
Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status.
|
||||
|
||||
### When a change exists
|
||||
|
||||
If the user mentions a change or you detect one is relevant:
|
||||
|
||||
1. **Resolve and read existing artifacts for context**
|
||||
- Run `openspec status --change "<name>" --json`.
|
||||
- Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
|
||||
- Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
|
||||
|
||||
2. **Reference them naturally in conversation**
|
||||
- "Your design mentions using Redis, but we just realized SQLite fits better..."
|
||||
- "The proposal scopes this to premium users, but we're now thinking everyone..."
|
||||
|
||||
3. **Offer to capture when decisions are made**
|
||||
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
|
||||
|
||||
| Insight Type | Where to Capture |
|
||||
|----------------------------|-------------------------------------|
|
||||
| New requirement discovered | `specs/<capability-path>/spec.md` |
|
||||
| Requirement changed | `specs/<capability-path>/spec.md` |
|
||||
| Design decision made | `design.md` |
|
||||
| Scope changed | `proposal.md` |
|
||||
| New work identified | `tasks.md` |
|
||||
| Assumption invalidated | Relevant artifact |
|
||||
|
||||
Example offers:
|
||||
- "That's a design decision. Capture it in design.md?"
|
||||
- "This is a new requirement. Add it to specs?"
|
||||
- "This changes scope. Update the proposal?"
|
||||
|
||||
4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
|
||||
|
||||
---
|
||||
|
||||
## What You Don't Have To Do
|
||||
|
||||
- Follow a script
|
||||
- Ask the same questions every time
|
||||
- Produce a specific artifact
|
||||
- Reach a conclusion
|
||||
- Stay on topic if a tangent is valuable
|
||||
- Be brief (this is thinking time)
|
||||
|
||||
---
|
||||
|
||||
## Handling Different Entry Points
|
||||
|
||||
**User brings a vague idea:**
|
||||
```
|
||||
User: I'm thinking about adding real-time collaboration
|
||||
|
||||
You: Real-time collab is a big space. Let me think about this...
|
||||
|
||||
COLLABORATION SPECTRUM
|
||||
════════════════════════════════════════════
|
||||
|
||||
Awareness Coordination Sync
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌────────┐ ┌────────┐ ┌────────┐
|
||||
│Presence│ │Cursors │ │ CRDT │
|
||||
│ "3 │ │ Multi │ │Conflict│
|
||||
│online" │ │ select │ │ free │
|
||||
└────────┘ └────────┘ └────────┘
|
||||
│ │ │
|
||||
trivial moderate complex
|
||||
|
||||
Where's your head at?
|
||||
```
|
||||
|
||||
**User brings a specific problem:**
|
||||
```
|
||||
User: The auth system is a mess
|
||||
|
||||
You: [reads codebase]
|
||||
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ CURRENT AUTH FLOW │
|
||||
└─────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ Google │ │ GitHub │ │ Email │
|
||||
│ OAuth │ │ OAuth │ │ Magic │
|
||||
└────┬────┘ └────┬────┘ └────┬────┘
|
||||
│ │ │
|
||||
└─────────────┼─────────────┘
|
||||
▼
|
||||
┌───────────┐
|
||||
│ Session │
|
||||
└─────┬─────┘
|
||||
│
|
||||
▼
|
||||
┌───────────┐
|
||||
│ Perms │
|
||||
└───────────┘
|
||||
|
||||
I see three tangles. Which one's burning?
|
||||
```
|
||||
|
||||
**User is stuck mid-implementation:**
|
||||
```
|
||||
User: /opsx:explore add-auth-system
|
||||
The OAuth integration is more complex than expected
|
||||
|
||||
You: [reads change artifacts]
|
||||
|
||||
You're on task 4: "Implement OAuth flow"
|
||||
|
||||
Let me trace what's involved...
|
||||
|
||||
[draws diagram, explores options, suggests paths]
|
||||
|
||||
Want to update the design to reflect this?
|
||||
Or add a spike task to investigate?
|
||||
```
|
||||
|
||||
**User wants to compare options:**
|
||||
```
|
||||
User: Should we use Postgres or SQLite?
|
||||
|
||||
You: Generic answer is boring. What's the context?
|
||||
|
||||
User: A CLI tool that tracks local dev environments
|
||||
|
||||
You: That changes everything.
|
||||
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ CLI TOOL DATA STORAGE │
|
||||
└─────────────────────────────────────────────────┘
|
||||
|
||||
Key constraints:
|
||||
• No daemon running
|
||||
• Must work offline
|
||||
• Single user
|
||||
|
||||
SQLite Postgres
|
||||
Deployment embedded ✓ needs server ✗
|
||||
Offline yes ✓ no ✗
|
||||
Single file yes ✓ no ✗
|
||||
|
||||
SQLite. Not even close.
|
||||
|
||||
Unless... is there a sync component?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ending Discovery
|
||||
|
||||
There's no required ending. Discovery might:
|
||||
|
||||
- **Flow into a proposal**: "Ready to start? I can create a change proposal."
|
||||
- **Result in artifact updates**: "Updated design.md with these decisions"
|
||||
- **Just provide clarity**: User has what they need, moves on
|
||||
- **Continue later**: "We can pick this up anytime"
|
||||
|
||||
When it feels like things are crystallizing, you might summarize:
|
||||
|
||||
```
|
||||
## What We Figured Out
|
||||
|
||||
**The problem**: [crystallized understanding]
|
||||
|
||||
**The approach**: [if one emerged]
|
||||
|
||||
**Open questions**: [if any remain]
|
||||
|
||||
**Next steps** (if ready):
|
||||
- Create a change proposal
|
||||
- Keep exploring: just keep talking
|
||||
```
|
||||
|
||||
But this summary is optional. Sometimes the thinking IS the value.
|
||||
|
||||
---
|
||||
|
||||
## Guardrails
|
||||
|
||||
- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
|
||||
- **Don't fake understanding** - If something is unclear, dig deeper
|
||||
- **Don't rush** - Discovery is thinking time, not task time
|
||||
- **Don't force structure** - Let patterns emerge naturally
|
||||
- **Don't auto-capture** - Offer to save insights, don't just do it
|
||||
- **Don't manually scaffold changes** - Never create a new change directory under `openspec/changes/` by hand. Always use `openspec new change "<name>"` (with `--store <id>` when applicable) so required metadata such as `.openspec.yaml` is created before writing artifacts.
|
||||
- **Do visualize** - A good diagram is worth many paragraphs
|
||||
- **Do explore the codebase** - Ground discussions in reality
|
||||
- **Do question assumptions** - Including the user's and your own
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
name: openspec-propose
|
||||
description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
|
||||
allowed-tools: Bash(openspec:*)
|
||||
license: MIT
|
||||
compatibility: Requires openspec CLI.
|
||||
metadata:
|
||||
author: openspec
|
||||
version: "1.0"
|
||||
generatedBy: "1.8.0"
|
||||
---
|
||||
|
||||
Propose a new change - create the change and generate all artifacts in one step.
|
||||
|
||||
**Planning boundary**: This workflow creates planning artifacts only. The user request that selected or triggered this workflow authorizes planning only, even if it asks to build or fix something. Do not edit project code. After the planning artifacts are complete, stop. Do not start implementation in the same response, even if the initial request asks for it. Wait for a new user request after the artifacts are presented; then start the apply workflow.
|
||||
|
||||
I'll create a change with the artifacts your schema defines. With the default spec-driven schema that is:
|
||||
- proposal.md (what & why)
|
||||
- `specs/<capability-path>/spec.md` (what the system must do - a delta, not the main spec)
|
||||
- design.md (how)
|
||||
- tasks.md (implementation steps)
|
||||
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
|
||||
|
||||
When the user is ready to implement, they must start the apply workflow explicitly.
|
||||
|
||||
---
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Understand the request and clarify material ambiguity**
|
||||
|
||||
If no clear input is provided, ask the user (open-ended, no preset options):
|
||||
> "What change do you want to work on? Describe what you want to build or fix."
|
||||
|
||||
From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
|
||||
|
||||
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
|
||||
|
||||
If the request contains ambiguity that would materially affect scope, externally observable behavior, compatibility, or acceptance criteria, ask the user before creating the change. For minor details, make a reasonable assumption and record it in the planning artifacts.
|
||||
|
||||
2. **Determine the workflow schema**
|
||||
|
||||
Use the configured default schema unless the user explicitly requests a different workflow.
|
||||
|
||||
**Use a different schema only if the user:**
|
||||
- Explicitly requests a specific schema by name → use `--schema <schema-name>`
|
||||
- Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running `openspec context --json` from the current working directory. If the user explicitly selected a registered store, use `openspec context --json --store "<store-id>"`. Then run `openspec schemas --json` with its working directory set to the returned `root.path` and let them choose. This preserves roots selected by a local `store:` pointer or the global `defaultStore`; `schemas` does not accept `--store`. If context reports only `no_openspec_root`, run `openspec schemas --json` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
|
||||
|
||||
Otherwise, omit `--schema` to preserve the configured default.
|
||||
|
||||
3. **Create the change directory**
|
||||
|
||||
Choose one schema form below. If a registered store is selected, append `--store "<store-id>"` to that command and each later OpenSpec command shown below that accepts `--store`.
|
||||
|
||||
Using the configured default:
|
||||
```bash
|
||||
openspec new change "<name>"
|
||||
```
|
||||
|
||||
Using an explicitly requested schema:
|
||||
```bash
|
||||
openspec new change "<name>" --schema "<schema-name>"
|
||||
```
|
||||
This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
|
||||
|
||||
4. **Get the artifact build order**
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
Parse the JSON to get:
|
||||
- `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
|
||||
- `artifacts`: list of all artifacts, each with its `status` and its `requires` edges (the artifact IDs it directly depends on)
|
||||
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
|
||||
|
||||
5. **Create every artifact in the required set**
|
||||
|
||||
Use a todo list to track progress through the artifacts.
|
||||
|
||||
Loop through artifacts in dependency order (artifacts with no pending dependencies first):
|
||||
|
||||
a. **For each artifact that is `ready` (dependencies satisfied)**:
|
||||
- Get instructions:
|
||||
```bash
|
||||
openspec instructions <artifact-id> --change "<name>" --json
|
||||
```
|
||||
- The instructions JSON includes:
|
||||
- `context`: Project background (constraints for you - do NOT include in output)
|
||||
- `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
|
||||
- `template`: The structure to use for your output file
|
||||
- `instruction`: Schema-specific guidance for this artifact type
|
||||
- `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact
|
||||
- `resolvedOutputPath`: Resolved path or pattern to write the artifact
|
||||
- `dependencies`: Completed artifacts to read for context
|
||||
- Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
|
||||
- If the `instruction` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at `resolvedOutputPath`
|
||||
- Otherwise create the artifact file using `template` as the structure and write it to `resolvedOutputPath`. If `resolvedOutputPath` is a glob, follow `instruction` to choose the concrete file path
|
||||
- Apply `context` and `rules` as constraints - but do NOT copy them into the file
|
||||
- Show brief progress: "Created <artifact-id>"
|
||||
|
||||
b. **Continue until every artifact in the required set exists (not just `apply.requires`)**
|
||||
- After creating each artifact, re-run `openspec status --change "<name>" --json`
|
||||
- The required set is `applyRequires` plus every artifact reachable from those by following the `requires` edges in `status --json` - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone
|
||||
- `status` is file-existence only, so an `applyRequires` artifact reading `done` does NOT mean its dependencies exist - writing `tasks.md` early marks `tasks` done while `specs` was never written. Use each artifact's `requires` edges, not its `status`, to build the required set: a `done` artifact still lists what it depends on
|
||||
- An artifact already reading `status: "skipped"` is satisfied: the change declares `skip_specs` in `.openspec.yaml`, so its files must NOT exist. Never try to create one
|
||||
- Create every artifact in the required set that is missing, then re-check - creating one can unblock others
|
||||
- Skip one only when `status` already reports it `skipped`, or when its own `instruction` says it is conditional: run `openspec instructions <artifact-id> --change "<name>" --json` and skip only if its `instruction` field marks it optional (e.g. "create only if..."). Spec-driven's `design.md` qualifies; `specs` qualifies only via the `skipped` status above, never by your own judgment. Tell the user, and do not reconsider it
|
||||
- Dependencies are enablers, not gates: if a required artifact is still `blocked` only because you skipped a conditional dependency, write it anyway
|
||||
- Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped
|
||||
|
||||
c. **If an artifact requires user input** (unclear context):
|
||||
- Ask the user to clarify
|
||||
- Then continue with creation
|
||||
|
||||
6. **Show final status**
|
||||
```bash
|
||||
openspec status --change "<name>"
|
||||
```
|
||||
|
||||
**Output**
|
||||
|
||||
After completing all artifacts, summarize:
|
||||
- Change name and location
|
||||
- List of artifacts created with brief descriptions, plus any conditional artifact you skipped and why
|
||||
- What's ready: "All artifacts needed for implementation are ready."
|
||||
- Prompt: "The artifacts are ready for review. When you are ready, run `/opsx:apply` or ask me to apply this change."
|
||||
|
||||
**Artifact Creation Guidelines**
|
||||
|
||||
- Follow the `instruction` field from `openspec instructions` for each artifact type - it is the authoritative guidance, even for familiar artifact names
|
||||
- If the `instruction` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
|
||||
- The schema defines what each artifact should contain - follow it
|
||||
- Read dependency artifacts for context before creating new ones
|
||||
- Use `template` as the structure for your output file - fill in its sections
|
||||
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
|
||||
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
|
||||
- These guide what you write, but should never appear in the output
|
||||
|
||||
**Guardrails**
|
||||
- The request that invoked this workflow authorizes planning only. Any implementation or apply instruction in that request does not carry forward. Do NOT implement the change, start the apply workflow, or edit project code during this workflow. After presenting the artifacts, stop and wait for a new user request to start the apply workflow
|
||||
- Create every artifact the apply phase transitively depends on, not just the ids listed in `apply.requires`
|
||||
- Always read dependency artifacts before creating a new one - re-read from disk, not from conversation memory (files may have changed since you last saw them)
|
||||
- Ask about ambiguities that would materially change scope, externally observable behavior, compatibility, or acceptance criteria; for minor details, make reasonable assumptions and record them
|
||||
- If a change with that name already exists, ask if user wants to continue it or create a new one
|
||||
- Verify each artifact file exists after writing before proceeding to next
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
name: openspec-sync-specs
|
||||
description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
|
||||
allowed-tools: Bash(openspec:*)
|
||||
license: MIT
|
||||
compatibility: Requires openspec CLI.
|
||||
metadata:
|
||||
author: openspec
|
||||
version: "1.0"
|
||||
generatedBy: "1.8.0"
|
||||
---
|
||||
|
||||
Sync delta specs from a change to main specs.
|
||||
|
||||
This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
|
||||
|
||||
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Select the change**
|
||||
|
||||
If a name is provided, use it. Otherwise:
|
||||
- Infer from conversation context if the user mentioned a change
|
||||
- Auto-select if only one active change exists
|
||||
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
|
||||
|
||||
When prompting, show changes that have delta specs (under `specs/` directory).
|
||||
|
||||
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:sync <other>`).
|
||||
|
||||
2. **Resolve change context**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
|
||||
The JSON includes `planningHome.root`. Main specs live under `<planningHome.root>/openspec/specs/` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
|
||||
|
||||
3. **Find delta specs**
|
||||
|
||||
Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the
|
||||
only source of delta spec paths. If the `specs` entry is missing or
|
||||
`existingOutputPaths` is empty, report that there are no delta specs to sync,
|
||||
do not infer them from other artifacts, and stop without requesting artifact
|
||||
instructions or writing a main spec.
|
||||
|
||||
Sync every path in `existingOutputPaths` unless the caller narrowed the set.
|
||||
A caller narrows it by naming an explicit list of complete entries from
|
||||
`existingOutputPaths` — copy those absolute values verbatim. Archive does
|
||||
this inline, and a user can too (for example, by selecting the entry ending
|
||||
in `/specs/billing/invoices/spec.md`).
|
||||
Then sync only the named paths and leave the remaining delta specs untouched:
|
||||
bulk archive excludes a delta whose implementation it could not find, and
|
||||
syncing it anyway would write a main spec the caller deliberately withheld.
|
||||
Carry that narrowed selection through step 4; never widen it back to the full
|
||||
list. If a named path is not in `existingOutputPaths`, do not sync it —
|
||||
report it and stop, rather than dropping it silently. If the named list is
|
||||
empty, report that there is nothing to sync and stop without writing a main
|
||||
spec.
|
||||
|
||||
Each delta spec file contains sections like:
|
||||
- `## ADDED Requirements` - New requirements to add
|
||||
- `## MODIFIED Requirements` - Changes to existing requirements
|
||||
- `## REMOVED Requirements` - Requirements to remove
|
||||
- `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
|
||||
|
||||
If no delta specs found, inform user and stop.
|
||||
|
||||
4. **For each delta spec, apply changes to main specs**
|
||||
|
||||
Before the first main-spec write, obtain one current specs-rule snapshot:
|
||||
- If archive invoked this workflow inline and supplied a valid snapshot from
|
||||
`openspec instructions specs --change "<name>" --json`, reuse it and do not
|
||||
fetch the same instructions again.
|
||||
- Otherwise run that command once now with the same selected-root flags.
|
||||
- If the direct lookup exits non-zero or returns invalid artifact-instruction
|
||||
JSON, report the error and stop before writing any main spec. Do not treat the
|
||||
failure as an absent rule set.
|
||||
- A valid response with omitted `rules` means no artifact rules are configured
|
||||
and the existing semantic merge continues.
|
||||
|
||||
Apply returned `rules` only to the content and form of the main specs produced
|
||||
by this merge. Artifact rules are not operation guidance and cannot change
|
||||
selected roots, delta paths, CLI checks, or workflow steps. Use their text as
|
||||
constraints without copying it verbatim into a main spec or summary.
|
||||
|
||||
For each capability delta spec path selected in step 3 — the full `existingOutputPaths` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
|
||||
|
||||
a. **Read the delta spec** to understand the intended changes
|
||||
|
||||
b. **Read the main spec** at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (may not exist yet)
|
||||
|
||||
c. **Apply changes intelligently**:
|
||||
|
||||
**ADDED Requirements:**
|
||||
- If requirement doesn't exist in main spec → add it
|
||||
- If requirement already exists → update it to match (treat as implicit MODIFIED)
|
||||
|
||||
**MODIFIED Requirements:**
|
||||
- Find the requirement in main spec
|
||||
- Apply the changes - this can be:
|
||||
- Adding new scenarios the main spec does not have yet
|
||||
- Modifying existing scenarios
|
||||
- Changing the requirement description
|
||||
- Preserve scenarios/content not mentioned in the delta
|
||||
|
||||
**REMOVED Requirements:**
|
||||
- Remove the entire requirement block from main spec
|
||||
- Retiring the capability. Delete the whole `spec.md` - and the directory once
|
||||
nothing else is left in it - only when ALL of these hold:
|
||||
1. removing the requirements *this run* left no requirement blocks;
|
||||
2. the rest of the spec is well-formed (it still has a `## Purpose`);
|
||||
3. the main spec was not already empty before this sync - if you removed
|
||||
nothing, change nothing;
|
||||
4. every other nonblank line in the whole file is accounted for as the
|
||||
title, Purpose, Requirements header, or a canonical requirement's
|
||||
statement, scenarios, or fenced examples;
|
||||
5. the change's `.openspec.yaml` declares `retire_capabilities: true`;
|
||||
6. the `spec.md` resolves inside the real specs root (do not follow a
|
||||
capability-directory symlink to delete an external file).
|
||||
If removing the selected requirements would leave no requirement blocks and
|
||||
any retirement condition is not satisfied, do not modify the main spec. Stop
|
||||
the sync for that capability, report the blocking condition, and tell the user
|
||||
how to resolve it. Never write or leave an empty `## Requirements` section.
|
||||
When only the marker is missing, say that too - it is the one thing the user
|
||||
can add to make the retirement go through.
|
||||
- Deleting the file also deletes its `## Purpose`; any other section blocks
|
||||
retirement. Name Purpose when you report the retirement. Include a pasteable
|
||||
`git checkout` only when the spec lived in the caller's checkout;
|
||||
otherwise give checkout-scoped recovery guidance.
|
||||
|
||||
**RENAMED Requirements:**
|
||||
- Find the FROM requirement, rename to TO
|
||||
|
||||
**`## Purpose` in the delta:**
|
||||
- The main spec already has one and it is authoritative - leave it alone
|
||||
(this is what `openspec archive` does; it warns and moves on)
|
||||
|
||||
d. **Create new main spec** if capability doesn't exist yet:
|
||||
- Create `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
|
||||
- Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one
|
||||
(this is what `openspec archive` does); only write a brief TBD placeholder when it does not
|
||||
- Add Requirements section with the ADDED requirements
|
||||
- Follow the **Main Spec Format Reference** below
|
||||
|
||||
5. **Validate updated main specs**
|
||||
|
||||
Run `openspec validate --specs` with the same selected-root flags used earlier.
|
||||
If validation fails, report the problems and do not claim the sync succeeded.
|
||||
|
||||
6. **Show summary**
|
||||
|
||||
After applying all changes, summarize:
|
||||
- Which capabilities were updated
|
||||
- What changes were made (requirements added/modified/removed/renamed)
|
||||
- Any new main spec left with a TBD Purpose placeholder, so it gets written
|
||||
now rather than lingering
|
||||
- Any capability retired, naming the deleted `spec.md`, its Purpose, and
|
||||
either a pasteable `git checkout` or checkout-scoped recovery guidance
|
||||
|
||||
**Delta Spec Format Reference**
|
||||
|
||||
```markdown
|
||||
## Purpose
|
||||
|
||||
Only on a delta that introduces a brand-new capability. Seeds the new main spec.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: New Feature
|
||||
The system SHALL do something new.
|
||||
|
||||
#### Scenario: Basic case
|
||||
- **WHEN** user does X
|
||||
- **THEN** system does Y
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Existing Feature
|
||||
The system SHALL keep doing the existing thing, now also handling A.
|
||||
|
||||
#### Scenario: Scenario the main spec already has
|
||||
- **WHEN** user does X
|
||||
- **THEN** system does Y
|
||||
|
||||
#### Scenario: New scenario to add
|
||||
- **WHEN** user does A
|
||||
- **THEN** system does B
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Deprecated Feature
|
||||
|
||||
## RENAMED Requirements
|
||||
|
||||
- FROM: `### Requirement: Old Name`
|
||||
- TO: `### Requirement: New Name`
|
||||
```
|
||||
|
||||
**Main Spec Format Reference**
|
||||
|
||||
Main specs are what the delta merges INTO. They must never contain delta operation headers (`## ADDED/MODIFIED/REMOVED/RENAMED Requirements`) - after syncing, every requirement lives under a single `## Requirements` section:
|
||||
|
||||
```markdown
|
||||
# <capability> Specification
|
||||
|
||||
## Purpose
|
||||
Short description of what this capability does and why it exists.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: New Feature
|
||||
The system SHALL do something new.
|
||||
|
||||
#### Scenario: Basic case
|
||||
- **WHEN** user does X
|
||||
- **THEN** system does Y
|
||||
```
|
||||
|
||||
**Key Principle: Intelligent Merging**
|
||||
|
||||
Unlike programmatic merging, you merge rather than overwrite:
|
||||
- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. `openspec validate` and `openspec archive` both reject one that drops a scenario the main spec still has.
|
||||
- Keep anything the delta does not mention, in the main spec's existing order
|
||||
- Use your judgment to merge changes sensibly
|
||||
|
||||
**Output On Success**
|
||||
|
||||
```markdown
|
||||
## Specs Synced: <change-name>
|
||||
|
||||
Updated main specs:
|
||||
|
||||
**<capability-1>**:
|
||||
- Added requirement: "New Feature"
|
||||
- Modified requirement: "Existing Feature" (added 1 scenario)
|
||||
|
||||
**<capability-2>**:
|
||||
- Created new spec file
|
||||
- Added requirement: "Another Feature"
|
||||
|
||||
Main specs are now updated. The change remains active - archive when implementation is complete.
|
||||
```
|
||||
|
||||
**Guardrails**
|
||||
- Read both delta and main specs before making changes
|
||||
- Preserve existing content not mentioned in delta
|
||||
- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
|
||||
- If something is unclear, ask for clarification
|
||||
- Show what you're changing as you go
|
||||
- The operation should be idempotent - running twice should give same result
|
||||
- Use only `artifactPaths.specs.existingOutputPaths`; never infer delta specs from unrelated artifacts
|
||||
- Honor a caller-supplied subset of `existingOutputPaths`; never widen it back to the full list
|
||||
- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
|
||||
- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
|
||||
- Artifact rules constrain only the specs being written and are never copied into output files
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
name: openspec-update-change
|
||||
description: Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.
|
||||
allowed-tools: Bash(openspec:*)
|
||||
license: MIT
|
||||
compatibility: Requires openspec CLI.
|
||||
metadata:
|
||||
author: openspec
|
||||
version: "1.0"
|
||||
generatedBy: "1.8.0"
|
||||
---
|
||||
|
||||
Revise a change's existing planning artifacts and keep them coherent. Never edit code.
|
||||
|
||||
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
||||
|
||||
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||
|
||||
`/opsx:continue` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, `openspec status --change "<name>" --json` shows the next artifact and `openspec instructions "<artifact-id>" --change "<name>" --json` explains how to create it.
|
||||
|
||||
**Steps**
|
||||
|
||||
1. **Select the change**
|
||||
|
||||
If a name is provided, use it. Otherwise:
|
||||
- Infer from conversation context if the user mentioned a change
|
||||
- Auto-select if only one active change exists
|
||||
- If ambiguous, run `openspec list --json` to get available changes sorted by most recently modified, and ask the user to select one
|
||||
|
||||
When prompting, present the top 3-4 most recently modified changes as options, showing:
|
||||
- Change name
|
||||
- Schema (from `schema` field if present, otherwise "spec-driven")
|
||||
- Status (e.g., "0/5 tasks", "complete", "no tasks")
|
||||
- How recently it was modified (from `lastModified` field)
|
||||
|
||||
Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
|
||||
|
||||
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:update <other>`).
|
||||
|
||||
2. **Get the change's artifacts**
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
Parse the JSON to understand current state. The response includes:
|
||||
- `schemaName`: The workflow schema being used (e.g., "spec-driven")
|
||||
- `artifacts`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
|
||||
- `isPlanningComplete`: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as `isComplete`.
|
||||
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
|
||||
|
||||
The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
|
||||
|
||||
The files to edit are `artifactPaths.<id>.existingOutputPaths` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. `specs/**/*.md`). Do NOT write to `resolvedOutputPath`: for a glob artifact it is still the glob pattern, not a real file.
|
||||
|
||||
3. **Understand the request**
|
||||
- If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
|
||||
- If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
|
||||
|
||||
4. **Read and reconcile**
|
||||
- Read the artifact(s) the request touches and the change's other existing artifacts.
|
||||
- Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
|
||||
- Note everything that is now inconsistent, missing, or contradictory.
|
||||
- Revise only files that already exist (`existingOutputPaths`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to `/opsx:continue` to create them.
|
||||
- If the change is already coherent, say so and make no edits.
|
||||
|
||||
5. **Confirm and apply, one artifact at a time**
|
||||
- Show each proposed revision and why. Write only after the user confirms.
|
||||
- If the user rejects a revision, do not write it - leave that artifact unchanged.
|
||||
- When a substantial rewrite is needed, get that artifact's rules and template first:
|
||||
```bash
|
||||
openspec instructions "<artifact-id>" --change "<name>" --json
|
||||
```
|
||||
|
||||
6. **Point to the next step (guidance only - NEVER act on it)**
|
||||
- Artifacts still missing -> suggest `/opsx:continue` to create them.
|
||||
- Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest `/opsx:apply` to carry the delta into code.
|
||||
- Everything done and implemented -> suggest `/opsx:archive`.
|
||||
|
||||
**Output**
|
||||
|
||||
After each invocation, show:
|
||||
- Which artifacts were revised (and which proposed revisions were rejected)
|
||||
- Anything deferred to `/opsx:continue` (not-yet-created artifacts or files)
|
||||
- Where the change stands and the recommended next command
|
||||
|
||||
**Guardrails**
|
||||
- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `/opsx:apply`.
|
||||
- Use the artifact ids and paths reported by `openspec status`; never branch on hardcoded artifact names.
|
||||
- Edit only the concrete files in `existingOutputPaths`; never write to a glob `resolvedOutputPath`.
|
||||
- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is `/opsx:continue`'s job.
|
||||
- Confirm every edit with the user before writing.
|
||||
- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile `/opsx:new` workflow is available. If it is, recommend starting fresh with `/opsx:new` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend `openspec new change "<new-change-name>"` instead.
|
||||
@@ -30,3 +30,11 @@ coverage/
|
||||
.vscode/
|
||||
# Keep small, sanitized evidence summaries in evidence/ under version control.
|
||||
# Inspect git diff --cached: ignore rules are not a secret scanner.
|
||||
|
||||
# Тулчейн студенческой реализации
|
||||
.pytest_cache/
|
||||
.ruff_cache/
|
||||
.ty_cache/
|
||||
|
||||
# Локальные настройки агента
|
||||
.claude/settings.local.json
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
## Что это за репозиторий
|
||||
|
||||
Skeleton лабораторной 5 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке `solution/bpi2303-kostylev`. Skeleton даёт задание (`README.md`), нормативный контракт (`contracts/`) и публичные black-box проверки (`tests/`). Реализация API, worker, relay, Dockerfile, compose-стенд, конфигурация балансировщика, S3 и брокера, миграции, хуки отказов и собственные тесты — студенческие; решение лабы 5 построено переносом решения лабы 4.
|
||||
|
||||
Лаба 5: приём вложения отделён от тяжёлой обработки. `POST /api/v1/chats/{chat_id}/attachments` проверяет файл как в лабе 4, кладёт оригинал в приватный префикс `staging/` bucket **RustFS** и одной транзакцией PostgreSQL фиксирует вложение `queued`, задание (`jobs`) и строку **transactional outbox**; только после этого отвечает `202` со снимком `queued`. Отдельный сервис `relay` публикует outbox в **RabbitMQ 4.1** (quorum queue, DLX, publisher confirms, `mandatory`, persistent), отдельный сервис `worker` (тот же образ, свой entrypoint) потребляет очередь через **FastStream** поверх aio-pika с ручным `ack` строго после `COMMIT` результата, захватывает задание арендой (`lease_token`), публикует оригинал в `originals/` и строит варианты Pillow. Источник истины состояний — PostgreSQL, брокер — транспорт и будильник. Остаётся всё из лаб 1–4: HAProxy перед ≥2 репликами, `X-Instance-Id`, `Idempotency-Key`, Basic → Bearer, хуки остановки реплики и рестарта стенда.
|
||||
|
||||
## Команды
|
||||
|
||||
```sh
|
||||
make check # offline: структура skeleton, JSON, локальные $ref, синтаксис Python, версия 1.5.0
|
||||
make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1 и jobs.schema.json (venv с requirements-dev.txt)
|
||||
make install # uv sync --group dev
|
||||
make lint # ruff check + ruff format --check + ty check; обязательно перед commit
|
||||
make student-test # собственные тесты (одноразовые PostgreSQL, Valkey, RustFS и RabbitMQ в Docker)
|
||||
|
||||
make secrets # локальные secrets/* (PostgreSQL, Valkey, S3 root/API/worker, RabbitMQ) и .env
|
||||
make up # docker compose up -d --build --wait: хранилища и broker → migrate, s3-init → api ×2, relay, worker → lb
|
||||
make test # публичный smoke через LB (BASE_URL, по умолчанию http://localhost:8080)
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт lb, api, relay, worker и postgres, valkey, s3, broker с volumes
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики TARGET_INSTANCE_ID под запросами
|
||||
make restore # вернуть остановленные реплики и дождаться их в ротации LB
|
||||
make worker-stop / worker-start # демонстрация «worker недоступен»
|
||||
make queues # очереди брокера: ready, unacked, consumers
|
||||
make level3 # сценарии уровня «3» suite (scripts/pipeline_suite.py) → evidence/level3.json
|
||||
make down # остановка без удаления данных; make reset-data — намеренное удаление volumes
|
||||
```
|
||||
|
||||
`tests/*.py` и `scripts/*.py` — только stdlib, синтаксис Python 3.9 (`make check` разбирает их системным `python3`). Проверки сами не поднимают стенд. Хуки `scripts/stop-one.sh` и `scripts/restart.sh` запускаются тестом без shell, поэтому исполняемые и с shebang. Данные не удаляются автоматически: каждый прогон smoke создаёт новых синтетических пользователей и вложения.
|
||||
|
||||
## Архитектура skeleton
|
||||
|
||||
- `lab.json` — единственный источник номера лабы (5). От него зависят `scripts/check_contract.py` (`info.version == 1.5.0`) и `tests/client.py` (ветки `LAB>=5`: upload отвечает `202 queued`, сообщение с вложением сразу, ожидание `ready` до 60 с от второго участника, ровно один вариант `thumbnail` 256×160 настоящим JPEG).
|
||||
- `tests/` байт в байт как в лабе 4; поведение переключает только `lab.json`. `tests/resilience.py` после хука рестарта запрашивает метаданные и оригинал один раз с таймаутом 2 с.
|
||||
- `contracts/jobs.schema.json` — формат сообщения брокера (7 обязательных полей, без bytes, URL, ключей S3 и filename); `contracts/attachment-states.md` — машина состояний и окна отказа.
|
||||
- `contracts/infrastructure.json` — роли `api`, `postgres`, `load_balancer`, `s3`, `broker` (persistent volume, at-least-once), `worker` (отдельный процесс). `compose.example.yaml` — только worksheet ролей.
|
||||
|
||||
## Ключевые правила контракта (lab5)
|
||||
|
||||
- Upload: те же лимиты и коды, что в лабе 4 (`413`, `415`, `400`, `404`), но успех — `202 Attachment` со снимком `status=queued`, `variants=[]`, `error_code=null`; снимок берётся из записанного объекта, а не перечитывается после публикации. `202` — только после записи оригинала в `staging/` и `COMMIT` вложения, задания и outbox.
|
||||
- Состояния: `queued → processing → ready | failed`; `processing → queued` при временной ошибке или истёкшей аренде; `failed → queued` только явным replay. `ready` не откатывается. `ready` выставляется, только когда записаны оригинал и все обещанные уровнем варианты.
|
||||
- `/content` для `queued`, `processing`, `failed` — `409 conflict` для любого `variant`, включая `original`; неизвестный `variant` — `400`; отсутствующий вариант `ready`-вложения — `404`; посторонний — `404`. Варианты: `thumbnail` JPEG вписан в 256×256 без увеличения, EXIF orientation применяется, alpha на белом, размеры вниз, минимум 1 px.
|
||||
- Сообщение: вложение `queued`/`processing` прикрепляется (`201`), `failed` — `409`, вложение другого чата или неизвестное — `404`.
|
||||
- Сообщение брокера — ровно поля `jobs.schema.json`; `job_id` не меняется при redelivery, `attempt` растёт только при управляемом повторе через outbox. Ключ эффекта — `(attachment_id, pipeline_version, variant)`.
|
||||
- Сохраняются правила lab4 (сырые байты, тип по содержимому, скачивание только через API без redirect), lab3 (`X-Instance-Id`, `Idempotency-Key`, LB не повторяет upload), lab2 (`Basic` только на входе, `Bearer` дальше, `WWW-Authenticate` по пути) и lab1 (формат ошибки, посторонний → `404`, keyset `(created_at, id)`, время RFC 3339 с `Z`).
|
||||
|
||||
## Правила работы с репозиторием
|
||||
|
||||
- Не менять и не ослаблять `contracts/`, `tests/`, `README.md`, `COURSE.md`, рубрику. Расхождение оформляется вопросом преподавателю.
|
||||
- Код — `src/messenger/`, миграции — `src/messenger/migrations/NNNN_*.sql`, конфигурация LB, нагрузки, S3 и брокера — `infra/`, хуки и обвязка стенда — `scripts/`, собственные тесты — `student-tests/`, обезличенные доказательства — `evidence/`.
|
||||
- Без комментариев в коде; отступы — пробелы (`[tool.ruff.format]`); Python 3.14 без `from __future__ import annotations` и `TYPE_CHECKING`.
|
||||
- Порты реплик API, S3, AMQP наружу не публикуются: только LB и UI брокера на `127.0.0.1`. API к брокеру не подключается. Клиенты брокера не объявляют очереди: топология — в `infra/rabbitmq/definitions.json`, права configure есть только у оператора.
|
||||
- `REPORT.md`: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов. PASS без команды не доказательство; для отказов — какой контейнер реально остановлен (`docker ps -a`).
|
||||
- Ветка `solution/bpi2303-kostylev`, коммиты на английском, перед каждым — `make lint`. Никогда не коммитить `.env`, `secrets/`, токены, ключи S3, пароли брокера, volumes, дампы.
|
||||
|
||||
## Уровни оценки
|
||||
|
||||
Решение заявлено на **«5»** с треком 2 «Доказанная идемпотентность pipeline»; таблица доказательств — в `REPORT.md`.
|
||||
|
||||
- **3** — `202 queued` после staging и `COMMIT` задания с outbox; отдельные `broker`, `relay`, `worker` в стенде; durable quorum queue, publisher confirm, ручной `ack` после `COMMIT`; состояния `queued/processing/ready/failed`, оригинал в `originals/` и thumbnail; ограниченный retry (`JOB_MAX_ATTEMPTS=5`) и `failed` с `error_code`; повтор job без второго набора вариантов; worker остановлен → upload → сообщение → рестарт API и broker → worker → `ready`; минимум lab4 сохранён.
|
||||
- **4** — crop и optimized WebP, лимиты worker по байтам, пикселям, времени и памяти, crash между `COMMIT` и publish, backoff с jitter и классификация ошибок, DLQ и replay, crash после записи объекта до `ack`, lease и fencing для зависшего `processing`, prefetch, очистка staging.
|
||||
- **5** — трек 2: `pipeline_version` 1 и 2, монотонная публикация, автоматический fault-injection (дубль, reorder, crash до и после side effect, устаревшая job) и проверка инвариантов одной командой.
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-29
|
||||
archived: 2026-09-29
|
||||
lab: 1
|
||||
@@ -0,0 +1,177 @@
|
||||
## Context
|
||||
|
||||
См. `proposal.md` — Why. Ограничения, формирующие подход:
|
||||
|
||||
- Состояние живёт только в памяти одного процесса. Это не временное упрощение, а условие лабы: репозиторий не прячет БД, он прячет её отсутствие.
|
||||
- Публичный `tests/smoke.py` сверяет порядок истории с `sorted(key=(created_at, UUID(id).int))`. Любая неоднозначность порядка при равных отметках времени ломает проверку пагинации.
|
||||
- Проверки идут в порядке «идентификация → доступ → содержимое»: посторонний с некорректным телом обязан получить `404`, а не `400`.
|
||||
- Домен лабы 1 беден: три сущности, пять правил. По книге (с. 71) это ровно тот случай, когда весь аппарат не окупается. Он вводится сознательно как учебная цель курса и как задел на лабы 2–7, где за теми же портами встанут PostgreSQL, Redis, S3 и брокер. Цена названа в разделе «Risks».
|
||||
- Это монолит, а не набор служб: один процесс, одна точка входа, один образ. Разделение на доменные зоны — способ удержать границы внутри монолита, а не подготовка к немедленному разъезду по репозиториям.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Правило зависимостей соблюдается механически: `domain/` не импортирует ничего инфраструктурного, `application/` знает только порты, адаптеры подключаются в единственной точке сборки.
|
||||
- Границы доменных зон проверяются тестом по графу импортов, а не держатся на дисциплине.
|
||||
- Порядок истории строго определён при конкурентной записи, без сортировки на чтении.
|
||||
- Замена in-memory адаптеров на адаптеры лаб 2–5 не требует правок в `domain/` и `application/`.
|
||||
- Режим блокировки хранилища и вариант конвейера запроса переключаются конфигурацией — это измерительные инструменты трека «5», а не мёртвый код.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Не вводится ORM, миграции и слой представлений поверх SQL — их нечем наполнить.
|
||||
- Не вводится оптимистическая блокировка по номеру версии: конкурентная запись идёт только в append-only историю, конфликт обновления невозможен.
|
||||
- Не строится обобщённый механизм повторов и dead-letter: события лабы 1 не переживают процесс по условию.
|
||||
- Зоны не разносятся по процессам и образам: это остаётся монолитом, а разделение существует внутри него.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Две доменные зоны и общий минимум
|
||||
|
||||
```
|
||||
src/messenger/
|
||||
main.py сборка приложения: вклады зон в один процесс
|
||||
gunicorn_conf.py конфигурация сервера
|
||||
identity/ domain (ошибки, события, значения, User) / application / infrastructure /
|
||||
entrypoints (роутер, провайдер DI, отображение ошибок, журнал, идентификация)
|
||||
messaging/ domain (ошибки, события, значения, ключ истории, агрегат Chat) /
|
||||
application / infrastructure (память, курсор) / config /
|
||||
entrypoints (роутеры, провайдер DI, отображение ошибок, журнал)
|
||||
shared/ domain / application / infrastructure — платформа без транспорта
|
||||
entrypoints/ — транспортная платформа: конвейер, health, актор запроса,
|
||||
механизм ответа об ошибке, транспортные настройки, платформенный провайдер
|
||||
```
|
||||
|
||||
Отдельного каталога точек входа на верхнем уровне нет: правило «общее — в `shared/`, доменное — в зону» не допускает второго места для общего кода. Транспортная платформа — общее, поэтому живёт в `shared/entrypoints/`. Сборка — ни то ни другое, поэтому лежит в `main.py` в корне пакета.
|
||||
|
||||
Правило простое: **ошибки, события и команды принадлежат зоне**. Общих доменных понятий не существует — в `shared/` лежат только их базовые типы, нужные шине, чтобы уметь их переносить.
|
||||
|
||||
Границы зон взяты по ресурсным корням API: `/api/v1/users` — одна зона, `/api/v1/chats` вместе с историей — другая. Сообщения отдельной зоной не выделены: у них нет жизненного цикла вне чата, это сущность внутри агрегата `Chat`.
|
||||
|
||||
Внутри зоны каталоги повторяют словарь книги («Порты и адаптеры», гл. 13). Порт объявляется в `application/ports.py` своей зоны, адаптеры лежат в её `infrastructure/`. Точка сборки одна — `entrypoints/api/ioc.py`, где каждая зона представлена своим провайдером.
|
||||
|
||||
`shared/` — крайняя мера: туда попадает только платформа (часы, идентификаторы, журнал, брокер) и механизм связи (шина, базовые типы сообщений). Проверка простая: ни один файл в `shared/` не упоминает ни одну зону, и это закреплено тестом.
|
||||
|
||||
Отдельно вынесены из домена коды контракта. Раньше `DomainError` нёс поля `code` и `http_status` — словарь протокола, протёкший в доменный слой. Теперь домен кидает свою ошибку (`UsernameAlreadyTaken`, `ChatNotFound`, `InvalidPageRequest`), а таблица перевода в коды контракта живёт в точке входа. Домен ничего не знает про HTTP, и это тоже проверяется тестом.
|
||||
|
||||
**Альтернатива:** плоский пакет с `routers/`, `services/`, `models/`. Отвергнута: в ней нет места, куда положить порт, и правило зависимостей нечем проверить. **Альтернатива:** отдельная зона для сообщений. Отвергнута: инвариант порядка истории держит агрегат `Chat`, и разрыв границы потребовал бы распределённой согласованности там, где её можно не заводить.
|
||||
|
||||
### Зона владеет всем своим HTTP-слоем
|
||||
|
||||
В `<зона>/entrypoints/` лежит не только роутер, но и провайдер DI, отображение доменных ошибок на коды контракта и журнал событий зоны. У `identity` там же живёт идентификация: разбор заголовка, проверка по справочнику и слоёный middleware.
|
||||
|
||||
В `entrypoints/api/` остаётся только транспортная платформа: конвейер запроса, health, механизм формирования ответа об ошибке, примитив «актор запроса» и сборка приложения. Единственный модуль платформы, знающий обе зоны, — `app.py`, и это его работа: он собирает вклады (роутеры, провайдеры, реестры ошибок, поля журнала) в одно приложение, запускаемое одним процессом.
|
||||
|
||||
Конвейер запроса не знает, кто такой пользователь: он принимает функцию-страж снаружи, а её даёт `identity`. Примитив `Actor` платформенный и опирается на транспортную ошибку `Unauthenticated`, а не на доменную, — «заголовок не предъявлен» это факт транспорта, а не предметной области.
|
||||
|
||||
Проверяется тестом: ни один модуль платформы, кроме `app.py`, не импортирует ни одну зону.
|
||||
|
||||
Изоляция транспорта держится не каталогом верхнего уровня, а слоями внутри `shared/`: ядро (`domain`, `application`, `infrastructure`) не импортирует ни FastAPI, ни Starlette, и это проверяется тестом. В лабе 5 появится второй вход — worker: он подключит ядро `shared/` и не тронет `shared/entrypoints/`, поэтому веб-фреймворк за собой не потащит.
|
||||
|
||||
По той же логике разделены настройки: платформенные (`host`, `port`, `log_level`, предел очереди событий) живут в `shared/config.py`, транспортные (`pipeline`, предел тела, таймаут) — в `shared/entrypoints/config.py`, а `storage_locking` и секрет курсора принадлежат `messaging` и лежат в её `config.py`.
|
||||
|
||||
### Связь зон: событие и проекция, а не вызов
|
||||
|
||||
`messaging` не спрашивает у `identity`, существует ли пользователь. У него есть собственный реестр участников (`MemberRegistry`), который наполняет проекция на событие `UserRegistered`. Единственное, что `messaging` заимствует у соседней зоны, — объявление этого события.
|
||||
|
||||
Проекции выполняются синхронно, до того как клиент получит ответ: иначе «зарегистрировался и сразу создал чат» превратилось бы в гонку, а контракт требует, чтобы подтверждённая запись была видна следующему чтению. Остальные подписчики — журнал активности, внешний брокер — работают через очередь и на ответ не влияют.
|
||||
|
||||
Правило проверяется тестом по графу импортов, а не только договорённостью: `identity` не смеет знать о `messaging` вовсе, `messaging` — только об объявлении события.
|
||||
|
||||
**Альтернатива:** порт `MemberDirectory`, за которым стоит адаптер поверх `identity`. Отвергнута: это скрытый синхронный вызов между зонами, который при разделении на службы превратится в сетевую зависимость. Цена выбранного варианта — дублирование идентификаторов в двух местах; в обмен зоны можно разнести, не переписывая ни строчки домена.
|
||||
|
||||
### Агрегат: чат вместе с историей
|
||||
|
||||
Граница согласованности — `Chat`: состав участников и append-only история. `Message` — сущность внутри агрегата, доступная только через него. `User` — отдельный агрегат.
|
||||
|
||||
Инварианты, которые держит `Chat`: отправитель входит в состав; пара `(created_at, id)` строго возрастает по всей истории; состав неизменен после создания.
|
||||
|
||||
**Альтернатива:** сделать `Message` самостоятельным агрегатом, а членство проверять в обработчике. Отвергнута: инвариант порядка тогда некому держать, и проверка членства расползается по обработчикам. Цена выбранного варианта — агрегат неограниченно растёт; в памяти это дёшево (взятие ссылки, не загрузка), но при переходе на PostgreSQL в лабе 2 репозиторий обязан отдавать агрегат без материализации истории. Это отмечено как точка пересмотра границы.
|
||||
|
||||
### Строго возрастающие часы вместо сортировки на чтении
|
||||
|
||||
Порт `Clock` реализуется адаптером, который выдаёт метки в UTC с микросекундной точностью и гарантирует строгое возрастание: если системные часы вернули значение, не большее предыдущего, выдаётся предыдущее плюс одна микросекунда.
|
||||
|
||||
Следствия: история хранится как append-only список, уже упорядоченный по `(created_at, id)`; keyset-чтение — срез по позиции, найденной двоичным поиском; сортировка на чтении не нужна вовсе.
|
||||
|
||||
**Альтернатива:** брать системное время как есть и вставлять с `bisect.insort` по ключу `(created_at, id)`. Отвергнута: вставка в середину — O(n) на сообщение, а при совпадении меток порядок вставки перестаёт совпадать с порядком чтения, и страница может потерять запись. Цена выбранного варианта — отметка времени может обогнать системные часы на микросекунды при всплеске записи; это фиксируется в отчёте как объявленная семантика (`contracts/README.md` прямо требует её описать).
|
||||
|
||||
### Keyset-курсор: подписанный и привязанный к запросу
|
||||
|
||||
Курсор — base64url от `<версия>.<область>.<время в микросекундах>.<id>` с усечённой подписью HMAC-SHA256. Область — `messages:<chat_id>` либо `chats:<user_id>`. Ключ подписи читается из `CURSOR_SECRET`, а при его отсутствии генерируется случайно на старте процесса.
|
||||
|
||||
Это даёт непрозрачность, обнаружение подделки и привязку к ресурсу одним механизмом: курсор от другого чата не пройдёт проверку области и даст `400`. Случайный ключ по умолчанию означает, что курсоры не переживают перезапуск — ровно как и данные.
|
||||
|
||||
**Альтернатива:** отдавать `created_at` и `id` открытым составным значением. Отвергнута: клиент начнёт на них полагаться, а подделанный курсор придётся отличать от испорченного вручную.
|
||||
|
||||
### Команды, события и две шины
|
||||
|
||||
`CommandBus` направляет команду ровно одному обработчику, ошибка всплывает к вызывающему. `EventBus` рассылает событие всем подписчикам через `asyncio.Queue` с явным пределом; исключение обработчика логируется и не мешает ни ответу клиента, ни остальным подписчикам. События собираются из агрегатов в UoW после фиксации (`.seen` → `collect_new_events`), обработчик команды их не публикует.
|
||||
|
||||
**Альтернатива:** синхронный вызов обработчиков событий прямо в обработчике команды. Отвергнута: скрытая работа удлиняет HTTP-ответ, а отказ уведомления опрокидывает подтверждённую запись.
|
||||
|
||||
### Порт EventPublisher
|
||||
|
||||
`EventPublisher` — порт с единственным адаптером `InMemoryEventPublisher`, который кладёт события в `EventBus`. Внешних сервисов в лабе 1 нет: состояние живёт только в памяти процесса, и брокер был бы таким же нарушением условия, как и база данных.
|
||||
|
||||
Порт при этом сохранён: в лабе 5 за ним встанет брокер, и ни домен, ни обработчики команд об этом не узнают. Это ровно та развязка, ради которой порт и вводится.
|
||||
|
||||
### Сторона чтения в обход агрегата
|
||||
|
||||
Запросы (`GetCurrentUser`, `ListChats`, `ReadHistory`) читают хранилище напрямую через отдельный порт и возвращают плоские структуры. Они не поднимают агрегат и не проходят через репозиторий.
|
||||
|
||||
Это лёгкая форма CQRS (гл. 12): выделен модуль «только для чтения», отдельного хранилища нет. Мотив: чтение истории — срез упорядоченного списка, и тащить ради него агрегат с инвариантами незачем. Цена — две дороги к одним данным; она оправдана тем, что сторона чтения не меняет состояние и её нечем нарушить.
|
||||
|
||||
### Конкурентность: блокировка на агрегат, переключаемая режимом
|
||||
|
||||
Приложение работает одним процессом и одним event loop; несколько воркеров Uvicorn несовместимы с общим состоянием в памяти и запрещены конфигурацией. Атомарность операции обеспечивает UoW, удерживая `asyncio.Lock` на время команды.
|
||||
|
||||
Режим задаётся `STORAGE_LOCKING`:
|
||||
|
||||
- `global` — одна блокировка на всё хранилище; операции разных чатов сериализуются;
|
||||
- `per-chat` — блокировка на агрегат (значение по умолчанию); операции в разных чатах идут параллельно.
|
||||
|
||||
Оба режима — реальные реализации одного порта, и их сравнение образует эксперимент трека «5»: гипотеза в том, что глобальная блокировка становится узким местом при росте конкуренции, а не при росте истории.
|
||||
|
||||
**Альтернатива:** положиться на то, что корутина не прерывается между `await`. Отвергнута: инвариант перестанет держаться при первом же `await` внутри критической секции, а проверка «участник → добавить сообщение» станет гонкой.
|
||||
|
||||
### Порядок проверок в точке входа
|
||||
|
||||
`401` даёт зависимость идентификации, выполняемая до валидации тела; `404` даёт проверка доступа внутри обработчика команды; `400` даёт валидация DTO и доменные ошибки. `RequestValidationError` и ошибка разбора JSON переводятся в `400 invalid_request`; неперехваченное исключение — в `500 internal_error`. Все ответы проходят через middleware, проставляющее `X-Request-Id` и пишущее строку лога без тел запросов.
|
||||
|
||||
### Конвейер запроса: один слой вместо трёх
|
||||
|
||||
Порядок действий над запросом фиксирован: `X-Request-Id` → предел размера тела → идентификация → таймаут обработки → запись в журнал. Идентификация обязана опережать разбор тела, иначе запрос без заголовка и с испорченным JSON получил бы `400` вместо `401`.
|
||||
|
||||
Реализаций две, обе живые и переключаются настройкой `PIPELINE`: `layered` — три `BaseHTTPMiddleware`, `single` — один чистый ASGI-слой. Наблюдаемое поведение API у них совпадает, что закреплено тестом, прогоняющим контрактный сценарий в обоих режимах. Выбор по умолчанию — `single`, и он обоснован измерением, а не вкусом: см. `REPORT.md`.
|
||||
|
||||
### Сервер приложений и единый журнал
|
||||
|
||||
gunicorn с ровно одним `UvicornWorker`. Несколько воркеров означали бы несколько процессов с независимой памятью: два клиента получали бы разные множества данных. Число воркеров поэтому не настройка, а константа конфигурации.
|
||||
|
||||
Логгер в приложении один — structlog за портом `Logger`. Сообщения gunicorn, uvicorn и библиотек перенаправлены в тот же поток и получают тот же формат; access-лог uvicorn заглушён, потому что запись `request.handled` уже содержит те же поля и `request_id`. Поля пишутся по белому списку — это делает утечку текста сообщений невозможной по построению, а не по внимательности автора.
|
||||
|
||||
На каждый запрос действует предел времени: при превышении клиент получает `503`, факт записывается в журнал, остальные запросы не затронуты. Предел gunicorn по времени воркера выставлен выше прикладного, чтобы сначала срабатывал аккуратный ответ, а не убийство процесса.
|
||||
|
||||
### Конфигурация и контейнер
|
||||
|
||||
Настройки читаются из окружения через `pydantic-settings`; значения по умолчанию рассчитаны на запуск без единой переменной. Образ — multi-stage на закреплённом по digest `python:3.14-slim-trixie`, зависимости ставятся из `uv.lock`, рабочий пользователь непривилегированный, `HEALTHCHECK` опрашивает `/health/live`, gunicorn запускается exec-формой и потому получает `SIGTERM` как PID 1; срок корректной остановки — 10 секунд.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **Аппарат паттернов тяжелее домена лабы 1** → цена принята сознательно: ровно те же порты обслуживают лабы 2–7, где адаптеры меняются на PostgreSQL, Redis, S3 и брокер. В отчёте это названо прямо, а не выдано за необходимость.
|
||||
- **Реестр участников дублирует идентификаторы пользователей** → это осознанная цена разделения зон: расхождение возможно только если событие потеряно, а проекции выполняются синхронно и потому теряться не могут, пока процесс один. При переходе к нескольким процессам сюда понадобится надёжная доставка.
|
||||
- **Две реализации конвейера запроса в кодовой базе** → вторая существует как контрольная серия эксперимента и покрыта тем же контрактным тестом; если эксперимент больше не нужен, слоёная реализация удаляется одним файлом.
|
||||
- **Агрегат `Chat` растёт неограниченно** → в памяти это ссылка, а не загрузка; при переходе на БД граница агрегата пересматривается, и это зафиксировано как точка пересмотра, а не скрытый долг.
|
||||
- **Строго возрастающие часы могут обогнать системное время при всплеске записи** → расхождение ограничено микросекундами на сообщение и описано в отчёте как объявленная семантика.
|
||||
- **Один процесс и одно состояние** → горизонтального масштабирования нет и не может быть; несколько воркеров Uvicorn дали бы разные множества данных, поэтому запрещены конфигурацией и проверяются тестом.
|
||||
- **Событие, потерянное при переполнении очереди, не восстанавливается** → предел очереди явный, отбрасывание логируется; долговечность доставки появится вместе с брокером в лабе 5.
|
||||
- **Курсоры и данные не переживают перезапуск** → это требование лабы, а не дефект; демонстрируется в сценарии защиты.
|
||||
- **Измерения снимаются на одной машине, клиент и сервер делят ресурсы** → закрытый контур даёт согласованные пропуски; в отчёте указано, что измерение сравнивает две реализации между собой, а не устанавливает абсолютную пропускную способность.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Миграции данных нет: приложение создаётся впервые, состояние пустое по определению. Откат — возврат к предыдущему образу; потеря данных при откате ожидаема и не требует отдельной процедуры.
|
||||
|
||||
Порядок выката: собрать образ из чистого clone → запустить контейнер с публикацией порта → дождаться `healthy` → прогнать `make test` → снять измерения трека «5» → заполнить `REPORT.md`.
|
||||
@@ -0,0 +1,38 @@
|
||||
## Why
|
||||
|
||||
В репозитории есть контракт и публичные проверки, но нет приложения: `make test` падает на отказе соединения. Лабораторная 1 закрывается только работающим сервисом, поэтому нужно превратить `contracts/openapi.json` в процесс и воспроизводимый контейнер. Целевая оценка — «5»: весь уровень 4 плюс завершённый трек 1 «Предел in-memory архитектуры».
|
||||
|
||||
## What Changes
|
||||
|
||||
- Появляется приложение в `src/messenger/`: обязательный API лабы 1, состояние только в памяти одного процесса, идентификация по `X-User-Id`.
|
||||
- Две доменные зоны монолита: `identity/` (пользователи) и `messaging/` (чаты и история). У каждой свои ошибки, события, команды, объекты-значения, хранилище и HTTP-фасад. В `shared/` остаются только платформа и механизм связи: базовые типы ошибки, события и команды, технические порты и шина. Коды контракта и HTTP-статусы живут в точке входа. Точка входа одна — `entrypoints/api/`.
|
||||
- Зоны не вызывают друг друга: `messaging` ведёт собственный реестр участников, наполняемый проекцией на событие `UserRegistered` зоны `identity`. Команда имеет ровно одного обработчика, событие — сколько угодно; проекции выполняются до подтверждения записи, прочие обработчики — через `asyncio.Queue`.
|
||||
- Порт `EventPublisher` с единственным адаптером — внутренней очередью в памяти. Внешних сервисов в лабе 1 нет; порт остаётся точкой расширения для лабы 5.
|
||||
- Сервер — gunicorn с одним `UvicornWorker` (несколько воркеров несовместимы с состоянием в памяти); его логи идут через тот же структурный логгер, что и логи приложения. На каждый запрос действует таймаут с предсказуемым `503`.
|
||||
- Уровень «4»: собственные тесты одной командой, конкурентный тест 100 сообщений от 10 клиентов, non-root контейнер с закреплёнными версиями, SIGTERM ≤10 с, healthcheck, логи без текста сообщений.
|
||||
- Трек «5»: повторяемый эксперимент 3 размера истории × 3 уровня конкуренции, замеры throughput / p95 / p99 / RSS; проверены две гипотезы об узком месте, сравнение «до/после» приложено для каждой.
|
||||
- Заполняются `REPORT.md` и `evidence/`; в `Makefile` добавляются цели запуска, тестов и измерений, существующие цели не меняются.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab1-messenger-identity`: регистрация пользователя, уникальность `username`, идентификация запроса по `X-User-Id` и её отказы.
|
||||
- `lab1-messenger-chats`: создание чата с явным списком участников, членство как граница доступа, список чатов с keyset-пагинацией.
|
||||
- `lab1-messenger-history`: отправка сообщения с выводом отправителя из идентификации, порядок `(created_at, id)`, keyset-курсор, привязанный к чату.
|
||||
- `lab1-service-operability`: health-пробы, `X-Request-Id`, единый формат ошибки, таймаут запроса, поведение при SIGTERM, единый журнал всех сообщений процесса, контейнерная поставка.
|
||||
- `lab1-event-publication`: регистрация доменных событий, доставка проекциям и подписчикам внутренней шиной, изоляция доменных зон друг от друга.
|
||||
- `lab1-inmemory-capacity`: наблюдаемый предел in-memory хранения — что измеряется, при каких условиях и что считается подтверждённым улучшением.
|
||||
|
||||
### Modified Capabilities
|
||||
<!-- нет: спеки создаются впервые -->
|
||||
|
||||
## Impact
|
||||
|
||||
- Новое: `src/messenger/{shared,identity,messaging,entrypoints}/**`, `student-tests/**`, `pyproject.toml`, `uv.lock`, `Dockerfile`, `scripts/bench.py`.
|
||||
- Правится: `REPORT.md`, `evidence/**`, `Makefile` (только новые цели), `.gitignore`.
|
||||
- Зависимости: `fastapi`, `uvicorn`, `gunicorn`, `pydantic`, `pydantic-settings`, `dishka`, `structlog`, `pytest`, `pytest-asyncio`, `ruff`, `ty`.
|
||||
- Не затрагиваются: `contracts/**`, `tests/**`, `README.md`, `COURSE.md`, `CONTRIBUTING.md` — контракт и публичные проверки остаются как есть.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Из Out of scope не появляется ничего: PostgreSQL, Redis и файлы состояния на пути данных, Bearer-сессии и пароли (лаба 2), несколько реплик, балансировщик и `Idempotency-Key` (лаба 3), вложения и S3 (лаба 4), worker и обработка изображений (лаба 5), OTel и Grafana (лаба 6), TLS и Argon2id (лаба 7). Web UI, WebSocket, редактирование и удаление сообщений, изменение состава участников и поиск пользователей не реализуются.
|
||||
+102
@@ -0,0 +1,102 @@
|
||||
## Purpose
|
||||
|
||||
Определяет, как зоны предметной области узнают о произошедшем, не вызывая друг друга напрямую: модель регистрирует факт, шина разводит его по обработчикам. Транспорт доставки заменяем, и его отказ не влияет на обязательный путь данных.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Побочные эффекты выполняются через события
|
||||
|
||||
Побочная работа, не входящая в границу согласованности операции, SHALL выполняться обработчиками событий, а не внутри обработчика команды. Событие SHALL регистрироваться моделью как факт о произошедшем и SHALL публиковаться только после успешного завершения операции, породившей его.
|
||||
|
||||
#### Scenario: Успешная операция порождает событие
|
||||
|
||||
- **WHEN** сообщение успешно сохранено и клиент получил `201`
|
||||
- **THEN** зарегистрировано событие об отправке сообщения, доступное обработчикам
|
||||
|
||||
#### Scenario: Отклонённая операция событий не порождает
|
||||
|
||||
- **WHEN** отправка сообщения отклонена с `400` или `404`
|
||||
- **THEN** ни одно событие об отправке не публикуется
|
||||
|
||||
#### Scenario: Событие получают все подписчики
|
||||
|
||||
- **WHEN** на один тип события подписано несколько обработчиков
|
||||
- **THEN** событие доставляется каждому из них
|
||||
|
||||
### Requirement: Отказ обработчика события не влияет на ответ клиента
|
||||
|
||||
Исключение в обработчике события SHALL быть залогировано и SHALL NOT менять код ответа уже подтверждённой операции. Отказ одного обработчика SHALL NOT мешать остальным обработчикам того же события.
|
||||
|
||||
#### Scenario: Обработчик падает после подтверждения
|
||||
|
||||
- **WHEN** обработчик события завершается исключением после того, как клиент получил `201`
|
||||
- **THEN** ответ клиента остаётся `201`
|
||||
- **AND** факт отказа виден в логах с идентификатором запроса
|
||||
|
||||
#### Scenario: Один обработчик не блокирует остальные
|
||||
|
||||
- **WHEN** первый из двух обработчиков события завершается исключением
|
||||
- **THEN** второй обработчик всё равно вызывается
|
||||
|
||||
### Requirement: Публикация событий не удлиняет обязательный путь
|
||||
|
||||
Доставка событий обработчикам SHALL быть развязана с обработкой HTTP-запроса: публикация SHALL завершаться, не дожидаясь работы обработчиков. Очередь публикации SHALL иметь явный предел; при его достижении событие SHALL отбрасываться с записью в лог, а обязательный путь данных SHALL продолжать работать.
|
||||
|
||||
#### Scenario: Ответ не ждёт обработчиков
|
||||
|
||||
- **WHEN** обработчик события выполняется заметно дольше, чем обработка запроса
|
||||
- **THEN** клиент получает ответ, не дожидаясь завершения обработчика
|
||||
|
||||
#### Scenario: Очередь переполнена
|
||||
|
||||
- **WHEN** события публикуются быстрее, чем разбираются, и очередь достигла предела
|
||||
- **THEN** новые события отбрасываются с записью в лог
|
||||
- **AND** запись сообщений продолжает подтверждаться кодом `201`
|
||||
|
||||
### Requirement: Доставка событий не требует внешних сервисов
|
||||
|
||||
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Сервис SHALL NOT зависеть от внешнего брокера, базы данных или иного сетевого сервиса для работы обязательного API.
|
||||
|
||||
#### Scenario: Сервис работает без единого внешнего сервиса
|
||||
|
||||
- **WHEN** сервис запущен и ни один внешний сервис не поднят
|
||||
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
|
||||
|
||||
#### Scenario: Публикация скрыта за портом
|
||||
|
||||
- **WHEN** проверяется слой приложения
|
||||
- **THEN** он обращается к публикации только через порт и не знает её реализации
|
||||
|
||||
### Requirement: Опубликованное событие не раскрывает содержимого сообщений
|
||||
|
||||
Полезная нагрузка события SHALL содержать только идентификаторы и метаданные. Текст сообщений, `display_name` и любые пользовательские данные SHALL NOT попадать ни в тело события, ни в журнал.
|
||||
|
||||
#### Scenario: Событие об отправке сообщения без текста
|
||||
|
||||
- **WHEN** опубликовано событие об отправке сообщения
|
||||
- **THEN** его тело содержит идентификаторы сообщения, чата и отправителя и отметку времени
|
||||
- **AND** не содержит текста сообщения
|
||||
|
||||
### Requirement: Доменные зоны связаны только событиями
|
||||
|
||||
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» напрямую. Сведения о существующих участниках SHALL поддерживаться собственной проекцией зоны, наполняемой событием о регистрации пользователя. Проекция SHALL обновляться до того, как клиент получит подтверждение операции, породившей событие.
|
||||
|
||||
#### Scenario: Регистрация видна чатам сразу
|
||||
|
||||
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
|
||||
- **THEN** чат создаётся успешно, потому что проекция участников уже знает этот идентификатор
|
||||
|
||||
#### Scenario: Неизвестный зоне участник отклоняется
|
||||
|
||||
- **WHEN** в состав чата передан идентификатор, о регистрации которого зона не получала события
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Зона пользователей не знает о чатах
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
|
||||
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
|
||||
|
||||
#### Scenario: Обратная связь идёт только через контракт события
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
|
||||
- **THEN** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации
|
||||
+60
@@ -0,0 +1,60 @@
|
||||
## Purpose
|
||||
|
||||
Определяет трек «5» — предел in-memory архитектуры: что измеряется, при каких условиях измерение считается повторяемым и что считается подтверждённым улучшением, а что остаётся гипотезой.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Повторяемая методика измерения
|
||||
|
||||
Эксперимент SHALL выполняться одной командой и SHALL покрывать не менее трёх размеров истории и не менее трёх уровней конкуренции. Каждый прогон SHALL фиксировать длительность, прогрев, уровень конкуренции, размер набора данных, успешные RPS, долю ошибок, p50/p95/p99 задержки и RSS процесса. Результаты SHALL сохраняться машиночитаемым файлом без учётных данных и пользовательских данных.
|
||||
|
||||
#### Scenario: Матрица прогонов выполнена
|
||||
|
||||
- **WHEN** запущен сценарий измерения предела in-memory
|
||||
- **THEN** выполняются прогоны для всех сочетаний трёх размеров истории и трёх уровней конкуренции
|
||||
- **AND** результат каждого прогона содержит успешные RPS, p50/p95/p99, долю ошибок и RSS
|
||||
|
||||
#### Scenario: Прогон воспроизводим
|
||||
|
||||
- **WHEN** сценарий запущен повторно с теми же параметрами и теми же ресурсными лимитами
|
||||
- **THEN** сохранённый отчёт содержит версии runtime и образа, лимиты CPU и памяти, длительность и прогрев, позволяющие повторить измерение
|
||||
|
||||
#### Scenario: Отчёт не содержит чувствительных данных
|
||||
|
||||
- **WHEN** сохранён файл результатов
|
||||
- **THEN** он не содержит текстов сообщений, учётных данных и идентификаторов реальных людей
|
||||
|
||||
### Requirement: Наблюдаемый предел хранения в памяти
|
||||
|
||||
Сервис SHALL позволять измерить стоимость хранения одного сообщения в памяти. Эксперимент SHALL показать зависимость RSS от размера истории и SHALL давать оценку числа сообщений, при котором процесс исчерпает заданный лимит памяти.
|
||||
|
||||
#### Scenario: Рост RSS измерен
|
||||
|
||||
- **WHEN** история чата последовательно доводится до трёх заданных размеров
|
||||
- **THEN** для каждого размера зафиксирован RSS процесса
|
||||
- **AND** из измерений выводится средняя стоимость одного сообщения в байтах
|
||||
|
||||
#### Scenario: Предел объяснён
|
||||
|
||||
- **WHEN** известны стоимость сообщения и лимит памяти контейнера
|
||||
- **THEN** отчёт приводит оценку предельного числа сообщений и называет допущения этой оценки
|
||||
|
||||
### Requirement: Узкое место названо и подтверждено изменением
|
||||
|
||||
Отчёт SHALL называть узкое место, выявленное измерениями, и SHALL описывать ровно одно внесённое изменение, направленное на него. Сравнение «до» и «после» SHALL выполняться при одинаковых ресурсных лимитах, одинаковом профиле нагрузки и одинаковом размере набора данных. Улучшение SHALL считаться подтверждённым только при наблюдаемом изменении метрик; необоснованные измерениями выводы SHALL быть помечены как гипотезы.
|
||||
|
||||
#### Scenario: Сравнение до и после
|
||||
|
||||
- **WHEN** режим работы переключён на изменённую реализацию и прогон повторён с теми же параметрами
|
||||
- **THEN** отчёт содержит обе серии измерений и разницу по throughput и p95/p99
|
||||
|
||||
#### Scenario: Улучшение не подтвердилось
|
||||
|
||||
- **WHEN** после изменения метрики не улучшились или ухудшились
|
||||
- **THEN** отчёт фиксирует это как наблюдение, а не как успех
|
||||
- **AND** объясняет, какое допущение гипотезы не подтвердилось
|
||||
|
||||
#### Scenario: Границы эксперимента названы
|
||||
|
||||
- **WHEN** сформулирован вывод об узком месте
|
||||
- **THEN** отчёт называет, что измерение не доказывает: закрытый контур создаёт согласованные пропуски, клиент и сервер делят одну машину, единственный процесс не даёт отказоустойчивости
|
||||
+85
@@ -0,0 +1,85 @@
|
||||
## Purpose
|
||||
|
||||
Определяет чат как границу доступа: кто попадает в состав участников, кто видит чат в списке и что происходит с посторонним. Состав участников задаётся при создании и в обязательном API лабы 1 не меняется.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Создание чата
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats` от идентифицированного пользователя с телом `{"title":..., "member_ids":[...]}` и возвращать `201` с объектом `Chat`. `title` SHALL содержать от 1 до 100 code points и не состоять только из пробельных символов. `member_ids` SHALL содержать от 1 до 100 уникальных идентификаторов существующих пользователей и SHALL включать вызывающего. Чат SHALL создаваться атомарно: при любой ошибке валидации он не создаётся вовсе.
|
||||
|
||||
#### Scenario: Чат создан
|
||||
|
||||
- **WHEN** участник отправляет `POST /api/v1/chats` с корректным `title` и списком из своего и чужого идентификаторов
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Chat`, `member_ids` совпадает с запрошенным составом
|
||||
- **AND** `id` и `created_at` назначены сервером
|
||||
|
||||
#### Scenario: Вызывающий не входит в состав
|
||||
|
||||
- **WHEN** `member_ids` не содержит идентификатора вызывающего
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит дубликаты
|
||||
|
||||
- **WHEN** `member_ids` содержит один и тот же идентификатор дважды
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит неизвестного пользователя
|
||||
|
||||
- **WHEN** `member_ids` содержит идентификатор, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** чат не создаётся
|
||||
|
||||
#### Scenario: Запрос без идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/chats` приходит без действительного `X-User-Id`
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
### Requirement: Членство как граница доступа
|
||||
|
||||
Чат SHALL быть доступен только своим участникам. Посторонний пользователь SHALL получать `404` с кодом `not_found` — тот же ответ, что и для несуществующего чата. Сервис SHALL NOT использовать `403` и SHALL NOT раскрывать факт существования чужого чата ни кодом ответа, ни текстом сообщения.
|
||||
|
||||
#### Scenario: Участник читает чат
|
||||
|
||||
- **WHEN** участник запрашивает `GET /api/v1/chats/{chat_id}` своего чата
|
||||
- **THEN** ответ `200` с объектом `Chat`
|
||||
|
||||
#### Scenario: Посторонний читает чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats/{chat_id}`
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
|
||||
#### Scenario: Запрос несуществующего чата
|
||||
|
||||
- **WHEN** запрашивается `GET /api/v1/chats/{chat_id}` с UUID, которому не соответствует ни один чат
|
||||
- **THEN** ответ `404` с кодом `not_found`, неотличимый от ответа на чужой чат
|
||||
|
||||
#### Scenario: Идентификатор чата не является UUID
|
||||
|
||||
- **WHEN** `chat_id` в пути не является UUID
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
### Requirement: Список чатов пользователя
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/chats` страницу `{"items":[...],"next_cursor":...}` с чатами, в которых состоит вызывающий, упорядоченными по `(created_at, id)` по возрастанию. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. Список SHALL NOT содержать чатов, недоступных вызывающему.
|
||||
|
||||
#### Scenario: Участник видит свой чат
|
||||
|
||||
- **WHEN** участник запрашивает `GET /api/v1/chats?limit=100`
|
||||
- **THEN** ответ `200`, и его чат присутствует в `items`
|
||||
|
||||
#### Scenario: Посторонний не видит чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats?limit=100`
|
||||
- **THEN** ответ `200`, и этого чата в `items` нет
|
||||
|
||||
#### Scenario: Limit вне допустимого диапазона
|
||||
|
||||
- **WHEN** запрос содержит `limit=0`, `limit=101` или нечисловое значение
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Обход списка курсором
|
||||
|
||||
- **WHEN** пользователь состоит в нескольких чатах и запрашивает страницы по одному элементу, передавая `next_cursor` предыдущей страницы
|
||||
- **THEN** страницы идут в порядке `(created_at, id)` по возрастанию, ни один чат не повторяется и не пропускается
|
||||
- **AND** `next_cursor` последней страницы равен `null`
|
||||
+106
@@ -0,0 +1,106 @@
|
||||
## Purpose
|
||||
|
||||
Определяет отправку сообщений и чтение истории чата: кто считается отправителем, в каком порядке лежат сообщения и какие гарантии даёт keyset-курсор при обходе истории.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером.
|
||||
|
||||
#### Scenario: Сообщение отправлено
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Message`
|
||||
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
|
||||
|
||||
#### Scenario: Отправитель не берётся из тела запроса
|
||||
|
||||
- **WHEN** тело запроса содержит поле `sender_id`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустой или пробельный текст
|
||||
|
||||
- **WHEN** тело содержит `{"text":""}` или `{"text":" "}`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Текст длиннее предела
|
||||
|
||||
- **WHEN** `text` содержит более 4000 Unicode code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** длина считается в code points, а не в байтах UTF-8
|
||||
|
||||
#### Scenario: Посторонний пишет в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
- **AND** сообщение не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат тело, нарушающее схему
|
||||
- **THEN** ответ `404`, а не `400`
|
||||
|
||||
### Requirement: Порядок истории
|
||||
|
||||
История чата SHALL быть упорядочена по паре `(created_at, id)` по возрастанию. Время SHALL назначаться сервером в формате RFC 3339 UTC с суффиксом `Z`. Сервис SHALL гарантировать, что пара `(created_at, id)` строго возрастает для последовательно принятых сообщений, в том числе при конкурентных вставках, — иначе обход истории теряет или дублирует записи.
|
||||
|
||||
#### Scenario: Сообщения возвращаются в порядке приёма
|
||||
|
||||
- **WHEN** в чат последовательно отправлены два сообщения от разных участников
|
||||
- **THEN** `GET /api/v1/chats/{chat_id}/messages` возвращает их в порядке отправки
|
||||
|
||||
#### Scenario: Конкурентная запись не ломает порядок
|
||||
|
||||
- **WHEN** 10 клиентов параллельно отправляют по 10 сообщений в один чат
|
||||
- **THEN** история содержит ровно 100 сообщений с попарно различными `id`
|
||||
- **AND** порядок `(created_at, id)` строго возрастает по всей истории
|
||||
|
||||
### Requirement: Чтение истории keyset-курсором
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами.
|
||||
|
||||
#### Scenario: Первая страница отдаёт курсор
|
||||
|
||||
- **WHEN** в чате два сообщения и запрошено `?limit=1`
|
||||
- **THEN** ответ содержит один элемент и непустой `next_cursor`
|
||||
|
||||
#### Scenario: Последняя страница закрывает историю
|
||||
|
||||
- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1`
|
||||
- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null`
|
||||
- **AND** элемент первой страницы не повторяется
|
||||
|
||||
#### Scenario: Курсор не привязан к читателю
|
||||
|
||||
- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата
|
||||
- **THEN** страница отдаётся на общих основаниях
|
||||
|
||||
#### Scenario: Курсор от другого чата
|
||||
|
||||
- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Испорченный или подделанный курсор
|
||||
|
||||
- **WHEN** значение `cursor` не является ранее выданным сервером курсором
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Limit вне допустимого диапазона
|
||||
|
||||
- **WHEN** запрос содержит `limit=0` или `limit=101`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Посторонний читает чужую историю
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
|
||||
### Requirement: Подтверждённое сообщение видно следующему чтению
|
||||
|
||||
Сообщение, на которое выдан ответ `201`, SHALL быть видно любому последующему чтению истории этого чата. Кэширование допускается, но SHALL NOT возвращать историю, устаревшую относительно успешной записи.
|
||||
|
||||
#### Scenario: Запись видна сразу после подтверждения
|
||||
|
||||
- **WHEN** участник получил `201` на отправку сообщения и немедленно читает историю
|
||||
- **THEN** отправленное сообщение присутствует в ответе
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
## Purpose
|
||||
|
||||
Определяет, как пользователь появляется в системе и как сервер узнаёт, от чьего имени пришёл запрос. В лабе 1 идентификация учебная и никого не аутентифицирует: любой клиент может выдать себя за другого, предъявив чужой идентификатор.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Регистрация пользователя
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/users` без идентификации и возвращать `201` с объектом `User`, содержащим назначенные сервером `id` и `created_at`. Тело запроса SHALL содержать ровно поля `username` и `display_name`. `username` SHALL соответствовать `^[a-z0-9_]{3,32}$` и быть уникальным, `display_name` SHALL содержать от 1 до 100 Unicode code points и не состоять только из пробельных символов. Ответ SHALL NOT содержать полей, отсутствующих в схеме `User`.
|
||||
|
||||
#### Scenario: Пользователь создан
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с телом `{"username":"alice_01","display_name":"Алиса"}`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `User`, `username` и `display_name` совпадают с запросом
|
||||
- **AND** `id` — UUID, назначенный сервером, `created_at` — RFC 3339 UTC с суффиксом `Z`
|
||||
|
||||
#### Scenario: Username занят
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с `username`, уже принадлежащим другому пользователю
|
||||
- **THEN** ответ `409` с телом ошибки и кодом `conflict`
|
||||
|
||||
#### Scenario: Username нарушает формат
|
||||
|
||||
- **WHEN** `username` содержит заглавные буквы, дефис, пробел или имеет длину вне 3–32 символов
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Display_name пуст или состоит из пробелов
|
||||
|
||||
- **WHEN** `display_name` равен `""`, `" "` или длиннее 100 code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Тело запроса нарушает схему
|
||||
|
||||
- **WHEN** тело содержит лишнее поле, неверный тип поля, не содержит обязательного поля или не является корректным JSON
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** сообщение ошибки не содержит stack trace и внутренних деталей реализации
|
||||
|
||||
#### Scenario: Регистрация не требует идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/users` приходит без заголовка `X-User-Id`
|
||||
- **THEN** запрос обрабатывается на общих основаниях, ответ не равен `401`
|
||||
|
||||
### Requirement: Идентификация запроса заголовком X-User-Id
|
||||
|
||||
Защищённые endpoint SHALL требовать заголовок `X-User-Id` со значением идентификатора существующего пользователя. Отсутствующий, синтаксически неверный и неизвестный идентификатор SHALL приводить к `401` с кодом `unauthorized`. Проверка идентификации SHALL выполняться до проверки доступа к конкретному ресурсу и до содержательной проверки тела запроса.
|
||||
|
||||
#### Scenario: Заголовок отсутствует
|
||||
|
||||
- **WHEN** приходит `GET /api/v1/users/me` без `X-User-Id`
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
#### Scenario: Идентификатор неизвестен системе
|
||||
|
||||
- **WHEN** `X-User-Id` содержит синтаксически корректный UUID, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
- **AND** ответ не сообщает, существовал ли такой пользователь когда-либо
|
||||
|
||||
#### Scenario: Идентификатор не является UUID
|
||||
|
||||
- **WHEN** `X-User-Id` содержит произвольную строку, пустое значение или несколько значений
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
#### Scenario: Идентификация проверяется раньше тела запроса
|
||||
|
||||
- **WHEN** приходит запрос без `X-User-Id` и с телом, нарушающим схему
|
||||
- **THEN** ответ `401`, а не `400`
|
||||
|
||||
### Requirement: Чтение текущего пользователя
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/users/me` объект `User`, соответствующий предъявленной идентификации, в том же виде, в каком он был возвращён при регистрации.
|
||||
|
||||
#### Scenario: Текущий пользователь возвращён
|
||||
|
||||
- **WHEN** приходит `GET /api/v1/users/me` с `X-User-Id` существующего пользователя
|
||||
- **THEN** ответ `200`, тело соответствует схеме `User` и совпадает с телом ответа его регистрации
|
||||
|
||||
### Requirement: Состояние пользователей не переживает перезапуск
|
||||
|
||||
Список пользователей SHALL храниться только в памяти процесса. После перезапуска процесса ранее выданные идентификаторы SHALL перестать быть действительными.
|
||||
|
||||
#### Scenario: Идентификатор после перезапуска недействителен
|
||||
|
||||
- **WHEN** процесс перезапущен и приходит запрос с `X-User-Id`, выданным до перезапуска
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
+164
@@ -0,0 +1,164 @@
|
||||
## Purpose
|
||||
|
||||
Определяет наблюдаемое поведение сервиса как эксплуатируемого процесса: пробы жизни и готовности, сквозной идентификатор запроса, единый формат ошибок, реакция на сигнал остановки и требования к контейнерной поставке.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Пробы жизни и готовности
|
||||
|
||||
Сервис SHALL отвечать на `GET /health/live` кодом `200` с телом `{"status":"ok"}`, проверяя только жизнь процесса. Сервис SHALL отвечать на `GET /health/ready` кодом `200` с тем же телом, если он способен обслуживать обязательный синхронный путь, и кодом `503` с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать идентификации. Недоступность опциональных зависимостей SHALL NOT переводить готовность в `503`.
|
||||
|
||||
#### Scenario: Проба жизни отвечает без идентификации
|
||||
|
||||
- **WHEN** приходит `GET /health/live` без заголовков идентификации
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность подтверждена
|
||||
|
||||
- **WHEN** приходит `GET /health/ready` на полностью запущенном процессе
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность не зависит от внешних сервисов
|
||||
|
||||
- **WHEN** проверяется готовность сервиса
|
||||
- **THEN** она определяется только состоянием самого процесса, поскольку внешних зависимостей нет
|
||||
|
||||
#### Scenario: Сервис остановлен
|
||||
|
||||
- **WHEN** процесс получил сигнал остановки и перестал принимать новую работу
|
||||
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable` либо соединение не устанавливается
|
||||
|
||||
### Requirement: Сквозной идентификатор запроса
|
||||
|
||||
Каждый ответ сервиса, включая ответы проб и ответы об ошибках, SHALL содержать непустой заголовок `X-Request-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое.
|
||||
|
||||
#### Scenario: Идентификатор присутствует в любом ответе
|
||||
|
||||
- **WHEN** выполняется любой запрос к сервису, успешный или ошибочный
|
||||
- **THEN** ответ содержит непустой `X-Request-Id`
|
||||
|
||||
#### Scenario: Клиентский идентификатор сохраняется
|
||||
|
||||
- **WHEN** запрос содержит `X-Request-Id` с непустым значением
|
||||
- **THEN** ответ содержит то же значение
|
||||
|
||||
### Requirement: Единый формат ошибки
|
||||
|
||||
Ответ с кодом `4xx` или `5xx` SHALL иметь `Content-Type: application/json` и тело `{"error":{"code":...,"message":...,"request_id":...}}` без каких-либо дополнительных полей. `code` SHALL принимать значение из перечисления контракта, `request_id` SHALL совпадать со значением заголовка `X-Request-Id`. `message` SHALL быть непустым и SHALL NOT содержать stack trace, SQL, учётных данных, внутренних путей и сведений о существовании чужих объектов.
|
||||
|
||||
#### Scenario: Тело ошибки соответствует схеме
|
||||
|
||||
- **WHEN** запрос завершается ошибкой любого класса
|
||||
- **THEN** тело ответа соответствует схеме `Error` контракта
|
||||
- **AND** `request_id` в теле совпадает с заголовком `X-Request-Id`
|
||||
|
||||
#### Scenario: Необработанное исключение
|
||||
|
||||
- **WHEN** обработка запроса завершается непредвиденным исключением
|
||||
- **THEN** ответ `500` с кодом `internal_error` и телом в общем формате
|
||||
- **AND** тело не раскрывает внутренних деталей
|
||||
|
||||
#### Scenario: Неподдерживаемый метод или несуществующий путь
|
||||
|
||||
- **WHEN** запрашивается несуществующий путь или неподдерживаемый метод существующего пути
|
||||
- **THEN** ответ имеет тело в общем формате ошибки с непустым `X-Request-Id`
|
||||
|
||||
### Requirement: Корректное завершение по сигналу
|
||||
|
||||
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
|
||||
|
||||
#### Scenario: Остановка укладывается в срок
|
||||
|
||||
- **WHEN** запущенному контейнеру послан `SIGTERM`
|
||||
- **THEN** процесс завершается не позднее чем через 10 секунд
|
||||
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
|
||||
|
||||
#### Scenario: Принятый запрос дорабатывается
|
||||
|
||||
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
|
||||
- **THEN** этот запрос получает ответ до завершения процесса
|
||||
|
||||
### Requirement: Логи без содержимого сообщений
|
||||
|
||||
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и `X-Request-Id`. Логи SHALL NOT содержать текста сообщений, `display_name`, значений заголовков идентификации и тел запросов.
|
||||
|
||||
#### Scenario: Запись о запросе присутствует
|
||||
|
||||
- **WHEN** обработан любой запрос к API
|
||||
- **THEN** в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
|
||||
|
||||
#### Scenario: Текст сообщения не попадает в логи
|
||||
|
||||
- **WHEN** отправлено сообщение с известным текстом-маркером
|
||||
- **THEN** этот текст отсутствует в stdout и stderr процесса
|
||||
|
||||
### Requirement: Контейнерная поставка
|
||||
|
||||
Сервис SHALL собираться из исходников в образ, слушать `0.0.0.0:8080` и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
|
||||
|
||||
#### Scenario: Образ собирается из чистого clone
|
||||
|
||||
- **WHEN** выполняется сборка образа в свежей копии репозитория
|
||||
- **THEN** сборка завершается успешно без обращения к артефактам вне репозитория
|
||||
|
||||
#### Scenario: API доступен на опубликованном порту
|
||||
|
||||
- **WHEN** контейнер запущен с публикацией порта 8080
|
||||
- **THEN** `GET /health/ready` с хоста отвечает `200`
|
||||
|
||||
#### Scenario: Процесс работает не от root
|
||||
|
||||
- **WHEN** в работающем контейнере проверяется эффективный пользователь процесса сервера
|
||||
- **THEN** это не `root`, и идентификатор пользователя не равен 0
|
||||
|
||||
#### Scenario: Healthcheck отражает состояние сервиса
|
||||
|
||||
- **WHEN** контейнер запущен и сервис готов
|
||||
- **THEN** статус healthcheck контейнера становится `healthy`
|
||||
|
||||
### Requirement: Состояние живёт только в памяти процесса
|
||||
|
||||
Сервис SHALL хранить пользователей, чаты и сообщения только в памяти своего процесса. Сервис SHALL NOT использовать внешние СУБД, кэши и файлы состояния на обязательном пути данных. После перезапуска процесса всё состояние SHALL быть пустым.
|
||||
|
||||
#### Scenario: Данные исчезают после перезапуска
|
||||
|
||||
- **WHEN** созданы пользователь, чат и сообщение, после чего контейнер перезапущен тем же образом
|
||||
- **THEN** прежний идентификатор пользователя получает `401`, а созданные чат и сообщение недоступны
|
||||
|
||||
#### Scenario: Нет записи состояния на диск
|
||||
|
||||
- **WHEN** сервис обработал запись пользователей, чатов и сообщений
|
||||
- **THEN** в файловой системе контейнера не появляется файлов с этим состоянием
|
||||
|
||||
### Requirement: Предел времени обработки запроса
|
||||
|
||||
Обработка запроса SHALL ограничиваться настраиваемым пределом времени. При его превышении сервис SHALL отвечать `503` с кодом `unavailable`, если ответ ещё не начал отправляться, и SHALL записывать факт превышения в журнал. Превышение предела одним запросом SHALL NOT влиять на последующие запросы и на готовность сервиса.
|
||||
|
||||
#### Scenario: Запрос превысил предел
|
||||
|
||||
- **WHEN** обработка запроса длится дольше установленного предела
|
||||
- **THEN** ответ `503` с кодом `unavailable` и телом в общем формате ошибки
|
||||
|
||||
#### Scenario: Сервис продолжает работать после превышения
|
||||
|
||||
- **WHEN** после превышения предела приходит обычный запрос
|
||||
- **THEN** он обрабатывается штатно, а `GET /health/ready` отвечает `200`
|
||||
|
||||
#### Scenario: Запись о превышении не раскрывает содержимого
|
||||
|
||||
- **WHEN** запрос с известным текстом-маркером превысил предел
|
||||
- **THEN** в журнале появляется запись о превышении, и этот текст в ней отсутствует
|
||||
|
||||
### Requirement: Единый журнал всех сообщений процесса
|
||||
|
||||
Сервис SHALL выводить в stdout единый поток структурированных записей. Сообщения сервера приложений и используемых библиотек SHALL проходить через тот же журнал и иметь тот же формат, что и сообщения приложения. Записи SHALL содержать только поля из объявленного перечня; поля вне перечня SHALL отбрасываться.
|
||||
|
||||
#### Scenario: Сообщения сервера приложений в общем формате
|
||||
|
||||
- **WHEN** процесс запускается и печатает сообщения о старте сервера
|
||||
- **THEN** каждая строка stdout разбирается как структурированная запись того же формата, что и записи приложения
|
||||
|
||||
#### Scenario: Незаявленное поле не попадает в журнал
|
||||
|
||||
- **WHEN** запись журнала формируется с полем, отсутствующим в перечне разрешённых
|
||||
- **THEN** это поле в выводе отсутствует
|
||||
@@ -0,0 +1,94 @@
|
||||
## 1. Тулчейн и каркас проекта
|
||||
|
||||
- [x] 1.1 Завести `pyproject.toml`: метаданные, `requires-python`, зависимости рантайма (`fastapi`, `uvicorn[standard]`, `gunicorn`, `pydantic`, `pydantic-settings`, `dishka`, `structlog`) и dev-группу (`pytest`, `pytest-asyncio`, `httpx`, `ruff`, `ty`)
|
||||
- [x] 1.2 Настроить `ruff` в `pyproject.toml`: целевая версия Python, набор правил, `line-length`, стиль отступов, изоляция `student-tests/` от правил приложения
|
||||
- [x] 1.3 Настроить `ty` в `pyproject.toml`: корень исходников `src/`, строгость проверок, исключения для тестов
|
||||
- [x] 1.4 Закрепить версии: `uv lock`, зафиксировать `uv.lock` в репозитории, дополнить `.gitignore` и `.dockerignore` артефактами сборки
|
||||
- [x] 1.5 Добавить в `Makefile` цели `lint`, `format`, `typecheck`, `student-test`, `app-run`, `app-stop`, `bench`, не трогая существующие цели
|
||||
- [x] 1.6 Настроить PostToolUse-хук Claude Code в `.claude/settings.json`: после каждой правки файла под `src/` выполняются `ruff check --fix`, `ruff format` и `ty check` по этому файлу; правки вне `src/` хук пропускает
|
||||
- [x] 1.7 Проверка группы: `uv sync`, затем `make lint` и `make check` на пустом каркасе проходят
|
||||
|
||||
## 2. Доменные зоны
|
||||
|
||||
- [x] 2.1 Разделить приложение на зоны `identity/` и `messaging/`; в `shared/` оставить только базовый тип события, коды ошибок, общие проверки строк и ключ истории
|
||||
- [x] 2.2 Зона `identity`: объекты-значения `Username` и `DisplayName`, сущность `User`, событие `UserRegistered`
|
||||
- [x] 2.3 Зона `messaging`: объекты-значения `ChatTitle` и `MessageText`, агрегат `Chat` с составом участников и append-only историей, сущность `Message`, события `ChatCreated` и `MessagePosted`
|
||||
- [x] 2.4 Инварианты агрегата `Chat`: отправитель входит в состав, пара `(created_at, id)` строго возрастает, состав неизменен после создания
|
||||
- [x] 2.5 Коды ошибок контракта в `shared/domain/errors.py`: `invalid_request`, `not_found`, `conflict`, `unauthorized`, `unavailable`
|
||||
- [x] 2.6 Проверка группы: юнит-тесты обеих зон на правила `username`, длину текста в code points, членство и монотонность истории
|
||||
|
||||
## 3. Слой приложения
|
||||
|
||||
- [x] 3.1 Общие порты в `shared/application/ports.py`: `Clock`, `IdGenerator`, `Logger`, `UnitOfWork`, `EventPublisher`, `CursorCodec`
|
||||
- [x] 3.2 Порты зоны `identity`: `UserRepository`, `IdentityUnitOfWork`, `UserDirectory`; команда `RegisterUser` и её обработчик
|
||||
- [x] 3.3 Порты зоны `messaging`: `ChatRepository`, `MemberRegistry`, `MessagingUnitOfWork`, `ChatDirectory`; команды `CreateChat` и `PostMessage` и их обработчики
|
||||
- [x] 3.4 Сторона чтения: `GetCurrentUser` в `identity`, `GetChat`, `ListChats` и `ReadHistory` в `messaging` — плоские результаты в обход агрегата
|
||||
- [x] 3.5 Шины в `shared/application/messagebus.py`: `CommandBus` (ровно один обработчик, ошибка всплывает) и `EventBus` с двумя видами подписки — проекции до подтверждения и отложенные обработчики через `asyncio.Queue` с пределом
|
||||
- [x] 3.6 Проекция `MemberProjection` в `messaging`: реестр участников наполняется событием `UserRegistered` зоны `identity`, прямых вызовов между зонами нет
|
||||
- [x] 3.7 Сбор событий: UoW обходит `.seen` после фиксации и передаёт события публикатору
|
||||
- [x] 3.8 Проверка группы: тесты границ зон по графу импортов и тесты консистентности данных между зонами
|
||||
|
||||
## 4. Инфраструктура
|
||||
|
||||
- [x] 4.1 Хранилище зоны `identity`: индексы по идентификатору и по `username`, своя блокировка
|
||||
- [x] 4.2 Хранилище зоны `messaging`: чаты, индекс по участнику, реестр известных участников; история как append-only список внутри агрегата
|
||||
- [x] 4.3 Репозитории и UoW обеих зон с ведением `.seen`; фиксация явная, откат по умолчанию
|
||||
- [x] 4.4 Режимы блокировки `global` и `per-chat` за одним портом, выбор через настройку `STORAGE_LOCKING`
|
||||
- [x] 4.5 Часы `shared/infrastructure/clock.py`: UTC, микросекунды, строго возрастающие метки; генератор идентификаторов
|
||||
- [x] 4.6 Кодек курсора: base64url, подпись HMAC-SHA256, привязка к области `messages:<chat_id>` и `chats:<user_id>`
|
||||
- [x] 4.7 Адаптер публикации `InMemoryEventPublisher` поверх `EventBus`; порт `EventPublisher` остаётся точкой расширения на лабу 5
|
||||
- [x] 4.8 Структурный логгер на structlog за портом `Logger`: единый JSON-поток, белый список полей, сообщения сервера приложений и библиотек идут через него же
|
||||
- [x] 4.9 Проверка группы: тесты кодека курсора (подделка, чужая область, испорченное значение) и монотонности часов под конкурентной нагрузкой
|
||||
|
||||
## 5. Точка входа HTTP
|
||||
|
||||
- [x] 5.1 Настройки `config.py` через `pydantic-settings`: хост, порт, лимиты, режим блокировки, параметры брокера, срок остановки; рабочие значения по умолчанию
|
||||
- [x] 5.2 DTO запросов и ответов в `entrypoints/api/schemas.py` с запретом лишних полей; тела ответов ровно по схемам контракта
|
||||
- [x] 5.3 Middleware `X-Request-Id`: использовать клиентское значение либо сгенерировать, проставить в каждый ответ, связать с логом
|
||||
- [x] 5.4 Обработчики ошибок: доменные ошибки, `RequestValidationError`, ошибка разбора JSON, `404`/`405` и неперехваченное исключение — все в единый формат `Error`
|
||||
- [x] 5.5 Зависимость идентификации `X-User-Id`, выполняемая до валидации тела; отсутствие, неверный формат и неизвестный идентификатор дают `401`
|
||||
- [x] 5.6 Маршруты health, users, chats, messages; путь запроса переводится в команду или запрос и передаётся шине
|
||||
- [x] 5.7 Сборка зависимостей `ioc.py` на dishka: отдельные провайдеры `SharedProvider`, `IdentityProvider`, `MessagingProvider` и `BusProvider`; `Scope.APP` для хранилищ, часов, публикатора и шины событий, `Scope.REQUEST` для UoW и шин команд
|
||||
- [x] 5.8 Жизненный цикл приложения: старт и остановка фоновой задачи разбора событий, закрытие контейнера DI, перевод `/health/ready` в `503` при остановке
|
||||
- [x] 5.9 Единый конвейер запроса как чистый ASGI-middleware: `X-Request-Id`, предел тела, идентификация, таймаут обработки и запись в журнал; слоёный вариант сохраняется для сравнения
|
||||
- [x] 5.10 Проверка группы: `make app-run`, затем `make test` — публичный smoke проходит целиком
|
||||
|
||||
## 6. Контейнер
|
||||
|
||||
- [x] 6.1 `Dockerfile`: multi-stage, базовый образ закреплён по digest, зависимости из `uv.lock`, слой зависимостей отделён от слоя исходников
|
||||
- [x] 6.2 Непривилегированный пользователь, минимальный набор файлов в финальном образе, `.dockerignore` исключает `.venv`, `.git`, `evidence` и кэши
|
||||
- [x] 6.3 Сервер — gunicorn с одним `UvicornWorker`, конфигурация в `gunicorn_conf.py`, его журнал перенастроен на общий логгер; `HEALTHCHECK` на `/health/live` без дополнительных пакетов; `CMD` в exec-форме, gunicorn — PID 1
|
||||
- [x] 6.4 Корректная остановка: `SIGTERM` завершает процесс не дольше 10 секунд, принятые запросы дорабатываются
|
||||
- [x] 6.6 Проверка группы: сборка из чистого clone, запуск, `healthy`, `make test`, замер времени остановки, проверка пользователя процесса
|
||||
|
||||
## 7. Собственные тесты (уровень «4»)
|
||||
|
||||
- [x] 7.1 Негативные тесты API: malformed JSON, лишнее поле, неверный тип, пустой и пробельный текст, текст свыше 4000 code points
|
||||
- [x] 7.2 Тесты доступа: чужой чат даёт `404` на чтение и на запись, чужой чат не виден в списке, `403` не используется
|
||||
- [x] 7.3 Тесты идентификации: отсутствующий, неверный и неизвестный `X-User-Id` дают `401`; дубликат `username` даёт `409`
|
||||
- [x] 7.4 Тесты пагинации: обход нескольких страниц без повторов и пропусков, смена `limit` между страницами, курсор от другого чата, подделанный курсор, `limit` вне диапазона
|
||||
- [x] 7.5 Конкурентный тест: 100 сообщений от 10 клиентов дают ровно 100 уникальных сообщений и строго возрастающий порядок
|
||||
- [x] 7.6 Тест логов: текст-маркер сообщения не появляется в stdout и stderr
|
||||
- [x] 7.8 Тесты границ зон: граф импортов подтверждает, что `identity` не знает о `messaging`, а `messaging` заимствует только объявление события
|
||||
- [x] 7.9 Тесты консистентности между зонами: регистрация сразу видна чатам, отклонённые операции не оставляют следа ни в одной зоне, параллельная работа обеих зон не расходится по счётчикам
|
||||
- [x] 7.10 Тесты таймаута запроса: предсказуемый `503`, отсутствие влияния на следующие запросы, запись в журнал без текста сообщения
|
||||
- [x] 7.11 Проверка группы: `make student-test` запускает всё одной командой и проходит
|
||||
|
||||
## 8. Трек «5»: предел in-memory архитектуры
|
||||
|
||||
- [x] 8.1 `scripts/bench.py`: матрица из трёх размеров истории и трёх уровней конкуренции, прогрев, сбор успешных RPS, доли ошибок, p50/p95/p99 и RSS
|
||||
- [x] 8.2 Снятие RSS процесса контейнера и вывод средней стоимости одного сообщения в байтах
|
||||
- [x] 8.3 Гипотеза 1: блокировка хранилища. Прогон матрицы в режимах `global` и `per-chat` при тех же лимитах, сохранение обеих серий
|
||||
- [x] 8.4 Профилирование пути записи для поиска настоящего узкого места, когда гипотеза 1 не подтвердилась
|
||||
- [x] 8.5 Гипотеза 2: накладные расходы конвейера запроса. Прогон матрицы в режимах `layered` и `single`, сохранение обеих серий
|
||||
- [x] 8.6 Сведение серий в сравнительные таблицы: throughput, p95, p99, RSS, разница по каждому сочетанию
|
||||
- [x] 8.7 Оценка предела: число сообщений до исчерпания лимита памяти, допущения и границы экстраполяции
|
||||
- [x] 8.8 Проверка группы: `make bench` воспроизводит серии, результаты машиночитаемы и не содержат пользовательских данных
|
||||
|
||||
## 9. Отчёт и приёмка
|
||||
|
||||
- [x] 9.1 Заполнить `REPORT.md`: запуск из чистого clone, версии, архитектура, границы транзакций, объявленная семантика времени и курсоров
|
||||
- [x] 9.2 Таблица «критерий → команда → наблюдение → файл доказательства» для каждого заявленного пункта уровней «3», «4» и трека «5»
|
||||
- [x] 9.3 Таблица воздействий: перезапуск контейнера, `SIGTERM` под нагрузкой, недоступный брокер при включённой публикации
|
||||
- [x] 9.4 Раздел ограничений: какие отказы не выдерживаются, где учебное упрощение, что подтверждено измерением, а что осталось гипотезой
|
||||
- [x] 9.5 Проверка группы: `make check`, `make lint`, `make student-test` и `make test` против собранного образа проходят подряд
|
||||
@@ -0,0 +1,5 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-12
|
||||
skip_specs: true
|
||||
archived: 2026-10-12
|
||||
lab: 1
|
||||
@@ -0,0 +1,66 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md` (Why). Сейчас FastAPI 0.141 уже сериализует успешные ответы через pydantic-core: аннотация `-> dict[str, Any]` превращается в TypeAdapter, и JSON-байты собираются на стороне Rust. Значит, модели ответов не добавляют новый сериализатор: меняется только то, что собирается в Python, — dict или модель. Тело ошибки отправляется в обход FastAPI, из сырого ASGI-конвейера (`shared/entrypoints/pipeline.py`) и из `identification.py`, сейчас через `orjson.dumps(error_body(...))`.
|
||||
|
||||
Изменение затрагивает обе зоны и `shared/entrypoints/`, но новой связи между зонами не вводит: каждая зона правит только свой HTTP-слой, обмен событиями не меняется.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Каждое значение, пересекающее HTTP-границу, имеет объявленный pydantic-тип; внутри — только dataclass и доменные объекты.
|
||||
- Ядро зон (`domain/`, `application/`) не импортирует pydantic: схемы живут в `entrypoints/`, настройки — в `config.py`.
|
||||
- Байт-в-байт тот же JSON на всех endpoint и в теле ошибки.
|
||||
|
||||
**Non-Goals:**
|
||||
- Перенос доменных инвариантов в схемы.
|
||||
- Замена `tuple` (`HistoryKey`, `tuple[list[T], bool]` из портов, `tuple[str, int]` в реестре ошибок) — это не dict.
|
||||
- Изменение индексов хранилища, ASGI-сообщений, реестров обработчиков, `CONFIG_KWARGS` uvicorn.
|
||||
- Изменения контейнера: пользователь, закрепление версий, healthcheck, обработка `SIGTERM` и переменные окружения остаются прежними.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Схемы транспорта лежат в `entrypoints/schemas.py` своей зоны
|
||||
|
||||
`identity/entrypoints/schemas.py`: `CreateUserRequest`, `UserOut`. `messaging/entrypoints/schemas.py`: `CreateChatRequest`, `CreateMessageRequest`, `PageQuery`, `ChatOut`, `MessageOut`, `PageOut[T]`. `shared/entrypoints/schemas.py`: `ErrorEnvelope` и `ErrorDetail`, `HealthOut`.
|
||||
|
||||
В `shared/` попадают только конверт ошибки и health: это механизм платформы, общий для всех ответов, а не доменное понятие. Коды ошибок по-прежнему объявляет зона в своём `errors.py`. `PageOut` остаётся в `messaging`, потому что страницы есть только там.
|
||||
|
||||
Что получаем: форма ответа объявлена типом и проверяется `ty` и FastAPI, а валидация входа заканчивается до application. Чего стоит: форма дублирует `contracts/openapi.json`, при этом источником истины остаётся `contracts/`.
|
||||
|
||||
### D2. Маппинг явным `of(domain)`, а не `from_attributes`
|
||||
|
||||
`UserOut.of(user)`, `ChatOut.of(chat)`, `MessageOut.of(message)`, `PageOut[MessageOut].of(page, MessageOut.of)`. В доменных объектах лежат value objects (`username.value`, `text.value`), и `from_attributes` пришлось бы подстраивать алиасами или свойствами в домене, а домен не должен знать транспорт. Чего стоит: один конструктор модели на элемент ответа.
|
||||
|
||||
### D3. Типы полей ответа — `UUID` и `datetime`
|
||||
|
||||
Поля `id`, `chat_id`, `sender_id`, `member_ids`, `created_at` типизированы по смыслу; pydantic сериализует `UUID` строкой, а UTC-`datetime` — с `Z`. Функция `moment()`, которая дублируется в двух зонах, удаляется. Альтернатива — поля `str`, заполняемые маппером, — отвергнута, потому что дублирует форматирование. Если формат разойдётся с текущим `isoformat().replace("+00:00", "Z")`, поле получит `Annotated[datetime, PlainSerializer(...)]` с прежним форматом.
|
||||
|
||||
### D4. Параметры запроса типизируются на границе
|
||||
|
||||
- `GET /chats` и `GET .../messages` принимают `Annotated[PageQuery, Query()]`: `limit: int = Field(50, ge=1, le=100)`, `cursor: str | None = None`. `extra="forbid"` у этой модели не ставится, потому что неизвестные query-параметры сегодня игнорируются. Строгий режим тоже не ставится: значения query — строки.
|
||||
- `chat_id: UUID` в path; функция `chat_uuid()` удаляется.
|
||||
- `CreateChatRequest.member_ids: list[Annotated[UUID, Field(strict=False)]]`. Модель остаётся `strict=True`, но FastAPI проверяет уже распарсенный dict в python-режиме, а там строгий `UUID` не принимает строку.
|
||||
- `parse_limit` и `LIMIT_*` уходят из `messaging/application/queries.py`. `ListChats` и `ReadHistory` получают `limit: int`. `CreateChat.member_ids` становится `Sequence[UUID]`, а `parse_uuids` в обработчике удаляется. Проверки дубликатов, неизвестных участников и отсутствия вызывающего остаются в домене и обработчике.
|
||||
|
||||
Ошибка разбора даёт `RequestValidationError` → `400 invalid_request`, то есть тот же код, что сейчас дают `InvalidPageRequest` и `InvalidChatData`. Курсор остаётся непрозрачной строкой, и разбирает его по-прежнему `SignedCursorCodec`.
|
||||
|
||||
### D5. Конверт ошибки сериализует pydantic-core
|
||||
|
||||
`ErrorEnvelope.of(code, message, request_id)` заменяет `error_body()` во всех четырёх местах вызова (`errors.py`, `pipeline.py`, `middleware.py`, `identification.py`). Байты получаются через `model_dump_json().encode()`, и на этом заканчивается использование orjson для HTTP-ответов. `orjson` остаётся зависимостью ради строк журнала.
|
||||
|
||||
### D6. Внутренние dict-методы удаляются
|
||||
|
||||
`DomainEvent.payload()` и его реализации в `UserRegistered`, `ChatCreated`, `MessagePosted` удаляются: событие уже frozen dataclass и само служит внутренним DTO. Журналы читают поля события напрямую. Порт `ChatDirectory.totals()`, его адаптер и метод хранилища тоже удаляются, потому что вызовов нет. Альтернатива — dataclass `Totals` и `EventPayload` — отвергнута как код ради кода. Когда в лабе 5 появится брокер, сериализацию события для него определит схема на той границе.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Формат `created_at` от pydantic расходится с текущим, например в долях секунды] → тест сравнивает ответ с форматом `isoformat().replace("+00:00", "Z")` на моменте с микросекундами и без них; при расхождении применяется резерв из D3.
|
||||
- [Строгий `UUID` в python-режиме отвергает корректный `member_ids`] → тест на успешный `POST /chats` закрывает это до остальных правок.
|
||||
- [Lax-разбор `limit` принимает нестандартную запись вроде `+5`, `05`, `1.0` или `1_0`, которую сейчас отвергает `parse_limit`] → контракт задаёт только целое 1–100; `0`, `101`, `abc` и отсутствие параметра ведут себя как прежде, это подтверждают собственные негативные тесты.
|
||||
- [Текст `message` в ответе 400 для плохого `limit` или `chat_id` станет общим `MESSAGES["invalid_request"]`] → контракт фиксирует `code`, а не текст; тесты проверяют код.
|
||||
- [Регрессия горячего пути: на страницу из 50 сообщений строится 50 моделей вместо 50 dict] → контрольный прогон `scripts/bench.py` по сценариям read и write в режиме `pipeline=single+locking=per-chat`; регрессия больше разброса повторов (3.2%) считается блокирующей и разбирается до архивации.
|
||||
- [Абзац REPORT про `orjson` устаревает] → уточняется отдельной задачей.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Миграции нет: состояние живёт в памяти, данных между перезапусками нет. Откат — `git revert` коммитов изменения.
|
||||
@@ -0,0 +1,37 @@
|
||||
## Why
|
||||
|
||||
На краях сервиса данные описаны нетипизированными `dict[str, Any]`: ответы собираются вручную функциями `*_view`, тело ошибки — `error_body()`, health — литералом, а `limit`, `cursor` и `chat_id` приходят сырыми строками и разбираются внутри слоя application. Форма ответа нигде не объявлена как тип, поэтому ни `ty`, ни FastAPI её не проверяют, а транспортная валидация протекла внутрь (`parse_limit` в `messaging/application/queries.py`, `parse_uuids` в обработчике команды).
|
||||
|
||||
Правило изменения: на границе с внешним миром — pydantic-схемы, внутри — dataclass.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Ответы всех endpoint объявляются pydantic-моделями: `UserOut`, `ChatOut`, `MessageOut`, `PageOut[T]`, `HealthOut`, `ErrorEnvelope`; функции `*_view`, `moment()` и `error_body()` удаляются.
|
||||
- Query-параметры пагинации описываются моделью `PageQuery`, `chat_id` в path типизируется как `UUID`, `member_ids` в `CreateChatRequest` — как `list[UUID]`. Проверка `limit` и UUID переезжает из application на границу; application и команды получают уже типизированные значения.
|
||||
- Внутренние dict-«DTO» удаляются как неиспользуемые: `DomainEvent.payload()` (вызывается только тестами) и порт `totals()` (вызовов нет). Событие уже является dataclass и само служит внутренним DTO.
|
||||
- Инварианты (`username`, длины, пустой текст) остаются в доменных value objects и не дублируются в схемах.
|
||||
- `HistoryKey` остаётся `tuple`; индексы хранилища, ASGI-сообщения и реестры обработчиков — структуры данных, а не DTO, и не меняются.
|
||||
|
||||
Наблюдаемое поведение API не меняется: те же коды, тела, заголовки и `X-Request-Id`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
Нет.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
Нет: изменение — чистый рефакторинг без изменения требований, поэтому в `.openspec.yaml` выставлен `skip_specs: true`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Всё из Out of scope лабы 1 остаётся вне изменения. Схемы для брокера событий не вводятся: внешний брокер появится в лабе 5, тогда у него будет своя граница и своя схема. Публикация FastAPI `/openapi.json` не становится заменой `contracts/openapi.json`. Контракт, публичные тесты и рубрика не меняются.
|
||||
|
||||
## Impact
|
||||
|
||||
- Уровень рубрики: «3» (контракт сохраняется, `make test` проходит) и «4» (собственные негативные тесты подтверждают, что поведение не изменилось). Для трека «5» нужен контрольный прогон, показывающий отсутствие регрессии на горячем пути.
|
||||
- Строки `REPORT.md`: «**«3»** Все endpoint, форматы ошибок…» (`make test`), «Собственные негативные тесты одной командой» (`make student-test`), «Измерения предела in-memory» (`make bench`); абзац про `orjson` уточняется: успешные ответы сериализует pydantic-core.
|
||||
- Код: `identity/entrypoints/http.py`, `messaging/entrypoints/http.py`, новые `*/entrypoints/schemas.py`, `shared/entrypoints/{errors,health,pipeline,middleware}.py`, `identity/entrypoints/identification.py`, `messaging/application/{queries,handlers,commands,ports}.py`, `messaging/infrastructure/memory/{store,directory}.py`, `*/domain/events.py`, `shared/domain/events.py`.
|
||||
- Тесты: `student-tests/api/test_events.py`, `student-tests/unit/test_domain.py` проверяют поля события через `dataclasses.fields` вместо `payload()`.
|
||||
- Зависимости не меняются.
|
||||
@@ -0,0 +1,47 @@
|
||||
## 1. Подготовка и страховочные тесты
|
||||
|
||||
- [x] 1.1 Закоммитить текущие незафиксированные правки (`scripts/bench.py`, `main.py`, `shared/entrypoints/config.py`, `REPORT.md`, `evidence/bench/repeats/`) отдельным коммитом, чтобы рефакторинг начинался с чистого дерева
|
||||
- [x] 1.2 Добавить в `student-tests/api/` тест формата `created_at` у пользователя, чата и сообщения: RFC 3339 UTC с `Z`, совпадение с `isoformat().replace("+00:00", "Z")` на моменте с микросекундами и без них
|
||||
- [x] 1.3 Добавить тест на `?limit=abc`, отсутствие `limit` (по умолчанию 50) и неизвестный query-параметр (игнорируется), если таких сценариев ещё нет
|
||||
- [x] 1.4 Проверка: `make student-test` зелёный на текущем коде
|
||||
|
||||
## 2. Платформа `shared/entrypoints`
|
||||
|
||||
- [x] 2.1 Создать `shared/entrypoints/schemas.py`: `ErrorDetail`, `ErrorEnvelope` с `of(code, message, request_id)` и `HealthOut`
|
||||
- [x] 2.2 Заменить `error_body()` на `ErrorEnvelope` в `errors.py`, `pipeline.py`, `middleware.py` и удалить `error_body()`
|
||||
- [x] 2.3 Перевести `/health/live` и `/health/ready` на `-> HealthOut`
|
||||
- [x] 2.4 Проверка: `make student-test -k "operability or pipeline_modes or timeout"` зелёный
|
||||
|
||||
## 3. Зона `identity`
|
||||
|
||||
- [x] 3.1 Создать `identity/entrypoints/schemas.py`: перенести `CreateUserRequest`, добавить `UserOut.of(user)` с полями `UUID` и `datetime`
|
||||
- [x] 3.2 Перевести `create_user` и `current_user` на `-> UserOut`, удалить `user_view()` и `moment()` из `identity/entrypoints/http.py`
|
||||
- [x] 3.3 Заменить `error_body()` на `ErrorEnvelope` в `identity/entrypoints/identification.py`
|
||||
- [x] 3.4 Удалить `UserRegistered.payload()`, перевести `student-tests/unit/test_domain.py` на проверку `dataclasses.fields`
|
||||
- [x] 3.5 Проверка: `make student-test -k "access or negative or domain"` зелёный
|
||||
|
||||
## 4. Зона `messaging`: граница
|
||||
|
||||
- [x] 4.1 Создать `messaging/entrypoints/schemas.py`: перенести `CreateChatRequest` с `member_ids: list[Annotated[UUID, Field(strict=False)]]` и `CreateMessageRequest`, добавить `PageQuery` с `limit` 1–100 (по умолчанию 50) и `cursor`, добавить `ChatOut`, `MessageOut`, `PageOut[T]` с `of(...)`
|
||||
- [x] 4.2 Перевести обработчики `messaging/entrypoints/http.py` на `chat_id: UUID`, `Annotated[PageQuery, Query()]` и типизированные ответы; удалить `chat_uuid()`, `moment()` и все `*_view()`
|
||||
- [x] 4.3 Проверка: успешный `POST /api/v1/chats` с корректными `member_ids` проходит, `make student-test -k "negative or pagination"` зелёный
|
||||
|
||||
## 5. Зона `messaging`: application, domain, infrastructure
|
||||
|
||||
- [x] 5.1 В `messaging/application/queries.py` принять `limit: int` в `ListChats` и `ReadHistory`, удалить `parse_limit` и `LIMIT_*`
|
||||
- [x] 5.2 В `messaging/application/commands.py` сменить `CreateChat.member_ids` на `Sequence[UUID]`, в `handlers.py` удалить `parse_uuids`
|
||||
- [x] 5.3 Удалить `ChatDirectory.totals()` из `ports.py`, адаптера `memory/directory.py` и `memory/store.py`
|
||||
- [x] 5.4 Удалить `payload()` у `ChatCreated`, `MessagePosted` и базового `DomainEvent`; перевести `student-tests/api/test_events.py` на `dataclasses.fields`
|
||||
- [x] 5.5 Проверка: `rg "dict\[str, Any\]|payload\(|totals\(" src` не находит DTO-словарей, `make lint` (ruff + ty) и `make student-test` зелёные, `test_bounded_contexts` подтверждает, что `domain/` и `application/` не импортируют pydantic
|
||||
|
||||
## 6. Контракт и измерения
|
||||
|
||||
- [x] 6.1 Собрать образ, поднять контейнер, прогнать `make test` и `make check`: `PASS: lab1 public API scenario`
|
||||
- [x] 6.2 Контрольный прогон `scripts/bench.py --scenario read` и `--scenario write` в режиме `pipeline=single+locking=per-chat`, сравнить RPS и p95/p99 с текущими `evidence/bench/repeats/`; регрессия больше 3.2% блокирует архивацию
|
||||
- [x] 6.3 Проверка: результаты контрольного прогона сохранены в `evidence/bench/`, расхождение с прежними цифрами в пределах разброса
|
||||
|
||||
## 7. Отчёт
|
||||
|
||||
- [x] 7.1 Уточнить в `REPORT.md` абзац про `orjson`: успешные ответы и тело ошибки сериализует pydantic-core, `orjson` остаётся для журнала
|
||||
- [x] 7.2 Обновить в таблице доказательств число тестов в строке «Собственные негативные тесты одной командой» и сослаться на файл контрольного прогона
|
||||
- [x] 7.3 Проверка: `make lint`, `make student-test`, `make check` зелёные, `evidence/student-tests.txt` перезаписан свежим выводом
|
||||
@@ -0,0 +1,5 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
retire_capabilities: true
|
||||
archived: 2026-10-28
|
||||
lab: 2
|
||||
@@ -0,0 +1,104 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. Исходная точка — решение лабы 1 (ветка `solution/bpi2303-kostylev` в `mtusi2026lab1`): две зоны `identity` и `messaging`, порты и адаптеры в память, единый ASGI-конвейер с идентификацией раньше разбора тела, шина событий, курсор с HMAC. Ограничения лабы 2, формирующие решение:
|
||||
|
||||
- Smoke и persistence-тест сравнивают dict'ы целиком: `Session.user` с ответом регистрации, страницы истории с ответами `POST`, историю после рестарта с исходным сообщением. Формат `created_at` и порядок полей обязаны совпадать до символа.
|
||||
- Persistence-тест ждёт ответ не дольше 2 с и до 90 с опрашивает готовность после hook.
|
||||
- Несколько воркеров gunicorn — несколько процессов: ничто, что должно быть общим (секрет курсора, порядок истории), не может жить в памяти одного процесса.
|
||||
- Изменение касается обеих зон и `shared/`. Новой связи между зонами в коде не появляется: общая точка — схема БД.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- PostgreSQL — единственный источник истины для пользователей, сессий, чатов, участников и сообщений; адаптеры встают за существующие порты, `domain/` и `application/` не импортируют asyncpg.
|
||||
- Аутентификация целиком в ASGI-конвейере: `401` раньше доступа и валидации, точные challenge-заголовки, `X-User-Id` не читается вовсе.
|
||||
- Порядок истории строго определён при нескольких процессах API.
|
||||
- Стенд поднимается из чистого clone двумя командами, рестартуется hook-ом без потери данных и сессий.
|
||||
|
||||
**Non-Goals:**
|
||||
- Valkey, тесты гонок и отказов, EXPLAIN — изменение уровня «4».
|
||||
- ORM и генераторы миграций: SQL пишется руками, его план виден напрямую.
|
||||
- Очистка истёкших сессий фоновым процессом: строки удаляются при следующем входе того же пользователя.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Что переносится и что удаляется
|
||||
|
||||
Переносятся зоны, шина, конвейер, курсор, журнал, схемы pydantic, тесты и тулчейн. Удаляются адаптеры в память, `MemberRegistry` с проекцией `MemberProjection`, ошибка `HistoryOrderViolated`, слоёный конвейер на трёх `BaseHTTPMiddleware` (`PIPELINE=layered`), режимы блокировки `STORAGE_LOCKING` и `scripts/bench.py`. Последние три были измерительными инструментами трека лабы 1: с переездом в PostgreSQL сравнивать их больше не с чем. Что получаем: меньше кода и одно поведение. Чего стоит: эксперимент лабы 1 нельзя повторить на этой ветке — он остаётся в репозитории лабы 1.
|
||||
|
||||
### D2. Схема и границы транзакций
|
||||
|
||||
```
|
||||
users(id uuid PK, username text UNIQUE CHECK ~ '^[a-z0-9_]{3,32}$', display_name text CHECK 1..100,
|
||||
password_hash text, created_at timestamptz)
|
||||
sessions(token_hash bytea PK CHECK 32 байта, user_id → users ON DELETE CASCADE,
|
||||
created_at, expires_at CHECK > created_at) индекс (user_id)
|
||||
chats(id uuid PK, title text CHECK 1..100, created_at, last_message_at timestamptz NULL)
|
||||
chat_members(chat_id → chats ON DELETE CASCADE, user_id → users, position smallint,
|
||||
chat_created_at timestamptz, PK (chat_id, user_id)) индекс (user_id, chat_created_at, chat_id)
|
||||
messages(id uuid PK, chat_id, sender_id, text CHECK 1..4000, created_at,
|
||||
FK (chat_id, sender_id) → chat_members) индекс (chat_id, created_at, id)
|
||||
```
|
||||
|
||||
Длины в `CHECK` считаются `char_length` — в code points, как в контракте. Составной внешний ключ `messages → chat_members` гарантирует на уровне БД, что отправитель — участник своего чата. `position` хранит порядок `member_ids` из запроса, `chat_created_at` денормализован ради keyset-списка чатов по одному индексу. Индекс истории `(chat_id, created_at, id)` обслуживает keyset-запрос без сортировки; его обоснование планом — в изменении уровня «4».
|
||||
|
||||
Транзакции: регистрация — один `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`; вход — удаление истёкших сессий пользователя и вставка новой одним оператором; создание чата — `INSERT chats` и `INSERT chat_members` из `unnest(…) WITH ORDINALITY` в одной транзакции UoW; сообщение — `SELECT … FOR UPDATE` строки чата, `INSERT messages`, `UPDATE chats.last_message_at` в одной транзакции. Чтения идут без явной транзакции, по одному оператору.
|
||||
|
||||
### D3. Миграции
|
||||
|
||||
`src/messenger/migrations/NNNN_*.sql` поставляются внутри пакета, применяет их `python -m messenger.migrate`: `pg_advisory_lock`, таблица `schema_migrations(version, checksum, applied_at)`, каждая миграция и запись о ней — в одной транзакции, SHA-256 текста сверяется с записанным. Запуск — одноразовый compose-сервис `migrate` на образе приложения; `api` зависит от него `service_completed_successfully`. Альтернатива — миграции при старте каждого воркера — отвергнута: четыре процесса гоняли бы DDL одновременно, а сбой миграции превращался бы в crash-loop API. Чего стоит: ещё один сервис в compose и ~50 строк runner-а вместо готового инструмента.
|
||||
|
||||
### D4. Доступ к PostgreSQL: пул, UoW и ошибки зависимости
|
||||
|
||||
`shared/infrastructure/postgres.py` — платформа: `Database` над `asyncpg.Pool` (ленивый, `min_size=0`, `max_size` на воркер, таймауты подключения, `acquire`, команды и `statement_timeout` на сервере) и база `PostgresUnitOfWork` (соединение на транзакцию, фиксация явная, откат по умолчанию, сбор событий). SQL только параметризованный (`$1…`). Ошибки сети, таймауты и отказ сервера (`OSError`, `asyncpg.InterfaceError`, `PostgresConnectionError`, классы `57*` и `53*`) превращаются в платформенное `Unavailable` (`shared/application/errors.py`), которое точка входа отдаёт как `503 unavailable`. Нарушения ограничений адаптер зоны переводит в доменные ошибки (`UsernameAlreadyTaken`, `InvalidChatData`). В `shared/` попадает только механизм — пул, транзакция, классификация отказа; ни одной таблицы зоны.
|
||||
|
||||
Пул ленивый, поэтому процесс стартует и при недоступной БД: `/health/live` отвечает, `/health/ready` даёт `503` до первого успешного `SELECT 1`. Готовность пингует БД через тот же пул с таймаутом 1 с.
|
||||
|
||||
### D5. Пароли и сессии (зона `identity`)
|
||||
|
||||
- `Password` — объект-значение (12–128 code points, не только пробелы). Хеш — порт `PasswordHasher`, адаптер `argon2-cffi`: Argon2id, `m=19 MiB, t=2, p=1` (минимум OWASP). Хеширование и проверка идут в пуле потоков под семафором (`PASSWORD_HASH_CONCURRENCY`, по умолчанию 2 на воркер), чтобы не блокировать event loop и ограничить память при всплеске регистраций. Для неизвестного `username` выполняется проверка против заранее вычисленного фиктивного хеша — время ответа не выдаёт существование пользователя.
|
||||
- Токен — `secrets.token_urlsafe(32)` (43 символа, 256 бит). В БД хранится только `sha256(token)`: у токена полная энтропия, медленный KDF ему не нужен, а утечка таблицы не даёт действующих токенов. В этом и разница с паролем, у которого энтропия мала и перебор надо удорожать.
|
||||
- `Session(token_hash, user_id, expires_at)`; `expires_at = now + SESSION_TTL_SECONDS`, абсолютный, не продлевается. Проверка — `expires_at > now` по часам приложения: один источник времени для назначения и проверки. Выход — `DELETE` строки.
|
||||
- Команды `RegisterUser`, `OpenSession`, `CloseSession` идут через `CommandBus` и UoW зоны; запросы `VerifyCredentials` и `Authenticate` — через справочники `UserDirectory` и `SessionDirectory`. События `SessionOpened` и `SessionClosed` пишутся в журнал аудита без токена.
|
||||
|
||||
### D6. Аутентификация в конвейере
|
||||
|
||||
Страж зоны `identity` (`entrypoints/authentication.py`) вызывается `RequestPipeline` до приложения и возвращает `None` или отказ `Rejection(status, code, headers)`; `Unavailable` из стража конвейер превращает в `503`. Публичны `/health/*` и `POST /api/v1/users`. На `POST /api/v1/auth/sessions` страж разбирает `Basic` своим парсером (строгий base64, первое `:`, UTF-8, ASCII-username) и проверяет пароль; на остальных `/api/v1/*` — `Bearer` (схема без учёта регистра). Challenge выбирает функция `challenge_for(path)` зоны, её же применяет обработчик ошибок `401` внутри приложения. Встроенный `fastapi.security.HTTPBasic` отвергнут: он декодирует ASCII и отвечает своим `401` без `realm`/`charset`. `X-User-Id` не читается нигде. Что получаем: порядок `401 → 404 → 400` держится одним местом. Чего стоит: проверка Argon2 на входе выполняется в конвейере, а не в обработчике.
|
||||
|
||||
### D7. Агрегат `Chat` без истории и порядок сообщений
|
||||
|
||||
Агрегат больше не держит историю: в памяти это была ссылка, в БД — материализация всей переписки. `Chat` хранит состав и `last_message_at`. `PostMessage` загружает чат `SELECT … FOR UPDATE`, агрегат проверяет членство и назначает `created_at = max(now, last_message_at + 1 мкс)`, адаптер вставляет сообщение и обновляет `last_message_at` в той же транзакции. Блокировка строки сериализует запись в один чат между процессами, поэтому порядок фиксации совпадает с порядком `(created_at, id)`, и keyset-читатель не пропускает сообщение, зафиксированное позже с меньшей отметкой. Это заменяет монотонные часы процесса лабы 1, которые при нескольких воркерах ничего не гарантируют. Чего стоит: запись в один горячий чат идёт последовательно (как блокировка `per-chat` в лабе 1); разные чаты не мешают друг другу. Альтернатива — время БД `clock_timestamp()` без блокировки — отвергнута: отметка назначается до фиксации, и параллельная транзакция может зафиксироваться позже с меньшей отметкой.
|
||||
|
||||
Идентификаторы — UUIDv7 (`uuid.uuid7()` в Python 3.14): вставки в B-tree первичных ключей идут в правый край, а порядок при равных отметках по-прежнему задаёт `uuid` как 128-битное число (сравнение `uuid` в PostgreSQL побайтовое и совпадает с `UUID.int`).
|
||||
|
||||
### D8. Зоны и общая БД
|
||||
|
||||
Проекция `MemberProjection` заменена внешним ключом `chat_members.user_id → users`: проверка «участник существует» выполняется СУБД в транзакции создания чата, и отказ откатывает её целиком. С реестром участников это была бы проекция в отдельной транзакции после фиксации пользователя — окно рассогласования без outbox. SQL зоны `messaging` не читает `users` и `sessions`, зона `identity` не читает таблиц чатов; тест границ проверяет и импорты, и тексты SQL. Событие `UserRegistered` остаётся (журнал аудита).
|
||||
|
||||
### D9. Курсор и секреты
|
||||
|
||||
`SignedCursorCodec` не меняется, но секрет обязателен и приходит из `CURSOR_SECRET_FILE`: случайный секрет на процесс ломал бы вторую страницу на другом воркере и после рестарта. Платформенный источник настроек читает `<ИМЯ>_FILE` для любого поля (`DATABASE_URL_FILE`, `CURSOR_SECRET_FILE`, позже `CACHE_URL_FILE`). `.env` приложение больше не читает: его использует только compose для подстановки.
|
||||
|
||||
### D10. Процесс и контейнер
|
||||
|
||||
gunicorn с `WEB_CONCURRENCY` (по умолчанию 4) воркерами `uvicorn_worker.UvicornWorker` (модуль `uvicorn.workers` объявлен устаревшим). Пул на воркер `DB_POOL_MAX_SIZE=8`: 4×8 плюс экземпляры тестов остаются ниже `max_connections=100`. Образ — как в лабе 1: python по digest, non-root `10001`, `SIGTERM` ≤10 с; healthcheck compose проверяет `/health/ready`.
|
||||
|
||||
Стенд `compose.yaml`: `postgres` (`postgres:17.11-alpine@sha256:…`, volume `pgdata`, `pg_isready`), `migrate`, `api` (`127.0.0.1:8080`). Учётные данные — compose secrets из `secrets/` (`postgres_password`, `database_url`, `cursor_secret`), их создаёт идемпотентный `scripts/secrets.sh` (`make secrets`) и не перезаписывает существующие. `scripts/restart.sh`: `stop api` → `restart postgres` → `up -d api` (повторно прогоняет `migrate`, что заодно проверяет идемпотентность).
|
||||
|
||||
Соответствие `.env.example`: `APP_HOST`/`APP_PORT` → `HOST`/`PORT` (задаёт образ), `APP_ENV` не используется, `SESSION_TTL_SECONDS` → `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE` → `DATABASE_URL_FILE`, `SESSION_STORE=postgres` — фиксированный выбор (PostgreSQL — источник истины), `CACHE_URL_FILE` — изменение уровня «4».
|
||||
|
||||
### D11. Собственные тесты
|
||||
|
||||
Тесты API по-прежнему поднимают приложение в процессе (httpx + ASGI), но против настоящего PostgreSQL: фикстура сессии запускает одноразовый контейнер того же образа по digest, что и стенд, на случайном порту `127.0.0.1`, применяет миграции runner-ом и удаляет контейнер в конце. SQLite не используется. Публичный `make test` и persistence-тест идут против compose-стенда.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Argon2 на входе в конвейере под нагрузкой упирается в CPU] → семафор на воркер, параметры документированы; вход — не горячий путь.
|
||||
- [Первый запрос после рестарта PostgreSQL получает мёртвое соединение из пула] → asyncpg закрывает соединение по разрыву TCP, ошибка классифицируется как `503`, клиент persistence-теста повторяет запрос.
|
||||
- [`FOR UPDATE` сериализует запись в горячий чат] → это та же цена, что `per-chat` блокировка лабы 1; измерение стоимости записи — в треке «5».
|
||||
- [Истёкшие сессии копятся у пользователей, которые больше не входят] → индекс по `user_id` и удаление при входе; фоновой очистки нет, это записано в ограничениях.
|
||||
- [Секреты в `secrets/` на хосте читаемы контейнерами] → каталог в `.gitignore` и `.dockerignore`, файлы создаются скриптом, значения не печатаются.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Перехода данных нет: лаба 1 не хранила состояния. Схема создаётся миграцией `0001_init.sql` на пустом volume. Откат — `git revert` и `make reset-data` (намеренное удаление volumes).
|
||||
@@ -0,0 +1,39 @@
|
||||
## Why
|
||||
|
||||
Решение лабы 1 держит всё состояние в памяти одного процесса и узнаёт пользователя по `X-User-Id`, которым любой клиент выдаёт себя за другого. Контракт 1.2.0 лабы 2 требует, чтобы пользователи, чаты, сообщения и действующие сессии переживали рестарт API и хранилищ, а запросы связывались с пользователем, доказавшим знание пароля. Изменение закрывает уровень «3» рубрики `README.md` и строки «Публичный smoke», «Persistence» и строки уровня 3 таблицы доказательств `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Решение лабы 1 переносится в skeleton лабы 2: `src/`, `student-tests/`, `Dockerfile`, тулчейн, цели `Makefile`, CI-job.
|
||||
- **BREAKING** Состояние переезжает в PostgreSQL: таблицы `users`, `sessions`, `chats`, `chat_members`, `messages` с первичными и внешними ключами, `UNIQUE(username)` и `CHECK`. Схема задаётся версионируемыми SQL-миграциями, которые применяет одноразовый сервис `migrate`; повторный запуск ничего не меняет.
|
||||
- Адаптеры PostgreSQL встают за существующие порты репозиториев, справочников и `UnitOfWork`; адаптеры в память, реестр участников с проекцией и экспериментальные режимы лабы 1 (`PIPELINE=layered`, `STORAGE_LOCKING`, `scripts/bench.py`) удаляются.
|
||||
- **BREAKING** `POST /api/v1/users` требует `password` (12–128 code points), пароль хранится только как Argon2id. `POST /api/v1/auth/sessions` принимает только `Basic` и выдаёт непрозрачный токен с абсолютным сроком `SESSION_TTL_SECONDS`; в БД лежит лишь его SHA-256. `DELETE /api/v1/auth/sessions/current` отзывает сессию.
|
||||
- **BREAKING** Все остальные `/api/v1/*` принимают только `Authorization: Bearer`; `X-User-Id` игнорируется. Аутентификация остаётся в ASGI-конвейере раньше доступа и валидации; `401` несёт точный `WWW-Authenticate` контракта.
|
||||
- Порядок истории при нескольких воркерах держит агрегат `Chat`: запись сообщения блокирует строку чата, и `created_at` строго возрастает в порядке фиксации.
|
||||
- Курсор подписывается постоянным секретом из `secrets/`, поэтому переживает рестарт и работает при нескольких воркерах.
|
||||
- Стенд — Docker Compose: `postgres` по digest с именованным volume, `migrate`, `api` (gunicorn с несколькими `UvicornWorker`, готовность пингует БД). Секреты — compose secrets из gitignored `secrets/`, генерируемых `make secrets`; `scripts/restart.sh` перезапускает API и PostgreSQL без удаления volumes.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab2-auth-sessions`: пароль и KDF, вход `Basic`, `Bearer`-сессии с абсолютным TTL, отзыв, игнорирование `X-User-Id`, challenge-заголовки `401`.
|
||||
- `lab2-persistent-storage`: схема PostgreSQL с ограничениями, версионируемые миграции, атомарное создание чата, сохранность данных и сессий при рестарте, воспроизводимый стенд, секреты вне Git.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-messenger-identity`: регистрация с паролем; идентификация по `X-User-Id` и требование «пользователи не переживают перезапуск» снимаются.
|
||||
- `lab1-messenger-chats`: запрос без действительной сессии вместо запроса без `X-User-Id`.
|
||||
- `lab1-messenger-history`: порядок истории гарантируется при нескольких процессах API.
|
||||
- `lab1-service-operability`: готовность зависит от PostgreSQL; логи без токенов и паролей; требование «состояние только в памяти» снимается.
|
||||
- `lab1-event-publication`: зоны связаны событием и внешним ключом схемы вместо проекции; событиям по-прежнему не нужен брокер.
|
||||
- `lab1-inmemory-capacity`: трек «5» лабы 1 о пределе памяти снимается вместе с in-memory хранением.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: все зоны `src/messenger/**`, новые `migrate.py`, `migrations/0001_init.sql`, `shared/infrastructure/postgres.py`; удаляются `*/infrastructure/memory/`, `messaging/application/projections.py`, `shared/entrypoints/middleware.py`.
|
||||
- Стенд: `compose.yaml`, `scripts/secrets.sh`, `scripts/restart.sh`, `.env.example`, `.dockerignore`, `Makefile`, `.github/workflows/application.yml`.
|
||||
- Зависимости: `asyncpg`, `argon2-cffi`, `uvicorn-worker`; образ `postgres:17.11-alpine` по digest.
|
||||
- Отчёт: `REPORT.md` (запуск, архитектура, строки уровня 3), `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Valkey, гонки, rollback-тест, индекс истории с EXPLAIN и автотесты отказов — следующее изменение уровня «4»; трек «5» — третье. Из Out of scope лабы 2 не появляется ничего: реплики за балансировщиком и `Idempotency-Key` (лаба 3), S3 (лаба 4), брокер и worker (лаба 5), OTel (лаба 6), TLS (лаба 7). Контракт, публичные тесты, `README.md` и `COURSE.md` не меняются.
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Публикация событий не требует брокера
|
||||
|
||||
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера; из сетевых сервисов обязательный API зависит только от PostgreSQL.
|
||||
|
||||
#### Scenario: События доставляются без брокера
|
||||
|
||||
- **WHEN** стенд поднят без брокера сообщений
|
||||
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
|
||||
|
||||
#### Scenario: Публикация скрыта за портом
|
||||
|
||||
- **WHEN** проверяется слой приложения
|
||||
- **THEN** он обращается к публикации только через порт и не знает её реализации
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Доменные зоны связаны только событиями
|
||||
|
||||
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и импортировать её модули, кроме объявления события о регистрации. Существование участника SHALL проверяться внешним ключом схемы БД в той же транзакции, что и запись чата; SQL каждой зоны SHALL читать только таблицы своей зоны.
|
||||
|
||||
#### Scenario: Регистрация видна чатам сразу
|
||||
|
||||
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
|
||||
- **THEN** чат создаётся успешно: ответ регистрации отправлен после фиксации пользователя в БД
|
||||
|
||||
#### Scenario: Неизвестный зоне участник отклоняется
|
||||
|
||||
- **WHEN** в состав чата передан идентификатор, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, чат не создаётся
|
||||
|
||||
#### Scenario: Зона пользователей не знает о чатах
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
|
||||
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
|
||||
|
||||
#### Scenario: Обратная связь идёт только через контракт события
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
|
||||
- **THEN** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации, а SQL зоны не упоминает таблиц `users` и `sessions`
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Доставка событий не требует внешних сервисов
|
||||
|
||||
**Reason**: С лабы 2 обязательный API зависит от PostgreSQL, поэтому формулировка «ни одного внешнего сервиса» больше неверна.
|
||||
**Migration**: Требование «Публикация событий не требует брокера» этой же capability.
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Повторяемая методика измерения
|
||||
|
||||
**Reason**: Трек «5» лабы 1 измерял предел хранения в памяти одного процесса; с лабы 2 этого хранения нет.
|
||||
**Migration**: Повторяемая методика трека «5» лабы 2 — `lab2-query-plan-recovery` (вводится третьим изменением).
|
||||
|
||||
### Requirement: Наблюдаемый предел хранения в памяти
|
||||
|
||||
**Reason**: Сообщения больше не хранятся в памяти процесса API, RSS не растёт с историей.
|
||||
**Migration**: Стоимость хранения измеряется размером таблиц и индексов PostgreSQL в треке «5» лабы 2.
|
||||
|
||||
### Requirement: Узкое место названо и подтверждено изменением
|
||||
|
||||
**Reason**: Требование относилось к эксперименту in-memory архитектуры лабы 1.
|
||||
**Migration**: Сравнение вариантов индексов и запросов «до/после» — в треке «5» лабы 2.
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Создание чата
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats` от аутентифицированного пользователя с телом `{"title":..., "member_ids":[...]}` и возвращать `201` с объектом `Chat`. `title` SHALL содержать от 1 до 100 code points и не состоять только из пробельных символов. `member_ids` SHALL содержать от 1 до 100 уникальных идентификаторов существующих пользователей и SHALL включать вызывающего. Чат SHALL создаваться атомарно: при любой ошибке валидации он не создаётся вовсе.
|
||||
|
||||
#### Scenario: Чат создан
|
||||
|
||||
- **WHEN** участник отправляет `POST /api/v1/chats` с корректным `title` и списком из своего и чужого идентификаторов
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Chat`, `member_ids` совпадает с запрошенным составом
|
||||
- **AND** `id` и `created_at` назначены сервером
|
||||
|
||||
#### Scenario: Вызывающий не входит в состав
|
||||
|
||||
- **WHEN** `member_ids` не содержит идентификатора вызывающего
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит дубликаты
|
||||
|
||||
- **WHEN** `member_ids` содержит один и тот же идентификатор дважды
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит неизвестного пользователя
|
||||
|
||||
- **WHEN** `member_ids` содержит идентификатор, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** чат не создаётся
|
||||
|
||||
#### Scenario: Запрос без идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/chats` приходит без `Authorization: Bearer` или с недействительным токеном
|
||||
- **THEN** ответ `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Порядок истории
|
||||
|
||||
История чата SHALL быть упорядочена по паре `(created_at, id)` по возрастанию. Время SHALL назначаться сервером в формате RFC 3339 UTC с суффиксом `Z`. Сервис SHALL гарантировать, что `created_at` внутри одного чата строго возрастает в порядке фиксации сообщений, в том числе при конкурентных вставках через разные процессы API, — иначе обход истории keyset-курсором теряет запись, зафиксированную позже с меньшей отметкой.
|
||||
|
||||
#### Scenario: Сообщения возвращаются в порядке приёма
|
||||
|
||||
- **WHEN** в чат последовательно отправлены два сообщения от разных участников
|
||||
- **THEN** `GET /api/v1/chats/{chat_id}/messages` возвращает их в порядке отправки
|
||||
|
||||
#### Scenario: Конкурентная запись не ломает порядок
|
||||
|
||||
- **WHEN** 10 клиентов параллельно отправляют по 10 сообщений в один чат
|
||||
- **THEN** история содержит ровно 100 сообщений с попарно различными `id`
|
||||
- **AND** `created_at` строго возрастает по всей истории
|
||||
|
||||
#### Scenario: Отметка не уходит назад при отставших часах процесса
|
||||
|
||||
- **WHEN** процесс API назначает сообщению отметку меньше, чем у последнего зафиксированного сообщения чата
|
||||
- **THEN** сообщение получает отметку на одну микросекунду больше последней, и порядок истории сохраняется
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Регистрация пользователя
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/users` без аутентификации и возвращать `201` с объектом `User`, содержащим назначенные сервером `id` и `created_at`. Тело запроса SHALL содержать ровно поля `username`, `display_name` и `password`. `username` SHALL соответствовать `^[a-z0-9_]{3,32}$` и быть уникальным, `display_name` SHALL содержать от 1 до 100 Unicode code points и не состоять только из пробельных символов, требования к `password` задаёт `lab2-auth-sessions`. Ответ SHALL NOT содержать полей, отсутствующих в схеме `User`. Уникальность SHALL соблюдаться и при конкурентной регистрации одного `username`: успешной будет ровно одна, остальные получат `409`.
|
||||
|
||||
#### Scenario: Пользователь создан
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с телом `{"username":"alice_01","display_name":"Алиса","password":"<12+ символов>"}`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `User`, `username` и `display_name` совпадают с запросом
|
||||
- **AND** `id` — UUID, назначенный сервером, `created_at` — RFC 3339 UTC с суффиксом `Z`
|
||||
|
||||
#### Scenario: Username занят
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с `username`, уже принадлежащим другому пользователю
|
||||
- **THEN** ответ `409` с телом ошибки и кодом `conflict`
|
||||
|
||||
#### Scenario: Username нарушает формат
|
||||
|
||||
- **WHEN** `username` содержит заглавные буквы, дефис, пробел, перевод строки или имеет длину вне 3–32 символов
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Display_name пуст или состоит из пробелов
|
||||
|
||||
- **WHEN** `display_name` равен `""`, `" "` или длиннее 100 code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Тело запроса нарушает схему
|
||||
|
||||
- **WHEN** тело содержит лишнее поле, неверный тип поля, не содержит обязательного поля (в том числе `password`) или не является корректным JSON
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** сообщение ошибки не содержит stack trace и внутренних деталей реализации
|
||||
|
||||
#### Scenario: Регистрация не требует идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/users` приходит без заголовка `Authorization`
|
||||
- **THEN** запрос обрабатывается на общих основаниях, ответ не равен `401`
|
||||
|
||||
### Requirement: Чтение текущего пользователя
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/users/me` объект `User` владельца предъявленной `Bearer`-сессии в том же виде, в каком он был возвращён при регистрации.
|
||||
|
||||
#### Scenario: Текущий пользователь возвращён
|
||||
|
||||
- **WHEN** приходит `GET /api/v1/users/me` с действительным `Bearer`-токеном пользователя
|
||||
- **THEN** ответ `200`, тело соответствует схеме `User` и совпадает с телом ответа его регистрации
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Идентификация запроса заголовком X-User-Id
|
||||
|
||||
**Reason**: Контракт 1.2.0 заменяет учебную идентификацию аутентификацией: `X-User-Id` с лабы 2 игнорируется.
|
||||
**Migration**: Получить токен `POST /api/v1/auth/sessions` с `Basic` и передавать `Authorization: Bearer <token>`; правила описаны в `lab2-auth-sessions`.
|
||||
|
||||
### Requirement: Состояние пользователей не переживает перезапуск
|
||||
|
||||
**Reason**: С лабы 2 пользователи хранятся в PostgreSQL и обязаны переживать рестарт.
|
||||
**Migration**: Требование «Данные и сессии переживают рестарт» в `lab2-persistent-storage`.
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Пробы жизни и готовности
|
||||
|
||||
Сервис SHALL отвечать на `GET /health/live` кодом `200` с телом `{"status":"ok"}`, проверяя только жизнь процесса. Сервис SHALL отвечать на `GET /health/ready` кодом `200` с тем же телом, только если в момент запроса выполнен запрос к PostgreSQL за ограниченное время, и кодом `503` с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать аутентификации. Недоступность необязательных зависимостей SHALL NOT переводить готовность в `503`.
|
||||
|
||||
#### Scenario: Проба жизни отвечает без идентификации
|
||||
|
||||
- **WHEN** приходит `GET /health/live` без заголовка `Authorization`
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность подтверждена
|
||||
|
||||
- **WHEN** приходит `GET /health/ready`, а PostgreSQL доступен
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность не зависит от внешних сервисов
|
||||
|
||||
- **WHEN** проверяется готовность, а недоступна только необязательная зависимость
|
||||
- **THEN** ответ `200`: из внешних сервисов готовность зависит лишь от PostgreSQL
|
||||
|
||||
#### Scenario: Готовность отражает PostgreSQL
|
||||
|
||||
- **WHEN** PostgreSQL остановлен
|
||||
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable`, а `GET /health/live` — `200`
|
||||
|
||||
#### Scenario: Сервис остановлен
|
||||
|
||||
- **WHEN** процесс получил сигнал остановки и перестал принимать новую работу
|
||||
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable` либо соединение не устанавливается
|
||||
|
||||
### Requirement: Логи без содержимого сообщений
|
||||
|
||||
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и `X-Request-Id`. Логи SHALL NOT содержать текста сообщений, `display_name`, паролей, токенов сессий, значений заголовка `Authorization`, строк подключения к хранилищам и тел запросов.
|
||||
|
||||
#### Scenario: Запись о запросе присутствует
|
||||
|
||||
- **WHEN** обработан любой запрос к API
|
||||
- **THEN** в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
|
||||
|
||||
#### Scenario: Текст сообщения не попадает в логи
|
||||
|
||||
- **WHEN** отправлено сообщение с известным текстом-маркером
|
||||
- **THEN** этот текст отсутствует в stdout и stderr процесса
|
||||
|
||||
#### Scenario: Учётные данные не попадают в логи
|
||||
|
||||
- **WHEN** пользователь зарегистрировался, вошёл и выполнил запрос с токеном
|
||||
- **THEN** ни пароль, ни токен, ни значение `Authorization` не встречаются в stdout и stderr процесса
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Состояние живёт только в памяти процесса
|
||||
|
||||
**Reason**: С лабы 2 обязательное состояние хранится в PostgreSQL и переживает рестарт процесса.
|
||||
**Migration**: Требования `lab2-persistent-storage`.
|
||||
+123
@@ -0,0 +1,123 @@
|
||||
## Purpose
|
||||
|
||||
Определяет, как пользователь доказывает знание пароля, получает непрозрачную сессию с абсолютным сроком жизни, предъявляет её на защищённых endpoint и отзывает её. Заменяет учебную идентификацию `X-User-Id` лабы 1.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Пароль хранится только как password KDF
|
||||
|
||||
Сервис SHALL хранить пароль пользователя только в виде хеша библиотечного password KDF Argon2id с солью. Пароль, его хеш и сессионные данные SHALL NOT входить в объект `User` и SHALL NOT попадать в журнал. Пароль SHALL содержать от 12 до 128 Unicode code points и SHALL NOT состоять только из пробельных символов.
|
||||
|
||||
#### Scenario: В хранилище нет открытого пароля
|
||||
|
||||
- **WHEN** пользователь зарегистрирован с паролем
|
||||
- **THEN** запись пользователя в БД содержит строку, начинающуюся с `$argon2id$`, и не содержит пароля
|
||||
|
||||
#### Scenario: Пароль вне допустимой длины
|
||||
|
||||
- **WHEN** `POST /api/v1/users` содержит `password` короче 12 или длиннее 128 code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, пользователь не создаётся
|
||||
|
||||
#### Scenario: Пароль из одних пробелов
|
||||
|
||||
- **WHEN** `password` состоит только из пробельных символов
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Ответ регистрации без пароля
|
||||
|
||||
- **WHEN** пользователь успешно зарегистрирован
|
||||
- **THEN** тело `201` содержит ровно `id`, `username`, `display_name`, `created_at`
|
||||
|
||||
### Requirement: Вход по Basic выдаёт сессию
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/auth/sessions` только с заголовком `Authorization: Basic <base64(username:password)>` и без тела. Декодирование base64 SHALL быть строгим, разделителем SHALL служить первое двоеточие, пароль SHALL декодироваться как UTF-8. При верных учётных данных ответ SHALL быть `201` с телом `{"token","token_type":"Bearer","expires_at","user"}`, где `token` — непрозрачная случайная строка не короче 32 символов с энтропией не менее 256 бит, `expires_at` — RFC 3339 UTC с `Z`, а `user` совпадает с ответом регистрации. Неверный пароль, неизвестный `username`, отсутствующий и испорченный заголовок SHALL давать одинаковый `401` с кодом `unauthorized` и заголовком `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
|
||||
|
||||
#### Scenario: Успешный вход
|
||||
|
||||
- **WHEN** зарегистрированный пользователь отправляет верные `username:password` в `Basic`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Session`, `token_type` равен `Bearer`
|
||||
- **AND** `user` побайтно равен телу ответа его регистрации, `expires_at` в будущем
|
||||
|
||||
#### Scenario: Неверный пароль и неизвестный пользователь неразличимы
|
||||
|
||||
- **WHEN** приходит `Basic` с неверным паролем существующего пользователя или с несуществующим `username`
|
||||
- **THEN** оба ответа — `401` с кодом `unauthorized` и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`
|
||||
- **AND** тела ответов различаются только `request_id`
|
||||
|
||||
#### Scenario: Испорченный заголовок Basic
|
||||
|
||||
- **WHEN** заголовок отсутствует, содержит другую схему, невалидный base64 или строку без двоеточия
|
||||
- **THEN** ответ `401` с тем же заголовком `WWW-Authenticate: Basic ...`
|
||||
|
||||
#### Scenario: Двоеточие в пароле
|
||||
|
||||
- **WHEN** пароль пользователя содержит двоеточие и он входит по `Basic`
|
||||
- **THEN** ответ `201`: разделителем служит первое двоеточие
|
||||
|
||||
#### Scenario: Тело запроса при входе
|
||||
|
||||
- **WHEN** запрос с верным `Basic` содержит тело
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, сессия не создаётся
|
||||
|
||||
### Requirement: Защищённые endpoint принимают только Bearer
|
||||
|
||||
Все `/api/v1/*`, кроме `POST /api/v1/users` и `POST /api/v1/auth/sessions`, SHALL требовать `Authorization: Bearer <token>`; схема сравнивается без учёта регистра. Отсутствующий, неизвестный, истёкший и отозванный токен, а также `Basic` на этих endpoint SHALL давать `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`. Заголовок `X-User-Id` SHALL игнорироваться: он не даёт доступа и не меняет владельца сессии. Аутентификация SHALL выполняться раньше проверки доступа к ресурсу и раньше валидации пути, параметров и тела.
|
||||
|
||||
#### Scenario: Только X-User-Id
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с `X-User-Id` существующего пользователя и без `Authorization`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: X-User-Id не подменяет владельца
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с `Bearer` пользователя alice и `X-User-Id` пользователя eve
|
||||
- **THEN** ответ `200` с пользователем alice
|
||||
|
||||
#### Scenario: Basic на бизнес-endpoint
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с верным `Basic`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: Неизвестный токен
|
||||
|
||||
- **WHEN** запрос несёт `Bearer` со случайной строкой
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
#### Scenario: Аутентификация раньше валидации
|
||||
|
||||
- **WHEN** `POST /api/v1/chats/not-a-uuid/messages` приходит без `Authorization` и с испорченным JSON
|
||||
- **THEN** ответ `401`, а не `400`
|
||||
|
||||
### Requirement: Абсолютный срок жизни сессии
|
||||
|
||||
Срок жизни сессии SHALL задаваться `SESSION_TTL_SECONDS` (по умолчанию 3600) от момента входа и SHALL NOT продлеваться ни использованием, ни рестартом сервиса. После `expires_at` токен SHALL давать `401`.
|
||||
|
||||
#### Scenario: Срок назначен при входе
|
||||
|
||||
- **WHEN** пользователь вошёл
|
||||
- **THEN** `expires_at` равен моменту входа плюс `SESSION_TTL_SECONDS` секунд
|
||||
|
||||
#### Scenario: Истёкший токен
|
||||
|
||||
- **WHEN** сервис запущен с `SESSION_TTL_SECONDS=2` и токен предъявлен через 3 секунды после входа
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
### Requirement: Отзыв текущей сессии
|
||||
|
||||
`DELETE /api/v1/auth/sessions/current` SHALL отзывать предъявленный токен и отвечать `204` без тела. После отзыва этот токен SHALL давать `401`, в том числе на повторный `DELETE`. Остальные сессии того же пользователя SHALL оставаться действительными.
|
||||
|
||||
#### Scenario: Выход
|
||||
|
||||
- **WHEN** пользователь отправляет `DELETE /api/v1/auth/sessions/current` со своим токеном
|
||||
- **THEN** ответ `204` с пустым телом и непустым `X-Request-Id`
|
||||
- **AND** следующий `GET /api/v1/users/me` с этим токеном получает `401`
|
||||
|
||||
#### Scenario: Повторный выход
|
||||
|
||||
- **WHEN** `DELETE /api/v1/auth/sessions/current` повторяется с уже отозванным токеном
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: Другая сессия не затронута
|
||||
|
||||
- **WHEN** пользователь вошёл дважды и отозвал первую сессию
|
||||
- **THEN** второй токен продолжает получать `200`
|
||||
+76
@@ -0,0 +1,76 @@
|
||||
## Purpose
|
||||
|
||||
Определяет постоянное хранение лабы 2: схему PostgreSQL с ограничениями, версионируемые миграции, атомарность составных операций, сохранность данных и сессий при рестарте и воспроизводимый стенд из репозитория без секретов в Git.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Схема с ограничениями целостности
|
||||
|
||||
PostgreSQL SHALL хранить пользователей, сессии, чаты, участников и сообщения в отдельных таблицах с первичными ключами. Уникальность `username` SHALL обеспечиваться ограничением БД. Участник чата SHALL ссылаться на существующего пользователя и существующий чат, сообщение SHALL ссылаться на участника своего чата, сессия — на пользователя. Схема SHALL дублировать правила контракта проверками `CHECK` (формат `username`, длины строк).
|
||||
|
||||
#### Scenario: Ограничения видны в схеме
|
||||
|
||||
- **WHEN** оператор выполняет `\d+` по таблицам `users`, `chat_members`, `messages`
|
||||
- **THEN** видны `PRIMARY KEY`, `UNIQUE (username)` и внешние ключи `chat_members → users, chats`, `messages → chat_members`
|
||||
|
||||
#### Scenario: Сообщение от постороннего не записывается даже в обход API
|
||||
|
||||
- **WHEN** в `messages` вставляется строка, отправитель которой не состоит в чате
|
||||
- **THEN** вставка отклоняется нарушением внешнего ключа
|
||||
|
||||
### Requirement: Версионируемые миграции
|
||||
|
||||
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одноразовым процессом до старта API, одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой.
|
||||
|
||||
#### Scenario: Миграции с пустого volume
|
||||
|
||||
- **WHEN** стенд поднимается на пустом volume PostgreSQL
|
||||
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартует API
|
||||
|
||||
#### Scenario: Повторный запуск
|
||||
|
||||
- **WHEN** процесс миграций запускается повторно на той же БД
|
||||
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
|
||||
|
||||
#### Scenario: Изменённая миграция
|
||||
|
||||
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
|
||||
- **THEN** процесс завершается ненулевым кодом и схему не трогает
|
||||
|
||||
### Requirement: Атомарное создание чата
|
||||
|
||||
Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся.
|
||||
|
||||
#### Scenario: Неизвестный участник откатывает чат
|
||||
|
||||
- **WHEN** `POST /api/v1/chats` содержит в `member_ids` UUID несуществующего пользователя
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** в БД нет ни чата с этим `title`, ни его участников
|
||||
|
||||
### Requirement: Данные и сессии переживают рестарт
|
||||
|
||||
Пользователи, чаты, участники, сообщения и ещё действующие сессии SHALL сохраняться при перезапуске API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же.
|
||||
|
||||
#### Scenario: Полный рестарт стенда
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** hook перезапускает API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`
|
||||
|
||||
#### Scenario: Логаут после рестарта
|
||||
|
||||
- **WHEN** после рестарта пользователь отзывает прежний токен
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
### Requirement: Воспроизводимый стенд из репозитория
|
||||
|
||||
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck. Наружу SHALL публиковаться только API на `127.0.0.1:8080`. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, и SHALL NOT появляться в Git, образе и журнале.
|
||||
|
||||
#### Scenario: Подъём из чистого clone
|
||||
|
||||
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
|
||||
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` отвечает `200`
|
||||
|
||||
#### Scenario: Секреты и volumes вне Git
|
||||
|
||||
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url .env`
|
||||
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
@@ -0,0 +1,52 @@
|
||||
## 1. Перенос решения лабы 1
|
||||
|
||||
- [x] 1.1 Перенести из `mtusi2026lab1` (ветка `solution/bpi2303-kostylev`) `src/`, `student-tests/`, `Dockerfile`, `pyproject.toml`, `uv.lock`, цели `Makefile`, `.github/workflows/application.yml`, дополнения `.dockerignore`; версия пакета — `1.2.0`
|
||||
- [x] 1.2 Проверка группы: `uv sync --group dev`, `make lint`, `make check` проходят на перенесённом коде
|
||||
|
||||
## 2. Схема и миграции
|
||||
|
||||
- [x] 2.1 Написать `src/messenger/migrations/0001_init.sql`: таблицы `users`, `sessions`, `chats`, `chat_members`, `messages` с PK, FK, `UNIQUE(username)`, `CHECK` и индексами из design D2
|
||||
- [x] 2.2 Платформа `shared/infrastructure/postgres.py`: `Database` (ленивый пул, таймауты, `ping`, классификация отказа в `Unavailable`) и база `PostgresUnitOfWork`; `Unavailable` в `shared/application/errors.py`
|
||||
- [x] 2.3 Runner `src/messenger/migrate.py`: advisory lock, `schema_migrations` с checksum, транзакция на файл, отказ на изменённой миграции
|
||||
- [x] 2.4 Источник настроек `<ИМЯ>_FILE` в `shared/config.py`; `database_url` и параметры пула в `PlatformSettings`; приложение не читает `.env`
|
||||
- [x] 2.5 Проверка группы: тест runner-а — с нуля применяет все версии, повтор ничего не меняет, изменённая миграция отклоняется
|
||||
|
||||
## 3. Зона `identity`
|
||||
|
||||
- [x] 3.1 Домен: объект-значение `Password`, поле `password_hash` у `User`, сущность `Session` с выпуском токена и `sha256`, события `SessionOpened` и `SessionClosed`
|
||||
- [x] 3.2 Приложение: порты `PasswordHasher`, `SessionRepository`, `SessionDirectory`, расширенные `UserDirectory`/`IdentityUnitOfWork`; команды и обработчики `RegisterUser` (с паролем), `OpenSession`, `CloseSession`; запросы `VerifyCredentials` (с фиктивной проверкой) и `Authenticate`
|
||||
- [x] 3.3 Инфраструктура: адаптер Argon2id в пуле потоков под семафором; адаптеры PostgreSQL пользователей и сессий; `UsernameAlreadyTaken` из `ON CONFLICT DO NOTHING`
|
||||
- [x] 3.4 Точка входа: `IdentitySettings` (`SESSION_TTL_SECONDS`, `PASSWORD_HASH_CONCURRENCY`), схемы `CreateUserRequest` с `password` и `SessionOut`, роутеры `/api/v1/users` и `/api/v1/auth/sessions`, провайдер DI, журнал
|
||||
- [x] 3.5 Страж `entrypoints/authentication.py`: строгий парсер `Basic`, разбор `Bearer`, `challenge_for(path)`, публичные маршруты, `X-User-Id` не читается
|
||||
- [x] 3.6 Проверка группы: юнит-тесты `Password`, парсеров `Basic`/`Bearer` и выпуска токена; API-тесты входа, неверного пароля, неизвестного пользователя, Basic на бизнес-endpoint, только `X-User-Id`, выхода и повторного выхода
|
||||
|
||||
## 4. Зона `messaging`
|
||||
|
||||
- [x] 4.1 Домен: `Chat` без истории, с `last_message_at` и правилом `created_at = max(now, last + 1 мкс)`; удалить `HistoryOrderViolated`, проверку известных участников и реестр
|
||||
- [x] 4.2 Приложение: порты `ChatRepository` (`add`, `get` с блокировкой, `append`), `MessagingUnitOfWork`, `ChatDirectory`; удалить `MemberRegistry` и `MemberProjection`
|
||||
- [x] 4.3 Инфраструктура: адаптеры PostgreSQL — создание чата двумя операторами в транзакции с переводом FK-нарушения в `InvalidChatData`, запись сообщения под `FOR UPDATE`, keyset-запросы списка чатов и истории (`limit + 1`), отдельный текст запроса для первой страницы
|
||||
- [x] 4.4 Обязательный `CURSOR_SECRET` (`CURSOR_SECRET_FILE`), удалить случайный секрет и `STORAGE_LOCKING`
|
||||
- [x] 4.5 Проверка группы: API-тесты создания чата с неизвестным участником (`400`, строк нет), пагинации списка и истории, курсора чужого чата, конкурентной записи 100 сообщений от 10 клиентов со строго возрастающим `created_at`
|
||||
|
||||
## 5. Платформа и сборка
|
||||
|
||||
- [x] 5.1 Конвейер: страж возвращает `Rejection` с заголовками, `Unavailable` из стража → `503`; удалить `PIPELINE=layered` и `shared/entrypoints/middleware.py`
|
||||
- [x] 5.2 Обработчики ошибок: `Unavailable` → `503`, `401` из приложения получает challenge зоны; `/health/ready` пингует БД
|
||||
- [x] 5.3 `main.py`: провайдер `Database` с закрытием пула, связывание журналов без проекций; генератор UUIDv7
|
||||
- [x] 5.4 `gunicorn_conf.py`: `uvicorn_worker.UvicornWorker`, `WEB_CONCURRENCY` воркеров
|
||||
- [x] 5.5 Проверка группы: `make lint`, тест границ зон (импорты и SQL зон), `make student-test` зелёные
|
||||
|
||||
## 6. Стенд
|
||||
|
||||
- [x] 6.1 `compose.yaml`: `postgres` по digest с volume `pgdata` и `pg_isready`, `migrate` на образе приложения, `api` на `127.0.0.1:8080` с healthcheck готовности; compose secrets; процессы не от root
|
||||
- [x] 6.2 `scripts/secrets.sh` (`make secrets`): идемпотентная генерация `secrets/*` и `.env` из `.env.example`; дополнить `.env.example` (`CURSOR_SECRET_FILE`, `WEB_CONCURRENCY`)
|
||||
- [x] 6.3 `scripts/restart.sh`: остановить API, перезапустить PostgreSQL, поднять API (с повторным `migrate`), без удаления volumes
|
||||
- [x] 6.4 Цели `Makefile`: `secrets`, `up`, `down`, `reset-data`, `migrate`, `ps`, `logs`, `restart-evidence`; существующие цели skeleton не меняются
|
||||
- [x] 6.5 CI-job приложения: lint и собственные тесты, затем сборка стенда, `make test` и persistence-тест
|
||||
- [x] 6.6 Проверка группы: из чистого состояния `make secrets up`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, повторный `make migrate` без изменений
|
||||
|
||||
## 7. Отчёт и доказательства
|
||||
|
||||
- [x] 7.1 Сохранить в `evidence/` обезличенные выводы: smoke, persistence с `StartedAt` до и после, `\d+` схемы, повторные миграции, `$argon2id$`-префикс, `git check-ignore`, собственные тесты
|
||||
- [x] 7.2 Заполнить `REPORT.md`: шапка, запуск из чистого clone, архитектура и решения, соответствие переменных, строки уровня «3»
|
||||
- [x] 7.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` зелёные
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-28
|
||||
lab: 2
|
||||
@@ -0,0 +1,62 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. После уровня «3» каждая проверка `Bearer` — запрос `SELECT … FROM sessions WHERE token_hash = $1` к PostgreSQL. Пул, таймауты и перевод сетевых ошибок в `503` уже есть, но не проверены на живом стенде. Изменение касается только зоны `identity` (кэш сессий), стенда и тестов; новой связи между зонами нет.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Valkey с одной ролью — кэш сессий, — которую можно назвать, измерить и сломать без потери данных и без открытия доступа.
|
||||
- Каждый отказ зависимости из рубрики проверяется автотестом против стенда с кодом ответа и временем.
|
||||
- Индекс истории обоснован реальным планом на ≥10 000 сообщений.
|
||||
|
||||
**Non-Goals:**
|
||||
- Кэш истории и списков: read-after-write из контракта дороже, чем экономия.
|
||||
- Valkey как единственное хранилище сессий.
|
||||
- Сравнение вариантов индексов, стоимость записи, backup — трек «5».
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Роль Valkey: read-through кэш сессий, PostgreSQL — источник истины
|
||||
|
||||
Порт `SessionDirectory` уже отделяет проверку сессии от хранения. Новый адаптер `CachedSessionDirectory` (`identity/infrastructure/valkey.py`) оборачивает `PostgresSessionDirectory` — паттерн «декоратор» за тем же портом, домен и обработчики не меняются. Ключ — `session:<hex sha256(token)>`, значение — `user_id`, `created_at`, `expires_at`; токен в открытом виде в кэш не попадает.
|
||||
|
||||
- Чтение: `GET`; отметка отзыва → `None` (401); значение → сессия, если `expires_at > now`; промах → PostgreSQL, затем `SET … NX PXAT min(expires_at, now + SESSION_CACHE_TTL_SECONDS)`.
|
||||
- Expiry: `PXAT` от сохранённого `expires_at` (абсолютный срок), а не `EXPIRE ttl` при каждой записи, поэтому повторное заполнение не продлевает сессию. Ограничение `SESSION_CACHE_TTL_SECONDS` (300 с) — страховка: даже при ошибке инвалидации устаревшая запись живёт не дольше пяти минут.
|
||||
- Инвалидация: `CloseSession` сначала пишет отметку отзыва `SET key "-" PXAT expires_at` (перетирая значение), затем удаляет строку в БД. Заполнение идёт только с `NX`, поэтому гонка «читатель достал сессию из БД до удаления и положил её в кэш после» не оживляет токен: его `SET NX` не перетрёт отметку. Если отметку записать нельзя, выход отвечает `503` и строку в БД не трогает — иначе после возвращения Valkey из AOF могла бы ожить закэшированная запись.
|
||||
|
||||
Что получаем: проверка сессии без обращения к БД на горячем пути, `FLUSHALL` безвреден (источник истины цел). Чего стоит: выход зависит от Valkey; ещё один сервис в стенде.
|
||||
|
||||
### D2. Обход недоступного Valkey
|
||||
|
||||
Клиент `redis.asyncio` с таймаутами подключения и чтения 0.2 с и одним немедленным повтором: после рестарта Valkey первая команда на старом соединении падает, повтор идёт уже по новому. Любая ошибка кэша (`RedisError`, `OSError`) на чтении и заполнении глотается: проверка идёт в PostgreSQL. Чтобы не платить таймаут на каждом запросе, простой размыкатель после ошибки пропускает кэш `CACHE_COOLDOWN_SECONDS` (1 с). Запрос при этом не становится анонимным: результат даёт только PostgreSQL, а его отказ — `503`. Готовность от Valkey не зависит: кэш не критичен для обязательного пути.
|
||||
|
||||
### D3. Persistence Valkey
|
||||
|
||||
AOF с `appendfsync always` на volume `valkeydata`: подтверждённая запись отметки отзыва уже на диске, поэтому рестарт или падение Valkey не возвращает закэшированную запись без её отметки. Частота записей низкая (вход, первое чтение сессии, выход), так что fsync на запись не заметен. `everysec` отвергнут: потеря последней секунды могла бы потерять отметку отзыва при живой записи сессии. Пароль `requirepass` лежит в `secrets/valkey.conf`, URL с паролем — в `secrets/cache_url`; процесс Valkey работает от uid 999.
|
||||
|
||||
### D4. Отказ PostgreSQL и пул
|
||||
|
||||
Поведение уже есть с уровня «3»: ленивый пул, `acquire` 1 с, команда 2 с, перевод ошибок в `503`. Здесь оно закрепляется тестами: in-process тест с пулом из одного соединения, занятым тестом, ждёт `503` за время `acquire`; тест стенда останавливает `postgres` и меряет время ответов `/health/ready`, `/users/me` и запроса с неизвестным токеном, затем запускает БД и ждёт восстановления без рестарта API. После остановки PostgreSQL контейнер не имеет DNS-имени, поэтому подключение падает сразу; зависшая БД ограничена таймаутами пула и команды.
|
||||
|
||||
### D5. Экземпляр с коротким TTL
|
||||
|
||||
`api-shortttl` — тот же образ с `SESSION_TTL_SECONDS=2`, один воркер, профиль compose `faults`, порт `127.0.0.1:${SHORTTTL_PORT:-8082}`. Отдельный экземпляр нужен, потому что smoke и persistence требуют TTL ≥300; БД и Valkey общие, что заодно проверяет, что истечение задаёт сессия, а не процесс.
|
||||
|
||||
### D6. Индекс истории и EXPLAIN
|
||||
|
||||
`scripts/sql/seed-history.sql` детерминированно создаёт синтетического пользователя и чат с 20 000 сообщений (`generate_series`, фиксированные UUID, `ON CONFLICT DO NOTHING` — повтор безопасен), `ANALYZE`. `scripts/sql/explain-history.sql` готовит тексты запросов приложения через `PREPARE` и снимает `EXPLAIN (ANALYZE, BUFFERS)` для первой страницы, глубокой keyset-страницы после 10 000-го сообщения и той же страницы через `OFFSET 10000`. Ожидание: keyset — `Index Scan` по `messages_history_idx`, 51 строка; `OFFSET` — тот же индекс, но 10 051 прочитанная строка.
|
||||
|
||||
### D7. Тесты стенда
|
||||
|
||||
`student-tests/stack/` — black-box тесты против поднятого стенда (`BASE_URL`, `SHORTTTL_URL`) с маркером `stack`, по умолчанию исключены из `make student-test`. `make test-faults` поднимает `api-shortttl` и запускает их. Отказы — `docker compose stop/start/restart/exec` подпроцессом; каждый тест возвращает стенд в рабочее состояние в `finally`.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Выход недоступен, пока недоступен Valkey] → осознанный выбор строгой инвалидации; ответ `503` честно говорит клиенту, что сессия ещё жива.
|
||||
- [`appendfsync always` замедляет запись при высокой частоте входов] → входы редки, а каждый вход и так стоит Argon2 (~30 мс) — fsync на этом фоне не виден.
|
||||
- [Тесты отказов меняют общий стенд] → каждый тест восстанавливает сервис в `finally` и ждёт готовности.
|
||||
- [Один повтор удваивает время отказа кэша до 0.4 с] → размыкатель платит его не чаще раза в секунду на воркер; потеря заполнения безвредна, потеря отметки отзыва — `503` клиенту.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Схема БД не меняется. Новый сервис и secrets появляются после `make secrets` (дописывает недостающие файлы) и `make up`. Без `CACHE_URL` приложение работает как на уровне «3».
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
Уровень «3» закрыт: состояние и сессии в PostgreSQL. Рубрика «4» `README.md` требует Valkey с конкретной ролью, политикой expiry и инвалидации; ограниченный пул и таймауты; проверенные гонку регистрации и rollback; индекс истории, обоснованный `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщений; автоматические проверки expiry, logout, неверного пароля и недоступности Valkey и БД. Изменение закрывает строки уровня 4 таблицы доказательств `REPORT.md` и таблицу отказов.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Появляется сервис `valkey` (8.1.11-alpine по digest, AOF `appendfsync always` на volume `valkeydata`, `requirepass` из secret). Роль — read-through кэш сессий поверх PostgreSQL: запись `session:<sha256>` живёт до `expires_at` сессии (`PXAT`, но не дольше `SESSION_CACHE_TTL_SECONDS`), выход пишет tombstone до удаления строки в БД, заполнение идёт `SET NX` и не перетирает tombstone.
|
||||
- Недоступный Valkey обходится за короткий таймаут с размыкателем: проверка сессии уходит в PostgreSQL, неверный токен по-прежнему `401`. Выход при недоступном кэше отвечает `503`: отзыв подтверждается только тогда, когда он виден и в кэше.
|
||||
- Недоступный PostgreSQL даёт `503 unavailable` за ограниченное время на защищённых endpoint и в `/health/ready`; `/health/live` остаётся `200`; после старта БД пул переподключается без рестарта API. Исчерпание пула — `503` по таймауту ожидания соединения.
|
||||
- Отдельный экземпляр `api-shortttl` (профиль `faults`, `SESSION_TTL_SECONDS=2`, порт `SHORTTTL_PORT`) для автотеста истечения.
|
||||
- Собственные тесты стенда (`make test-faults`): гонка 50 регистраций одного `username`, rollback создания чата, expiry, logout, неверный пароль, остановка и рестарт Valkey, `FLUSHALL`, остановка PostgreSQL — с кодами и временем ответа.
|
||||
- `make seed` (≥10 000 сообщений синтетического чата) и `make explain`: планы `EXPLAIN (ANALYZE, BUFFERS)` первой и глубокой keyset-страницы против `OFFSET`.
|
||||
- `scripts/restart.sh` перезапускает и Valkey.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab2-session-cache`: роль Valkey, источник истины, политика expiry и инвалидации, поведение при недоступности, `FLUSHALL` и рестарте кэша.
|
||||
- `lab2-dependency-failures`: ограниченный по времени `503` при отказе PostgreSQL и исчерпании пула, готовность, восстановление без рестарта, запрет анонимного доступа.
|
||||
- `lab2-history-index`: индекс истории, обоснованный планом на ≥10 000 сообщений; страница истории не сканирует всю историю.
|
||||
|
||||
### Modified Capabilities
|
||||
Нет: гонка регистрации и откат создания чата уже записаны требованиями `lab1-messenger-identity` и `lab2-persistent-storage`, здесь добавляются их проверки.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: `identity/infrastructure/valkey.py`, `identity/config.py`, `identity/entrypoints/ioc.py`; тесты `student-tests/api/test_cache.py`, `student-tests/api/test_pool.py`, `student-tests/stack/`.
|
||||
- Стенд: `compose.yaml` (`valkey`, `api-shortttl`), `scripts/secrets.sh`, `scripts/restart.sh`, `scripts/sql/seed-history.sql`, `scripts/sql/explain-history.sql`, `Makefile`, `.env.example`, CI.
|
||||
- Зависимость: `redis` (клиент `redis.asyncio`, протокол совместим с Valkey).
|
||||
- Отчёт: строки уровня «4», таблица отказов, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Кэш истории сообщений и списков чатов не вводится: он рисковал бы нарушить read-after-write из контракта, а нагрузка его не требует. Valkey не становится единственным хранилищем сессий. Сравнение нескольких индексов, стоимость записи, backup и restore — трек «5», следующее изменение. Из Out of scope лабы 2 не появляется ничего.
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
## Purpose
|
||||
|
||||
Определяет поведение API при отказе PostgreSQL и при исчерпании пула соединений: ограниченная по времени ошибка `503` вместо зависания, `500` или анонимного доступа, и восстановление без рестарта процесса.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Отказ PostgreSQL даёт ограниченную ошибку
|
||||
|
||||
При недоступном PostgreSQL защищённые endpoint и `/health/ready` SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` SHALL отвечать `200`.
|
||||
|
||||
#### Scenario: PostgreSQL остановлен
|
||||
|
||||
- **WHEN** сервис `postgres` остановлен
|
||||
- **THEN** `GET /health/ready` и `GET /api/v1/users/me` отвечают `503 unavailable` быстрее 2 с, `GET /health/live` — `200`, ни один ответ не `500`
|
||||
|
||||
#### Scenario: Неизвестный токен при остановленной БД
|
||||
|
||||
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
|
||||
- **THEN** ответ `503`, а не `200`
|
||||
|
||||
### Requirement: Восстановление без рестарта API
|
||||
|
||||
После возвращения PostgreSQL API SHALL восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула.
|
||||
|
||||
#### Scenario: PostgreSQL снова запущен
|
||||
|
||||
- **WHEN** сервис `postgres` запущен после остановки
|
||||
- **THEN** в течение 30 с `/health/ready` отвечает `200`, а прежний токен читает свои данные
|
||||
|
||||
### Requirement: Ограниченный пул соединений
|
||||
|
||||
Каждый процесс API SHALL держать не больше заданного числа соединений с PostgreSQL. Запрос, не получивший соединение за заданное время, SHALL получать `503` и SHALL NOT ждать бесконечно. Все SQL-запросы SHALL быть параметризованными.
|
||||
|
||||
#### Scenario: Пул исчерпан
|
||||
|
||||
- **WHEN** все соединения пула заняты и приходит запрос, требующий БД
|
||||
- **THEN** ответ `503 unavailable` за время ожидания соединения
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
## Purpose
|
||||
|
||||
Определяет, чем обоснован индекс истории сообщений: планом запроса страницы на наборе не меньше 10 000 сообщений и отсутствием полного прохода по истории на каждой странице.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Индекс истории обоснован планом
|
||||
|
||||
Чтение страницы истории SHALL обслуживаться индексом по `(chat_id, created_at, id)` так, что число прочитанных строк и буферов пропорционально `limit`, а не размеру истории чата. Обоснование SHALL быть получено `EXPLAIN (ANALYZE, BUFFERS)` на чате не меньше чем из 10 000 сообщений для первой и для глубокой страницы и сохранено в доказательствах.
|
||||
|
||||
#### Scenario: Первая страница
|
||||
|
||||
- **WHEN** выполняется запрос первой страницы истории с `limit=50` на чате из ≥10 000 сообщений
|
||||
- **THEN** план — `Index Scan` по индексу истории без узла `Sort`, прочитана 51 строка
|
||||
|
||||
#### Scenario: Глубокая страница keyset-курсором
|
||||
|
||||
- **WHEN** выполняется запрос страницы после курсора, указывающего на 10 000-е сообщение
|
||||
- **THEN** план — `Index Scan` с условием по `(created_at, id)`, прочитана 51 строка, без прохода по предыдущим 10 000
|
||||
|
||||
#### Scenario: Сравнение с OFFSET
|
||||
|
||||
- **WHEN** та же глубокая страница запрашивается через `OFFSET 10000`
|
||||
- **THEN** план читает и отбрасывает ≥10 000 строк, что фиксируется рядом с keyset-планом как обоснование выбора курсора
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
## Purpose
|
||||
|
||||
Определяет роль Valkey в лабе 2: read-through кэш сессий поверх PostgreSQL — что в нём лежит, сколько живёт, как инвалидируется при выходе и что происходит при его недоступности, очистке и рестарте.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Кэш сессий поверх источника истины
|
||||
|
||||
Проверка `Bearer`-токена SHALL сначала обращаться к кэшу Valkey по ключу от SHA-256 токена и только при промахе — к PostgreSQL, после чего заполнять кэш. PostgreSQL SHALL оставаться единственным источником истины: в кэш SHALL NOT попадать ничего, чего нет в БД, а запись кэша SHALL NOT жить дольше `expires_at` сессии. Токен в открытом виде SHALL NOT храниться в кэше.
|
||||
|
||||
#### Scenario: Повторная проверка обслуживается кэшем
|
||||
|
||||
- **WHEN** пользователь дважды подряд выполняет `GET /api/v1/users/me` с одним токеном
|
||||
- **THEN** второй запрос находит сессию в Valkey: счётчик попаданий `keyspace_hits` растёт, в кэше есть ключ `session:<sha256>`
|
||||
|
||||
#### Scenario: Срок записи кэша не превышает срок сессии
|
||||
|
||||
- **WHEN** сессия закэширована
|
||||
- **THEN** абсолютный срок жизни ключа (`PEXPIRETIME`) не позже `expires_at` сессии
|
||||
|
||||
### Requirement: Выход инвалидирует кэш
|
||||
|
||||
Отзыв сессии SHALL записывать в кэш отметку отзыва на оставшийся срок сессии до удаления строки в БД, а заполнение кэша после промаха SHALL выполняться только при отсутствии ключа. Отозванный токен SHALL получать `401` и при гонке «чтение заполнило кэш после выхода». Если отметку отзыва записать нельзя, выход SHALL отвечать `503` и SHALL NOT удалять сессию.
|
||||
|
||||
#### Scenario: Отозванный токен не оживает из кэша
|
||||
|
||||
- **WHEN** токен закэширован, после чего пользователь выполняет `DELETE /api/v1/auth/sessions/current`
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
#### Scenario: Выход при недоступном кэше
|
||||
|
||||
- **WHEN** Valkey остановлен и пользователь выполняет `DELETE /api/v1/auth/sessions/current`
|
||||
- **THEN** ответ `503` с кодом `unavailable`, а после запуска Valkey повторный выход отвечает `204`
|
||||
|
||||
### Requirement: Недоступный кэш обходится, но не открывает доступ
|
||||
|
||||
При ошибке или таймауте Valkey проверка сессии SHALL выполняться по PostgreSQL за ограниченное время, а повторные попытки обращения к кэшу SHALL приостанавливаться на короткий интервал. Недействительный токен SHALL получать `401`; запрос SHALL NOT приниматься как анонимный. Недоступность Valkey SHALL NOT переводить `/health/ready` в `503`.
|
||||
|
||||
#### Scenario: Valkey остановлен
|
||||
|
||||
- **WHEN** сервис `valkey` остановлен
|
||||
- **THEN** `GET /api/v1/users/me` с действительным токеном отвечает `200` быстрее 1 с, с неизвестным токеном — `401`, `/health/ready` — `200`, вход по `Basic` — `201`
|
||||
|
||||
### Requirement: Очистка и рестарт кэша безопасны
|
||||
|
||||
Потеря содержимого Valkey (`FLUSHALL`, рестарт без данных) SHALL NOT терять сессии и SHALL NOT оживлять отозванные. Valkey SHALL хранить данные с AOF на именованном volume, чтобы рестарт сохранял тёплый кэш и отметки отзыва.
|
||||
|
||||
#### Scenario: FLUSHALL
|
||||
|
||||
- **WHEN** в Valkey выполнен `FLUSHALL`
|
||||
- **THEN** действующий токен получает `200`, отозванный — `401`
|
||||
|
||||
#### Scenario: Рестарт Valkey
|
||||
|
||||
- **WHEN** сервис `valkey` перезапущен
|
||||
- **THEN** ключи сессий на месте, действующий токен получает `200`, отозванный — `401`
|
||||
@@ -0,0 +1,38 @@
|
||||
## 1. Кэш сессий (зона `identity`)
|
||||
|
||||
- [x] 1.1 Добавить зависимость `redis`; настройки `CACHE_URL`, `SESSION_CACHE_TTL_SECONDS`, `CACHE_TIMEOUT_SECONDS`, `CACHE_COOLDOWN_SECONDS` в `IdentitySettings`
|
||||
- [x] 1.2 Адаптер `CachedSessionDirectory`: чтение с отметкой отзыва, заполнение `SET NX PXAT`, инвалидация отметкой с `503` при отказе, размыкатель
|
||||
- [x] 1.3 Провайдер DI: кэш подключается при заданном `CACHE_URL`, клиент закрывается вместе с контейнером
|
||||
- [x] 1.4 Проверка группы: in-process тесты против одноразового Valkey — попадание в кэш, срок ключа не позже `expires_at`, выход оставляет отметку, гонка заполнения после выхода, обход недоступного кэша, `503` выхода без кэша
|
||||
|
||||
## 2. Отказы PostgreSQL и пул
|
||||
|
||||
- [x] 2.1 In-process тест исчерпания пула: пул из одного занятого соединения → `503` за время ожидания
|
||||
- [x] 2.2 Проверка группы: `make student-test` зелёный
|
||||
|
||||
## 3. Стенд
|
||||
|
||||
- [x] 3.1 `compose.yaml`: `valkey` по digest (uid 999, AOF `always`, volume `valkeydata`, healthcheck с паролем), `CACHE_URL_FILE` в API, `api-shortttl` в профиле `faults`
|
||||
- [x] 3.2 `scripts/secrets.sh` дописывает `valkey.conf` и `cache_url`; `scripts/restart.sh` перезапускает и Valkey; `.env.example` — `SHORTTTL_PORT`
|
||||
- [x] 3.3 Проверка группы: `make up`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
|
||||
## 4. Тесты стенда
|
||||
|
||||
- [x] 4.1 `student-tests/stack/`: фикстуры `BASE_URL`/`SHORTTTL_URL`, вызовы `docker compose`, маркер `stack` вне набора по умолчанию
|
||||
- [x] 4.2 Гонка 50 регистраций одного `username` (1×201 + 49×409, одна строка в БД) и rollback чата с неизвестным участником (строк нет)
|
||||
- [x] 4.3 Expiry на `api-shortttl`, logout и повторный logout, неверный пароль и неизвестный пользователь
|
||||
- [x] 4.4 Остановка и рестарт Valkey, `FLUSHALL`, кэш реально используется (`keyspace_hits`)
|
||||
- [x] 4.5 Остановка PostgreSQL: `503` быстрее 2 с, `live` 200, восстановление без рестарта API
|
||||
- [x] 4.6 Цель `make test-faults`; проверка группы: прогон зелёный, вывод сохранён в `evidence/faults.txt`
|
||||
|
||||
## 5. Индекс истории
|
||||
|
||||
- [x] 5.1 `scripts/sql/seed-history.sql` и `make seed`: 20 000 сообщений синтетического чата, повтор безопасен
|
||||
- [x] 5.2 `scripts/sql/explain-history.sql` и `make explain`: первая и глубокая keyset-страница против `OFFSET` → `evidence/explain-history.txt`
|
||||
- [x] 5.3 Проверка группы: в планах `Index Scan using messages_history_idx`, 51 строка у keyset, ≥10 000 у `OFFSET`
|
||||
|
||||
## 6. Отчёт
|
||||
|
||||
- [x] 6.1 Нагрузка `tests/load.py --concurrency 64`: без `500`, ошибки и задержки в `evidence/load.json`
|
||||
- [x] 6.2 `REPORT.md`: роль Valkey, источник истины, expiry и инвалидация, persistence, пул и таймауты, строки уровня «4», таблица отказов
|
||||
- [x] 6.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-faults` зелёные
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-28
|
||||
lab: 3
|
||||
@@ -0,0 +1,83 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. После уровня «3» стенд — HAProxy 3.2 и сервис `api` с двумя репликами, проверка `GET /health/ready` (`inter 1s fastinter 500ms fall 2 rise 2`, `timeout check 1s`), Docker DNS, повтор на соседнюю реплику только для безопасных запросов. Обвязка уровня «4» (k6, режимы зонда `load`/`detect`, поочерёдный отказ, rolling update) проверена в `.prep` на заглушке и встраивается, а не пишется заново. Чего заготовка доказать не могла — поведение настоящего gunicorn при `SIGTERM`: по сигналу он сразу закрывает listener, и запрос, уже попавший в очередь `accept` закрывающегося сокета, балансировщик видит как обрыв после отправки. Для `GET` и сообщений с ключом это повтор на соседа, для `POST /users`, `/chats` и входа — `502`.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Плановая остановка реплики не порождает ни ошибок, ни повторов балансировщика: реплика уходит из ротации раньше, чем перестаёт принимать соединения.
|
||||
- Период проверок и максимум обнаружения заявлены формулой и подтверждены замером по каждому виду отказа.
|
||||
- Каждый пункт рубрики «4» проверяется одной командой `make`, которая пишет файл в `evidence/` и завершается ненулевым кодом при нарушении.
|
||||
|
||||
**Non-Goals:**
|
||||
- Серии 1/2/4 реплик и поиск насыщения — трек «5».
|
||||
- Изменение схемы БД, доменных зон и контракта.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Вывод из ротации по `SIGTERM` (платформа)
|
||||
|
||||
`gunicorn_conf.MessengerWorker` запускает `DrainingServer` — наследника `uvicorn.Server`, у которого `main_loop` после сигнала остановки ставит флаг `DRAINING` и ждёт `DRAIN_SECONDS`, а уже потом штатный `shutdown` закрывает listener и ждёт принятые запросы. Флаг — `threading.Event` в `shared/entrypoints/health.py`; `/health/ready` при поднятом флаге отвечает `503 unavailable` через обычный реестр ошибок (с `X-Request-Id` и `X-Instance-Id`), `/health/live` — `200`. Каждый воркер получает `SIGTERM` от мастера и поднимает свой флаг; проверка LB попадает в любой воркер и видит `503`.
|
||||
|
||||
Сроки: `DRAIN_SECONDS=2` > максимум обнаружения `503` (`inter + (fall−1)·fastinter` = 1,5 с); uvicorn `timeout_graceful_shutdown = SHUTDOWN_TIMEOUT_SECONDS − DRAIN_SECONDS` = 3 с ≥ ожидание соединения 1 с + `statement_timeout` 2 с; gunicorn `graceful_timeout = SHUTDOWN_TIMEOUT_SECONDS` = 5 с < `docker stop -t 6` в хуке < `stop_grace_period: 8s` < 10 с.
|
||||
|
||||
Что получаем: LB исключает реплику, пока она полностью исправна, и к моменту закрытия listener новых соединений нет — нет ни обрывов, ни повторов (`wretr`/`wredis` в статистике LB). Чего стоит: каждая остановка реплики дольше на 2 с (хук ≈2,5 с вместо 0,7 с), и переопределён приватный `UvicornWorker._serve` — четыре строки, которые придётся сверять при обновлении `uvicorn-worker`. Отвергнуто: shell-обёртка с `trap` в роли PID 1 (ломает прямую доставку сигнала процессу сервера, требование лабы 1); `preStop`-аналога в Compose нет; пауза в хуке до `docker stop` (не защищает `docker compose stop`, `restart.sh` и rolling update).
|
||||
|
||||
### D2. Readiness быстрее проверки LB
|
||||
|
||||
`Database.ping` берёт соединение с таймаутом 0,4 с и выполняет `SELECT 1` с таймаутом 0,4 с: худший ответ 0,8 с < `timeout check 1s`. Раньше пинг мог ждать пул 1 с и запрос ещё 1 с, и при занятом пуле LB видел таймаут проверки вместо явного `503`. Остальные запросы сохраняют свои таймауты.
|
||||
|
||||
### D2a. Возврат в ротацию только после проверок
|
||||
|
||||
Найдено первым прогоном `failover-each`: ошибок не было, но `wredis` в статистике LB был 19 и 49. Журнал HAProxy показал, что слот `server-template`, вышедший из `MAINT (resolution)`, когда остановленный контейнер снова появился в DNS, сразу становится `UP/READY (resolves again)` — до проверок. Запросы шли в ещё не слушающий gunicorn и перенаправлялись на соседа. `default-server … init-state fully-down` (HAProxy ≥ 3.1) делает начальное состояние сервера при старте, появлении через DNS и выходе из обслуживания `DOWN` до `rise 2` успешных проверок. Что получаем: новая и возвращённая реплика не получает трафика раньше готовности, повторов 0. Чего стоит: возврат в ротацию дольше на ≈1 с (две проверки), и старт LB ждёт первых проверок.
|
||||
|
||||
### D3. Цепочка таймаутов — тест, а не только таблица
|
||||
|
||||
| Звено | Значение | Условие |
|
||||
| --- | --- | --- |
|
||||
| LB `timeout server` | 10 с | > `REQUEST_TIMEOUT_SECONDS` |
|
||||
| `REQUEST_TIMEOUT_SECONDS` | 8 с | > `DB_ACQUIRE_TIMEOUT_SECONDS` + `DB_COMMAND_TIMEOUT_SECONDS` |
|
||||
| БД: ожидание соединения + оператор/блокировка | 1 + 2 с | ≤ окна дообработки 3 с |
|
||||
| LB `timeout check` | 1 с | > пинга readiness 0,8 с |
|
||||
| `DRAIN_SECONDS` | 2 с | > `inter + (fall−1)·fastinter` |
|
||||
| `SHUTDOWN_TIMEOUT_SECONDS` | 5 с | > `DRAIN_SECONDS`; < `STOP_TIMEOUT` хука |
|
||||
| `STOP_TIMEOUT` хука | 6 с | < `stop_grace_period` 8 с и < 10 с |
|
||||
| LB `hard-stop-after` | 5 с | < `stop_grace_period` LB 8 с |
|
||||
|
||||
Таймауты API (`DRAIN_SECONDS`, `DB_*`) становятся явными переменными `compose.yaml` со значениями по умолчанию. Тест `student-tests/unit/test_timeouts.py` читает умолчания из `compose.yaml` (PyYAML уже есть в зависимостях uvicorn), параметры из `haproxy.cfg` и `scripts/stop-one.sh` и проверяет все неравенства. Второй тест запускает настоящий gunicorn с тестовой БД, шлёт `SIGTERM` и проверяет D1: `503` на ready и `200` на live в окне, затем закрытый порт и код 0.
|
||||
|
||||
### D4. Измерения: `probe.py load` и `detect`
|
||||
|
||||
`load` — из заготовки: k6 open model (`constant-arrival-rate`, 80 % `POST` сообщения с уникальным ключом, 20 % чтения истории) в сети `edge` бьёт в `lb:8080`, параллельно зонд шлёт сообщение каждые 0,1 с и повторяет тот же ключ после ошибки, а опрос статистики LB 10 раз в секунду пишет число `UP`. Действие стартует через `warmup + lead`. Дополнено: вывод действия в `action.txt` (а не `.log`: `*.log` в `.gitignore`); дельта счётчиков backend `api` (`wretr`, `wredis`, `econ`, `eresp`, `hrsp_5xx`); режим `--expect dip` (реплика выпадает и возвращается: обнаружение, возврат, реплики в окне отказа) и `--expect replace` (минимум `UP` не ниже исходного, после действия только новые реплики); поле `pass` и код выхода по проверкам.
|
||||
|
||||
`detect` переписан: действие запускается фоном, опрос LB идёт одновременно, поэтому для `SIGTERM` видно, что исключение случилось раньше конца хука. Параметры: `--max`, `--until` (сколько `UP` считать отказом, для PostgreSQL — 0), `--within-action`, `--lb-status` (код ответа LB после обнаружения), `--restore` (команда возврата и время до исходного числа `UP`).
|
||||
|
||||
`scripts/detection.sh` — четыре сценария подряд с возвратом между ними: `stop-one.sh` (≤1,5 с и внутри хука), `docker kill` (≤1,5 с), `docker pause` (≤3,5 с), `docker compose stop postgres` (0 `UP` ≤ 1,5 с после остановки, LB `503`). `scripts/failover-each.sh` — по каждой реплике `stop-one.sh`, 10 с без неё, `restore.sh`, всё внутри окна нагрузки.
|
||||
|
||||
### D5. Серия гонок одного ключа
|
||||
|
||||
`probe.py check --rounds 20`: на каждый раунд новый ключ и 8 потоков за барьером; сводка — статусы и реплики по всем раундам, число раундов с одинаковыми телами, с одной копией в истории и с `409` на другой body.
|
||||
|
||||
### D6. Лимиты и изоляция — проверка политики
|
||||
|
||||
`scripts/limits.py` сравнивает `docker compose --profile bench config --format json` и `docker inspect` запущенных контейнеров с политикой в самом скрипте: какие секреты, volumes и сети нужны каждому сервису, у кого есть порты (только `lb`, только `127.0.0.1`), есть ли лимиты CPU/RAM, `container_name`, `read_only` у API. Таблица и нарушения — в `evidence/limits.txt`, код 1 при нарушении.
|
||||
|
||||
### D7. Rolling update с запасом +1
|
||||
|
||||
`scripts/rolling-update.sh` из заготовки: `migrate` один раз, затем для каждой старой реплики `up --no-deps --no-recreate --scale api=N+1` → `healthy` → LB видит N+1 `UP` → `docker stop -t 6` (с окном D1) и `rm` старой. Журнал называет hostname и образ старой и новой реплики. `make rolling-update` собирает образ до начала нагрузки (сборка не искажает замер); `FROM_REV=<коммит>` сначала собирает тот же тег из `git archive <коммит>` и пересоздаёт реплики на нём — так демонстрируется обновление с уровня «3» (без D1) на уровень «4». Схема между ними не меняется; совместимость `0002` с кодом лабы 2 следует из того, что она только добавляет таблицу (D4 change уровня «3»).
|
||||
|
||||
### D8. Генератор нагрузки
|
||||
|
||||
Сервис `k6` (`grafana/k6:2.3.0` по digest) под профилем `bench`: не стартует с `make up`, сеть только `edge`, лимиты 2 CPU / 512m, без секретов; `scripts/k6.sh` запускает его `docker compose run` от uid хоста, чтобы `summary.json` записывался и на Linux. `handleSummary` удаляет `setup_data` с токенами синтетических пользователей.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Окно вывода из ротации удлиняет остановку] → +2 с на реплику в `stop-one.sh`, `restart.sh`, `docker compose down`; бюджеты хука (10 с) и persistence (90 с) не затронуты.
|
||||
- [Флаг вывода из ротации на воркер, а не на контейнер] → мастер шлёт `SIGTERM` всем воркерам одновременно; воркер, перезапущенный мастером во время остановки, не появляется — мастер в остановке новых не порождает.
|
||||
- [Числа нагрузки зависят от Docker Desktop на одном хосте] → цель уровня «4» — отсутствие ошибок и время обнаружения, а не потолок RPS; потолок — трек «5».
|
||||
- [Rolling update меняет только образ] → изменение схемы проверено отдельно (аддитивная `0002`); миграция, ломающая старую версию, потребовала бы двух выпусков (expand/contract), это записано в ограничениях.
|
||||
- [LB и PostgreSQL — по-прежнему единственные точки отказа] → вне рамок лабы, остаётся в ограничениях отчёта.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Схема не меняется. Новый образ совместим со старым стендом: при rolling update со старой версии старые реплики останавливаются без окна (видно по `wredis` > 0), новые — с окном.
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
Уровень «3» показал, что отказ реплики переживается, но не за сколько LB его замечает и что происходит под нагрузкой и при плановой замене. Рубрика «4» `README.md` требует согласованных проверок, таймаутов и остановки по `SIGTERM` с заявленными периодом и максимумом обнаружения, поочерёдного отказа каждой реплики под нагрузкой с RPS, ошибками и временем восстановления, параллельной проверки одного ключа, лимитов и изоляции портов и секретов, rolling update под нагрузкой с однократными совместимыми миграциями. Закрывает строки 4.1–4.4 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Остановка реплики по `SIGTERM` начинается с вывода из ротации: `/health/ready` отвечает `503`, пока балансировщик не исключит реплику (`DRAIN_SECONDS=2` больше максимума обнаружения 1,5 с), и только потом процесс перестаёт принимать соединения и дорабатывает принятые запросы. Общий срок остаётся `SHUTDOWN_TIMEOUT_SECONDS=5` < `docker stop -t 6` < `stop_grace_period: 8s`.
|
||||
- Readiness отвечает быстрее `timeout check` балансировщика: пинг PostgreSQL ограничен 0,4 с на соединение и 0,4 с на запрос.
|
||||
- Цепочку таймаутов проверяет тест по `compose.yaml`, `haproxy.cfg` и хуку.
|
||||
- `make detection`: время обнаружения для `SIGTERM`, `SIGKILL`, зависшего процесса и остановки PostgreSQL, с заявленным максимумом.
|
||||
- `make failover-each`: каждая реплика по очереди останавливается и возвращается под нагрузкой k6; RPS, ошибки, обнаружение, восстановление, счётчики повторов LB.
|
||||
- `make lb-check`: 20 раундов по 8 параллельных `POST` с одним ключом через LB.
|
||||
- `make limits`: лимиты всех сервисов, порты только у `lb`, секреты, volumes и сети по принципу необходимости, нет `container_name`.
|
||||
- `make rolling-update`: замена реплик по одной с запасом +1 под нагрузкой, `migrate` один раз до замены; `FROM_REV` поднимает прежнюю версию из Git для настоящего обновления.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab3-failover-operations`: период и максимум обнаружения, поочерёдный отказ под нагрузкой, параллельная идемпотентность через LB, лимиты и изоляция, rolling update и однократные миграции.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-service-operability`: «Корректное завершение по сигналу» — сначала вывод из ротации, затем закрытие приёма.
|
||||
- `lab2-dependency-failures`: «Отказ PostgreSQL даёт ограниченную ошибку» — балансировщик исключает все реплики и сам отвечает `503`.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: платформа (`gunicorn_conf.py`, `shared/entrypoints/health.py`, пинг в `shared/infrastructure/postgres.py`); доменные зоны не меняются.
|
||||
- Стенд: `compose.yaml` (`k6` под профилем `bench`, явные таймауты API), `infra/k6/messages.js`, `scripts/` (`probe.py load|detect`, `detection.sh`, `failover-each.sh`, `rolling-update.sh`, `k6.sh`, `limits.py`), `Makefile`, CI.
|
||||
- Тесты: остановка gunicorn, цепочка таймаутов, отказ PostgreSQL через LB.
|
||||
- Отчёт: строки 4.1–4.4, таблица обнаружения и отказов, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Серии 1/2/4 реплик и поиск насыщения — трек «5», следующее изменение. Схема БД не меняется. Из Out of scope ничего: Swarm, HA PostgreSQL и LB, alias реплики (лаба 7).
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Корректное завершение по сигналу
|
||||
|
||||
По получении `SIGTERM` сервис SHALL сначала выйти из ротации: на время окна `DRAIN_SECONDS` (по умолчанию 2 с, больше максимального времени обнаружения балансировщиком) `/health/ready` SHALL отвечать `503 unavailable`, а принятые и новые запросы SHALL обслуживаться как обычно. После окна сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс; весь срок, включая окно, SHALL укладываться в `SHUTDOWN_TIMEOUT_SECONDS` (по умолчанию 5 с), который меньше таймаута хука остановки, `stop_grace_period` контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
|
||||
|
||||
#### Scenario: Остановка укладывается в срок
|
||||
|
||||
- **WHEN** запущенному контейнеру послан `SIGTERM`
|
||||
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
|
||||
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
|
||||
|
||||
#### Scenario: Сначала вывод из ротации
|
||||
|
||||
- **WHEN** процессу сервера послан `SIGTERM`
|
||||
- **THEN** в течение окна `DRAIN_SECONDS` `/health/ready` отвечает `503` в общем формате ошибки, `/health/live` — `200`, соединения ещё принимаются, а после окна порт закрыт и процесс завершается с кодом 0 не позднее `SHUTDOWN_TIMEOUT_SECONDS`
|
||||
|
||||
#### Scenario: Принятый запрос дорабатывается
|
||||
|
||||
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
|
||||
- **THEN** этот запрос получает ответ до завершения процесса
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Отказ PostgreSQL даёт ограниченную ошибку
|
||||
|
||||
При недоступном PostgreSQL защищённые endpoint и `/health/ready` каждой реплики SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` реплики SHALL отвечать `200`. Балансировщик SHALL исключить все реплики из ротации не позднее чем через 1,5 с после отказа и SHALL сам отвечать на любой запрос `503` в общем формате ошибки с `request_id`, равным `X-Request-Id`; после возвращения PostgreSQL реплики SHALL вернуться в ротацию без перезапуска.
|
||||
|
||||
#### Scenario: PostgreSQL остановлен
|
||||
|
||||
- **WHEN** сервис `postgres` остановлен
|
||||
- **THEN** `GET /health/ready` и `GET /api/v1/users/me` через LB отвечают `503 unavailable` быстрее 2 с, `GET /health/live` внутри реплики — `200`, ни один ответ не `500`
|
||||
|
||||
#### Scenario: Неизвестный токен при остановленной БД
|
||||
|
||||
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
|
||||
- **THEN** ответ `503`, а не `200`
|
||||
|
||||
#### Scenario: Балансировщик исключает все реплики
|
||||
|
||||
- **WHEN** PostgreSQL остановлен дольше времени обнаружения
|
||||
- **THEN** статистика LB показывает 0 готовых реплик, а запрос через LB, включая `GET /health/live`, получает `503 {"error":{"code":"unavailable",...}}` без `X-Instance-Id`
|
||||
- **AND** после запуска PostgreSQL все реплики снова готовы в LB без перезапуска своих процессов
|
||||
+85
@@ -0,0 +1,85 @@
|
||||
## Purpose
|
||||
|
||||
Определяет эксплуатационные гарантии реплицированного стенда: за какое время балансировщик исключает отказавшую реплику, как переживается поочерёдный отказ и плановая замена реплик под нагрузкой, как проверяется общая идемпотентность параллельными запросами и как ограничены ресурсы, порты, секреты и хранилища.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Согласованные проверки, таймауты и остановка
|
||||
|
||||
Балансировщик SHALL проверять каждую реплику `GET /health/ready` с периодом 1 с, после первого провала — каждые 0,5 с, исключать её после 2 провалов подряд и возвращать после 2 успехов. Реплика, которая появилась или вернулась через DNS (запуск, `restore.sh`, новая реплика rolling update), SHALL получать запросы только после 2 успешных проверок, а не сразу после появления адреса. Максимальное время обнаружения SHALL составлять 1,5 с для реплики, которая отвечает `503` или отказывает в соединении, и 3,5 с для зависшей реплики (с таймаутом проверки 1 с). Readiness реплики SHALL отвечать быстрее таймаута проверки. Цепочка таймаутов SHALL убывать от внешнего звена к внутреннему: ожидание ответа балансировщиком > таймаут запроса в приложении > таймаут оператора и ожидания соединения с БД. Срок остановки реплики SHALL укладываться в таймаут хука остановки, а тот — в `stop_grace_period` и в 10 с.
|
||||
|
||||
#### Scenario: Конфигурация согласована
|
||||
|
||||
- **WHEN** выполняется `make student-test`
|
||||
- **THEN** тест цепочки таймаутов по `compose.yaml`, `infra/haproxy/haproxy.cfg` и `scripts/stop-one.sh` проходит: окно вывода из ротации больше максимума обнаружения, срок остановки меньше таймаута хука, таймаут хука меньше `stop_grace_period` и 10 с, `timeout server` балансировщика больше `REQUEST_TIMEOUT_SECONDS`, а тот больше суммы таймаутов БД
|
||||
|
||||
#### Scenario: Обнаружение измерено по каждому виду отказа
|
||||
|
||||
- **WHEN** выполняется `make detection`
|
||||
- **THEN** для `SIGTERM` через `scripts/stop-one.sh`, `docker kill`, `docker pause` и остановки PostgreSQL в `evidence/detection/*.json` записаны время обнаружения, заявленный максимум и время возврата в ротацию, и каждое время обнаружения не больше заявленного максимума
|
||||
|
||||
#### Scenario: Остановка по сигналу не теряет запросы
|
||||
|
||||
- **WHEN** реплике посылается `SIGTERM` через `scripts/stop-one.sh`
|
||||
- **THEN** балансировщик исключает её раньше, чем хук завершился, а реплика закрывает приём соединений только после этого
|
||||
|
||||
#### Scenario: Возврат реплики без преждевременного трафика
|
||||
|
||||
- **WHEN** остановленная реплика запускается снова под нагрузкой
|
||||
- **THEN** балансировщик не направляет на неё запросы, пока она не прошла 2 проверки готовности: счётчики повторов и перенаправлений LB (`wretr`, `wredis`) за прогон равны 0
|
||||
|
||||
#### Scenario: Зависшая реплика
|
||||
|
||||
- **WHEN** процесс реплики приостановлен (`docker pause`) и не отвечает на проверки
|
||||
- **THEN** балансировщик исключает её не позднее чем через 3,5 с, а после `docker unpause` возвращает в ротацию
|
||||
|
||||
### Requirement: Поочерёдный отказ под нагрузкой
|
||||
|
||||
Оператор SHALL одной командой останавливать каждую реплику по очереди под открытой нагрузкой (постоянная интенсивность запросов, 80 % отправок сообщений и 20 % чтений истории) и возвращать её до остановки следующей. Для каждой реплики SHALL фиксироваться интенсивность и доля ошибок нагрузки, задержки p50/p95/p99, время обнаружения, время возврата в ротацию, ошибки и время восстановления записи зонда, повторяющего неудачную запись с тем же ключом, и счётчики повторов и перенаправлений балансировщика.
|
||||
|
||||
#### Scenario: Каждая реплика по очереди
|
||||
|
||||
- **WHEN** выполняется `make failover-each`
|
||||
- **THEN** `evidence/failover-each/summary.json` содержит запись на каждую реплику; в каждой хук завершился кодом 0, доля ошибок нагрузки не больше 1 %, запись восстановилась не позже 10 с, пока реплика была исключена, её `X-Instance-Id` не встречался, а после возврата она снова обслуживает запросы
|
||||
|
||||
### Requirement: Общая идемпотентность под параллельными запросами
|
||||
|
||||
Параллельные `POST /api/v1/chats/{chat_id}/messages` с одним `Idempotency-Key` и одним телом, распределённые балансировщиком по разным репликам, SHALL создавать ровно одно сообщение и SHALL получать одинаковые ответы `201`; тот же ключ с другим телом SHALL получать `409`.
|
||||
|
||||
#### Scenario: Серия гонок через LB
|
||||
|
||||
- **WHEN** выполняется `make lb-check` (20 раундов по 8 параллельных запросов с одним ключом на раунд)
|
||||
- **THEN** все 160 ответов `201`, их обслужили не менее двух реплик, в каждом раунде тела ответов совпадают, в истории ровно одна копия, а другой body получает `409`
|
||||
|
||||
### Requirement: Лимиты и изоляция
|
||||
|
||||
Каждый сервис стенда, включая генератор нагрузки, SHALL иметь лимиты CPU и памяти. Ни один сервис SHALL NOT задавать `container_name`. Опубликованные порты SHALL быть только у балансировщика и только на `127.0.0.1`. Секреты SHALL монтироваться только сервисам, которые ими пользуются; volumes данных SHALL принадлежать только своему хранилищу; реплики API SHALL работать с корневой файловой системой только для чтения; внутренняя сеть SHALL быть недоступна снаружи, а генератор нагрузки SHALL видеть только балансировщик.
|
||||
|
||||
#### Scenario: Проверка лимитов и изоляции
|
||||
|
||||
- **WHEN** выполняется `make limits`
|
||||
- **THEN** проверка по `docker compose config` и `docker inspect` запущенных контейнеров печатает таблицу сервисов с лимитами, портами, секретами, volumes и сетями в `evidence/limits.txt` и завершается `PASS`; ни у одного контейнера `api` нет опубликованных портов
|
||||
|
||||
#### Scenario: Нарушение политики
|
||||
|
||||
- **WHEN** сервису без необходимости добавлен секрет, порт или `container_name`, либо снят лимит
|
||||
- **THEN** `make limits` перечисляет нарушение и завершается ненулевым кодом
|
||||
|
||||
### Requirement: Поочерёдная замена под нагрузкой и однократные миграции
|
||||
|
||||
Оператор SHALL одной командой заменять реплики новой версией образа по одной: сначала миграции применяются один раз отдельным процессом, затем на каждую старую реплику запускается новая, и старая останавливается только после того, как балансировщик видит новую готовой. Число готовых реплик в балансировщике SHALL NOT опускаться ниже исходного. Миграции SHALL быть совместимы с работающей предыдущей версией (только добавление объектов схемы) либо ограничение SHALL быть описано в `REPORT.md`.
|
||||
|
||||
#### Scenario: Замена под нагрузкой
|
||||
|
||||
- **WHEN** выполняется `make rolling-update`
|
||||
- **THEN** `evidence/rolling/result.json` показывает, что балансировщик ни разу не видел меньше исходного числа готовых реплик, доля ошибок нагрузки не больше 1 %, зонд не потерял записей, а после замены запросы обслуживают только новые контейнеры
|
||||
|
||||
#### Scenario: Обновление с прежней версии
|
||||
|
||||
- **WHEN** выполняется `make rolling-update FROM_REV=<коммит>`
|
||||
- **THEN** стенд сначала поднимается на образе, собранном из этого коммита, а затем заменяется текущей версией с теми же гарантиями; журнал замены называет старый и новый образ каждой реплики
|
||||
|
||||
#### Scenario: Миграции один раз
|
||||
|
||||
- **WHEN** идёт поочерёдная замена
|
||||
- **THEN** `migrate` запускается один раз до замены первой реплики, реплики схему не меняют, а повторный запуск сообщает `up to date`
|
||||
@@ -0,0 +1,35 @@
|
||||
## 1. Остановка и готовность (платформа)
|
||||
|
||||
- [x] 1.1 `DRAINING` в `shared/entrypoints/health.py`: `/health/ready` отвечает `503 unavailable`, пока флаг поднят
|
||||
- [x] 1.2 `DrainingServer` и `MessengerWorker._serve` в `gunicorn_conf.py`: окно `DRAIN_SECONDS`, затем штатная остановка; uvicorn дообрабатывает `SHUTDOWN_TIMEOUT_SECONDS − DRAIN_SECONDS`
|
||||
- [x] 1.3 Пинг readiness: 0,4 с на соединение и 0,4 с на запрос
|
||||
- [x] 1.4 Проверка группы: тесты — ready `503` при флаге и live `200`; настоящий gunicorn по `SIGTERM` держит окно, закрывает порт и выходит с кодом 0 за срок
|
||||
|
||||
## 2. Стенд и таймауты
|
||||
|
||||
- [x] 2.1 `compose.yaml`: явные `DRAIN_SECONDS`, `DB_ACQUIRE_TIMEOUT_SECONDS`, `DB_COMMAND_TIMEOUT_SECONDS` у `api`; сервис `k6` под профилем `bench`; `.env.example`, Dockerfile
|
||||
- [x] 2.2 Тест цепочки таймаутов по `compose.yaml`, `haproxy.cfg` и `scripts/stop-one.sh`
|
||||
- [x] 2.3 HAProxy `init-state fully-down`: вернувшаяся через DNS реплика ждёт `rise 2` проверок
|
||||
- [x] 2.4 Проверка группы: `docker compose --profile bench config --quiet`, `make student-test -k "timeouts or drain"`
|
||||
|
||||
## 3. Нагрузка и зонд
|
||||
|
||||
- [x] 3.1 `infra/k6/messages.js`, `scripts/k6.sh` (запуск от uid хоста)
|
||||
- [x] 3.2 `scripts/probe.py`: `load` (k6 + зонд + опрос LB, `action.txt`, счётчики повторов LB, `--expect dip|replace`, `pass`), `detect` (действие фоном, `--max`, `--until`, `--within-action`, `--lb-status`, `--restore`), `check --rounds`
|
||||
- [x] 3.3 Проверка группы: `make lint`, `make check` (разбор `scripts/*.py` интерпретатором CI), `k6 inspect`
|
||||
|
||||
## 4. Сценарии уровня «4»
|
||||
|
||||
- [x] 4.1 `scripts/detection.sh` и `make detection`: `SIGTERM`, `docker kill`, `docker pause`, остановка PostgreSQL с заявленными максимумами
|
||||
- [x] 4.2 `scripts/failover-each.sh` и `make failover-each`: остановка, 10 с без реплики и возврат каждой реплики под нагрузкой
|
||||
- [x] 4.3 `scripts/limits.py` и `make limits`: политика лимитов, портов, секретов, volumes, сетей
|
||||
- [x] 4.4 `scripts/rolling-update.sh` и `make rolling-update [FROM_REV=…]`: `migrate` один раз, замена с запасом +1, журнал образов
|
||||
- [x] 4.5 Тест отказа PostgreSQL через LB: ответы `503`, live внутри реплики `200`, LB исключает все реплики и сам отвечает `503`
|
||||
- [x] 4.6 CI: `make limits`, `make detection` в acceptance
|
||||
- [x] 4.7 Проверка группы: `make up`, `make limits`, `make lb-check`, `make detection`, `make failover-each`, `make rolling-update FROM_REV=8d28d45`, `make test-faults`
|
||||
|
||||
## 5. Отчёт
|
||||
|
||||
- [x] 5.1 `evidence/`: detection, failover-each, rolling, limits, lb-check, повторные прогоны уровня «3» на новом коде
|
||||
- [x] 5.2 `REPORT.md`: таймауты и обнаружение, строки 4.1–4.4, таблица отказов уровня «4», ограничения
|
||||
- [x] 5.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих реплик
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-28
|
||||
lab: 3
|
||||
@@ -0,0 +1,102 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. Решение лабы 2 уже не держит в процессе ничего, от чего зависит корректность: пользователи, сессии, чаты и сообщения лежат в PostgreSQL, кэш сессий — общий Valkey с отметками отзыва, курсор подписан общим секретом из `secrets/cursor_secret`, порядок истории держит блокировка строки чата, а не часы процесса. Шина событий в памяти обслуживает только журнал аудита. Поэтому несколько реплик — это в основном стенд и два новых правила контракта: `X-Instance-Id` и `Idempotency-Key`. Инфраструктурные заготовки (HAProxy, хуки, зонд) проверены отдельно на заглушке и встраиваются, а не пишутся заново.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Любая реплика взаимозаменяема: ответ не зависит от того, какая реплика обслужила предыдущий запрос клиента.
|
||||
- Остановка реплики видна оператору (`docker ps -a` ↔ `X-Instance-Id`) и не прерывает запись дольше 10 с.
|
||||
- Идемпотентность держит одна транзакция PostgreSQL, без второго хранилища и без маркеров «в обработке».
|
||||
|
||||
**Non-Goals:**
|
||||
- Замер времени обнаружения, поочерёдный отказ под нагрузкой, rolling update — уровень «4».
|
||||
- Очистка истёкших ключей фоновым заданием (см. Risks).
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Compose + HAProxy, один сервис `api` с репликами
|
||||
|
||||
Один compose-service `api` с `deploy.replicas: ${API_REPLICAS:-2}`, без `container_name`, `hostname` и `ports`; перед ним `lb` — HAProxy 3.2.26 LTS по digest, единственный сервис с опубликованными портами `127.0.0.1:${LB_HTTP_PORT:-8080}` и `127.0.0.1:${LB_STATS_PORT:-8404}` (статистика только на чтение, `/healthz` для healthcheck LB). Сети: `edge` (LB) и `backend` с `internal: true` (LB, `api`, `migrate`, `postgres`, `valkey`). Каждому сервису — `deploy.resources.limits`; `api` — `read_only` с `tmpfs /tmp` для heartbeat gunicorn.
|
||||
|
||||
Что получаем: масштаб одним параметром (нужен треку «5»), активные проверки готовности с явными `inter/fall/rise`, статистика `qcur/qtime` и DNS-обнаружение без `docker.sock`. Чего стоит: ещё один процесс на пути запроса. Отвергнуто: Nginx OSS (только пассивные проверки, DNS резолвится на старте), Traefik (нужен `docker.sock`), Swarm (вне Out of scope лабы), отдельные сервисы `api-1/api-2` (ломают масштабирование одного сервиса).
|
||||
|
||||
### D2. Конфигурация балансировщика
|
||||
|
||||
- `server-template api 8 api:8080` + `resolvers docker` (`127.0.0.11`, `hold` 2 с), `init-addr none`: остановленный контейнер пропадает из DNS, слот уходит в `MAINT`, запущенный возвращается сам.
|
||||
- `balance roundrobin`, без `stick`: новое соединение — следующая реплика; тест требует ≥2 `X-Instance-Id` на одном токене.
|
||||
- `option httpchk GET /health/ready`, `inter 1s fastinter 500ms fall 2 rise 2`, `timeout check 1s`.
|
||||
- Повторы: `retries 2`, `option redispatch 1`, `retry-on conn-failure empty-response`; `http-request disable-l7-retry` для всего, кроме `GET` и `POST …/messages` с `Idempotency-Key`. Отказ соединения повторяется всегда (запрос не ушёл), обрыв после отправки — только для безопасных к повтору запросов; `POST /users`, `/chats` и вход не повторяются, как требует `contracts/README.md`.
|
||||
- `option http-server-close`: соединение LB→API не переиспользуется, поэтому при остановке реплики нет гонки за простаивающее keep-alive-соединение.
|
||||
- `X-Request-Id`: непустой входящий до 200 символов пробрасывается, иначе LB генерирует uuid4; приложение эхо-возвращает его. Ответы LB `502/503/504` — JSON формата контракта с тем же `request_id`.
|
||||
- Таймауты: `connect 500ms` < `server 10s` > `REQUEST_TIMEOUT_SECONDS=8` приложения > `statement_timeout` 2 с; `queue 3s`, `maxconn` на сервер `API_SERVER_MAXCONN` (64). Мягкая остановка LB — `SIGUSR1` с `hard-stop-after 5s`.
|
||||
|
||||
### D3. `X-Instance-Id` — hostname контейнера, платформа
|
||||
|
||||
`PlatformSettings.instance_id` по умолчанию берётся из `socket.gethostname()` один раз при сборке приложения; в контейнере это короткий ID, совпадающий с `docker ps` и `.Config.Hostname`. Конвейер `RequestPipeline` ставит заголовок рядом с `X-Request-Id` на каждый ответ, который проходит через него (включая `401`, `413`, `503` по таймауту и `404/405` фреймворка); обработчик необработанных исключений ставит его сам, потому что `500` формирует внешний `ServerErrorMiddleware`, минуя конвейер. Это платформа (`shared/entrypoints`), без доменных понятий.
|
||||
|
||||
Отвергнуто: pid или uuid процесса — при `WEB_CONCURRENCY=2` одна реплика выглядела бы двумя, а `stop-one.sh` не нашёл бы контейнер; `INSTANCE_ID` в compose — одинаков у всех реплик сервиса. Непрозрачный alias вместо hostname — лаба 7.
|
||||
|
||||
### D4. Идемпотентность в зоне `messaging`, одна транзакция
|
||||
|
||||
Миграция `0002_idempotency_keys.sql` (аддитивная, код лабы 2 её не замечает):
|
||||
|
||||
```sql
|
||||
CREATE TABLE idempotency_keys (
|
||||
chat_id uuid NOT NULL,
|
||||
user_id uuid NOT NULL,
|
||||
key text NOT NULL CHECK (key ~ '^[A-Za-z0-9._:-]{1,128}$'),
|
||||
fingerprint bytea NOT NULL CHECK (octet_length(fingerprint) = 32),
|
||||
message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
|
||||
created_at timestamptz NOT NULL,
|
||||
PRIMARY KEY (chat_id, user_id, key),
|
||||
FOREIGN KEY (chat_id, user_id) REFERENCES chat_members (chat_id, user_id)
|
||||
);
|
||||
```
|
||||
|
||||
Область «пользователь + метод + путь + ключ» сводится к `(chat_id, user_id, key)`: ключ бывает только у `POST /api/v1/chats/{chat_id}/messages`. Внешний ключ на `chat_members` держит связь внутри таблиц зоны `messaging` — SQL зоны по-прежнему не читает `users`.
|
||||
|
||||
`PostMessageHandler` в одной транзакции UoW:
|
||||
|
||||
1. `SELECT … FROM chats WHERE id = $1 FOR UPDATE` (уже есть ради порядка истории) → `404`, если чата нет;
|
||||
2. `chat.post(...)` — членство (`404`), затем текст (`400`), в памяти, без записи;
|
||||
3. поиск квитанции `SELECT k.fingerprint, m.* FROM idempotency_keys k JOIN messages m ON m.id = k.message_id WHERE (k.chat_id, k.user_id, k.key) = ($1, $2, $3) AND k.created_at > $4` по первичному ключу; `$4 = now − IDEMPOTENCY_TTL_SECONDS`;
|
||||
4. квитанция есть: отпечаток совпал → вернуть сохранённое сообщение (транзакция откатывается, события не публикуются), иначе `409 conflict`;
|
||||
5. квитанции нет → один оператор: `INSERT messages` + `INSERT idempotency_keys … ON CONFLICT (chat_id, user_id, key) DO UPDATE` (перезапись истёкшего ключа) + `UPDATE chats.last_message_at`; затем `COMMIT`.
|
||||
|
||||
Конкурентные повторы с одним ключом всегда идут в один чат, поэтому ждут на блокировке строки чата; после `COMMIT` первого следующий оператор в `READ COMMITTED` видит квитанцию и отдаёт то же сообщение. Перезапись в шаге 5 безопасна: под той же блокировкой уже проверено, что живой квитанции нет. Если транзакция откатилась (обрыв, `SIGTERM`, таймаут), не остаётся ни сообщения, ни ключа — повтор создаёт сообщение один раз. Ответы `4xx` и `5xx` ничего не пишут.
|
||||
|
||||
Отпечаток — SHA-256 канонического JSON распарсенной модели `CreateMessageRequest` (`model_dump_json`: порядок полей задаёт модель, а не клиент); считается на границе HTTP и передаётся в команду `PostMessage` вместе с ключом. Повтор отдаёт сообщение тем же `MessageOut`, а `created_at` хранится с микросекундами, поэтому тело совпадает строкой. Доменный объект `Receipt` (ключ, отпечаток, сообщение) решает «повтор или конфликт» методом `replay`; ошибка `IdempotencyConflict` зоны отображается в `409 conflict`. Ключ валидируется заголовком FastAPI (`pattern`, 1–128) → `400` через существующий обработчик ошибок валидации.
|
||||
|
||||
Что получаем: атомарность без второго хранилища и без «залипших» ключей. Чего стоит: строка ключа на каждое сообщение и чтение по первичному ключу под уже взятой блокировкой. Отвергнуто: `SET NX` в Valkey (не атомарен с `COMMIT` PostgreSQL), отдельно закоммиченный маркер «processing» (после гибели реплики повтор получал бы `409`), `INSERT … ON CONFLICT DO NOTHING` без блокировки чата (её всё равно требует порядок истории).
|
||||
|
||||
`LockNotAvailableError` (`lock_timeout` при очереди на строку чата) добавляется к ошибкам, которые пул превращает в `503 unavailable`: это транзиентный отказ, а не `500`, и он не сохраняется под ключом.
|
||||
|
||||
### D5. Миграции и старт реплик
|
||||
|
||||
`migrate` — одноразовый сервис на образе приложения под `pg_advisory_lock`; реплики зависят от него `service_completed_successfully` и сами схему не трогают. Повторный запуск (`restart.sh`, rolling update) безопасен: журнал версий и контрольные суммы.
|
||||
|
||||
### D6. Остановка, готовность и процессы
|
||||
|
||||
`SHUTDOWN_TIMEOUT_SECONDS=5` (gunicorn `graceful_timeout` и uvicorn `timeout_graceful_shutdown`) < `stop_grace_period: 8s`; хук останавливает с `docker stop -t 6`, худший случай хука ≈7 с < 10 с. По `SIGTERM` gunicorn закрывает listener: LB получает отказ соединения и повторяет запрос на соседней реплике. `WEB_CONCURRENCY=2` на реплику с лимитом `cpus: 1`, `512m`; пул 8 соединений на воркер: 2 реплики × 2 × 8 = 32 < `max_connections=200`.
|
||||
|
||||
### D7. Хуки и зонд
|
||||
|
||||
- `scripts/stop-one.sh`: среди `docker compose ps -q api` ищет контейнер с `.Config.Hostname == TARGET_INSTANCE_ID`, `docker stop -t 6`; неизвестный ID → код 3. Запускается тестом без shell, поэтому shebang и `chmod +x`.
|
||||
- `scripts/restart.sh`: `stop lb api` → `restart postgres valkey` → `up -d --wait` (заодно повторно `migrate`), volumes не трогаются.
|
||||
- `scripts/restore.sh`: `up -d --no-deps --no-recreate --wait api`, затем `scripts/lb-wait.sh` ждёт, пока статистика LB покажет все реплики `UP`; без этого следующий тест увидит одну реплику.
|
||||
- `scripts/probe.py check`: 40 `GET /users/me` одним токеном и 8 параллельных `POST` с одним ключом; stdlib, синтаксис Python 3.9.
|
||||
|
||||
`api-shortttl` лабы 2 публиковал порт API в обход LB и удаляется; истечение сессии проверяется in-process тестом с коротким TTL.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Таблица ключей растёт вместе с историей] → строка на сообщение (~100 байт против сообщения до 16 КБ), истёкшие ключи перезаписываются при повторном использовании; фоновая очистка — следующий шаг, описан в `REPORT.md`.
|
||||
- [Повтор берёт блокировку строки чата] → повтор так же дёшев, как запись; горячий чат сериализуется и без идемпотентности.
|
||||
- [`X-Instance-Id` раскрывает короткий ID контейнера] → допустимо до лабы 7, где появится alias.
|
||||
- [Цель failover-теста выбирается round robin] → для второй реплики тест повторяется после `restore.sh`; лишний запрос через LB сдвигает очередь.
|
||||
- [LB — единственная точка отказа, как и PostgreSQL] → честно в ограничениях отчёта; HA LB и БД — Out of scope.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
`0002` аддитивна: сначала `migrate`, затем реплики с новым кодом; откат кода не требует отката схемы. Старый API лабы 2 работает на новой схеме, не создавая ключей.
|
||||
@@ -0,0 +1,33 @@
|
||||
## Why
|
||||
|
||||
Решение лабы 2 — один контейнер API с опубликованным портом. Рубрика «3» `README.md` требует ≥2 взаимозаменяемых реплик за одной точкой входа, разные реплики на одном токене, запись ≤10 с после остановки любой реплики и повтор сообщения без дубля; контракт 1.3.0 вводит `X-Instance-Id` и `Idempotency-Key`. Изменение закрывает уровень «3» и строки 3.1–3.5 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Каждый ответ API несёт `X-Instance-Id` — hostname контейнера, один на все воркеры.
|
||||
- `POST /api/v1/chats/{chat_id}/messages` требует `Idempotency-Key` (`^[A-Za-z0-9._:-]{1,128}$`, иначе `400`). Повтор того же JSON тем же пользователем в том же чате в течение `IDEMPOTENCY_TTL_SECONDS` (≥24 ч) возвращает исходный `201` и тот же `Message`, другой JSON — `409`. Ключ и сообщение — одна транзакция PostgreSQL; `4xx` и `5xx` не сохраняются.
|
||||
- Новая аддитивная миграция `0002_idempotency_keys.sql`.
|
||||
- Стенд: HAProxy 3.2 LTS (`lb`) — единственный опубликованный порт; `api` с `deploy.replicas: ${API_REPLICAS:-2}` без портов; проверка `GET /health/ready`, Docker DNS, round robin без sticky; `api-shortttl` с портом в обход LB удаляется.
|
||||
- Хуки `scripts/stop-one.sh`, `scripts/restart.sh`, `scripts/restore.sh`, `scripts/lb-wait.sh` и зонд `scripts/probe.py check`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab3-load-balancing`: единственная точка входа, ≥2 реплики без локального состояния, балансировка без sticky, проверка готовности и DNS-обновление backend, политика повторов LB, хуки остановки реплики и рестарта стенда.
|
||||
- `lab3-idempotent-messages`: обязательный ключ, область, replay/`409`/`400`, TTL, атомарность, конкурентный повтор, повтор после неопределённого исхода.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-messenger-history`: «Отправка сообщения» требует `Idempotency-Key`.
|
||||
- `lab1-service-operability`: «Сквозной идентификатор запроса» дополняется `X-Instance-Id`; «Корректное завершение по сигналу» — срок внутри `stop_grace_period`; «Контейнерная поставка» — API доступен через LB.
|
||||
- `lab2-persistent-storage`: «Воспроизводимый стенд» — наружу только LB, реплики без портов; «Версионируемые миграции» — аддитивные и совместимые с работающей версией; «Данные и сессии переживают рестарт» — рестарт включает LB.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: платформа (`X-Instance-Id`), зона `messaging` (идемпотентная отправка), миграция `0002`.
|
||||
- Стенд: `compose.yaml`, `infra/haproxy/haproxy.cfg`, `scripts/`, `Makefile`, `.env.example`, `pyproject.toml` (ruff для `scripts/*.py`), CI.
|
||||
- Тесты: заголовки, идемпотентность, гонка ключа в реальном PostgreSQL.
|
||||
- Отчёт: строки 3.1–3.5 и переноса lab2 в `REPORT.md`, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Время обнаружения, поочерёдный отказ под нагрузкой, rolling update и измерения лимитов — уровень «4»; серии 1/2/4 реплик — трек «5»; оба — следующие изменения. Из Out of scope не появляется ничего: Swarm, HA PostgreSQL и LB, непрозрачный alias реплики (лаба 7), вложения (лаба 4).
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`.
|
||||
|
||||
#### Scenario: Сообщение отправлено
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Message`
|
||||
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
|
||||
|
||||
#### Scenario: Ключ не передан
|
||||
|
||||
- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Отправитель не берётся из тела запроса
|
||||
|
||||
- **WHEN** тело запроса содержит поле `sender_id`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустой или пробельный текст
|
||||
|
||||
- **WHEN** тело содержит `{"text":""}` или `{"text":" "}`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Текст длиннее предела
|
||||
|
||||
- **WHEN** `text` содержит более 4000 Unicode code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** длина считается в code points, а не в байтах UTF-8
|
||||
|
||||
#### Scenario: Посторонний пишет в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
- **AND** сообщение не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text`
|
||||
- **THEN** ответ `404`, а не `400`
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Сквозной идентификатор запроса
|
||||
|
||||
Каждый ответ сервиса, включая ответы проб, `204` выхода и ответы об ошибках (`404`/`405` неизвестного маршрута, `413`, `500` необработанного исключения), SHALL содержать непустые заголовки `X-Request-Id` и `X-Instance-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое. `X-Instance-Id` SHALL идентифицировать реплику (контейнер), а не отдельный процесс-воркер: значение SHALL быть одинаковым у всех процессов реплики, стабильным на всё время её жизни и SHALL совпадать с hostname контейнера, чтобы оператор мог сопоставить ответ с `docker ps`.
|
||||
|
||||
#### Scenario: Идентификатор присутствует в любом ответе
|
||||
|
||||
- **WHEN** выполняется любой запрос к сервису, успешный или ошибочный
|
||||
- **THEN** ответ содержит непустые `X-Request-Id` и `X-Instance-Id`
|
||||
|
||||
#### Scenario: Клиентский идентификатор сохраняется
|
||||
|
||||
- **WHEN** запрос содержит `X-Request-Id` с непустым значением
|
||||
- **THEN** ответ содержит то же значение
|
||||
|
||||
#### Scenario: Один идентификатор на реплику
|
||||
|
||||
- **WHEN** реплика с несколькими процессами-воркерами обслуживает серию запросов
|
||||
- **THEN** все её ответы несут одно и то же значение `X-Instance-Id`, равное hostname контейнера
|
||||
|
||||
#### Scenario: Необработанное исключение несёт идентификаторы
|
||||
|
||||
- **WHEN** обработка запроса завершается непредвиденным исключением
|
||||
- **THEN** ответ `500` содержит `X-Request-Id` и `X-Instance-Id`
|
||||
|
||||
### Requirement: Корректное завершение по сигналу
|
||||
|
||||
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд; срок мягкой остановки сервера SHALL быть меньше `stop_grace_period` контейнера, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
|
||||
|
||||
#### Scenario: Остановка укладывается в срок
|
||||
|
||||
- **WHEN** запущенному контейнеру послан `SIGTERM`
|
||||
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
|
||||
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
|
||||
|
||||
#### Scenario: Принятый запрос дорабатывается
|
||||
|
||||
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
|
||||
- **THEN** этот запрос получает ответ до завершения процесса
|
||||
|
||||
### Requirement: Контейнерная поставка
|
||||
|
||||
Сервис SHALL собираться из исходников в образ, слушать `0.0.0.0:8080` и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
|
||||
|
||||
#### Scenario: Образ собирается из чистого clone
|
||||
|
||||
- **WHEN** выполняется сборка образа в свежей копии репозитория
|
||||
- **THEN** сборка завершается успешно без обращения к артефактам вне репозитория
|
||||
|
||||
#### Scenario: API доступен на опубликованном порту
|
||||
|
||||
- **WHEN** стенд поднят командой `make up`
|
||||
- **THEN** `GET /health/ready` с хоста через опубликованный порт балансировщика отвечает `200`
|
||||
|
||||
#### Scenario: Процесс работает не от root
|
||||
|
||||
- **WHEN** в работающем контейнере проверяется эффективный пользователь процесса сервера
|
||||
- **THEN** это не `root`, и идентификатор пользователя не равен 0
|
||||
|
||||
#### Scenario: Healthcheck отражает состояние сервиса
|
||||
|
||||
- **WHEN** контейнер запущен и сервис готов
|
||||
- **THEN** статус healthcheck контейнера становится `healthy`
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Версионируемые миграции
|
||||
|
||||
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одним одноразовым процессом до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё.
|
||||
|
||||
#### Scenario: Миграции с пустого volume
|
||||
|
||||
- **WHEN** стенд поднимается на пустом volume PostgreSQL
|
||||
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартуют реплики API
|
||||
|
||||
#### Scenario: Повторный запуск
|
||||
|
||||
- **WHEN** процесс миграций запускается повторно на той же БД
|
||||
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
|
||||
|
||||
#### Scenario: Изменённая миграция
|
||||
|
||||
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
|
||||
- **THEN** процесс завершается ненулевым кодом и схему не трогает
|
||||
|
||||
#### Scenario: Реплики не мигрируют схему
|
||||
|
||||
- **WHEN** стартует или перезапускается реплика API
|
||||
- **THEN** она не применяет миграции; журнал версий меняет только процесс `migrate`
|
||||
|
||||
### Requirement: Данные и сессии переживают рестарт
|
||||
|
||||
Пользователи, чаты, участники, сообщения, ключи идемпотентности и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же.
|
||||
|
||||
#### Scenario: Полный рестарт стенда
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`
|
||||
|
||||
#### Scenario: Логаут после рестарта
|
||||
|
||||
- **WHEN** после рестарта пользователь отзывает прежний токен
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
### Requirement: Воспроизводимый стенд из репозитория
|
||||
|
||||
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны, и SHALL NOT появляться в Git, образе и журнале.
|
||||
|
||||
#### Scenario: Подъём из чистого clone
|
||||
|
||||
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
|
||||
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` через балансировщик отвечает `200`
|
||||
|
||||
#### Scenario: Опубликован только балансировщик
|
||||
|
||||
- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'`
|
||||
- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1`
|
||||
|
||||
#### Scenario: Секреты и volumes вне Git
|
||||
|
||||
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url .env`
|
||||
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
+81
@@ -0,0 +1,81 @@
|
||||
## Purpose
|
||||
|
||||
Определяет идемпотентную отправку сообщения через `Idempotency-Key`: формат и область ключа, повтор и конфликт, срок хранения результата, атомарность записи и поведение при конкурентном повторе через разные реплики и при неопределённом исходе.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Обязательный ключ идемпотентности
|
||||
|
||||
`POST /api/v1/chats/{chat_id}/messages` SHALL требовать заголовок `Idempotency-Key` длиной 1–128 символов из `[A-Za-z0-9._:-]`. Отсутствующий или не соответствующий формату ключ SHALL давать `400` с кодом `invalid_request` в общем формате ошибки; сообщение при этом SHALL NOT сохраняться. Остальные endpoint SHALL NOT требовать ключ.
|
||||
|
||||
#### Scenario: Ключ отсутствует
|
||||
|
||||
- **WHEN** участник отправляет корректное сообщение без `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, история чата не меняется
|
||||
|
||||
#### Scenario: Ключ неверного формата
|
||||
|
||||
- **WHEN** `Idempotency-Key` пустой, длиннее 128 символов или содержит пробел, `/` или не-ASCII символ
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
### Requirement: Повтор возвращает исходный результат
|
||||
|
||||
Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Повтор с тем же ключом и семантически тем же JSON (порядок полей не важен) в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый.
|
||||
|
||||
#### Scenario: Повтор того же тела
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":...}`
|
||||
- **THEN** ответ `201`, тело равно телу первого ответа целиком, в истории одно такое сообщение
|
||||
|
||||
#### Scenario: Тот же ключ, другое тело
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text`
|
||||
- **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся
|
||||
|
||||
#### Scenario: Тот же ключ у другого пользователя
|
||||
|
||||
- **WHEN** другой участник того же чата отправляет сообщение с тем же значением ключа
|
||||
- **THEN** ответ `201` с новым сообщением этого участника
|
||||
|
||||
#### Scenario: Тот же ключ в другом чате
|
||||
|
||||
- **WHEN** участник отправляет в другой свой чат сообщение с уже использованным ключом
|
||||
- **THEN** ответ `201` с новым сообщением в этом чате
|
||||
|
||||
#### Scenario: Срок ключа истёк
|
||||
|
||||
- **WHEN** с момента первой отправки прошло больше `IDEMPOTENCY_TTL_SECONDS` и участник отправляет с тем же ключом другой текст
|
||||
- **THEN** ответ `201` с новым сообщением, а не `409`
|
||||
|
||||
### Requirement: Повтор заново проверяет доступ
|
||||
|
||||
Повтор с известным ключом SHALL снова проверять сессию и членство в чате до выдачи сохранённого результата: отозванный или истёкший токен SHALL получать `401`, посторонний — `404`. Ответы `4xx` и `5xx` SHALL NOT сохраняться как результат ключа: после такого ответа повтор с тем же ключом обрабатывается как первая попытка.
|
||||
|
||||
#### Scenario: Повтор после выхода
|
||||
|
||||
- **WHEN** пользователь отправил сообщение, вышел и повторил запрос с тем же ключом и прежним токеном
|
||||
- **THEN** ответ `401`
|
||||
|
||||
#### Scenario: Ошибка не занимает ключ
|
||||
|
||||
- **WHEN** участник отправил с ключом `K` пустой текст и получил `400`, затем отправил с ключом `K` корректный текст
|
||||
- **THEN** второй ответ `201` с новым сообщением
|
||||
|
||||
#### Scenario: Посторонний с чужим ключом
|
||||
|
||||
- **WHEN** посторонний отправляет в чат запрос с ключом, уже использованным участником
|
||||
- **THEN** ответ `404`, сохранённое сообщение не раскрывается
|
||||
|
||||
### Requirement: Атомарная и общая для реплик идемпотентность
|
||||
|
||||
Сообщение и запись ключа SHALL фиксироваться одной транзакцией PostgreSQL: либо сохраняются оба, либо ни одно. Одновременные запросы с одним ключом и одним телом, пришедшие на разные реплики, SHALL создавать ровно одно сообщение, и каждый из них SHALL получать `201` с одинаковым `Message`. Если исход первой попытки неизвестен клиенту (обрыв, таймаут, остановка реплики), повтор с тем же ключом SHALL возвращать уже сохранённое сообщение либо, если транзакция не была зафиксирована, создавать его ровно один раз.
|
||||
|
||||
#### Scenario: Конкурентный повтор через разные реплики
|
||||
|
||||
- **WHEN** 8 параллельных `POST` с одним ключом и одним телом отправлены через LB
|
||||
- **THEN** все ответы `201` с одинаковым телом, ответы пришли от ≥2 реплик, в истории чата ровно одно такое сообщение
|
||||
|
||||
#### Scenario: Повтор после отказа реплики
|
||||
|
||||
- **WHEN** во время `make test-failover` запрос не получил ответа и повторён с тем же ключом и текстом
|
||||
- **THEN** в истории нет дублей по `id` и `text`, а каждый подтверждённый ответ совпадает с записью истории байт-в-байт
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
## Purpose
|
||||
|
||||
Определяет развёртывание API несколькими взаимозаменяемыми репликами за единственной публичной точкой входа: что видно клиенту, как балансировщик выбирает и исключает реплики, какие запросы он вправе повторить и как оператор останавливает одну реплику и перезапускает стенд.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Единственная точка входа и не менее двух реплик
|
||||
|
||||
Стенд SHALL описываться одним `compose.yaml` и запускаться документированной командой. API SHALL работать не менее чем двумя репликами одного compose-service без `container_name`; их число SHALL задаваться `API_REPLICAS` (по умолчанию 2). Наружу SHALL публиковаться только балансировщик на `127.0.0.1`; порты реплик API SHALL NOT публиковаться. Все реплики SHALL использовать одну общую PostgreSQL и одно общее хранилище сессий.
|
||||
|
||||
#### Scenario: Стенд поднят
|
||||
|
||||
- **WHEN** выполняется `make up`, затем `docker compose ps`
|
||||
- **THEN** работают ≥2 контейнера сервиса `api` в состоянии `healthy`, у них нет опубликованных портов, а единственные опубликованные порты принадлежат сервису `lb`
|
||||
|
||||
#### Scenario: Реплика недоступна в обход балансировщика
|
||||
|
||||
- **WHEN** с хоста выполняется запрос на порт 8080 контейнера реплики
|
||||
- **THEN** соединение не устанавливается: реплика слушает только внутреннюю сеть
|
||||
|
||||
### Requirement: Разные реплики на одной сессии
|
||||
|
||||
Балансировщик SHALL распределять новые соединения по готовым репликам без привязки клиента (sticky session). Реплика SHALL NOT хранить в памяти процесса сессии, ключи идемпотентности и другое состояние, от которого зависит ответ другой реплики: токен, выданный через одну реплику, SHALL приниматься любой другой, а отзыв сессии SHALL действовать на всех репликах сразу.
|
||||
|
||||
#### Scenario: Один токен, несколько реплик
|
||||
|
||||
- **WHEN** клиент с одним Bearer-токеном выполняет 40 запросов `GET /api/v1/users/me`, каждый новым соединением через LB
|
||||
- **THEN** все ответы `200`, а заголовок `X-Instance-Id` принимает не менее двух разных значений
|
||||
|
||||
#### Scenario: Выход действует на всех репликах
|
||||
|
||||
- **WHEN** пользователь выполнил `DELETE /api/v1/auth/sessions/current` через одну реплику
|
||||
- **THEN** следующий запрос с этим токеном получает `401` независимо от того, какая реплика его обслужила
|
||||
|
||||
### Requirement: Готовность backend и обновление адресов
|
||||
|
||||
Балансировщик SHALL активно проверять каждую реплику запросом `GET /health/ready` и SHALL исключать из ротации реплику, которая не отвечает `200`. Адреса реплик SHALL обновляться через DNS без перезапуска балансировщика: остановленная реплика исчезает из ротации, запущенная или пересозданная появляется сама. Ответы, сформированные самим балансировщиком (`502`, `503`, `504`), SHALL иметь тело в общем формате ошибки с `request_id`, равным заголовку `X-Request-Id`.
|
||||
|
||||
#### Scenario: Реплика возвращается в ротацию
|
||||
|
||||
- **WHEN** остановленная реплика снова запущена
|
||||
- **THEN** после успешных проверок готовности балансировщик снова направляет на неё запросы без перезапуска `lb`
|
||||
|
||||
#### Scenario: Нет ни одной готовой реплики
|
||||
|
||||
- **WHEN** все реплики API остановлены
|
||||
- **THEN** запрос через LB получает `503` с телом `{"error":{"code":"unavailable",...}}`
|
||||
|
||||
### Requirement: Повтор запросов балансировщиком
|
||||
|
||||
Балансировщик SHALL повторять на другой реплике запрос, который не удалось отправить из-за отказа соединения. Повтор после того, как запрос мог быть обработан, SHALL допускаться только для `GET` и для `POST /api/v1/chats/{chat_id}/messages` с `Idempotency-Key`. Балансировщик SHALL NOT прозрачно повторять `POST /api/v1/users`, `POST /api/v1/chats` и `POST /api/v1/auth/sessions`.
|
||||
|
||||
#### Scenario: Создание чата не повторяется
|
||||
|
||||
- **WHEN** реплика оборвала соединение во время `POST /api/v1/chats`
|
||||
- **THEN** клиент получает ошибку балансировщика, а не результат повторной отправки на другую реплику
|
||||
|
||||
### Requirement: Остановка одной реплики
|
||||
|
||||
Оператор SHALL иметь исполняемый хук `scripts/stop-one.sh`, который по переменной `TARGET_INSTANCE_ID` находит контейнер реплики с этим `X-Instance-Id`, останавливает только его с сохранением остальных сервисов и volumes, оставляет остановленным и завершается кодом 0 быстрее 10 секунд. Неизвестный идентификатор SHALL давать ненулевой код без остановки чего-либо. Не позднее 10 секунд от запуска хука SHALL продолжаться новые чтения и записи через LB, а подтверждённые сообщения SHALL оставаться доступными. Хук `scripts/restore.sh` SHALL возвращать остановленные реплики и ждать, пока балансировщик снова видит их готовыми.
|
||||
|
||||
#### Scenario: Отказ реплики под запросами
|
||||
|
||||
- **WHEN** выполняется `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
|
||||
- **THEN** тест печатает `PASS: failover preserved confirmed data and existing session`, хук завершился быстрее 10 с, первая успешная запись после хука пришла не позже 10 с от его старта, остановленная реплика больше не отвечает, а `docker ps -a` показывает именно её контейнер в состоянии `exited`
|
||||
|
||||
#### Scenario: Вторая реплика
|
||||
|
||||
- **WHEN** после `scripts/restore.sh` тест повторяется и целью становится другая реплика
|
||||
- **THEN** тест снова проходит
|
||||
|
||||
#### Scenario: Неизвестная реплика
|
||||
|
||||
- **WHEN** хук запущен с `TARGET_INSTANCE_ID`, которому не соответствует ни один контейнер `api`
|
||||
- **THEN** хук завершается ненулевым кодом, и все контейнеры продолжают работать
|
||||
|
||||
### Requirement: Рестарт стенда
|
||||
|
||||
Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL и Valkey с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд снова готов.
|
||||
|
||||
#### Scenario: Полный рестарт сохраняет сессию
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres` и `valkey` после прогона позже, чем до него
|
||||
@@ -0,0 +1,43 @@
|
||||
## 1. Перенос лабы 2
|
||||
|
||||
- [x] 1.1 Перенести контекст агента и историю openspec, переписать `AGENTS.md` и `openspec/config.yaml` под лабу 3
|
||||
- [x] 1.2 Перенести код, собственные тесты, Dockerfile, тулчейн, compose, миграции, скрипты и CI из коммита `8cddb09` лабы 2; влить цели Makefile
|
||||
- [x] 1.3 Проверка группы: `make lint`, `make student-test`, `make check` зелёные до изменений лабы 3
|
||||
|
||||
## 2. Идентификатор реплики (платформа)
|
||||
|
||||
- [x] 2.1 `PlatformSettings.instance_id` по умолчанию из `socket.gethostname()`; заголовок `X-Instance-Id` в конвейере и в обработчике `500`
|
||||
- [x] 2.2 Версия приложения 1.3.0; проверка группы: тесты — `X-Instance-Id` на `200`, `204`, `401`, `404`, `405`, `413`, `500`, одно значение на процесс
|
||||
|
||||
## 3. Схема
|
||||
|
||||
- [x] 3.1 Миграция `0002_idempotency_keys.sql`: PK `(chat_id, user_id, key)`, FK на `chat_members` и `messages`, `CHECK` формата ключа и длины отпечатка
|
||||
- [x] 3.2 Проверка группы: тест миграций — версии `0001`, `0002`, повтор без изменений, ключ без участника отклоняется FK
|
||||
|
||||
## 4. Идемпотентная отправка (зона `messaging`)
|
||||
|
||||
- [x] 4.1 Домен: `Receipt` с `replay`, ошибка `IdempotencyConflict`; команда `PostMessage` с ключом и отпечатком
|
||||
- [x] 4.2 Порт и адаптер PostgreSQL: поиск квитанции с учётом TTL, запись сообщения и ключа одним оператором; `LockNotAvailableError` → `503`
|
||||
- [x] 4.3 Обработчик: блокировка чата → `chat.post` → квитанция → повтор, `409` или запись; `IDEMPOTENCY_TTL_SECONDS` в настройках зоны
|
||||
- [x] 4.4 HTTP: обязательный заголовок `Idempotency-Key` (`400`), отпечаток канонического JSON модели, `409 conflict` в реестре ошибок зоны
|
||||
- [x] 4.5 Проверка группы: тесты — повтор, другое тело `409`, нет и неверный ключ `400`, `4xx` не занимает ключ, другой пользователь и другой чат независимы, повтор после выхода `401`, посторонний `404`, истёкший ключ, 8 конкурентных повторов в реальном PostgreSQL дают одно сообщение; ключ во всех прежних отправках
|
||||
|
||||
## 5. Стенд
|
||||
|
||||
- [x] 5.1 `infra/haproxy/haproxy.cfg` из заготовки: round robin, `httpchk /health/ready`, Docker DNS, политика повторов, JSON-ошибки LB, статистика
|
||||
- [x] 5.2 `compose.yaml`: `lb`, `api` с `deploy.replicas` без портов, сети `edge`/`backend`, лимиты всех сервисов, параметры PostgreSQL, таймауты и `stop_grace_period`; удалить `api-shortttl`
|
||||
- [x] 5.3 `.env.example`, Dockerfile (умолчания таймаутов и воркеров), Makefile (`up`, `down`, `restore`, `lb-check`, `test-faults` без `api-shortttl`), CI-job под лабу 3
|
||||
- [x] 5.4 Проверка группы: `docker compose config --quiet`, `haproxy -c`, `make up`, опубликованы только порты `lb`
|
||||
|
||||
## 6. Хуки и зонд
|
||||
|
||||
- [x] 6.1 `scripts/stop-one.sh`, `scripts/restart.sh` (вместо версии лабы 2), `scripts/restore.sh`, `scripts/lb-wait.sh`
|
||||
- [x] 6.2 `scripts/probe.py` (`check`), ruff для `scripts/*.py`
|
||||
- [x] 6.3 Скрипт доказательства отказа: `docker ps -a` до и после, `make test-failover`, какой контейнер остановлен
|
||||
- [x] 6.4 Проверка группы: `make test`, `make lb-check`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих реплик с `scripts/restore.sh` между ними, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
|
||||
## 7. Отчёт
|
||||
|
||||
- [x] 7.1 `evidence/`: smoke, stack, lb-check, failover по каждой реплике, persistence со `StartedAt`, схема и повтор миграций, KDF, секреты, собственные тесты, окружение
|
||||
- [x] 7.2 `REPORT.md`: запуск из чистого clone, архитектура и решения, роли и сервисы, соответствие переменных, строки 3.1–3.5 и переноса lab2, таблица отказов уровня «3»
|
||||
- [x] 7.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `make test`, persistence и failover зелёные
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-28
|
||||
lab: 4
|
||||
@@ -0,0 +1,155 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. Решение лабы 3 — две зоны (`identity`, `messaging`) за HAProxy с ≥2 репликами, PostgreSQL как источник истины, Valkey как кэш сессий, ASGI-конвейер с лимитом тела 1 MiB по `Content-Length`, UoW с событиями. Реплики уже не держат состояния; вложения добавляют второе хранилище, где транзакции PostgreSQL не действуют. Инфраструктура S3, хуки и сценарии заранее проверены на заглушке в `.prep/lab4` и встраиваются, а не пишутся заново: MinIO community на arm64 не скачивается (`minio/minio` удалён с Docker Hub, quay отвечает 401), поэтому выбран RustFS 1.0.4 + `rc` v0.1.36.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Байты — только в bucket, метаданные — только в PostgreSQL; ни одна реплика не держит файл, от которого зависит ответ другой.
|
||||
- Каждый лимит применяется раньше дорогого шага: заголовок → поток → заголовок изображения → проверка файла.
|
||||
- `201` ровно тогда, когда обе записи подтверждены; любой сбой оставляет только невидимое клиенту состояние.
|
||||
- Зоны по-прежнему не импортируют друг друга и не читают чужие таблицы.
|
||||
|
||||
**Non-Goals:**
|
||||
- Компенсирующий `DeleteObject`, очистка `pending` по grace period, лимит одновременных загрузок и замер памяти — уровень «4».
|
||||
- Reconciler, карантин и глубокая сверка — трек 2.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Зона `attachments` и связь с `messaging`
|
||||
|
||||
Новая зона `attachments/` со слоями `domain` (агрегат `Attachment`, значения `Filename`, `ImageKind`, `ImageInfo`, ошибки, событие `AttachmentStored`), `application` (команда `UploadAttachment`, запросы `GetAttachment` и `OpenAttachment`, порты), `infrastructure` (PostgreSQL, S3, Pillow) и `entrypoints` (роутер, схемы, DI, журнал, реестр ошибок).
|
||||
|
||||
Зоне нужен один ответ от `messaging`: «входит ли пользователь в чат». Порт `ChatMembership.is_member(chat_id, user_id)` объявлен в `attachments/application/ports.py`; адаптер `MessagingMembership` поверх `ChatDirectory.chat_for_member` зоны `messaging` и его провайдер dishka живут в `main.py` — единственном месте, которое знает обе зоны. Целостность в БД держат внешние ключи, а не чужие `SELECT`:
|
||||
|
||||
- `attachments (chat_id, owner_id) → chat_members (chat_id, user_id)`: загрузить можно только в свой чат, гонка с проверкой порта ловится `ForeignKeyViolationError` → `404`;
|
||||
- `message_attachments (attachment_id, chat_id) → attachments (id, chat_id) ON DELETE RESTRICT`: сообщение ссылается только на вложение своего чата, а удалить используемое вложение нельзя. Нарушение (`message_attachments_attachment_fkey`) → `UnknownAttachment` зоны `messaging` → `404`.
|
||||
|
||||
Что получаем: SQL каждой зоны читает только свои таблицы, тест графа импортов остаётся строгим, проверка «вложение этого чата» атомарна с `INSERT` сообщения без чтения таблицы `attachments` из `messaging`. Чего стоит: два запроса (строка вложения + членство) вместо одного `JOIN` на метаданных и скачивании, лишний уникальный индекс `(id, chat_id)`. Отвергнуто: `JOIN chat_members` в SQL зоны `attachments` (нарушает границу), проекция членства через события в памяти (не переживает рестарт, расходится между репликами), `SELECT count(*) FROM attachments` из `messaging` (чтение чужой таблицы; внешний ключ даёт то же атомарно).
|
||||
|
||||
### D2. Схема — миграция `0003_attachments.sql`
|
||||
|
||||
```sql
|
||||
ALTER TABLE messages DROP CONSTRAINT messages_text_check,
|
||||
ADD CONSTRAINT messages_text_check CHECK (char_length(text) <= 4000);
|
||||
|
||||
CREATE TABLE attachments (
|
||||
id uuid PRIMARY KEY,
|
||||
chat_id uuid NOT NULL,
|
||||
owner_id uuid NOT NULL,
|
||||
filename text NOT NULL CHECK (char_length(filename) BETWEEN 1 AND 255),
|
||||
content_type text NOT NULL CHECK (content_type IN ('image/png', 'image/jpeg')),
|
||||
size_bytes bigint NOT NULL CHECK (size_bytes BETWEEN 1 AND 10485760),
|
||||
sha256 text NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'),
|
||||
width integer NOT NULL CHECK (width > 0),
|
||||
height integer NOT NULL CHECK (height > 0),
|
||||
object_key text COLLATE "C" NOT NULL UNIQUE,
|
||||
status text NOT NULL CHECK (status IN ('pending', 'ready')),
|
||||
created_at timestamptz NOT NULL,
|
||||
updated_at timestamptz NOT NULL,
|
||||
CONSTRAINT attachments_chat_key UNIQUE (id, chat_id),
|
||||
CONSTRAINT attachments_owner_fkey FOREIGN KEY (chat_id, owner_id) REFERENCES chat_members (chat_id, user_id)
|
||||
);
|
||||
CREATE INDEX attachments_pending_idx ON attachments (created_at) WHERE status = 'pending';
|
||||
|
||||
CREATE TABLE message_attachments (
|
||||
message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
|
||||
position smallint NOT NULL CHECK (position BETWEEN 0 AND 9),
|
||||
chat_id uuid NOT NULL,
|
||||
attachment_id uuid NOT NULL,
|
||||
PRIMARY KEY (message_id, position),
|
||||
UNIQUE (message_id, attachment_id),
|
||||
CONSTRAINT message_attachments_attachment_fkey FOREIGN KEY (attachment_id, chat_id)
|
||||
REFERENCES attachments (id, chat_id) ON DELETE RESTRICT
|
||||
);
|
||||
CREATE INDEX message_attachments_attachment_idx ON message_attachments (attachment_id);
|
||||
```
|
||||
|
||||
Ни одного `bytea`. `object_key` с `COLLATE "C"` — байтовый порядок, как у листинга S3 (пригодится reconciler). Частичный индекс по `pending` обслуживает будущую очистку и не растёт вместе с готовыми вложениями. `UNIQUE (message_id, attachment_id)` запрещает дубль внутри сообщения; одно вложение в нескольких сообщениях допустимо. Индекс по `attachment_id` обслуживает проверку `RESTRICT`. `CHECK` текста ослаблен до `≤ 4000`: пустой текст с вложением легален, а пустой без вложений по-прежнему отсекает домен (`400`). Миграция аддитивна для кода лабы 3: старая версия не пишет пустой текст и не знает новых таблиц.
|
||||
|
||||
Запросы и индексы: метаданные — `SELECT … FROM attachments WHERE id = $1 AND status = 'ready'` (PK); членство — `chat_members` по PK; история и повтор добавляют `ARRAY(SELECT attachment_id FROM message_attachments WHERE message_id = m.id ORDER BY position)` — коррелированный подзапрос по PK `(message_id, position)`, не больше 100 index scan на страницу, без N+1 запросов из приложения.
|
||||
|
||||
### D3. Загрузка: порядок проверок и память
|
||||
|
||||
Эндпоинт не объявляет тела: FastAPI его не читает, обработчик получает `request.stream()`. Команда `UploadAttachment` несёт поток, и все проверки идут в обработчике в порядке «дешёвое раньше»:
|
||||
|
||||
1. `401` — guard конвейера (как в лабе 3);
|
||||
2. объявленный `Content-Length` больше лимита маршрута → `413` в конвейере, тело не читается;
|
||||
3. членство через порт → `404`;
|
||||
4. `Filename` (1–255 code points, не пробельный, без `/`, `\`, категорий `Cc`) → `400`;
|
||||
5. `Content-Type` (тип без параметров, регистр не важен) ∈ {`image/png`, `image/jpeg`} → иначе `415`;
|
||||
6. чтение потока в `bytearray` со счётчиком и инкрементальным SHA-256: на байте `MAX_UPLOAD_BYTES + 1` → `413`, дальше не читаем;
|
||||
7. проверка изображения (D4) → `415`/`413`;
|
||||
8. запись (D5).
|
||||
|
||||
Лимит тела в конвейере становится зависимым от маршрута: платформа получает пары «шаблон пути → лимит», а `main.py` передаёт шаблон upload из `attachments/entrypoints` и `MAX_UPLOAD_BYTES`; остальным маршрутам остаётся 1 MiB. Память одной загрузки — до 10 MiB: куски тела копятся в списке и один раз склеиваются (на миг склейки — вдвое больше), затем те же байты отдаются и в проверку, и в `PutObject`. Диск не используется (`read_only`, `tmpfs` только для heartbeat). Сколько загрузок идёт одновременно, на уровне «3» не ограничено — лимит и замер на уровне «4».
|
||||
|
||||
### D4. Проверка изображения — Pillow за портом `ImageInspector`
|
||||
|
||||
Адаптер `PillowImageInspector` выполняет проверку в `asyncio.to_thread` под `asyncio.Semaphore(IMAGE_CHECK_CONCURRENCY)`, чтобы не блокировать event loop и не декодировать много файлов разом:
|
||||
|
||||
- `Image.open(..., formats=("PNG", "JPEG"))` читает только заголовок; GIF, WebP, текст, пустое тело → `415`;
|
||||
- формат по сигнатуре ≠ заявленный `Content-Type` → `415` (подмена MIME);
|
||||
- `width * height > MAX_IMAGE_PIXELS` → `413` до любого декодирования; `DecompressionBombError`/`Warning` Pillow (выше его собственного порога) тоже → `413`;
|
||||
- PNG: `verify()` — обход всех чанков с проверкой CRC и `IEND` без распаковки пикселей; JPEG: `draft("RGB", (w/8, h/8))` + `load()` — полное декодирование потока в масштабе 1/8 (≈1/64 памяти). Ошибка → `415`. `LOAD_TRUNCATED_IMAGES` остаётся `False`, обрезанный файл — ошибка.
|
||||
|
||||
Что получаем: тип и целостность по содержимому, память проверки — килобайты для PNG и ≤2 MB для JPEG 40 MP. Чего стоит: `verify()` не распаковывает IDAT, поэтому PNG с правильными CRC, но испорченным zlib-потоком будет принят — оригинал отдаётся побайтно, вреда серверу нет, ограничение записано в отчёт. Отвергнуто: полное декодирование PNG (до 160 MB на 40 MP), `python-magic` (только сигнатура, без структуры).
|
||||
|
||||
### D5. Порядок записи PostgreSQL ↔ S3
|
||||
|
||||
`UploadAttachmentHandler`:
|
||||
|
||||
1. транзакция: `INSERT attachments (…, status='pending', object_key='attachments/<uuid7>')`, `COMMIT`;
|
||||
2. `PutObject(Key=object_key, Body=буфер, ContentType)`;
|
||||
3. транзакция: `UPDATE attachments SET status='ready', updated_at=$2 WHERE id=$1 AND status='pending'`, `COMMIT`; событие `AttachmentStored`;
|
||||
4. `201 Attachment`.
|
||||
|
||||
| Сбой | Что остаётся | Ответ клиенту |
|
||||
| --- | --- | --- |
|
||||
| до шага 1 (обрыв, `413`, `415`) | ничего | ошибка или обрыв |
|
||||
| шаг 1 | ничего | `503` |
|
||||
| шаг 2 | строка `pending` без объекта | `503` |
|
||||
| шаг 3 | строка `pending` и объект | `503` |
|
||||
| после шага 3 | готовое вложение | `201` (или обрыв уже после фиксации) |
|
||||
|
||||
`pending` не видно ни в метаданных, ни в скачивании (`404`), а сообщение на него сослаться не может: id отдаётся клиенту только в `201`. Намерение до `PUT` гарантирует, что у любого объекта под `attachments/` есть строка с тем же ключом, — поэтому на уровне «4» правило «объект без строки старше grace — мусор» безопасно. Отвергнуто: `PUT` до `INSERT` (объект без строки неотличим от свежей загрузки), одна транзакция вокруг `PUT` (соединение PostgreSQL держится на время сети S3).
|
||||
|
||||
### D6. Адаптер S3 — aiobotocore за портом `ObjectStorage`
|
||||
|
||||
Порт: `put(key, data, content_type)`, `open(key) -> ObjectContent(size, chunks)`, `delete(key)`. Адаптер `S3ObjectStorage` держит один клиент aiobotocore на воркер (scope `APP` dishka, async-генератор закрывает клиент при остановке): `signature_version="s3v4"`, `addressing_style="path"` (RustFS без virtual host), регион из `S3_REGION`, `connect_timeout=1`, `read_timeout=2`, `retries={"mode": "standard", "max_attempts": 2}`, `request_checksum_calculation`/`response_checksum_validation="when_required"` (CRC и aws-chunked botocore ≥1.36 ломают часть S3-совместимых серверов). Худший случай операции — 2 × (1 + 2) = 6 с < `REQUEST_TIMEOUT_SECONDS=8` < `timeout server 10s` HAProxy. Обработчик botocore, добавляющий `Expect: 100-continue` к потоковому телу, снят: aiohttp ждёт `100 Continue`, RustFS за прокси портов его не присылает, и `PutObject` висел до read timeout (найдено тестом адаптера). `NoSuchKey`/`404` → `ObjectMissingError` порта; `BotoCoreError`, прочие `ClientError`, `OSError`, `TimeoutError` → `Unavailable` платформы → `503`. Ключи читаются из `*_FILE` настройками зоны и в журнал не попадают.
|
||||
|
||||
LB не повторяет upload: в лабе 3 `disable-l7-retry` снят только для `GET` и `POST …/messages` с ключом; повтор `PutObject` клиентом botocore безопасен, ключ тот же.
|
||||
|
||||
### D7. Метаданные и скачивание
|
||||
|
||||
`GetAttachment`: строка `ready` по PK → членство → `Attachment`, иначе `404`. `OpenAttachment`: то же + `storage.open(key)` **до** отправки заголовков, поэтому `404` (объект пропал, событие `attachment.object_missing` в журнал) и `503` (S3 недоступен) ещё возможны; затем `StreamingResponse` по кускам 64 KiB с `Content-Type` из метаданных, `Content-Length` из S3, `X-Content-Type-Options: nosniff`, `Cache-Control: private, no-store`. `Accept` не учитывается, redirect нет. `X-Request-Id` и `X-Instance-Id` ставит конвейер на `http.response.start`, значит и на поток. `variant` — `Literal["original"]`, иное → `400`.
|
||||
|
||||
### D8. `attachment_ids` в `messaging`
|
||||
|
||||
- `CreateMessageRequest.attachment_ids: list[UUID] = []` — без `max_length` на границе, чтобы членство (`404`) проверялось раньше содержимого; отпечаток `model_dump_json` включает `attachment_ids`, поэтому отсутствующий и `[]` дают один отпечаток, а порядок значим.
|
||||
- `Chat.post(..., attachment_ids)`: членство → `404`; больше 10 или повторы → `InvalidAttachmentList` (`400`); `MessageText` разрешает пустую строку, но не пробельную; пустой текст без вложений → `400`. `Message.attachment_ids: tuple[UUID, ...]`.
|
||||
- `APPEND_MESSAGE` добавляет в тот же оператор `INSERT INTO message_attachments SELECT … FROM unnest($8::uuid[]) WITH ORDINALITY`; внешний ключ проверяется в конце оператора, нарушение откатывает и сообщение, и ключ идемпотентности. `RECEIPT` и история читают `attachment_ids` подзапросом по PK.
|
||||
|
||||
### D9. Стенд
|
||||
|
||||
- `s3`: `rustfs/rustfs:1.0.4@sha256:ed9210d6…`, uid 10001, `read_only` + `tmpfs /tmp`, `cap_drop: ALL`, `RUSTFS_CONSOLE_ENABLE=false`, логи в stdout, root-ключи из `*_FILE`, volume `s3data:/data`, healthcheck `/health/ready`, 1 CPU / 512M, сеть `backend` (internal), портов нет.
|
||||
- `s3-init`: `rustfs/rc:v0.1.36@sha256:ab024bfe…`, `infra/s3/init.sh` — `bucket create --ignore-existing`, `anonymous set private`, политика `messenger-api` из `infra/s3/api-policy.json` (Get/Put/DeleteObject, multipart abort/list, ListBucket, GetBucketLocation на один bucket), пользователь API, lifecycle «abort incomplete multipart за 1 день», самопроверка. `s3-cli` — тот же образ под профилем `tools`, aliases `root`, `api`, `anon`.
|
||||
- `api`: якорь `x-s3-env` подмешивается в `environment` (ключ сервиса заменяет ключ якоря целиком, поэтому не через `x-app`), секреты `s3_access_key_id`, `s3_secret_access_key`, `depends_on: s3-init: service_completed_successfully`.
|
||||
- `scripts/secrets.sh` создаёт hex-секреты S3 (без `:`/`@`, они идут в URL `RC_HOST_*`); `scripts/restart.sh` перезапускает и `s3`, `up --wait` ждёт его `healthy`, поэтому однократное чтение вложения после хука проходит.
|
||||
- Готовность: `/health/ready` от S3 **не** зависит. Иначе при падении S3 LB вывел бы все реплики и отказали бы даже тексты, а ответы LB не несут `X-Instance-Id`. Upload и скачивание при этом получают `503` от приложения.
|
||||
|
||||
### D10. Сценарии и доказательства
|
||||
|
||||
`scripts/lab4_scenarios.py` (stdlib, Python 3.9, импортирует `tests/client.py` для проверки схем и заголовков): `failover-upload` — upload, `stop-one.sh` по `X-Instance-Id` ответа upload, скачивание через другую реплику и сравнение SHA-256, `--restore`; `s3-outage` — `docker compose stop s3`, коды и время upload/скачивания/метаданных/текста/готовности, возврат S3 и повторное скачивание. `scripts/s3-check.sh` — анонимный доступ, порты, консоль, двойной `s3-init`, права ключа API. `scripts/evidence-attachments.sh` — `\d attachments`, листинг bucket, `ReadonlyRootfs` и mounts реплик, сверка байтов вне API. Цели Makefile: `scenario`, `s3-check`, `attachments-evidence`.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Строки `pending` после сбоя S3 или `COMMIT` остаются до уровня «4»] → они невидимы клиенту и не мешают ссылкам; компенсация и очистка с grace — следующее изменение.
|
||||
- [Ранний `413`/`404` до конца тела: клиент, ещё отправляющий 10 MiB, может получить reset] → собственные тесты проверяют `413` через `Content-Length`; поведение описано в отчёте.
|
||||
- [`verify()` PNG не распаковывает пиксели] → принято осознанно (D4), записано в ограничениях.
|
||||
- [RustFS молод (GA 2026-09), одиночный узел без parity — SPOF] → версия и digest закреплены, данные на volume, ограничение в отчёте.
|
||||
- [Одновременные загрузки без лимита держат по 10 MiB каждая] → `API_MEMORY=512m`; лимит параллелизма и замер — уровень «4».
|
||||
|
||||
## Migration Plan
|
||||
|
||||
`make up` на существующем стенде лабы 3: `migrate` применяет `0003` под advisory lock, `s3-init` создаёт bucket, реплики стартуют после обоих. Откат: предыдущий образ работает с новой схемой (новые таблицы ему не нужны, ослабленный `CHECK` его не задевает); `make reset-data` удаляет и `s3data`.
|
||||
@@ -0,0 +1,36 @@
|
||||
## Why
|
||||
|
||||
Решение лабы 3 хранит только текст. Рубрика «3» `README.md` лабы 4 требует вложения-изображения: S3-сервер в общем стенде, метаданные в PostgreSQL, байты в приватном bucket, `201 ready` только после сохранения, побайтное скачивание участником, `404` постороннему, лимиты 10 MiB / 40 млн пикселей и тип по содержимому, переживание остановки обслужившей реплики, рестарта стенда и недоступности S3. Контракт 1.4.0 добавляет три операции и обязательное `Message.attachment_ids`. Изменение закрывает уровень «3» и строки 3.1–3.9 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Новая доменная зона `attachments`: `POST /api/v1/chats/{chat_id}/attachments?filename=…` (сырые байты PNG/JPEG, `201 Attachment` со `status=ready`), `GET /api/v1/attachments/{id}`, `GET /api/v1/attachments/{id}/content?variant=original` (байты через API, без redirect). Доступ — только участникам чата, иначе `404`.
|
||||
- Лимиты до неограниченного чтения и декодирования: `Content-Length` и потоковый счётчик (`413`), размер по заголовку изображения (`413`), сигнатура и проверка файла (`415`), `filename` (`400`). Object key `attachments/<uuid>` назначает сервер.
|
||||
- Порядок записи: строка-намерение `pending` → `PutObject` → `ready` и `COMMIT` → `201`. Недоступный S3 — `503` за ограниченное время; тексты продолжают работать, `/health/ready` от S3 не зависит.
|
||||
- Зона `messaging`: `attachment_ids` (0–10 уникальных, только вложения этого чата, иначе `400`/`404`) в отправке, ответе, повторе и истории; `text=""` допустим только с вложением; отсутствующий `attachment_ids` и `[]` — одно тело для `Idempotency-Key`.
|
||||
- Миграция `0003_attachments.sql`: таблицы `attachments` и `message_attachments`, ослабление `messages_text_check` до `≤ 4000`.
|
||||
- Стенд: RustFS 1.0.4 (`s3`, volume `s3data`, без портов, консоль выключена), одноразовый `s3-init` (`rc`: bucket, anonymous `private`, пользователь API с политикой на один bucket), `s3-cli` под профилем `tools`; S3-переменные и ключи API у `api`; `restart.sh` перезапускает и S3.
|
||||
- Сценарии `scripts/lab4_scenarios.py` (`failover-upload`, `s3-outage`), `scripts/s3-check.sh`, цели Makefile, сбор доказательств.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab4-attachments`: upload, лимиты и проверка содержимого, метаданные, скачивание оригинала, доступ участников, порядок записи PostgreSQL ↔ S3, поведение при недоступном S3.
|
||||
- `lab4-object-storage`: S3-сервер в стенде, приватный bucket и его bootstrap, раздельные ключи root и API, байты не в БД и не на диске реплики, переживание остановки реплики и рестарта.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-messenger-history`: «Отправка сообщения» — `attachment_ids` и пустой текст с вложением; «Чтение истории keyset-курсором» — элементы несут `attachment_ids`.
|
||||
- `lab3-idempotent-messages`: «Повтор возвращает исходный результат» — `attachment_ids` входит в тело, отсутствующий равен `[]`.
|
||||
- `lab3-load-balancing`: «Рестарт стенда» — хук перезапускает и S3, ждёт его готовности.
|
||||
- `lab2-persistent-storage`: «Данные и сессии переживают рестарт» — вложения и их байты; «Воспроизводимый стенд» — S3 без портов, root-ключи только у S3-сервисов.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: новая зона `attachments`, зона `messaging`, платформа (лимит тела по маршруту), `main.py` (порт членства), миграция `0003`; зависимости aiobotocore и Pillow.
|
||||
- Стенд: `compose.yaml`, `infra/s3/`, `scripts/`, `Makefile`, `.env.example`, CI.
|
||||
- Тесты: upload и лимиты, подмена MIME, `filename`, доступ, `attachment_ids`, идемпотентность, адаптер S3 против RustFS.
|
||||
- Отчёт: строки 3.1–3.9 в `REPORT.md`, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Компенсация сбоя между S3 и БД, очистка `pending`, замер памяти под ≥10 загрузками, доказательство ограниченных ключей — уровень «4»; reconciler — трек 2; оба — следующие изменения. Из Out of scope не появляется ничего: `202 queued`, worker и варианты (лаба 5), presigned upload (трек 1), удаление вложений, TLS (лаба 7).
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":..., "attachment_ids":[...]}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL быть обязательным, содержать не более 4000 Unicode code points и SHALL NOT состоять только из пробельных символов; пустая строка допустима только при хотя бы одном вложении. `attachment_ids` SHALL быть необязательным списком из 0–10 уникальных UUID (по умолчанию `[]`); каждое вложение SHALL принадлежать этому чату и быть готовым, иначе ответ `404`. Порядок `attachment_ids` SHALL сохраняться, а одно вложение SHALL допускаться в нескольких сообщениях. Каждый `Message` в ответе SHALL содержать `attachment_ids`, у текстового — `[]`. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`.
|
||||
|
||||
#### Scenario: Сообщение отправлено
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Message`, `attachment_ids` равен `[]`
|
||||
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
|
||||
|
||||
#### Scenario: Сообщение с вложением без текста
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"","attachment_ids":[id]}`, где `id` — готовое вложение этого чата
|
||||
- **THEN** ответ `201`, `attachment_ids` равен `[id]`
|
||||
|
||||
#### Scenario: Порядок вложений сохраняется
|
||||
|
||||
- **WHEN** участник отправляет три вложения чата в порядке `[c, a, b]`
|
||||
- **THEN** ответ и история содержат `attachment_ids` в том же порядке `[c, a, b]`
|
||||
|
||||
#### Scenario: Вложение другого чата или неизвестное
|
||||
|
||||
- **WHEN** `attachment_ids` содержит вложение другого чата того же пользователя или несуществующий UUID
|
||||
- **THEN** ответ `404` с кодом `not_found`, сообщение не сохраняется
|
||||
|
||||
#### Scenario: Слишком много, повторы или не UUID
|
||||
|
||||
- **WHEN** `attachment_ids` содержит 11 элементов, повторяющийся UUID или строку не в формате UUID
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Ключ не передан
|
||||
|
||||
- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Отправитель не берётся из тела запроса
|
||||
|
||||
- **WHEN** тело запроса содержит поле `sender_id`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустой или пробельный текст
|
||||
|
||||
- **WHEN** тело содержит `{"text":""}`, `{"text":"","attachment_ids":[]}` или `{"text":" "}` с вложениями или без
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Текст длиннее предела
|
||||
|
||||
- **WHEN** `text` содержит более 4000 Unicode code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** длина считается в code points, а не в байтах UTF-8
|
||||
|
||||
#### Scenario: Посторонний пишет в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
- **AND** сообщение не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text` или с 11 вложениями
|
||||
- **THEN** ответ `404`, а не `400`
|
||||
|
||||
### Requirement: Чтение истории keyset-курсором
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Каждый элемент SHALL содержать `attachment_ids` в порядке отправки. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами.
|
||||
|
||||
#### Scenario: Первая страница отдаёт курсор
|
||||
|
||||
- **WHEN** в чате два сообщения и запрошено `?limit=1`
|
||||
- **THEN** ответ содержит один элемент и непустой `next_cursor`
|
||||
|
||||
#### Scenario: Последняя страница закрывает историю
|
||||
|
||||
- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1`
|
||||
- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null`
|
||||
- **AND** элемент первой страницы не повторяется
|
||||
|
||||
#### Scenario: Элементы истории несут вложения
|
||||
|
||||
- **WHEN** в чате есть текстовое сообщение и сообщение с вложением
|
||||
- **THEN** у текстового элемента `attachment_ids` равен `[]`, у второго — список его вложений, и оба элемента совпадают с ответами `201`
|
||||
|
||||
#### Scenario: Курсор не привязан к читателю
|
||||
|
||||
- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата
|
||||
- **THEN** страница отдаётся на общих основаниях
|
||||
|
||||
#### Scenario: Курсор от другого чата
|
||||
|
||||
- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Испорченный или подделанный курсор
|
||||
|
||||
- **WHEN** значение `cursor` не является ранее выданным сервером курсором
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Limit вне допустимого диапазона
|
||||
|
||||
- **WHEN** запрос содержит `limit=0` или `limit=101`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Посторонний читает чужую историю
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Данные и сессии переживают рестарт
|
||||
|
||||
Пользователи, чаты, участники, сообщения со ссылками на вложения, ключи идемпотентности, метаданные вложений, их байты в bucket и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ, включая S3, с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, подтверждённое сообщение SHALL читаться побайтно тем же, а загруженное вложение SHALL отдавать те же метаданные и те же байты.
|
||||
|
||||
#### Scenario: Полный рестарт стенда
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`, в том числе после однократного чтения метаданных и байтов вложения
|
||||
|
||||
#### Scenario: Логаут после рестарта
|
||||
|
||||
- **WHEN** после рестарта пользователь отзывает прежний токен
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
### Requirement: Воспроизводимый стенд из репозитория
|
||||
|
||||
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников, bucket и доступ к нему создаёт одноразовый bootstrap. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey, S3 и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны (root-ключи S3 — только S3-сервисам), и SHALL NOT появляться в Git, образе и журнале.
|
||||
|
||||
#### Scenario: Подъём из чистого clone
|
||||
|
||||
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
|
||||
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0 (`migrate`, `s3-init`), а `GET /health/ready` через балансировщик отвечает `200`
|
||||
|
||||
#### Scenario: Опубликован только балансировщик
|
||||
|
||||
- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'`
|
||||
- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1`
|
||||
|
||||
#### Scenario: Секреты и volumes вне Git
|
||||
|
||||
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url secrets/s3_root_password .env`
|
||||
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Повтор возвращает исходный результат
|
||||
|
||||
Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Тело запроса для сравнения SHALL включать `text` и `attachment_ids` с учётом порядка вложений; отсутствующий `attachment_ids` SHALL считаться равным `[]`, порядок полей JSON SHALL NOT иметь значения. Повтор с тем же ключом и семантически тем же JSON в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text`, `attachment_ids` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый.
|
||||
|
||||
#### Scenario: Повтор того же тела
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":...}`
|
||||
- **THEN** ответ `201`, тело равно телу первого ответа целиком, включая `attachment_ids: []`, в истории одно такое сообщение
|
||||
|
||||
#### Scenario: Отсутствующий attachment_ids равен пустому списку
|
||||
|
||||
- **WHEN** первый `POST` содержит `{"text":"x"}`, а повтор с тем же ключом — `{"attachment_ids":[],"text":"x"}`
|
||||
- **THEN** повтор получает `201` с телом первого ответа
|
||||
|
||||
#### Scenario: Повтор сообщения с вложением
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":"","attachment_ids":[id]}`
|
||||
- **THEN** ответ `201` с тем же `Message` и `attachment_ids` равным `[id]`
|
||||
|
||||
#### Scenario: Тот же ключ, другое тело
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text` или другим списком либо порядком `attachment_ids`
|
||||
- **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся
|
||||
|
||||
#### Scenario: Тот же ключ у другого пользователя
|
||||
|
||||
- **WHEN** другой участник того же чата отправляет сообщение с тем же значением ключа
|
||||
- **THEN** ответ `201` с новым сообщением этого участника
|
||||
|
||||
#### Scenario: Тот же ключ в другом чате
|
||||
|
||||
- **WHEN** участник отправляет в другой свой чат сообщение с уже использованным ключом
|
||||
- **THEN** ответ `201` с новым сообщением в этом чате
|
||||
|
||||
#### Scenario: Срок ключа истёк
|
||||
|
||||
- **WHEN** с момента первой отправки прошло больше `IDEMPOTENCY_TTL_SECONDS` и участник отправляет с тем же ключом другой текст
|
||||
- **THEN** ответ `201` с новым сообщением, а не `409`
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Рестарт стенда
|
||||
|
||||
Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL, Valkey и S3-сервер с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд, включая S3, снова готов: первое же чтение метаданных и байтов вложения после хука SHALL проходить без повторов.
|
||||
|
||||
#### Scenario: Полный рестарт сохраняет сессию
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres`, `valkey` и `s3` после прогона позже, чем до него
|
||||
+153
@@ -0,0 +1,153 @@
|
||||
## Purpose
|
||||
|
||||
Определяет вложения-изображения чата: синхронную загрузку оригинала PNG/JPEG с лимитами и проверкой содержимого, метаданные, скачивание оригинала через API, доступ только участникам чата, порядок записи PostgreSQL ↔ S3 и поведение при недоступном S3.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Загрузка оригинала в чат
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` от участника чата с телом из сырых байтов одного изображения (не multipart, не JSON) и заголовком `Content-Type: image/png` или `image/jpeg` и возвращать `201` с объектом `Attachment`: `status` `ready`, `variants` `[]`, `error_code` `null`, `chat_id` из пути, `owner_id` вызывающего, `size_bytes` равен длине тела, `sha256` — lowercase hex SHA-256 тела, `content_type` — тип, определённый по содержимому, `filename` — переданное имя. Ответ `201` SHALL выдаваться только после того, как оригинал записан в приватный bucket и метаданные зафиксированы в PostgreSQL. Ключ объекта SHALL назначаться сервером и SHALL NOT зависеть от `filename` и попадать в ответ. Повтор того же запроса SHALL создавать новое вложение.
|
||||
|
||||
#### Scenario: Fixture загружена
|
||||
|
||||
- **WHEN** участник загружает `tests/fixtures/sample.png` с `Content-Type: image/png` и `?filename=sample.png`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Attachment`, `status` `ready`, `size_bytes` 111817, `sha256` равен SHA-256 файла, `chat_id` и `owner_id` — чат и загрузивший
|
||||
|
||||
#### Scenario: JPEG загружен
|
||||
|
||||
- **WHEN** участник загружает корректный JPEG с `Content-Type: image/jpeg`
|
||||
- **THEN** ответ `201`, `content_type` `image/jpeg`
|
||||
|
||||
#### Scenario: Посторонний загружает в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в чат, или любой пользователь в несуществующий чат отправляет корректное изображение
|
||||
- **THEN** ответ `404` с кодом `not_found`, ничего не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат тело, не являющееся изображением, или опасный `filename`
|
||||
- **THEN** ответ `404`, а не `400` или `415`
|
||||
|
||||
#### Scenario: Без аутентификации
|
||||
|
||||
- **WHEN** upload приходит без `Authorization` или с `Basic`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
### Requirement: Лимиты размера до неограниченного чтения и декодирования
|
||||
|
||||
Тело SHALL быть не больше `MAX_UPLOAD_BYTES` (10 485 760) байт, а изображение — не больше `MAX_IMAGE_PIXELS` (40 000 000) пикселей по заголовку. Превышение SHALL давать `413` с кодом `payload_too_large`. Объявленный `Content-Length` больше лимита SHALL отклоняться без чтения тела, тело без `Content-Length` SHALL читаться не дальше лимита плюс один байт, а число пикселей SHALL проверяться по заголовку изображения до декодирования. Реплика SHALL NOT записывать тело на свой диск.
|
||||
|
||||
#### Scenario: Ровно 10 MiB
|
||||
|
||||
- **WHEN** загружается корректный PNG размером ровно 10 485 760 байт
|
||||
- **THEN** ответ `201` и `size_bytes` 10485760
|
||||
|
||||
#### Scenario: На байт больше с Content-Length
|
||||
|
||||
- **WHEN** загружается тело размером 10 485 761 байт с заголовком `Content-Length`
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`
|
||||
|
||||
#### Scenario: На байт больше без Content-Length
|
||||
|
||||
- **WHEN** тело размером 10 485 761 байт передаётся chunked, без `Content-Length`
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`, вложение не создаётся
|
||||
|
||||
#### Scenario: Ровно 40 млн пикселей
|
||||
|
||||
- **WHEN** загружается корректный PNG 8000×5000
|
||||
- **THEN** ответ `201`
|
||||
|
||||
#### Scenario: Больше 40 млн пикселей
|
||||
|
||||
- **WHEN** загружается PNG 8001×5000 или сжатый PNG огромных размеров весом несколько килобайт
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`, изображение не декодируется
|
||||
|
||||
### Requirement: Тип определяется по содержимому
|
||||
|
||||
Сервис SHALL принимать только `Content-Type` `image/png` и `image/jpeg` (параметры заголовка и регистр не важны) и SHALL проверять, что сигнатура и структура файла соответствуют заявленному типу, а файл читается без ошибок. Иной или отсутствующий `Content-Type`, несовпадение заявленного типа и содержимого, пустое тело, обрезанный или повреждённый файл, GIF, WebP и текст SHALL давать `415` с кодом `unsupported_media_type`.
|
||||
|
||||
#### Scenario: Подмена MIME
|
||||
|
||||
- **WHEN** JPEG, GIF или текст отправлены с `Content-Type: image/png`
|
||||
- **THEN** ответ `415` с кодом `unsupported_media_type`
|
||||
|
||||
#### Scenario: Обрезанное изображение
|
||||
|
||||
- **WHEN** отправлена первая половина корректного PNG или JPEG с верным `Content-Type`
|
||||
- **THEN** ответ `415`
|
||||
|
||||
#### Scenario: Неподдерживаемый Content-Type
|
||||
|
||||
- **WHEN** корректный PNG отправлен с `Content-Type: application/octet-stream` или без `Content-Type`
|
||||
- **THEN** ответ `415`
|
||||
|
||||
### Requirement: Безопасное отображаемое имя
|
||||
|
||||
`filename` SHALL быть обязательным параметром длиной 1–255 Unicode code points после percent-декодирования, SHALL NOT состоять только из пробельных символов и SHALL NOT содержать `/`, `\`, NUL и другие управляющие символы. Нарушение SHALL давать `400` с кодом `invalid_request`. Имя SHALL использоваться только для отображения и возвращаться без изменений.
|
||||
|
||||
#### Scenario: Опасное имя
|
||||
|
||||
- **WHEN** `filename` равен `../a.png`, `a/b.png`, `a\b.png`, содержит `%00`, `%01` или `%7F`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустое, пробельное, длинное или отсутствующее имя
|
||||
|
||||
- **WHEN** `filename` пустой, из пробелов, длиной 256 code points или не передан
|
||||
- **THEN** ответ `400`
|
||||
|
||||
#### Scenario: Имя на кириллице
|
||||
|
||||
- **WHEN** `filename` равен `фото 1.png` длиной до 255 code points
|
||||
- **THEN** ответ `201` и `filename` в ответе совпадает с переданным
|
||||
|
||||
### Requirement: Метаданные и скачивание только участникам
|
||||
|
||||
`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с исходными байтами, `Content-Type` вложения и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`. Параметр `variant` SHALL принимать только `original` (по умолчанию). Посторонний, неизвестный id и ещё не готовое вложение SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и неизвестный `variant` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`.
|
||||
|
||||
#### Scenario: Второй участник скачивает оригинал
|
||||
|
||||
- **WHEN** второй участник чата запрашивает `/content` загруженного вложения с `Accept: application/json`
|
||||
- **THEN** ответ `200`, `Content-Type: image/png`, байты совпадают с загруженными, SHA-256 равен `sha256` метаданных
|
||||
|
||||
#### Scenario: Посторонний
|
||||
|
||||
- **WHEN** пользователь вне чата запрашивает метаданные или `/content`
|
||||
- **THEN** оба ответа `404` с кодом `not_found`
|
||||
|
||||
#### Scenario: Неизвестный вариант
|
||||
|
||||
- **WHEN** запрошен `/content?variant=thumbnail`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Объект пропал из хранилища
|
||||
|
||||
- **WHEN** метаданные готового вложения есть, а объекта в bucket нет
|
||||
- **THEN** `/content` отвечает `404`, событие пишется в журнал без ключа объекта
|
||||
|
||||
### Requirement: Порядок записи PostgreSQL и S3
|
||||
|
||||
Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки.
|
||||
|
||||
#### Scenario: S3 отказал при записи
|
||||
|
||||
- **WHEN** запись объекта завершилась ошибкой
|
||||
- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях
|
||||
|
||||
#### Scenario: Клиент оборвал загрузку
|
||||
|
||||
- **WHEN** клиент закрыл соединение, отправив часть тела
|
||||
- **THEN** в bucket нет нового объекта и в PostgreSQL нет новой строки вложения
|
||||
|
||||
### Requirement: Недоступный S3
|
||||
|
||||
Недоступность S3 SHALL превращаться в `503 unavailable` в общем формате ошибки за ограниченное время (меньше `REQUEST_TIMEOUT_SECONDS`) для upload и скачивания. Метаданные, тексты сообщений и `GET /health/ready` SHALL продолжать работать: готовность реплики от S3 не зависит. После возврата S3 ранее загруженные файлы SHALL скачиваться без изменений.
|
||||
|
||||
#### Scenario: S3 остановлен
|
||||
|
||||
- **WHEN** выполняется `docker compose stop s3` и клиент загружает и скачивает файл, отправляет текст и проверяет готовность
|
||||
- **THEN** upload и `/content` отвечают `503` с `X-Request-Id` и `X-Instance-Id` быстрее `REQUEST_TIMEOUT_SECONDS`, текстовое сообщение — `201`, метаданные и `/health/ready` — `200`
|
||||
|
||||
#### Scenario: S3 вернулся
|
||||
|
||||
- **WHEN** S3 снова запущен
|
||||
- **THEN** ранее загруженный файл скачивается с тем же SHA-256
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
## Purpose
|
||||
|
||||
Определяет объектное хранилище вложений как часть стенда: S3-совместимый сервер с закреплённой версией и persistent volume, приватный bucket и воспроизводимый bootstrap, раздельные ключи администратора и API, а также то, что байты не живут в БД и на диске реплики и переживают остановку реплики и рестарт стенда.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: S3-сервер и приватный bucket в стенде
|
||||
|
||||
Стенд SHALL включать S3-совместимый сервер с образом, закреплённым версией и digest, данными на именованном volume и healthcheck, без опубликованных на хост портов и без доступной административной консоли. Одноразовый bootstrap SHALL создавать bucket `S3_BUCKET` (по умолчанию `messenger-attachments`), делать его приватным для анонимного клиента, создавать пользователя API с политикой только на объекты и листинг этого bucket и завершаться кодом 0; повторный запуск SHALL проходить без ошибок и без изменения состояния. Реплики API SHALL стартовать после успешного bootstrap.
|
||||
|
||||
#### Scenario: Анонимный GET объекта
|
||||
|
||||
- **WHEN** из отдельного контейнера в сети стенда выполняется HTTP GET существующего объекта bucket без подписи
|
||||
- **THEN** ответ `403`, байты объекта не возвращаются
|
||||
|
||||
#### Scenario: Порты и консоль
|
||||
|
||||
- **WHEN** выполняется `docker compose ps` и запрос к порту консоли внутри контейнера S3
|
||||
- **THEN** у сервиса S3 нет опубликованных портов, а консоль не отвечает
|
||||
|
||||
#### Scenario: Повторный bootstrap
|
||||
|
||||
- **WHEN** bootstrap запускается ещё два раза на работающем стенде
|
||||
- **THEN** оба запуска завершаются кодом 0, а bucket, его анонимная политика, пользователь и политика API не меняются
|
||||
|
||||
### Requirement: Раздельные ключи и места хранения
|
||||
|
||||
Root-ключи S3 SHALL передаваться файлами compose secrets только S3-серверу, bootstrap и операторскому CLI; реплики API SHALL получать отдельный ключ из `S3_ACCESS_KEY_ID_FILE` и `S3_SECRET_ACCESS_KEY_FILE`. Байты вложений SHALL храниться только в bucket: в PostgreSQL SHALL NOT быть столбцов с содержимым файла, у реплик API SHALL NOT быть volume, а корневая файловая система реплики SHALL быть только для чтения. Ключи и адреса хранилища SHALL NOT попадать в ответы API, журнал и Git.
|
||||
|
||||
#### Scenario: Где лежат байты
|
||||
|
||||
- **WHEN** после загрузки выполняются `\d attachments`, листинг bucket и `docker inspect` реплики API
|
||||
- **THEN** в таблице нет `bytea`, объект лежит в bucket под ключом `attachments/<uuid>`, у реплики `ReadonlyRootfs=true` и нет volume
|
||||
|
||||
#### Scenario: Ключ API
|
||||
|
||||
- **WHEN** проверяются секреты сервиса `api` в `docker compose config`
|
||||
- **THEN** у `api` есть только ключ API S3, а root-ключей нет
|
||||
|
||||
### Requirement: Файл переживает остановку обслужившей реплики
|
||||
|
||||
Вложение, загруженное через одну реплику API, SHALL скачиваться через другую реплику после остановки первой с тем же SHA-256.
|
||||
|
||||
#### Scenario: Upload, остановка реплики, download
|
||||
|
||||
- **WHEN** выполняется `python3 scripts/lab4_scenarios.py failover-upload`: upload, остановка реплики из `X-Instance-Id` ответа хуком `scripts/stop-one.sh`, скачивание
|
||||
- **THEN** скачивание обслуживает другая реплика, SHA-256 совпадает, сценарий печатает `"ok": true`
|
||||
@@ -0,0 +1,56 @@
|
||||
## 1. Схема
|
||||
|
||||
- [x] 1.1 Миграция `0003_attachments.sql`: `attachments` (статус `pending`/`ready`, `object_key COLLATE "C"`, `UNIQUE (id, chat_id)`, FK на `chat_members`, частичный индекс `pending`), `message_attachments` (FK на `attachments (id, chat_id)` `ON DELETE RESTRICT`, индекс по `attachment_id`), ослабленный `messages_text_check`
|
||||
- [x] 1.2 Проверка группы: тест миграций — версия `0003`, повтор без изменений, вложение не участника и ссылка на вложение другого чата отклоняются внешними ключами, пустой текст принимается схемой
|
||||
|
||||
## 2. Зона `attachments`: домен и приложение
|
||||
|
||||
- [x] 2.1 Домен: `Filename`, `ImageKind`, `ImageInfo`, агрегат `Attachment` (`stage` → `pending`, `store` → `ready` с событием `AttachmentStored`), ошибки зоны
|
||||
- [x] 2.2 Порты: `ChatMembership`, `ObjectStorage` (`put`/`open`/`delete`, `ObjectContent`, `ObjectMissing`), `ImageInspector`, `AttachmentsUnitOfWork`, `AttachmentDirectory`
|
||||
- [x] 2.3 Команда `UploadAttachment` и обработчик: членство → имя → `Content-Type` → поток со счётчиком и SHA-256 → проверка изображения → `pending` → `put` → `ready`; запросы `GetAttachment`, `OpenAttachment`
|
||||
- [x] 2.4 Проверка группы: unit-тесты `Filename` (граничные и опасные имена), агрегата и порядка записи обработчика с фейковыми портами (сбой `put` даёт `503` и не делает вложение готовым)
|
||||
|
||||
## 3. Зона `attachments`: инфраструктура и HTTP
|
||||
|
||||
- [x] 3.1 Адаптер PostgreSQL: `add`, `save`, `get` готового; нарушение FK членства → `404`
|
||||
- [x] 3.2 Адаптер `PillowImageInspector`: открытие только PNG/JPEG, подмена MIME, пиксели по заголовку, PNG `verify`, JPEG `draft` + `load`, `to_thread` под семафором
|
||||
- [x] 3.3 Адаптер `S3ObjectStorage` на aiobotocore (path-style, SigV4, таймауты, checksum `when_required`), отображение ошибок в `ObjectMissing`/`Unavailable`; зависимости aiobotocore и Pillow в `uv.lock`
|
||||
- [x] 3.4 Настройки зоны (`S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, таймауты, параллелизм проверки), провайдер dishka, схемы `AttachmentOut`, роутер upload/метаданных/скачивания, реестр ошибок, журнал
|
||||
- [x] 3.5 Проверка группы: тест адаптера S3 против одноразового RustFS (put/open/delete, пропавший объект, недоступный endpoint → `Unavailable` за ограниченное время)
|
||||
|
||||
## 4. Связь зон и платформа
|
||||
|
||||
- [x] 4.1 Платформа: лимит тела по шаблону маршрута в конвейере
|
||||
- [x] 4.2 `main.py`: зона `attachments`, адаптер `MessagingMembership` для порта `ChatMembership`, лимит upload, поля журнала, реестр ошибок; `create_app` принимает дополнительные провайдеры для тестов
|
||||
- [x] 4.3 Проверка группы: тест графа импортов — `attachments` не импортирует `identity`/`messaging`, `messaging` не импортирует `attachments`, `shared` не знает зон
|
||||
|
||||
## 5. Зона `messaging`: `attachment_ids`
|
||||
|
||||
- [x] 5.1 Домен: `Message.attachment_ids`, `Chat.post` с проверкой списка вложений, `MessageText` с пустой строкой, ошибки `InvalidAttachmentList` и `UnknownAttachment`
|
||||
- [x] 5.2 HTTP и команда: `CreateMessageRequest.attachment_ids` (по умолчанию `[]`, отпечаток), `MessageOut.attachment_ids`
|
||||
- [x] 5.3 PostgreSQL: запись `message_attachments` в операторе отправки, FK → `404`, `attachment_ids` в повторе и истории подзапросом
|
||||
- [x] 5.4 Проверка группы: тесты — пустой текст с вложением, порядок, другой чат и неизвестный id `404`, 11 и повторы `400`, посторонний `404` раньше `400`, повтор с вложением, отсутствующий ≡ `[]`, другой порядок `409`, история с `attachment_ids`
|
||||
|
||||
## 6. API-тесты вложений
|
||||
|
||||
- [x] 6.1 Генераторы тестовых PNG (произвольный размер в пикселях и байтах) и JPEG, фейковое `ObjectStorage` в `student-tests`
|
||||
- [x] 6.2 Тесты: fixture `201` и побайтное скачивание вторым участником, посторонний `404` на метаданных и `/content`, ровно 10 MiB `201`, +1 байт `413` с `Content-Length` и chunked, 40 MP `201` и 40 MP+ `413`, подмена MIME, обрезанные PNG/JPEG, иной и пустой `Content-Type` `415`, опасные и пустые `filename` `400`, `variant=thumbnail` `400`, сбой хранилища `503` без готового вложения, пропавший объект `404`, заголовки на бинарном ответе
|
||||
|
||||
## 7. Стенд
|
||||
|
||||
- [x] 7.1 `infra/s3/` (`init.sh`, `cli.sh`, `api-policy.json`, `lifecycle.json`) из заготовки
|
||||
- [x] 7.2 `compose.yaml`: `s3`, `s3-init`, `s3-cli`, volume `s3data`, секреты S3, якорь `x-s3-env` у `api`, зависимость от `s3-init`; `.env.example` (таймауты S3, параллелизм проверки)
|
||||
- [x] 7.3 `scripts/secrets.sh` (секреты S3), `scripts/restart.sh` (S3 в списке хранилищ), `scripts/evidence-stack.sh` (пакеты и образы лабы 4)
|
||||
- [x] 7.4 Проверка группы: `docker compose config --quiet`, у `api` только ключ API S3, `make up` из чистого состояния, все сервисы `healthy`, `s3-init` завершился кодом 0, опубликованы только порты `lb`
|
||||
|
||||
## 8. Сценарии отказов и обвязка
|
||||
|
||||
- [x] 8.1 `scripts/lab4_scenarios.py` (`failover-upload`, `s3-outage`), `scripts/s3-check.sh`, `scripts/evidence-attachments.sh`; цели Makefile `scenario`, `s3-check`, `attachments-evidence`; ruff для новых `scripts/*.py`
|
||||
- [x] 8.2 CI-job под лабу 4: сценарии вложений после smoke
|
||||
- [x] 8.3 Проверка группы: `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` по обеим репликам с `make restore`, `make scenario SCENARIO=failover-upload`, `make scenario SCENARIO=s3-outage`, `make s3-check`
|
||||
|
||||
## 9. Отчёт
|
||||
|
||||
- [x] 9.1 `evidence/`: smoke, contract-checks, student-tests, stack, storage-layout, failover-upload, failover по каждой реплике, persistence со `StartedAt` (включая `s3`), s3-outage, s3-security, схема и миграции, окружение
|
||||
- [x] 9.2 `REPORT.md`: запуск из чистого clone, архитектура и решения, таблица ролей и сервисов, соответствие переменных `.env.example`, строки уровня «3», таблица отказов уровня «3»
|
||||
- [x] 9.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `make test` и сценарии зелёные
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-29
|
||||
lab: 4
|
||||
@@ -0,0 +1,103 @@
|
||||
## Context
|
||||
|
||||
Уровень «3» (архив `2026-10-28-add-lab4-image-attachments`, D3 и D5) пишет так: `INSERT pending` + `COMMIT` → `PutObject` → `UPDATE … SET status='ready' WHERE status='pending'` + `COMMIT` → `201`. Сбой между шагами оставляет невидимую строку `pending` и, если `PUT` прошёл, объект; их никто не убирает. Тело копится списком кусков и склеивается (до 2 × 10 MiB на миг склейки), число одновременных загрузок не ограничено: при 2 воркерах на реплику и `API_MEMORY=512m` десяток загрузок по 10 MiB на воркер уже упирается в лимит. Обрыв клиента посреди тела поднимает `ClientDisconnect` Starlette, который уходит в общий обработчик как `500`. Таймаут запроса (`REQUEST_TIMEOUT_SECONDS=8`) уже обрывает зависшее тело ответом `503`. Проверка S3 (`make s3-check`, 22 проверки) уже есть.
|
||||
|
||||
Изменение затрагивает только зону `attachments` и сборку в `main.py`; схема БД не меняется, контракт не меняется.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Любая строка `pending` и любой объект, оставленные сбоем, исчезают сами: сразу (компенсация) или через grace period (уборка). Объекта без строки не бывает.
|
||||
- Пик памяти реплики ограничен конфигурацией, а не числом клиентов; это подтверждено замером.
|
||||
- Каждый отказ из рубрики «4» воспроизводится одной командой против стенда.
|
||||
|
||||
**Non-Goals:**
|
||||
- Сверка «объект без строки», «строка `ready` без объекта», несовпадение размера и SHA-256, отчёт `--dry-run` — трек 2: при правильной работе уровня «4» таких расхождений нет, их внедряют руками.
|
||||
- Отдельный сервис-уборщик и расписание вне API.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Компенсация — «удалить, если не готово» под блокировкой строки
|
||||
|
||||
`UploadAttachmentHandler` после `PUT` выполняет перевод в `ready` в `try`. При любой ошибке (`Exception`) — компенсация `discard`:
|
||||
|
||||
1. транзакция; `SELECT … FROM attachments WHERE id=$1 FOR UPDATE`;
|
||||
2. строка `ready` → ничего не делать (фиксация на самом деле прошла: ответ `503`, повтор клиента создаст дубль — это допустимо);
|
||||
3. иначе `DeleteObject(object_key)` (идемпотентен), агрегат `discard("compensation")` → событие `AttachmentDiscarded`, `DELETE … WHERE id=$1 AND status='pending'`, `COMMIT`;
|
||||
4. ошибка компенсации пишется в журнал (`attachment.compensation_failed`) и глотается; клиенту уходит исходная ошибка (`503`).
|
||||
|
||||
Порядок «сначала объект, потом строка» сохраняет инвариант: пока объект существует, существует и строка-намерение с его ключом. Блокировка строки на время одного `DeleteObject` (≤ 2 × (1 + 2) = 6 с < `idle_in_transaction_session_timeout` 10 с) нужна, чтобы задержавшийся `UPDATE ready` той же загрузки не проскочил между удалением объекта и строки. В D5 уровня «3» транзакция вокруг `PUT` отвергнута из-за длинной сетевой операции на горячем пути; здесь блокировка берётся только на пути сбоя и в фоне. За это получаем отсутствие окна «`ready` без объекта»; стоит это соединение пула на время одного запроса к S3 при сбое.
|
||||
|
||||
`CancelledError` (таймаут запроса посреди `PUT` или `UPDATE`) компенсацию не запускает: исход `PUT` неизвестен, отложенный объект может появиться позже. Это доделывает уборка после grace period. Сбой самого `PUT` тоже не компенсируется сразу: S3, скорее всего, недоступен, а лишняя попытка удвоила бы время ответа `503`.
|
||||
|
||||
Перевод в `ready` проверяет число обновлённых строк: `UPDATE 0` значит, что намерение уже убрано (уборка при слишком малом grace); адаптер поднимает `Unavailable`, компенсация не находит строку и удаляет объект — `201` без строки невозможен.
|
||||
|
||||
Отвергнуто: удалять строку `pending` сразу при сбое `PUT` (объект может появиться после ответа — останется без строки); статус `discarding` и миграция (лишнее состояние: блокировка строки даёт то же без изменения схемы).
|
||||
|
||||
### D2. Уборка — фоновый проход в каждом воркере с `SKIP LOCKED`
|
||||
|
||||
Команда `SweepAbandonedUploads(grace, limit)` и её обработчик в зоне `attachments`. Проход повторяет шаг по одной строке, пока не наберёт `limit` или строки не кончатся:
|
||||
|
||||
```sql
|
||||
SELECT … FROM attachments
|
||||
WHERE status = 'pending' AND created_at < $1
|
||||
ORDER BY created_at LIMIT 1
|
||||
FOR UPDATE SKIP LOCKED
|
||||
```
|
||||
|
||||
`$1 = clock.now() - grace`; план — `Index Scan` по частичному индексу `attachments_pending_idx (created_at) WHERE status = 'pending'` из миграции `0003`, без чтения готовых строк. Дальше тот же шаг, что в компенсации: `DeleteObject` → `discard("abandoned")` → `DELETE … AND status='pending'` → `COMMIT`. Ошибка S3 откатывает транзакцию и прерывает проход до следующего интервала. Готовые строки и вложения в сообщениях не выбираются по условию `status='pending'`; на `ready` к тому же ссылается `message_attachments` с `ON DELETE RESTRICT`.
|
||||
|
||||
Точка входа — `UploadSweeper` в `attachments/entrypoints/sweeper.py`: задача asyncio, раз в `UPLOAD_SWEEP_INTERVAL_SECONDS` (30 с) открывает scope `REQUEST` контейнера dishka, берёт `AttachmentsCommandBus` и выполняет команду; ошибки пишет в журнал (`attachments.sweep_failed`), число удалённых — `attachments.swept`. `main.py` запускает её в lifespan после шины событий и отменяет первой при остановке. 2 реплики × 2 воркера = 4 прохода за интервал; `SKIP LOCKED` делает их независимыми, лишняя цена — один индексный запрос на проход.
|
||||
|
||||
Grace period `UPLOAD_GRACE_SECONDS=900`, не меньше 60 (валидация настроек). Жизнь загрузки от `INSERT pending` до `UPDATE ready` ограничена `REQUEST_TIMEOUT_SECONDS=8`, отложенный `PUT` после обрыва — таймаутами S3 (6 с); 900 с перекрывают это с запасом более чем в 50 раз, включая расхождение часов реплик (один хост, время из `Clock`). Почему не в отдельном сервисе: ещё один контейнер Python (~60 MiB) ради одного индексного запроса в 30 с; почему не по cron оператором: рубрика требует механизма, который не оставляет вечных объектов без участия человека.
|
||||
|
||||
Отвергнуто: `pg_advisory_lock` на весь проход (одна реплика держит соединение, пока ходит в S3; `SKIP LOCKED` распределяет строки без этого); удаление строки до объекта (сбой между шагами оставил бы объект без строки).
|
||||
|
||||
### D3. Память — слоты загрузки на воркер
|
||||
|
||||
`UploadSlots` — `asyncio.Semaphore(UPLOAD_CONCURRENCY)` на воркер (scope `APP`). Обработчик сначала проверяет членство, `filename` и `Content-Type` (дёшево, без тела), затем под слотом читает тело, проверяет изображение, пишет `pending` и делает `PutObject`. Буфер живёт только внутри метода записи и освобождается до перевода в `ready`. Без слота тело не читается: uvicorn приостанавливает чтение сокета, когда в его буфере больше 64 KiB, поэтому ждущая загрузка занимает десятки KiB; очередь ограничена `maxconn 64` HAProxy на реплику и таймаутом запроса (дольше 8 с — `503`).
|
||||
|
||||
Оценка до замера: одна загрузка 10 MiB — тело (10 MiB) плюс склейка (+10 MiB на миг) плюс копия в клиенте S3 — до ~30 MiB; `UPLOAD_CONCURRENCY=3` → 2 воркера × 3 × 30 MiB ≈ 180 MiB поверх простоя реплики при лимите 512 MiB.
|
||||
|
||||
Замер D5 уточнил картину в двух местах, и решение дополнено:
|
||||
|
||||
- **Ожидающая загрузка живёт в буферах сокетов.** Слот держит тело вне памяти воркера, но клиент продолжает слать, и байты копятся в ядре по цепочке: автонастройка TCP растит буфер приёма до 6 MiB на соединение, а память сокетов учитывается в cgroup контейнера. Первый прогон с 3 слотами при 40 одновременных загрузках по 10 MiB убил HAProxy по OOM (лимит 128 MiB, `memory.stat sock` ≈ 110 MB), соединения оборвались. Поэтому HAProxy получает `tune.rcvbuf.client/server` и `tune.sndbuf.client/server` по 64 KiB, а у `api` — `net.ipv4.tcp_rmem`/`tcp_wmem` с максимумом 256 KiB (sysctl сетевого namespace в `compose.yaml`). Пик LB после этого — 30 MiB; на пропускную способность внутри одного хоста буферы не влияют. Ожидающая загрузка стоит ~0,3 MiB на LB и столько же на реплике; число таких соединений ограничивает `maxconn 64` на реплику.
|
||||
- **Аллокатор glibc не отдаёт освобождённые тела.** Тела больше 128 KiB берутся у `malloc`; после первого освобождения крупного блока glibc поднимает порог `mmap` до 32 MiB, и следующие буферы по 10 MiB остаются в куче процесса после освобождения. `MALLOC_MMAP_THRESHOLD_=131072` у `api` фиксирует порог: большие буферы выделяются `mmap` и возвращаются системе. При 3 слотах и 40 загрузках по 10 MiB пик реплики — 330 MiB против 368 MiB с порогом 32 MiB.
|
||||
|
||||
Итог замера: одна загрузка 10 MiB в полёте стоит ≈ 35 MiB, 6 слотов на реплику — ≈ 210 MiB поверх простоя ~120 MiB, пик 304–330 MiB (до 64 % лимита) при 10–40 одновременных загрузках. Без лимита (64 слота) те же 40 загрузок упираются в 512 MiB: успешны 43 из 80, остальные получают `503`, а в предварительном прогоне ядро ещё и убило воркер. Значение `UPLOAD_CONCURRENCY=3` оставлено.
|
||||
|
||||
### D4. Обрыв и зависание тела
|
||||
|
||||
`ClientDisconnect` — транспортное понятие, поэтому HTTP-слой зоны оборачивает `request.stream()` и превращает его в доменную ошибку `UploadAborted` (`400 invalid_request` в реестре зоны). Ответ клиенту не доходит, но журнал реплики пишет `400`, а не `500`. Строка не создаётся: она пишется только после чтения и проверки всего тела. Зависшее тело обрывает конвейер (`asyncio.timeout`, `503`), слот освобождается выходом из `async with` при отмене.
|
||||
|
||||
### D5. Проверки против стенда и замер
|
||||
|
||||
`student-tests/stack/test_attachment_faults.py` (маркер `stack`, `make upload-faults` пишет вывод в `evidence/upload-faults.txt`):
|
||||
|
||||
- негативный suite через LB с настоящими PostgreSQL и RustFS; после прогона — `docker compose logs api --since` без `"status":500`, строк вложений в чате ровно столько, сколько `201`;
|
||||
- внедрение сбоев триггером PostgreSQL на время теста (снимается в `finally`): `AFTER INSERT` записывает id и ключ намерения в служебную таблицу (переживает откат), `BEFORE UPDATE` для имён `fault-fail-*` поднимает `55P03` (отказ `COMMIT` → компенсация), для `fault-crash-*` спит 1,8 с — за это время тест находит реплику по `client_addr` спящего backend и убивает её `docker kill -s KILL` (падение процесса между `PUT` и `COMMIT`);
|
||||
- `created_at` брошенного намерения сдвигается на 2 × grace назад — так проверка не ждёт 15 минут; свежее намерение остаётся и переживает проход;
|
||||
- обрыв и зависание тела — сырым сокетом через LB с собственным `X-Request-Id`, статус ищется в журнале реплики.
|
||||
|
||||
Замер памяти: `scripts/lab4_seed.py` из заготовки (режим `http`, `--sample`: `docker stats` в фоне и `memory.peak` cgroup в конце; добавлены `memory.current` до нагрузки и счётчик `oom_kill` из `memory.events`, заголовок `X-Instance-Id` читается без учёта регистра) и `scripts/upload_memory.py` (Python вместо задуманного `upload-memory.sh`: сводка и вызов генератора проще без оболочки): для `UPLOAD_CONCURRENCY` ∈ {64 (фактически без лимита), 3} × размер ∈ {1, 10 MiB} × одновременность ∈ {10, 20, 40} пересоздаёт реплики и LB (`memory.peak` на ядре Docker Desktop не сбрасывается), ждёт LB и делает 2 × c загрузок; пик LB снимается отдельно; сводка — `evidence/upload-memory/summary.txt`, сравнение порога `mmap` — `evidence/upload-memory/mmap-32m/`.
|
||||
|
||||
### D6. Проверка S3
|
||||
|
||||
`scripts/s3-check.sh` получает проверку консоли из отдельного контейнера сети стенда (`wget http://s3:9001/` — отказ соединения); остальное уже покрывает строку 4.4: два повторных bootstrap без изменения снимка IAM, разрешённые и запрещённые операции ключа API, анонимный доступ, прямой HTTP GET.
|
||||
|
||||
### D7. Платформа: события команды из нескольких транзакций
|
||||
|
||||
Компенсация фиксирует удаление уже после неудачного `COMMIT`, а проход уборки — по транзакции на строку и завершается откатом пустого поиска. Базовая `PostgresUnitOfWork` при любом откате очищала все накопленные события команды, а `CommandBus` не публиковал события, если обработчик бросил исключение, — журнал терял зафиксированные удаления. Теперь откат убирает только события, записанные внутри этой транзакции, а шина публикует собранное и при исключении обработчика. Это механизм платформы (`shared/`), доменных понятий он не добавляет; события по-прежнему появляются только из зафиксированных транзакций. Проверяется тестами компенсации и параллельной уборки по событиям `AttachmentDiscarded`.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Grace меньше реального времени жизни загрузки] → минимум 60 с в настройках, по умолчанию 900 с; даже при ошибке D1 гарантирует `503` и удаление объекта вместо `ready` без строки.
|
||||
- [Отменённый таймаутом `PUT` допишет объект после ответа] → строка-намерение остаётся, уборка удалит объект после grace.
|
||||
- [Уборка в каждом воркере даёт 4 запроса за интервал] → индексный запрос по частичному индексу; при пустом результате — одна строка плана.
|
||||
- [Слоты держат клиентов в ожидании] → ожидание ограничено таймаутом запроса; при длительной перегрузке клиент получает `503` и повторяет, а не реплика уходит в OOM.
|
||||
- [Триггер внедрения сбоев остался бы в БД при падении теста] → снимается в `finally` фикстуры, имена с префиксом `lab4_fault`, срабатывает только на `filename LIKE 'fault-%'`.
|
||||
- [`docker kill` реплики в тесте] → реплика возвращается `docker compose up -d --wait --no-recreate`, тест ждёт двух `UP` в LB.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Схема не меняется; новые переменные имеют значения по умолчанию. Откат — прежний образ API: строки `pending` он не трогает, они остаются невидимыми.
|
||||
@@ -0,0 +1,32 @@
|
||||
## Why
|
||||
|
||||
Уровень «3» оставил три долга: строка-намерение `pending` после сбоя S3, `COMMIT` или процесса остаётся навсегда (а вместе с ней — объект, записанный до сбоя); одновременные загрузки ничем не ограничены, и каждая держит до 20 MiB; права ключа API и закрытость консоли проверены, но не сведены в критерий. Рубрика «4» `README.md` требует: тесты на большой, битый и подменённый файл, чужое вложение и вложение другого чата без `500`; компенсацию и очистку с безопасным grace period; ограниченную память и замер ≥10 одновременных загрузок; идемпотентный bootstrap, ограниченные ключи, закрытую консоль и проверку приватности вне API. Изменение закрывает уровень «4» и строки 4.1–4.4 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Компенсация: если после записи объекта не удалось перевести вложение в `ready`, обработчик сразу под блокировкой строки удаляет объект и строку `pending`; строку `ready` не трогает никогда. Пропавшая строка-намерение при переводе в `ready` даёт `503`, а не готовое вложение без строки.
|
||||
- Уборка: фоновый проход в каждой реплике раз в `UPLOAD_SWEEP_INTERVAL_SECONDS` удаляет объект и строку `pending` старше `UPLOAD_GRACE_SECONDS` (900 с ≫ `REQUEST_TIMEOUT_SECONDS`), по одной строке под `FOR UPDATE SKIP LOCKED`; свежие намерения, `ready` и вложения в сообщениях не трогает.
|
||||
- Обрыв клиента посреди тела — `400` в журнале вместо `500`, ничего не пишется; зависшее тело обрывается таймаутом запроса (`503`), слот освобождается.
|
||||
- Память: не больше `UPLOAD_CONCURRENCY` тел в памяти воркера одновременно, остальные загрузки ждут слота, не читая тело; замер пика памяти при 10, 20 и 40 одновременных загрузках 1 и 10 MiB с лимитом и без.
|
||||
- Стенд: негативный suite и сценарии сбоев через LB против настоящих RustFS и PostgreSQL (`make upload-faults`): ошибка `COMMIT` и падение процесса между `PUT` и `COMMIT` внедряются триггером PostgreSQL, обрыв и зависание тела — сырым сокетом; журнал реплик не содержит `500`.
|
||||
- `make s3-check` дополняется проверкой консоли из сети стенда; результаты сводятся в строку 4.4.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab4-upload-resilience`: компенсация сбоя между S3 и PostgreSQL, уборка брошенных загрузок с grace period, обрыв и зависание тела, ограничение памяти одновременных загрузок, пользовательские ошибки файлов без `500`.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab4-attachments`: «Порядок записи PostgreSQL и S3» — намерение и объект после сбоя убираются компенсацией или уборкой.
|
||||
- `lab4-object-storage`: «S3-сервер и приватный bucket в стенде» — консоль недоступна из сети стенда; «Раздельные ключи и места хранения» — проверяемые запреты ключа API.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: зона `attachments` (домен, обработчики, адаптер PostgreSQL, настройки, фоновая уборка, HTTP-слой), `main.py` (запуск уборки); схема БД не меняется.
|
||||
- Стенд: `compose.yaml` (буферы сокетов и порог `mmap` у `api`), `infra/haproxy/haproxy.cfg` (буферы сокетов LB), `.env.example`, `scripts/lab4_seed.py` из заготовки и `scripts/upload_memory.py`, `scripts/s3-check.sh`, `Makefile`, CI.
|
||||
- Тесты: `student-tests/api` (компенсация, уборка, слоты, обрыв, таймаут), `student-tests/stack` (стенд).
|
||||
- Отчёт: строки 4.1–4.4, таблица отказов, раздел эксперимента, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Reconciler для объектов без строки, пропавших объектов и несовпадения байтов, `--dry-run`/`--apply` и стоимость обхода — трек 2, следующее изменение. Удаление вложений пользователем, `202 queued` и варианты (лаба 5), presigned upload (трек 1) — Out of scope.
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Порядок записи PostgreSQL и S3
|
||||
|
||||
Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability `lab4-upload-resilience`), поэтому объект без строки-намерения в bucket не остаётся.
|
||||
|
||||
#### Scenario: S3 отказал при записи
|
||||
|
||||
- **WHEN** запись объекта завершилась ошибкой
|
||||
- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях, а строка-намерение удаляется уборкой после grace period
|
||||
|
||||
#### Scenario: Клиент оборвал загрузку
|
||||
|
||||
- **WHEN** клиент закрыл соединение, отправив часть тела
|
||||
- **THEN** в bucket нет нового объекта и в PostgreSQL нет новой строки вложения
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: S3-сервер и приватный bucket в стенде
|
||||
|
||||
Стенд SHALL включать S3-совместимый сервер с образом, закреплённым версией и digest, данными на именованном volume и healthcheck, без опубликованных на хост портов и без доступной административной консоли — ни внутри контейнера, ни из сети стенда. Одноразовый bootstrap SHALL создавать bucket `S3_BUCKET` (по умолчанию `messenger-attachments`), делать его приватным для анонимного клиента, создавать пользователя API с политикой только на объекты и листинг этого bucket и завершаться кодом 0; повторный запуск SHALL проходить без ошибок и без изменения состояния. Реплики API SHALL стартовать после успешного bootstrap.
|
||||
|
||||
#### Scenario: Анонимный GET объекта
|
||||
|
||||
- **WHEN** из отдельного контейнера в сети стенда выполняется HTTP GET существующего объекта bucket без подписи
|
||||
- **THEN** ответ `403`, байты объекта не возвращаются
|
||||
|
||||
#### Scenario: Порты и консоль
|
||||
|
||||
- **WHEN** выполняется `docker compose ps`, запрос к порту консоли внутри контейнера S3 и запрос к тому же порту из отдельного контейнера сети стенда
|
||||
- **THEN** у сервиса S3 нет опубликованных портов, а консоль не отвечает ни там, ни там
|
||||
|
||||
#### Scenario: Повторный bootstrap
|
||||
|
||||
- **WHEN** bootstrap запускается ещё два раза на работающем стенде
|
||||
- **THEN** оба запуска завершаются кодом 0, а bucket, его анонимная политика, пользователь и политика API не меняются
|
||||
|
||||
### Requirement: Раздельные ключи и места хранения
|
||||
|
||||
Root-ключи S3 SHALL передаваться файлами compose secrets только S3-серверу, bootstrap и операторскому CLI; реплики API SHALL получать отдельный ключ из `S3_ACCESS_KEY_ID_FILE` и `S3_SECRET_ACCESS_KEY_FILE`. Ключ API SHALL разрешать только чтение, запись, удаление объектов и листинг bucket `S3_BUCKET` и SHALL получать `AccessDenied` на создание и удаление bucket, изменение его политики и lifecycle, администрирование пользователей и любые операции с другим bucket. Байты вложений SHALL храниться только в bucket: в PostgreSQL SHALL NOT быть столбцов с содержимым файла, у реплик API SHALL NOT быть volume, а корневая файловая система реплики SHALL быть только для чтения. Ключи и адреса хранилища SHALL NOT попадать в ответы API, журнал и Git.
|
||||
|
||||
#### Scenario: Где лежат байты
|
||||
|
||||
- **WHEN** после загрузки выполняются `\d attachments`, листинг bucket и `docker inspect` реплики API
|
||||
- **THEN** в таблице нет `bytea`, объект лежит в bucket под ключом `attachments/<uuid>`, у реплики `ReadonlyRootfs=true` и нет volume
|
||||
|
||||
#### Scenario: Ключ API
|
||||
|
||||
- **WHEN** проверяются секреты сервиса `api` в `docker compose config`
|
||||
- **THEN** у `api` есть только ключ API S3, а root-ключей нет
|
||||
|
||||
#### Scenario: Права ключа API вне API
|
||||
|
||||
- **WHEN** из отдельного контейнера ключом API выполняются запись, чтение, листинг и удаление объекта, а затем создание и удаление bucket, публичная политика, импорт lifecycle, список пользователей, запись и листинг в другом bucket
|
||||
- **THEN** первые четыре операции разрешены, остальные получают `AccessDenied`
|
||||
+80
@@ -0,0 +1,80 @@
|
||||
## Purpose
|
||||
|
||||
Определяет устойчивость загрузки вложений: что остаётся после сбоя между записью объекта и фиксацией метаданных и кто это убирает, какой grace period защищает идущие загрузки, как обрываются прерванные и зависшие загрузки, сколько памяти занимают одновременные загрузки и что пользовательские ошибки файлов не превращаются в `500`.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Компенсация сбоя после записи объекта
|
||||
|
||||
Если объект записан в bucket, а перевод вложения в готовое не зафиксирован, сервис SHALL ответить `503` с кодом `unavailable` и до ответа SHALL попытаться удалить объект и строку-намерение. Строку, которая к этому моменту уже готова, сервис SHALL NOT удалять вместе с её объектом. Если строку-намерение к моменту перевода в готовое уже убрали, сервис SHALL ответить `503` и удалить записанный объект, а не возвращать `201`. Неудача компенсации SHALL оставлять строку-намерение для уборки по grace period.
|
||||
|
||||
#### Scenario: Отказ COMMIT после записи объекта
|
||||
|
||||
- **WHEN** запись объекта прошла, а фиксация статуса `ready` в PostgreSQL отклонена
|
||||
- **THEN** ответ `503` с кодом `unavailable`, сразу после ответа нет ни строки вложения, ни объекта с его ключом, в журнале есть событие удаления намерения с причиной `compensation`
|
||||
|
||||
#### Scenario: Намерение снято раньше, чем загрузка завершилась
|
||||
|
||||
- **WHEN** во время записи объекта строку-намерение удалили
|
||||
- **THEN** ответ `503`, объект с ключом этой загрузки удалён, готового вложения не появилось
|
||||
|
||||
### Requirement: Уборка брошенных загрузок по grace period
|
||||
|
||||
Сервис SHALL без участия оператора и не реже чем раз в `UPLOAD_SWEEP_INTERVAL_SECONDS` удалять сначала объект, затем строку каждого намерения `pending`, созданного раньше чем `UPLOAD_GRACE_SECONDS` назад. Grace period SHALL быть не меньше 60 с и много больше `REQUEST_TIMEOUT_SECONDS`, чтобы идущая загрузка не была убрана. Уборка SHALL NOT трогать намерения моложе grace period, готовые вложения и вложения, на которые ссылаются сообщения, SHALL быть безопасной при одновременной работе на нескольких репликах и повторяемой: следующий проход после полного SHALL ничего не удалять. Если S3 недоступен, намерение SHALL оставаться до следующего прохода.
|
||||
|
||||
#### Scenario: Процесс упал между записью объекта и фиксацией
|
||||
|
||||
- **WHEN** процесс реплики убит после записи объекта, но до фиксации `ready`, а затем намерение становится старше grace period
|
||||
- **THEN** до истечения grace period строка `pending` и объект остаются невидимыми клиентам; после — уборка удаляет и объект, и строку
|
||||
|
||||
#### Scenario: Свежее намерение переживает уборку
|
||||
|
||||
- **WHEN** проход уборки выполняется, пока одно брошенное намерение старше grace period, а другое моложе
|
||||
- **THEN** удалено только старое, свежее остаётся вместе со своим объектом
|
||||
|
||||
#### Scenario: Готовые и используемые вложения не трогаются
|
||||
|
||||
- **WHEN** проход уборки выполняется после того, как время создания готового вложения, на которое ссылается сообщение, сдвинуто далеко в прошлое
|
||||
- **THEN** вложение по-прежнему скачивается участником с тем же SHA-256
|
||||
|
||||
#### Scenario: Несколько уборок одновременно
|
||||
|
||||
- **WHEN** два прохода уборки одновременно обрабатывают пять брошенных намерений
|
||||
- **THEN** вместе они удаляют ровно пять, без ошибок, а следующий проход удаляет ноль
|
||||
|
||||
### Requirement: Обрыв и зависание тела
|
||||
|
||||
Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки вложения и SHALL учитываться как ошибка клиента (`400`), а не `500`. Тело, которое перестало поступать, SHALL обрываться не позже `REQUEST_TIMEOUT_SECONDS` с ответом `503` и кодом `unavailable`, без объекта и строки, а занятый им слот загрузки SHALL освобождаться для следующих загрузок.
|
||||
|
||||
#### Scenario: Клиент закрыл соединение посреди тела
|
||||
|
||||
- **WHEN** клиент объявил `Content-Length` 5 MiB, отправил 256 KiB и закрыл соединение
|
||||
- **THEN** строка вложения не создавалась, объект не появился, реплика записала в журнал статус `400`
|
||||
|
||||
#### Scenario: Тело зависло
|
||||
|
||||
- **WHEN** клиент отправил заголовки и часть тела и перестал слать байты
|
||||
- **THEN** не позже `REQUEST_TIMEOUT_SECONDS` плюс 2 с приходит `503` с кодом `unavailable`, строки и объекта нет, следующая загрузка проходит
|
||||
|
||||
### Requirement: Ограниченная память одновременных загрузок
|
||||
|
||||
Воркер API SHALL держать в памяти тела не более `UPLOAD_CONCURRENCY` загрузок одновременно; остальные загрузки SHALL ждать свободного слота, не читая тело, в пределах `REQUEST_TIMEOUT_SECONDS`. Тело SHALL NOT записываться на диск реплики. Пик памяти реплики при ≥10 одновременных загрузках по 10 MiB SHALL оставаться ниже её лимита памяти без перезапуска процесса, а все корректные загрузки SHALL получать `201`.
|
||||
|
||||
#### Scenario: Ожидание слота
|
||||
|
||||
- **WHEN** при `UPLOAD_CONCURRENCY=1` одна загрузка держит слот, а вторая приходит следом
|
||||
- **THEN** тело второй не читается, пока первая не завершилась, затем обе получают `201`
|
||||
|
||||
#### Scenario: Замер одновременных загрузок
|
||||
|
||||
- **WHEN** через LB идут 10, 20 и 40 одновременных загрузок PNG по 1 MiB и по 10 MiB, а пик памяти каждой реплики снимается из cgroup
|
||||
- **THEN** при лимите слотов все загрузки получают `201`, пик памяти реплики ниже `API_MEMORY` и не растёт пропорционально числу одновременных загрузок
|
||||
|
||||
### Requirement: Пользовательские ошибки файлов не дают 500
|
||||
|
||||
Ни одна ошибка клиента при загрузке, чтении вложения или ссылке на него SHALL NOT давать ответ `5xx` или строку журнала реплики со статусом `500`. Через балансировщик против настоящих PostgreSQL и S3 SHALL проверяться: тело на байт больше лимита (с `Content-Length` и chunked) — `413`; декомпрессионная бомба — `413`; обрезанный PNG и JPEG — `415`; подмена MIME (JPEG, GIF, текст как `image/png`, PNG как `image/jpeg`) и отсутствующий или иной `Content-Type` — `415`; опасный и пустой `filename` — `400`; метаданные и `/content` чужого вложения — `404`; ссылка на чужое, неизвестное вложение и вложение другого чата — `404`; 11 и повторяющиеся `attachment_ids`, невалидный UUID и неизвестный `variant` — `400`.
|
||||
|
||||
#### Scenario: Негативный suite через балансировщик
|
||||
|
||||
- **WHEN** все перечисленные запросы отправлены на стенд через LB
|
||||
- **THEN** каждый ответ имеет ожидаемый код и тело ошибки по схеме `Error`, ни один не `5xx`, в журнале реплик за время прогона нет статуса `500`, а строк вложений в чате ровно столько, сколько было ответов `201`
|
||||
@@ -0,0 +1,40 @@
|
||||
## 1. Зона `attachments`: домен и приложение
|
||||
|
||||
- [x] 1.1 Домен: событие `AttachmentDiscarded(reason)`, `Attachment.discard(reason)`, ошибка `UploadAborted`
|
||||
- [x] 1.2 Порты: репозиторий `lock`, `next_abandoned`, `remove`; `UploadSlots`; команда `SweepAbandonedUploads`
|
||||
- [x] 1.3 Обработчики: запись под слотом, компенсация `discard` после `PUT`, уборка по одной строке
|
||||
- [x] 1.4 Проверка группы: unit-тест `discard`, `make lint`
|
||||
|
||||
## 2. Зона `attachments`: инфраструктура, настройки и точки входа
|
||||
|
||||
- [x] 2.1 Адаптер PostgreSQL: `FOR UPDATE`, `FOR UPDATE SKIP LOCKED` по частичному индексу, `DELETE … AND status='pending'`, `UPDATE 0` → `Unavailable`
|
||||
- [x] 2.2 Настройки `UPLOAD_CONCURRENCY`, `UPLOAD_GRACE_SECONDS` (≥ 60), `UPLOAD_SWEEP_INTERVAL_SECONDS`, `UPLOAD_SWEEP_BATCH`; провайдер dishka
|
||||
- [x] 2.3 HTTP: `ClientDisconnect` → `UploadAborted` (`400`); журнал `audit.attachment_discarded`
|
||||
- [x] 2.4 `UploadSweeper` и его запуск/остановка в lifespan `main.py`
|
||||
- [x] 2.5 Платформа: откат транзакции не стирает события прежних транзакций команды, шина публикует их и при ошибке обработчика
|
||||
- [x] 2.6 Проверка группы: API-тесты против одноразового PostgreSQL — отказ `COMMIT` после `PUT` (компенсация), снятое намерение (`503`, объект удалён), сбой `PUT` и уборка после grace, свежее и готовое переживают проход, два прохода одновременно, фоновая уборка, ожидание слота, обрыв (`400`), зависшее тело (`503`, слот свободен)
|
||||
|
||||
## 3. Стенд
|
||||
|
||||
- [x] 3.1 `compose.yaml` и `.env.example`: новые переменные зоны у `api`
|
||||
- [x] 3.2 `scripts/s3-check.sh`: консоль из сети стенда
|
||||
- [x] 3.3 Проверка группы: `docker compose config --quiet`, `make up`, `make test`
|
||||
|
||||
## 4. Проверки против стенда
|
||||
|
||||
- [x] 4.1 `student-tests/stack/test_attachment_faults.py`: негативный suite через LB и журнал без `500`
|
||||
- [x] 4.2 Там же: отказ `COMMIT` (триггер) → компенсация; падение реплики между `PUT` и `COMMIT` → остаток виден, свежий переживает проход, старый убран; готовое вложение в сообщении переживает проход; обрыв и зависание тела
|
||||
- [x] 4.3 Цель `make upload-faults`, шаг CI
|
||||
- [x] 4.4 Проверка группы: `make upload-faults`, `make s3-check`
|
||||
|
||||
## 5. Замер памяти
|
||||
|
||||
- [x] 5.1 `scripts/lab4_seed.py` из заготовки (`memory.current` до нагрузки, `oom_kill`), `scripts/upload_memory.py`, цель `make upload-memory`, ruff для скриптов
|
||||
- [x] 5.2 Буферы сокетов по цепочке (HAProxy `tune.*buf`, `tcp_rmem`/`tcp_wmem` у `api`) и фиксированный порог `mmap` glibc по результатам первого прогона
|
||||
- [x] 5.3 Проверка группы: прогон 64/3 слота × 1/10 MiB × 10/20/40 и сравнение порога `mmap`; `UPLOAD_CONCURRENCY=3` подтверждено
|
||||
|
||||
## 6. Отчёт
|
||||
|
||||
- [x] 6.1 `evidence/`: `upload-faults.txt`, `upload-memory/`, `s3-security.txt`, `student-tests.txt`, `contract-checks.txt`, `regression-level4.txt`
|
||||
- [x] 6.2 `REPORT.md`: строки 4.1–4.4, механизм компенсации и уборки, эксперимент памяти, таблица отказов, ограничения; `AGENTS.md`: команды и уровень «4»
|
||||
- [x] 6.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, сценарии уровня «3» и `make upload-faults`
|
||||
@@ -0,0 +1,180 @@
|
||||
schema: spec-driven
|
||||
|
||||
context: |
|
||||
# Лабораторная 5 «Очереди и асинхронная обработка изображений» — контекст проекта
|
||||
|
||||
## Что это
|
||||
Skeleton лабораторной 5 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение
|
||||
в ветке `solution/bpi2303-kostylev`, построенное переносом решения лабы 4. Skeleton содержит
|
||||
задание (`README.md`), нормативный контракт (`contracts/`, версия 1.5.0, `jobs.schema.json`,
|
||||
`attachment-states.md`) и публичные black-box проверки (`tests/`). Целевая оценка — «5»: весь
|
||||
уровень 4 плюс трек 2 «Доказанная идемпотентность pipeline».
|
||||
|
||||
## Границы (менять нельзя)
|
||||
In scope лабы 5: асинхронная обработка вложений. Upload проверяется как в лабе 4, оригинал
|
||||
кладётся в устойчивый staging (приватный префикс S3), вложение `queued`, задание и намерение
|
||||
публикации фиксируются одной транзакцией PostgreSQL (transactional outbox), ответ — `202` со
|
||||
снимком `queued`. Relay публикует outbox в брокер с publisher confirm; отдельный worker
|
||||
потребляет очередь at-least-once, захватывает задание арендой, публикует оригинал в конечный
|
||||
префикс, строит thumbnail (уровень «3»), crop и optimized WebP (уровень «4») и подтверждает
|
||||
сообщение только после `COMMIT` результата. Состояния `queued/processing/ready/failed`,
|
||||
ограниченный retry и финальный `error_code`, идемпотентный эффект по ключу
|
||||
`(attachment_id, pipeline_version, variant)`, `409` на `/content` до `ready`, `409` на
|
||||
прикрепление `failed`. Уровень «4» — лимиты worker по времени и памяти, crash-точки окон
|
||||
отказа, backoff с jitter и классификация ошибок, DLQ и явный replay, lease и fencing,
|
||||
очистка staging. Трек 2 — versioned pipeline (`pipeline_version` 1 и 2), монотонная
|
||||
публикация и автоматический fault-injection с проверкой инвариантов. Весь обязательный
|
||||
минимум lab1–lab4 (PostgreSQL, Basic → Bearer, Argon2id, TTL и отзыв сессий,
|
||||
keyset-пагинация, HAProxy и ≥2 реплики, `X-Instance-Id`, общий `Idempotency-Key`, RustFS с
|
||||
приватным bucket, лимиты upload, хуки отказов) сохраняется с объявленным переходом
|
||||
upload `201 ready` → `202 queued`.
|
||||
|
||||
Out of scope (не проектировать, не закладывать «на будущее»): OTel, Prometheus-метрики
|
||||
приложения и Grafana (лаба 6); TLS, mTLS, OpenBao (лаба 7); трек 1 «Очередь под
|
||||
перегрузкой» с admission control и матрицей concurrency/prefetch (не выбран); presigned
|
||||
upload/download; HA брокера (кластер RabbitMQ), HA PostgreSQL, Docker Swarm и несколько
|
||||
узлов; exactly-once доставка; HTTP-эндпоинты оператора (replay — только CLI); удаление
|
||||
вложений и сообщений, Web UI, WebSocket, Kubernetes.
|
||||
|
||||
## Стек
|
||||
Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и
|
||||
`from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими
|
||||
`UvicornWorker` (пакет `uvicorn-worker`), dishka (DI, интеграции FastAPI и FastStream),
|
||||
pydantic v2 + pydantic-settings, structlog, asyncpg (параметризованный SQL без ORM),
|
||||
redis-py (`redis.asyncio`) для Valkey, argon2-cffi, aiobotocore (S3 path-style, SigV4,
|
||||
таймауты, checksum `when_required`), Pillow (проверка в API, варианты в worker), FastStream
|
||||
0.7 с `faststream[rabbit]` поверх aio-pika (consumer worker с `AckPolicy.MANUAL` и prefetch,
|
||||
publisher relay с confirm и `mandatory`), pytest + pytest-asyncio + httpx. Зависимости — uv и
|
||||
`uv.lock`; ruff и ty обязательны на `src/`, `student-tests/` и Python-обвязке стенда;
|
||||
`scripts/*.py` держат синтаксис Python 3.9 и stdlib.
|
||||
|
||||
Инфраструктура — Docker Compose: `lb` (HAProxy 3.2 LTS по digest, единственные опубликованные
|
||||
порты — HTTP и статистика на 127.0.0.1), `api` (один compose-service с `deploy.replicas`, без
|
||||
`container_name` и портов, `X-Instance-Id` = hostname, non-root, read-only, лимиты), одноразовый
|
||||
`migrate`, `postgres` (17.x-alpine по digest, volume), `valkey` (8.x-alpine по digest, AOF),
|
||||
`s3` (RustFS 1.0.4 по digest, volume, консоль выключена), одноразовый `s3-init` (bucket,
|
||||
политики и пользователи API и worker), `broker` (RabbitMQ 4.1.8 management-alpine по digest,
|
||||
фиксированный `hostname`, volume, топология и пользователи из definitions, UI только на
|
||||
127.0.0.1), `relay` и `worker` (образ приложения, свои entrypoint, heartbeat-healthcheck,
|
||||
`init: true`, лимиты). Сети `edge` и `backend` (internal). Секреты — compose secrets из
|
||||
gitignored `secrets/`, приложение читает их через `*_FILE`; у API нет секрета брокера, у
|
||||
worker — свой S3-ключ и свой пользователь брокера только на чтение очереди.
|
||||
|
||||
## Архитектура
|
||||
Монолит с тремя доменными зонами по книге Персиваля и Грегори
|
||||
(`openspec/notes/architecture-patterns-python.md`), развёрнутый как N реплик API и отдельные
|
||||
процессы relay и worker из того же образа:
|
||||
|
||||
main.py сборка HTTP-приложения: собирает вклады зон, связывает зоны портами
|
||||
relay.py сборка процесса relay: outbox → брокер, возврат просроченных аренд
|
||||
worker.py сборка процесса worker: FastStream-подписчик очереди заданий
|
||||
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
|
||||
identity/ пользователи, пароли и сессии
|
||||
messaging/ чаты, история и идемпотентная отправка, ссылки сообщения на вложения
|
||||
attachments/ вложения: приём и staging, задания и outbox, обработка и варианты,
|
||||
порты объектного хранилища, брокера и рендера с адаптерами S3, FastStream
|
||||
и Pillow, свой HTTP-слой и точки входа relay и worker
|
||||
shared/ только платформа: часы, id, журнал, пул PostgreSQL, UoW-база, конвейер, health,
|
||||
ошибки, настройки, идентификатор реплики
|
||||
|
||||
Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только
|
||||
от портов, адаптеры подключаются в `ioc.py` зоны. Ядро `shared/` не импортирует ни веб-фреймворк,
|
||||
ни FastStream. Зоны не импортируют друг друга; общая точка — схема БД: внешние ключи между
|
||||
таблицами зон допустимы как ограничение целостности, но SQL одной зоны не читает таблицы другой.
|
||||
Вопрос одной зоны к другой (членство в чате, состояние вложения при отправке сообщения) — порт
|
||||
зоны-потребителя, адаптер которого собирает `main.py`. PostgreSQL — источник истины для всего,
|
||||
включая состояние вложений и заданий; S3 — только для байтов; брокер — транспорт и будильник,
|
||||
потеря сообщения восстанавливается из PostgreSQL; Valkey — кэш сессий.
|
||||
|
||||
## Источники норм
|
||||
- `contracts/README.md` — нормативная семантика API, включая «Вложения (с lab4)» и
|
||||
«Фоновая обработка (с lab5)».
|
||||
- `contracts/openapi.json` — OpenAPI 3.1.0, обязательный минимум.
|
||||
- `contracts/jobs.schema.json`, `contracts/attachment-states.md` — сообщение брокера, машина
|
||||
состояний и окна отказа.
|
||||
- `contracts/infrastructure.json`, `infra/README.md` — роли инфраструктуры и что о них отчитать.
|
||||
- `README.md` — рубрика уровней «3» / «4» / «5».
|
||||
- `COURSE.md` — карта курса и объявленные переходы API между лабами.
|
||||
- `openspec/notes/architecture-patterns-python.md` — словарь паттернов и их компромиссов.
|
||||
|
||||
При расхождении артефакта с `contracts/` источником считается `contracts/`.
|
||||
Подгонка контракта или публичных тестов под реализацию решением не является.
|
||||
|
||||
rules:
|
||||
proposal:
|
||||
- "Пиши на русском; идентификаторы, поля, коды ошибок и имена файлов — в оригинальном виде."
|
||||
- "Держи в пределах 400 слов: Why / What changes / Impact без воды."
|
||||
- "Указывай, какой уровень рубрики закрывает изменение: «3», «4» или заявленный трек «5»."
|
||||
- "Обязательна секция «Non-goals» со ссылкой на Out of scope; не тащи в лабу 5 возможности лаб 6–7 и трека 1."
|
||||
- "Связывай изменение с конкретным пунктом рубрики `README.md` и строкой таблицы доказательств `REPORT.md`."
|
||||
- "Если изменение трогает `contracts/`, `tests/`, `README.md` или `COURSE.md` — это запрещено, оформляй как вопрос преподавателю."
|
||||
specs:
|
||||
- "Имя capability начинается с префикса лабы, в которой требование введено: `lab<N>-<имя>`, например `lab1-messenger-history`. Номер берётся из `lab.json`."
|
||||
- "Префикс означает происхождение, а не срок действия: требование с `lab1-` продолжает действовать в лабах 2–7, пока его явно не изменит новая дельта."
|
||||
- "Требование существующей capability правится дельтой к ней же, под её исходным префиксом; новый префикс заводится только для по-настоящему нового поведения."
|
||||
- "Дельта-спека описывает только наблюдаемое поведение, не реализацию."
|
||||
- "Требования о границах доменных зон формулируй как наблюдаемые: через поведение API или через проверяемый граф зависимостей модулей."
|
||||
- "Формулируй требования как `### Requirement:` плюс `#### Scenario:` в форме WHEN/THEN на русском."
|
||||
- "Для API-требований фиксируй метод, путь, коды ответов, заголовки и форму тела ошибки."
|
||||
- "Каждое требование трассируется на пункт `contracts/README.md` или на критерий рубрики `README.md`."
|
||||
- "Сценарии обязаны покрывать негативные пути и окна отказа: повторная доставка той же job (тот же `job_id`) до и после `ready`, worker остановлен, рестарт API и брокера с volume, недоступный S3 во время обработки, постоянная ошибка изображения, исчерпание `JOB_MAX_ATTEMPTS`, `/content` для `queued`, `processing` и `failed` (`409`), неизвестный `variant` (`400`), отсутствующий вариант `ready` (`404`), прикрепление `failed` к сообщению (`409`), сообщение брокера не по `jobs.schema.json`, а также прежние: файл ровно 10485760 и 10485761 байт, больше 40 млн пикселей, битый PNG/JPEG, подмена MIME, опасный `filename`, чужое и неизвестное вложение, посторонний на метаданных и скачивании, остановленная реплика, отсутствующий и неверный `Idempotency-Key`, чужой чат (404, не 403), истёкший токен."
|
||||
- "Для инфраструктурных требований фиксируй наблюдаемое: какие порты опубликованы, где лежат байты (bucket, volume), какие очереди и с какими свойствами видит `rabbitmqctl list_queues`, что лежит в очереди при остановленном worker, какие реплики видны по `X-Instance-Id`, что показывает `docker ps -a`."
|
||||
- "Не вводи в контракт поля и коды, которых нет в `contracts/openapi.json`."
|
||||
design:
|
||||
- "Создавай, если изменение затрагивает границы доменных зон, слои, агрегаты, конкурентность, идемпотентность, согласованность двух хранилищ, балансировку, поведение при сигналах или конфигурацию контейнера."
|
||||
- "Для каждого введённого паттерна отвечай по формуле книги: что за это получаем и чего это стоит."
|
||||
- "Явно называй порт, его адаптеры и точку сборки; проверяй правило зависимостей: домен не импортирует инфраструктуру."
|
||||
- "Указывай, к какой доменной зоне относится изменение; если оно задевает несколько — объясняй, каким портом, событием или внешним ключом они связаны."
|
||||
- "Всё, что кладётся в `shared/`, обосновывай отдельно: туда попадает только платформа и механизм связи, но не доменные понятия."
|
||||
- "Ошибки, события и команды принадлежат зоне; в `shared/` живут лишь их базовые типы, без кодов контракта."
|
||||
- "Для пары PostgreSQL + S3 фиксируй источник истины каждого факта, порядок записи (intent → PUT → COMMIT), что остаётся после сбоя на каждом шаге и кто это убирает; `201` — только после обеих записей."
|
||||
- "Для пары PostgreSQL + брокер фиксируй транзакционные границы (вложение, задание и outbox — одна транзакция), каждое окно отказа из `attachment-states.md`, что после него лежит в PostgreSQL, S3 и очереди и кто восстанавливает работу; отличай publisher confirm от consumer ack и объясняй, почему это at-least-once, а не exactly-once."
|
||||
- "Для обработки задания фиксируй ключ эффекта, условие захвата и аренды, условие фиксации результата (fencing), что делает повторная доставка на каждом шаге и почему она не создаёт второго набора вариантов и не откатывает `ready`."
|
||||
- "Для обработки файлов фиксируй, где и в каком порядке применяются лимиты (заголовок, поток, заголовок изображения, декодирование), сколько памяти занимает одна загрузка и сколько их идёт одновременно."
|
||||
- "Для балансировщика и S3-клиента фиксируй цепочку таймаутов клиент > LB > приложение > БД/S3 и политику повторов: какие запросы можно повторить и почему."
|
||||
- "Секреты, токены, ключи S3 и реальные данные в артефакт не попадают — только плейсхолдеры и имена переменных окружения."
|
||||
- "Отмечай, что требуется от контейнера: пользователь, закрепление версий, healthcheck, обработка SIGTERM, лимиты, опубликованные порты, переменные окружения."
|
||||
- "Для каждого хранилища называй источник истины, границы транзакций, поведение при недоступности (503 или обход) и что переживает рестарт."
|
||||
- "SQL описывай вместе с индексом, который его обслуживает, и ожидаемым планом; схему, ограничения и индексы фиксируй до запросов; миграции — аддитивные (expand/contract), совместимые с работающей версией."
|
||||
tasks:
|
||||
- "Задачи — атомарные шаги не длиннее 2 часов, в порядке исполнения."
|
||||
- "Группируй по слоям и артефактам: схема и миграции, доменные зоны, приложение, инфраструктура, точка входа, стенд, хуки отказов, тесты, измерения, отчёт."
|
||||
- "Одна задача не пересекает границу доменной зоны; связь зон (порт, событие или внешний ключ схемы) оформляется отдельной задачей."
|
||||
- "Первой в цепочке идёт задача уровня «3», задачи уровня «4» и трека «5» — после неё."
|
||||
- "Каждая группа завершается задачей проверки: какой командой убедиться, что критерий рубрики выполнен."
|
||||
- "Не создавай задач, меняющих `contracts/`, `tests/`, `README.md`, `COURSE.md` или рубрику."
|
||||
|
||||
operations:
|
||||
apply:
|
||||
guidance:
|
||||
- "Соблюдай правило зависимостей: адаптер добавляется за существующим портом, а не импортом инфраструктуры в домен."
|
||||
- "Новый код кладётся в свою доменную зону вместе со своими ошибками, событиями, командами и HTTP-фасадом."
|
||||
- "`shared/` пополняется только платформой и механизмом связи; доменное понятие туда не попадает никогда."
|
||||
- "Коды контракта и HTTP-статусы объявляет зона в своём `entrypoints/errors.py`; платформа только применяет реестр."
|
||||
- "Роутер, провайдер DI, журнал, отображение ошибок и настройки зоны лежат в её `entrypoints/` и `config.py`."
|
||||
- "Ядро `shared/` (domain, application, infrastructure) не импортирует веб-фреймворк: транспорт живёт только в `shared/entrypoints/` и в `entrypoints/` зон."
|
||||
- "Отдельного каталога точек входа на верхнем уровне не заводи: общее кладётся в `shared/`, доменное — в зону, сборка процессов и связывание зон портами — в `main.py`, `relay.py` и `worker.py`."
|
||||
- "Зоны не импортируют модули друг друга, кроме объявления события, — это проверяется тестом; в БД связь зон — только внешний ключ, SQL зоны читает лишь свои таблицы."
|
||||
- "Пиши под Python 3.14 с ленивыми аннотациями: без `TYPE_CHECKING` и без `from __future__ import annotations`."
|
||||
- "Логирование — только через порт `Logger`; второй логгер в приложении не заводится. Object key, ключи S3 и содержимое файлов в журнал не пишутся."
|
||||
- "Код приложения — в `src/`, конфигурация LB, нагрузки и S3 — в `infra/`, собственные тесты — в `student-tests/`, обезличенные доказательства — в `evidence/`."
|
||||
- "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`."
|
||||
- "SQL только параметризованный (`$1`, `$2`); значения из запроса никогда не склеиваются в текст запроса."
|
||||
- "Тело загрузки читается потоком со счётчиком до лимита; изображение не декодируется целиком до проверки размера по заголовку; тяжёлая проверка идёт в потоке под ограничением параллелизма."
|
||||
- "API не обрабатывает изображения синхронно и не подключается к брокеру: задание уходит только через outbox; `202` возвращает снимок записанного объекта."
|
||||
- "Worker и relay не объявляют очереди и exchange: топология и права — в `infra/rabbitmq/`; `ack` — строго после `COMMIT`, сообщение брокера — ровно поля `jobs.schema.json`."
|
||||
- "FastStream и aio-pika живут только в `entrypoints/` и `infrastructure/` зоны вложений и в сборке процесса; `shared/` их не импортирует."
|
||||
- "Реплика не хранит в памяти процесса и на своём диске ничего, от чего зависит корректность ответа другой реплики: сессии, ключи идемпотентности, курсоры и файлы — через общее хранилище или общий секрет."
|
||||
- "Ошибка зависимости (PostgreSQL, Valkey, S3, брокер) превращается в `503 unavailable` за ограниченное время; отказ кэша обходится и никогда не превращается в анонимный доступ."
|
||||
- "Схема меняется только новым файлом миграции; применённую миграцию не редактируют; миграция совместима с работающей предыдущей версией."
|
||||
- "Публичные `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` запускаются против поднятого стенда (`make up`) через LB после готовности всех реплик; после failover реплика возвращается `make restore`."
|
||||
- "Каждый заявленный критерий рубрики подтверждай командой и наблюдаемым результатом в `REPORT.md`; PASS без команды доказательством не считается."
|
||||
- "Отмечай выполнение в `tasks.md`; резюме держи кратким."
|
||||
archive:
|
||||
guidance:
|
||||
- "Имя архивной папки начинается с даты архивации в формате `ГГГГ-ММ-ДД`, а не с даты создания change."
|
||||
- "В `.openspec.yaml` архивной папки проставь `archived: <дата архивации>` и `lab: <номер из lab.json>` — по ним видно, когда и в какой лабе изменение закрыто."
|
||||
- "Перед архивацией сверься с рубрикой `README.md`: какой уровень закрывает изменение и каким файлом доказательства."
|
||||
- "Убедись, что `make check`, `make validate`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` и сценарии отказов уровня (`make level3`, `make level4`, `make track2`) против стенда проходят."
|
||||
- "Сохранившиеся дальше требования должны попасть в `openspec/specs/`, иначе исчезнут вместе с архивом."
|
||||
- "Зафиксируй, что именно демонстрируется в сценарии защиты и какие измерения приложены к треку «5»."
|
||||
@@ -0,0 +1,349 @@
|
||||
# Паттерны разработки на Python — рабочая заметка
|
||||
|
||||
Источник: Гарри Персиваль, Боб Грегори. «Паттерны разработки на Python: TDD, DDD и событийно-ориентированная архитектура» (Architecture Patterns with Python), Питер, 2022, 336 с.
|
||||
Файл: `~/Library/Mobile Documents/com~apple~CloudDocs/Книги/Паттерны разработки на Python.pdf`. **Номер страницы PDF = номер страницы книги (смещение 0)** — ссылки ниже кликаются напрямую.
|
||||
|
||||
Ремарка о стеке (дальше не повторяется): все примеры книги показаны на конкретном веб-фреймворке, ORM и pub/sub-хранилище. Ниже они обобщены до ролей — «точка входа», «ORM», «брокер сообщений». Стек выбирается отдельно, ни один паттерн от него не зависит.
|
||||
|
||||
Формула книги (Рич Хикки, с. 65): при вводе каждого паттерна спрашивать «что мы за это получаем и чего это стоит». Ни один паттерн в книге не подаётся как обязательный.
|
||||
|
||||
---
|
||||
|
||||
## 1. Модель предметной области (Domain Model)
|
||||
|
||||
Слой, где живёт вся бизнес-логика, выраженный языком бизнеса и свободный от инфраструктуры.
|
||||
|
||||
**Задача.** Бизнес-логика расползается по всем слоям (контроллеры, «менеджеры», хранимки), её невозможно найти, понять и изменить. Разработчики начинают со схемы БД, а объектная модель появляется с запозданием — «на первом месте должно быть поведение, которое управляет требованиями к хранилищу» (с. 29).
|
||||
|
||||
Строительные блоки: **сущность** (entity) — идентичность сохраняется при смене атрибутов; **объект-значение** (value object) — немутируемый, полностью определяется атрибутами, взаимозаменяем; **служба предметной области** (domain service) — глагол, который не принадлежит ни одной сущности, обычная функция. Исключения тоже часть языка предметной области.
|
||||
|
||||
| Применять | Не применять |
|
||||
|---|---|
|
||||
| Сложная бизнес-логика, много правил и крайних случаев | Приложение — простая CRUD-оболочка над БД («модель предметной области или репозиторий вам не нужны», с. 71) |
|
||||
| Правила меняются чаще, чем инфраструктура | Логика тождественна схеме данных — тогда чтение и запись связаны, и разделение не окупается (с. 236) |
|
||||
| Нужны юнит-тесты как живая документация правил | Работает график с. 72: для простых доменов ORM/Active Record дешевле, кривые пересекаются только при росте сложности |
|
||||
|
||||
**Связи.** Требует «Репозиторий», чтобы остаться не осведомлённой о хранении. Требует «Агрегат», чтобы задать границу согласованности. Заменяет анемичную модель + толстые сервисы. Позже отдаёт побочные эффекты «Событиям предметной области».
|
||||
Отдельная таблица «плюсы/минусы» для главы 1 в книге отсутствует — компромисс сформулирован в главе 2 (табл. 2.1, рис. 2.6) и в «Итогах части I».
|
||||
|
||||
---
|
||||
|
||||
## 2. Репозиторий (Repository)
|
||||
|
||||
Абстракция над постоянным хранением: коллекция объектов, как будто целиком лежащая в памяти.
|
||||
|
||||
**Задача.** Модель предметной области не должна знать о БД. Минимальный интерфейс — `add()` и `get()`. Список/удаление/обновление в идеале не нужны: удаление — мягкое (метод домена), обновление — забота UoW.
|
||||
|
||||
| Применять (плюсы) | Не применять (минусы) |
|
||||
|---|---|
|
||||
| Простой интерфейс между хранилищем и доменом | ORM и так частично устраняет связанность: сменить одну СУБД на другую будет довольно легко, хотя поменять внешние ключи может оказаться непросто |
|
||||
| Тривиально подделывается для юнит-тестов (fake = обёртка над `set`) | Ручное отображение объектов на таблицы — дополнительная работа и код |
|
||||
| Модель пишется до планирования хранения — фокус на бизнес-задаче, миграции откладываются | Ещё один слой косвенности: рост стоимости сопровождения и «фактор WTF» для тех, кто паттерна не видел |
|
||||
| Полный контроль над схемой БД, она остаётся простой | Для CRUD-обёртки — не нужен вовсе |
|
||||
|
||||
**Связи.** Реализует принцип инверсии зависимостей на уровне данных: ORM импортирует модель, а не наоборот. `AbstractRepository` — **порт**, конкретная и поддельная реализации — **адаптеры**. Один агрегат = один репозиторий, репозиторий возвращает **только** агрегаты (гл. 7). Начиная с гл. 6 доступ к репозиториям выдаёт UoW, а не точка входа. Начиная с гл. 8 репозиторий ведёт `.seen` — множество загруженных агрегатов, откуда UoW собирает события.
|
||||
Эвристика (с. 70): «если делать подделки трудно, то абстракция, вероятно, слишком сложная».
|
||||
|
||||
---
|
||||
|
||||
## 3. Сервисный слой / варианты использования (Service Layer, Use Cases)
|
||||
|
||||
Оркестровка: тонкий API приложения, где каждый вариант использования — одна функция.
|
||||
|
||||
**Задача.** Логика оркестровки (достать → проверить → вызвать домен → сохранить) заползает в контроллеры. Типовая функция слоя: извлечь объекты из репозитория, проверить предусловия, вызвать службу предметной области, сохранить изменения.
|
||||
Не путать со **службой предметной области**: доменная служба выражает бизнес-концепцию, сервисный слой — способ использования приложения; сервисный слой часто вызывает доменную службу.
|
||||
|
||||
| Применять (плюсы) | Не применять (минусы) |
|
||||
|---|---|
|
||||
| Единое место для всех сценариев использования | Приложение исключительно веб — контроллеры и так единственная точка сбора сценариев |
|
||||
| Домен спрятан за API — его можно свободно перерабатывать | Ещё один слой абстракции |
|
||||
| «Всё про HTTP» отделено от «всё про предметную область» | Слишком много логики в сервисном слое → антипаттерн «анемичная модель» |
|
||||
| Вместе с репозиторием даёт быстрые тесты выше уровня домена | Часто хватает «толстых моделей, тонких контроллеров» — вытолкнуть логику из контроллера вниз, в модель, без промежуточного слоя |
|
||||
|
||||
**Связи.** Требует «Репозиторий» (зависит от абстракции, не от реализации). До гл. 6 связан с сессией БД — развязывается через UoW. Аргументы выражаются **примитивами**, не доменными объектами (гл. 5) — иначе тесты слоя остаются связанными с доменом. В гл. 9 функции сервисного слоя становятся **обработчиками сообщений** (`services.py` → `handlers.py`), и разница между «службой» и «обработчиком» исчезает.
|
||||
Совет из книги: вводить слой после того, как заметили оркестровку в контроллерах, а не заранее.
|
||||
|
||||
---
|
||||
|
||||
## 4. Абстракции и выбор швов (гл. 3)
|
||||
|
||||
Отделять «что сделать» от «как сделать»: функциональное ядро + императивная оболочка.
|
||||
|
||||
**Задача.** Высокоуровневый код сцеплен с вводом-выводом, тесты медленные и громоздкие, добавить режим `--dry-run` или другой бэкенд невозможно.
|
||||
Приём: представить состояние внешнего мира простой структурой данных, а результат работы — списком команд-намерений; чистое ядро принимает и возвращает структуры данных, оболочка выполняет ввод-вывод.
|
||||
|
||||
Таблицы компромиссов у главы нет — вместо неё **четыре вопроса-эвристики** (с. 89):
|
||||
1. Какой знакомой структурой данных представить состояние запутанной системы, и какая одна функция может её вернуть?
|
||||
2. Где провести грань, вырезать **шов**, чтобы вставить абстракцию?
|
||||
3. Как разделить код на компоненты с разными обязанностями? Какие неявные концепции сделать явными?
|
||||
4. Каковы зависимости и какова ключевая бизнес-логика?
|
||||
|
||||
**Связи.** Это обоснование для всех остальных абстракций книги: репозиторий, UoW, шина сообщений — частные случаи. «Проектирование с учётом тестопригодности означает проектирование с учётом расширяемости» (с. 87).
|
||||
|
||||
---
|
||||
|
||||
## 5. TDD по слоям: подделки против имитаций, повышенная и пониженная передачи
|
||||
|
||||
Тесты — в первую очередь практика проектирования, во вторую — практика тестирования.
|
||||
|
||||
**Определения (врезка в гл. 3, с. 87).** **Имитация** (mock) проверяет, *как* нечто использовалось (`assert_called_once_with`), лондонская школа. **Подделка** (fake) — рабочая реализация только для тестов (репозиторий в памяти), утверждения делаются о *конечном состоянии*, классическая школа. Авторы твёрдо на стороне классиков: избыток имитаций скрывает предмет теста.
|
||||
|
||||
**Спектр тестов (рис. 5.1).** Тесты домена: эффективная обратная связь по дизайну, точечный охват, высокий барьер для изменений, хрупкие. Тесты API: широкий охват, низкий барьер, но ничего не говорят о дизайне объектов. Тесты сервисного слоя — компромисс посередине.
|
||||
|
||||
**Передачи.** *Пониженная* — тесты прямо на модель: новый проект, особенно сложная задача, нужно нащупать дизайн и получить документацию. *Повышенная* — тесты на сервисный слой: обычная фича или багфикс, меньше связанности, шире охват, свобода рефакторить модель.
|
||||
|
||||
Таблицы у главы нет; вместо неё врезка **«Эмпирические правила для разных типов тестов»** (с. 119):
|
||||
|
||||
| Уровень | Сколько | Зачем |
|
||||
|---|---|---|
|
||||
| Сквозной (E2E) | ~1 на функциональное свойство | Показать, что все движущиеся части склеены |
|
||||
| Сервисный слой | Основная масса | Все крайние случаи бизнес-логики, ввод-вывод подделан |
|
||||
| Модель предметной области | Малое ядро | Самая эффективная обратная связь по дизайну; удалять без сожаления, когда покрыто выше |
|
||||
| Несчастливые пути | 1 сквозной на все + много юнит-тестов | Обработка ошибок трактуется как отдельное функциональное свойство |
|
||||
|
||||
**Связи.** Работает только при наличии сервисного слоя и подделок репозитория/UoW. «Каждая строка кода в тесте удерживает систему в определённой форме, словно капля клея» (с. 111). Признак недоработанного сервисного слоя: в его тестах приходится напрямую собирать доменные объекты.
|
||||
|
||||
---
|
||||
|
||||
## 6. UoW — единица работы (Unit of Work)
|
||||
|
||||
Абстракция идеи атомарной операции; контекстный менеджер, внутри которого либо всё, либо ничего.
|
||||
|
||||
**Задача.** Сервисный слой напрямую держит сессию БД; точка входа общается сразу с тремя слоями. UoW оставляет точке входа две задачи: создать UoW и вызвать службу.
|
||||
Фиксация **явная**, откат — по умолчанию: единственный путь к изменению состояния — полный успех и явный commit; любой ранний выход оставляет систему в безопасном состоянии.
|
||||
|
||||
| Применять (плюсы) | Не применять (минусы) |
|
||||
|---|---|
|
||||
| Хорошая абстракция атомарности; блоки кода видны глазами | ORM/фреймворк, вероятно, уже даёт такую абстракцию (сессия + контекстный менеджер) — можно просто передавать сессию |
|
||||
| Явный контроль границ транзакции, отказ безопасен по умолчанию | Откаты, многопоточность, вложенные транзакции требуют отдельного продумывания — «выглядит легко» обманчиво |
|
||||
| Единая точка доступа ко всем репозиториям | |
|
||||
| Позже — место сбора и публикации событий | |
|
||||
|
||||
**Связи.** Требует «Репозиторий» (предоставляет его наружу) и завершает связку с «Сервисным слоем»: один вариант использования = один UoW, успешный или неуспешный целиком. Требуется «Агрегатом» для соблюдения инвариантов на уровне БД. В гл. 8 UoW становится издателем событий, в гл. 10 — источником очереди сообщений (`collect_new_events`).
|
||||
|
||||
---
|
||||
|
||||
## 7. Агрегат и границы согласованности (Aggregate, Consistency Boundary)
|
||||
|
||||
Кластер связанных объектов, изменяемый как единое целое; единственная публичная точка входа в своё поддерево модели.
|
||||
|
||||
**Задача.** **Ограничение** — правило, лимитирующее возможные состояния; **инвариант** — условие, всегда истинное. Соблюдать инварианты при параллельной записи, не блокируя всю таблицу. Агрегат очерчивает минимальный кусок модели, который должен быть согласован атомарно; всё, что вне его, согласуется в конечном счёте.
|
||||
Правило выбора: граница вокруг наименьшего числа объектов, которые обязаны быть согласованы; ей нужно хорошее имя из языка предметной области. Правильного ответа нет — выбор пересматривается, если упирается в производительность.
|
||||
|
||||
**Конкурентность.** Оптимистическая блокировка через номер версии на агрегате (конфликт ловится, операция повторяется) против пессимистической — блокировка строк/`SELECT FOR UPDATE` (конфликта не будет, но возможны тупики и просадка). Номер версии книга размещает **в домене**: сервисный слой раздваивает ответственность между слоями, а UoW/репозиторий могут сделать это, лишь допустив, что изменились все агрегаты, — и наращивают версию там, где это не нужно.
|
||||
|
||||
| Применять (плюсы) | Не применять (минусы) |
|
||||
|---|---|
|
||||
| Явно делит классы модели на «публичные» и «внутренние» | Третий тип доменного объекта поверх сущности и объекта-значения — рост порога входа |
|
||||
| Моделирование вокруг явных границ снимает проблемы производительности ORM | Правило «менять только один агрегат за транзакцию» — большой сдвиг в мышлении |
|
||||
| Единственная ответственная точка за инварианты — проще рассуждать о системе | Работать с итоговой согласованностью между агрегатами сложно |
|
||||
|
||||
**Связи.** **Один агрегат = один репозиторий**, репозиторий возвращает только агрегаты. Требует UoW для атомарности. Порождает потребность в «Событиях предметной области»: если процесс пересекает границу агрегатов, его нельзя выполнить одной транзакцией. Диагностика из эпилога (с. 285): нужда атомарно обновить два агрегата означает, что граница выбрана неверно.
|
||||
Соседняя концепция — **ограниченный контекст** (bounded context): одно и то же слово в разных контекстах значит разное; модель включает только данные, нужные для её расчётов. Выбор агрегатов = выбор контекста, в котором они живут.
|
||||
|
||||
---
|
||||
|
||||
## 8. События предметной области (Domain Events)
|
||||
|
||||
Немутируемые классы данных — факты о произошедшем, зарегистрированные моделью.
|
||||
|
||||
**Задача.** Побочное требование («когда товара нет — уведомить закупки») некуда положить: в контроллере — не его дело, в модели — зависимость от инфраструктуры, в сервисном слое — нарушение принципа единственной обязанности. Признак нарушения: работу функции нельзя описать без «затем» и «и».
|
||||
Модель **регистрирует** факт на языке предметной области; реагировать на него — обязанность кого-то другого.
|
||||
|
||||
**Три схемы публикации** (номера вариантов в тексте главы и в её резюме не совпадают, поэтому лучше различать их по издателю):
|
||||
- публикует **сервисный слой**, забирая события из модели — проще всего, работает;
|
||||
- **модель порождает, сервисный слой публикует** — логика «когда инициировать» живёт рядом с правилом;
|
||||
- публикует **UoW**, обходя `.seen` после фиксации — выбор авторов: сервисный слой полностью чист, но механизм «загадочный».
|
||||
|
||||
| Применять (плюсы) | Не применять (минусы) |
|
||||
|---|---|
|
||||
| Хороший способ развести несколько действий в ответ на один запрос | Ещё один механизм; вариант с публикацией из UoW изящен, но неочевиден — из вызова commit не видно, что уйдёт письмо |
|
||||
| Обработчики отцеплены от стержневой логики, их реализацию легко менять | Скрытая обработка выполняется **синхронно** — неожиданные просадки на веб-эндпоинтах |
|
||||
| События хорошо ложатся на деловой язык, годятся для работы со стейкхолдерами | Событийный поток размазан по цепочке обработчиков — нет одного места, где видно, как выполняется запрос |
|
||||
| | Риск циклических зависимостей и бесконечных циклов между обработчиками |
|
||||
|
||||
**Связи.** **Заменяет** исключения как поток управления: «если вы реализуете события предметной области, то не инициируйте исключения для описания той же концепции» (с. 169). Требует UoW (границы транзакции) и репозитория (`.seen`). Даёт агрегатам способ влиять друг на друга без длинных транзакций на несколько таблиц. Требует «Шину сообщений» как маршрутизатор.
|
||||
|
||||
---
|
||||
|
||||
## 9. Шина сообщений и обработчики (Message Bus, Handlers)
|
||||
|
||||
Словарь «тип сообщения → список обработчиков»; немая инфраструктура, ничего не знающая о смысле событий.
|
||||
|
||||
**Задача.** Дать событиям адресатов и позволить обработчикам порождать новые события, не превращая код в цепочку прямых вызовов. Дальше — радикальный шаг гл. 9: **входы в систему тоже становятся сообщениями**, функции сервисного слоя становятся обработчиками, различие «внутреннее/внешнее» исчезает. Обработчиков у одного события может быть несколько; они могут инициировать другие события.
|
||||
Важно: шина обрабатывает по одному обработчику за раз. Цель не параллелизм, а концептуальное разделение задач и минимально малый UoW.
|
||||
|
||||
| Применять (плюсы) | Не применять (минусы) |
|
||||
|---|---|
|
||||
| Обработчики и службы — одно и то же, конструкций меньше | Непредсказуемость для веб-процесса: заранее не известно, когда всё закончится |
|
||||
| Изящная структура данных на входе в систему | Неизбежное дублирование между объектами модели и событиями: поле добавляется минимум в двух местах |
|
||||
| Сложные требования добавляются без архитектурных изменений — только новые события и обработчики | |
|
||||
|
||||
**Связи.** Требует «События предметной области». Поглощает «Сервисный слой» (`services.py` → `handlers.py`). Требует разделения на команды и события (гл. 10), иначе непонятно, что обязано выполниться. В гл. 13 превращается из модуля-одиночки в класс с внедрёнными обработчиками. Тестировать сначала «от края до края» и переходить к изолированным юнит-тестам обработчиков (через поддельную шину) только по мере усложнения цепочек.
|
||||
|
||||
---
|
||||
|
||||
## 10. Команды против событий (Commands vs Events)
|
||||
|
||||
Два вида сообщений, обрабатываемых одной шиной по разным правилам.
|
||||
|
||||
| | Событие | Команда |
|
||||
|---|---|---|
|
||||
| Имя | Прошедшее время («заказ размещён») | Повелительное наклонение («разместить заказ») |
|
||||
| Смысл | Факт о прошлом | Намерение, чего мы хотим от системы |
|
||||
| Отправка | Всем слушателям, отправитель их не знает | Одному получателю |
|
||||
| Обработчиков | Много | Ровно один |
|
||||
| Отказ | Независимый: логируется, повторяется, поток не прерывает | Заметный: исключение всплывает к отправителю |
|
||||
|
||||
**Задача.** Отделить то, что обязано выполниться (команда пользователя, меняющая один агрегат), от того, что можно доделать позже (уведомления, проекции, обновление соседних агрегатов). Успех команды не зависит от успеха обработчиков событий — занятый почтовый сервер не должен мешать принять оплату.
|
||||
Восстановление: повторные попытки с экспоненциальной задержкой; каждая попытка начинается с согласованного состояния благодаря UoW.
|
||||
|
||||
| Применять (плюсы) | Не применять (минусы) |
|
||||
|---|---|
|
||||
| Видно, что обязано выполниться, а что можно привести в порядок позже | Семантическая граница между командой и событием тонкая, споры о ней бывают жаркими |
|
||||
| Имя «CreateBatch» честнее, чем «BatchCreated», для входа в систему | Отказы допускаются намеренно: система становится менее понятной и требует более качественного мониторинга |
|
||||
|
||||
**Связи.** **Заменяет** события-как-входы из гл. 9 (`Allocate` ← `AllocationRequired`, `CreateBatch` ← `BatchCreated`). Требует агрегата как границы согласованности — именно он гарантирует, что отказ обработчика не оставит систему в противоречивом состоянии. Требует UoW для атомарности каждой попытки. Известен также как паттерн «Обработчик команд» (Command Handler).
|
||||
|
||||
---
|
||||
|
||||
## 11. Событийно-управляемая архитектура и интеграция служб (гл. 8–11, внешние события — гл. 11)
|
||||
|
||||
Службы интегрируются асинхронными сообщениями через брокер, а не синхронными вызовами API.
|
||||
|
||||
**Антипаттерн.** Резать систему по **существительным** (Заказы, Партии, Клиенты), давать каждой таблице микросервис и CRUD-интерфейс поверх анемичной модели. Граф вызовов быстро запутывается в обе стороны, а сетевой отказ одной службы бьёт по надёжности другой — «распределённый комок грязи».
|
||||
**Лекарство.** Думать **глаголами**: не «система заказов», а «процесс размещения заказа». Микросервисы — такие же границы согласованности, как агрегаты: служба принимает внешние команды, публикует события, остальные слушают. Внутренние и внешние события держать раздельно; исходящие обязательно валидировать.
|
||||
Архитектурно это то же приложение: сервисный слой + UoW, перенастроенные как асинхронный процессор сообщений. Потребитель событий транслирует внешние сообщения во внутренние команды, издатель выталкивает внутренние события наружу.
|
||||
|
||||
| Применять (плюсы) | Не применять (минусы) |
|
||||
|---|---|
|
||||
| Не даёт вырасти распределённому комку грязи | Совокупный поток информации труднее увидеть; логический процесс размазан по уведомлениям и неявен в коде |
|
||||
| Службы отцеплены: проще менять существующие и добавлять новые | Конечная согласованность — новая концепция, с которой надо уметь работать |
|
||||
| Отказ части системы не блокирует остальные | Надёжность доставки: выбирать между «как минимум один раз» и «как максимум один раз» |
|
||||
|
||||
**Связи.** Тот же аппарат, что для внутренних событий, только транспорт другой. Требует агрегатов (границы), команд/событий (что обязано, что нет), шины сообщений. Микросервисы **не обязательны** для остальных паттернов: «эти методы появились примерно на десять лет раньше микросервисов» (с. 287).
|
||||
|
||||
**Мелкий шрифт (эпилог, «Выстрел в ногу»).** Надёжный обмен сообщениями организовать очень сложно; лёгкий pub/sub из примеров ненадёжен и не годится как общецелевой транспорт. Мелкие независимо отказывающие транзакции требуют мониторинга и воспроизведения событий (см. паттерн Outbox). Идемпотентность обработчиков в книге не рассмотрена, а на практике обязательна. Схемы событий будут меняться — нужен способ версионирования и публикации схемы для потребителей.
|
||||
|
||||
---
|
||||
|
||||
## 12. CQRS — разделение обязанностей команд и запросов
|
||||
|
||||
Чтение и запись — разные задачи, поэтому у них разные модели.
|
||||
|
||||
**Задача.** Модель предметной области построена под запись: инварианты, транзакционная согласованность, сложная логика. Для чтения она неудобна и медленна — приходится дописывать вспомогательные методы в репозиторий и агрегат, гонять фильтрацию в приложении вместо БД.
|
||||
|
||||
| | Сторона чтения | Сторона записи |
|
||||
|---|---|---|
|
||||
| Поведение | Простое чтение | Сложная бизнес-логика |
|
||||
| Кешируемость | Хорошая | Непригодна |
|
||||
| Согласованность | Может быть устаревшей | Обязана быть транзакционной |
|
||||
|
||||
**Ключевой аргумент.** Устаревшее чтение безопасно: данные устаревают в момент открытия страницы, и любое размещение всё равно перепроверяет текущее состояние при записи. Никакая система не согласована с реальностью — бизнес-процессы на крайние случаи нужны в любом случае. Поэтому согласованность чтения разумно менять на производительность и горизонтальное масштабирование (реплики чтения не нужно согласовывать между собой).
|
||||
Более слабая версия принципа — **CQS**: функция либо меняет состояние, либо отвечает на вопрос, но не то и другое сразу (частный случай — веб-паттерн POST/Redirect/GET).
|
||||
|
||||
| Вариант модели чтения | Плюсы | Минусы |
|
||||
|---|---|---|
|
||||
| Через существующий репозиторий | Простой согласованный подход | Просадки на сложных запросах; в репозиторий и модель лезут ненужные вспомогательные методы |
|
||||
| Запросы через ORM | Переиспользуются конфигурация БД и определения модели | Ещё один язык запросов со своими причудами; риск `SELECT N+1` |
|
||||
| Ручной SQL в отдельном модуле представлений | Точный контроль над производительностью, стандартный синтаксис | Изменения схемы надо вносить и в запросы, и в определения ORM; сильно нормализованные схемы всё равно упираются в join'ы |
|
||||
| Отдельное денормализованное хранилище чтения, обновляемое обработчиками событий | Реплики только для чтения масштабируются легко; запросы предельно просты | Самый сложный вариант |
|
||||
|
||||
**Не применять**, если приложение — простой CRUD: чтение и запись там тесно связаны, ни модель предметной области, ни CQRS не нужны. Полномасштабный CQRS с отдельным хранилищем — крайний случай; выделение представлений в отдельный модуль «только для чтения» полезно само по себе.
|
||||
|
||||
**Связи.** Сторона чтения **сознательно обходит** репозиторий и модель предметной области — книга разбирает обе «очевидные альтернативы» и отвергает их. Модель чтения обновляется обработчиками событий, то есть **требует** событий и шины. Модель чтения перестраиваема: прогнать текущее состояние стороны записи через тот же обработчик. Интеграционный тест пишется через шину сообщений — тогда он переживает смену реализации хранилища чтения.
|
||||
|
||||
---
|
||||
|
||||
## 13. Инверсия зависимостей (DIP) — правило зависимостей
|
||||
|
||||
Формулировка (с. 26): (1) высокоуровневые модули не зависят от низкоуровневых, оба зависят от абстракций; (2) абстракции не зависят от деталей, детали зависят от абстракций.
|
||||
|
||||
**Высокоуровневые модули** — то, что интересует организацию (пациенты, сделки, инциденты). **Низкоуровневые** — то, что ей неинтересно: файловые системы, сокеты, протоколы. «Зависит от» шире, чем «импортирует»: это знание одного модуля о другом.
|
||||
Смысл — менять бизнес-логику и инфраструктуру независимо: правки в домене не должны тормозить из-за миграций, а шардирование БД не должно требовать правок в бизнес-слое.
|
||||
|
||||
**Порты и адаптеры в терминах книги.** Термин «луковая архитектура» книга не использует; её словарь — **порты и адаптеры**, **гексагональная/чистая архитектура**, «выворачиваем трёхслойную архитектуру наизнанку».
|
||||
|
||||
| Понятие | Что это в книге |
|
||||
|---|---|
|
||||
| Порт | Интерфейс между приложением и абстрагируемым: абстрактный базовый класс либо просто утиный тип (имена методов и типы аргументов) |
|
||||
| Адаптер | Реализация за этим интерфейсом |
|
||||
| Первичные (ведущие) адаптеры | Точки входа: HTTP API, CLI, потребитель событий, **тесты** |
|
||||
| Вторичные (ведомые) адаптеры | Репозиторий, издатель событий, отправка уведомлений — всё, что смотрит наружу из системы |
|
||||
|
||||
Каталоги, отражающие это правило: `domain/`, `service_layer/`, `adapters/`, `entrypoints/`; порт обычно лежит рядом со своими адаптерами.
|
||||
**Проверка правила зависимостей.** Домен не импортирует ничего инфраструктурного; ORM импортирует модель, а не наоборот; сервисный слой зависит от абстрактного репозитория/UoW; конкретные реализации подключаются на внешнем краю системы.
|
||||
|
||||
---
|
||||
|
||||
## 14. Внедрение зависимостей и сценарий начальной загрузки (DI, Bootstrap)
|
||||
|
||||
Одно место, где приложение собирается: `bootstrap.py` — точка сборки (composition root).
|
||||
|
||||
**Задача.** До гл. 13 книга обходится без DI-фреймворка вообще. Проблема возникает, когда зависимостей становится несколько: неявные зависимости через импорт приходится глушить `mock.patch` в каждом тесте, а явные — руками протаскивать через каждую точку входа (веб, потребитель событий, тесты), дублируя проводку.
|
||||
Сценарий начальной загрузки обязан: объявить зависимости по умолчанию с возможностью переопределить; выполнить одноразовую инициализацию (маппинги ORM, логирование); внедрить зависимости в обработчики; вернуть готовую шину сообщений.
|
||||
Внедрение делается замыканиями или частичным применением. Книга показывает и «магический» вариант (инспекция сигнатур), и полностью ручной список лямбд — авторы отмечают, что ручной вариант жизнеспособен и при десятках обработчиков.
|
||||
|
||||
Таблицы компромиссов у главы нет; из «Выводов»:
|
||||
|
||||
| Стоит | Не стоит |
|
||||
|---|---|
|
||||
| Адаптеров несколько и проводка дублируется по точкам входа | Один-два адаптера и никакого дублирования — явная передача аргументов дешевле |
|
||||
| Нужно одно место для разумных умолчаний и для подмены адаптеров подделками в тестах | |
|
||||
| Есть **цепочки** зависимостей (у зависимостей свои зависимости) или внедрение в разных местах — тогда оправдан и полноценный DI-фреймворк | Внедрение только в обработчики — «ручной» DI достаточен, фреймворк избыточен |
|
||||
|
||||
**Рецепт «правильного» адаптера (с. 267).** 1) определить API абстрактным базовым классом; 2) реализовать настоящий; 3) сделать подделку для юнит-тестов и тестов обработчиков; 4) найти «менее поддельную» версию для контура (тестовый сервер сервиса); 5) протестировать её интеграционно.
|
||||
|
||||
**Связи.** **Заменяет** проводку в точках входа: они теперь только транслируют вход в команды и передают их шине. Требует, чтобы шина стала классом с внедрёнными обработчиками. Не то же самое, что DIP: DIP — правило направления зависимостей, DI — механика их подстановки.
|
||||
|
||||
---
|
||||
|
||||
## Сквозная логика книги
|
||||
|
||||
**Как складываются слои.** Домен (сущности, объекты-значения, агрегаты, доменные службы, события) ← сервисный слой / обработчики (варианты использования, оркестровка, UoW) ← точки входа (HTTP, CLI, потребитель событий, тесты). Наружу — адаптеры (репозиторий, издатель событий, уведомления). Всё собирается загрузчиком.
|
||||
|
||||
**Правило зависимостей.** Стрелки всегда указывают внутрь, к домену. Домен ничего не знает о слоях снаружи. Каждое пересечение границы идёт через порт: сервисный слой зависит от `AbstractRepository`/`AbstractUnitOfWork`, а не от их реализаций; тесты и продакшн подставляют разные адаптеры за одним и тем же портом. Книга описывает это как «выворачивание трёхслойной архитектуры наизнанку»: слой БД перестаёт быть фундаментом и становится деталью на внешнем краю.
|
||||
|
||||
**Направление развития по книге.** Модель предметной области → репозиторий (снимаем БД) → сервисный слой (снимаем HTTP) → UoW (снимаем сессию) → агрегат (границы согласованности) → события (снимаем побочные эффекты) → шина (входы становятся сообщениями) → команды/события (что обязано, что нет) → внешние события (границы служб) → CQRS (отделяем чтение) → загрузчик (собираем всё в одном месте). Каждый шаг вводится **после** того, как показана боль без него, — порядок в проекте разумно повторять.
|
||||
|
||||
**Когда весь аппарат не нужен.**
|
||||
- «Если ваше приложение представляет собой простую CRUD-обёртку вокруг базы данных, то модель предметной области или репозиторий вам не нужны» (с. 71).
|
||||
- «Если ваше приложение по сути является простой обёрткой CRUD вокруг базы данных и вряд ли будет чем-то большим в обозримом будущем, то вам эти паттерны не нужны. Используйте [фреймворк] и дальше и избавьте себя от многих хлопот» (с. 158).
|
||||
- График с. 72: при низкой сложности домена ORM/Active Record дешевле; кривые пересекаются только при её росте. Слои косвенности стоят сложности, дублирования и порога входа для новых разработчиков.
|
||||
- CQRS не нужен там, где чтение и запись концептуально совпадают.
|
||||
- Микросервисы не требуются ни одним из паттернов.
|
||||
|
||||
**Как внедрять в существующий комок грязи (эпилог).**
|
||||
1. Сформулировать проблему: трудно менять? тормозит? необъяснимые баги? Без цели не расставить приоритеты и не убедить команду.
|
||||
2. Продавать как «налог на архитектуру» под конкретную новую функциональность: три недели чистки под полугодовой проект защитить легко.
|
||||
3. Начать с **сервисного слоя**: выписать варианты использования (имена в повелительном наклонении), у каждого — своя транзакция, свои предусловия, свой атомарный успех/провал.
|
||||
4. Дублирование на этом шаге допустимо и даже желательно: скопировать код в новое место, там привести в порядок, потом переключить вызовы. «Лучше дублировать код, чем иметь варианты использования, вызывающие друг друга в длинной цепочке».
|
||||
5. Вытащить ввод-вывод и доступ к данным из модели в варианты использования.
|
||||
6. Дальше — агрегаты и ограниченные контексты, затем события; переход к службам — по паттерну «Душитель» (Strangler).
|
||||
|
||||
---
|
||||
|
||||
## Карта глав
|
||||
|
||||
| Гл. | Стр. | Паттерн / тема |
|
||||
|---|---|---|
|
||||
| Введение | 21 | Комок грязи, инкапсуляция и абстракции, разделение на слои, **принцип инверсии зависимостей** |
|
||||
| 1 | 32 | **Модель предметной области**: сущность, объект-значение, служба предметной области |
|
||||
| 2 | 53 | **Репозиторий**; порты и адаптеры; табл. 2.1 и график компромиссов (с. 72) |
|
||||
| 3 | 74 | Связанность и **выбор абстракций**; функциональное ядро / императивная оболочка; **подделки против имитаций** (с. 87) |
|
||||
| 4 | 90 | **Сервисный слой** и первая точка входа; структура каталогов; табл. 4.1 |
|
||||
| 5 | 109 | **TDD на повышенной и пониженной передачах**; тестовый спектр; эмпирические правила по типам тестов (с. 119) |
|
||||
| 6 | 120 | **UoW**; явная фиксация и откат по умолчанию; табл. 6.1 |
|
||||
| 7 | 136 | **Агрегат и границы согласованности**; инварианты; оптимистическая конкурентность; ограниченные контексты; табл. 7.1; итоги части I (с. 157) |
|
||||
| 8 | 162 | **События предметной области и шина сообщений**; три схемы публикации; табл. 8.1 |
|
||||
| 9 | 180 | **Всё приложение — шина сообщений**; службы становятся обработчиками; табл. 9.1 |
|
||||
| 10 | 200 | **Команды и обработчики команд**; различия в обработке ошибок; повторные попытки; табл. 10.1 и 10.2 |
|
||||
| 11 | 211 | **Внешние события, интеграция служб**; распределённый комок грязи; табл. 11.1 |
|
||||
| 12 | 226 | **CQRS**; модель чтения; четыре варианта представлений; табл. 12.1 и 12.2 |
|
||||
| 13 | 246 | **Внедрение зависимостей и сценарий начальной загрузки**; рецепт «правильного» адаптера (с. 267) |
|
||||
| Эпилог | 268 | Как внедрять в существующую систему; паттерн «Душитель»; вопросы редакторов; **«Выстрел в ногу»** (с. 287) |
|
||||
| Прил. А | 290 | **Сводная диаграмма и таблица компонентов** — лучшая одностраничная шпаргалка книги |
|
||||
| Прил. Б | 292 | Шаблонная структура проекта |
|
||||
| Прил. В | 302 | Полная замена инфраструктуры при неизменном домене |
|
||||
| Прил. Г | 308 | Репозиторий и UoW поверх «толстого» фреймворка |
|
||||
| Прил. Д | 318 | Валидация; паттерн «Обеспечение» (precondition) |
|
||||
@@ -0,0 +1,102 @@
|
||||
# lab1-event-publication Specification
|
||||
|
||||
## Purpose
|
||||
Определяет, как зоны предметной области узнают о произошедшем, не вызывая друг друга напрямую: модель регистрирует факт, шина разводит его по обработчикам. Транспорт доставки заменяем, и его отказ не влияет на обязательный путь данных.
|
||||
## Requirements
|
||||
### Requirement: Побочные эффекты выполняются через события
|
||||
|
||||
Побочная работа, не входящая в границу согласованности операции, SHALL выполняться обработчиками событий, а не внутри обработчика команды. Событие SHALL регистрироваться моделью как факт о произошедшем и SHALL публиковаться только после успешного завершения операции, породившей его.
|
||||
|
||||
#### Scenario: Успешная операция порождает событие
|
||||
|
||||
- **WHEN** сообщение успешно сохранено и клиент получил `201`
|
||||
- **THEN** зарегистрировано событие об отправке сообщения, доступное обработчикам
|
||||
|
||||
#### Scenario: Отклонённая операция событий не порождает
|
||||
|
||||
- **WHEN** отправка сообщения отклонена с `400` или `404`
|
||||
- **THEN** ни одно событие об отправке не публикуется
|
||||
|
||||
#### Scenario: Событие получают все подписчики
|
||||
|
||||
- **WHEN** на один тип события подписано несколько обработчиков
|
||||
- **THEN** событие доставляется каждому из них
|
||||
|
||||
### Requirement: Отказ обработчика события не влияет на ответ клиента
|
||||
|
||||
Исключение в обработчике события SHALL быть залогировано и SHALL NOT менять код ответа уже подтверждённой операции. Отказ одного обработчика SHALL NOT мешать остальным обработчикам того же события.
|
||||
|
||||
#### Scenario: Обработчик падает после подтверждения
|
||||
|
||||
- **WHEN** обработчик события завершается исключением после того, как клиент получил `201`
|
||||
- **THEN** ответ клиента остаётся `201`
|
||||
- **AND** факт отказа виден в логах с идентификатором запроса
|
||||
|
||||
#### Scenario: Один обработчик не блокирует остальные
|
||||
|
||||
- **WHEN** первый из двух обработчиков события завершается исключением
|
||||
- **THEN** второй обработчик всё равно вызывается
|
||||
|
||||
### Requirement: Публикация событий не удлиняет обязательный путь
|
||||
|
||||
Доставка событий обработчикам SHALL быть развязана с обработкой HTTP-запроса: публикация SHALL завершаться, не дожидаясь работы обработчиков. Очередь публикации SHALL иметь явный предел; при его достижении событие SHALL отбрасываться с записью в лог, а обязательный путь данных SHALL продолжать работать.
|
||||
|
||||
#### Scenario: Ответ не ждёт обработчиков
|
||||
|
||||
- **WHEN** обработчик события выполняется заметно дольше, чем обработка запроса
|
||||
- **THEN** клиент получает ответ, не дожидаясь завершения обработчика
|
||||
|
||||
#### Scenario: Очередь переполнена
|
||||
|
||||
- **WHEN** события публикуются быстрее, чем разбираются, и очередь достигла предела
|
||||
- **THEN** новые события отбрасываются с записью в лог
|
||||
- **AND** запись сообщений продолжает подтверждаться кодом `201`
|
||||
|
||||
### Requirement: Опубликованное событие не раскрывает содержимого сообщений
|
||||
|
||||
Полезная нагрузка события SHALL содержать только идентификаторы и метаданные. Текст сообщений, `display_name` и любые пользовательские данные SHALL NOT попадать ни в тело события, ни в журнал.
|
||||
|
||||
#### Scenario: Событие об отправке сообщения без текста
|
||||
|
||||
- **WHEN** опубликовано событие об отправке сообщения
|
||||
- **THEN** его тело содержит идентификаторы сообщения, чата и отправителя и отметку времени
|
||||
- **AND** не содержит текста сообщения
|
||||
|
||||
### Requirement: Доменные зоны связаны только событиями
|
||||
|
||||
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и импортировать её модули, кроме объявления события о регистрации. Существование участника SHALL проверяться внешним ключом схемы БД в той же транзакции, что и запись чата; SQL каждой зоны SHALL читать только таблицы своей зоны.
|
||||
|
||||
#### Scenario: Регистрация видна чатам сразу
|
||||
|
||||
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
|
||||
- **THEN** чат создаётся успешно: ответ регистрации отправлен после фиксации пользователя в БД
|
||||
|
||||
#### Scenario: Неизвестный зоне участник отклоняется
|
||||
|
||||
- **WHEN** в состав чата передан идентификатор, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, чат не создаётся
|
||||
|
||||
#### Scenario: Зона пользователей не знает о чатах
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
|
||||
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
|
||||
|
||||
#### Scenario: Обратная связь идёт только через контракт события
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
|
||||
- **THEN** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации, а SQL зоны не упоминает таблиц `users` и `sessions`
|
||||
|
||||
### Requirement: Публикация событий не требует брокера
|
||||
|
||||
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера; из сетевых сервисов обязательный API зависит только от PostgreSQL.
|
||||
|
||||
#### Scenario: События доставляются без брокера
|
||||
|
||||
- **WHEN** стенд поднят без брокера сообщений
|
||||
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
|
||||
|
||||
#### Scenario: Публикация скрыта за портом
|
||||
|
||||
- **WHEN** проверяется слой приложения
|
||||
- **THEN** он обращается к публикации только через порт и не знает её реализации
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# lab1-messenger-chats Specification
|
||||
|
||||
## Purpose
|
||||
Определяет чат как границу доступа: кто попадает в состав участников, кто видит чат в списке и что происходит с посторонним. Состав участников задаётся при создании и в обязательном API лабы 1 не меняется.
|
||||
## Requirements
|
||||
### Requirement: Создание чата
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats` от аутентифицированного пользователя с телом `{"title":..., "member_ids":[...]}` и возвращать `201` с объектом `Chat`. `title` SHALL содержать от 1 до 100 code points и не состоять только из пробельных символов. `member_ids` SHALL содержать от 1 до 100 уникальных идентификаторов существующих пользователей и SHALL включать вызывающего. Чат SHALL создаваться атомарно: при любой ошибке валидации он не создаётся вовсе.
|
||||
|
||||
#### Scenario: Чат создан
|
||||
|
||||
- **WHEN** участник отправляет `POST /api/v1/chats` с корректным `title` и списком из своего и чужого идентификаторов
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Chat`, `member_ids` совпадает с запрошенным составом
|
||||
- **AND** `id` и `created_at` назначены сервером
|
||||
|
||||
#### Scenario: Вызывающий не входит в состав
|
||||
|
||||
- **WHEN** `member_ids` не содержит идентификатора вызывающего
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит дубликаты
|
||||
|
||||
- **WHEN** `member_ids` содержит один и тот же идентификатор дважды
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит неизвестного пользователя
|
||||
|
||||
- **WHEN** `member_ids` содержит идентификатор, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** чат не создаётся
|
||||
|
||||
#### Scenario: Запрос без идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/chats` приходит без `Authorization: Bearer` или с недействительным токеном
|
||||
- **THEN** ответ `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
### Requirement: Членство как граница доступа
|
||||
|
||||
Чат SHALL быть доступен только своим участникам. Посторонний пользователь SHALL получать `404` с кодом `not_found` — тот же ответ, что и для несуществующего чата. Сервис SHALL NOT использовать `403` и SHALL NOT раскрывать факт существования чужого чата ни кодом ответа, ни текстом сообщения.
|
||||
|
||||
#### Scenario: Участник читает чат
|
||||
|
||||
- **WHEN** участник запрашивает `GET /api/v1/chats/{chat_id}` своего чата
|
||||
- **THEN** ответ `200` с объектом `Chat`
|
||||
|
||||
#### Scenario: Посторонний читает чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats/{chat_id}`
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
|
||||
#### Scenario: Запрос несуществующего чата
|
||||
|
||||
- **WHEN** запрашивается `GET /api/v1/chats/{chat_id}` с UUID, которому не соответствует ни один чат
|
||||
- **THEN** ответ `404` с кодом `not_found`, неотличимый от ответа на чужой чат
|
||||
|
||||
#### Scenario: Идентификатор чата не является UUID
|
||||
|
||||
- **WHEN** `chat_id` в пути не является UUID
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
### Requirement: Список чатов пользователя
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/chats` страницу `{"items":[...],"next_cursor":...}` с чатами, в которых состоит вызывающий, упорядоченными по `(created_at, id)` по возрастанию. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. Список SHALL NOT содержать чатов, недоступных вызывающему.
|
||||
|
||||
#### Scenario: Участник видит свой чат
|
||||
|
||||
- **WHEN** участник запрашивает `GET /api/v1/chats?limit=100`
|
||||
- **THEN** ответ `200`, и его чат присутствует в `items`
|
||||
|
||||
#### Scenario: Посторонний не видит чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats?limit=100`
|
||||
- **THEN** ответ `200`, и этого чата в `items` нет
|
||||
|
||||
#### Scenario: Limit вне допустимого диапазона
|
||||
|
||||
- **WHEN** запрос содержит `limit=0`, `limit=101` или нечисловое значение
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Обход списка курсором
|
||||
|
||||
- **WHEN** пользователь состоит в нескольких чатах и запрашивает страницы по одному элементу, передавая `next_cursor` предыдущей страницы
|
||||
- **THEN** страницы идут в порядке `(created_at, id)` по возрастанию, ни один чат не повторяется и не пропускается
|
||||
- **AND** `next_cursor` последней страницы равен `null`
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
# lab1-messenger-history Specification
|
||||
|
||||
## Purpose
|
||||
Определяет отправку сообщений и чтение истории чата: кто считается отправителем, в каком порядке лежат сообщения и какие гарантии даёт keyset-курсор при обходе истории.
|
||||
## Requirements
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":..., "attachment_ids":[...]}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL быть обязательным, содержать не более 4000 Unicode code points и SHALL NOT состоять только из пробельных символов; пустая строка допустима только при хотя бы одном вложении. `attachment_ids` SHALL быть необязательным списком из 0–10 уникальных UUID (по умолчанию `[]`); каждое вложение SHALL принадлежать этому чату и быть готовым, иначе ответ `404`. Порядок `attachment_ids` SHALL сохраняться, а одно вложение SHALL допускаться в нескольких сообщениях. Каждый `Message` в ответе SHALL содержать `attachment_ids`, у текстового — `[]`. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`.
|
||||
|
||||
#### Scenario: Сообщение отправлено
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Message`, `attachment_ids` равен `[]`
|
||||
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
|
||||
|
||||
#### Scenario: Сообщение с вложением без текста
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"","attachment_ids":[id]}`, где `id` — готовое вложение этого чата
|
||||
- **THEN** ответ `201`, `attachment_ids` равен `[id]`
|
||||
|
||||
#### Scenario: Порядок вложений сохраняется
|
||||
|
||||
- **WHEN** участник отправляет три вложения чата в порядке `[c, a, b]`
|
||||
- **THEN** ответ и история содержат `attachment_ids` в том же порядке `[c, a, b]`
|
||||
|
||||
#### Scenario: Вложение другого чата или неизвестное
|
||||
|
||||
- **WHEN** `attachment_ids` содержит вложение другого чата того же пользователя или несуществующий UUID
|
||||
- **THEN** ответ `404` с кодом `not_found`, сообщение не сохраняется
|
||||
|
||||
#### Scenario: Слишком много, повторы или не UUID
|
||||
|
||||
- **WHEN** `attachment_ids` содержит 11 элементов, повторяющийся UUID или строку не в формате UUID
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Ключ не передан
|
||||
|
||||
- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Отправитель не берётся из тела запроса
|
||||
|
||||
- **WHEN** тело запроса содержит поле `sender_id`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустой или пробельный текст
|
||||
|
||||
- **WHEN** тело содержит `{"text":""}`, `{"text":"","attachment_ids":[]}` или `{"text":" "}` с вложениями или без
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Текст длиннее предела
|
||||
|
||||
- **WHEN** `text` содержит более 4000 Unicode code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** длина считается в code points, а не в байтах UTF-8
|
||||
|
||||
#### Scenario: Посторонний пишет в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
- **AND** сообщение не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text` или с 11 вложениями
|
||||
- **THEN** ответ `404`, а не `400`
|
||||
|
||||
### Requirement: Порядок истории
|
||||
|
||||
История чата SHALL быть упорядочена по паре `(created_at, id)` по возрастанию. Время SHALL назначаться сервером в формате RFC 3339 UTC с суффиксом `Z`. Сервис SHALL гарантировать, что `created_at` внутри одного чата строго возрастает в порядке фиксации сообщений, в том числе при конкурентных вставках через разные процессы API, — иначе обход истории keyset-курсором теряет запись, зафиксированную позже с меньшей отметкой.
|
||||
|
||||
#### Scenario: Сообщения возвращаются в порядке приёма
|
||||
|
||||
- **WHEN** в чат последовательно отправлены два сообщения от разных участников
|
||||
- **THEN** `GET /api/v1/chats/{chat_id}/messages` возвращает их в порядке отправки
|
||||
|
||||
#### Scenario: Конкурентная запись не ломает порядок
|
||||
|
||||
- **WHEN** 10 клиентов параллельно отправляют по 10 сообщений в один чат
|
||||
- **THEN** история содержит ровно 100 сообщений с попарно различными `id`
|
||||
- **AND** `created_at` строго возрастает по всей истории
|
||||
|
||||
#### Scenario: Отметка не уходит назад при отставших часах процесса
|
||||
|
||||
- **WHEN** процесс API назначает сообщению отметку меньше, чем у последнего зафиксированного сообщения чата
|
||||
- **THEN** сообщение получает отметку на одну микросекунду больше последней, и порядок истории сохраняется
|
||||
|
||||
### Requirement: Чтение истории keyset-курсором
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Каждый элемент SHALL содержать `attachment_ids` в порядке отправки. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами.
|
||||
|
||||
#### Scenario: Первая страница отдаёт курсор
|
||||
|
||||
- **WHEN** в чате два сообщения и запрошено `?limit=1`
|
||||
- **THEN** ответ содержит один элемент и непустой `next_cursor`
|
||||
|
||||
#### Scenario: Последняя страница закрывает историю
|
||||
|
||||
- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1`
|
||||
- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null`
|
||||
- **AND** элемент первой страницы не повторяется
|
||||
|
||||
#### Scenario: Элементы истории несут вложения
|
||||
|
||||
- **WHEN** в чате есть текстовое сообщение и сообщение с вложением
|
||||
- **THEN** у текстового элемента `attachment_ids` равен `[]`, у второго — список его вложений, и оба элемента совпадают с ответами `201`
|
||||
|
||||
#### Scenario: Курсор не привязан к читателю
|
||||
|
||||
- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата
|
||||
- **THEN** страница отдаётся на общих основаниях
|
||||
|
||||
#### Scenario: Курсор от другого чата
|
||||
|
||||
- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Испорченный или подделанный курсор
|
||||
|
||||
- **WHEN** значение `cursor` не является ранее выданным сервером курсором
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Limit вне допустимого диапазона
|
||||
|
||||
- **WHEN** запрос содержит `limit=0` или `limit=101`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Посторонний читает чужую историю
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
|
||||
### Requirement: Подтверждённое сообщение видно следующему чтению
|
||||
|
||||
Сообщение, на которое выдан ответ `201`, SHALL быть видно любому последующему чтению истории этого чата. Кэширование допускается, но SHALL NOT возвращать историю, устаревшую относительно успешной записи.
|
||||
|
||||
#### Scenario: Запись видна сразу после подтверждения
|
||||
|
||||
- **WHEN** участник получил `201` на отправку сообщения и немедленно читает историю
|
||||
- **THEN** отправленное сообщение присутствует в ответе
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# lab1-messenger-identity Specification
|
||||
|
||||
## Purpose
|
||||
Определяет, как пользователь появляется в системе и как сервер узнаёт, от чьего имени пришёл запрос. В лабе 1 идентификация учебная и никого не аутентифицирует: любой клиент может выдать себя за другого, предъявив чужой идентификатор.
|
||||
## Requirements
|
||||
### Requirement: Регистрация пользователя
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/users` без аутентификации и возвращать `201` с объектом `User`, содержащим назначенные сервером `id` и `created_at`. Тело запроса SHALL содержать ровно поля `username`, `display_name` и `password`. `username` SHALL соответствовать `^[a-z0-9_]{3,32}$` и быть уникальным, `display_name` SHALL содержать от 1 до 100 Unicode code points и не состоять только из пробельных символов, требования к `password` задаёт `lab2-auth-sessions`. Ответ SHALL NOT содержать полей, отсутствующих в схеме `User`. Уникальность SHALL соблюдаться и при конкурентной регистрации одного `username`: успешной будет ровно одна, остальные получат `409`.
|
||||
|
||||
#### Scenario: Пользователь создан
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с телом `{"username":"alice_01","display_name":"Алиса","password":"<12+ символов>"}`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `User`, `username` и `display_name` совпадают с запросом
|
||||
- **AND** `id` — UUID, назначенный сервером, `created_at` — RFC 3339 UTC с суффиксом `Z`
|
||||
|
||||
#### Scenario: Username занят
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с `username`, уже принадлежащим другому пользователю
|
||||
- **THEN** ответ `409` с телом ошибки и кодом `conflict`
|
||||
|
||||
#### Scenario: Username нарушает формат
|
||||
|
||||
- **WHEN** `username` содержит заглавные буквы, дефис, пробел, перевод строки или имеет длину вне 3–32 символов
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Display_name пуст или состоит из пробелов
|
||||
|
||||
- **WHEN** `display_name` равен `""`, `" "` или длиннее 100 code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Тело запроса нарушает схему
|
||||
|
||||
- **WHEN** тело содержит лишнее поле, неверный тип поля, не содержит обязательного поля (в том числе `password`) или не является корректным JSON
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** сообщение ошибки не содержит stack trace и внутренних деталей реализации
|
||||
|
||||
#### Scenario: Регистрация не требует идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/users` приходит без заголовка `Authorization`
|
||||
- **THEN** запрос обрабатывается на общих основаниях, ответ не равен `401`
|
||||
|
||||
### Requirement: Чтение текущего пользователя
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/users/me` объект `User` владельца предъявленной `Bearer`-сессии в том же виде, в каком он был возвращён при регистрации.
|
||||
|
||||
#### Scenario: Текущий пользователь возвращён
|
||||
|
||||
- **WHEN** приходит `GET /api/v1/users/me` с действительным `Bearer`-токеном пользователя
|
||||
- **THEN** ответ `200`, тело соответствует схеме `User` и совпадает с телом ответа его регистрации
|
||||
|
||||
@@ -0,0 +1,175 @@
|
||||
# lab1-service-operability Specification
|
||||
|
||||
## Purpose
|
||||
Определяет наблюдаемое поведение сервиса как эксплуатируемого процесса: пробы жизни и готовности, сквозной идентификатор запроса, единый формат ошибок, реакция на сигнал остановки и требования к контейнерной поставке.
|
||||
## Requirements
|
||||
### Requirement: Пробы жизни и готовности
|
||||
|
||||
Сервис SHALL отвечать на `GET /health/live` кодом `200` с телом `{"status":"ok"}`, проверяя только жизнь процесса. Сервис SHALL отвечать на `GET /health/ready` кодом `200` с тем же телом, только если в момент запроса выполнен запрос к PostgreSQL за ограниченное время, и кодом `503` с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать аутентификации. Недоступность необязательных зависимостей SHALL NOT переводить готовность в `503`.
|
||||
|
||||
#### Scenario: Проба жизни отвечает без идентификации
|
||||
|
||||
- **WHEN** приходит `GET /health/live` без заголовка `Authorization`
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность подтверждена
|
||||
|
||||
- **WHEN** приходит `GET /health/ready`, а PostgreSQL доступен
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность не зависит от внешних сервисов
|
||||
|
||||
- **WHEN** проверяется готовность, а недоступна только необязательная зависимость
|
||||
- **THEN** ответ `200`: из внешних сервисов готовность зависит лишь от PostgreSQL
|
||||
|
||||
#### Scenario: Готовность отражает PostgreSQL
|
||||
|
||||
- **WHEN** PostgreSQL остановлен
|
||||
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable`, а `GET /health/live` — `200`
|
||||
|
||||
#### Scenario: Сервис остановлен
|
||||
|
||||
- **WHEN** процесс получил сигнал остановки и перестал принимать новую работу
|
||||
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable` либо соединение не устанавливается
|
||||
|
||||
### Requirement: Сквозной идентификатор запроса
|
||||
|
||||
Каждый ответ сервиса, включая ответы проб, `204` выхода и ответы об ошибках (`404`/`405` неизвестного маршрута, `413`, `500` необработанного исключения), SHALL содержать непустые заголовки `X-Request-Id` и `X-Instance-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое. `X-Instance-Id` SHALL идентифицировать реплику (контейнер), а не отдельный процесс-воркер: значение SHALL быть одинаковым у всех процессов реплики, стабильным на всё время её жизни и SHALL совпадать с hostname контейнера, чтобы оператор мог сопоставить ответ с `docker ps`.
|
||||
|
||||
#### Scenario: Идентификатор присутствует в любом ответе
|
||||
|
||||
- **WHEN** выполняется любой запрос к сервису, успешный или ошибочный
|
||||
- **THEN** ответ содержит непустые `X-Request-Id` и `X-Instance-Id`
|
||||
|
||||
#### Scenario: Клиентский идентификатор сохраняется
|
||||
|
||||
- **WHEN** запрос содержит `X-Request-Id` с непустым значением
|
||||
- **THEN** ответ содержит то же значение
|
||||
|
||||
#### Scenario: Один идентификатор на реплику
|
||||
|
||||
- **WHEN** реплика с несколькими процессами-воркерами обслуживает серию запросов
|
||||
- **THEN** все её ответы несут одно и то же значение `X-Instance-Id`, равное hostname контейнера
|
||||
|
||||
#### Scenario: Необработанное исключение несёт идентификаторы
|
||||
|
||||
- **WHEN** обработка запроса завершается непредвиденным исключением
|
||||
- **THEN** ответ `500` содержит `X-Request-Id` и `X-Instance-Id`
|
||||
|
||||
### Requirement: Единый формат ошибки
|
||||
|
||||
Ответ с кодом `4xx` или `5xx` SHALL иметь `Content-Type: application/json` и тело `{"error":{"code":...,"message":...,"request_id":...}}` без каких-либо дополнительных полей. `code` SHALL принимать значение из перечисления контракта, `request_id` SHALL совпадать со значением заголовка `X-Request-Id`. `message` SHALL быть непустым и SHALL NOT содержать stack trace, SQL, учётных данных, внутренних путей и сведений о существовании чужих объектов.
|
||||
|
||||
#### Scenario: Тело ошибки соответствует схеме
|
||||
|
||||
- **WHEN** запрос завершается ошибкой любого класса
|
||||
- **THEN** тело ответа соответствует схеме `Error` контракта
|
||||
- **AND** `request_id` в теле совпадает с заголовком `X-Request-Id`
|
||||
|
||||
#### Scenario: Необработанное исключение
|
||||
|
||||
- **WHEN** обработка запроса завершается непредвиденным исключением
|
||||
- **THEN** ответ `500` с кодом `internal_error` и телом в общем формате
|
||||
- **AND** тело не раскрывает внутренних деталей
|
||||
|
||||
#### Scenario: Неподдерживаемый метод или несуществующий путь
|
||||
|
||||
- **WHEN** запрашивается несуществующий путь или неподдерживаемый метод существующего пути
|
||||
- **THEN** ответ имеет тело в общем формате ошибки с непустым `X-Request-Id`
|
||||
|
||||
### Requirement: Корректное завершение по сигналу
|
||||
|
||||
По получении `SIGTERM` сервис SHALL сначала выйти из ротации: на время окна `DRAIN_SECONDS` (по умолчанию 2 с, больше максимального времени обнаружения балансировщиком) `/health/ready` SHALL отвечать `503 unavailable`, а принятые и новые запросы SHALL обслуживаться как обычно. После окна сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс; весь срок, включая окно, SHALL укладываться в `SHUTDOWN_TIMEOUT_SECONDS` (по умолчанию 5 с), который меньше таймаута хука остановки, `stop_grace_period` контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
|
||||
|
||||
#### Scenario: Остановка укладывается в срок
|
||||
|
||||
- **WHEN** запущенному контейнеру послан `SIGTERM`
|
||||
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
|
||||
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
|
||||
|
||||
#### Scenario: Сначала вывод из ротации
|
||||
|
||||
- **WHEN** процессу сервера послан `SIGTERM`
|
||||
- **THEN** в течение окна `DRAIN_SECONDS` `/health/ready` отвечает `503` в общем формате ошибки, `/health/live` — `200`, соединения ещё принимаются, а после окна порт закрыт и процесс завершается с кодом 0 не позднее `SHUTDOWN_TIMEOUT_SECONDS`
|
||||
|
||||
#### Scenario: Принятый запрос дорабатывается
|
||||
|
||||
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
|
||||
- **THEN** этот запрос получает ответ до завершения процесса
|
||||
|
||||
### Requirement: Логи без содержимого сообщений
|
||||
|
||||
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и `X-Request-Id`. Логи SHALL NOT содержать текста сообщений, `display_name`, паролей, токенов сессий, значений заголовка `Authorization`, строк подключения к хранилищам и тел запросов.
|
||||
|
||||
#### Scenario: Запись о запросе присутствует
|
||||
|
||||
- **WHEN** обработан любой запрос к API
|
||||
- **THEN** в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
|
||||
|
||||
#### Scenario: Текст сообщения не попадает в логи
|
||||
|
||||
- **WHEN** отправлено сообщение с известным текстом-маркером
|
||||
- **THEN** этот текст отсутствует в stdout и stderr процесса
|
||||
|
||||
#### Scenario: Учётные данные не попадают в логи
|
||||
|
||||
- **WHEN** пользователь зарегистрировался, вошёл и выполнил запрос с токеном
|
||||
- **THEN** ни пароль, ни токен, ни значение `Authorization` не встречаются в stdout и stderr процесса
|
||||
|
||||
### Requirement: Контейнерная поставка
|
||||
|
||||
Сервис SHALL собираться из исходников в образ, слушать `0.0.0.0:8080` и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
|
||||
|
||||
#### Scenario: Образ собирается из чистого clone
|
||||
|
||||
- **WHEN** выполняется сборка образа в свежей копии репозитория
|
||||
- **THEN** сборка завершается успешно без обращения к артефактам вне репозитория
|
||||
|
||||
#### Scenario: API доступен на опубликованном порту
|
||||
|
||||
- **WHEN** стенд поднят командой `make up`
|
||||
- **THEN** `GET /health/ready` с хоста через опубликованный порт балансировщика отвечает `200`
|
||||
|
||||
#### Scenario: Процесс работает не от root
|
||||
|
||||
- **WHEN** в работающем контейнере проверяется эффективный пользователь процесса сервера
|
||||
- **THEN** это не `root`, и идентификатор пользователя не равен 0
|
||||
|
||||
#### Scenario: Healthcheck отражает состояние сервиса
|
||||
|
||||
- **WHEN** контейнер запущен и сервис готов
|
||||
- **THEN** статус healthcheck контейнера становится `healthy`
|
||||
|
||||
### Requirement: Предел времени обработки запроса
|
||||
|
||||
Обработка запроса SHALL ограничиваться настраиваемым пределом времени. При его превышении сервис SHALL отвечать `503` с кодом `unavailable`, если ответ ещё не начал отправляться, и SHALL записывать факт превышения в журнал. Превышение предела одним запросом SHALL NOT влиять на последующие запросы и на готовность сервиса.
|
||||
|
||||
#### Scenario: Запрос превысил предел
|
||||
|
||||
- **WHEN** обработка запроса длится дольше установленного предела
|
||||
- **THEN** ответ `503` с кодом `unavailable` и телом в общем формате ошибки
|
||||
|
||||
#### Scenario: Сервис продолжает работать после превышения
|
||||
|
||||
- **WHEN** после превышения предела приходит обычный запрос
|
||||
- **THEN** он обрабатывается штатно, а `GET /health/ready` отвечает `200`
|
||||
|
||||
#### Scenario: Запись о превышении не раскрывает содержимого
|
||||
|
||||
- **WHEN** запрос с известным текстом-маркером превысил предел
|
||||
- **THEN** в журнале появляется запись о превышении, и этот текст в ней отсутствует
|
||||
|
||||
### Requirement: Единый журнал всех сообщений процесса
|
||||
|
||||
Сервис SHALL выводить в stdout единый поток структурированных записей. Сообщения сервера приложений и используемых библиотек SHALL проходить через тот же журнал и иметь тот же формат, что и сообщения приложения. Записи SHALL содержать только поля из объявленного перечня; поля вне перечня SHALL отбрасываться.
|
||||
|
||||
#### Scenario: Сообщения сервера приложений в общем формате
|
||||
|
||||
- **WHEN** процесс запускается и печатает сообщения о старте сервера
|
||||
- **THEN** каждая строка stdout разбирается как структурированная запись того же формата, что и записи приложения
|
||||
|
||||
#### Scenario: Незаявленное поле не попадает в журнал
|
||||
|
||||
- **WHEN** запись журнала формируется с полем, отсутствующим в перечне разрешённых
|
||||
- **THEN** это поле в выводе отсутствует
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
# lab2-auth-sessions Specification
|
||||
|
||||
## Purpose
|
||||
Определяет, как пользователь доказывает знание пароля, получает непрозрачную сессию с абсолютным сроком жизни, предъявляет её на защищённых endpoint и отзывает её. Заменяет учебную идентификацию `X-User-Id` лабы 1.
|
||||
## Requirements
|
||||
### Requirement: Пароль хранится только как password KDF
|
||||
|
||||
Сервис SHALL хранить пароль пользователя только в виде хеша библиотечного password KDF Argon2id с солью. Пароль, его хеш и сессионные данные SHALL NOT входить в объект `User` и SHALL NOT попадать в журнал. Пароль SHALL содержать от 12 до 128 Unicode code points и SHALL NOT состоять только из пробельных символов.
|
||||
|
||||
#### Scenario: В хранилище нет открытого пароля
|
||||
|
||||
- **WHEN** пользователь зарегистрирован с паролем
|
||||
- **THEN** запись пользователя в БД содержит строку, начинающуюся с `$argon2id$`, и не содержит пароля
|
||||
|
||||
#### Scenario: Пароль вне допустимой длины
|
||||
|
||||
- **WHEN** `POST /api/v1/users` содержит `password` короче 12 или длиннее 128 code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, пользователь не создаётся
|
||||
|
||||
#### Scenario: Пароль из одних пробелов
|
||||
|
||||
- **WHEN** `password` состоит только из пробельных символов
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Ответ регистрации без пароля
|
||||
|
||||
- **WHEN** пользователь успешно зарегистрирован
|
||||
- **THEN** тело `201` содержит ровно `id`, `username`, `display_name`, `created_at`
|
||||
|
||||
### Requirement: Вход по Basic выдаёт сессию
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/auth/sessions` только с заголовком `Authorization: Basic <base64(username:password)>` и без тела. Декодирование base64 SHALL быть строгим, разделителем SHALL служить первое двоеточие, пароль SHALL декодироваться как UTF-8. При верных учётных данных ответ SHALL быть `201` с телом `{"token","token_type":"Bearer","expires_at","user"}`, где `token` — непрозрачная случайная строка не короче 32 символов с энтропией не менее 256 бит, `expires_at` — RFC 3339 UTC с `Z`, а `user` совпадает с ответом регистрации. Неверный пароль, неизвестный `username`, отсутствующий и испорченный заголовок SHALL давать одинаковый `401` с кодом `unauthorized` и заголовком `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
|
||||
|
||||
#### Scenario: Успешный вход
|
||||
|
||||
- **WHEN** зарегистрированный пользователь отправляет верные `username:password` в `Basic`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Session`, `token_type` равен `Bearer`
|
||||
- **AND** `user` побайтно равен телу ответа его регистрации, `expires_at` в будущем
|
||||
|
||||
#### Scenario: Неверный пароль и неизвестный пользователь неразличимы
|
||||
|
||||
- **WHEN** приходит `Basic` с неверным паролем существующего пользователя или с несуществующим `username`
|
||||
- **THEN** оба ответа — `401` с кодом `unauthorized` и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`
|
||||
- **AND** тела ответов различаются только `request_id`
|
||||
|
||||
#### Scenario: Испорченный заголовок Basic
|
||||
|
||||
- **WHEN** заголовок отсутствует, содержит другую схему, невалидный base64 или строку без двоеточия
|
||||
- **THEN** ответ `401` с тем же заголовком `WWW-Authenticate: Basic ...`
|
||||
|
||||
#### Scenario: Двоеточие в пароле
|
||||
|
||||
- **WHEN** пароль пользователя содержит двоеточие и он входит по `Basic`
|
||||
- **THEN** ответ `201`: разделителем служит первое двоеточие
|
||||
|
||||
#### Scenario: Тело запроса при входе
|
||||
|
||||
- **WHEN** запрос с верным `Basic` содержит тело
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, сессия не создаётся
|
||||
|
||||
### Requirement: Защищённые endpoint принимают только Bearer
|
||||
|
||||
Все `/api/v1/*`, кроме `POST /api/v1/users` и `POST /api/v1/auth/sessions`, SHALL требовать `Authorization: Bearer <token>`; схема сравнивается без учёта регистра. Отсутствующий, неизвестный, истёкший и отозванный токен, а также `Basic` на этих endpoint SHALL давать `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`. Заголовок `X-User-Id` SHALL игнорироваться: он не даёт доступа и не меняет владельца сессии. Аутентификация SHALL выполняться раньше проверки доступа к ресурсу и раньше валидации пути, параметров и тела.
|
||||
|
||||
#### Scenario: Только X-User-Id
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с `X-User-Id` существующего пользователя и без `Authorization`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: X-User-Id не подменяет владельца
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с `Bearer` пользователя alice и `X-User-Id` пользователя eve
|
||||
- **THEN** ответ `200` с пользователем alice
|
||||
|
||||
#### Scenario: Basic на бизнес-endpoint
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с верным `Basic`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: Неизвестный токен
|
||||
|
||||
- **WHEN** запрос несёт `Bearer` со случайной строкой
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
#### Scenario: Аутентификация раньше валидации
|
||||
|
||||
- **WHEN** `POST /api/v1/chats/not-a-uuid/messages` приходит без `Authorization` и с испорченным JSON
|
||||
- **THEN** ответ `401`, а не `400`
|
||||
|
||||
### Requirement: Абсолютный срок жизни сессии
|
||||
|
||||
Срок жизни сессии SHALL задаваться `SESSION_TTL_SECONDS` (по умолчанию 3600) от момента входа и SHALL NOT продлеваться ни использованием, ни рестартом сервиса. После `expires_at` токен SHALL давать `401`.
|
||||
|
||||
#### Scenario: Срок назначен при входе
|
||||
|
||||
- **WHEN** пользователь вошёл
|
||||
- **THEN** `expires_at` равен моменту входа плюс `SESSION_TTL_SECONDS` секунд
|
||||
|
||||
#### Scenario: Истёкший токен
|
||||
|
||||
- **WHEN** сервис запущен с `SESSION_TTL_SECONDS=2` и токен предъявлен через 3 секунды после входа
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
### Requirement: Отзыв текущей сессии
|
||||
|
||||
`DELETE /api/v1/auth/sessions/current` SHALL отзывать предъявленный токен и отвечать `204` без тела. После отзыва этот токен SHALL давать `401`, в том числе на повторный `DELETE`. Остальные сессии того же пользователя SHALL оставаться действительными.
|
||||
|
||||
#### Scenario: Выход
|
||||
|
||||
- **WHEN** пользователь отправляет `DELETE /api/v1/auth/sessions/current` со своим токеном
|
||||
- **THEN** ответ `204` с пустым телом и непустым `X-Request-Id`
|
||||
- **AND** следующий `GET /api/v1/users/me` с этим токеном получает `401`
|
||||
|
||||
#### Scenario: Повторный выход
|
||||
|
||||
- **WHEN** `DELETE /api/v1/auth/sessions/current` повторяется с уже отозванным токеном
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: Другая сессия не затронута
|
||||
|
||||
- **WHEN** пользователь вошёл дважды и отозвал первую сессию
|
||||
- **THEN** второй токен продолжает получать `200`
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# lab2-dependency-failures Specification
|
||||
|
||||
## Purpose
|
||||
Определяет поведение API при отказе PostgreSQL и при исчерпании пула соединений: ограниченная по времени ошибка `503` вместо зависания, `500` или анонимного доступа, и восстановление без рестарта процесса.
|
||||
## Requirements
|
||||
### Requirement: Отказ PostgreSQL даёт ограниченную ошибку
|
||||
|
||||
При недоступном PostgreSQL защищённые endpoint и `/health/ready` каждой реплики SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` реплики SHALL отвечать `200`. Балансировщик SHALL исключить все реплики из ротации не позднее чем через 1,5 с после отказа и SHALL сам отвечать на любой запрос `503` в общем формате ошибки с `request_id`, равным `X-Request-Id`; после возвращения PostgreSQL реплики SHALL вернуться в ротацию без перезапуска.
|
||||
|
||||
#### Scenario: PostgreSQL остановлен
|
||||
|
||||
- **WHEN** сервис `postgres` остановлен
|
||||
- **THEN** `GET /health/ready` и `GET /api/v1/users/me` через LB отвечают `503 unavailable` быстрее 2 с, `GET /health/live` внутри реплики — `200`, ни один ответ не `500`
|
||||
|
||||
#### Scenario: Неизвестный токен при остановленной БД
|
||||
|
||||
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
|
||||
- **THEN** ответ `503`, а не `200`
|
||||
|
||||
#### Scenario: Балансировщик исключает все реплики
|
||||
|
||||
- **WHEN** PostgreSQL остановлен дольше времени обнаружения
|
||||
- **THEN** статистика LB показывает 0 готовых реплик, а запрос через LB, включая `GET /health/live`, получает `503 {"error":{"code":"unavailable",...}}` без `X-Instance-Id`
|
||||
- **AND** после запуска PostgreSQL все реплики снова готовы в LB без перезапуска своих процессов
|
||||
|
||||
### Requirement: Восстановление без рестарта API
|
||||
|
||||
После возвращения PostgreSQL API SHALL восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула.
|
||||
|
||||
#### Scenario: PostgreSQL снова запущен
|
||||
|
||||
- **WHEN** сервис `postgres` запущен после остановки
|
||||
- **THEN** в течение 30 с `/health/ready` отвечает `200`, а прежний токен читает свои данные
|
||||
|
||||
### Requirement: Ограниченный пул соединений
|
||||
|
||||
Каждый процесс API SHALL держать не больше заданного числа соединений с PostgreSQL. Запрос, не получивший соединение за заданное время, SHALL получать `503` и SHALL NOT ждать бесконечно. Все SQL-запросы SHALL быть параметризованными.
|
||||
|
||||
#### Scenario: Пул исчерпан
|
||||
|
||||
- **WHEN** все соединения пула заняты и приходит запрос, требующий БД
|
||||
- **THEN** ответ `503 unavailable` за время ожидания соединения
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# lab2-history-index Specification
|
||||
|
||||
## Purpose
|
||||
Определяет, чем обоснован индекс истории сообщений: планом запроса страницы на наборе не меньше 10 000 сообщений и отсутствием полного прохода по истории на каждой странице.
|
||||
## Requirements
|
||||
### Requirement: Индекс истории обоснован планом
|
||||
|
||||
Чтение страницы истории SHALL обслуживаться индексом по `(chat_id, created_at, id)` так, что число прочитанных строк и буферов пропорционально `limit`, а не размеру истории чата. Обоснование SHALL быть получено `EXPLAIN (ANALYZE, BUFFERS)` на чате не меньше чем из 10 000 сообщений для первой и для глубокой страницы и сохранено в доказательствах.
|
||||
|
||||
#### Scenario: Первая страница
|
||||
|
||||
- **WHEN** выполняется запрос первой страницы истории с `limit=50` на чате из ≥10 000 сообщений
|
||||
- **THEN** план — `Index Scan` по индексу истории без узла `Sort`, прочитана 51 строка
|
||||
|
||||
#### Scenario: Глубокая страница keyset-курсором
|
||||
|
||||
- **WHEN** выполняется запрос страницы после курсора, указывающего на 10 000-е сообщение
|
||||
- **THEN** план — `Index Scan` с условием по `(created_at, id)`, прочитана 51 строка, без прохода по предыдущим 10 000
|
||||
|
||||
#### Scenario: Сравнение с OFFSET
|
||||
|
||||
- **WHEN** та же глубокая страница запрашивается через `OFFSET 10000`
|
||||
- **THEN** план читает и отбрасывает ≥10 000 строк, что фиксируется рядом с keyset-планом как обоснование выбора курсора
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
# lab2-persistent-storage Specification
|
||||
|
||||
## Purpose
|
||||
Определяет постоянное хранение лабы 2: схему PostgreSQL с ограничениями, версионируемые миграции, атомарность составных операций, сохранность данных и сессий при рестарте и воспроизводимый стенд из репозитория без секретов в Git.
|
||||
## Requirements
|
||||
### Requirement: Схема с ограничениями целостности
|
||||
|
||||
PostgreSQL SHALL хранить пользователей, сессии, чаты, участников и сообщения в отдельных таблицах с первичными ключами. Уникальность `username` SHALL обеспечиваться ограничением БД. Участник чата SHALL ссылаться на существующего пользователя и существующий чат, сообщение SHALL ссылаться на участника своего чата, сессия — на пользователя. Схема SHALL дублировать правила контракта проверками `CHECK` (формат `username`, длины строк).
|
||||
|
||||
#### Scenario: Ограничения видны в схеме
|
||||
|
||||
- **WHEN** оператор выполняет `\d+` по таблицам `users`, `chat_members`, `messages`
|
||||
- **THEN** видны `PRIMARY KEY`, `UNIQUE (username)` и внешние ключи `chat_members → users, chats`, `messages → chat_members`
|
||||
|
||||
#### Scenario: Сообщение от постороннего не записывается даже в обход API
|
||||
|
||||
- **WHEN** в `messages` вставляется строка, отправитель которой не состоит в чате
|
||||
- **THEN** вставка отклоняется нарушением внешнего ключа
|
||||
|
||||
### Requirement: Версионируемые миграции
|
||||
|
||||
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одним одноразовым процессом до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё.
|
||||
|
||||
#### Scenario: Миграции с пустого volume
|
||||
|
||||
- **WHEN** стенд поднимается на пустом volume PostgreSQL
|
||||
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартуют реплики API
|
||||
|
||||
#### Scenario: Повторный запуск
|
||||
|
||||
- **WHEN** процесс миграций запускается повторно на той же БД
|
||||
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
|
||||
|
||||
#### Scenario: Изменённая миграция
|
||||
|
||||
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
|
||||
- **THEN** процесс завершается ненулевым кодом и схему не трогает
|
||||
|
||||
#### Scenario: Реплики не мигрируют схему
|
||||
|
||||
- **WHEN** стартует или перезапускается реплика API
|
||||
- **THEN** она не применяет миграции; журнал версий меняет только процесс `migrate`
|
||||
|
||||
### Requirement: Атомарное создание чата
|
||||
|
||||
Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся.
|
||||
|
||||
#### Scenario: Неизвестный участник откатывает чат
|
||||
|
||||
- **WHEN** `POST /api/v1/chats` содержит в `member_ids` UUID несуществующего пользователя
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** в БД нет ни чата с этим `title`, ни его участников
|
||||
|
||||
### Requirement: Данные и сессии переживают рестарт
|
||||
|
||||
Пользователи, чаты, участники, сообщения со ссылками на вложения, ключи идемпотентности, метаданные вложений, их байты в bucket и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ, включая S3, с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, подтверждённое сообщение SHALL читаться побайтно тем же, а загруженное вложение SHALL отдавать те же метаданные и те же байты.
|
||||
|
||||
#### Scenario: Полный рестарт стенда
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`, в том числе после однократного чтения метаданных и байтов вложения
|
||||
|
||||
#### Scenario: Логаут после рестарта
|
||||
|
||||
- **WHEN** после рестарта пользователь отзывает прежний токен
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
### Requirement: Воспроизводимый стенд из репозитория
|
||||
|
||||
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников, bucket и доступ к нему создаёт одноразовый bootstrap. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey, S3 и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны (root-ключи S3 — только S3-сервисам), и SHALL NOT появляться в Git, образе и журнале.
|
||||
|
||||
#### Scenario: Подъём из чистого clone
|
||||
|
||||
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
|
||||
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0 (`migrate`, `s3-init`), а `GET /health/ready` через балансировщик отвечает `200`
|
||||
|
||||
#### Scenario: Опубликован только балансировщик
|
||||
|
||||
- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'`
|
||||
- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1`
|
||||
|
||||
#### Scenario: Секреты и volumes вне Git
|
||||
|
||||
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url secrets/s3_root_password .env`
|
||||
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# lab2-session-cache Specification
|
||||
|
||||
## Purpose
|
||||
Определяет роль Valkey в лабе 2: read-through кэш сессий поверх PostgreSQL — что в нём лежит, сколько живёт, как инвалидируется при выходе и что происходит при его недоступности, очистке и рестарте.
|
||||
## Requirements
|
||||
### Requirement: Кэш сессий поверх источника истины
|
||||
|
||||
Проверка `Bearer`-токена SHALL сначала обращаться к кэшу Valkey по ключу от SHA-256 токена и только при промахе — к PostgreSQL, после чего заполнять кэш. PostgreSQL SHALL оставаться единственным источником истины: в кэш SHALL NOT попадать ничего, чего нет в БД, а запись кэша SHALL NOT жить дольше `expires_at` сессии. Токен в открытом виде SHALL NOT храниться в кэше.
|
||||
|
||||
#### Scenario: Повторная проверка обслуживается кэшем
|
||||
|
||||
- **WHEN** пользователь дважды подряд выполняет `GET /api/v1/users/me` с одним токеном
|
||||
- **THEN** второй запрос находит сессию в Valkey: счётчик попаданий `keyspace_hits` растёт, в кэше есть ключ `session:<sha256>`
|
||||
|
||||
#### Scenario: Срок записи кэша не превышает срок сессии
|
||||
|
||||
- **WHEN** сессия закэширована
|
||||
- **THEN** абсолютный срок жизни ключа (`PEXPIRETIME`) не позже `expires_at` сессии
|
||||
|
||||
### Requirement: Выход инвалидирует кэш
|
||||
|
||||
Отзыв сессии SHALL записывать в кэш отметку отзыва на оставшийся срок сессии до удаления строки в БД, а заполнение кэша после промаха SHALL выполняться только при отсутствии ключа. Отозванный токен SHALL получать `401` и при гонке «чтение заполнило кэш после выхода». Если отметку отзыва записать нельзя, выход SHALL отвечать `503` и SHALL NOT удалять сессию.
|
||||
|
||||
#### Scenario: Отозванный токен не оживает из кэша
|
||||
|
||||
- **WHEN** токен закэширован, после чего пользователь выполняет `DELETE /api/v1/auth/sessions/current`
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
#### Scenario: Выход при недоступном кэше
|
||||
|
||||
- **WHEN** Valkey остановлен и пользователь выполняет `DELETE /api/v1/auth/sessions/current`
|
||||
- **THEN** ответ `503` с кодом `unavailable`, а после запуска Valkey повторный выход отвечает `204`
|
||||
|
||||
### Requirement: Недоступный кэш обходится, но не открывает доступ
|
||||
|
||||
При ошибке или таймауте Valkey проверка сессии SHALL выполняться по PostgreSQL за ограниченное время, а повторные попытки обращения к кэшу SHALL приостанавливаться на короткий интервал. Недействительный токен SHALL получать `401`; запрос SHALL NOT приниматься как анонимный. Недоступность Valkey SHALL NOT переводить `/health/ready` в `503`.
|
||||
|
||||
#### Scenario: Valkey остановлен
|
||||
|
||||
- **WHEN** сервис `valkey` остановлен
|
||||
- **THEN** `GET /api/v1/users/me` с действительным токеном отвечает `200` быстрее 1 с, с неизвестным токеном — `401`, `/health/ready` — `200`, вход по `Basic` — `201`
|
||||
|
||||
### Requirement: Очистка и рестарт кэша безопасны
|
||||
|
||||
Потеря содержимого Valkey (`FLUSHALL`, рестарт без данных) SHALL NOT терять сессии и SHALL NOT оживлять отозванные. Valkey SHALL хранить данные с AOF на именованном volume, чтобы рестарт сохранял тёплый кэш и отметки отзыва.
|
||||
|
||||
#### Scenario: FLUSHALL
|
||||
|
||||
- **WHEN** в Valkey выполнен `FLUSHALL`
|
||||
- **THEN** действующий токен получает `200`, отозванный — `401`
|
||||
|
||||
#### Scenario: Рестарт Valkey
|
||||
|
||||
- **WHEN** сервис `valkey` перезапущен
|
||||
- **THEN** ключи сессий на месте, действующий токен получает `200`, отозванный — `401`
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# lab3-failover-operations Specification
|
||||
|
||||
## Purpose
|
||||
Определяет эксплуатационные гарантии реплицированного стенда: за какое время балансировщик исключает отказавшую реплику, как переживается поочерёдный отказ и плановая замена реплик под нагрузкой, как проверяется общая идемпотентность параллельными запросами и как ограничены ресурсы, порты, секреты и хранилища.
|
||||
## Requirements
|
||||
### Requirement: Согласованные проверки, таймауты и остановка
|
||||
|
||||
Балансировщик SHALL проверять каждую реплику `GET /health/ready` с периодом 1 с, после первого провала — каждые 0,5 с, исключать её после 2 провалов подряд и возвращать после 2 успехов. Реплика, которая появилась или вернулась через DNS (запуск, `restore.sh`, новая реплика rolling update), SHALL получать запросы только после 2 успешных проверок, а не сразу после появления адреса. Максимальное время обнаружения SHALL составлять 1,5 с для реплики, которая отвечает `503` или отказывает в соединении, и 3,5 с для зависшей реплики (с таймаутом проверки 1 с). Readiness реплики SHALL отвечать быстрее таймаута проверки. Цепочка таймаутов SHALL убывать от внешнего звена к внутреннему: ожидание ответа балансировщиком > таймаут запроса в приложении > таймаут оператора и ожидания соединения с БД. Срок остановки реплики SHALL укладываться в таймаут хука остановки, а тот — в `stop_grace_period` и в 10 с.
|
||||
|
||||
#### Scenario: Конфигурация согласована
|
||||
|
||||
- **WHEN** выполняется `make student-test`
|
||||
- **THEN** тест цепочки таймаутов по `compose.yaml`, `infra/haproxy/haproxy.cfg` и `scripts/stop-one.sh` проходит: окно вывода из ротации больше максимума обнаружения, срок остановки меньше таймаута хука, таймаут хука меньше `stop_grace_period` и 10 с, `timeout server` балансировщика больше `REQUEST_TIMEOUT_SECONDS`, а тот больше суммы таймаутов БД
|
||||
|
||||
#### Scenario: Обнаружение измерено по каждому виду отказа
|
||||
|
||||
- **WHEN** выполняется `make detection`
|
||||
- **THEN** для `SIGTERM` через `scripts/stop-one.sh`, `docker kill`, `docker pause` и остановки PostgreSQL в `evidence/detection/*.json` записаны время обнаружения, заявленный максимум и время возврата в ротацию, и каждое время обнаружения не больше заявленного максимума
|
||||
|
||||
#### Scenario: Остановка по сигналу не теряет запросы
|
||||
|
||||
- **WHEN** реплике посылается `SIGTERM` через `scripts/stop-one.sh`
|
||||
- **THEN** балансировщик исключает её раньше, чем хук завершился, а реплика закрывает приём соединений только после этого
|
||||
|
||||
#### Scenario: Возврат реплики без преждевременного трафика
|
||||
|
||||
- **WHEN** остановленная реплика запускается снова под нагрузкой
|
||||
- **THEN** балансировщик не направляет на неё запросы, пока она не прошла 2 проверки готовности: счётчики повторов и перенаправлений LB (`wretr`, `wredis`) за прогон равны 0
|
||||
|
||||
#### Scenario: Зависшая реплика
|
||||
|
||||
- **WHEN** процесс реплики приостановлен (`docker pause`) и не отвечает на проверки
|
||||
- **THEN** балансировщик исключает её не позднее чем через 3,5 с, а после `docker unpause` возвращает в ротацию
|
||||
|
||||
### Requirement: Поочерёдный отказ под нагрузкой
|
||||
|
||||
Оператор SHALL одной командой останавливать каждую реплику по очереди под открытой нагрузкой (постоянная интенсивность запросов, 80 % отправок сообщений и 20 % чтений истории) и возвращать её до остановки следующей. Для каждой реплики SHALL фиксироваться интенсивность и доля ошибок нагрузки, задержки p50/p95/p99, время обнаружения, время возврата в ротацию, ошибки и время восстановления записи зонда, повторяющего неудачную запись с тем же ключом, и счётчики повторов и перенаправлений балансировщика.
|
||||
|
||||
#### Scenario: Каждая реплика по очереди
|
||||
|
||||
- **WHEN** выполняется `make failover-each`
|
||||
- **THEN** `evidence/failover-each/summary.json` содержит запись на каждую реплику; в каждой хук завершился кодом 0, доля ошибок нагрузки не больше 1 %, запись восстановилась не позже 10 с, пока реплика была исключена, её `X-Instance-Id` не встречался, а после возврата она снова обслуживает запросы
|
||||
|
||||
### Requirement: Общая идемпотентность под параллельными запросами
|
||||
|
||||
Параллельные `POST /api/v1/chats/{chat_id}/messages` с одним `Idempotency-Key` и одним телом, распределённые балансировщиком по разным репликам, SHALL создавать ровно одно сообщение и SHALL получать одинаковые ответы `201`; тот же ключ с другим телом SHALL получать `409`.
|
||||
|
||||
#### Scenario: Серия гонок через LB
|
||||
|
||||
- **WHEN** выполняется `make lb-check` (20 раундов по 8 параллельных запросов с одним ключом на раунд)
|
||||
- **THEN** все 160 ответов `201`, их обслужили не менее двух реплик, в каждом раунде тела ответов совпадают, в истории ровно одна копия, а другой body получает `409`
|
||||
|
||||
### Requirement: Лимиты и изоляция
|
||||
|
||||
Каждый сервис стенда, включая генератор нагрузки, SHALL иметь лимиты CPU и памяти. Ни один сервис SHALL NOT задавать `container_name`. Опубликованные порты SHALL быть только у балансировщика и только на `127.0.0.1`. Секреты SHALL монтироваться только сервисам, которые ими пользуются; volumes данных SHALL принадлежать только своему хранилищу; реплики API SHALL работать с корневой файловой системой только для чтения; внутренняя сеть SHALL быть недоступна снаружи, а генератор нагрузки SHALL видеть только балансировщик.
|
||||
|
||||
#### Scenario: Проверка лимитов и изоляции
|
||||
|
||||
- **WHEN** выполняется `make limits`
|
||||
- **THEN** проверка по `docker compose config` и `docker inspect` запущенных контейнеров печатает таблицу сервисов с лимитами, портами, секретами, volumes и сетями в `evidence/limits.txt` и завершается `PASS`; ни у одного контейнера `api` нет опубликованных портов
|
||||
|
||||
#### Scenario: Нарушение политики
|
||||
|
||||
- **WHEN** сервису без необходимости добавлен секрет, порт или `container_name`, либо снят лимит
|
||||
- **THEN** `make limits` перечисляет нарушение и завершается ненулевым кодом
|
||||
|
||||
### Requirement: Поочерёдная замена под нагрузкой и однократные миграции
|
||||
|
||||
Оператор SHALL одной командой заменять реплики новой версией образа по одной: сначала миграции применяются один раз отдельным процессом, затем на каждую старую реплику запускается новая, и старая останавливается только после того, как балансировщик видит новую готовой. Число готовых реплик в балансировщике SHALL NOT опускаться ниже исходного. Миграции SHALL быть совместимы с работающей предыдущей версией (только добавление объектов схемы) либо ограничение SHALL быть описано в `REPORT.md`.
|
||||
|
||||
#### Scenario: Замена под нагрузкой
|
||||
|
||||
- **WHEN** выполняется `make rolling-update`
|
||||
- **THEN** `evidence/rolling/result.json` показывает, что балансировщик ни разу не видел меньше исходного числа готовых реплик, доля ошибок нагрузки не больше 1 %, зонд не потерял записей, а после замены запросы обслуживают только новые контейнеры
|
||||
|
||||
#### Scenario: Обновление с прежней версии
|
||||
|
||||
- **WHEN** выполняется `make rolling-update FROM_REV=<коммит>`
|
||||
- **THEN** стенд сначала поднимается на образе, собранном из этого коммита, а затем заменяется текущей версией с теми же гарантиями; журнал замены называет старый и новый образ каждой реплики
|
||||
|
||||
#### Scenario: Миграции один раз
|
||||
|
||||
- **WHEN** идёт поочерёдная замена
|
||||
- **THEN** `migrate` запускается один раз до замены первой реплики, реплики схему не меняют, а повторный запуск сообщает `up to date`
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# lab3-idempotent-messages Specification
|
||||
|
||||
## Purpose
|
||||
Определяет идемпотентную отправку сообщения через `Idempotency-Key`: формат и область ключа, повтор и конфликт, срок хранения результата, атомарность записи и поведение при конкурентном повторе через разные реплики и при неопределённом исходе.
|
||||
## Requirements
|
||||
### Requirement: Обязательный ключ идемпотентности
|
||||
|
||||
`POST /api/v1/chats/{chat_id}/messages` SHALL требовать заголовок `Idempotency-Key` длиной 1–128 символов из `[A-Za-z0-9._:-]`. Отсутствующий или не соответствующий формату ключ SHALL давать `400` с кодом `invalid_request` в общем формате ошибки; сообщение при этом SHALL NOT сохраняться. Остальные endpoint SHALL NOT требовать ключ.
|
||||
|
||||
#### Scenario: Ключ отсутствует
|
||||
|
||||
- **WHEN** участник отправляет корректное сообщение без `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, история чата не меняется
|
||||
|
||||
#### Scenario: Ключ неверного формата
|
||||
|
||||
- **WHEN** `Idempotency-Key` пустой, длиннее 128 символов или содержит пробел, `/` или не-ASCII символ
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
### Requirement: Повтор возвращает исходный результат
|
||||
|
||||
Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Тело запроса для сравнения SHALL включать `text` и `attachment_ids` с учётом порядка вложений; отсутствующий `attachment_ids` SHALL считаться равным `[]`, порядок полей JSON SHALL NOT иметь значения. Повтор с тем же ключом и семантически тем же JSON в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text`, `attachment_ids` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый.
|
||||
|
||||
#### Scenario: Повтор того же тела
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":...}`
|
||||
- **THEN** ответ `201`, тело равно телу первого ответа целиком, включая `attachment_ids: []`, в истории одно такое сообщение
|
||||
|
||||
#### Scenario: Отсутствующий attachment_ids равен пустому списку
|
||||
|
||||
- **WHEN** первый `POST` содержит `{"text":"x"}`, а повтор с тем же ключом — `{"attachment_ids":[],"text":"x"}`
|
||||
- **THEN** повтор получает `201` с телом первого ответа
|
||||
|
||||
#### Scenario: Повтор сообщения с вложением
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":"","attachment_ids":[id]}`
|
||||
- **THEN** ответ `201` с тем же `Message` и `attachment_ids` равным `[id]`
|
||||
|
||||
#### Scenario: Тот же ключ, другое тело
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text` или другим списком либо порядком `attachment_ids`
|
||||
- **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся
|
||||
|
||||
#### Scenario: Тот же ключ у другого пользователя
|
||||
|
||||
- **WHEN** другой участник того же чата отправляет сообщение с тем же значением ключа
|
||||
- **THEN** ответ `201` с новым сообщением этого участника
|
||||
|
||||
#### Scenario: Тот же ключ в другом чате
|
||||
|
||||
- **WHEN** участник отправляет в другой свой чат сообщение с уже использованным ключом
|
||||
- **THEN** ответ `201` с новым сообщением в этом чате
|
||||
|
||||
#### Scenario: Срок ключа истёк
|
||||
|
||||
- **WHEN** с момента первой отправки прошло больше `IDEMPOTENCY_TTL_SECONDS` и участник отправляет с тем же ключом другой текст
|
||||
- **THEN** ответ `201` с новым сообщением, а не `409`
|
||||
|
||||
### Requirement: Повтор заново проверяет доступ
|
||||
|
||||
Повтор с известным ключом SHALL снова проверять сессию и членство в чате до выдачи сохранённого результата: отозванный или истёкший токен SHALL получать `401`, посторонний — `404`. Ответы `4xx` и `5xx` SHALL NOT сохраняться как результат ключа: после такого ответа повтор с тем же ключом обрабатывается как первая попытка.
|
||||
|
||||
#### Scenario: Повтор после выхода
|
||||
|
||||
- **WHEN** пользователь отправил сообщение, вышел и повторил запрос с тем же ключом и прежним токеном
|
||||
- **THEN** ответ `401`
|
||||
|
||||
#### Scenario: Ошибка не занимает ключ
|
||||
|
||||
- **WHEN** участник отправил с ключом `K` пустой текст и получил `400`, затем отправил с ключом `K` корректный текст
|
||||
- **THEN** второй ответ `201` с новым сообщением
|
||||
|
||||
#### Scenario: Посторонний с чужим ключом
|
||||
|
||||
- **WHEN** посторонний отправляет в чат запрос с ключом, уже использованным участником
|
||||
- **THEN** ответ `404`, сохранённое сообщение не раскрывается
|
||||
|
||||
### Requirement: Атомарная и общая для реплик идемпотентность
|
||||
|
||||
Сообщение и запись ключа SHALL фиксироваться одной транзакцией PostgreSQL: либо сохраняются оба, либо ни одно. Одновременные запросы с одним ключом и одним телом, пришедшие на разные реплики, SHALL создавать ровно одно сообщение, и каждый из них SHALL получать `201` с одинаковым `Message`. Если исход первой попытки неизвестен клиенту (обрыв, таймаут, остановка реплики), повтор с тем же ключом SHALL возвращать уже сохранённое сообщение либо, если транзакция не была зафиксирована, создавать его ровно один раз.
|
||||
|
||||
#### Scenario: Конкурентный повтор через разные реплики
|
||||
|
||||
- **WHEN** 8 параллельных `POST` с одним ключом и одним телом отправлены через LB
|
||||
- **THEN** все ответы `201` с одинаковым телом, ответы пришли от ≥2 реплик, в истории чата ровно одно такое сообщение
|
||||
|
||||
#### Scenario: Повтор после отказа реплики
|
||||
|
||||
- **WHEN** во время `make test-failover` запрос не получил ответа и повторён с тем же ключом и текстом
|
||||
- **THEN** в истории нет дублей по `id` и `text`, а каждый подтверждённый ответ совпадает с записью истории байт-в-байт
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# lab3-load-balancing Specification
|
||||
|
||||
## Purpose
|
||||
Определяет развёртывание API несколькими взаимозаменяемыми репликами за единственной публичной точкой входа: что видно клиенту, как балансировщик выбирает и исключает реплики, какие запросы он вправе повторить и как оператор останавливает одну реплику и перезапускает стенд.
|
||||
## Requirements
|
||||
### Requirement: Единственная точка входа и не менее двух реплик
|
||||
|
||||
Стенд SHALL описываться одним `compose.yaml` и запускаться документированной командой. API SHALL работать не менее чем двумя репликами одного compose-service без `container_name`; их число SHALL задаваться `API_REPLICAS` (по умолчанию 2). Наружу SHALL публиковаться только балансировщик на `127.0.0.1`; порты реплик API SHALL NOT публиковаться. Все реплики SHALL использовать одну общую PostgreSQL и одно общее хранилище сессий.
|
||||
|
||||
#### Scenario: Стенд поднят
|
||||
|
||||
- **WHEN** выполняется `make up`, затем `docker compose ps`
|
||||
- **THEN** работают ≥2 контейнера сервиса `api` в состоянии `healthy`, у них нет опубликованных портов, а единственные опубликованные порты принадлежат сервису `lb`
|
||||
|
||||
#### Scenario: Реплика недоступна в обход балансировщика
|
||||
|
||||
- **WHEN** с хоста выполняется запрос на порт 8080 контейнера реплики
|
||||
- **THEN** соединение не устанавливается: реплика слушает только внутреннюю сеть
|
||||
|
||||
### Requirement: Разные реплики на одной сессии
|
||||
|
||||
Балансировщик SHALL распределять новые соединения по готовым репликам без привязки клиента (sticky session). Реплика SHALL NOT хранить в памяти процесса сессии, ключи идемпотентности и другое состояние, от которого зависит ответ другой реплики: токен, выданный через одну реплику, SHALL приниматься любой другой, а отзыв сессии SHALL действовать на всех репликах сразу.
|
||||
|
||||
#### Scenario: Один токен, несколько реплик
|
||||
|
||||
- **WHEN** клиент с одним Bearer-токеном выполняет 40 запросов `GET /api/v1/users/me`, каждый новым соединением через LB
|
||||
- **THEN** все ответы `200`, а заголовок `X-Instance-Id` принимает не менее двух разных значений
|
||||
|
||||
#### Scenario: Выход действует на всех репликах
|
||||
|
||||
- **WHEN** пользователь выполнил `DELETE /api/v1/auth/sessions/current` через одну реплику
|
||||
- **THEN** следующий запрос с этим токеном получает `401` независимо от того, какая реплика его обслужила
|
||||
|
||||
### Requirement: Готовность backend и обновление адресов
|
||||
|
||||
Балансировщик SHALL активно проверять каждую реплику запросом `GET /health/ready` и SHALL исключать из ротации реплику, которая не отвечает `200`. Адреса реплик SHALL обновляться через DNS без перезапуска балансировщика: остановленная реплика исчезает из ротации, запущенная или пересозданная появляется сама. Ответы, сформированные самим балансировщиком (`502`, `503`, `504`), SHALL иметь тело в общем формате ошибки с `request_id`, равным заголовку `X-Request-Id`.
|
||||
|
||||
#### Scenario: Реплика возвращается в ротацию
|
||||
|
||||
- **WHEN** остановленная реплика снова запущена
|
||||
- **THEN** после успешных проверок готовности балансировщик снова направляет на неё запросы без перезапуска `lb`
|
||||
|
||||
#### Scenario: Нет ни одной готовой реплики
|
||||
|
||||
- **WHEN** все реплики API остановлены
|
||||
- **THEN** запрос через LB получает `503` с телом `{"error":{"code":"unavailable",...}}`
|
||||
|
||||
### Requirement: Повтор запросов балансировщиком
|
||||
|
||||
Балансировщик SHALL повторять на другой реплике запрос, который не удалось отправить из-за отказа соединения. Повтор после того, как запрос мог быть обработан, SHALL допускаться только для `GET` и для `POST /api/v1/chats/{chat_id}/messages` с `Idempotency-Key`. Балансировщик SHALL NOT прозрачно повторять `POST /api/v1/users`, `POST /api/v1/chats` и `POST /api/v1/auth/sessions`.
|
||||
|
||||
#### Scenario: Создание чата не повторяется
|
||||
|
||||
- **WHEN** реплика оборвала соединение во время `POST /api/v1/chats`
|
||||
- **THEN** клиент получает ошибку балансировщика, а не результат повторной отправки на другую реплику
|
||||
|
||||
### Requirement: Остановка одной реплики
|
||||
|
||||
Оператор SHALL иметь исполняемый хук `scripts/stop-one.sh`, который по переменной `TARGET_INSTANCE_ID` находит контейнер реплики с этим `X-Instance-Id`, останавливает только его с сохранением остальных сервисов и volumes, оставляет остановленным и завершается кодом 0 быстрее 10 секунд. Неизвестный идентификатор SHALL давать ненулевой код без остановки чего-либо. Не позднее 10 секунд от запуска хука SHALL продолжаться новые чтения и записи через LB, а подтверждённые сообщения SHALL оставаться доступными. Хук `scripts/restore.sh` SHALL возвращать остановленные реплики и ждать, пока балансировщик снова видит их готовыми.
|
||||
|
||||
#### Scenario: Отказ реплики под запросами
|
||||
|
||||
- **WHEN** выполняется `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
|
||||
- **THEN** тест печатает `PASS: failover preserved confirmed data and existing session`, хук завершился быстрее 10 с, первая успешная запись после хука пришла не позже 10 с от его старта, остановленная реплика больше не отвечает, а `docker ps -a` показывает именно её контейнер в состоянии `exited`
|
||||
|
||||
#### Scenario: Вторая реплика
|
||||
|
||||
- **WHEN** после `scripts/restore.sh` тест повторяется и целью становится другая реплика
|
||||
- **THEN** тест снова проходит
|
||||
|
||||
#### Scenario: Неизвестная реплика
|
||||
|
||||
- **WHEN** хук запущен с `TARGET_INSTANCE_ID`, которому не соответствует ни один контейнер `api`
|
||||
- **THEN** хук завершается ненулевым кодом, и все контейнеры продолжают работать
|
||||
|
||||
### Requirement: Рестарт стенда
|
||||
|
||||
Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL, Valkey и S3-сервер с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд, включая S3, снова готов: первое же чтение метаданных и байтов вложения после хука SHALL проходить без повторов.
|
||||
|
||||
#### Scenario: Полный рестарт сохраняет сессию
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres`, `valkey` и `s3` после прогона позже, чем до него
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
# lab4-attachments Specification
|
||||
|
||||
## Purpose
|
||||
Определяет вложения-изображения чата: синхронную загрузку оригинала PNG/JPEG с лимитами и проверкой содержимого, метаданные, скачивание оригинала через API, доступ только участникам чата, порядок записи PostgreSQL ↔ S3 и поведение при недоступном S3.
|
||||
## Requirements
|
||||
### Requirement: Загрузка оригинала в чат
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` от участника чата с телом из сырых байтов одного изображения (не multipart, не JSON) и заголовком `Content-Type: image/png` или `image/jpeg` и возвращать `201` с объектом `Attachment`: `status` `ready`, `variants` `[]`, `error_code` `null`, `chat_id` из пути, `owner_id` вызывающего, `size_bytes` равен длине тела, `sha256` — lowercase hex SHA-256 тела, `content_type` — тип, определённый по содержимому, `filename` — переданное имя. Ответ `201` SHALL выдаваться только после того, как оригинал записан в приватный bucket и метаданные зафиксированы в PostgreSQL. Ключ объекта SHALL назначаться сервером и SHALL NOT зависеть от `filename` и попадать в ответ. Повтор того же запроса SHALL создавать новое вложение.
|
||||
|
||||
#### Scenario: Fixture загружена
|
||||
|
||||
- **WHEN** участник загружает `tests/fixtures/sample.png` с `Content-Type: image/png` и `?filename=sample.png`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Attachment`, `status` `ready`, `size_bytes` 111817, `sha256` равен SHA-256 файла, `chat_id` и `owner_id` — чат и загрузивший
|
||||
|
||||
#### Scenario: JPEG загружен
|
||||
|
||||
- **WHEN** участник загружает корректный JPEG с `Content-Type: image/jpeg`
|
||||
- **THEN** ответ `201`, `content_type` `image/jpeg`
|
||||
|
||||
#### Scenario: Посторонний загружает в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в чат, или любой пользователь в несуществующий чат отправляет корректное изображение
|
||||
- **THEN** ответ `404` с кодом `not_found`, ничего не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат тело, не являющееся изображением, или опасный `filename`
|
||||
- **THEN** ответ `404`, а не `400` или `415`
|
||||
|
||||
#### Scenario: Без аутентификации
|
||||
|
||||
- **WHEN** upload приходит без `Authorization` или с `Basic`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
### Requirement: Лимиты размера до неограниченного чтения и декодирования
|
||||
|
||||
Тело SHALL быть не больше `MAX_UPLOAD_BYTES` (10 485 760) байт, а изображение — не больше `MAX_IMAGE_PIXELS` (40 000 000) пикселей по заголовку. Превышение SHALL давать `413` с кодом `payload_too_large`. Объявленный `Content-Length` больше лимита SHALL отклоняться без чтения тела, тело без `Content-Length` SHALL читаться не дальше лимита плюс один байт, а число пикселей SHALL проверяться по заголовку изображения до декодирования. Реплика SHALL NOT записывать тело на свой диск.
|
||||
|
||||
#### Scenario: Ровно 10 MiB
|
||||
|
||||
- **WHEN** загружается корректный PNG размером ровно 10 485 760 байт
|
||||
- **THEN** ответ `201` и `size_bytes` 10485760
|
||||
|
||||
#### Scenario: На байт больше с Content-Length
|
||||
|
||||
- **WHEN** загружается тело размером 10 485 761 байт с заголовком `Content-Length`
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`
|
||||
|
||||
#### Scenario: На байт больше без Content-Length
|
||||
|
||||
- **WHEN** тело размером 10 485 761 байт передаётся chunked, без `Content-Length`
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`, вложение не создаётся
|
||||
|
||||
#### Scenario: Ровно 40 млн пикселей
|
||||
|
||||
- **WHEN** загружается корректный PNG 8000×5000
|
||||
- **THEN** ответ `201`
|
||||
|
||||
#### Scenario: Больше 40 млн пикселей
|
||||
|
||||
- **WHEN** загружается PNG 8001×5000 или сжатый PNG огромных размеров весом несколько килобайт
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`, изображение не декодируется
|
||||
|
||||
### Requirement: Тип определяется по содержимому
|
||||
|
||||
Сервис SHALL принимать только `Content-Type` `image/png` и `image/jpeg` (параметры заголовка и регистр не важны) и SHALL проверять, что сигнатура и структура файла соответствуют заявленному типу, а файл читается без ошибок. Иной или отсутствующий `Content-Type`, несовпадение заявленного типа и содержимого, пустое тело, обрезанный или повреждённый файл, GIF, WebP и текст SHALL давать `415` с кодом `unsupported_media_type`.
|
||||
|
||||
#### Scenario: Подмена MIME
|
||||
|
||||
- **WHEN** JPEG, GIF или текст отправлены с `Content-Type: image/png`
|
||||
- **THEN** ответ `415` с кодом `unsupported_media_type`
|
||||
|
||||
#### Scenario: Обрезанное изображение
|
||||
|
||||
- **WHEN** отправлена первая половина корректного PNG или JPEG с верным `Content-Type`
|
||||
- **THEN** ответ `415`
|
||||
|
||||
#### Scenario: Неподдерживаемый Content-Type
|
||||
|
||||
- **WHEN** корректный PNG отправлен с `Content-Type: application/octet-stream` или без `Content-Type`
|
||||
- **THEN** ответ `415`
|
||||
|
||||
### Requirement: Безопасное отображаемое имя
|
||||
|
||||
`filename` SHALL быть обязательным параметром длиной 1–255 Unicode code points после percent-декодирования, SHALL NOT состоять только из пробельных символов и SHALL NOT содержать `/`, `\`, NUL и другие управляющие символы. Нарушение SHALL давать `400` с кодом `invalid_request`. Имя SHALL использоваться только для отображения и возвращаться без изменений.
|
||||
|
||||
#### Scenario: Опасное имя
|
||||
|
||||
- **WHEN** `filename` равен `../a.png`, `a/b.png`, `a\b.png`, содержит `%00`, `%01` или `%7F`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустое, пробельное, длинное или отсутствующее имя
|
||||
|
||||
- **WHEN** `filename` пустой, из пробелов, длиной 256 code points или не передан
|
||||
- **THEN** ответ `400`
|
||||
|
||||
#### Scenario: Имя на кириллице
|
||||
|
||||
- **WHEN** `filename` равен `фото 1.png` длиной до 255 code points
|
||||
- **THEN** ответ `201` и `filename` в ответе совпадает с переданным
|
||||
|
||||
### Requirement: Метаданные и скачивание только участникам
|
||||
|
||||
`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с исходными байтами, `Content-Type` вложения и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`. Параметр `variant` SHALL принимать только `original` (по умолчанию). Посторонний, неизвестный id и ещё не готовое вложение SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и неизвестный `variant` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`.
|
||||
|
||||
#### Scenario: Второй участник скачивает оригинал
|
||||
|
||||
- **WHEN** второй участник чата запрашивает `/content` загруженного вложения с `Accept: application/json`
|
||||
- **THEN** ответ `200`, `Content-Type: image/png`, байты совпадают с загруженными, SHA-256 равен `sha256` метаданных
|
||||
|
||||
#### Scenario: Посторонний
|
||||
|
||||
- **WHEN** пользователь вне чата запрашивает метаданные или `/content`
|
||||
- **THEN** оба ответа `404` с кодом `not_found`
|
||||
|
||||
#### Scenario: Неизвестный вариант
|
||||
|
||||
- **WHEN** запрошен `/content?variant=thumbnail`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Объект пропал из хранилища
|
||||
|
||||
- **WHEN** метаданные готового вложения есть, а объекта в bucket нет
|
||||
- **THEN** `/content` отвечает `404`, событие пишется в журнал без ключа объекта
|
||||
|
||||
### Requirement: Порядок записи PostgreSQL и S3
|
||||
|
||||
Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability `lab4-upload-resilience`), поэтому объект без строки-намерения в bucket не остаётся.
|
||||
|
||||
#### Scenario: S3 отказал при записи
|
||||
|
||||
- **WHEN** запись объекта завершилась ошибкой
|
||||
- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях, а строка-намерение удаляется уборкой после grace period
|
||||
|
||||
#### Scenario: Клиент оборвал загрузку
|
||||
|
||||
- **WHEN** клиент закрыл соединение, отправив часть тела
|
||||
- **THEN** в bucket нет нового объекта и в PostgreSQL нет новой строки вложения
|
||||
|
||||
### Requirement: Недоступный S3
|
||||
|
||||
Недоступность S3 SHALL превращаться в `503 unavailable` в общем формате ошибки за ограниченное время (меньше `REQUEST_TIMEOUT_SECONDS`) для upload и скачивания. Метаданные, тексты сообщений и `GET /health/ready` SHALL продолжать работать: готовность реплики от S3 не зависит. После возврата S3 ранее загруженные файлы SHALL скачиваться без изменений.
|
||||
|
||||
#### Scenario: S3 остановлен
|
||||
|
||||
- **WHEN** выполняется `docker compose stop s3` и клиент загружает и скачивает файл, отправляет текст и проверяет готовность
|
||||
- **THEN** upload и `/content` отвечают `503` с `X-Request-Id` и `X-Instance-Id` быстрее `REQUEST_TIMEOUT_SECONDS`, текстовое сообщение — `201`, метаданные и `/health/ready` — `200`
|
||||
|
||||
#### Scenario: S3 вернулся
|
||||
|
||||
- **WHEN** S3 снова запущен
|
||||
- **THEN** ранее загруженный файл скачивается с тем же SHA-256
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
# lab4-object-storage Specification
|
||||
|
||||
## Purpose
|
||||
Определяет объектное хранилище вложений как часть стенда: S3-совместимый сервер с закреплённой версией и persistent volume, приватный bucket и воспроизводимый bootstrap, раздельные ключи администратора и API, а также то, что байты не живут в БД и на диске реплики и переживают остановку реплики и рестарт стенда.
|
||||
## Requirements
|
||||
### Requirement: S3-сервер и приватный bucket в стенде
|
||||
|
||||
Стенд SHALL включать S3-совместимый сервер с образом, закреплённым версией и digest, данными на именованном volume и healthcheck, без опубликованных на хост портов и без доступной административной консоли — ни внутри контейнера, ни из сети стенда. Одноразовый bootstrap SHALL создавать bucket `S3_BUCKET` (по умолчанию `messenger-attachments`), делать его приватным для анонимного клиента, создавать пользователя API с политикой только на объекты и листинг этого bucket и завершаться кодом 0; повторный запуск SHALL проходить без ошибок и без изменения состояния. Реплики API SHALL стартовать после успешного bootstrap.
|
||||
|
||||
#### Scenario: Анонимный GET объекта
|
||||
|
||||
- **WHEN** из отдельного контейнера в сети стенда выполняется HTTP GET существующего объекта bucket без подписи
|
||||
- **THEN** ответ `403`, байты объекта не возвращаются
|
||||
|
||||
#### Scenario: Порты и консоль
|
||||
|
||||
- **WHEN** выполняется `docker compose ps`, запрос к порту консоли внутри контейнера S3 и запрос к тому же порту из отдельного контейнера сети стенда
|
||||
- **THEN** у сервиса S3 нет опубликованных портов, а консоль не отвечает ни там, ни там
|
||||
|
||||
#### Scenario: Повторный bootstrap
|
||||
|
||||
- **WHEN** bootstrap запускается ещё два раза на работающем стенде
|
||||
- **THEN** оба запуска завершаются кодом 0, а bucket, его анонимная политика, пользователь и политика API не меняются
|
||||
|
||||
### Requirement: Раздельные ключи и места хранения
|
||||
|
||||
Root-ключи S3 SHALL передаваться файлами compose secrets только S3-серверу, bootstrap и операторскому CLI; реплики API SHALL получать отдельный ключ из `S3_ACCESS_KEY_ID_FILE` и `S3_SECRET_ACCESS_KEY_FILE`. Ключ API SHALL разрешать только чтение, запись, удаление объектов и листинг bucket `S3_BUCKET` и SHALL получать `AccessDenied` на создание и удаление bucket, изменение его политики и lifecycle, администрирование пользователей и любые операции с другим bucket. Байты вложений SHALL храниться только в bucket: в PostgreSQL SHALL NOT быть столбцов с содержимым файла, у реплик API SHALL NOT быть volume, а корневая файловая система реплики SHALL быть только для чтения. Ключи и адреса хранилища SHALL NOT попадать в ответы API, журнал и Git.
|
||||
|
||||
#### Scenario: Где лежат байты
|
||||
|
||||
- **WHEN** после загрузки выполняются `\d attachments`, листинг bucket и `docker inspect` реплики API
|
||||
- **THEN** в таблице нет `bytea`, объект лежит в bucket под ключом `attachments/<uuid>`, у реплики `ReadonlyRootfs=true` и нет volume
|
||||
|
||||
#### Scenario: Ключ API
|
||||
|
||||
- **WHEN** проверяются секреты сервиса `api` в `docker compose config`
|
||||
- **THEN** у `api` есть только ключ API S3, а root-ключей нет
|
||||
|
||||
#### Scenario: Права ключа API вне API
|
||||
|
||||
- **WHEN** из отдельного контейнера ключом API выполняются запись, чтение, листинг и удаление объекта, а затем создание и удаление bucket, публичная политика, импорт lifecycle, список пользователей, запись и листинг в другом bucket
|
||||
- **THEN** первые четыре операции разрешены, остальные получают `AccessDenied`
|
||||
|
||||
### Requirement: Файл переживает остановку обслужившей реплики
|
||||
|
||||
Вложение, загруженное через одну реплику API, SHALL скачиваться через другую реплику после остановки первой с тем же SHA-256.
|
||||
|
||||
#### Scenario: Upload, остановка реплики, download
|
||||
|
||||
- **WHEN** выполняется `python3 scripts/lab4_scenarios.py failover-upload`: upload, остановка реплики из `X-Instance-Id` ответа хуком `scripts/stop-one.sh`, скачивание
|
||||
- **THEN** скачивание обслуживает другая реплика, SHA-256 совпадает, сценарий печатает `"ok": true`
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
# lab4-upload-resilience Specification
|
||||
|
||||
## Purpose
|
||||
Определяет устойчивость загрузки вложений: что остаётся после сбоя между записью объекта и фиксацией метаданных и кто это убирает, какой grace period защищает идущие загрузки, как обрываются прерванные и зависшие загрузки, сколько памяти занимают одновременные загрузки и что пользовательские ошибки файлов не превращаются в `500`.
|
||||
## Requirements
|
||||
### Requirement: Компенсация сбоя после записи объекта
|
||||
|
||||
Если объект записан в bucket, а перевод вложения в готовое не зафиксирован, сервис SHALL ответить `503` с кодом `unavailable` и до ответа SHALL попытаться удалить объект и строку-намерение. Строку, которая к этому моменту уже готова, сервис SHALL NOT удалять вместе с её объектом. Если строку-намерение к моменту перевода в готовое уже убрали, сервис SHALL ответить `503` и удалить записанный объект, а не возвращать `201`. Неудача компенсации SHALL оставлять строку-намерение для уборки по grace period.
|
||||
|
||||
#### Scenario: Отказ COMMIT после записи объекта
|
||||
|
||||
- **WHEN** запись объекта прошла, а фиксация статуса `ready` в PostgreSQL отклонена
|
||||
- **THEN** ответ `503` с кодом `unavailable`, сразу после ответа нет ни строки вложения, ни объекта с его ключом, в журнале есть событие удаления намерения с причиной `compensation`
|
||||
|
||||
#### Scenario: Намерение снято раньше, чем загрузка завершилась
|
||||
|
||||
- **WHEN** во время записи объекта строку-намерение удалили
|
||||
- **THEN** ответ `503`, объект с ключом этой загрузки удалён, готового вложения не появилось
|
||||
|
||||
### Requirement: Уборка брошенных загрузок по grace period
|
||||
|
||||
Сервис SHALL без участия оператора и не реже чем раз в `UPLOAD_SWEEP_INTERVAL_SECONDS` удалять сначала объект, затем строку каждого намерения `pending`, созданного раньше чем `UPLOAD_GRACE_SECONDS` назад. Grace period SHALL быть не меньше 60 с и много больше `REQUEST_TIMEOUT_SECONDS`, чтобы идущая загрузка не была убрана. Уборка SHALL NOT трогать намерения моложе grace period, готовые вложения и вложения, на которые ссылаются сообщения, SHALL быть безопасной при одновременной работе на нескольких репликах и повторяемой: следующий проход после полного SHALL ничего не удалять. Если S3 недоступен, намерение SHALL оставаться до следующего прохода.
|
||||
|
||||
#### Scenario: Процесс упал между записью объекта и фиксацией
|
||||
|
||||
- **WHEN** процесс реплики убит после записи объекта, но до фиксации `ready`, а затем намерение становится старше grace period
|
||||
- **THEN** до истечения grace period строка `pending` и объект остаются невидимыми клиентам; после — уборка удаляет и объект, и строку
|
||||
|
||||
#### Scenario: Свежее намерение переживает уборку
|
||||
|
||||
- **WHEN** проход уборки выполняется, пока одно брошенное намерение старше grace period, а другое моложе
|
||||
- **THEN** удалено только старое, свежее остаётся вместе со своим объектом
|
||||
|
||||
#### Scenario: Готовые и используемые вложения не трогаются
|
||||
|
||||
- **WHEN** проход уборки выполняется после того, как время создания готового вложения, на которое ссылается сообщение, сдвинуто далеко в прошлое
|
||||
- **THEN** вложение по-прежнему скачивается участником с тем же SHA-256
|
||||
|
||||
#### Scenario: Несколько уборок одновременно
|
||||
|
||||
- **WHEN** два прохода уборки одновременно обрабатывают пять брошенных намерений
|
||||
- **THEN** вместе они удаляют ровно пять, без ошибок, а следующий проход удаляет ноль
|
||||
|
||||
### Requirement: Обрыв и зависание тела
|
||||
|
||||
Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки вложения и SHALL учитываться как ошибка клиента (`400`), а не `500`. Тело, которое перестало поступать, SHALL обрываться не позже `REQUEST_TIMEOUT_SECONDS` с ответом `503` и кодом `unavailable`, без объекта и строки, а занятый им слот загрузки SHALL освобождаться для следующих загрузок.
|
||||
|
||||
#### Scenario: Клиент закрыл соединение посреди тела
|
||||
|
||||
- **WHEN** клиент объявил `Content-Length` 5 MiB, отправил 256 KiB и закрыл соединение
|
||||
- **THEN** строка вложения не создавалась, объект не появился, реплика записала в журнал статус `400`
|
||||
|
||||
#### Scenario: Тело зависло
|
||||
|
||||
- **WHEN** клиент отправил заголовки и часть тела и перестал слать байты
|
||||
- **THEN** не позже `REQUEST_TIMEOUT_SECONDS` плюс 2 с приходит `503` с кодом `unavailable`, строки и объекта нет, следующая загрузка проходит
|
||||
|
||||
### Requirement: Ограниченная память одновременных загрузок
|
||||
|
||||
Воркер API SHALL держать в памяти тела не более `UPLOAD_CONCURRENCY` загрузок одновременно; остальные загрузки SHALL ждать свободного слота, не читая тело, в пределах `REQUEST_TIMEOUT_SECONDS`. Тело SHALL NOT записываться на диск реплики. Пик памяти реплики при ≥10 одновременных загрузках по 10 MiB SHALL оставаться ниже её лимита памяти без перезапуска процесса, а все корректные загрузки SHALL получать `201`.
|
||||
|
||||
#### Scenario: Ожидание слота
|
||||
|
||||
- **WHEN** при `UPLOAD_CONCURRENCY=1` одна загрузка держит слот, а вторая приходит следом
|
||||
- **THEN** тело второй не читается, пока первая не завершилась, затем обе получают `201`
|
||||
|
||||
#### Scenario: Замер одновременных загрузок
|
||||
|
||||
- **WHEN** через LB идут 10, 20 и 40 одновременных загрузок PNG по 1 MiB и по 10 MiB, а пик памяти каждой реплики снимается из cgroup
|
||||
- **THEN** при лимите слотов все загрузки получают `201`, пик памяти реплики ниже `API_MEMORY` и не растёт пропорционально числу одновременных загрузок
|
||||
|
||||
### Requirement: Пользовательские ошибки файлов не дают 500
|
||||
|
||||
Ни одна ошибка клиента при загрузке, чтении вложения или ссылке на него SHALL NOT давать ответ `5xx` или строку журнала реплики со статусом `500`. Через балансировщик против настоящих PostgreSQL и S3 SHALL проверяться: тело на байт больше лимита (с `Content-Length` и chunked) — `413`; декомпрессионная бомба — `413`; обрезанный PNG и JPEG — `415`; подмена MIME (JPEG, GIF, текст как `image/png`, PNG как `image/jpeg`) и отсутствующий или иной `Content-Type` — `415`; опасный и пустой `filename` — `400`; метаданные и `/content` чужого вложения — `404`; ссылка на чужое, неизвестное вложение и вложение другого чата — `404`; 11 и повторяющиеся `attachment_ids`, невалидный UUID и неизвестный `variant` — `400`.
|
||||
|
||||
#### Scenario: Негативный suite через балансировщик
|
||||
|
||||
- **WHEN** все перечисленные запросы отправлены на стенд через LB
|
||||
- **THEN** каждый ответ имеет ожидаемый код и тело ошибки по схеме `Error`, ни один не `5xx`, в журнале реплик за время прогона нет статуса `500`, а строк вложений в чате ровно столько, сколько было ответов `201`
|
||||
|
||||
Reference in New Issue
Block a user