1 Commits
Author SHA1 Message Date
Artyom 6d8b76b447 lab2 2026-10-30 12:32:42 +03:00
222 changed files with 19685 additions and 18 deletions
+181
View File
@@ -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
+225
View File
@@ -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
+193
View File
@@ -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
+145
View File
@@ -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
+258
View File
@@ -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
+87
View File
@@ -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.
+45
View File
@@ -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
+17
View File
@@ -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
+308
View File
@@ -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
+149
View File
@@ -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
+262
View File
@@ -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.
+24
View File
@@ -14,7 +14,31 @@ backups
*.pfx *.pfx
*.jks *.jks
.venv .venv
venv
__pycache__ __pycache__
*.pyc
*.pyo
.pytest_cache
.ruff_cache
.mypy_cache
.ty_cache
node_modules node_modules
evidence evidence
openspec
student-tests
tests
scripts
examples
contracts
infra
*.md
!README.md
Makefile
Dockerfile*
compose*.yaml
.dockerignore
.gitignore
.DS_Store .DS_Store
lab.json
requirements-dev.txt
.claude
+5
View File
@@ -9,3 +9,8 @@ DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey: # Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url CACHE_URL_FILE=/run/secrets/cache_url
# Solution-specific: host ports of the API and of the short TTL instance, workers, cursor key file.
API_PORT=8080
SHORTTTL_PORT=8082
WEB_CONCURRENCY=4
CURSOR_SECRET_FILE=/run/secrets/cursor_secret
+58
View File
@@ -0,0 +1,58 @@
name: Application
on: [push, pull_request]
permissions:
contents: read
jobs:
quality:
name: Линт, типы и собственные тесты
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
with:
enable-cache: true
- run: uv sync --locked --group dev
- run: make lint VENV=.venv
- run: make student-test VENV=.venv
acceptance:
name: Стенд Compose, smoke, рестарт и отказы зависимостей
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
with:
enable-cache: true
- run: uv sync --locked --group dev
- name: Поднять стенд из чистого clone
run: make up
- name: Публичный smoke
run: make test
- name: Рестарт API и хранилищ с сохранением volumes
run: make test-persistence ACTION_SCRIPT=scripts/restart.sh
- name: Отказы Valkey и PostgreSQL, expiry, гонка и rollback
run: make test-faults
- name: Процессы работают не от root
run: |
docker compose top | awk 'NR>1 && $3=="0" {print; bad=1} END {exit bad}'
- name: Корректная остановка API по SIGTERM
run: |
start=$(date +%s)
docker compose kill --signal SIGTERM api
code=$(docker wait "$(docker compose ps -aq api)")
elapsed=$(( $(date +%s) - start ))
echo "остановка за ${elapsed} с, код завершения ${code}"
test "$elapsed" -le 10 && test "$code" = "0"
- name: Журналы стенда
if: always()
run: docker compose logs --tail 80
+8
View File
@@ -30,3 +30,11 @@ coverage/
.vscode/ .vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control. # Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner. # Inspect git diff --cached: ignore rules are not a secret scanner.
# Тулчейн студенческой реализации
.pytest_cache/
.ruff_cache/
.ty_cache/
# Локальные настройки агента
.claude/settings.local.json
+61
View File
@@ -0,0 +1,61 @@
## Что это за репозиторий
Skeleton лабораторной 2 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке `solution/bpi2303-kostylev`. Skeleton даёт задание (`README.md`), нормативный контракт (`contracts/`) и публичные black-box проверки (`tests/`). Реализация API, Dockerfile, compose-стенд, миграции и собственные тесты — студенческие; решение лабы 2 построено переносом решения лабы 1.
Лаба 2: состояние переезжает в **PostgreSQL**, пользователи входят по паролю (`Basic` только на `POST /api/v1/auth/sessions`), остальные endpoint требуют непрозрачный `Bearer`-токен сессии с TTL и отзывом, `X-User-Id` игнорируется. На «4» появляется **Valkey** с конкретной ролью (здесь — read-through кэш сессий поверх PostgreSQL). Данные и действующие сессии переживают рестарт API и хранилищ с сохранёнными volumes.
## Команды
```sh
make check # offline: структура skeleton, JSON, локальные $ref, синтаксис Python
make install # uv sync --group dev (включая openapi-spec-validator)
make validate # полная валидация OpenAPI 3.1 (берёт .venv/bin/python после make install)
make lint # ruff check + ruff format --check + ty check; обязательно перед commit
make student-test # собственные тесты (поднимают одноразовые PostgreSQL и Valkey в Docker)
make student-test PYTEST_ARGS='-v -k cache' # выборка тестов с именами
make secrets # локальные secrets/* и .env из .env.example (не коммитятся)
make up # docker compose up -d --build --wait: postgres, valkey, migrate, api
make test # публичный smoke против http://localhost:$API_PORT (Makefile читает .env)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт api, postgres, valkey с сохранением volumes
make test-faults # expiry, logout, гонки, rollback, отказы Valkey и PostgreSQL против стенда
make seed explain # 20 000 сообщений и EXPLAIN (ANALYZE, BUFFERS) индекса истории
make track-bench # трек 5: база track, 1M сообщений по Ципфу, 4 набора индексов, pgbench
make track-recovery # трек 5: pg_dump → новый postgres-restore → pg_restore → сверка, RTO/RPO
make down # остановка без удаления данных (с профилями faults и track); make reset-data — удаление volumes
make toolchain-evidence # и другие *-evidence: файлы evidence/ с датой и коммитом (список — REPORT.md)
```
`tests/*.py` и `scripts/*.py` — только stdlib, синтаксис Python 3.9 (`make check` разбирает их системным `python3`). Проверки сами не поднимают стенд. Данные не удаляются автоматически: в API нет DELETE, каждый прогон smoke создаёт новых синтетических пользователей.
## Архитектура skeleton
- `lab.json` — единственный источник номера лабы (2). От него зависят `scripts/check_contract.py` (`info.version == 1.2.0`, наличие `/api/v1/auth/sessions`) и `tests/client.py` (Bearer-ветки smoke с lab2).
- `tests/client.py` валидирует ответы по подмножеству JSON Schema прямо из `contracts/openapi.json`; для `401` на lab≥2 проверяет `WWW-Authenticate`: `Basic` на `/api/v1/auth/sessions`, `Bearer` на остальных путях.
- `tests/resilience.py --mode persistence` держит токен только в памяти, запускает hook без shell (≤90 с, код 0), ждёт `/health/ready` и `/users/me` прежним токеном до 90 с, сверяет историю. Таймаут клиента 2 с.
- `contracts/infrastructure.json` — роли: `api`, `postgres` (persistent volume), опциональный `redis_or_valkey` (обязателен на «4»). `compose.example.yaml` — только worksheet ролей.
## Ключевые правила контракта (lab2)
- `POST /api/v1/users` публичен, тело `{username, display_name, password}`; `password` 12–128 code points, хранится только как Argon2id; `User` без пароля и hash; дубль `username` → `409`, в том числе в гонке.
- `POST /api/v1/auth/sessions`: только `Authorization: Basic`, без тела; неверный пароль и неизвестный username — одинаковый `401` с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. Ответ `201 {token, token_type:"Bearer", expires_at, user}`.
- Остальные `/api/v1/*` — только `Authorization: Bearer <token>`; истёкший, отозванный, неизвестный токен и `Basic` на бизнес-endpoint → `401` с `WWW-Authenticate: Bearer realm="messenger"`. `X-User-Id` игнорируется полностью.
- `DELETE /api/v1/auth/sessions/current` → `204` без тела; повтор → `401`. TTL абсолютный (`SESSION_TTL_SECONDS`), рестарт его не продлевает.
- Аутентификация раньше доступа и валидации: без валидного Bearer — `401` даже при битом JSON. Отказ зависимости при проверке сессии — `503 unavailable`, не `401` и не анонимный доступ.
- Прежние правила lab1 сохраняются: `X-Request-Id` в каждом ответе, формат ошибки `{"error":{code,message,request_id}}`, посторонний → `404`, keyset `(created_at, id)`, `limit` 1–100, cursor привязан к чату, время RFC 3339 с `Z`.
## Правила работы с репозиторием
- Не менять и не ослаблять `contracts/`, `tests/`, `README.md`, `COURSE.md`, рубрику. Расхождение оформляется вопросом преподавателю.
- Код — `src/messenger/`, миграции — `src/messenger/migrations/NNNN_*.sql`, собственные тесты — `student-tests/`, обезличенные доказательства — `evidence/`.
- Без комментариев в коде; отступы — пробелы (`[tool.ruff.format]`); Python 3.14 без `from __future__ import annotations` и `TYPE_CHECKING`.
- `REPORT.md`: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл». PASS без команды не доказательство.
- Ветка `solution/bpi2303-kostylev`, коммиты на английском, перед каждым — `make lint`. Никогда не коммитить `.env`, `secrets/`, токены, volumes, дампы.
## Уровни оценки
Решение заявлено на **«5»** с треком 2 «План запроса и восстановление»; таблица доказательств — в `REPORT.md`.
- **3** — контракт lab2, PostgreSQL с PK/FK/UNIQUE и миграциями, атомарное создание чата, Basic/Bearer/TTL/logout, Argon2id, `make test` и `make test-persistence ACTION_SCRIPT=scripts/restart.sh`.
- **4** — Valkey с ролью и политикой инвалидации, параметризованный SQL, ограниченный пул и таймауты, гонка регистрации и rollback, индекс истории с EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях, автотесты expiry/logout/неверного пароля/недоступности Valkey и PostgreSQL.
- **5** — трек 2: ≥100 000 сообщений с перекосом чатов, сравнение индексов и запросов, стоимость записи, backup → restore в новое хранилище → сверка, RTO/RPO.
+47
View File
@@ -0,0 +1,47 @@
FROM python:3.14-slim-trixie@sha256:51dafde81dbdb6ebde285137a295cf18a47ca95234fe388a343719cb97305b3d AS builder
COPY --from=ghcr.io/astral-sh/uv:0.9.7@sha256:ba4857bf2a068e9bc0e64eed8563b065908a4cd6bfb66b531a9c424c8e25e142 /uv /usr/local/bin/uv
ENV UV_COMPILE_BYTECODE=1 \
UV_LINK_MODE=copy \
UV_PYTHON_DOWNLOADS=never \
UV_PROJECT_ENVIRONMENT=/opt/venv
WORKDIR /build
COPY pyproject.toml uv.lock README.md ./
RUN uv sync --locked --no-dev --no-install-project --no-editable
COPY src ./src
RUN uv sync --locked --no-dev --no-editable
FROM python:3.14-slim-trixie@sha256:51dafde81dbdb6ebde285137a295cf18a47ca95234fe388a343719cb97305b3d AS runtime
ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
PATH="/opt/venv/bin:$PATH" \
HOST=0.0.0.0 \
PORT=8080 \
LOG_LEVEL=INFO \
WEB_CONCURRENCY=4 \
REQUEST_TIMEOUT_SECONDS=15 \
SHUTDOWN_TIMEOUT_SECONDS=8
RUN groupadd --system --gid 10001 messenger \
&& useradd --system --uid 10001 --gid messenger --no-create-home --shell /usr/sbin/nologin messenger
COPY --from=builder --chown=root:root /opt/venv /opt/venv
WORKDIR /app
USER 10001:10001
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
CMD ["python", "-c", "import urllib.request,sys;sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8080/health/live',timeout=2).status==200 else 1)"]
CMD ["python", "-m", "gunicorn", \
"--config", "python:messenger.gunicorn_conf", \
"messenger.main:create_app()"]
+116 -2
View File
@@ -1,17 +1,36 @@
SHELL_PORTS := $(foreach v,API_PORT SHORTTTL_PORT,$(if $(filter environment,$(origin $v)),$v=$($v)))
-include .env
$(foreach port,$(SHELL_PORTS),$(eval $(port)))
PYTHON ?= python3 PYTHON ?= python3
BASE_URL ?= http://localhost:8080 BASE_URL ?= http://localhost:$(or $(API_PORT),8080)
CA_FILE ?= CA_FILE ?=
ACTION_SCRIPT ?= ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence VENV ?= .venv
UV ?= uv
COMPOSE ?= docker compose
PSQL = $(COMPOSE) exec -T postgres psql -U messenger -d messenger -X -q
SHORTTTL_PORT ?= 8082
PYTEST_ARGS ?=
TRACK_ARGS ?=
SHORTTTL_URL ?= http://localhost:$(SHORTTTL_PORT)
.PHONY: help check validate test load test-persistence \
install lint format typecheck student-test \
secrets up down reset-data migrate ps logs persistence-evidence storage-evidence cache-evidence test-faults seed explain track-bench track-recovery \
migrations-evidence environment-evidence sigterm-evidence load-evidence toolchain-evidence faults-evidence
help: help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "install/lint/typecheck/student-test: студенческий тулчейн"
@echo "secrets/up/down/migrate/ps/logs: стенд Docker Compose; reset-data: намеренное удаление volumes"
check: check:
$(PYTHON) scripts/check_contract.py $(PYTHON) scripts/check_contract.py
validate: PYTHON := $(if $(wildcard $(VENV)/bin/python),$(VENV)/bin/python,$(PYTHON))
validate: validate:
$(PYTHON) scripts/validate_openapi.py $(PYTHON) scripts/validate_openapi.py
@@ -24,3 +43,98 @@ load:
test-persistence: test-persistence:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2) @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2)
$(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) $(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
install:
$(UV) sync --group dev
lint:
$(VENV)/bin/ruff check src student-tests scripts/track.py
$(VENV)/bin/ruff format --check src student-tests scripts/track.py
$(VENV)/bin/ty check src student-tests
format:
$(VENV)/bin/ruff check --fix src student-tests scripts/track.py
$(VENV)/bin/ruff format src student-tests scripts/track.py
typecheck:
$(VENV)/bin/ty check src student-tests
student-test:
$(VENV)/bin/pytest $(PYTEST_ARGS)
secrets:
sh scripts/secrets.sh
up: secrets
$(COMPOSE) up -d --build --wait
down:
$(COMPOSE) --profile faults --profile track down
reset-data:
@echo "Удаляются volumes с учебными данными стенда"
$(COMPOSE) --profile faults --profile track down -v --remove-orphans
migrate:
$(COMPOSE) run --rm migrate
ps:
$(COMPOSE) ps
logs:
$(COMPOSE) logs --tail 200
persistence-evidence:
sh scripts/persistence-evidence.sh "$(BASE_URL)" > evidence/persistence.txt
cat evidence/persistence.txt
storage-evidence:
sh scripts/evidence-storage.sh
cache-evidence:
sh scripts/evidence-cache.sh > evidence/cache.txt
cat evidence/cache.txt
migrations-evidence:
@echo "Удаляются volumes с учебными данными стенда: миграции применяются к пустой БД"
sh scripts/evidence-migrations.sh "$(BASE_URL)" > evidence/migrations.txt
cat evidence/migrations.txt
environment-evidence:
sh scripts/evidence-environment.sh > evidence/environment.txt
cat evidence/environment.txt
sigterm-evidence:
sh scripts/evidence-sigterm.sh "$(BASE_URL)" > evidence/sigterm.txt
cat evidence/sigterm.txt
load-evidence:
sh scripts/evidence-load.sh "$(BASE_URL)" > evidence/load.txt
cat evidence/load.txt
toolchain-evidence:
sh scripts/evidence-toolchain.sh "$(BASE_URL)"
test-faults:
$(COMPOSE) --profile faults up -d --wait api-shortttl
BASE_URL="$(BASE_URL)" SHORTTTL_URL="$(SHORTTTL_URL)" $(VENV)/bin/pytest -m stack -v -s student-tests/stack
faults-evidence:
{ echo "date: $$(date -u +%FT%TZ) commit: $$(git rev-parse --short HEAD)"; echo "\$$ make test-faults"; \
$(MAKE) --no-print-directory test-faults 2>&1; } > evidence/faults.txt
cat evidence/faults.txt
seed:
$(PSQL) -f - < scripts/sql/seed-history.sql
explain: seed
{ echo "date: $$(date -u +%FT%TZ) commit: $$(git rev-parse --short HEAD)"; \
echo "\$$ make explain # scripts/sql/explain-history.sql"; \
$(PSQL) -f - < scripts/sql/explain-history.sql; } > evidence/explain-history.txt
cat evidence/explain-history.txt
track-bench:
$(PYTHON) scripts/track.py bench $(TRACK_ARGS)
track-recovery:
$(PYTHON) scripts/track.py recovery $(TRACK_ARGS)
+534 -16
View File
@@ -1,37 +1,555 @@
# Отчёт — лабораторная 2 # Отчёт — лабораторная 2
- Автор, группа: TODO - Автор, группа: Костылев Артём, БПИ2303
- Целевая оценка; выбранный трек 5, если нужен: TODO - Целевая оценка: **5**; трек «5» — **трек 2 «План запроса и восстановление»**
- Commit/PR: TODO после публикации - Commit/PR: ветка `solution/bpi2303-kostylev`; код (`src/`, `compose.yaml`, `Dockerfile`, `student-tests/`)
- Использованные источники, библиотеки и помощь ИИ: TODO последний раз менялся в коммите `bc90266`. Все файлы `evidence/` сняты на `6468ee2`: код там тот же, после
`bc90266` менялись только скрипты доказательств и архив openspec. Дальше коммиты меняют только отчёт и
`evidence/`. PR «ЛР 2 — БПИ2303 — Костылев — на 5» в репозиторий преподавателя заполняется по
`.github/pull_request_template.md`; его ссылка появляется при публикации
- Использованные источники, библиотеки и помощь ИИ: FastAPI, gunicorn + uvicorn-worker, dishka, pydantic,
structlog, asyncpg, redis-py (`redis.asyncio`), argon2-cffi, pytest, ruff, ty (версии —
`evidence/environment.txt` и `uv.lock`); документация PostgreSQL (transactions, EXPLAIN, WAL
reliability), Valkey persistence, RFC 7617, OWASP Password Storage Cheat Sheet.
Решение перенесено из моей лабы 1 и выполнено с помощью Claude Code; код, стенд и измерения проверены
прогонами, перечисленными ниже.
## Запуск из чистого clone ## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. Требуются Docker с Compose v2 и `make`; системный Python 3.9+ — только для публичных проверок. Образы
сторонних сервисов закреплены версией и digest, API собирается из исходников.
```sh
git clone <repo> && cd mtusi2026lab2 && git checkout solution/bpi2303-kostylev
make secrets # secrets/*: пароль PostgreSQL, DATABASE_URL, valkey.conf и CACHE_URL, ключ курсора; .env из .env.example
make up # docker compose up -d --build --wait: postgres и valkey → migrate → api, ждёт healthy
make test # публичный smoke против http://localhost:$API_PORT
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make down # безопасная остановка: контейнеры удаляются, volumes с данными остаются
make reset-data # НАМЕРЕННОЕ удаление учебных данных: docker compose down -v
```
Стенд останавливают только `make down` и `make reset-data`: в них стоит `--profile faults --profile track`. Простой
`docker compose down` не видит профильные `api-shortttl` и `postgres-restore`, которые поднимают
`make test-faults`, трек и `make environment-evidence`, и не может удалить сеть («Resource is still in use»). При
ручном вызове профили нужно указать явно: `docker compose --profile faults --profile track down`.
`make secrets` идемпотентен: существующие файлы не перезаписываются, поэтому пароль остаётся согласованным
с уже созданным volume. Значения нигде не печатаются. Порты хоста задают `API_PORT` (по умолчанию 8080) и
`SHORTTTL_PORT` (8082, экземпляр с коротким TTL) в `.env`. Makefile читает `.env`, поэтому `BASE_URL` и
`SHORTTTL_URL` следуют за ними без флагов. Переопределить порты можно переменной окружения
(`API_PORT=18082 make up`: Makefile запоминает её до чтения `.env` и возвращает после) или аргументом make
(`make test-faults API_PORT=18082 SHORTTTL_PORT=22082`). Доказательства в `evidence/` сняты на портах 18082 и 22082.
Образ приложения помечается именем compose-проекта (`mtusi-messenger:${COMPOSE_PROJECT_NAME}`), поэтому клон
в другом каталоге собирает свой образ и не перетирает чужой.
Собственные проверки и тулчейн:
```sh
make install # uv sync --group dev (Python 3.14, зависимости из uv.lock, openapi-spec-validator)
make lint # ruff check + ruff format --check + ty check
make student-test # собственные тесты; поднимают одноразовые PostgreSQL и Valkey тех же образов в Docker
make student-test PYTEST_ARGS='-v -k cache' # выборка тестов с именами (аргументы уходят в pytest)
make check # офлайн-проверка skeleton
make validate # полная валидация OpenAPI 3.1: берёт .venv/bin/python, если его создал make install
make migrate # повторный запуск миграций на текущей БД
make test-faults # поднимает api-shortttl и гоняет 13 тестов отказов против стенда
make seed explain # 20 000 сообщений в синтетическом чате и EXPLAIN (ANALYZE, BUFFERS)
make track-bench # трек 5: база track, 1 000 000 сообщений по Ципфу, 4 набора индексов + контроль, pgbench (~10 мин)
make track-recovery # трек 5: pg_dump → новый postgres-restore → pg_restore → сверка, 100k и 1M × 3 (~1.5 мин)
```
Без `make install` каталога `.venv` нет, и `make validate` идёт системным `python3`, где нет
`openapi_spec_validator` (`ModuleNotFoundError`). Тогда нужен `make install` или `pip install -r requirements-dev.txt`.
Короткая проверка трека без перезаписи `evidence/track` (аргументы уходят в `scripts/track.py`):
```sh
make track-bench TRACK_ARGS='--messages 20000 --write-seconds 2 --write-repeats 1 --out backups/track-quick' # ~40 с
make track-recovery TRACK_ARGS='--sizes 100000 --repeats 1 --out backups/track-quick' # ~15 с
```
Каждый файл доказательств пишет своя цель, с датой и коммитом в заголовке:
```sh
make toolchain-evidence # check, validate, lint, test → checks.txt; student-test -v и выборки -k → student-tests.txt
make migrations-evidence # НАМЕРЕННО удаляет volumes: 0001_init на пустом volume, затем повтор → migrations.txt
make persistence-evidence # persistence-тест + StartedAt сервисов до и после → persistence.txt
make storage-evidence # \d+ схемы, префикс KDF, правила ignore и volumes проекта → schema/kdf/secrets.txt
make cache-evidence # AOF, попадания, ключи и отметки отзыва, срок ключа против срока сессии → cache.txt
make faults-evidence # make test-faults → faults.txt
make load-evidence # 3 прогона tests/load.py c64 с docker stats и ожиданиями pg_stat_activity → load.txt, load-c64-{1,2,3}.json
make sigterm-evidence # SIGTERM api при двух запросах в работе: ответы, время и код завершения → sigterm.txt
make environment-evidence # host, образы, версии пакетов, uid процессов (сам поднимает профильные сервисы), durability → environment.txt
```
**Версии и стенд:** Python 3.14.7 в образе `python:3.14-slim-trixie@sha256:51dafde8…`,
`postgres:17.11-alpine@sha256:266d3c25…`, `valkey/valkey:8.1.11-alpine@sha256:2602ace2…`, uv 0.9.7 по digest, Docker 28.3.2, Compose 2.38.2. Машина —
Apple M4 Max, 16 CPU, 48 ГБ RAM, macOS 15.1; VM Docker Desktop — 16 CPU, 7.65 ГиБ. Полный список —
`evidence/environment.txt`.
## Архитектура и решения ## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. ```
┌──redis.asyncio, 0.2 с──▶ valkey (кэш сессий, AOF, volume valkeydata)
клиент ──HTTP──▶ api (gunicorn, 4 × UvicornWorker)
└──asyncpg pool, 1–2 с──▶ postgres (источник истины, volume pgdata)
migrate (тот же образ, одноразово до старта api) ──▶ postgres
api-shortttl (профиль faults, SESSION_TTL_SECONDS=2) ──▶ те же postgres и valkey
```
**Перенесено из лабы 1:** две доменные зоны `identity` и `messaging`, порты и адаптеры, UoW, шина событий
с журналом аудита, единый ASGI-конвейер (`X-Request-Id` → предел тела → таймаут, внутри которого
аутентификация и обработчик → журнал), курсор с HMAC, pydantic-схемы на границе, structlog за портом
`Logger`, non-root образ. **Изменено после ревью** (change `2026-10-28-harden-lab2-after-review`): предел
тела 1 MiB считает фактически принятые байты, поэтому и `chunked`-тело больше предела получает `413`.
**Изменено после второго ревью** (change `2026-10-28-harden-lab2-second-review`): выход при сбое PostgreSQL
снимает отметку отзыва (см. «Инвалидация»); пустой `cursor=` даёт `400`; воркер uvicorn ждёт принятые
запросы 7 с, мастер gunicorn ждёт воркеры 8 с (`SHUTDOWN_TIMEOUT_SECONDS`), Docker ждёт 10 с
(`stop_grace_period`). В `evidence/sigterm.txt` два запроса в работе: тот, чьё тело дописано через 1 с
после `SIGTERM`, получает `201`. Тот, чьё тело не приходит, воркер сам отменяет через 7.2 с (клиент получает
`500`) и выходит штатно; контейнер останавливается за 7.68 с с кодом 0. Когда сроки воркера и мастера были
равны, мастер успевал убить такой воркер раньше. **Удалено:**
адаптеры в память, реестр участников с проекцией, слоёный конвейер и режимы блокировки — инструменты
эксперимента лабы 1, которым в PostgreSQL не с чем сравниваться.
**Источник истины** — PostgreSQL для всего: пользователей, сессий, чатов, участников и сообщений. API не
держит состояния между запросами, поэтому воркеров несколько. Valkey — только кэш сессий: его потеря не
теряет данных и не открывает доступ.
**Схема и ограничения** (`src/messenger/migrations/0001_init.sql`, вывод `\d+` — `evidence/schema.txt`):
| Таблица | Ключи и ограничения | Индексы и зачем |
| --- | --- | --- |
| `users` | PK `id`; `UNIQUE (username)`; `CHECK` формата `username`, длины `display_name`, префикса `$argon2id$` у хеша | `users_username_key` — вход по username и уникальность |
| `sessions` | PK `token_hash` (32 байта SHA-256); FK `user_id → users`; `CHECK expires_at > created_at` | `sessions_user_idx` — удаление истёкших при входе |
| `chats` | PK `id`; `CHECK` длины `title`; `last_message_at` — отметка последнего сообщения | — |
| `chat_members` | PK `(chat_id, user_id)`; FK `chat_id → chats`, `user_id → users`; `position` — порядок `member_ids` | `(user_id, chat_created_at, chat_id)` — keyset-список чатов одним индексом |
| `messages` | PK `id`; FK `(chat_id, sender_id) → chat_members`; `CHECK` длины `text` | `(chat_id, created_at, id)` — keyset-история без сортировки |
Составной FK `messages → chat_members` держит на уровне БД правило «пишет только участник»: вставка от
постороннего отклоняется даже в обход API (тест `test_sender_must_be_member_even_bypassing_api`).
**Границы транзакций.** Регистрация — один `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`: при
гонке ровно один успешен, остальные получают `409`. Вход — один оператор, удаляющий истёкшие сессии
пользователя и вставляющий новую. Создание чата — `INSERT chats` и `INSERT chat_members` из
`unnest(…) WITH ORDINALITY` в одной транзакции UoW: несуществующий участник даёт нарушение FK, транзакция
откатывается целиком, ответ `400`. Сообщение — `SELECT … FOR UPDATE` строки чата с условием членства
отправителя (посторонний сразу получает `404` и не встаёт в очередь за участниками, тест
`test_outsider_does_not_wait_for_members_lock`), затем одним оператором `INSERT messages` и
`UPDATE chats.last_message_at`. Чтения — по одному оператору без явной транзакции.
UoW фиксирует только явно, откат — по умолчанию.
**Порядок истории при нескольких процессах.** Монотонные часы процесса лабы 1 при четырёх воркерах ничего
не гарантируют. Агрегат `Chat` хранит `last_message_at` и назначает `created_at = max(now, last + 1 мкс)`
под блокировкой строки чата. Порядок фиксации поэтому совпадает с порядком `(created_at, id)`, и
keyset-читатель не пропускает сообщение, зафиксированное позже с меньшей отметкой. Цена — запись в один
горячий чат сериализуется; разные чаты не мешают друг другу. Идентификаторы — UUIDv7.
**Зоны и общая БД.** Проекция участников заменена внешним ключом `chat_members.user_id → users`: проверку
«участник существует» делает СУБД внутри той же транзакции. Зоны не вызывают и не импортируют друг друга,
SQL зоны `messaging` не читает `users` и `sessions`, зона `identity` не читает таблиц чатов — это проверяет
тест границ по импортам и по текстам SQL; требование `lab1-event-publication` «Доменные зоны не вызывают
друг друга; общая точка — схема БД» заменило прежнее «связаны только событиями». Цена: схемы зон сцеплены,
`identity` нельзя вынести в отдельную БД или сервис, не вернув проекцию участников с outbox; FK при создании
чата берёт `FOR KEY SHARE` на строках `users`; любое нарушение FK в `INSERT chat_members` обезличенно
становится «неизвестный участник» (`400`). Триггер пересмотра — отдельная БД для зоны `identity`.
**Пароли и сессии.** Argon2id `m=19 MiB, t=2, p=1` (минимум OWASP) в пуле потоков под семафором
(2 на воркер), чтобы не блокировать event loop и ограничить память при всплеске регистраций. Для
неизвестного username выполняется проверка против фиктивного хеша — время не выдаёт существование
пользователя. Токен — `secrets.token_urlsafe(32)` (43 символа, 256 бит); в БД лежит только его SHA-256.
Пароль хешируется медленно, потому что у него мало энтропии и перебор надо удорожать; у токена энтропия
полная, быстрого хеша достаточно, а утечка таблицы `sessions` не даёт действующих токенов. Срок
абсолютный: `expires_at = вход + SESSION_TTL_SECONDS`, проверка по часам приложения, рестарт его не
продлевает. Выход — удаление строки.
**Аутентификация в конвейере.** Страж зоны `identity` работает в ASGI-конвейере до FastAPI, поэтому `401`
приходит раньше `404` и `400`, даже при битом JSON. `Basic` разбирается своим строгим парсером (base64 с
`validate=True`, первое `:`, UTF-8, ASCII-username) только на `POST /api/v1/auth/sessions`; остальные
`/api/v1/*` принимают только `Bearer`. `WWW-Authenticate` выбирается по пути: `Basic realm="messenger",
charset="UTF-8"` на входе и `Bearer realm="messenger"` везде, включая `Basic` на бизнес-endpoint.
`X-User-Id` не читается нигде. Отказ БД при проверке сессии — `503 unavailable`, не `401`.
**Пул и таймауты.** asyncpg-пул ленивый (`min_size=0`, `max_size=8` на воркер; 4×8 < `max_connections`),
подключение 1 с, ожидание соединения из пула 1 с, команда 2 с на клиенте и `statement_timeout`,
`lock_timeout` 2 с на сервере. Сетевые ошибки и отказ сервера превращаются в `503`. Готовность
`/health/ready` выполняет `SELECT 1` через тот же пул; `/health/live` от БД не зависит.
**Роль Valkey: read-through кэш сессий.** Адаптер `CachedSessionDirectory` оборачивает справочник сессий
PostgreSQL за тем же портом чтения `SessionDirectory` и реализует отдельный порт `SessionRevocations` для
отзыва (без кэша — пустой `NoRevocations`) — домен и обработчики о кэше не знают.
- *Что лежит:* ключ `session:<sha256 токена>`, значение — `user_id` и сроки сессии. Токена в кэше нет.
- *Чтение:* `GET`; промах → `SELECT` в PostgreSQL → `SET … NX PXAT`. Повторные проверки одного токена
обслуживает Valkey (`keyspace_hits` растёт, `evidence/cache.txt`, `evidence/faults.txt`).
- *Expiry:* `PXAT` — абсолютное время, `min(expires_at, сейчас + SESSION_CACHE_TTL_SECONDS)`; повторное
заполнение не продлевает сессию, ключ не переживает сессию (`pexpiretime` ≤ `expires_at` в
`evidence/cache.txt`). Потолок 300 с — страховка от ошибки инвалидации.
- *Инвалидация:* выход сначала пишет отметку отзыва `SET key "-" PXAT expires_at`, затем удаляет строку в
БД. Заполнение идёт только с `NX`, поэтому читатель, достававший сессию из БД в момент выхода, не
перетрёт отметку и не оживит токен (тест `test_fill_racing_with_logout_does_not_revive_token`). Если
отметку записать нельзя, выход отвечает `503` и сессию не трогает: иначе после возвращения Valkey из AOF
ожила бы закэшированная запись. Если отметка записана, а удаление или `COMMIT` в PostgreSQL упали,
отметка снимается (`DEL`, через тот же размыкатель) и выход отвечает `503`. Значит, `503` всегда означает
«ничего не изменилось»: токен работает, повтор после возвращения БД даёт `204` (тест
`test_logout_rejected_by_database_changes_nothing`). До исправления отметка оставалась: повтор отвечал
`401`, а после вытеснения отметки или `FLUSHALL` токен оживал. Остаток без двухфазной фиксации: при
неоднозначном `COMMIT` строка уже удалена, и если в то же окно чтение успеет заполнить кэш, токен
проживёт в кэше до 300 с. Клиент же получил `503` и повторит выход.
- *Недоступность:* таймаут 0.2 с, один повтор на новом соединении, размыкатель на 1 с. Проверка уходит в
PostgreSQL, неизвестный токен получает `401`; запрос никогда не становится анонимным. Готовность от
Valkey не зависит.
- *Persistence:* AOF `appendfsync always` на volume `valkeydata`: подтверждённая отметка отзыва уже на
диске, рестарт сохраняет тёплый кэш и отметки. `FLUSHALL` безвреден: источник истины — PostgreSQL.
`maxmemory 64mb` с `volatile-lru`: вытеснение любой записи безопасно по той же причине.
**Курсор** подписывается постоянным ключом из `secrets/cursor_secret`: страница, выданная одним воркером,
продолжается другим и после рестарта.
**Миграции.** `python -m messenger.migrate`: `pg_advisory_lock`, `schema_migrations(version, checksum,
applied_at)`, каждая версия — в своей транзакции, изменённая применённая миграция останавливает запуск.
Одноразовый сервис `migrate` стартует после `postgres: service_healthy`, `api` — после
`migrate: service_completed_successfully`. Применение к пустому volume и безопасный повтор —
`evidence/migrations.txt`.
**Инфраструктура** (`compose.yaml`, одна внутренняя сеть `backend`, наружу — только API на `127.0.0.1`):
| Роль | Сервис | Версия / digest | Health / readiness | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| api | `api` | образ `mtusi-messenger:${COMPOSE_PROJECT_NAME}` из `Dockerfile`, python по digest, uid 10001; `SIGTERM`: воркер ждёт 7 с, gunicorn 8 с, `stop_grace_period` 10 с | `GET /health/ready` (пингует БД), при старте раз в 200 мс | нет | `127.0.0.1:${API_PORT:-8080}:8080` | secrets `database_url`, `cache_url`, `cursor_secret` через `*_FILE` |
| postgres | `postgres` | `postgres:17.11-alpine@sha256:266d3c25…`, uid 70 | `pg_isready`, при старте раз в 200 мс (`start_interval`) | `pgdata:/var/lib/postgresql/data` | `backend`, порт не публикуется | secret `postgres_password` через `POSTGRES_PASSWORD_FILE` |
| cache | `valkey` | `valkey/valkey:8.1.11-alpine@sha256:2602ace2…`, uid 999 | `valkey-cli ping` с паролем | `valkeydata:/data` (AOF) | `backend`, порт не публикуется | secret `valkey.conf` (`requirepass`); API — secret `cache_url` |
| bootstrap | `migrate` | образ api | код выхода 0 | нет | `backend` | secret `database_url` |
| expiry-тест | `api-shortttl` (профиль `faults`) | образ api, `SESSION_TTL_SECONDS=2`, 1 воркер | как у api | нет | `127.0.0.1:${SHORTTTL_PORT:-8082}:8080` | как у api |
Критичная зависимость готовности — только PostgreSQL. Bootstrap: `make secrets` (идемпотентно), `make up`
(миграции применяет `migrate`), повтор обеих команд безопасен.
**Соответствие `.env.example` реальной конфигурации:**
| `.env.example` | В решении | Комментарий |
| --- | --- | --- |
| `APP_HOST`, `APP_PORT` | `HOST`, `PORT` | заданы в образе (`0.0.0.0:8080`); порт хоста — `API_PORT` |
| `APP_ENV` | не используется | режимов окружения нет |
| `SESSION_TTL_SECONDS` | `SESSION_TTL_SECONDS` | по умолчанию 3600 |
| `DATABASE_URL_FILE` | `DATABASE_URL_FILE` | любой параметр читается из `<ИМЯ>_FILE` |
| `SESSION_STORE=postgres` | фиксировано | PostgreSQL — источник истины сессий, Valkey — кэш поверх него |
| `CACHE_URL_FILE` | `CACHE_URL_FILE` | без него кэш выключен и всё работает как на уровне «3» |
| — | `CURSOR_SECRET_FILE`, `WEB_CONCURRENCY`, `API_PORT`, `SHORTTTL_PORT` | ключ курсора, число воркеров, порты хоста |
| — | `SESSION_CACHE_TTL_SECONDS`, `CACHE_TIMEOUT_SECONDS`, `CACHE_COOLDOWN_SECONDS` | потолок срока ключа 300 с, таймаут 0.2 с, размыкатель 1 с |
| — | `DB_POOL_MAX_SIZE`, `DB_*_TIMEOUT_SECONDS`, `PASSWORD_HASH_CONCURRENCY` | пул 8, подключение и `acquire` 1 с, команда 2 с, Argon2 по 2 |
## Доказательства критериев ## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO | | Публичный smoke | `make test` (в `make toolchain-evidence`) | `PASS: lab2 public API scenario` | `evidence/checks.txt` |
| Остальные пункты уровня 3 | TODO | TODO | TODO | | Офлайн-проверки и тулчейн | `make check`, `make validate` (после `make install`), `make lint` | `PASS: offline skeleton structure…`, `PASS: full OpenAPI 3.1 and JSON Schema validation`, ruff и ty — `All checks passed!` | `evidence/checks.txt` |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | | Persistence: данные и действующие сессии переживают рестарт API и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (обёртка `make persistence-evidence`) | `PASS: persistence preserved confirmed data and existing session`; `StartedAt` у `postgres`, `valkey` и `api` после теста новее, чем до | `evidence/persistence.txt` |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO | | Persistence + logout после полного рестарта | `make test-faults` (`test_full_restart_keeps_session_until_logout`) | после `scripts/restart.sh` прежний токен `200`, выход `204`, затем `401` | `evidence/faults.txt` |
| **«3»** Минимум lab1 сохранён с переходом на новую аутентификацию | `make student-test PYTEST_ARGS=-v` | 221 тест `PASSED` по именам (в процессе против одноразовых PostgreSQL и Valkey), включая перенесённые проверки ошибок, членства, пагинации и конкурентной записи; ещё 13 тестов стенда — `make test-faults` | `evidence/student-tests.txt` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. | **«3»** Keyset-курсор: чужой, испорченный и пустой отклоняются | `make student-test PYTEST_ARGS="-v -k cursor"` | 17 `PASSED`: курсор другого чата → `400`; `garbage`, `1.2.3.4`, `%20` и пустой `cursor=` → `400 invalid_request` и в истории, и в списке чатов (до второго ревью пустой давал первую страницу `200`) | `evidence/student-tests.txt` |
| **«3»** PostgreSQL: пользователи, чаты, участники, сообщения; PK/FK/UNIQUE | `make storage-evidence` (`\d+` по таблицам) | `users_username_key UNIQUE`, FK `chat_members → users, chats`, `messages → chat_members` | `evidence/schema.txt` |
| **«3»** Миграции с нуля и повторный запуск без дублей | `make migrations-evidence`: `make reset-data && make up`, `docker compose logs migrate`, `make test`, `make migrate` | на пустом volume `migration.applied 0001_init`, 0 строк во всех таблицах и одна версия в `schema_migrations`; после `make test` повтор — `up to date`, счётчики 3/2/1/2/2 до и после равны | `evidence/migrations.txt` |
| **«3»** Составная операция создания чата атомарна | `make student-test PYTEST_ARGS="-v -k rolls_back"` | `test_failed_chat_creation_rolls_back_both_tables PASSED`: неизвестный участник → `400`, строк в `chats` и `chat_members` не появилось | `evidence/student-tests.txt` |
| **«3»** Basic только на `POST /auth/sessions`, остальное — Bearer | `make student-test PYTEST_ARGS="-v -k 'sessions or bearer'"` | 34 `PASSED`, в том числе `Basic` на `/users/me` → `401 Bearer realm="messenger"`, без `Basic` на входе → `401 Basic …` | `evidence/student-tests.txt` |
| **«3»** Срок жизни сессии и отзыв | `make student-test PYTEST_ARGS="-v -k 'expire or logout'"` | 6 `PASSED`: TTL 1 с → `401`; `DELETE /auth/sessions/current` → `204`, затем `401`, повтор → `401`, вторая сессия жива; удаление в БД упало → `503`, токен `200`, отметки в Valkey нет, повтор → `204` | `evidence/student-tests.txt` |
| **«3»** `X-User-Id` не даёт доступ | `make test`; `make student-test PYTEST_ARGS="-v -k user_id"` | один `X-User-Id` → `401`; `Bearer` alice + `X-User-Id` eve → alice (2 `PASSED`) | `evidence/checks.txt`, `evidence/student-tests.txt` |
| **«3»** Доступ к чату — по членству, отдельно от аутентификации | `make test`; `make student-test PYTEST_ARGS="-v -k outsider"` | посторонний с действующим токеном получает `404`, как на несуществующий чат; запись постороннего не ждёт блокировки чата участником (`404` быстрее 0.5 с) | `evidence/checks.txt`, `evidence/student-tests.txt` |
| **«3»** Пароли хешируются password KDF | `make storage-evidence` | у всех строк `users` префикс `$argon2id$v=19$m=19456,t=2,p=1$`; у 34 настоящих хешей длина 97 символов. Отдельной строкой (`seed_stub = t`) показан синтетический `seed_author` из `make seed` с заглушкой в 44 символа: войти им нельзя, он нужен только для `make explain`. В `sessions` только 32-байтовые SHA-256 | `evidence/kdf.txt` |
| **«3»** Secrets и volumes не в Git | `git ls-files secrets .env`; `git check-ignore -v …`; `docker volume ls --filter label=com.docker.compose.project=…` | пусто; пути игнорируются правилами `.gitignore`; volumes `pgdata`, `valkeydata`, `pgrestore` только у Docker | `evidence/secrets.txt` |
| Непривилегированные процессы | `make environment-evidence` (сам поднимает `api-shortttl` и `postgres-restore`, затем `docker compose top` без процессов healthcheck) | api и api-shortttl — uid 10001, postgres и postgres-restore — uid 70, valkey — uid 999 | `evidence/environment.txt` |
| Остановка по `SIGTERM` ≤10 с | `make sigterm-evidence` (два `POST /messages` с недописанным телом в момент сигнала) | дописанный через 1 с после `SIGTERM` → `201 Created` через 1.15 с; недописанный воркер сам отменяет → `500` через 7.24 с (`Cancel 1 running task(s)` в журнале); остановка за 7.68 с, код 0, при `stop_grace_period` 10 с | `evidence/sigterm.txt` |
| Предел тела, в том числе `chunked` | `make student-test PYTEST_ARGS="-v -k 'body_limit or chunked'"` | `Content-Length` больше предела и `chunked`-тело больше предела → `413 payload_too_large`; `chunked` в пределах → `201` | `evidence/student-tests.txt` |
| **«4»** Valkey реально используется: роль, источник истины | `make test-faults` (`test_valkey_serves_repeated_checks`); `make cache-evidence` | 5 проверок токена → `keyspace_hits` 4 → 9; 4 ключа вида `session:<sha256>…`, из них 1 отметка отзыва | `evidence/faults.txt`, `evidence/cache.txt` |
| **«4»** Политика expiry и инвалидации | `make student-test PYTEST_ARGS="-v -k cache"`; `make cache-evidence` | для сессии из БД `pexpiretime` ключа ≤ `expires_at` («ключ не переживает сессию: да»); выход оставляет отметку `"-"`; гонка заполнения после выхода не оживляет токен; сбой БД при выходе снимает отметку; при недоступном Valkey чат и сообщение создаются (6 `PASSED`) | `evidence/student-tests.txt`, `evidence/cache.txt` |
| **«4»** Persistence кэша выдерживает рестарт; FLUSHALL | `make test-faults` (restart, flushall); `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | после рестарта Valkey ключей 14 → 14, живой токен 200, отозванный 401; после `FLUSHALL` то же | `evidence/faults.txt`, `evidence/persistence.txt` |
| **«4»** Параметризованные запросы | код адаптеров `*/infrastructure/postgres.py` | все значения передаются как `$1…$n`, SQL — константы модуля | `src/messenger/*/infrastructure/postgres.py` |
| **«4»** Ограниченный пул и таймауты | `make student-test PYTEST_ARGS="-v -k pool"` | 2 `PASSED`: пул из 1 занятого соединения → `503` за 0.3 с ожидания; на соединении `statement_timeout = lock_timeout` равны таймауту команды (в тесте задано 1.5 с, в стенде — 2 с) | `evidence/student-tests.txt` |
| **«4»** Гонка регистрации одного username | `make test-faults` (`test_registration_race_yields_exactly_one_user`) | 50 параллельных `POST /users` → 201×1, 409×49, в `users` одна строка | `evidence/faults.txt` |
| **«4»** Rollback составной операции | `make test-faults` (`test_chat_creation_rolls_back_on_unknown_member`) | `400 invalid_request`; в `chats` и `chat_members` ноль строк | `evidence/faults.txt` |
| **«4»** Индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 | `make explain` | 20 000 сообщений в чате, 30 005 всего; keyset-страница после 10 000-го — `Index Scan using messages_history_idx`, 51 строка, 4 буфера; `OFFSET 10000` — 10 051 строка, 247 буферов; без индекса — `Seq Scan` всех 30 005 строк + сортировка, 505 буферов | `evidence/explain-history.txt` |
| **«4»** Автотест expiry при коротком TTL | `make test-faults` (`test_short_ttl_session_expires`, `test_short_ttl_expires_after_restart_at_original_time`) | сразу `200`, через 3 с `401 Bearer realm="messenger"`; после рестарта `api-shortttl` токен всё равно `401` после исходного `expires_at` | `evidence/faults.txt` |
| **«4»** Автотест logout | `make test-faults` (`test_logout_then_token_is_dead`) | `204` без тела, затем `401`, повтор `401` | `evidence/faults.txt` |
| **«4»** Автотест неверного пароля | `make test-faults` | неверный пароль и неизвестный username — одинаковый `401 Basic realm="messenger", charset="UTF-8"`, 0.012 с и 0.011 с | `evidence/faults.txt` |
| **«4»** Недоступность Valkey: обход кэша, без анонимного доступа | `make test-faults` (`test_valkey_stopped_is_bypassed_but_logout_waits`) | действующий токен `200` за 0.207 с, неизвестный `401`, ready `200`, вход `201`, выход `503`, после старта — `204` | `evidence/faults.txt` |
| **«4»** Недоступность PostgreSQL: ограниченная ошибка | `make test-faults` (`test_postgres_stopped_gives_bounded_503_and_recovers`) | ready, me, неизвестный токен, вход, регистрация — `503` за 0.992–1.012 с; live `200`; после `healthy` PostgreSQL готовность `200` без рестарта API | `evidence/faults.txt` |
| **«5» трек 2** ≥100 000 сообщений с неравномерными чатами | `make track-bench` | база `track`: 999 993 сообщения в 1 000 чатах по Ципфу `s = 1.3`; крупнейший чат 284 708 (28.5 %), 50-й — 1 761, мельчайший — 36 | `evidence/track/bench.json`, `evidence/track/summary.txt` |
| **«5» трек 2** Сравнение ≥2 индексов и запросов, EXPLAIN (ANALYZE, BUFFERS) | `make track-bench` | 4 набора индексов × 3 чата × {первая, keyset 90 %, OFFSET 90 %} × {тёплый, холодный}, все запуски — custom-план; составной индекс + keyset — 0.012–0.024 мс и 4–6 буферов везде; `(chat_id)` — 12.2 мс и сортировка 284 709 строк на крупнейшем; `(created_at, id)` — 14.7 мс на мельчайшем: планировщик выбирает параллельный `Seq Scan` всей таблицы (25 704 буфера, 999 993 строки); `OFFSET` 90 % крупнейшего — 20–63 мс при любом индексе | `evidence/track/summary.txt`, `evidence/track/plans.txt` |
| **«5» трек 2** Custom против generic плана | `make track-bench` | при `(created_at, id)` generic-план для мельчайшего чата 156.5 мс против 14.9 мс custom (≈10 раз); при `(chat_id)` на крупнейшем 28.1 против 13.0 мс; при составном индексе планы совпадают (0.015–0.023 мс) | `evidence/track/summary.txt` |
| **«5» трек 2** Стоимость записи | `make track-bench` (pgbench, 5 × 10 с на режим, `docker stats` в середине прогона, `pg_stat_wal`, контрольный повтор без индексов A-B-C-D-A) | индекс истории 56.2 МБ против 6.8 МБ у `(chat_id)`; каждый индекс — +1 запись WAL на вставку (6.03–6.06 → 7.03–7.06), +75–105 байт у одноколоночного и +133–161 у составного при `sync`; TPS ниже на 0.4–3.6 % при дрейфе первый/контрольный 1.0–1.2 %, то есть на уровне шума; postgres 266–359 % CPU, 183–190 МиБ | `evidence/track/bench.json`, `evidence/track/summary.txt` |
| **«5» трек 2** Backup → новое хранилище → сверка | `make track-recovery` (3 повтора на размер) | `pg_dump -Fc` 14.7 МБ за 1.04 с; каждый раз новый `postgres-restore` с новым volume; `pg_restore` 0.16 + 2.16 + 0.91 с (медианы); 13 из 13 проверок совпали во всех 6 восстановлениях (счётчики, `md5` по чатам и истории, выборка ≈0.1 % строк — 90 и 1 005, миграции, индексы, ограничения) | `evidence/track/recovery.json` |
| **«5» трек 2** RTO и RPO | `make track-recovery` для 100 011 и 999 993 сообщений | RTO — медиана 2.17 с (2.17..2.26) и 5.32 с (5.31..5.35), из них новый экземпляр 1.26–1.30 с; 46–48 маркеров, записанных во время дампа 1M после его снимка, в копии отсутствуют — потеря равна всему, что после снимка | `evidence/track/recovery.json` |
| Нагрузка с конкуренцией 64 | `make load-evidence` (3 × `tests/load.py --duration 8 --concurrency 64`, снимки `pg_stat_activity`) | медиана 1 676 RPS (1 619..1 711), p50/p95/p99 = 30/87/112 мс, 0 ошибок; на сервере 0×5xx; 81–86 % занятых соединений PostgreSQL ждут блокировку строки чата (`Lock:tuple`, `Lock:transactionid`); CPU api ≈1.6 ядра, postgres ≈1.5 | `evidence/load.txt`, `evidence/load-c64-{1,2,3}.json` |
## Эксперименты и отказы ## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| TODO | TODO | TODO | TODO | | Рестарт всего стека hook-ом `scripts/restart.sh` (api, postgres, valkey) | прежний токен работает, история побайтно та же; после logout — `401` | persistence-тест `PASS`, `StartedAt` всех трёх обновился; `test_full_restart_keeps_session_until_logout`: токен `200`, выход `204`, затем `401` | API стартует через ≈1.6 с после хранилищ (healthy с опросом раз в 200 мс + `migrate`; до `start_interval` первая проверка ждала 5 с, и выходило ≈6 с); потерь нет |
| Рестарт только API (`docker compose restart api`) | данные и сессии на месте, `expires_at` не меняется | `test_api_restart_keeps_session_without_extending_it`: токен `200`, `expires_at` в БД побайтно равен выданному при входе | готовность через ≈0.5 с; потерь нет |
| Рестарт `api-shortttl` (TTL 2 с) до истечения сессии | рестарт не продлевает срок | после исходного `expires_at` токен `401 Bearer` | готовность через ≈0.5 с |
| `SIGTERM` в контейнер API с двумя запросами в работе | принятый запрос дорабатывается, зависший прерывает сам сервер, остановка ≤10 с, код 0 | дописанный запрос `201` через 1.15 с; недописанный воркер отменил через 7.24 с (`500`); остановка за 7.68 с, код 0 | `docker compose up -d --wait api` |
| `docker compose stop postgres` | live `200`, ready и защищённые `503` быстрее 2 с, без `500` | `503` за 0.99–1.01 с (таймаут подключения и `acquire` 1 с), live `200` за 0.004 с | после `healthy` PostgreSQL готовность `200` сразу, тот же процесс API; подтверждённые данные целы |
| `docker compose stop valkey` | проверка уходит в PostgreSQL, никакого анонимного доступа | действующий токен `200` за 0.207 с, неизвестный `401`, ready `200`, вход `201`, выход `503`. Время зависит от соединения в пуле воркера: на свежем соединении имя остановленного контейнера не резолвится и отказ мгновенный (0.007 с в отдельном прогоне), на зависшем — таймаут 0.2 с и один повтор (до 0.41 с); дальше размыкатель на 1 с | после `start` выход снова `204`; потерь нет |
| `docker compose restart valkey` | кэш и отметки отзыва сохраняются (AOF) | ключей 14 → 14, живой `200`, отозванный `401` | секунды; потерь нет |
| `FLUSHALL` в Valkey | сессии не теряются, отозванные не оживают | живой `200`, отозванный `401`, кэш заполняется заново | мгновенно; потерь нет |
| Истечение TTL (`api-shortttl`, 2 с) | `401` после `expires_at` | сразу `200`, через 3 с `401 Bearer` | — |
| Logout | `204`, затем `401`, повтор `401` | так и есть; в Valkey отметка `-` | — |
| Сбой PostgreSQL посреди выхода: отметка записана, `DELETE` сессии падает | `503`, сессия цела и в БД, и для кэша | `503 unavailable`, ключа в Valkey нет, токен `200`, повтор `204`, затем `401` (до исправления: повтор `401`, а после `FLUSHALL` токен снова `200`) | сразу после возвращения БД |
| Посторонний пишет в чужой чат, пока участник держит блокировку строки чата | `404` сразу | `404` быстрее 0.5 с (до исправления — `503` через `lock_timeout` 2 с) | — |
| `chunked`-тело больше 1 MiB | `413`, тело не дочитывается | `413 payload_too_large` (до исправления тело читалось целиком и давало `400`) | — |
| 50 параллельных регистраций одного username | ровно один `201` | 201×1, 409×49, одна строка | — |
| Чат с несуществующим участником | `400`, откат транзакции | `400`, ноль строк в `chats` и `chat_members` | — |
| Пул исчерпан | `503` за время `acquire`, без зависания | `503` за 0.3 с, затем `200` | мгновенно после освобождения |
| Повторный `migrate` | схема и данные не меняются | `up to date`, счётчики строк равны | мгновенно |
| Потеря базы: backup → восстановление в новый `postgres-restore` (трек 2) | все данные снимка на месте, всё после снимка потеряно | 13/13 проверок совпали в 6 восстановлениях; 46–48 маркеров после снимка отсутствуют | RTO 5.32 с (5.31..5.35) для 1M сообщений, 2.17 с для 100k; RPO — момент снимка `pg_dump` |
### Нагрузка HTTP
*Гипотеза:* запись в один горячий чат упирается в блокировку строки чата, а не в пул (4 × 8 соединений) и
не в Argon2. Поэтому при 64 конкурентных клиентах большая часть занятых соединений PostgreSQL ждёт блокировку
строки, ошибок и `503` нет, а p99 остаётся в пределах 0.2 с.
*Методика* (`make load-evidence`): закрытый контур `tests/load.py`, 64 потока, 8 с, все записи прогона в
один чат (одна строка `chats` под `FOR UPDATE`), 3 повтора с паузой 40 с, клиент на хосте macOS, стенд —
VM Docker Desktop 16 CPU / 7.65 ГиБ, 4 воркера API × пул 8. Прогрева нет: в окно попадают и регистрация
пользователей, и создание чата из `tests/load.py`. На 4-й секунде снимаются `docker stats` и 20 снимков
`pg_stat_activity` через 0.1 с: состояние и `wait_event` всех непростаивающих соединений базы `messenger`.
Статусы ответов берутся из журнала `request.handled`. Других compose-стендов на VM во время прогона не было
(строка в заголовке `evidence/load.txt`).
*Результат:* медиана 1 676 RPS (1 619..1 711), p50/p95/p99 = 30/87/112 мс, 0 ошибок из 40 696 запросов; на
сервере только `201` и `200`, ни одного `5xx`. В среднем заняты 14.5–17.4 соединения PostgreSQL из 32, и
81–86 % из них ждут блокировку строки: `Lock:tuple` (очередь за `FOR UPDATE`) и `Lock:transactionid`
(ожидание транзакции-держателя). На CPU в момент снимка — 0.5–0.7 соединения, на `fsync` WAL — до 0.3.
CPU: api 162–165 %, postgres 138–157 %, valkey ≈5 %; память: api 254–280 МиБ, postgres 135–144 МиБ.
Гипотеза подтверждена: ни CPU (16 ядер), ни пул не насыщены, очередь стоит на строке чата.
Разброс трёх прогонов серии — 5.5 %. Между сериями абсолютный RPS плавает сильнее: прошлая серия дала
1 724, повтор ревьюера при работающем рядом стенде лабы 3 — 1 639. Поэтому выводы опираются на
отсутствие ошибок, p99 и долю ожиданий, а не на RPS. Прогон длиннее 8 с упирается в эфемерные порты macOS:
клиент открывает новое соединение на каждый запрос (`TIME_WAIT` ≈14 000), поэтому между повторами пауза.
Это пропускная способность HTTP-подтверждений одного горячего чата, а не предел системы.
### Трек 5 — трек 2 «План запроса и восстановление»
**Гипотезы.** H1: составной индекс `(chat_id, created_at, id)` с keyset-курсором даёт время страницы,
не зависящее ни от размера чата, ни от глубины страницы; `(chat_id)` проигрывает на большом чате (надо
отсортировать весь чат), `(created_at, id)` — на маленьком (надо пройти чужие сообщения), а `OFFSET`
проигрывает на глубине при любом индексе. H2: каждый индекс истории добавляет к вставке измеримую долю
WAL и времени; составной индекс дороже `(chat_id)` на ширину ключа. H3: `pg_dump -Fc` + `pg_restore -j`
поднимает миллион сообщений в новом хранилище за секунды, заметная доля уходит на перестройку индексов,
а граница потери данных — момент снимка дампа.
**Методика** (`scripts/track.py`, `scripts/sql/track-*.sql`, одна команда на часть):
- Стенд: Apple M4 Max, VM Docker Desktop 16 CPU / 7.65 ГиБ, PostgreSQL 17.11 с настройками образа
(`shared_buffers = 128MB`, `fsync` и `synchronous_commit` включены). API в это время простаивает.
- Данные: отдельная база `track`, мигрированная тем же runner-ом (`python -m messenger.migrate track`) —
схема, ограничения и индекс те же, что у сервиса. 2 000 пользователей, 1 000 чатов по два участника,
`n_k = round(N · k^-1.3 / H)`, `N = 1 000 000` (фактически 999 993): крупнейший чат 284 708 (28.5 %),
топ-10 — 65 %, 50-й — 1 761, мельчайший — 36. Таблица `messages` — 200.8 МБ. Построение детерминировано.
- Чтение: подготовленные запросы приложения с `LIMIT 51`; первая страница, keyset-страница после 90 %
чата и та же страница через `OFFSET`; 5 тёплых запусков и 3 холодных (перед каждым все буферы базы
вытесняются `pg_buffercache_evict`), медиана. Все запуски матрицы идут с
`plan_cache_mode = force_custom_plan`: при `auto` шестое выполнение перешло бы на generic-план, и время,
форма плана и строки одной ячейки относились бы к разным планам. Форма плана и «строк просмотрено» берутся
из медианного запуска, `plans.txt` снят в том же режиме. «Строк просмотрено» — сумма по узлам `Scan` величины
`(Actual Rows + Rows Removed by Filter + Rows Removed by Index Recheck) × Actual Loops`: PostgreSQL отдаёт
обе величины как среднее на один цикл, и у параллельного узла их надо умножать на число процессов.
Generic-план меряется отдельно: для первой страницы — 5 запусков в `force_custom_plan` и в
`force_generic_plan`.
- Запись: `pgbench -c 4 -j 4`, 5 прогонов по 10 с на режим, транзакция приложения (`SELECT … FOR UPDATE`,
`INSERT messages` + `UPDATE chats`) в случайный из 1 000 чатов, UUIDv7; перед прогоном `CHECKPOINT`;
WAL — разница `pg_current_wal_lsn()` в байтах и разница `pg_stat_wal` в записях WAL и full page images
(FPI) на вставку. Режим `sync` — как в приложении, `async` — `synchronous_commit=off`, чтобы отделить
обслуживание индекса от ожидания fsync. В середине прогона — `docker stats` контейнера postgres (в нём и
сервер, и клиент pgbench). После прогона вставки удаляются. Наборы идут в фиксированном порядке, поэтому
после составного набора запись ещё раз меряется без индексов истории (порядок A-B-C-D-A): если цифры
повторного «без индексов» уходят от первого, это дрейф VM и рост PK, а не цена индекса.
- Восстановление: во время дампа в источник каждые 20 мс пишется маркер; `postgres-restore` (профиль
`track`) и его volume `pgrestore` удаляются и создаются заново, время нового экземпляра — `up --wait` до
`healthy`, при старте `pg_isready` опрашивается раз в 200 мс (`start_interval`), так что шаг опроса добавляет
не больше 0.2 с; `pg_restore` по секциям `pre-data`,
`data -j 4`, `post-data -j 4`; затем одинаковые проверочные запросы в обеих базах. Начало и конец дампа —
`clock_timestamp()` PostgreSQL-источника, теми же часами, что `created_at` маркеров, поэтому граница
«после снимка» не зависит от часов хоста. Каждый размер — 3 повтора, медиана и диапазон.
**Чтение, медиана тёплых запусков, мс** (в скобках — холодный; полная матрица с буферами и планами —
`evidence/track/summary.txt` и `plans.txt`):
| Индексы истории | Крупнейший: 1-я стр. | Крупнейший: keyset 90 % | Крупнейший: OFFSET 90 % | 50-й чат: 1-я стр. | Мельчайший: 1-я стр. | Мельчайший: keyset 90 % |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| нет (только PK) | 22.0 (19.8) | 17.6 | 61.3 | 14.5 | 14.4 | 16.2 |
| `(chat_id)` | 12.2 (16.5) | 8.3 | 55.8 | 0.19 | 0.024 | 0.016 |
| `(created_at, id)` | 0.035 (0.092) | 0.065 | 63.1 | 3.1 | 14.7 (14.5) | 6.6 |
| `(chat_id, created_at, id)` | **0.022** (0.036) | **0.024** | 20.0 (33.4) | **0.019** | **0.017** | **0.012** |
Буферы и строки холодного запуска. Составной индекс читает 4–6 буферов на любую keyset-страницу. Без индекса
читается вся таблица: 25 698–25 704 буфера, 999 993 строки. `(chat_id)` на крупнейшем чате читает 7 606 буферов
и сортирует 284 709 строк. `(created_at, id)` на мельчайшем чате тоже читает всю таблицу (25 704 буфера,
999 993 строки): зная по статистике, что чат маленький, custom-план выбирает параллельный `Seq Scan` с
сортировкой, а не проход по индексу времени. Keyset-страница того же чата идёт через bitmap-скан индекса
времени: 223 122 строки, 4 496 буферов. `OFFSET` 90 % по составному индексу читает 8 453 буфера и 256 288
строк, которые выбрасываются. Колонка «строк просмотрено» теперь считается по циклам (см. методику). В прошлой
версии отчёта она складывала среднее «Rows Removed by Filter» один раз, и параллельный `Seq Scan` всей
таблицы выглядел как 333 355–523 137 строк.
**Custom против generic плана** (asyncpg использует prepared statements, PostgreSQL после пяти выполнений
может перейти на generic-план):
| Индексы | Чат | custom, мс | generic, мс | Что меняется |
| --- | --- | ---: | ---: | --- |
| `(created_at, id)` | мельчайший | 14.9 (параллельный Seq Scan + Sort) | **156.5** (Index Scan по всему индексу времени) | generic-план не знает, что чат маленький |
| `(chat_id)` | крупнейший | 13.0 (параллельная сортировка) | 28.1 (последовательная) | generic теряет параллелизм |
| `(chat_id, created_at, id)` | крупнейший / мельчайший | 0.023 / 0.021 | 0.022 / 0.015 | план не зависит от параметра |
**Запись** (медиана 5 прогонов, в скобках — минимум..максимум; строки в порядке прогонов, последняя —
контрольный повтор без индексов истории):
| № | Индексы истории | Размер индекса, МБ | TPS `sync` | TPS `async` | Задержка `sync`, мс | WAL на вставку `sync` / `async`, байт | Записей WAL на вставку | FPI на вставку `sync` |
| ---: | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 1 | нет | — | 9 455 (9 314..9 502) | 12 681 (12 393..12 820) | 0.423 | 1 511 / 1 205 | 6.70 / 6.05 | 0.128 |
| 2 | `(chat_id)` | 6.8 | 9 233 (7 941..9 604) | 12 497 (10 743..12 721) | 0.433 | 1 588 / 1 303 | 7.06 / 7.04 | 0.135 |
| 3 | `(created_at, id)` | 38.7 | 9 180 (9 055..9 540) | 12 461 (12 429..12 626) | 0.436 | 1 586 / 1 304 | 7.04 / 7.04 | 0.132 |
| 4 | `(chat_id, created_at, id)` | 56.2 | 9 113 (8 821..9 448) | 12 444 (12 368..12 483) | 0.439 | 1 644 / 1 365 | 7.03 / 7.04 | 0.146 |
| 5 | нет (контроль) | — | 9 346 (9 279..9 601) | 12 551 (12 437..12 612) | 0.428 | 1 483 / 1 216 | 6.03 / 6.06 | 0.130 |
`(chat_id)` весит всего 6.8 МБ из-за дедупликации повторяющихся ключей в B-tree (PostgreSQL 13+); у
составного индекса ключи уникальны. Первичный ключ после первого набора прогонов pgbench растёт с 30.1 до
37.8 МБ: удалённые вставки оставляют пустые страницы, `VACUUM` их не возвращает. CPU postgres — 266–282 %
при `sync` и 306–359 % при `async`; память — 183–190 МиБ (один замер 282 МиБ в первом прогоне).
**Восстановление в новое хранилище:**
| Набор | 100 011 сообщений | 999 993 сообщения |
| --- | ---: | ---: |
| Размер `pg_dump -Fc` | 1.6 МБ | 14.7 МБ |
| Дамп | 0.15 с (0.15..0.15) | 1.04 с (1.03..1.05) |
| Новый экземпляр (пустой volume, initdb, `healthy` с опросом раз в 200 мс) | 1.26 с (1.26..1.30) | 1.27 с (1.27..1.27) |
| `pre-data` / `data -j 4` / `post-data -j 4` | 0.16 / 0.35 / 0.22 с | 0.16 / 2.16 / 0.91 с |
| Сверка | 0.19 с | 0.84 с |
| **RTO** (экземпляр + восстановление + сверка), медиана [мин..макс] | **2.17 с** [2.17..2.26] | **5.32 с** [5.31..5.35] |
| Проверки: счётчики 4 таблиц, `md5` «чат: число», `md5` истории 3 чатов, выборка, миграции, индексы, ограничения | 13 из 13 × 3 | 13 из 13 × 3 |
| Маркеры: в источнике / в копии / записаны во время дампа после снимка и потеряны (медиана) | 76 / 43 / 6 | 118 / 43 / 47 |
**Выводы.**
- H1 **подтверждена**. Составной индекс с keyset — единственный вариант, где страница стоит 0.012–0.024 мс
и 4–6 буферов и для чата из 36 сообщений, и для чата из 284 708, на любой глубине. `(chat_id)` хорош для
маленьких чатов и в ≈550 раз хуже на большом (12.2 против 0.022 мс); `(created_at, id)` — зеркально: хорош
на большом и в ≈860 раз хуже на маленьком (14.7 против 0.017 мс). Перекос размеров чатов делает оба
одноколоночных индекса непригодными: в одном сервисе есть и те и другие чаты. `OFFSET` на 90 % большого
чата стоит 20 мс даже с лучшим индексом — читает и выбрасывает 256 288 строк; keyset на той же глубине —
0.024 мс. Поэтому курсор приложения — keyset.
- Находка про prepared statements: с `(created_at, id)` generic-план для маленького чата в ≈10 раз
медленнее custom (156.5 против 14.9 мс). Приложение работает через asyncpg и после пяти выполнений могло
бы получить именно его. С составным индексом план от параметра не зависит (0.015–0.023 мс в обоих
режимах), и риска нет — ещё один довод за этот индекс.
- H2 **подтверждена для объёма и WAL; по времени эффект на уровне шума**. Размер: составной индекс — 56.2 МБ
против 6.8 МБ у `(chat_id)` и 38.7 МБ у `(created_at, id)`. WAL: каждый индекс истории добавляет ровно одну
запись WAL на вставку (6.03–6.06 без индекса → 7.03–7.06 с любым индексом, в обоих режимах) и 75–105 байт
у одноколоночного или 133–161 байт у составного при `sync`; при `async` — 87–99 и 149–160 байт. Диапазон
взят относительно первого и контрольного прогона без индексов. Составной дороже одноколоночных примерно на
60 байт: его ключ — 40 байт (`uuid`, `timestamptz`, `uuid`) против 16 и 24. Доля full page writes почти не
меняется: 0.128–0.146 FPI на вставку при `sync`. TPS с индексом падает на 0.4–3.6 %: при `sync` 9 455 → 9 113
у составного (−3.6 % к первому прогону, −2.5 % к контрольному). Это того же порядка, что дрейф между
первым и контрольным прогоном без индексов (−1.2 % и −1.0 %), и диапазоны пересекаются. Значит, направление
эффекта ожидаемое (составной самый медленный), но величину по TPS эта VM не различает. Прошлая серия без
контрольного повтора дала обратную картину: составной набор при `async` был на 20 % быстрее, чем без
индексов. Скорее всего, это был дрейф VM, и как раз его ловит повтор A-B-C-D-A. Ещё одна оговорка: первый прогон без
индексов дал 6.70 записей WAL при `sync` против 6.03 у контрольного, то есть состояние таблиц сразу после
построения базы тоже весит. Цену индекса показывают размер и WAL; на чтении он выигрывает 2–3 порядка.
- H3 **подтверждена**. Миллион сообщений поднимается в новом хранилище за 5.32 с (три повтора
5.31–5.35 с), 100 тысяч — за 2.17 с. Запуск пустого экземпляра (initdb, старт, первый успешный
`pg_isready`) занимает 1.27 с: 24 % RTO для миллиона и 58 % для 100 тысяч. Перестройка индексов и
ограничений (`post-data`) — 28 % времени `pg_restore` миллиона. От 100 тысяч к миллиону время данных выросло
в 6.2 раза, `post-data` — в 4.1 раза, запуск экземпляра не изменился. Прошлая версия отчёта давала RTO 9.75
и 6.68 с и «5.8 с на запуск экземпляра». Из этих 5.8 с около 4.5 с были не PostgreSQL, а ожиданием первой
проверки здоровья: без `start_interval` Docker ждёт 5 с до первого `pg_isready`. Теперь при старте проверка
идёт раз в 200 мс. RPO дампа — момент его снимка: 46–48 сообщений, подтверждённых во время работы
`pg_dump` после снимка, в копии отсутствуют, хотя дамп завершился позже них. Последний маркер копии
записан за 1–16 мс до начала дампа по часам источника.
- Решение по приложению: индекс `(chat_id, created_at, id)` и keyset-курсор остаются без изменений.
**Ограничения трека.** VM Docker Desktop шумит, поэтому сравниваются буферы, строки и порядки величин, а
абсолютные миллисекунды — только внутри одного прогона. «Холодный» кэш — это пустые `shared_buffers`;
кэш страниц ОС внутри VM не сбрасывается, реальное чтение с диска было бы медленнее. Для параллельных
планов «строк просмотрено» считается по циклам: `(Actual Rows + Rows Removed by Filter + Rows Removed by Index
Recheck) × Actual Loops`; строки, прочитанные и отброшенные внутри `Sort` или `Limit`, в ней не учтены.
Влияние индекса на TPS при записи (0.4–3.6 %) того же порядка, что дрейф между первым и контрольным прогоном
(1.0–1.2 %); наборы идут в фиксированном порядке, и один контрольный повтор не заменяет перемешивания.
Синтетический текст хорошо сжимается, поэтому дамп в 14 раз меньше таблицы; на реальных сообщениях он будет
больше и дольше. Восстанавливается синтетическая база `track`, а не рабочая `messenger`. `pg_dump -d track`
не переносит роли и прочие глобальные объекты кластера: восстановление работает, потому что роль
`messenger` в новом экземпляре создаёт `POSTGRES_USER`. Для настоящего кластера нужен ещё
`pg_dumpall --globals-only`. Восстановленная база сверялась SQL-запросами, а не через API. RTO измерено на
одной машине без переключения API на восстановленную базу: это ещё смена `DATABASE_URL`, рестарт API
(≈1.6 с до готовности по `evidence/persistence.txt`) и `make test`. Время экземпляра включает шаг опроса
`healthy` (до 0.2 с). Три повтора дают разброс 1–4 %, для доверительного интервала их мало. «Sync»-цифры записи сняты в VM Docker
Desktop, где `fsync` подтверждает запись в виртуальный диск; дошла ли она до носителя хоста, не проверялось.
`pg_dump` даёт RPO, равный интервалу между дампами; для RPO в секунды нужны `pg_basebackup` и архивирование
WAL с восстановлением на момент времени (PITR) — здесь это только обсуждается.
## Ответы на вопросы защиты
**Что подтверждает `COMMIT` и какие гарантии зависят от durability?** `COMMIT` возвращается, когда запись
транзакции в WAL сброшена на диск: при `synchronous_commit = on` сервер ждёт `fsync` (здесь
`wal_sync_method = fdatasync`) до ответа клиенту, поэтому подтверждённые `201` переживают падение процесса
и рестарт (`make test-persistence`). Настройки стенда — `fsync = on`, `synchronous_commit = on`,
`full_page_writes = on` (`evidence/environment.txt`). С `synchronous_commit = off` подтверждённые
транзакции последних ≈0.6 с (`3 × wal_writer_delay`) теряются при падении сервера, но база остаётся
согласованной; с `fsync = off` при сбое ОС база может разрушиться; без `full_page_writes` — разорванные
страницы после сбоя питания. Оговорка стенда: `fsync` в VM Docker Desktop подтверждает запись в
виртуальный диск, а дойдёт ли она до носителя (на macOS это `F_FULLFSYNC`), решает гипервизор — это не
проверялось. Коммит с `fsync` в треке стоит 0.42–0.44 мс против 0.32 мс без него, подозрительно дёшево для
честного сброса на SSD, поэтому «sync»-цифры трека — нижняя граница цены durability, а не её значение на
реальном сервере.
**Где хранятся сессии и что будет после flush/restart Valkey?** Источник истины — таблица `sessions` в
PostgreSQL (только SHA-256 токена). Valkey хранит read-through копию и отметки отзыва `"-"`. `FLUSHALL`
теряет только кэш: живой токен `200` (заполнение заново из БД), отозванный `401` (строки в БД уже нет).
Рестарт Valkey сохраняет ключи через AOF `appendfsync always` (14 → 14). Недоступный Valkey обходится,
выход в это время отвечает `503` (`evidence/faults.txt`).
**Чем аутентификация отличается от доступа к конкретному чату?** Аутентификация отвечает на вопрос «кто
это» — страж конвейера проверяет `Bearer`-сессию до маршрутизации и даёт `401` с `WWW-Authenticate`.
Доступ (авторизация) отвечает на вопрос «можно ли ему этот чат» — зона `messaging` проверяет членство в
`chat_members`: посторонний с действующим токеном получает `404`, неотличимый от несуществующего чата,
а не `403`, и не узнаёт, что чат есть (`test_outsider_*` в `evidence/student-tests.txt`, `make test`).
Запись постороннего не берёт блокировку строки чата и не ждёт участников.
**Почему hash пароля и быстрый checksum решают разные задачи?** Пароль выбирает человек, энтропии в нём
мало, поэтому хеш должен быть медленным и требовать памяти (Argon2id `m=19 MiB, t=2`), чтобы перебор по
утёкшей таблице стоил дорого. Токен сессии — 256 случайных бит, перебирать нечего, поэтому достаточно
быстрого SHA-256: он лишь не даёт превратить утечку `sessions` в действующие токены. Checksum миграции
(`schema_migrations.checksum`) — не защита от противника, а обнаружение изменения уже применённого файла.
## Ограничения и следующие шаги ## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. - Один Docker-host и один экземпляр PostgreSQL: потеря host или volume теряет всё после последнего дампа;
репликации нет, резервная копия снимается вручную (`make track-recovery` показывает процедуру и RTO).
- Истёкшие сессии удаляются только при следующем входе того же пользователя; фоновой очистки нет.
- Запись в один горячий чат сериализуется блокировкой строки чата — цена строгого порядка истории.
- Выход невозможен, пока недоступен Valkey (`503`): осознанная плата за то, что отзыв подтверждается только
когда он виден и в кэше. Проверка остальных запросов при этом продолжается через PostgreSQL.
- Нагрузка снята закрытым контуром `tests/load.py` с клиента на той же машине: согласованные пропуски,
новое TCP-соединение на запрос (поэтому прогон ограничен 8 с), все записи в один чат. Это пропускная
способность HTTP-подтверждений в одном горячем чате, а не предел системы.
- Секреты лежат файлами в `secrets/` на хосте (каталог `0700`, файлы `0644`, чтобы их читали
непривилегированные пользователи контейнеров); это учебное упрощение вместо менеджера секретов.
- Отзыв и PostgreSQL не связаны двухфазной фиксацией. Отказ БД при выходе снимает отметку в Valkey, но при
неоднозначном `COMMIT` (сервер зафиксировал, ответ потерян) возможна гонка: чтение заполнит кэш, и токен
проживёт в кэше до 300 с, хотя клиент получил `503` и повторит выход.
- Запрос, который при `SIGTERM` не дождался своего тела за 7 с, отменяет uvicorn. Клиенту уходит
встроенный текстовый `500 Internal Server Error`, а не JSON-ошибка контракта: приложение к этому моменту
уже отменено.
- Процесс openspec: правило `config.yaml` «proposal в пределах 400 слов» нарушено в архивных циклах.
Без разметки в `add-lab2-postgres-sessions` около 483 слов, в `harden-lab2-after-review` — около 409;
`wc -w` с разметкой даёт 522 и 433, а у `add-lab2-session-cache-and-resilience` — 427. Архив уже
закоммичен, а ЛР3 переносится с коммита `8cddb09`, поэтому историю не переписываю. В proposal цикла
`harden-lab2-second-review` 342 слова по `wc -w`.
+149
View File
@@ -0,0 +1,149 @@
x-app: &app
image: mtusi-messenger:${COMPOSE_PROJECT_NAME}
build: .
environment: &app-environment
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
CURSOR_SECRET_FILE: /run/secrets/cursor_secret
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
WEB_CONCURRENCY: ${WEB_CONCURRENCY:-4}
LOG_LEVEL: ${LOG_LEVEL:-INFO}
secrets: [database_url, cache_url, cursor_secret]
networks: [backend]
x-ready: &ready
test: ["CMD", "python", "-c", "import urllib.request,sys;sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8080/health/ready',timeout=2).status==200 else 1)"]
interval: 3s
timeout: 3s
retries: 5
start_period: 15s
start_interval: 200ms
services:
postgres:
image: postgres:17.11-alpine@sha256:266d3c257594e195b309ae9d1805e54c788f1d7b375f56bf6c367aac6c917e7b
user: "70:70"
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets: [postgres_password]
volumes: [pgdata:/var/lib/postgresql/data]
shm_size: 256m
healthcheck:
test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "messenger", "-d", "messenger"]
interval: 2s
timeout: 3s
retries: 30
start_period: 10s
start_interval: 200ms
stop_grace_period: 10s
restart: unless-stopped
networks: [backend]
valkey:
image: valkey/valkey:8.1.11-alpine@sha256:2602ace2be6569bc2bbb06f873776516ab9089821525be34f4305c67eb9db02a
user: "999:1000"
command:
- valkey-server
- /run/secrets/valkey.conf
- --appendonly
- "yes"
- --appendfsync
- always
- --maxmemory
- 64mb
- --maxmemory-policy
- volatile-lru
secrets: [valkey.conf]
volumes: [valkeydata:/data]
healthcheck:
test: ["CMD-SHELL", "REDISCLI_AUTH=\"$$(sed -n 's/^requirepass //p' /run/secrets/valkey.conf)\" valkey-cli ping | grep -q PONG"]
interval: 2s
timeout: 3s
retries: 30
stop_grace_period: 10s
restart: unless-stopped
networks: [backend]
postgres-restore:
image: postgres:17.11-alpine@sha256:266d3c257594e195b309ae9d1805e54c788f1d7b375f56bf6c367aac6c917e7b
profiles: [track]
user: "70:70"
environment:
POSTGRES_DB: track
POSTGRES_USER: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets: [postgres_password]
volumes:
- pgrestore:/var/lib/postgresql/data
- ./backups:/backups:ro
shm_size: 256m
healthcheck:
test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "messenger", "-d", "track"]
interval: 2s
timeout: 3s
retries: 30
start_period: 10s
start_interval: 200ms
stop_grace_period: 10s
networks: [backend]
migrate:
<<: *app
command: ["python", "-m", "messenger.migrate"]
healthcheck:
disable: true
restart: "no"
depends_on:
postgres:
condition: service_healthy
api:
<<: *app
ports: ["127.0.0.1:${API_PORT:-8080}:8080"]
healthcheck: *ready
stop_grace_period: 10s
restart: unless-stopped
depends_on:
migrate:
condition: service_completed_successfully
valkey:
condition: service_started
api-shortttl:
<<: *app
profiles: [faults]
environment:
<<: *app-environment
SESSION_TTL_SECONDS: "2"
WEB_CONCURRENCY: "1"
ports: ["127.0.0.1:${SHORTTTL_PORT:-8082}:8080"]
healthcheck: *ready
stop_grace_period: 10s
restart: unless-stopped
depends_on:
migrate:
condition: service_completed_successfully
valkey:
condition: service_started
secrets:
postgres_password:
file: ./secrets/postgres_password
database_url:
file: ./secrets/database_url
valkey.conf:
file: ./secrets/valkey.conf
cache_url:
file: ./secrets/cache_url
cursor_secret:
file: ./secrets/cursor_secret
volumes:
pgdata:
valkeydata:
pgrestore:
networks:
backend:
+27
View File
@@ -0,0 +1,27 @@
date: 2026-10-28T17:16:16Z commit: 6468ee2
$ valkey-cli config get appendonly appendfsync maxmemory maxmemory-policy
appendonly
yes
appendfsync
always
maxmemory
67108864
maxmemory-policy
volatile-lru
$ valkey-cli info persistence | grep aof_enabled,aof_last_write_status
aof_enabled:1
aof_last_write_status:ok
$ valkey-cli dbsize; info stats | grep keyspace
4
keyspace_hits:2
keyspace_misses:2
$ valkey-cli --scan --pattern 'session:*' и вид значения (хеш сокращён, значения не печатаются)
session:253ef5d9… сессия
session:59c9c3c4… сессия
session:b86641dc… сессия
session:95ea586e… отметка отзыва "-"
tombstones: 1, cached sessions: 3
$ срок ключа кэша против срока сессии для session:253ef5d9…
valkey pexpiretime, ms: 1793208059163
postgres expires_at, ms: 1793211358951
ключ не переживает сессию: да
+17
View File
@@ -0,0 +1,17 @@
date: 2026-10-28T17:14:50Z commit: 6468ee2
$ make check
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ make validate
.venv/bin/python scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
$ make lint
.venv/bin/ruff check src student-tests scripts/track.py
All checks passed!
.venv/bin/ruff format --check src student-tests scripts/track.py
96 files already formatted
.venv/bin/ty check src student-tests
All checks passed!
$ make test
python3 tests/smoke.py --base-url "http://localhost:18082"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
+41
View File
@@ -0,0 +1,41 @@
date: 2026-10-28T17:31:07Z commit: 6468ee2
host: Apple M4 Max, 16 CPU, 48 GiB RAM, macOS 15.1
docker: 28.3.2, VM: 16 CPU, 8217190400 bytes
compose: 2.38.2-desktop.1
images:
mtusi-messenger:mtusi2026lab2
postgres:17.11-alpine@sha256:266d3c257594e195b309ae9d1805e54c788f1d7b375f56bf6c367aac6c917e7b
valkey/valkey:8.1.11-alpine@sha256:2602ace2be6569bc2bbb06f873776516ab9089821525be34f4305c67eb9db02a
FROM python:3.14-slim-trixie@sha256:51dafde81dbdb6ebde285137a295cf18a47ca95234fe388a343719cb97305b3d AS builder
COPY --from=ghcr.io/astral-sh/uv:0.9.7@sha256:ba4857bf2a068e9bc0e64eed8563b065908a4cd6bfb66b531a9c424c8e25e142 /uv /usr/local/bin/uv
FROM python:3.14-slim-trixie@sha256:51dafde81dbdb6ebde285137a295cf18a47ca95234fe388a343719cb97305b3d AS runtime
COPY --from=builder --chown=root:root /opt/venv /opt/venv
python in image: Python 3.14.7
packages (uv.lock):
fastapi 0.141.1
uvicorn 0.54.0
uvicorn-worker 0.4.0
gunicorn 26.2.0
asyncpg 0.32.0
argon2-cffi 25.1.0
pydantic 2.13.5
pydantic-settings 2.15.0
dishka 1.10.1
structlog 26.1.0
redis 8.1.0
$ docker compose --profile faults --profile track up -d --wait api-shortttl postgres-restore
docker compose top (service, UID, command), без повторов и без процессов healthcheck:
api 10001 python
api-shortttl 10001 python
postgres 70 postgres
postgres 70 postgres:
postgres-restore 70 postgres
postgres-restore 70 postgres:
valkey 999 tini
valkey 999 valkey-server
postgres durability (pg_settings):
fsync = on
full_page_writes = on
shared_buffers = 16384
synchronous_commit = on
wal_sync_method = fdatasync
+80
View File
@@ -0,0 +1,80 @@
date: 2026-10-28T17:16:18Z commit: 6468ee2
$ make explain # scripts/sql/explain-history.sql
chat_messages
---------------
20000
(1 row)
all_messages
--------------
30005
(1 row)
history_index_size
--------------------
1736 kB
(1 row)
== Первая страница, limit=50 (запрос HISTORY_FIRST приложения, LIMIT limit+1)
QUERY PLAN
-----------------------------------------------------------------------------------------------------------------------------------------------
Limit (cost=0.29..5.37 rows=51 width=102) (actual time=0.008..0.013 rows=51 loops=1)
Buffers: shared hit=3
-> Index Scan using messages_history_idx on messages (cost=0.29..1994.42 rows=20001 width=102) (actual time=0.007..0.010 rows=51 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-00000000c001'::uuid)
Buffers: shared hit=3
Planning:
Buffers: shared hit=24
Planning Time: 0.081 ms
Execution Time: 0.022 ms
(9 rows)
== Глубокая страница: keyset после 10 000-го сообщения (запрос HISTORY_AFTER приложения)
QUERY PLAN
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Limit (cost=0.29..9.99 rows=51 width=102) (actual time=0.007..0.012 rows=51 loops=1)
Buffers: shared hit=4
-> Index Scan using messages_history_idx on messages (cost=0.29..1269.18 rows=6670 width=102) (actual time=0.007..0.010 rows=51 loops=1)
Index Cond: ((chat_id = '00000000-0000-7000-8000-00000000c001'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 02:46:40+00'::timestamp with time zone, '00000000-0000-7000-8001-000000002710'::uuid)))
Buffers: shared hit=4
Planning Time: 0.034 ms
Execution Time: 0.032 ms
(7 rows)
== Та же глубокая страница через OFFSET 10000 (не используется приложением, для сравнения)
QUERY PLAN
--------------------------------------------------------------------------------------------------------------------------------------------------
Limit (cost=997.30..1002.39 rows=51 width=102) (actual time=0.879..0.885 rows=51 loops=1)
Buffers: shared hit=247
-> Index Scan using messages_history_idx on messages (cost=0.29..1994.42 rows=20001 width=102) (actual time=0.010..0.674 rows=10051 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-00000000c001'::uuid)
Buffers: shared hit=247
Planning Time: 0.046 ms
Execution Time: 0.897 ms
(7 rows)
== Проверка: keyset и OFFSET возвращают одну и ту же страницу
same_page
-----------
t
(1 row)
== Контрольный план без индекса истории (DROP INDEX внутри транзакции, затем ROLLBACK)
QUERY PLAN
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Limit (cost=1246.61..1246.74 rows=51 width=102) (actual time=1.473..1.478 rows=51 loops=1)
Buffers: shared hit=505
-> Sort (cost=1246.61..1263.29 rows=6670 width=102) (actual time=1.473..1.473 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 31kB
Buffers: shared hit=505
-> Seq Scan on messages (cost=0.00..1024.09 rows=6670 width=102) (actual time=0.291..1.073 rows=10000 loops=1)
Filter: ((chat_id = '00000000-0000-7000-8000-00000000c001'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 02:46:40+00'::timestamp with time zone, '00000000-0000-7000-8001-000000002710'::uuid)))
Rows Removed by Filter: 20005
Buffers: shared hit=499
Planning:
Buffers: shared hit=14
Planning Time: 0.084 ms
Execution Time: 1.486 ms
(14 rows)
+73
View File
@@ -0,0 +1,73 @@
date: 2026-10-28T17:15:43Z commit: 6468ee2
$ make test-faults
docker compose --profile faults up -d --wait api-shortttl
Container mtusi2026lab2-valkey-1 Running
Container mtusi2026lab2-postgres-1 Running
Container mtusi2026lab2-api-shortttl-1 Creating
Container mtusi2026lab2-api-shortttl-1 Created
Container mtusi2026lab2-postgres-1 Waiting
Container mtusi2026lab2-postgres-1 Healthy
Container mtusi2026lab2-migrate-1 Starting
Container mtusi2026lab2-migrate-1 Started
Container mtusi2026lab2-migrate-1 Waiting
Container mtusi2026lab2-migrate-1 Exited
Container mtusi2026lab2-api-shortttl-1 Starting
Container mtusi2026lab2-api-shortttl-1 Started
Container mtusi2026lab2-migrate-1 Waiting
Container mtusi2026lab2-api-shortttl-1 Waiting
Container mtusi2026lab2-postgres-1 Waiting
Container mtusi2026lab2-valkey-1 Waiting
Container mtusi2026lab2-valkey-1 Healthy
Container mtusi2026lab2-postgres-1 Healthy
Container mtusi2026lab2-migrate-1 Exited
Container mtusi2026lab2-api-shortttl-1 Healthy
BASE_URL="http://localhost:18082" SHORTTTL_URL="http://localhost:22082" .venv/bin/pytest -m stack -v -s student-tests/stack
============================= test session starts ==============================
platform darwin -- Python 3.14.5, pytest-9.1.1, pluggy-1.6.0 -- /Users/artemkostylev/projects/learning/HL/labs/mtusi2026lab2/.venv/bin/python
cachedir: .pytest_cache
rootdir: /Users/artemkostylev/projects/learning/HL/labs/mtusi2026lab2
configfile: pyproject.toml
plugins: asyncio-1.4.0, anyio-4.15.1
asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=function, asyncio_default_test_loop_scope=function
collecting ... collected 13 items
student-tests/stack/test_faults.py::test_registration_race_yields_exactly_one_user гонка 50 регистраций: 201×1, 409×49
PASSED
student-tests/stack/test_faults.py::test_chat_creation_rolls_back_on_unknown_member чат с несуществующим участником: 400 invalid_request
PASSED
student-tests/stack/test_faults.py::test_wrong_password_and_unknown_user_get_same_basic_challenge неверный пароль: 401 за 0.012 с
неизвестный пользователь: 401 за 0.011 с
PASSED
student-tests/stack/test_faults.py::test_logout_then_token_is_dead logout: 204, затем 401, повтор 401
PASSED
student-tests/stack/test_faults.py::test_short_ttl_session_expires SESSION_TTL_SECONDS=2: сразу 200, через 3 с 401
PASSED
student-tests/stack/test_faults.py::test_valkey_serves_repeated_checks 5 проверок токена: keyspace_hits 4 → 9
PASSED
student-tests/stack/test_faults.py::test_valkey_stopped_is_bypassed_but_logout_waits valkey остановлен, действующий токен: 200 за 0.207 с
valkey остановлен, неизвестный токен: 401 за 0.004 с
valkey остановлен: ready 200, вход 201, выход 503
valkey снова запущен: повторный выход 204
PASSED
student-tests/stack/test_faults.py::test_valkey_restart_keeps_cache_and_revocations рестарт valkey: ключей 14 → 14
рестарт valkey: живой 200, отозванный 401
PASSED
student-tests/stack/test_faults.py::test_valkey_flushall_loses_nothing FLUSHALL: живой 200, отозванный 401
PASSED
student-tests/stack/test_faults.py::test_postgres_stopped_gives_bounded_503_and_recovers postgres остановлен, ready: 503 за 1.012 с
postgres остановлен, live: 200 за 0.006 с
postgres остановлен, me: 503 за 1.006 с
postgres остановлен, stranger: 503 за 1.012 с
postgres остановлен, login: 503 за 1.005 с
postgres остановлен, register: 503 за 0.992 с
postgres запущен: готовность через 0.0 с, прежний токен 200
PASSED
student-tests/stack/test_faults.py::test_api_restart_keeps_session_without_extending_it рестарт api: готовность через 0.5 с, токен 200
expires_at при входе 2026-10-28T18:16:04.950293Z, в БД после рестарта 2026-10-28T18:16:04.950293Z
PASSED
student-tests/stack/test_faults.py::test_full_restart_keeps_session_until_logout restart.sh: готовность через 0.0 с, прежний токен 200, выход 204, затем 401
PASSED
student-tests/stack/test_faults.py::test_short_ttl_expires_after_restart_at_original_time рестарт api-shortttl: готовность через 0.5 с, после expires_at входа 401
PASSED
============================= 13 passed in 26.08s ==============================
+14
View File
@@ -0,0 +1,14 @@
date: 2026-10-28T17:31:06Z commit: 6468ee2
$ psql -c "SELECT substring(password_hash from '^[$]argon2id[$]v=[0-9]+[$]m=[0-9]+,t=[0-9]+,p=[0-9]+[$]') AS kdf_prefix, username = 'seed_author' AS seed_stub, count(*) AS users, min(length(password_hash)) AS min_length, max(length(password_hash)) AS max_length FROM users GROUP BY 1, 2 ORDER BY 2"
kdf_prefix | seed_stub | users | min_length | max_length
---------------------------------+-----------+-------+------------+------------
$argon2id$v=19$m=19456,t=2,p=1$ | f | 34 | 97 | 97
$argon2id$v=19$m=19456,t=2,p=1$ | t | 1 | 44 | 44
(2 rows)
$ psql -c "SELECT octet_length(token_hash) AS stored_bytes, count(*) AS sessions FROM sessions GROUP BY 1"
stored_bytes | sessions
--------------+----------
32 | 27
(1 row)
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 8.0,
"elapsed_seconds": 8.115,
"concurrency": 64,
"successful_requests": 13600,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 1675.852,
"successful_latency_ms": {
"p50": 30.112,
"p95": 86.847,
"p99": 112.662
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 8.0,
"elapsed_seconds": 8.129,
"concurrency": 64,
"successful_requests": 13163,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 1619.165,
"successful_latency_ms": {
"p50": 30.37,
"p95": 87.703,
"p99": 111.511
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 8.0,
"elapsed_seconds": 8.141,
"concurrency": 64,
"successful_requests": 13933,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 1711.47,
"successful_latency_ms": {
"p50": 27.216,
"p95": 83.269,
"p99": 103.729
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+67
View File
@@ -0,0 +1,67 @@
date: 2026-10-28T17:16:35Z commit: 6468ee2
условия: closed-loop tests/load.py, 64 потока, 8 с без прогрева, 3 повтора с паузой 40 с (TIME_WAIT клиента), один чат на прогон, api 4 воркера × пул 8, клиент на хосте macOS
другие стенды Docker в это время:
== прогон 1
$ python3 tests/load.py --duration 8 --concurrency 64 --output evidence/load-c64-1.json
$ docker stats --no-stream на 4-й секунде
mtusi2026lab2-api-1 164.88% 254.4MiB / 7.653GiB
mtusi2026lab2-api-shortttl-1 0.06% 76.9MiB / 7.653GiB
mtusi2026lab2-postgres-1 156.93% 135.4MiB / 7.653GiB
mtusi2026lab2-valkey-1 5.36% 14.27MiB / 7.653GiB
$ pg_stat_activity: состояние и ожидание соединений messenger, кроме простаивающих, 20 снимков через 0.1 с
192 active Lock:tuple
91 active Lock:transactionid
32 active LWLock:LockManager
14 idle in transaction Client:ClientRead
10 active CPU
4 active IO:WalSync
2 idle in transaction CPU
2 active Client:ClientRead
успешных 13600 ошибок 0 RPS 1675.852 p50/p95/p99 30.112/86.847/112.662 мс
$ docker compose logs api --since 15s | статусы request.handled
7 "status":200
13607 "status":201
== прогон 2
$ python3 tests/load.py --duration 8 --concurrency 64 --output evidence/load-c64-2.json
$ docker stats --no-stream на 4-й секунде
mtusi2026lab2-api-1 162.27% 262.2MiB / 7.653GiB
mtusi2026lab2-api-shortttl-1 14.80% 76.9MiB / 7.653GiB
mtusi2026lab2-postgres-1 137.73% 140.9MiB / 7.653GiB
mtusi2026lab2-valkey-1 4.88% 14.14MiB / 7.653GiB
$ pg_stat_activity: состояние и ожидание соединений messenger, кроме простаивающих, 20 снимков через 0.1 с
176 active Lock:tuple
58 active Lock:transactionid
27 active LWLock:LockManager
14 active CPU
8 idle in transaction Client:ClientRead
4 active Client:ClientRead
1 idle in transaction CPU
1 active LWLock:BufferContent
1 active IO:WalSync
успешных 13163 ошибок 0 RPS 1619.165 p50/p95/p99 30.37/87.703/111.511 мс
$ docker compose logs api --since 15s | статусы request.handled
7 "status":200
13170 "status":201
== прогон 3
$ python3 tests/load.py --duration 8 --concurrency 64 --output evidence/load-c64-3.json
$ docker stats --no-stream на 4-й секунде
mtusi2026lab2-api-1 163.71% 280.2MiB / 7.653GiB
mtusi2026lab2-api-shortttl-1 0.07% 76.9MiB / 7.653GiB
mtusi2026lab2-postgres-1 148.17% 144.1MiB / 7.653GiB
mtusi2026lab2-valkey-1 5.67% 14.12MiB / 7.653GiB
$ pg_stat_activity: состояние и ожидание соединений messenger, кроме простаивающих, 20 снимков через 0.1 с
193 active Lock:tuple
69 active Lock:transactionid
14 active LWLock:LockManager
13 active CPU
5 idle in transaction CPU
4 idle in transaction Client:ClientRead
4 active IO:WalSync
2 idle in transaction IO:WalSync
1 active Client:ClientRead
успешных 13933 ошибок 0 RPS 1711.47 p50/p95/p99 27.216/83.269/103.729 мс
$ docker compose logs api --since 15s | статусы request.handled
7 "status":200
13940 "status":201
== медиана трёх прогонов
RPS 1675.852 [1619.165..1711.47], p50 30.112 мс, p95 86.847 мс, p99 111.511 мс, ошибок 0
+36
View File
@@ -0,0 +1,36 @@
date: 2026-10-28T17:14:42Z commit: 6468ee2
== применение к пустому volume
$ make reset-data && make up
$ docker compose logs --no-log-prefix migrate
{"version":"0001_init","event":"migration.applied","level":"info","ts":"2026-10-28T17:14:47.224527Z"}
{"reason":"applied","event":"migration.completed","level":"info","ts":"2026-10-28T17:14:47.224610Z"}
$ psql -c "SELECT (SELECT count(*) FROM users) users, (SELECT count(*) FROM sessions) sessions, (SELECT count(*) FROM chats) chats, (SELECT count(*) FROM chat_members) members, (SELECT count(*) FROM messages) messages, (SELECT count(*) FROM schema_migrations) versions"
users | sessions | chats | members | messages | versions
-------+----------+-------+---------+----------+----------
0 | 0 | 0 | 0 | 0 | 1
(1 row)
$ psql -c "SELECT version, left(checksum, 12) AS checksum, applied_at FROM schema_migrations"
version | checksum | applied_at
-----------+--------------+------------------------------
0001_init | 9a13618f078a | 2026-10-28 17:14:47.21836+00
(1 row)
== повторный запуск на заполненной БД
$ make test
python3 tests/smoke.py --base-url "http://localhost:18082"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
$ psql -c "SELECT (SELECT count(*) FROM users) users, (SELECT count(*) FROM sessions) sessions, (SELECT count(*) FROM chats) chats, (SELECT count(*) FROM chat_members) members, (SELECT count(*) FROM messages) messages, (SELECT count(*) FROM schema_migrations) versions"
users | sessions | chats | members | messages | versions
-------+----------+-------+---------+----------+----------
3 | 2 | 1 | 2 | 2 | 1
(1 row)
$ make migrate
{"reason":"up to date","event":"migration.completed","level":"info","ts":"2026-10-28T17:14:50.421856Z"}
$ psql -c "SELECT (SELECT count(*) FROM users) users, (SELECT count(*) FROM sessions) sessions, (SELECT count(*) FROM chats) chats, (SELECT count(*) FROM chat_members) members, (SELECT count(*) FROM messages) messages, (SELECT count(*) FROM schema_migrations) versions"
users | sessions | chats | members | messages | versions
-------+----------+-------+---------+----------+----------
3 | 2 | 1 | 2 | 2 | 1
(1 row)
+14
View File
@@ -0,0 +1,14 @@
date: 2026-10-28T17:15:38Z commit: 6468ee2
== before: service StartedAt status
postgres 2026-10-28T17:14:45.771182542Z running
migrate 2026-10-28T17:14:46.867549042Z exited
valkey 2026-10-28T17:14:45.770904042Z running
api 2026-10-28T17:14:47.462394959Z running
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:18082"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
== after: service StartedAt status
postgres 2026-10-28T17:15:40.432032345Z running
migrate 2026-10-28T17:15:41.475733721Z exited
valkey 2026-10-28T17:15:40.539058345Z running
api 2026-10-28T17:15:42.059123013Z running
+111
View File
@@ -0,0 +1,111 @@
date: 2026-10-28T17:31:05Z commit: 6468ee2
$ psql -c '\d+ users'
Table "public.users"
Column | Type | Collation | Nullable | Default | Storage | Compression | Stats target | Description
---------------+--------------------------+-----------+----------+---------+----------+-------------+--------------+-------------
id | uuid | | not null | | plain | | |
username | text | | not null | | extended | | |
display_name | text | | not null | | extended | | |
password_hash | text | | not null | | extended | | |
created_at | timestamp with time zone | | not null | | plain | | |
Indexes:
"users_pkey" PRIMARY KEY, btree (id)
"users_username_key" UNIQUE CONSTRAINT, btree (username)
Check constraints:
"users_display_name_check" CHECK (char_length(display_name) >= 1 AND char_length(display_name) <= 100)
"users_password_hash_check" CHECK (password_hash ~~ '$argon2id$%'::text)
"users_username_format" CHECK (username ~ '^[a-z0-9_]{3,32}$'::text)
Referenced by:
TABLE "chat_members" CONSTRAINT "chat_members_user_id_fkey" FOREIGN KEY (user_id) REFERENCES users(id)
TABLE "sessions" CONSTRAINT "sessions_user_id_fkey" FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
Access method: heap
$ psql -c '\d+ sessions'
Table "public.sessions"
Column | Type | Collation | Nullable | Default | Storage | Compression | Stats target | Description
------------+--------------------------+-----------+----------+---------+----------+-------------+--------------+-------------
token_hash | bytea | | not null | | extended | | |
user_id | uuid | | not null | | plain | | |
created_at | timestamp with time zone | | not null | | plain | | |
expires_at | timestamp with time zone | | not null | | plain | | |
Indexes:
"sessions_pkey" PRIMARY KEY, btree (token_hash)
"sessions_user_idx" btree (user_id)
Check constraints:
"sessions_check" CHECK (expires_at > created_at)
"sessions_token_hash_check" CHECK (octet_length(token_hash) = 32)
Foreign-key constraints:
"sessions_user_id_fkey" FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
Access method: heap
$ psql -c '\d+ chats'
Table "public.chats"
Column | Type | Collation | Nullable | Default | Storage | Compression | Stats target | Description
-----------------+--------------------------+-----------+----------+---------+----------+-------------+--------------+-------------
id | uuid | | not null | | plain | | |
title | text | | not null | | extended | | |
created_at | timestamp with time zone | | not null | | plain | | |
last_message_at | timestamp with time zone | | | | plain | | |
Indexes:
"chats_pkey" PRIMARY KEY, btree (id)
Check constraints:
"chats_title_check" CHECK (char_length(title) >= 1 AND char_length(title) <= 100)
Referenced by:
TABLE "chat_members" CONSTRAINT "chat_members_chat_id_fkey" FOREIGN KEY (chat_id) REFERENCES chats(id) ON DELETE CASCADE
Access method: heap
$ psql -c '\d+ chat_members'
Table "public.chat_members"
Column | Type | Collation | Nullable | Default | Storage | Compression | Stats target | Description
-----------------+--------------------------+-----------+----------+---------+---------+-------------+--------------+-------------
chat_id | uuid | | not null | | plain | | |
user_id | uuid | | not null | | plain | | |
position | smallint | | not null | | plain | | |
chat_created_at | timestamp with time zone | | not null | | plain | | |
Indexes:
"chat_members_pkey" PRIMARY KEY, btree (chat_id, user_id)
"chat_members_user_idx" btree (user_id, chat_created_at, chat_id)
Check constraints:
"chat_members_position_check" CHECK ("position" >= 1 AND "position" <= 100)
Foreign-key constraints:
"chat_members_chat_id_fkey" FOREIGN KEY (chat_id) REFERENCES chats(id) ON DELETE CASCADE
"chat_members_user_id_fkey" FOREIGN KEY (user_id) REFERENCES users(id)
Referenced by:
TABLE "messages" CONSTRAINT "messages_chat_id_sender_id_fkey" FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members(chat_id, user_id)
Access method: heap
$ psql -c '\d+ messages'
Table "public.messages"
Column | Type | Collation | Nullable | Default | Storage | Compression | Stats target | Description
------------+--------------------------+-----------+----------+---------+----------+-------------+--------------+-------------
id | uuid | | not null | | plain | | |
chat_id | uuid | | not null | | plain | | |
sender_id | uuid | | not null | | plain | | |
text | text | | not null | | extended | | |
created_at | timestamp with time zone | | not null | | plain | | |
Indexes:
"messages_pkey" PRIMARY KEY, btree (id)
"messages_history_idx" btree (chat_id, created_at, id)
Check constraints:
"messages_text_check" CHECK (char_length(text) >= 1 AND char_length(text) <= 4000)
Foreign-key constraints:
"messages_chat_id_sender_id_fkey" FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members(chat_id, user_id)
Access method: heap
$ psql -c '\d+ schema_migrations'
Table "public.schema_migrations"
Column | Type | Collation | Nullable | Default | Storage | Compression | Stats target | Description
------------+--------------------------+-----------+----------+---------+----------+-------------+--------------+-------------
version | text | | not null | | extended | | |
checksum | text | | not null | | extended | | |
applied_at | timestamp with time zone | | not null | now() | plain | | |
Indexes:
"schema_migrations_pkey" PRIMARY KEY, btree (version)
Access method: heap
$ psql -c 'SELECT version, left(checksum, 12), applied_at FROM schema_migrations'
version | checksum | applied_at
-----------+--------------+------------------------------
0001_init | 9a13618f078a | 2026-10-28 17:14:47.21836+00
(1 row)
+13
View File
@@ -0,0 +1,13 @@
date: 2026-10-28T17:31:07Z commit: 6468ee2
$ git ls-files secrets .env backups volumes
(пусто: секретов, .env, дампов и volumes в Git нет)
$ git check-ignore -v secrets/database_url secrets/postgres_password .env backups/
.gitignore:5:secrets/ secrets/database_url
.gitignore:5:secrets/ secrets/postgres_password
.gitignore:2:.env .env
.gitignore:15:backups/ backups/
$ docker volume ls --filter label=com.docker.compose.project=mtusi2026lab2
DRIVER VOLUME NAME
local mtusi2026lab2_pgdata
local mtusi2026lab2_pgrestore
local mtusi2026lab2_valkeydata
+21
View File
@@ -0,0 +1,21 @@
date: 2026-10-28T17:16:20Z commit: 6468ee2
stop_grace_period: 10s, SHUTDOWN_TIMEOUT_SECONDS: 8
$ два POST /messages в работе (тело отправлено не целиком); docker compose kill --signal SIGTERM api; первому дописать тело через 1 с, второму — никогда; docker wait <api>
запрос, дописанный через 1 с после SIGTERM: HTTP/1.1 201 Created через 1.15 с
запрос, не дописанный никогда: HTTP/1.1 500 Internal Server Error через 7.24 с
остановка за 7.68 с, код завершения 0
$ docker logs <api> | записи об остановке
{"event":"Shutting down","level":"info","ts":"2026-10-28T17:16:21.580367Z"}
{"event":"Shutting down","level":"info","ts":"2026-10-28T17:16:21.597496Z"}
{"event":"Waiting for application shutdown.","level":"info","ts":"2026-10-28T17:16:21.625380Z"}
{"event":"Finished server process [13]","level":"info","ts":"2026-10-28T17:16:21.626805Z"}
{"event":"Waiting for connections to close. (CTRL+C to force quit)","level":"info","ts":"2026-10-28T17:16:21.626825Z"}
{"event":"Waiting for connections to close. (CTRL+C to force quit)","level":"info","ts":"2026-10-28T17:16:21.682577Z"}
{"event":"Waiting for application shutdown.","level":"info","ts":"2026-10-28T17:16:21.701990Z"}
{"event":"Finished server process [14]","level":"info","ts":"2026-10-28T17:16:21.708567Z"}
{"event":"Waiting for application shutdown.","level":"info","ts":"2026-10-28T17:16:22.635466Z"}
{"event":"Finished server process [16]","level":"info","ts":"2026-10-28T17:16:22.642431Z"}
{"event":"Cancel 1 running task(s), timeout graceful shutdown exceeded","level":"error","ts":"2026-10-28T17:16:28.628254Z"}
{"event":"Waiting for application shutdown.","level":"info","ts":"2026-10-28T17:16:28.628314Z"}
{"event":"Finished server process [15]","level":"info","ts":"2026-10-28T17:16:28.629034Z"}
{"event":"Shutting down: Master","level":"info","ts":"2026-10-28T17:16:28.850585Z"}
+329
View File
@@ -0,0 +1,329 @@
date: 2026-10-28T17:14:51Z commit: 6468ee2
$ make student-test PYTEST_ARGS=-v
.venv/bin/pytest -v
============================= test session starts ==============================
platform darwin -- Python 3.14.5, pytest-9.1.1, pluggy-1.6.0 -- /Users/artemkostylev/projects/learning/HL/labs/mtusi2026lab2/.venv/bin/python
cachedir: .pytest_cache
rootdir: /Users/artemkostylev/projects/learning/HL/labs/mtusi2026lab2
configfile: pyproject.toml
testpaths: student-tests
plugins: asyncio-1.4.0, anyio-4.15.1
asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=function, asyncio_default_test_loop_scope=function
collecting ... collected 234 items / 13 deselected / 221 selected
student-tests/api/test_access.py::test_outsider_gets_404_on_chat PASSED [ 0%]
student-tests/api/test_access.py::test_unknown_chat_is_indistinguishable_from_foreign PASSED [ 0%]
student-tests/api/test_access.py::test_outsider_cannot_write PASSED [ 1%]
student-tests/api/test_access.py::test_outsider_cannot_read_history PASSED [ 1%]
student-tests/api/test_access.py::test_access_checked_before_body PASSED [ 2%]
student-tests/api/test_access.py::test_chat_list_hides_foreign_chats PASSED [ 2%]
student-tests/api/test_access.py::test_403_is_never_used PASSED [ 3%]
student-tests/api/test_access.py::test_outsider_does_not_wait_for_members_lock PASSED [ 3%]
student-tests/api/test_bounded_contexts.py::test_identity_does_not_know_about_messaging PASSED [ 4%]
student-tests/api/test_bounded_contexts.py::test_domains_do_not_import_infrastructure PASSED [ 4%]
student-tests/api/test_bounded_contexts.py::test_core_layers_do_not_import_pydantic PASSED [ 4%]
student-tests/api/test_bounded_contexts.py::test_shared_knows_nothing_about_zones PASSED [ 5%]
student-tests/api/test_bounded_contexts.py::test_shared_core_is_free_of_transport PASSED [ 5%]
student-tests/api/test_bounded_contexts.py::test_shared_core_holds_only_platform PASSED [ 6%]
student-tests/api/test_bounded_contexts.py::test_shared_entrypoints_hold_only_transport PASSED [ 6%]
student-tests/api/test_bounded_contexts.py::test_every_zone_owns_its_errors_events_and_commands PASSED [ 7%]
student-tests/api/test_bounded_contexts.py::test_every_zone_owns_its_http_layer PASSED [ 7%]
student-tests/api/test_bounded_contexts.py::test_only_main_knows_both_zones PASSED [ 8%]
student-tests/api/test_bounded_contexts.py::test_application_has_no_separate_entrypoints_root PASSED [ 8%]
student-tests/api/test_bounded_contexts.py::test_shared_source_mentions_no_domain_vocabulary PASSED [ 9%]
student-tests/api/test_bounded_contexts.py::test_shared_declares_no_concrete_commands_or_events PASSED [ 9%]
student-tests/api/test_bounded_contexts.py::test_shared_has_no_test_doubles PASSED [ 9%]
student-tests/api/test_bounded_contexts.py::test_zone_errors_do_not_leak_transport_codes PASSED [ 10%]
student-tests/api/test_bounded_contexts.py::test_sql_of_each_zone_reads_only_its_tables PASSED [ 10%]
student-tests/api/test_bounded_contexts.py::test_messaging_does_not_import_identity_at_all PASSED [ 11%]
student-tests/api/test_cache.py::test_second_check_is_served_from_cache PASSED [ 11%]
student-tests/api/test_cache.py::test_logout_writes_tombstone_before_database PASSED [ 12%]
student-tests/api/test_cache.py::test_logout_rejected_by_database_changes_nothing PASSED [ 12%]
student-tests/api/test_cache.py::test_fill_racing_with_logout_does_not_revive_token PASSED [ 13%]
student-tests/api/test_cache.py::test_flushall_loses_nothing PASSED [ 13%]
student-tests/api/test_cache.py::test_unreachable_cache_is_bypassed_without_anonymous_access PASSED [ 14%]
student-tests/api/test_concurrency.py::test_hundred_messages_from_ten_clients PASSED [ 14%]
student-tests/api/test_concurrency.py::test_parallel_registration_keeps_username_unique PASSED [ 14%]
student-tests/api/test_concurrency.py::test_parallel_chat_creation_is_atomic PASSED [ 15%]
student-tests/api/test_consistency.py::test_registration_is_visible_to_chats_immediately PASSED [ 15%]
student-tests/api/test_consistency.py::test_parallel_registrations_are_all_usable_as_members PASSED [ 16%]
student-tests/api/test_consistency.py::test_rejected_registration_leaves_no_trace PASSED [ 16%]
student-tests/api/test_consistency.py::test_failed_chat_creation_rolls_back_both_tables PASSED [ 17%]
student-tests/api/test_consistency.py::test_rejected_message_does_not_enter_history PASSED [ 17%]
student-tests/api/test_consistency.py::test_confirmed_write_is_visible_to_next_read PASSED [ 18%]
student-tests/api/test_consistency.py::test_parallel_writes_across_zones_keep_counts_consistent PASSED [ 18%]
student-tests/api/test_consistency.py::test_chat_membership_survives_parallel_reads_and_writes PASSED [ 19%]
student-tests/api/test_events.py::test_event_has_no_message_text PASSED [ 19%]
student-tests/api/test_events.py::test_every_subscriber_receives_event PASSED [ 19%]
student-tests/api/test_events.py::test_failing_subscriber_does_not_block_others PASSED [ 20%]
student-tests/api/test_events.py::test_queue_overflow_drops_events_without_raising PASSED [ 20%]
student-tests/api/test_events.py::test_publication_does_not_delay_response PASSED [ 21%]
student-tests/api/test_events.py::test_null_logger_hides_everything PASSED [ 21%]
student-tests/api/test_migrations.py::test_migrations_are_ordered_and_versioned PASSED [ 22%]
student-tests/api/test_migrations.py::test_rerun_changes_nothing PASSED [ 22%]
student-tests/api/test_migrations.py::test_changed_migration_is_refused PASSED [ 23%]
student-tests/api/test_migrations.py::test_sender_must_be_member_even_bypassing_api PASSED [ 23%]
student-tests/api/test_migrations.py::test_database_name_argument_replaces_only_the_database PASSED [ 23%]
student-tests/api/test_negative.py::test_malformed_json PASSED [ 24%]
student-tests/api/test_negative.py::test_unexpected_field PASSED [ 24%]
student-tests/api/test_negative.py::test_wrong_types PASSED [ 25%]
student-tests/api/test_negative.py::test_invalid_registration[body0] PASSED [ 25%]
student-tests/api/test_negative.py::test_invalid_registration[body1] PASSED [ 26%]
student-tests/api/test_negative.py::test_invalid_registration[body2] PASSED [ 26%]
student-tests/api/test_negative.py::test_invalid_registration[body3] PASSED [ 27%]
student-tests/api/test_negative.py::test_invalid_registration[body4] PASSED [ 27%]
student-tests/api/test_negative.py::test_invalid_registration[body5] PASSED [ 28%]
student-tests/api/test_negative.py::test_invalid_registration[body6] PASSED [ 28%]
student-tests/api/test_negative.py::test_invalid_registration[body7] PASSED [ 28%]
student-tests/api/test_negative.py::test_invalid_registration[body8] PASSED [ 29%]
student-tests/api/test_negative.py::test_invalid_registration[body9] PASSED [ 29%]
student-tests/api/test_negative.py::test_invalid_registration[body10] PASSED [ 30%]
student-tests/api/test_negative.py::test_duplicate_username PASSED [ 30%]
student-tests/api/test_negative.py::test_missing_identity PASSED [ 31%]
student-tests/api/test_negative.py::test_invalid_bearer[] PASSED [ 31%]
student-tests/api/test_negative.py::test_invalid_bearer[Bearer] PASSED [ 32%]
student-tests/api/test_negative.py::test_invalid_bearer[Bearer ] PASSED [ 32%]
student-tests/api/test_negative.py::test_invalid_bearer[Bearer not a token] PASSED [ 33%]
student-tests/api/test_negative.py::test_invalid_bearer[Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] PASSED [ 33%]
student-tests/api/test_negative.py::test_invalid_bearer[Token abcdef] PASSED [ 33%]
student-tests/api/test_negative.py::test_invalid_bearer[11111111-1111-4111-8111-111111111111] PASSED [ 34%]
student-tests/api/test_negative.py::test_user_id_header_alone_is_ignored PASSED [ 34%]
student-tests/api/test_negative.py::test_identity_checked_before_body PASSED [ 35%]
student-tests/api/test_negative.py::test_empty_message_rejected PASSED [ 35%]
student-tests/api/test_negative.py::test_long_message_rejected PASSED [ 36%]
student-tests/api/test_negative.py::test_sender_id_not_accepted PASSED [ 36%]
student-tests/api/test_negative.py::test_invalid_chat_creation[body0] PASSED [ 37%]
student-tests/api/test_negative.py::test_invalid_chat_creation[body1] PASSED [ 37%]
student-tests/api/test_negative.py::test_invalid_chat_creation[body2] PASSED [ 38%]
student-tests/api/test_negative.py::test_invalid_chat_creation[body3] PASSED [ 38%]
student-tests/api/test_negative.py::test_invalid_chat_creation[body4] PASSED [ 38%]
student-tests/api/test_negative.py::test_invalid_chat_creation[body5] PASSED [ 39%]
student-tests/api/test_negative.py::test_creator_must_be_member PASSED [ 39%]
student-tests/api/test_negative.py::test_unknown_member_rejected PASSED [ 40%]
student-tests/api/test_negative.py::test_bad_chat_id_in_path PASSED [ 40%]
student-tests/api/test_operability.py::test_health_needs_no_identity PASSED [ 41%]
student-tests/api/test_operability.py::test_every_response_carries_request_id PASSED [ 41%]
student-tests/api/test_operability.py::test_client_request_id_is_preserved PASSED [ 42%]
student-tests/api/test_operability.py::test_unknown_public_route_is_404 PASSED [ 42%]
student-tests/api/test_operability.py::test_unknown_protected_route_needs_identity PASSED [ 42%]
student-tests/api/test_operability.py::test_method_not_allowed_is_hidden PASSED [ 43%]
student-tests/api/test_operability.py::test_logs_do_not_contain_message_text PASSED [ 43%]
student-tests/api/test_operability.py::test_log_lines_are_json PASSED [ 44%]
student-tests/api/test_operability.py::test_body_limit_returns_413 PASSED [ 44%]
student-tests/api/test_operability.py::test_chunked_body_is_limited_too PASSED [ 45%]
student-tests/api/test_operability.py::test_ready_turns_unavailable_without_database PASSED [ 45%]
student-tests/api/test_operability.py::test_protected_request_is_503_not_401_without_database PASSED [ 46%]
student-tests/api/test_operability.py::test_state_survives_new_process PASSED [ 46%]
student-tests/api/test_operability.py::test_logs_do_not_contain_credentials PASSED [ 47%]
student-tests/api/test_pagination.py::test_full_walk_has_no_gaps_or_repeats PASSED [ 47%]
student-tests/api/test_pagination.py::test_limit_may_change_between_pages PASSED [ 47%]
student-tests/api/test_pagination.py::test_last_page_closes_history PASSED [ 48%]
student-tests/api/test_pagination.py::test_cursor_is_shared_between_members PASSED [ 48%]
student-tests/api/test_pagination.py::test_cursor_from_another_chat_is_rejected PASSED [ 49%]
student-tests/api/test_pagination.py::test_broken_cursor_is_rejected[garbage] PASSED [ 49%]
student-tests/api/test_pagination.py::test_broken_cursor_is_rejected[1.2.3.4] PASSED [ 50%]
student-tests/api/test_pagination.py::test_broken_cursor_is_rejected[%20] PASSED [ 50%]
student-tests/api/test_pagination.py::test_broken_cursor_is_rejected[] PASSED [ 51%]
student-tests/api/test_pagination.py::test_limit_out_of_range[0] PASSED [ 51%]
student-tests/api/test_pagination.py::test_limit_out_of_range[-1] PASSED [ 52%]
student-tests/api/test_pagination.py::test_limit_out_of_range[101] PASSED [ 52%]
student-tests/api/test_pagination.py::test_limit_out_of_range[abc] PASSED [ 52%]
student-tests/api/test_pagination.py::test_limit_out_of_range[1.5] PASSED [ 53%]
student-tests/api/test_pagination.py::test_limit_out_of_range[] PASSED [ 53%]
student-tests/api/test_pagination.py::test_default_limit_is_50 PASSED [ 54%]
student-tests/api/test_pagination.py::test_unknown_query_parameter_is_ignored PASSED [ 54%]
student-tests/api/test_pagination.py::test_chat_list_pagination PASSED [ 55%]
student-tests/api/test_pool.py::test_exhausted_pool_answers_503_in_bounded_time PASSED [ 55%]
student-tests/api/test_pool.py::test_statement_timeout_is_set_on_connections PASSED [ 56%]
student-tests/api/test_sessions.py::test_login_returns_session_for_registered_user PASSED [ 56%]
student-tests/api/test_sessions.py::test_registration_response_hides_password PASSED [ 57%]
student-tests/api/test_sessions.py::test_password_is_stored_as_argon2id PASSED [ 57%]
student-tests/api/test_sessions.py::test_session_stores_only_token_digest PASSED [ 57%]
student-tests/api/test_sessions.py::test_wrong_password_and_unknown_user_look_the_same PASSED [ 58%]
student-tests/api/test_sessions.py::test_login_without_valid_basic[headers0] PASSED [ 58%]
student-tests/api/test_sessions.py::test_login_without_valid_basic[headers1] PASSED [ 59%]
student-tests/api/test_sessions.py::test_login_without_valid_basic[headers2] PASSED [ 59%]
student-tests/api/test_sessions.py::test_login_without_valid_basic[headers3] PASSED [ 60%]
student-tests/api/test_sessions.py::test_password_with_colon_logs_in PASSED [ 60%]
student-tests/api/test_sessions.py::test_login_with_body_is_rejected PASSED [ 61%]
student-tests/api/test_sessions.py::test_basic_on_business_endpoint_gets_bearer_challenge PASSED [ 61%]
student-tests/api/test_sessions.py::test_user_id_header_does_not_override_owner PASSED [ 61%]
student-tests/api/test_sessions.py::test_authentication_precedes_validation PASSED [ 62%]
student-tests/api/test_sessions.py::test_logout_revokes_only_current_session PASSED [ 62%]
student-tests/api/test_sessions.py::test_short_ttl_session_expires PASSED [ 63%]
student-tests/api/test_sessions.py::test_expired_sessions_are_purged_on_next_login PASSED [ 63%]
student-tests/api/test_sessions.py::test_chat_routes_require_bearer PASSED [ 64%]
student-tests/api/test_timeout.py::test_timeout_returns_unavailable_error_body PASSED [ 64%]
student-tests/api/test_timeout.py::test_timeout_does_not_break_following_requests PASSED [ 65%]
student-tests/api/test_timeout.py::test_timeout_is_logged_without_message_text PASSED [ 65%]
student-tests/api/test_timeout.py::test_normal_request_is_not_affected_by_timeout PASSED [ 66%]
student-tests/api/test_timeout.py::test_slow_event_handler_does_not_trigger_timeout PASSED [ 66%]
student-tests/api/test_timeout.py::test_healthcheck_stays_fast PASSED [ 66%]
student-tests/api/test_wire_format.py::test_created_at_is_rfc3339_utc[whole-second] PASSED [ 67%]
student-tests/api/test_wire_format.py::test_created_at_is_rfc3339_utc[microseconds] PASSED [ 67%]
student-tests/unit/test_authentication.py::test_basic_splits_on_first_colon PASSED [ 68%]
student-tests/unit/test_authentication.py::test_basic_decodes_utf8_password PASSED [ 68%]
student-tests/unit/test_authentication.py::test_basic_scheme_is_case_insensitive PASSED [ 69%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[] PASSED [ 69%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Basic] PASSED [ 70%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Basic ] PASSED [ 70%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Basic !!!not-base64!!!] PASSED [ 71%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Basic YWxpY2U] PASSED [ 71%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Basic bm8tY29sb24taGVyZQ==] PASSED [ 71%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Basic 0LDQu9C40YHQsDrQv9Cw0YDQvtC70Yw=] PASSED [ 72%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Basic YWxpY2U6//4=] PASSED [ 72%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Bearer YWxpY2U6c2VjcmV0] PASSED [ 73%]
student-tests/unit/test_authentication.py::test_bearer_accepts_token68 PASSED [ 73%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[] PASSED [ 74%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[Bearer] PASSED [ 74%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[Bearer ] PASSED [ 75%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[Bearer a b] PASSED [ 75%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[Basic abc] PASSED [ 76%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] PASSED [ 76%]
student-tests/unit/test_authentication.py::test_bearer_rejects_oversized_token PASSED [ 76%]
student-tests/unit/test_authentication.py::test_challenge_depends_only_on_path PASSED [ 77%]
student-tests/unit/test_cursor.py::test_roundtrip_preserves_key PASSED [ 77%]
student-tests/unit/test_cursor.py::test_cursor_is_opaque PASSED [ 78%]
student-tests/unit/test_cursor.py::test_cursor_from_another_scope_is_rejected PASSED [ 78%]
student-tests/unit/test_cursor.py::test_forged_cursor_is_rejected PASSED [ 79%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[] PASSED [ 79%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[garbage] PASSED [ 80%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[1.2.3] PASSED [ 80%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[2.1.2.3] PASSED [ 80%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[1.notanumber.ff.AAAA] PASSED [ 81%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[1.1.zz.AAAA] PASSED [ 81%]
student-tests/unit/test_cursor.py::test_tampered_payload_is_rejected PASSED [ 82%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[ab] PASSED [ 82%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa] PASSED [ 83%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[Alice] PASSED [ 83%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[alice-01] PASSED [ 84%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[\u0430\u043b\u0438\u0441\u0430] PASSED [ 84%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[] PASSED [ 85%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[a b] PASSED [ 85%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[alice\n] PASSED [ 85%]
student-tests/unit/test_domain.py::test_username_rejects_invalid[alice\r\n] PASSED [ 86%]
student-tests/unit/test_domain.py::test_username_accepts_valid[abc] PASSED [ 86%]
student-tests/unit/test_domain.py::test_username_accepts_valid[a_b_9] PASSED [ 87%]
student-tests/unit/test_domain.py::test_username_accepts_valid[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa] PASSED [ 87%]
student-tests/unit/test_domain.py::test_display_name_rejects_invalid[] PASSED [ 88%]
student-tests/unit/test_domain.py::test_display_name_rejects_invalid[ ] PASSED [ 88%]
student-tests/unit/test_domain.py::test_display_name_rejects_invalid[\t\n] PASSED [ 89%]
student-tests/unit/test_domain.py::test_display_name_rejects_invalid[xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] PASSED [ 89%]
student-tests/unit/test_domain.py::test_password_rejects_invalid[] PASSED [ 90%]
student-tests/unit/test_domain.py::test_password_rejects_invalid[ ] PASSED [ 90%]
student-tests/unit/test_domain.py::test_password_rejects_invalid[xxxxxxxxxxx] PASSED [ 90%]
student-tests/unit/test_domain.py::test_password_rejects_invalid[xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] PASSED [ 91%]
student-tests/unit/test_domain.py::test_password_rejects_invalid[\t\t\t\t\t\t\t\t\t\t\t\t] PASSED [ 91%]
student-tests/unit/test_domain.py::test_password_counts_code_points[xxxxxxxxxxxx] PASSED [ 92%]
student-tests/unit/test_domain.py::test_password_counts_code_points[\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f\u043f] PASSED [ 92%]
student-tests/unit/test_domain.py::test_password_counts_code_points[\u043f\u0430\u0440\u043e\u043b\u044c:\u0441:\u0434\u0432\u043e\u0435\u0442\u043e\u0447\u0438\u0435\u043c] PASSED [ 93%]
student-tests/unit/test_domain.py::test_password_counts_code_points[\U0001f44b\U0001f44b\U0001f44b\U0001f44b\U0001f44b\U0001f44b\U0001f44b\U0001f44b\U0001f44b\U0001f44b\U0001f44b\U0001f44b] PASSED [ 93%]
student-tests/unit/test_domain.py::test_password_is_not_printed PASSED [ 94%]
student-tests/unit/test_domain.py::test_session_token_is_opaque_and_stored_as_digest PASSED [ 94%]
student-tests/unit/test_domain.py::test_session_tokens_are_unique PASSED [ 95%]
student-tests/unit/test_domain.py::test_message_text_counts_code_points_not_bytes PASSED [ 95%]
student-tests/unit/test_domain.py::test_message_text_rejects_blank PASSED [ 95%]
student-tests/unit/test_domain.py::test_chat_requires_creator_in_members PASSED [ 96%]
student-tests/unit/test_domain.py::test_chat_rejects_duplicate_members PASSED [ 96%]
student-tests/unit/test_domain.py::test_chat_rejects_more_than_hundred_members PASSED [ 97%]
student-tests/unit/test_domain.py::test_outsider_cannot_post PASSED [ 97%]
student-tests/unit/test_domain.py::test_post_never_moves_history_back PASSED [ 98%]
student-tests/unit/test_domain.py::test_post_keeps_clock_when_it_is_ahead PASSED [ 98%]
student-tests/unit/test_domain.py::test_post_validates_membership_before_text PASSED [ 99%]
student-tests/unit/test_domain.py::test_user_registration_emits_event PASSED [ 99%]
student-tests/unit/test_domain.py::test_clock_is_strictly_increasing PASSED [100%]
===================== 221 passed, 13 deselected in 14.97s ======================
$ make student-test PYTEST_ARGS="-v -k 'rolls_back'"
student-tests/api/test_consistency.py::test_failed_chat_creation_rolls_back_both_tables PASSED [100%]
====================== 1 passed, 233 deselected in 1.58s =======================
$ make student-test PYTEST_ARGS="-v -k 'sessions or bearer'"
student-tests/api/test_negative.py::test_invalid_bearer[] PASSED [ 2%]
student-tests/api/test_negative.py::test_invalid_bearer[Bearer] PASSED [ 5%]
student-tests/api/test_negative.py::test_invalid_bearer[Bearer ] PASSED [ 8%]
student-tests/api/test_negative.py::test_invalid_bearer[Bearer not a token] PASSED [ 11%]
student-tests/api/test_negative.py::test_invalid_bearer[Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] PASSED [ 14%]
student-tests/api/test_negative.py::test_invalid_bearer[Token abcdef] PASSED [ 17%]
student-tests/api/test_negative.py::test_invalid_bearer[11111111-1111-4111-8111-111111111111] PASSED [ 20%]
student-tests/api/test_sessions.py::test_login_returns_session_for_registered_user PASSED [ 23%]
student-tests/api/test_sessions.py::test_registration_response_hides_password PASSED [ 26%]
student-tests/api/test_sessions.py::test_password_is_stored_as_argon2id PASSED [ 29%]
student-tests/api/test_sessions.py::test_session_stores_only_token_digest PASSED [ 32%]
student-tests/api/test_sessions.py::test_wrong_password_and_unknown_user_look_the_same PASSED [ 35%]
student-tests/api/test_sessions.py::test_login_without_valid_basic[headers0] PASSED [ 38%]
student-tests/api/test_sessions.py::test_login_without_valid_basic[headers1] PASSED [ 41%]
student-tests/api/test_sessions.py::test_login_without_valid_basic[headers2] PASSED [ 44%]
student-tests/api/test_sessions.py::test_login_without_valid_basic[headers3] PASSED [ 47%]
student-tests/api/test_sessions.py::test_password_with_colon_logs_in PASSED [ 50%]
student-tests/api/test_sessions.py::test_login_with_body_is_rejected PASSED [ 52%]
student-tests/api/test_sessions.py::test_basic_on_business_endpoint_gets_bearer_challenge PASSED [ 55%]
student-tests/api/test_sessions.py::test_user_id_header_does_not_override_owner PASSED [ 58%]
student-tests/api/test_sessions.py::test_authentication_precedes_validation PASSED [ 61%]
student-tests/api/test_sessions.py::test_logout_revokes_only_current_session PASSED [ 64%]
student-tests/api/test_sessions.py::test_short_ttl_session_expires PASSED [ 67%]
student-tests/api/test_sessions.py::test_expired_sessions_are_purged_on_next_login PASSED [ 70%]
student-tests/api/test_sessions.py::test_chat_routes_require_bearer PASSED [ 73%]
student-tests/unit/test_authentication.py::test_basic_rejects_malformed[Bearer YWxpY2U6c2VjcmV0] PASSED [ 76%]
student-tests/unit/test_authentication.py::test_bearer_accepts_token68 PASSED [ 79%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[] PASSED [ 82%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[Bearer] PASSED [ 85%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[Bearer ] PASSED [ 88%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[Bearer a b] PASSED [ 91%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[Basic abc] PASSED [ 94%]
student-tests/unit/test_authentication.py::test_bearer_rejects_malformed[xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] PASSED [ 97%]
student-tests/unit/test_authentication.py::test_bearer_rejects_oversized_token PASSED [100%]
====================== 34 passed, 200 deselected in 5.00s ======================
$ make student-test PYTEST_ARGS="-v -k 'expire or logout'"
student-tests/api/test_cache.py::test_logout_writes_tombstone_before_database PASSED [ 16%]
student-tests/api/test_cache.py::test_logout_rejected_by_database_changes_nothing PASSED [ 33%]
student-tests/api/test_cache.py::test_fill_racing_with_logout_does_not_revive_token PASSED [ 50%]
student-tests/api/test_sessions.py::test_logout_revokes_only_current_session PASSED [ 66%]
student-tests/api/test_sessions.py::test_short_ttl_session_expires PASSED [ 83%]
student-tests/api/test_sessions.py::test_expired_sessions_are_purged_on_next_login PASSED [100%]
====================== 6 passed, 228 deselected in 4.83s =======================
$ make student-test PYTEST_ARGS="-v -k 'user_id'"
student-tests/api/test_negative.py::test_user_id_header_alone_is_ignored PASSED [ 50%]
student-tests/api/test_sessions.py::test_user_id_header_does_not_override_owner PASSED [100%]
====================== 2 passed, 232 deselected in 1.72s =======================
$ make student-test PYTEST_ARGS="-v -k 'outsider'"
student-tests/api/test_access.py::test_outsider_gets_404_on_chat PASSED [ 20%]
student-tests/api/test_access.py::test_outsider_cannot_write PASSED [ 40%]
student-tests/api/test_access.py::test_outsider_cannot_read_history PASSED [ 60%]
student-tests/api/test_access.py::test_outsider_does_not_wait_for_members_lock PASSED [ 80%]
student-tests/unit/test_domain.py::test_outsider_cannot_post PASSED [100%]
====================== 5 passed, 229 deselected in 1.98s =======================
$ make student-test PYTEST_ARGS="-v -k 'cursor'"
student-tests/api/test_pagination.py::test_cursor_is_shared_between_members PASSED [ 5%]
student-tests/api/test_pagination.py::test_cursor_from_another_chat_is_rejected PASSED [ 11%]
student-tests/api/test_pagination.py::test_broken_cursor_is_rejected[garbage] PASSED [ 17%]
student-tests/api/test_pagination.py::test_broken_cursor_is_rejected[1.2.3.4] PASSED [ 23%]
student-tests/api/test_pagination.py::test_broken_cursor_is_rejected[%20] PASSED [ 29%]
student-tests/api/test_pagination.py::test_broken_cursor_is_rejected[] PASSED [ 35%]
student-tests/unit/test_cursor.py::test_roundtrip_preserves_key PASSED [ 41%]
student-tests/unit/test_cursor.py::test_cursor_is_opaque PASSED [ 47%]
student-tests/unit/test_cursor.py::test_cursor_from_another_scope_is_rejected PASSED [ 52%]
student-tests/unit/test_cursor.py::test_forged_cursor_is_rejected PASSED [ 58%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[] PASSED [ 64%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[garbage] PASSED [ 70%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[1.2.3] PASSED [ 76%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[2.1.2.3] PASSED [ 82%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[1.notanumber.ff.AAAA] PASSED [ 88%]
student-tests/unit/test_cursor.py::test_broken_cursor_is_rejected[1.1.zz.AAAA] PASSED [ 94%]
student-tests/unit/test_cursor.py::test_tampered_payload_is_rejected PASSED [100%]
====================== 17 passed, 217 deselected in 2.07s ======================
$ make student-test PYTEST_ARGS="-v -k 'body_limit or chunked'"
student-tests/api/test_operability.py::test_body_limit_returns_413 PASSED [ 50%]
student-tests/api/test_operability.py::test_chunked_body_is_limited_too PASSED [100%]
====================== 2 passed, 232 deselected in 1.54s =======================
$ make student-test PYTEST_ARGS="-v -k 'cache'"
student-tests/api/test_cache.py::test_second_check_is_served_from_cache PASSED [ 16%]
student-tests/api/test_cache.py::test_logout_writes_tombstone_before_database PASSED [ 33%]
student-tests/api/test_cache.py::test_logout_rejected_by_database_changes_nothing PASSED [ 50%]
student-tests/api/test_cache.py::test_fill_racing_with_logout_does_not_revive_token PASSED [ 66%]
student-tests/api/test_cache.py::test_flushall_loses_nothing PASSED [ 83%]
student-tests/api/test_cache.py::test_unreachable_cache_is_bypassed_without_anonymous_access PASSED [100%]
====================== 6 passed, 228 deselected in 2.35s =======================
$ make student-test PYTEST_ARGS="-v -k 'pool'"
student-tests/api/test_pool.py::test_exhausted_pool_answers_503_in_bounded_time PASSED [ 50%]
student-tests/api/test_pool.py::test_statement_timeout_is_set_on_connections PASSED [100%]
====================== 2 passed, 232 deselected in 1.87s =======================
File diff suppressed because it is too large Load Diff
+552
View File
@@ -0,0 +1,552 @@
date: 2026-10-28T17:18:31.130Z commit: 6468ee2 17.11
EXPLAIN (ANALYZE, BUFFERS) при plan_cache_mode = force_custom_plan
=== none | largest (284708 сообщений) | first | тёплый кэш
Limit (cost=35863.74..35869.69 rows=51 width=176) (actual time=19.687..21.080 rows=51 loops=1)
Buffers: shared hit=14320 read=11464
-> Gather Merge (cost=35863.74..63557.67 rows=237360 width=176) (actual time=19.686..21.077 rows=51 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=14320 read=11464
-> Sort (cost=34863.71..35160.41 rows=118680 width=176) (actual time=18.751..18.753 rows=51 loops=3)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 38kB
Buffers: shared hit=14320 read=11464
Worker 0: Sort Method: top-N heapsort Memory: 38kB
Worker 1: Sort Method: top-N heapsort Memory: 38kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=118680 width=176) (actual time=0.013..14.715 rows=94903 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Rows Removed by Filter: 238428
Buffers: shared hit=14232 read=11464
Planning Time: 0.059 ms
Execution Time: 21.103 ms
=== none | largest (284708 сообщений) | keyset_deep | тёплый кэш
Limit (cost=34387.32..34393.27 rows=51 width=176) (actual time=17.737..18.764 rows=51 loops=1)
Buffers: shared hit=702 read=25024
-> Gather Merge (cost=34387.32..37182.85 rows=23960 width=176) (actual time=17.736..18.761 rows=51 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=702 read=25024
-> Sort (cost=33387.29..33417.24 rows=11980 width=176) (actual time=16.550..16.551 rows=34 loops=3)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 38kB
Buffers: shared hit=702 read=25024
Worker 0: Sort Method: top-N heapsort Memory: 38kB
Worker 1: Sort Method: top-N heapsort Memory: 38kB
-> Parallel Seq Scan on messages (cost=0.00..32987.62 rows=11980 width=176) (actual time=5.403..16.125 rows=9490 loops=3)
Filter: ((chat_id = '00000000-0000-7000-8000-000000000001'::uuid) AND (ROW(created_at, id) > ROW('2026-01-27 23:59:58.179187+00'::timestamp with time zone, '00000001-0000-7000-8002-00000003e8ed'::uuid)))
Rows Removed by Filter: 323841
Buffers: shared hit=672 read=25024
Planning Time: 0.083 ms
Execution Time: 18.778 ms
=== none | largest (284708 сообщений) | offset_deep | тёплый кэш
Limit (cost=79744.03..79744.15 rows=1 width=176) (actual time=58.869..60.326 rows=51 loops=1)
Buffers: shared hit=760 read=25024, temp read=6161 written=6660
-> Gather Merge (cost=52050.10..79744.03 rows=237360 width=176) (actual time=26.697..55.317 rows=256288 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=760 read=25024, temp read=6161 written=6660
-> Sort (cost=51050.07..51346.77 rows=118680 width=176) (actual time=25.251..31.125 rows=85598 loops=3)
Sort Key: created_at, id
Sort Method: external merge Disk: 18360kB
Buffers: shared hit=760 read=25024, temp read=6161 written=6660
Worker 0: Sort Method: external merge Disk: 16632kB
Worker 1: Sort Method: external merge Disk: 18144kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=118680 width=176) (actual time=0.018..14.215 rows=94903 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Rows Removed by Filter: 238428
Buffers: shared hit=672 read=25024
Planning Time: 0.074 ms
Execution Time: 60.862 ms
=== none | chat_50 (1761 сообщений) | first | тёплый кэш
Limit (cost=31923.34..31929.29 rows=51 width=176) (actual time=13.382..14.353 rows=51 loops=1)
Buffers: shared hit=760 read=25024
-> Gather Merge (cost=31923.34..32056.35 rows=1140 width=176) (actual time=13.381..14.350 rows=51 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=760 read=25024
-> Sort (cost=30923.31..30924.74 rows=570 width=176) (actual time=12.427..12.429 rows=51 loops=3)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 38kB
Buffers: shared hit=760 read=25024
Worker 0: Sort Method: top-N heapsort Memory: 38kB
Worker 1: Sort Method: top-N heapsort Memory: 38kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=570 width=176) (actual time=10.425..12.342 rows=587 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Rows Removed by Filter: 332744
Buffers: shared hit=672 read=25024
Planning Time: 0.070 ms
Execution Time: 14.366 ms
=== none | chat_50 (1761 сообщений) | keyset_deep | тёплый кэш
Limit (cost=33989.34..33995.29 rows=51 width=176) (actual time=14.321..15.468 rows=51 loops=1)
Buffers: shared hit=702 read=25024
-> Gather Merge (cost=33989.34..34002.87 rows=116 width=176) (actual time=14.321..15.465 rows=51 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=702 read=25024
-> Sort (cost=32989.31..32989.46 rows=58 width=176) (actual time=13.344..13.345 rows=17 loops=3)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 38kB
Buffers: shared hit=702 read=25024
Worker 0: Sort Method: quicksort Memory: 25kB
Worker 1: Sort Method: quicksort Memory: 25kB
-> Parallel Seq Scan on messages (cost=0.00..32987.62 rows=58 width=176) (actual time=12.630..13.319 rows=59 loops=3)
Filter: ((chat_id = '00000000-0000-7000-8000-000000000032'::uuid) AND (ROW(created_at, id) > ROW('2026-01-27 23:37:55.298126+00'::timestamp with time zone, '00000032-0000-7000-8002-000000000630'::uuid)))
Rows Removed by Filter: 333272
Buffers: shared hit=672 read=25024
Planning Time: 0.067 ms
Execution Time: 15.485 ms
=== none | chat_50 (1761 сообщений) | offset_deep | тёплый кэш
Limit (cost=32063.42..32063.54 rows=1 width=176) (actual time=15.830..16.873 rows=51 loops=1)
Buffers: shared hit=760 read=25024
-> Gather Merge (cost=31930.41..32063.42 rows=1140 width=176) (actual time=15.600..16.837 rows=1635 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=760 read=25024
-> Sort (cost=30930.39..30931.81 rows=570 width=176) (actual time=14.374..14.389 rows=587 loops=3)
Sort Key: created_at, id
Sort Method: quicksort Memory: 185kB
Buffers: shared hit=760 read=25024
Worker 0: Sort Method: quicksort Memory: 186kB
Worker 1: Sort Method: quicksort Memory: 157kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=570 width=176) (actual time=11.973..14.250 rows=587 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Rows Removed by Filter: 332744
Buffers: shared hit=672 read=25024
Planning Time: 0.096 ms
Execution Time: 16.898 ms
=== none | smallest (36 сообщений) | first | тёплый кэш
Limit (cost=31906.17..31912.12 rows=51 width=176) (actual time=13.734..14.652 rows=36 loops=1)
Buffers: shared hit=760 read=25024
-> Gather Merge (cost=31906.17..31920.63 rows=124 width=176) (actual time=13.733..14.648 rows=36 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=760 read=25024
-> Sort (cost=30906.14..30906.30 rows=62 width=176) (actual time=12.758..12.758 rows=12 loops=3)
Sort Key: created_at, id
Sort Method: quicksort Memory: 26kB
Buffers: shared hit=760 read=25024
Worker 0: Sort Method: quicksort Memory: 25kB
Worker 1: Sort Method: quicksort Memory: 32kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=62 width=176) (actual time=12.709..12.709 rows=12 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Rows Removed by Filter: 333319
Buffers: shared hit=672 read=25024
Planning Time: 0.066 ms
Execution Time: 14.661 ms
=== none | smallest (36 сообщений) | keyset_deep | тёплый кэш
Limit (cost=33987.74..33989.37 rows=14 width=176) (actual time=15.901..16.837 rows=4 loops=1)
Buffers: shared hit=702 read=25024
-> Gather Merge (cost=33987.74..33989.37 rows=14 width=176) (actual time=15.900..16.836 rows=4 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=702 read=25024
-> Sort (cost=32987.71..32987.73 rows=7 width=176) (actual time=14.760..14.760 rows=1 loops=3)
Sort Key: created_at, id
Sort Method: quicksort Memory: 25kB
Buffers: shared hit=702 read=25024
Worker 0: Sort Method: quicksort Memory: 26kB
Worker 1: Sort Method: quicksort Memory: 25kB
-> Parallel Seq Scan on messages (cost=0.00..32987.62 rows=7 width=176) (actual time=14.740..14.741 rows=1 loops=3)
Filter: ((chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid) AND (ROW(created_at, id) > ROW('2026-01-27 16:00:00+00'::timestamp with time zone, '000003e8-0000-7000-8002-000000000020'::uuid)))
Rows Removed by Filter: 333330
Buffers: shared hit=672 read=25024
Planning Time: 0.106 ms
Execution Time: 16.849 ms
=== none | smallest (36 сообщений) | offset_deep | тёплый кэш
Limit (cost=31909.90..31915.85 rows=51 width=176) (actual time=13.819..14.716 rows=4 loops=1)
Buffers: shared hit=760 read=25024
-> Gather Merge (cost=31906.17..31920.63 rows=124 width=176) (actual time=13.806..14.706 rows=36 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=760 read=25024
-> Sort (cost=30906.14..30906.30 rows=62 width=176) (actual time=12.679..12.679 rows=12 loops=3)
Sort Key: created_at, id
Sort Method: quicksort Memory: 26kB
Buffers: shared hit=760 read=25024
Worker 0: Sort Method: quicksort Memory: 25kB
Worker 1: Sort Method: quicksort Memory: 32kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=62 width=176) (actual time=12.627..12.628 rows=12 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Rows Removed by Filter: 333319
Buffers: shared hit=672 read=25024
Planning Time: 0.075 ms
Execution Time: 14.727 ms
=== chat_id | largest (284708 сообщений) | first | тёплый кэш
Limit (cost=16437.64..16443.59 rows=51 width=176) (actual time=10.754..11.724 rows=51 loops=1)
Buffers: shared hit=7866
-> Gather Merge (cost=16437.64..43836.62 rows=234832 width=176) (actual time=10.754..11.722 rows=51 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=7866
-> Sort (cost=15437.62..15731.16 rows=117416 width=176) (actual time=9.806..9.807 rows=51 loops=3)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 38kB
Buffers: shared hit=7866
Worker 0: Sort Method: top-N heapsort Memory: 38kB
Worker 1: Sort Method: top-N heapsort Memory: 38kB
-> Parallel Index Scan using track_chat_idx on messages (cost=0.42..11520.37 rows=117416 width=176) (actual time=0.006..5.561 rows=94903 loops=3)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Buffers: shared hit=7836
Planning Time: 0.068 ms
Execution Time: 11.738 ms
=== chat_id | largest (284708 сообщений) | keyset_deep | тёплый кэш
Limit (cost=13498.08..13504.03 rows=51 width=176) (actual time=6.926..7.877 rows=51 loops=1)
Buffers: shared hit=7848
-> Gather Merge (cost=13498.08..16230.14 rows=23416 width=176) (actual time=6.925..7.874 rows=51 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=7848
-> Sort (cost=12498.05..12527.32 rows=11708 width=176) (actual time=5.778..5.779 rows=51 loops=3)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 38kB
Buffers: shared hit=7848
Worker 0: Sort Method: top-N heapsort Memory: 38kB
Worker 1: Sort Method: top-N heapsort Memory: 38kB
-> Parallel Index Scan using track_chat_idx on messages (cost=0.42..12107.45 rows=11708 width=176) (actual time=4.661..5.364 rows=9490 loops=3)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Filter: (ROW(created_at, id) > ROW('2026-01-27 23:59:58.179187+00'::timestamp with time zone, '00000001-0000-7000-8002-00000003e8ed'::uuid))
Rows Removed by Filter: 85412
Buffers: shared hit=7818
Planning Time: 0.087 ms
Execution Time: 7.900 ms
=== chat_id | largest (284708 сообщений) | offset_deep | тёплый кэш
Limit (cost=59841.05..59841.16 rows=1 width=176) (actual time=56.297..59.389 rows=51 loops=1)
Buffers: shared hit=7849, temp read=6290 written=6665
-> Gather Merge (cost=32442.07..59841.05 rows=234832 width=176) (actual time=20.056..54.066 rows=256288 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=7849, temp read=6290 written=6665
-> Sort (cost=31442.04..31735.58 rows=117416 width=176) (actual time=18.834..24.515 rows=85603 loops=3)
Sort Key: created_at, id
Sort Method: external merge Disk: 19728kB
Buffers: shared hit=7849, temp read=6290 written=6665
Worker 0: Sort Method: external merge Disk: 16616kB
Worker 1: Sort Method: external merge Disk: 16824kB
-> Parallel Index Scan using track_chat_idx on messages (cost=0.42..11520.37 rows=117416 width=176) (actual time=0.014..6.727 rows=94903 loops=3)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Buffers: shared hit=7819
Planning Time: 0.104 ms
Execution Time: 60.257 ms
=== chat_id | chat_50 (1761 сообщений) | first | тёплый кэш
Limit (cost=139.43..139.56 rows=51 width=176) (actual time=0.197..0.200 rows=51 loops=1)
Buffers: shared hit=50
-> Sort (cost=139.43..143.60 rows=1667 width=176) (actual time=0.197..0.198 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 38kB
Buffers: shared hit=50
-> Index Scan using track_chat_idx on messages (cost=0.42..83.82 rows=1667 width=176) (actual time=0.010..0.109 rows=1761 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Buffers: shared hit=50
Planning Time: 0.064 ms
Execution Time: 0.211 ms
=== chat_id | chat_50 (1761 сообщений) | keyset_deep | тёплый кэш
Limit (cost=97.73..97.85 rows=51 width=176) (actual time=0.095..0.098 rows=51 loops=1)
Buffers: shared hit=50
-> Sort (cost=97.73..98.14 rows=167 width=176) (actual time=0.095..0.097 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 38kB
Buffers: shared hit=50
-> Index Scan using track_chat_idx on messages (cost=0.42..92.15 rows=167 width=176) (actual time=0.072..0.083 rows=177 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Filter: (ROW(created_at, id) > ROW('2026-01-27 23:37:55.298126+00'::timestamp with time zone, '00000032-0000-7000-8002-000000000630'::uuid))
Rows Removed by Filter: 1584
Buffers: shared hit=50
Planning Time: 0.024 ms
Execution Time: 0.105 ms
=== chat_id | chat_50 (1761 сообщений) | offset_deep | тёплый кэш
Limit (cost=176.99..177.12 rows=51 width=176) (actual time=0.300..0.304 rows=51 loops=1)
Buffers: shared hit=50
-> Sort (cost=173.03..177.20 rows=1667 width=176) (actual time=0.232..0.270 rows=1635 loops=1)
Sort Key: created_at, id
Sort Method: quicksort Memory: 503kB
Buffers: shared hit=50
-> Index Scan using track_chat_idx on messages (cost=0.42..83.82 rows=1667 width=176) (actual time=0.004..0.086 rows=1761 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Buffers: shared hit=50
Planning Time: 0.022 ms
Execution Time: 0.320 ms
=== chat_id | smallest (36 сообщений) | first | тёплый кэш
Limit (cost=19.13..19.25 rows=51 width=176) (actual time=0.012..0.014 rows=36 loops=1)
Buffers: shared hit=5
-> Sort (cost=19.13..19.50 rows=151 width=176) (actual time=0.011..0.012 rows=36 loops=1)
Sort Key: created_at, id
Sort Method: quicksort Memory: 34kB
Buffers: shared hit=5
-> Index Scan using track_chat_idx on messages (cost=0.42..14.09 rows=151 width=176) (actual time=0.005..0.007 rows=36 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Buffers: shared hit=5
Planning Time: 0.037 ms
Execution Time: 0.023 ms
=== chat_id | smallest (36 сообщений) | keyset_deep | тёплый кэш
Limit (cost=15.19..15.23 rows=17 width=176) (actual time=0.012..0.013 rows=4 loops=1)
Buffers: shared hit=5
-> Sort (cost=15.19..15.23 rows=17 width=176) (actual time=0.012..0.012 rows=4 loops=1)
Sort Key: created_at, id
Sort Method: quicksort Memory: 26kB
Buffers: shared hit=5
-> Index Scan using track_chat_idx on messages (cost=0.42..14.84 rows=17 width=176) (actual time=0.008..0.008 rows=4 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Filter: (ROW(created_at, id) > ROW('2026-01-27 16:00:00+00'::timestamp with time zone, '000003e8-0000-7000-8002-000000000020'::uuid))
Rows Removed by Filter: 32
Buffers: shared hit=5
Planning Time: 0.076 ms
Execution Time: 0.021 ms
=== chat_id | smallest (36 сообщений) | offset_deep | тёплый кэш
Limit (cost=19.63..19.76 rows=51 width=176) (actual time=0.017..0.018 rows=4 loops=1)
Buffers: shared hit=5
-> Sort (cost=19.55..19.93 rows=151 width=176) (actual time=0.016..0.017 rows=36 loops=1)
Sort Key: created_at, id
Sort Method: quicksort Memory: 34kB
Buffers: shared hit=5
-> Index Scan using track_chat_idx on messages (cost=0.42..14.09 rows=151 width=176) (actual time=0.008..0.010 rows=36 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Buffers: shared hit=5
Planning Time: 0.070 ms
Execution Time: 0.026 ms
=== created_at_id | largest (284708 сообщений) | first | тёплый кэш
Limit (cost=0.42..25.26 rows=51 width=176) (actual time=0.010..0.031 rows=51 loops=1)
Buffers: shared hit=113
-> Index Scan using track_time_idx on messages (cost=0.42..139575.12 rows=286631 width=176) (actual time=0.010..0.028 rows=51 loops=1)
Filter: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Rows Removed by Filter: 73
Buffers: shared hit=113
Planning Time: 0.053 ms
Execution Time: 0.039 ms
=== created_at_id | largest (284708 сообщений) | keyset_deep | тёплый кэш
Limit (cost=0.42..188.15 rows=51 width=176) (actual time=0.027..0.052 rows=51 loops=1)
Buffers: shared hit=251
-> Index Scan using track_time_idx on messages (cost=0.42..106136.95 rows=28835 width=176) (actual time=0.027..0.049 rows=51 loops=1)
Index Cond: (ROW(created_at, id) > ROW('2026-01-27 23:59:58.179187+00'::timestamp with time zone, '00000001-0000-7000-8002-00000003e8ed'::uuid))
Filter: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Rows Removed by Filter: 200
Buffers: shared hit=251
Planning Time: 0.035 ms
Execution Time: 0.058 ms
=== created_at_id | largest (284708 сообщений) | offset_deep | тёплый кэш
Limit (cost=80050.68..80050.80 rows=1 width=176) (actual time=59.207..60.934 rows=51 loops=1)
Buffers: shared hit=807 read=24977, temp read=6253 written=6661
-> Gather Merge (cost=52181.74..80050.68 rows=238860 width=176) (actual time=26.737..55.792 rows=256288 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=807 read=24977, temp read=6253 written=6661
-> Sort (cost=51181.71..51480.29 rows=119430 width=176) (actual time=25.560..31.143 rows=85575 loops=3)
Sort Key: created_at, id
Sort Method: external merge Disk: 18736kB
Buffers: shared hit=807 read=24977, temp read=6253 written=6661
Worker 0: Sort Method: external merge Disk: 16960kB
Worker 1: Sort Method: external merge Disk: 17440kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=119430 width=176) (actual time=0.016..14.329 rows=94903 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Rows Removed by Filter: 238428
Buffers: shared hit=719 read=24977
Planning Time: 0.097 ms
Execution Time: 61.612 ms
=== created_at_id | chat_50 (1761 сообщений) | first | тёплый кэш
Limit (cost=0.42..3813.12 rows=51 width=176) (actual time=0.065..3.258 rows=51 loops=1)
Buffers: shared hit=28010
-> Index Scan using track_time_idx on messages (cost=0.42..139575.12 rows=1867 width=176) (actual time=0.065..3.254 rows=51 loops=1)
Filter: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Rows Removed by Filter: 28460
Buffers: shared hit=28010
Planning Time: 0.053 ms
Execution Time: 3.268 ms
=== created_at_id | chat_50 (1761 сообщений) | keyset_deep | тёплый кэш
Limit (cost=0.42..28646.45 rows=51 width=176) (actual time=0.099..3.240 rows=51 loops=1)
Buffers: shared hit=28414
-> Index Scan using track_time_idx on messages (cost=0.42..106159.22 rows=189 width=176) (actual time=0.099..3.236 rows=51 loops=1)
Index Cond: (ROW(created_at, id) > ROW('2026-01-27 23:37:55.298126+00'::timestamp with time zone, '00000032-0000-7000-8002-000000000630'::uuid))
Filter: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Rows Removed by Filter: 28907
Buffers: shared hit=28414
Planning Time: 0.038 ms
Execution Time: 3.251 ms
=== created_at_id | chat_50 (1761 сообщений) | offset_deep | тёплый кэш
Limit (cost=32123.22..32123.34 rows=1 width=176) (actual time=14.536..15.478 rows=51 loops=1)
Buffers: shared hit=2431 read=23353
-> Gather Merge (cost=31941.68..32123.22 rows=1556 width=176) (actual time=14.355..15.443 rows=1635 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=2431 read=23353
-> Sort (cost=30941.65..30943.60 rows=778 width=176) (actual time=13.244..13.265 rows=587 loops=3)
Sort Key: created_at, id
Sort Method: quicksort Memory: 185kB
Buffers: shared hit=2431 read=23353
Worker 0: Sort Method: quicksort Memory: 157kB
Worker 1: Sort Method: quicksort Memory: 186kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=778 width=176) (actual time=10.936..13.123 rows=587 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Rows Removed by Filter: 332744
Buffers: shared hit=2343 read=23353
Planning Time: 0.099 ms
Execution Time: 15.503 ms
=== created_at_id | smallest (36 сообщений) | first | тёплый кэш
Limit (cost=31906.17..31912.12 rows=51 width=176) (actual time=13.930..15.035 rows=36 loops=1)
Buffers: shared hit=760 read=25024
-> Gather Merge (cost=31906.17..31920.63 rows=124 width=176) (actual time=13.929..15.033 rows=36 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=760 read=25024
-> Sort (cost=30906.14..30906.30 rows=62 width=176) (actual time=12.920..12.920 rows=12 loops=3)
Sort Key: created_at, id
Sort Method: quicksort Memory: 32kB
Buffers: shared hit=760 read=25024
Worker 0: Sort Method: quicksort Memory: 26kB
Worker 1: Sort Method: quicksort Memory: 25kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=62 width=176) (actual time=12.870..12.871 rows=12 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Rows Removed by Filter: 333319
Buffers: shared hit=672 read=25024
Planning Time: 0.091 ms
Execution Time: 15.047 ms
=== created_at_id | smallest (36 сообщений) | keyset_deep | тёплый кэш
Limit (cost=30560.11..30561.75 rows=14 width=176) (actual time=5.528..6.445 rows=4 loops=1)
Buffers: shared hit=4524
-> Gather Merge (cost=30560.11..30561.75 rows=14 width=176) (actual time=5.528..6.444 rows=4 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=4524
-> Sort (cost=29560.09..29560.11 rows=7 width=176) (actual time=4.643..4.643 rows=1 loops=3)
Sort Key: created_at, id
Sort Method: quicksort Memory: 25kB
Buffers: shared hit=4524
Worker 0: Sort Method: quicksort Memory: 25kB
Worker 1: Sort Method: quicksort Memory: 26kB
-> Parallel Bitmap Heap Scan on messages (cost=3049.84..29559.99 rows=7 width=176) (actual time=4.627..4.627 rows=1 loops=3)
Recheck Cond: (ROW(created_at, id) > ROW('2026-01-27 16:00:00+00'::timestamp with time zone, '000003e8-0000-7000-8002-000000000020'::uuid))
Filter: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Rows Removed by Filter: 37186
Heap Blocks: exact=1618
Buffers: shared hit=4494
-> Bitmap Index Scan on track_time_idx (cost=0.00..3049.84 rows=111655 width=0) (actual time=3.125..3.125 rows=111561 loops=1)
Index Cond: (ROW(created_at, id) > ROW('2026-01-27 16:00:00+00'::timestamp with time zone, '000003e8-0000-7000-8002-000000000020'::uuid))
Buffers: shared hit=553
Planning Time: 0.069 ms
Execution Time: 6.464 ms
=== created_at_id | smallest (36 сообщений) | offset_deep | тёплый кэш
Limit (cost=31909.90..31915.85 rows=51 width=176) (actual time=14.001..15.088 rows=4 loops=1)
Buffers: shared hit=4605 read=21179
-> Gather Merge (cost=31906.17..31920.63 rows=124 width=176) (actual time=13.998..15.086 rows=36 loops=1)
Workers Planned: 2
Workers Launched: 2
Buffers: shared hit=4605 read=21179
-> Sort (cost=30906.14..30906.30 rows=62 width=176) (actual time=13.028..13.029 rows=12 loops=3)
Sort Key: created_at, id
Sort Method: quicksort Memory: 25kB
Buffers: shared hit=4605 read=21179
Worker 0: Sort Method: quicksort Memory: 32kB
Worker 1: Sort Method: quicksort Memory: 26kB
-> Parallel Seq Scan on messages (cost=0.00..30904.30 rows=62 width=176) (actual time=12.975..12.976 rows=12 loops=3)
Filter: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Rows Removed by Filter: 333319
Buffers: shared hit=4517 read=21179
Planning Time: 0.090 ms
Execution Time: 15.100 ms
=== chat_id_created_at_id | largest (284708 сообщений) | first | тёплый кэш
Limit (cost=0.42..11.49 rows=51 width=176) (actual time=0.008..0.014 rows=51 loops=1)
Buffers: shared hit=5
-> Index Scan using messages_history_idx on messages (cost=0.42..62439.90 rows=287698 width=176) (actual time=0.008..0.011 rows=51 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Buffers: shared hit=5
Planning Time: 0.035 ms
Execution Time: 0.020 ms
=== chat_id_created_at_id | largest (284708 сообщений) | keyset_deep | тёплый кэш
Limit (cost=0.42..61.18 rows=51 width=176) (actual time=0.009..0.014 rows=51 loops=1)
Buffers: shared hit=5
-> Index Scan using messages_history_idx on messages (cost=0.42..33769.77 rows=28348 width=176) (actual time=0.008..0.011 rows=51 loops=1)
Index Cond: ((chat_id = '00000000-0000-7000-8000-000000000001'::uuid) AND (ROW(created_at, id) > ROW('2026-01-27 23:59:58.179187+00'::timestamp with time zone, '00000001-0000-7000-8002-00000003e8ed'::uuid)))
Buffers: shared hit=5
Planning Time: 0.050 ms
Execution Time: 0.023 ms
=== chat_id_created_at_id | largest (284708 сообщений) | offset_deep | тёплый кэш
Limit (cost=55611.87..55622.94 rows=51 width=176) (actual time=21.642..21.647 rows=51 loops=1)
Buffers: shared hit=9012
-> Index Scan using messages_history_idx on messages (cost=0.42..62439.90 rows=287698 width=176) (actual time=0.011..16.618 rows=256288 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000001'::uuid)
Buffers: shared hit=9012
Planning Time: 0.078 ms
Execution Time: 21.666 ms
=== chat_id_created_at_id | chat_50 (1761 сообщений) | first | тёплый кэш
Limit (cost=0.42..90.76 rows=51 width=176) (actual time=0.006..0.011 rows=51 loops=1)
Buffers: shared hit=5
-> Index Scan using messages_history_idx on messages (cost=0.42..2303.01 rows=1300 width=176) (actual time=0.006..0.008 rows=51 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Buffers: shared hit=5
Planning Time: 0.034 ms
Execution Time: 0.018 ms
=== chat_id_created_at_id | chat_50 (1761 сообщений) | keyset_deep | тёплый кэш
Limit (cost=0.42..93.83 rows=51 width=176) (actual time=0.006..0.013 rows=51 loops=1)
Buffers: shared hit=6
-> Index Scan using messages_history_idx on messages (cost=0.42..236.70 rows=129 width=176) (actual time=0.006..0.011 rows=51 loops=1)
Index Cond: ((chat_id = '00000000-0000-7000-8000-000000000032'::uuid) AND (ROW(created_at, id) > ROW('2026-01-27 23:37:55.298126+00'::timestamp with time zone, '00000032-0000-7000-8002-000000000630'::uuid)))
Buffers: shared hit=6
Planning Time: 0.049 ms
Execution Time: 0.020 ms
=== chat_id_created_at_id | chat_50 (1761 сообщений) | offset_deep | тёплый кэш
Limit (cost=2303.01..2304.79 rows=1 width=176) (actual time=0.158..0.164 rows=51 loops=1)
Buffers: shared hit=64
-> Index Scan using messages_history_idx on messages (cost=0.42..2303.01 rows=1300 width=176) (actual time=0.005..0.125 rows=1635 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-000000000032'::uuid)
Buffers: shared hit=64
Planning Time: 0.031 ms
Execution Time: 0.170 ms
=== chat_id_created_at_id | smallest (36 сообщений) | first | тёплый кэш
Limit (cost=0.42..94.71 rows=51 width=176) (actual time=0.006..0.010 rows=36 loops=1)
Buffers: shared hit=5
-> Index Scan using messages_history_idx on messages (cost=0.42..272.19 rows=147 width=176) (actual time=0.006..0.009 rows=36 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Buffers: shared hit=5
Planning Time: 0.044 ms
Execution Time: 0.016 ms
=== chat_id_created_at_id | smallest (36 сообщений) | keyset_deep | тёплый кэш
Limit (cost=0.42..35.00 rows=16 width=176) (actual time=0.005..0.006 rows=4 loops=1)
Buffers: shared hit=4
-> Index Scan using messages_history_idx on messages (cost=0.42..35.00 rows=16 width=176) (actual time=0.005..0.006 rows=4 loops=1)
Index Cond: ((chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid) AND (ROW(created_at, id) > ROW('2026-01-27 16:00:00+00'::timestamp with time zone, '000003e8-0000-7000-8002-000000000020'::uuid)))
Buffers: shared hit=4
Planning Time: 0.039 ms
Execution Time: 0.012 ms
=== chat_id_created_at_id | smallest (36 сообщений) | offset_deep | тёплый кэш
Limit (cost=59.58..153.87 rows=51 width=176) (actual time=0.008..0.009 rows=4 loops=1)
Buffers: shared hit=5
-> Index Scan using messages_history_idx on messages (cost=0.42..272.19 rows=147 width=176) (actual time=0.005..0.007 rows=36 loops=1)
Index Cond: (chat_id = '00000000-0000-7000-8000-0000000003e8'::uuid)
Buffers: shared hit=5
Planning Time: 0.040 ms
Execution Time: 0.015 ms
+608
View File
@@ -0,0 +1,608 @@
{
"meta": {
"date": "2026-10-28T17:28:48.636Z",
"commit": "6468ee2",
"postgres": "17.11"
},
"method": "время начала и конца pg_dump — clock_timestamp() PostgreSQL источника, теми же часами, что created_at маркеров",
"runs": [
{
"messages": 100011,
"attempt": 1,
"dataset": {
"messages": 100011,
"chats": 1000,
"zipf_s": 1.3,
"largest": 28471,
"chat_50": 176,
"smallest": 4,
"largest_share": 0.2847,
"top10_share": 0.6507,
"table_bytes": 20922368,
"seed_seconds": 1.1
},
"dump": {
"file": "backups/track-100011.dump",
"bytes": 1685570,
"dump_seconds": 0.15,
"dump_started": "2026-10-28T17:28:52.450145+00:00",
"dump_finished": "2026-10-28T17:28:52.597283+00:00"
},
"instance": {
"volume": "mtusi2026lab2_pgrestore",
"volume_created": "2026-10-28T17:28:53Z"
},
"restore": {
"pre-data_seconds": 0.2,
"data_seconds": 0.35,
"post-data_seconds": 0.22,
"new_instance_seconds": 1.3,
"verify_seconds": 0.19,
"rto_seconds": 2.26
},
"checks": {
"users": true,
"chats": true,
"chat_members": true,
"messages": true,
"migrations": true,
"per_chat_counts_md5": true,
"history_md5_largest": true,
"history_md5_chat_50": true,
"history_md5_smallest": true,
"sample_rows": true,
"sample_md5": true,
"indexes": true,
"constraints": true
},
"all_checks_passed": true,
"source": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 100011,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "b06aba9e2766adec5cc81ea748132e15",
"history_md5_largest": "b810fd78d33a0ba7063788f5a0575bac",
"history_md5_chat_50": "5a9e32b500653af6d41a2e9e601ea154",
"history_md5_smallest": "c1827adf4c8667bc1706113288d6bef6",
"sample_rows": 90,
"sample_md5": "3f0fbfe474b498ff751f283bc2171c62",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 75,
"last_marker_at": "2026-10-28T17:28:53.231617+00:00"
},
"restored": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 100011,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "b06aba9e2766adec5cc81ea748132e15",
"history_md5_largest": "b810fd78d33a0ba7063788f5a0575bac",
"history_md5_chat_50": "5a9e32b500653af6d41a2e9e601ea154",
"history_md5_smallest": "c1827adf4c8667bc1706113288d6bef6",
"sample_rows": 90,
"sample_md5": "3f0fbfe474b498ff751f283bc2171c62",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 41,
"last_marker_at": "2026-10-28T17:28:52.449345+00:00"
},
"rpo": {
"markers_in_source": 75,
"markers_in_backup": 41,
"markers_lost": 34,
"markers_lost_while_dump_was_running": 6,
"last_marker_in_backup": "2026-10-28T17:28:52.449345+00:00",
"dump_started": "2026-10-28T17:28:52.450145+00:00",
"dump_finished": "2026-10-28T17:28:52.597283+00:00"
}
},
{
"messages": 100011,
"attempt": 2,
"dataset": {
"messages": 100011,
"chats": 1000,
"zipf_s": 1.3,
"largest": 28471,
"chat_50": 176,
"smallest": 4,
"largest_share": 0.2847,
"top10_share": 0.6507,
"table_bytes": 20922368,
"seed_seconds": 1.1
},
"dump": {
"file": "backups/track-100011.dump",
"bytes": 1685752,
"dump_seconds": 0.15,
"dump_started": "2026-10-28T17:28:57.537217+00:00",
"dump_finished": "2026-10-28T17:28:57.682906+00:00"
},
"instance": {
"volume": "mtusi2026lab2_pgrestore",
"volume_created": "2026-10-28T17:28:59Z"
},
"restore": {
"pre-data_seconds": 0.14,
"data_seconds": 0.35,
"post-data_seconds": 0.23,
"new_instance_seconds": 1.26,
"verify_seconds": 0.19,
"rto_seconds": 2.17
},
"checks": {
"users": true,
"chats": true,
"chat_members": true,
"messages": true,
"migrations": true,
"per_chat_counts_md5": true,
"history_md5_largest": true,
"history_md5_chat_50": true,
"history_md5_smallest": true,
"sample_rows": true,
"sample_md5": true,
"indexes": true,
"constraints": true
},
"all_checks_passed": true,
"source": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 100011,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "b06aba9e2766adec5cc81ea748132e15",
"history_md5_largest": "b810fd78d33a0ba7063788f5a0575bac",
"history_md5_chat_50": "5a9e32b500653af6d41a2e9e601ea154",
"history_md5_smallest": "c1827adf4c8667bc1706113288d6bef6",
"sample_rows": 90,
"sample_md5": "3f0fbfe474b498ff751f283bc2171c62",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 77,
"last_marker_at": "2026-10-28T17:28:58.333567+00:00"
},
"restored": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 100011,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "b06aba9e2766adec5cc81ea748132e15",
"history_md5_largest": "b810fd78d33a0ba7063788f5a0575bac",
"history_md5_chat_50": "5a9e32b500653af6d41a2e9e601ea154",
"history_md5_smallest": "c1827adf4c8667bc1706113288d6bef6",
"sample_rows": 90,
"sample_md5": "3f0fbfe474b498ff751f283bc2171c62",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 43,
"last_marker_at": "2026-10-28T17:28:57.534265+00:00"
},
"rpo": {
"markers_in_source": 77,
"markers_in_backup": 43,
"markers_lost": 34,
"markers_lost_while_dump_was_running": 6,
"last_marker_in_backup": "2026-10-28T17:28:57.534265+00:00",
"dump_started": "2026-10-28T17:28:57.537217+00:00",
"dump_finished": "2026-10-28T17:28:57.682906+00:00"
}
},
{
"messages": 100011,
"attempt": 3,
"dataset": {
"messages": 100011,
"chats": 1000,
"zipf_s": 1.3,
"largest": 28471,
"chat_50": 176,
"smallest": 4,
"largest_share": 0.2847,
"top10_share": 0.6507,
"table_bytes": 20922368,
"seed_seconds": 1.1
},
"dump": {
"file": "backups/track-100011.dump",
"bytes": 1685825,
"dump_seconds": 0.15,
"dump_started": "2026-10-28T17:29:02.671832+00:00",
"dump_finished": "2026-10-28T17:29:02.819966+00:00"
},
"instance": {
"volume": "mtusi2026lab2_pgrestore",
"volume_created": "2026-10-28T17:29:04Z"
},
"restore": {
"pre-data_seconds": 0.16,
"data_seconds": 0.34,
"post-data_seconds": 0.22,
"new_instance_seconds": 1.26,
"verify_seconds": 0.19,
"rto_seconds": 2.17
},
"checks": {
"users": true,
"chats": true,
"chat_members": true,
"messages": true,
"migrations": true,
"per_chat_counts_md5": true,
"history_md5_largest": true,
"history_md5_chat_50": true,
"history_md5_smallest": true,
"sample_rows": true,
"sample_md5": true,
"indexes": true,
"constraints": true
},
"all_checks_passed": true,
"source": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 100011,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "b06aba9e2766adec5cc81ea748132e15",
"history_md5_largest": "b810fd78d33a0ba7063788f5a0575bac",
"history_md5_chat_50": "5a9e32b500653af6d41a2e9e601ea154",
"history_md5_smallest": "c1827adf4c8667bc1706113288d6bef6",
"sample_rows": 90,
"sample_md5": "3f0fbfe474b498ff751f283bc2171c62",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 76,
"last_marker_at": "2026-10-28T17:29:03.454521+00:00"
},
"restored": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 100011,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "b06aba9e2766adec5cc81ea748132e15",
"history_md5_largest": "b810fd78d33a0ba7063788f5a0575bac",
"history_md5_chat_50": "5a9e32b500653af6d41a2e9e601ea154",
"history_md5_smallest": "c1827adf4c8667bc1706113288d6bef6",
"sample_rows": 90,
"sample_md5": "3f0fbfe474b498ff751f283bc2171c62",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 43,
"last_marker_at": "2026-10-28T17:29:02.670566+00:00"
},
"rpo": {
"markers_in_source": 76,
"markers_in_backup": 43,
"markers_lost": 33,
"markers_lost_while_dump_was_running": 7,
"last_marker_in_backup": "2026-10-28T17:29:02.670566+00:00",
"dump_started": "2026-10-28T17:29:02.671832+00:00",
"dump_finished": "2026-10-28T17:29:02.819966+00:00"
}
},
{
"messages": 999993,
"attempt": 1,
"dataset": {
"messages": 999993,
"chats": 1000,
"zipf_s": 1.3,
"largest": 284708,
"chat_50": 1761,
"smallest": 36,
"largest_share": 0.2847,
"top10_share": 0.6508,
"table_bytes": 210591744,
"seed_seconds": 8.6
},
"dump": {
"file": "backups/track-999993.dump",
"bytes": 15400057,
"dump_seconds": 1.03,
"dump_started": "2026-10-28T17:29:17.903031+00:00",
"dump_finished": "2026-10-28T17:29:18.937636+00:00"
},
"instance": {
"volume": "mtusi2026lab2_pgrestore",
"volume_created": "2026-10-28T17:29:20Z"
},
"restore": {
"pre-data_seconds": 0.17,
"data_seconds": 2.16,
"post-data_seconds": 0.89,
"new_instance_seconds": 1.27,
"verify_seconds": 0.83,
"rto_seconds": 5.32
},
"checks": {
"users": true,
"chats": true,
"chat_members": true,
"messages": true,
"migrations": true,
"per_chat_counts_md5": true,
"history_md5_largest": true,
"history_md5_chat_50": true,
"history_md5_smallest": true,
"sample_rows": true,
"sample_md5": true,
"indexes": true,
"constraints": true
},
"all_checks_passed": true,
"source": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 999993,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "9c9de2270a5df6c52d3c9fa78e788d52",
"history_md5_largest": "d2e65041f85c2b3918b6ed41f90ae912",
"history_md5_chat_50": "507411ae207ce077b612fb47ddd69de8",
"history_md5_smallest": "9c119064d444208cdec773d9dd82c9d6",
"sample_rows": 1005,
"sample_md5": "7ce2113e18546b9191eda7c66c5fcf10",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 118,
"last_marker_at": "2026-10-28T17:29:19.571073+00:00"
},
"restored": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 999993,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "9c9de2270a5df6c52d3c9fa78e788d52",
"history_md5_largest": "d2e65041f85c2b3918b6ed41f90ae912",
"history_md5_chat_50": "507411ae207ce077b612fb47ddd69de8",
"history_md5_smallest": "9c119064d444208cdec773d9dd82c9d6",
"sample_rows": 1005,
"sample_md5": "7ce2113e18546b9191eda7c66c5fcf10",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 42,
"last_marker_at": "2026-10-28T17:29:17.887529+00:00"
},
"rpo": {
"markers_in_source": 118,
"markers_in_backup": 42,
"markers_lost": 76,
"markers_lost_while_dump_was_running": 48,
"last_marker_in_backup": "2026-10-28T17:29:17.887529+00:00",
"dump_started": "2026-10-28T17:29:17.903031+00:00",
"dump_finished": "2026-10-28T17:29:18.937636+00:00"
}
},
{
"messages": 999993,
"attempt": 2,
"dataset": {
"messages": 999993,
"chats": 1000,
"zipf_s": 1.3,
"largest": 284708,
"chat_50": 1761,
"smallest": 36,
"largest_share": 0.2847,
"top10_share": 0.6508,
"table_bytes": 210591744,
"seed_seconds": 8.6
},
"dump": {
"file": "backups/track-999993.dump",
"bytes": 15400357,
"dump_seconds": 1.04,
"dump_started": "2026-10-28T17:29:27.895177+00:00",
"dump_finished": "2026-10-28T17:29:28.932480+00:00"
},
"instance": {
"volume": "mtusi2026lab2_pgrestore",
"volume_created": "2026-10-28T17:29:31Z"
},
"restore": {
"pre-data_seconds": 0.16,
"data_seconds": 2.17,
"post-data_seconds": 0.91,
"new_instance_seconds": 1.27,
"verify_seconds": 0.84,
"rto_seconds": 5.35
},
"checks": {
"users": true,
"chats": true,
"chat_members": true,
"messages": true,
"migrations": true,
"per_chat_counts_md5": true,
"history_md5_largest": true,
"history_md5_chat_50": true,
"history_md5_smallest": true,
"sample_rows": true,
"sample_md5": true,
"indexes": true,
"constraints": true
},
"all_checks_passed": true,
"source": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 999993,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "9c9de2270a5df6c52d3c9fa78e788d52",
"history_md5_largest": "d2e65041f85c2b3918b6ed41f90ae912",
"history_md5_chat_50": "507411ae207ce077b612fb47ddd69de8",
"history_md5_smallest": "9c119064d444208cdec773d9dd82c9d6",
"sample_rows": 1005,
"sample_md5": "7ce2113e18546b9191eda7c66c5fcf10",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 118,
"last_marker_at": "2026-10-28T17:29:29.591525+00:00"
},
"restored": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 999993,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "9c9de2270a5df6c52d3c9fa78e788d52",
"history_md5_largest": "d2e65041f85c2b3918b6ed41f90ae912",
"history_md5_chat_50": "507411ae207ce077b612fb47ddd69de8",
"history_md5_smallest": "9c119064d444208cdec773d9dd82c9d6",
"sample_rows": 1005,
"sample_md5": "7ce2113e18546b9191eda7c66c5fcf10",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 44,
"last_marker_at": "2026-10-28T17:29:27.894289+00:00"
},
"rpo": {
"markers_in_source": 118,
"markers_in_backup": 44,
"markers_lost": 74,
"markers_lost_while_dump_was_running": 46,
"last_marker_in_backup": "2026-10-28T17:29:27.894289+00:00",
"dump_started": "2026-10-28T17:29:27.895177+00:00",
"dump_finished": "2026-10-28T17:29:28.932480+00:00"
}
},
{
"messages": 999993,
"attempt": 3,
"dataset": {
"messages": 999993,
"chats": 1000,
"zipf_s": 1.3,
"largest": 284708,
"chat_50": 1761,
"smallest": 36,
"largest_share": 0.2847,
"top10_share": 0.6508,
"table_bytes": 210591744,
"seed_seconds": 8.6
},
"dump": {
"file": "backups/track-999993.dump",
"bytes": 15400375,
"dump_seconds": 1.05,
"dump_started": "2026-10-28T17:29:38.014765+00:00",
"dump_finished": "2026-10-28T17:29:39.062119+00:00"
},
"instance": {
"volume": "mtusi2026lab2_pgrestore",
"volume_created": "2026-10-28T17:29:41Z"
},
"restore": {
"pre-data_seconds": 0.16,
"data_seconds": 2.13,
"post-data_seconds": 0.91,
"new_instance_seconds": 1.27,
"verify_seconds": 0.84,
"rto_seconds": 5.31
},
"checks": {
"users": true,
"chats": true,
"chat_members": true,
"messages": true,
"migrations": true,
"per_chat_counts_md5": true,
"history_md5_largest": true,
"history_md5_chat_50": true,
"history_md5_smallest": true,
"sample_rows": true,
"sample_md5": true,
"indexes": true,
"constraints": true
},
"all_checks_passed": true,
"source": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 999993,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "9c9de2270a5df6c52d3c9fa78e788d52",
"history_md5_largest": "d2e65041f85c2b3918b6ed41f90ae912",
"history_md5_chat_50": "507411ae207ce077b612fb47ddd69de8",
"history_md5_smallest": "9c119064d444208cdec773d9dd82c9d6",
"sample_rows": 1005,
"sample_md5": "7ce2113e18546b9191eda7c66c5fcf10",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 118,
"last_marker_at": "2026-10-28T17:29:39.704206+00:00"
},
"restored": {
"users": 2000,
"chats": 1000,
"chat_members": 2000,
"messages": 999993,
"migrations": "0001_init:9a13618f078a",
"per_chat_counts_md5": "9c9de2270a5df6c52d3c9fa78e788d52",
"history_md5_largest": "d2e65041f85c2b3918b6ed41f90ae912",
"history_md5_chat_50": "507411ae207ce077b612fb47ddd69de8",
"history_md5_smallest": "9c119064d444208cdec773d9dd82c9d6",
"sample_rows": 1005,
"sample_md5": "7ce2113e18546b9191eda7c66c5fcf10",
"indexes": "chat_members_pkey,chat_members_user_idx,chats_pkey,messages_history_idx,messages_pkey,schema_migrations_pkey,sessions_pkey,sessions_user_idx,users_pkey,users_username_key",
"constraints": 19,
"markers": 43,
"last_marker_at": "2026-10-28T17:29:38.013596+00:00"
},
"rpo": {
"markers_in_source": 118,
"markers_in_backup": 43,
"markers_lost": 75,
"markers_lost_while_dump_was_running": 47,
"last_marker_in_backup": "2026-10-28T17:29:38.013596+00:00",
"dump_started": "2026-10-28T17:29:38.014765+00:00",
"dump_finished": "2026-10-28T17:29:39.062119+00:00"
}
}
],
"summary": [
{
"messages": 100011,
"repeats": 3,
"rto_median_seconds": 2.17,
"rto_range_seconds": [
2.17,
2.26
],
"new_instance_median_seconds": 1.26,
"all_checks_passed": true,
"markers_lost_while_dump_was_running": [
6,
6,
7
]
},
{
"messages": 999993,
"repeats": 3,
"rto_median_seconds": 5.32,
"rto_range_seconds": [
5.31,
5.35
],
"new_instance_median_seconds": 1.27,
"all_checks_passed": true,
"markers_lost_while_dump_was_running": [
48,
46,
47
]
}
]
}
+66
View File
@@ -0,0 +1,66 @@
date: 2026-10-28T17:18:31.130Z commit: 6468ee2 17.11
dataset: {"messages": 999993, "chats": 1000, "zipf_s": 1.3, "largest": 284708, "chat_50": 1761, "smallest": 36, "largest_share": 0.2847, "top10_share": 0.6508, "table_bytes": 210591744, "seed_seconds": 8.1}
variant | chat | query | warm median ms | cold median ms | hit/read (cold) | rows scanned | plan
none | largest | first | 21.986 | 19.778 | 81/25703 | 999993 | Limit > Gather Merge > Sort > Seq Scan
none | largest | keyset_deep | 17.603 | 16.681 | 28/25698 | 999993 | Limit > Gather Merge > Sort > Seq Scan
none | largest | offset_deep | 61.335 | 58.804 | 80/25704 | 999993 | Limit > Gather Merge > Sort > Seq Scan
none | chat_50 | first | 14.505 | 14.59 | 80/25704 | 999993 | Limit > Gather Merge > Sort > Seq Scan
none | chat_50 | keyset_deep | 15.863 | 16.096 | 28/25698 | 999993 | Limit > Gather Merge > Sort > Seq Scan
none | chat_50 | offset_deep | 16.791 | 16.125 | 81/25703 | 999993 | Limit > Gather Merge > Sort > Seq Scan
none | smallest | first | 14.383 | 15.032 | 80/25704 | 999993 | Limit > Gather Merge > Sort > Seq Scan
none | smallest | keyset_deep | 16.15 | 16.268 | 28/25698 | 999993 | Limit > Gather Merge > Sort > Seq Scan
none | smallest | offset_deep | 14.286 | 14.403 | 81/25703 | 999993 | Limit > Gather Merge > Sort > Seq Scan
chat_id | largest | first | 12.189 | 16.475 | 259/7608 | 284709 | Limit > Gather Merge > Sort > Index Scan(track_chat_idx)
chat_id | largest | keyset_deep | 8.294 | 12.737 | 255/7606 | 284706 | Limit > Gather Merge > Sort > Index Scan(track_chat_idx)
chat_id | largest | offset_deep | 55.767 | 63.201 | 240/7606 | 284709 | Limit > Gather Merge > Sort > Index Scan(track_chat_idx)
chat_id | chat_50 | first | 0.185 | 0.276 | 0/50 | 1761 | Limit > Sort > Index Scan(track_chat_idx)
chat_id | chat_50 | keyset_deep | 0.12 | 0.211 | 0/50 | 1761 | Limit > Sort > Index Scan(track_chat_idx)
chat_id | chat_50 | offset_deep | 0.344 | 0.447 | 0/50 | 1761 | Limit > Sort > Index Scan(track_chat_idx)
chat_id | smallest | first | 0.024 | 0.05 | 0/5 | 36 | Limit > Sort > Index Scan(track_chat_idx)
chat_id | smallest | keyset_deep | 0.016 | 0.034 | 0/5 | 36 | Limit > Sort > Index Scan(track_chat_idx)
chat_id | smallest | offset_deep | 0.018 | 0.037 | 0/5 | 36 | Limit > Sort > Index Scan(track_chat_idx)
created_at_id | largest | first | 0.035 | 0.092 | 88/25 | 124 | Limit > Index Scan(track_time_idx)
created_at_id | largest | keyset_deep | 0.065 | 0.325 | 103/148 | 251 | Limit > Index Scan(track_time_idx)
created_at_id | largest | offset_deep | 63.071 | 63.074 | 80/25704 | 999993 | Limit > Gather Merge > Sort > Seq Scan
created_at_id | chat_50 | first | 3.133 | 6.748 | 26118/1892 | 28511 | Limit > Index Scan(track_time_idx)
created_at_id | chat_50 | keyset_deep | 3.226 | 7.116 | 26501/1913 | 28958 | Limit > Index Scan(track_time_idx)
created_at_id | chat_50 | offset_deep | 15.902 | 14.655 | 79/25705 | 999993 | Limit > Gather Merge > Sort > Seq Scan
created_at_id | smallest | first | 14.654 | 14.474 | 80/25704 | 999993 | Limit > Gather Merge > Sort > Seq Scan
created_at_id | smallest | keyset_deep | 6.563 | 10.028 | 28/4496 | 223122 | Limit > Gather Merge > Sort > Bitmap Heap Scan > Bitmap Index Scan(track_time_idx)
created_at_id | smallest | offset_deep | 15.407 | 14.45 | 81/25703 | 999993 | Limit > Gather Merge > Sort > Seq Scan
chat_id_created_at_id | largest | first | 0.022 | 0.036 | 0/5 | 51 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | largest | keyset_deep | 0.024 | 0.035 | 0/5 | 51 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | largest | offset_deep | 19.956 | 33.396 | 559/8453 | 256288 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | chat_50 | first | 0.019 | 0.03 | 0/5 | 51 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | chat_50 | keyset_deep | 0.021 | 0.038 | 0/6 | 51 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | chat_50 | offset_deep | 0.157 | 0.25 | 7/57 | 1635 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | smallest | first | 0.017 | 0.03 | 0/5 | 36 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | smallest | keyset_deep | 0.012 | 0.024 | 0/4 | 4 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | smallest | offset_deep | 0.017 | 0.028 | 0/5 | 36 | Limit > Index Scan(messages_history_idx)
order | variant | commit | build s | table MB | indexes MB | tps median [min..max] | latency ms | WAL bytes/insert | WAL records/insert | FPI/insert | postgres CPU % | postgres MiB
1 | none | sync | 0.0 | 200.8 | 30.1 | 9455.4 [9314.0..9502.3] | 0.423 | 1511 | 6.7 | 0.128 | 272.13 | 281.6
1 | none | async | 0.0 | 200.8 | 30.1 | 12680.5 [12393.0..12819.5] | 0.315 | 1205 | 6.05 | 0.096 | 353.0 | 187.6
2 | chat_id | sync | 0.27 | 200.8 | 44.6 | 9233.4 [7941.2..9603.8] | 0.433 | 1588 | 7.06 | 0.135 | 273.39 | 188.1
2 | chat_id | async | 0.27 | 200.8 | 44.6 | 12496.8 [10742.6..12721.2] | 0.32 | 1303 | 7.04 | 0.1 | 352.39 | 189.5
3 | created_at_id | sync | 0.28 | 200.8 | 76.4 | 9179.6 [9055.4..9539.9] | 0.436 | 1586 | 7.04 | 0.132 | 273.37 | 188.5
3 | created_at_id | async | 0.28 | 200.8 | 76.4 | 12461.2 [12429.2..12625.5] | 0.321 | 1304 | 7.04 | 0.098 | 352.1 | 187.0
4 | chat_id_created_at_id | sync | 0.42 | 200.8 | 94.0 | 9112.6 [8820.8..9447.6] | 0.439 | 1644 | 7.03 | 0.146 | 275.45 | 187.1
4 | chat_id_created_at_id | async | 0.42 | 200.8 | 94.0 | 12443.6 [12368.3..12483.2] | 0.321 | 1365 | 7.04 | 0.11 | 351.74 | 189.5
5 | none | sync | 0.0 | 200.8 | 37.8 | 9345.7 [9278.8..9600.6] | 0.428 | 1483 | 6.03 | 0.13 | 273.66 | 185.0
5 | none | async | 0.0 | 200.8 | 37.8 | 12550.5 [12436.8..12612.4] | 0.319 | 1216 | 6.06 | 0.097 | 353.1 | 184.5
variant | chat | plan_cache_mode | median ms | plan
chat_id | largest | force_custom_plan | 12.96 | Limit > Gather Merge > Sort > Index Scan(track_chat_idx)
chat_id | largest | force_generic_plan | 28.128 | Limit > Sort > Index Scan(track_chat_idx)
chat_id | smallest | force_custom_plan | 0.029 | Limit > Sort > Index Scan(track_chat_idx)
chat_id | smallest | force_generic_plan | 0.026 | Limit > Sort > Index Scan(track_chat_idx)
created_at_id | largest | force_custom_plan | 0.034 | Limit > Index Scan(track_time_idx)
created_at_id | largest | force_generic_plan | 0.039 | Limit > Index Scan(track_time_idx)
created_at_id | smallest | force_custom_plan | 14.9 | Limit > Gather Merge > Sort > Seq Scan
created_at_id | smallest | force_generic_plan | 156.475 | Limit > Index Scan(track_time_idx)
chat_id_created_at_id | largest | force_custom_plan | 0.023 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | largest | force_generic_plan | 0.022 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | smallest | force_custom_plan | 0.021 | Limit > Index Scan(messages_history_idx)
chat_id_created_at_id | smallest | force_generic_plan | 0.015 | Limit > Index Scan(messages_history_idx)
@@ -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, редактирование и удаление сообщений, изменение состава участников и поиск пользователей не реализуются.
@@ -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** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации
@@ -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** отчёт называет, что измерение не доказывает: закрытый контур создаёт согласованные пропуски, клиент и сервер делят одну машину, единственный процесс не даёт отказоустойчивости
@@ -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`
@@ -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** отправленное сообщение присутствует в ответе
@@ -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`
@@ -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` не меняются.
@@ -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.
@@ -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.
@@ -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"`
@@ -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** сообщение получает отметку на одну микросекунду больше последней, и порядок истории сохраняется
@@ -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`.
@@ -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`.
@@ -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`
@@ -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` зелёные
@@ -0,0 +1,4 @@
schema: spec-driven
created: 2026-10-28
archived: 2026-10-28
lab: 2
@@ -0,0 +1,51 @@
## Context
Мотивация — в `proposal.md`. Запрос истории приложения — `WHERE chat_id = $1 [AND (created_at, id) > ($2, $3)] ORDER BY created_at, id LIMIT $n` — выполняется asyncpg как prepared statement. Запись — транзакция `SELECT … FOR UPDATE` строки чата и `INSERT messages` + `UPDATE chats` одним оператором. Индекс уровня «4» — `messages_history_idx (chat_id, created_at, id)`. Стенд — Docker Desktop на Apple M4 Max, VM 16 CPU / 7.65 ГиБ, PostgreSQL 17.11 с настройками по умолчанию (`shared_buffers = 128MB`).
## Goals / Non-Goals
**Goals:**
- Гипотеза проверяема числами: какой индекс и какой способ пагинации держат время страницы независимым от размера чата и глубины страницы, и сколько это стоит на записи.
- Восстановление проверено сверкой, а не фактом завершения `pg_restore`.
- Всё запускается двумя командами и детерминировано.
**Non-Goals:**
- Подбор настроек PostgreSQL, партиционирование, PITR-стенд.
- Нагрузочное тестирование HTTP — шум VM здесь больше эффекта.
## Decisions
### D1. Гипотеза
H1: составной индекс `(chat_id, created_at, id)` с keyset-курсором даёт время страницы O(limit) для любого чата и любой глубины; `(chat_id)` проигрывает на большом чате (сортировка всего чата), `(created_at, id)` — на маленьком (проход по чужим сообщениям), `OFFSET` проигрывает на глубине при любом индексе. H2: каждый вторичный индекс истории добавляет к стоимости вставки сопоставимую долю WAL и времени, а составной индекс дороже `(chat_id)` лишь на ширину ключа. H3: `pg_dump -Fc` + `pg_restore -j` восстанавливает 1 000 000 сообщений в новое хранилище за десятки секунд, при этом заметную долю занимает перестройка индексов и ограничений (`post-data`); RPO равен моменту снимка.
### D2. Набор данных
База `track` создаётся в том же кластере и мигрируется тем же runner-ом (`python -m messenger.migrate track`), поэтому схема, ограничения и индекс совпадают с продуктовыми. `scripts/sql/track-seed.sql` детерминированно: 2 000 пользователей, 1 000 чатов по два участника, сообщения по Ципфу `n_k = round(N · k^-1.3 / H)`, отметки равномерно на 30 дней внутри каждого чата, тексты 20–80 символов. `N` — параметр (`100000` и `1000000`). Перед вставкой вторичные индексы снимаются и создаются после — так быстрее и честнее для замера построения. Отдельная база, а не данные приложения: замеры с удалением индексов не трогают работающий API.
### D3. Матрица чтения
`scripts/track.py` (stdlib, синтаксис 3.9) для каждого набора индексов {нет, `(chat_id)`, `(created_at, id)`, `(chat_id, created_at, id)`}: создаёт индексы, `ANALYZE`, затем для чатов {крупнейший, 50-й, 1000-й} и запросов {первая страница, keyset после 90 % чата, тот же сдвиг через `OFFSET`} снимает `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` подготовленного запроса приложения: 5 тёплых повторов (медиана) и 3 холодных, перед каждым из которых буферы базы вытесняются `pg_buffercache_evict` (PostgreSQL 17). Холодный — значит «нет в `shared_buffers`»; страницы могут оставаться в кэше ОС внутри VM, это ограничение записано в отчёте. Generic против custom: для каждого набора индексов `SET plan_cache_mode = force_generic_plan | force_custom_plan` и тот же `EXECUTE` для большого и маленького чата.
### D4. Стоимость записи
`pgbench -n -c 4 -j 4 -T 15` в контейнере `postgres` выполняет транзакцию приложения для случайного чата из 1 000: `SELECT … FOR UPDATE`, затем `INSERT messages` + `UPDATE chats`. Идентификатор — UUIDv7, вычисляемый функцией в базе `track`, как в приложении (вставка в правый край B-tree первичного ключа). WAL на вставку — разница `pg_current_wal_lsn()` до и после, делённая на число транзакций (кластер в это время больше ничего не пишет). Размер — `pg_relation_size` каждого индекса и таблицы. После замера вставленные строки удаляются и выполняется `VACUUM`.
### D5. Резервное копирование и восстановление
Дамп снимается `pg_dump -Fc` внутри контейнера `postgres` и потоком сохраняется в gitignored `backups/` на хосте. Новый экземпляр — сервис `postgres-restore` (профиль `track`) того же образа; перед каждым восстановлением его контейнер и volume `pgrestore` удаляются, так что хранилище действительно новое. `backups/` смонтирован в него только для чтения. `pg_restore` идёт тремя секциями с отдельным временем: `pre-data` (схема), `data -j 4` (COPY), `post-data -j 4` (индексы, PK, FK). Сверка выполняется одинаковыми запросами в обеих базах: число строк по таблицам, `md5` списка «чат: число сообщений», `md5` упорядоченной истории трёх чатов, `md5` выборки ≈1 000 строк по хешу id, журнал миграций. RPO: через полсекунды после старта дампа в источник пишется маркер; он должен быть в источнике и отсутствовать в копии.
### D6. Где что лежит
`scripts/track.py` — подкоманды `bench` и `recovery`, вывод в `evidence/track/`. Цели `make track-bench` и `make track-recovery`. Скрипт вызывает `docker compose exec` и не читает секретов: `psql` в контейнере работает от суперпользователя по локальному сокету.
## Risks / Trade-offs
- [Шум VM Docker Desktop] → медиана повторов, сравнение относительных величин и буферов, а не абсолютных миллисекунд.
- [Холодный кэш не включает кэш ОС] → буферы `read` всё равно показывают обращение мимо `shared_buffers`; ограничение названо.
- [WAL кластера пишут и другие процессы] → во время замера API простаивает; автовакуум может добавить шум, это в ограничениях.
- [Дамп 1 000 000 строк занимает сотни МБ в `backups/`] → каталог в `.gitignore` и `.dockerignore`, файлы перезаписываются.
## Migration Plan
Схема приложения не меняется. База `track` и volume `pgrestore` удаляются `make reset-data`.
@@ -0,0 +1,30 @@
## Why
Уровень «4» обосновал индекс истории одним планом на 20 000 сообщений равномерного чата. Это не отвечает, как ведут себя индекс и запросы при реальном перекосе размеров чатов, сколько стоит каждый индекс на записи и можно ли поднять данные из резервной копии в новом хранилище. Изменение закрывает заявленный трек «5» — трек 2 «План запроса и восстановление» рубрики `README.md` — и строки трека 5 таблицы доказательств `REPORT.md`.
## What Changes
- Отдельная база `track` в том же PostgreSQL со схемой из тех же миграций (`python -m messenger.migrate track`) и детерминированным набором: 1 000 чатов, ≈1 000 000 сообщений по закону Ципфа (`s = 1.3`, топ-чат ≈28 %, хвост ≈36 сообщений). Данные приложения не затрагиваются.
- `make track-bench`: четыре набора индексов истории — без индекса, `(chat_id)`, `(created_at, id)`, `(chat_id, created_at, id)` — на одних данных. Для большого, среднего и маленького чата — первая страница, глубокая keyset-страница и та же страница через `OFFSET`, тёплый и холодный кэш буферов (`pg_buffercache_evict`), повторы с медианой; custom против generic плана (`plan_cache_mode`). Стоимость записи — `pgbench` транзакцией приложения: TPS, задержка, размер индексов, WAL на вставку.
- `make track-recovery`: `pg_dump -Fc` → `pg_restore -j` по секциям в новый сервис `postgres-restore` с новым volume → сверка числа строк по таблицам и чатам, `md5` упорядоченной истории выбранных чатов и выборки строк по id; маркер, записанный после начала дампа, показывает границу потери данных. Замеры для 100 000 и 1 000 000 сообщений дают RTO в зависимости от размера.
- `python -m messenger.migrate` принимает имя базы, чтобы набор трека жил в своей базе с той же схемой.
- Результаты — `evidence/track/*.json` и `*.txt`; в `REPORT.md` — гипотеза, методика, результаты, RTO/RPO и ограничения.
## Capabilities
### New Capabilities
- `lab2-query-plan-recovery`: повторяемое исследование планов истории на перекошенных данных, стоимость записи для наборов индексов, резервное копирование и восстановление в новое хранилище со сверкой, RTO и RPO.
### Modified Capabilities
Нет.
## Impact
- Код: аргумент базы в `src/messenger/migrate.py`.
- Стенд: сервис `postgres-restore` (профиль `track`, volume `pgrestore`, каталог `backups/` только для чтения).
- Скрипты: `scripts/track.py` (stdlib, синтаксис 3.9), `scripts/sql/track-*.sql`, цели `track-bench`, `track-recovery` в `Makefile`.
- Отчёт: раздел трека «5», таблица отказов (backup/restore), `evidence/track/`.
## Non-goals
Партиционирование, реплики, `pg_basebackup` и архивирование WAL (PITR) только обсуждаются как альтернатива, но не разворачиваются. Индекс приложения меняется только если исследование это обоснует. Из Out of scope лабы 2 не появляется ничего.
@@ -0,0 +1,51 @@
## Purpose
Определяет трек «5» лабы 2: повторяемое исследование планов чтения истории и стоимости записи на перекошенных данных и проверяемое восстановление из резервной копии в новое хранилище с оценкой RTO и RPO.
## ADDED Requirements
### Requirement: Воспроизводимый перекошенный набор данных
Исследование SHALL выполняться на наборе не меньше 100 000 сообщений с неравномерными размерами чатов, построенном детерминированно одной командой в отдельной базе с той же схемой, что у приложения. Параметры набора (число чатов, сообщений, распределение, доли крупнейшего и мельчайшего чата) SHALL сохраняться вместе с результатами. Набор SHALL NOT менять данные приложения.
#### Scenario: Набор построен
- **WHEN** выполняется `make track-bench`
- **THEN** в базе `track` ≈1 000 000 сообщений в 1 000 чатах по закону Ципфа, а в `evidence/track/` записаны размеры крупнейшего, среднего и мельчайшего чата
### Requirement: Сравнение индексов и запросов
Исследование SHALL сравнивать не меньше двух наборов индексов истории и SHALL для каждого снимать `EXPLAIN (ANALYZE, BUFFERS)` для большого и маленького чата, первой и глубокой страницы, keyset-курсора и `OFFSET`, при тёплом и холодном кэше буферов, с несколькими повторами и медианой. Результат SHALL фиксировать время выполнения, прочитанные и найденные в кэше буферы и форму плана.
#### Scenario: Матрица планов снята
- **WHEN** выполняется `make track-bench`
- **THEN** `evidence/track/bench.json` содержит для каждого набора индексов, чата, запроса и состояния кэша медиану времени, буферы и узлы плана, а `evidence/track/plans.txt` — текстовые планы
#### Scenario: Generic и custom план
- **WHEN** запрос истории подготовлен как prepared statement
- **THEN** отчёт сравнивает custom и generic план для большого и маленького чата и называет, при каком индексе они расходятся
### Requirement: Стоимость записи для каждого набора индексов
Для каждого набора индексов исследование SHALL измерять TPS и задержку вставки сообщения транзакцией приложения, размер индексов и объём WAL на одну вставку при одинаковой нагрузке. Вставленные при замере строки SHALL удаляться, чтобы наборы сравнивались на одних данных.
#### Scenario: Запись измерена
- **WHEN** выполняется `make track-bench`
- **THEN** для каждого набора индексов записаны TPS, средняя задержка, байты WAL на транзакцию и размеры индексов
### Requirement: Восстановление в новое хранилище со сверкой
Резервная копия SHALL сниматься `pg_dump -Fc` и восстанавливаться `pg_restore` в отдельный экземпляр PostgreSQL с новым пустым volume. После восстановления SHALL сверяться число строк по каждой таблице и по каждому чату, `md5` упорядоченной истории выбранных чатов и выборка строк по id. Время дампа, восстановления данных и перестройки индексов SHALL измеряться не меньше чем для двух размеров набора.
#### Scenario: Сверка проходит
- **WHEN** выполняется `make track-recovery`
- **THEN** `evidence/track/recovery.json` показывает совпадение всех счётчиков и хешей источника и восстановленной базы и времена дампа, `pre-data`, `data` и `post-data`
#### Scenario: Граница потери данных
- **WHEN** во время снятия дампа в источник записано сообщение-маркер
- **THEN** маркер есть в источнике и отсутствует в восстановленной базе: всё, что записано после снимка, теряется
@@ -0,0 +1,22 @@
## 1. Подготовка
- [x] 1.1 `python -m messenger.migrate [база]`: имя базы из аргумента; тест runner-а
- [x] 1.2 Сервис `postgres-restore` в профиле `track` с volume `pgrestore` и `backups/` только для чтения
- [x] 1.3 `scripts/sql/track-setup.sql` (UUIDv7, `pg_buffercache`, вспомогательные функции) и `scripts/sql/track-seed.sql` (Ципф, параметр `N`)
- [x] 1.4 Проверка группы: база `track` создаётся и заполняется повторно без ошибок, доли чатов соответствуют расчёту
## 2. Планы и запись
- [x] 2.1 `scripts/track.py bench`: наборы индексов, матрица чтения (тёплый и холодный кэш, повторы), generic против custom
- [x] 2.2 Стоимость записи: `pgbench` транзакцией приложения, TPS, задержка, WAL на вставку, размеры индексов, очистка
- [x] 2.3 Цель `make track-bench`; проверка группы: `evidence/track/bench.json`, `plans.txt`, `summary.txt` записаны
## 3. Восстановление
- [x] 3.1 `scripts/track.py recovery`: дамп с маркером RPO, новое хранилище, `pg_restore` по секциям, сверка
- [x] 3.2 Цель `make track-recovery` для 100 000 и 1 000 000 сообщений; проверка группы: `evidence/track/recovery.json` с совпадением всех проверок
## 4. Отчёт
- [x] 4.1 `REPORT.md`: гипотеза, методика, результаты, RTO/RPO, ограничения трека; строки трека в таблице доказательств и backup/restore в таблице отказов
- [x] 4.2 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
@@ -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 не появляется ничего.
@@ -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` за время ожидания соединения
@@ -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-планом как обоснование выбора курсора
@@ -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: 2
@@ -0,0 +1,37 @@
## Context
Изменение закрывает находки ревью уровня «3» и «4». Затронуты обе зоны и платформа, но связь зон не появляется: правка только приводит требование о границах к тому, что уже проверяют тесты.
## Decisions
### D1. Связь зон — внешний ключ схемы, а не событие
Требование «Доменные зоны связаны только событиями» заменено требованием «Доменные зоны не вызывают друг друга; общая точка — схема БД» (REMOVED + ADDED: MODIFIED не позволяет удалить сценарий, разрешавший импорт объявления события). Зона `messaging` не импортирует ни одного модуля `identity` (тест `test_messaging_does_not_import_identity_at_all`), существование участника проверяет FK `chat_members.user_id → users` в транзакции создания чата, SQL каждой зоны читает только свои таблицы (`test_sql_of_each_zone_reads_only_its_tables`). Тест, разрешавший импорт `identity.domain.events`, удаляется: его перекрывает более строгий.
*Что получаем:* проверка «участник существует» атомарна с записью чата, без проекции и её отставания; граница видна в графе импортов и в текстах SQL. *Чего стоит:* схемы зон сцеплены. Зону `identity` нельзя вынести в отдельную БД или сервис без возврата к проекции участников с outbox; FK при создании чата берёт `FOR KEY SHARE` на строках `users`; любое нарушение FK в `INSERT chat_members` обезличенно превращается в «неизвестный участник» (`400`). Триггер пересмотра — отдельная БД зоны.
### D2. Блокировка строки чата только участником
`ChatRepository.get(chat_id, member_id)` выполняет `SELECT … FROM chats c WHERE c.id = $1 AND EXISTS (SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2) FOR UPDATE`. Подзапрос не блокирует строк `chat_members`; блокируется только строка чата, и только если отправитель — участник. Посторонний получает `None` → `ChatNotFound` → `404` без ожидания. Агрегат по-прежнему проверяет членство в `Chat.post` — инвариант модели не переносится в SQL, SQL лишь не даёт постороннему встать в очередь. Состав участников не меняется (Out of scope), поэтому между проверкой и блокировкой гонки нет. Индекс — PK `chat_members (chat_id, user_id)`.
*Чего стоит:* одно условие в запросе и второй параметр у порта.
### D3. Предел тела по принятым байтам
Конвейер оборачивает `receive` счётчиком: как только сумма `body` превысила `max_body_bytes`, бросается `HTTPException(413)`. FastAPI пробрасывает `HTTPException` из чтения тела, обработчик ошибок отдаёт `413 payload_too_large` в общем формате. Проверка по `Content-Length` остаётся как быстрый отказ до чтения. *Что получаем:* `chunked` не обходит предел, память на запрос ограничена. *Чего стоит:* сложение длины на каждый кусок тела.
### D4. Порт отзыва отдельно от справочника сессий
`SessionDirectory` — только `find`. Новый порт `SessionRevocations.revoke(session)` реализуют `CachedSessionDirectory` (тот же объект и тот же размыкатель, что и чтение) и `NoRevocations` при выключенном кэше. Провайдер DI отдаёт кэширующий справочник как оба порта. `CloseSessionHandler` получает `SessionRevocations`; пустой `invalidate` у `PostgresSessionDirectory` исчезает. *Чего стоит:* ещё один порт и провайдер.
### D5. Срок завершения короче `stop_grace_period`
`SHUTDOWN_TIMEOUT_SECONDS=8` в образе: gunicorn `graceful_timeout` и uvicorn `timeout_graceful_shutdown` — 8 с, `stop_grace_period` compose — 10 с. Зависший запрос прерывается самим сервером, процесс выходит с кодом 0 раньше, чем Docker пошлёт `SIGKILL`. Контейнер: uid 10001, образ по digest, healthcheck без изменений.
### D6. Остатки
Удаляются `EventBus.project` и `_projections` (вызовов нет после удаления проекции участников), `PlatformSettings.instance_id` и поля журнала `queue`, `instance` (лаба 1 и задел на лабу 3), текст `Unauthenticated` про «заголовок идентификации» становится «сессия не подтверждена».
## Risks
Изменение порта `ChatRepository.get` затрагивает только `PostMessageHandler`. Остальные изменения не меняют контракт.
@@ -0,0 +1,33 @@
## Why
Ревью решения лабы 2 нашло расхождения между требованиями и кодом, которые закрывают уровни «3» и «4» `README.md`. Требование «Доменные зоны связаны только событиями» после замены проекции участников внешним ключом ложно: между зонами не ходит ни одно событие, а сценарий всё ещё разрешает импорт объявления события. Посторонний, знающий `chat_id`, берёт `FOR UPDATE` строки чужого чата до проверки членства и ждёт законных писателей до 2 с, прежде чем получить `404`. Предел тела проверяется только по `Content-Length`, и тело `Transfer-Encoding: chunked` его обходит. Ожидание принятых запросов при `SIGTERM` (10 с) равно `stop_grace_period`, и зависший запрос получает `SIGKILL` вместо штатного завершения. Изменение относится к строкам «3» и «4» таблицы доказательств `REPORT.md`: граница доступа, контейнер и `SIGTERM`, зоны и общая БД.
## What Changes
- Требование о связи зон заменено новым: зоны не вызывают и не импортируют друг друга, общая точка — схема БД (внешний ключ), SQL зоны читает только свои таблицы. Purpose спецификации перестаёт обещать, что зоны узнают друг о друге через события.
- Отправка сообщения блокирует строку чата только для участника: посторонний получает `404` сразу, не дожидаясь чужих транзакций.
- Предел тела запроса считает фактически принятые байты: `chunked`-тело больше предела даёт `413 payload_too_large`.
- `SHUTDOWN_TIMEOUT_SECONDS` = 8 с при `stop_grace_period` 10 с: штатное завершение успевает раньше `SIGKILL`.
- Отзыв сессии в кэше выделен в порт `SessionRevocations` (адаптеры Valkey и пустой при выключенном кэше); `SessionDirectory` остаётся только чтением.
- Убраны остатки: `EventBus.project` без вызовов, противоречащий тест границ, `instance_id` и поля журнала лаб 1 и 3, текст ошибки про заголовок идентификации.
- В `openspec/config.yaml` правила design и apply говорят о связи «событием или внешним ключом схемы».
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `lab1-event-publication`: требование «Доменные зоны связаны только событиями» удалено и заменено требованием «Доменные зоны не вызывают друг друга; общая точка — схема БД» (REMOVED + ADDED: MODIFIED не может убрать устаревший сценарий об импорте события).
- `lab1-messenger-chats`: членство как граница доступа — посторонний не ждёт блокировок чужого чата.
- `lab1-service-operability`: срок завершения по `SIGTERM` короче срока принудительной остановки; новое требование о пределе размера тела, включая `chunked`.
## Impact
- Код: `shared/application/messagebus.py`, `shared/entrypoints/pipeline.py`, `shared/entrypoints/actor.py`, `shared/config.py`, `main.py`, `identity/application/{ports,handlers}.py`, `identity/infrastructure/{postgres,valkey}.py`, `identity/entrypoints/ioc.py`, `messaging/application/{ports,handlers}.py`, `messaging/infrastructure/postgres.py`; `Dockerfile`.
- Тесты: `student-tests/api/test_bounded_contexts.py`, `test_events.py`, `test_cache.py`, `test_operability.py`, новый тест блокировки в `test_chats_postgres` или рядом.
- Доказательства: `evidence/sigterm.txt`, строки REPORT про зоны, `SIGTERM` и предел тела.
## Non-goals
Контракт, публичные тесты и рубрика не меняются. Схема БД и миграции не меняются. Проекция участников с outbox не возвращается: это понадобится, только если зону `identity` вынесут в отдельную БД. Ничего из Out of scope лабы 2 (`X-Instance-Id`, несколько реплик) не вводится — наоборот, заготовка `instance_id` удаляется.
@@ -0,0 +1,32 @@
## REMOVED Requirements
### Requirement: Доменные зоны связаны только событиями
**Reason**: после замены проекции участников внешним ключом между зонами не ходит ни одно событие, а сценарий разрешал импорт объявления события, который запрещает тест границ. Формулировка стала ложной; убрать сценарий в MODIFIED нельзя, поэтому требование заменяется новым.
**Migration**: действует требование «Доменные зоны не вызывают друг друга; общая точка — схема БД» ниже; проверки — `test_messaging_does_not_import_identity_at_all` и `test_sql_of_each_zone_reads_only_its_tables`.
## ADDED Requirements
### Requirement: Доменные зоны не вызывают друг друга; общая точка — схема БД
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и SHALL NOT импортировать ни одного её модуля, включая объявления событий; зона «пользователи» SHALL NOT импортировать модулей зоны «чаты и сообщения». Единственная точка связи зон — схема БД: существование участника SHALL проверяться внешним ключом схемы в той же транзакции, что и запись чата; SQL каждой зоны SHALL читать только таблицы своей зоны. События SHALL оставаться механизмом побочных эффектов внутри зоны и журнала, а не каналом связи зон.
#### Scenario: Регистрация видна чатам сразу
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
- **THEN** чат создаётся успешно: ответ регистрации отправлен после фиксации пользователя в БД
#### Scenario: Неизвестный зоне участник отклоняется
- **WHEN** в состав чата передан идентификатор, которому не соответствует ни один пользователь
- **THEN** ответ `400` с кодом `invalid_request`, чат не создаётся
#### Scenario: Зона пользователей не знает о чатах
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
#### Scenario: Зона чатов не импортирует зону пользователей
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
- **THEN** среди них нет ни одного модуля зоны «пользователи», а SQL зоны не упоминает таблиц `users` и `sessions`
@@ -0,0 +1,30 @@
## MODIFIED Requirements
### 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`
#### Scenario: Посторонний не ждёт блокировок чужого чата
- **WHEN** участник держит открытую транзакцию отправки сообщения в чат, а посторонний в это время отправляет `POST /api/v1/chats/{chat_id}/messages` в тот же чат
- **THEN** посторонний сразу получает `404` с кодом `not_found`, не дожидаясь завершения транзакции участника
@@ -0,0 +1,43 @@
## MODIFIED Requirements
### Requirement: Корректное завершение по сигналу
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд. Собственный срок ожидания принятых запросов SHALL быть меньше срока, после которого контейнер останавливается принудительно (`stop_grace_period`), чтобы зависший запрос прерывал сам сервер, а не `SIGKILL`. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
#### Scenario: Остановка укладывается в срок
- **WHEN** запущенному контейнеру послан `SIGTERM`
- **THEN** процесс завершается не позднее чем через 10 секунд
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
#### Scenario: Принятый запрос дорабатывается
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
- **THEN** этот запрос получает ответ до завершения процесса
#### Scenario: Зависший запрос не приводит к SIGKILL
- **WHEN** во время `SIGTERM` принятый запрос не завершается за собственный срок ожидания сервера
- **THEN** сервер прерывает его сам и процесс завершается с кодом `0` раньше `stop_grace_period`
## ADDED Requirements
### Requirement: Предел размера тела запроса
Сервис SHALL ограничивать размер тела запроса настраиваемым пределом (по умолчанию 1 MiB) и SHALL отвечать `413` с кодом `payload_too_large` в общем формате ошибки, если тело больше предела. Предел SHALL применяться к фактически принятым байтам независимо от способа передачи: и к телу с заголовком `Content-Length`, и к телу `Transfer-Encoding: chunked`. Сервис SHALL NOT дочитывать тело сверх предела.
#### Scenario: Объявленная длина больше предела
- **WHEN** приходит запрос с `Content-Length` больше предела
- **THEN** ответ `413` с кодом `payload_too_large` до чтения тела
#### Scenario: Chunked-тело больше предела
- **WHEN** тело передано `Transfer-Encoding: chunked` без `Content-Length` и его размер превышает предел
- **THEN** ответ `413` с кодом `payload_too_large`, а не `400` и не `500`
#### Scenario: Тело в пределах лимита
- **WHEN** `chunked`-тело меньше предела
- **THEN** запрос обрабатывается штатно
@@ -0,0 +1,25 @@
## 1. Правило связи зон (уровень «3»)
- [x] 1.1 `openspec/config.yaml`: в `rules.design` и `operations.apply` связь зон — «событием или внешним ключом схемы», импорт объявления события больше не разрешён
- [x] 1.2 Удалить `test_messaging_touches_identity_only_through_events` (его перекрывает `test_messaging_does_not_import_identity_at_all`)
- [x] 1.3 Удалить `EventBus.project`, `_projections` и `test_projection_runs_before_publish_returns`
- [x] 1.4 Проверка группы: `make student-test PYTEST_ARGS='-k "bounded or events"'`
## 2. Зона `identity`: порт отзыва
- [x] 2.1 Порт `SessionRevocations.revoke`; `SessionDirectory` — только `find`; `PostgresSessionDirectory` без пустого `invalidate`
- [x] 2.2 `CachedSessionDirectory.revoke`, адаптер `NoRevocations`; провайдер DI отдаёт кэш как оба порта; `CloseSessionHandler` зависит от `SessionRevocations`
- [x] 2.3 Проверка группы: `make student-test PYTEST_ARGS='-k "cache or logout"'`
## 3. Зона `messaging`: блокировка только участником
- [x] 3.1 `ChatRepository.get(chat_id, member_id)`: `FOR UPDATE` с условием членства; `PostMessageHandler` передаёт отправителя
- [x] 3.2 Тест: участник держит блокировку строки чата, посторонний получает `404` быстрее `lock_timeout`
- [x] 3.3 Проверка группы: `make student-test PYTEST_ARGS='-k "message or stranger"'`
## 4. Платформа и контейнер
- [x] 4.1 Конвейер считает принятые байты тела: `chunked` больше предела → `413 payload_too_large`; тест
- [x] 4.2 Удалить `PlatformSettings.instance_id`, поля журнала `queue` и `instance`; текст `Unauthenticated` — «сессия не подтверждена»
- [x] 4.3 `SHUTDOWN_TIMEOUT_SECONDS=8` в `Dockerfile` и умолчаниях `gunicorn_conf.py`; `stop_grace_period` остаётся 10 с
- [x] 4.4 Проверка группы: `make lint`, `make student-test`, `make check`; стенд `make up`, `make test`, `make sigterm-evidence` (код 0, меньше 10 с)
@@ -0,0 +1,4 @@
schema: spec-driven
created: 2026-10-28
archived: 2026-10-28
lab: 2
@@ -0,0 +1,31 @@
## Context
Изменение закрывает находки второго ревью уровней «3» и «4». Затронута зона `identity` (выход и кэш сессий), зона `messaging` (разбор курсора) и платформа (настройки транспорта). Связь между зонами не появляется.
## Decisions
### D1. Отказ PostgreSQL при выходе снимает отметку отзыва
Порядок «сначала отметка в Valkey, потом `DELETE` в PostgreSQL» остаётся. Обратный порядок хуже: удалённая в БД сессия, чью отметку не удалось записать, жила бы в кэше до 300 с. Порт `SessionRevocations` получает второй метод `restore(session)`. `CachedSessionDirectory` выполняет `DEL session:<sha256>` тихо, через размыкатель, ошибку Valkey только журналирует. `NoRevocations.restore` ничего не делает. `CloseSessionHandler` вызывает `restore`, если транзакция UoW завершилась любым исключением, и пробрасывает исключение дальше: клиент получает `503 unavailable`.
*Что получаем:* `503` на выход означает «ничего не изменилось». Сессия жива и в БД, и для кэша, а повтор после возвращения PostgreSQL отвечает `204`. Вытеснение или `FLUSHALL` больше не оживляют токен, который клиент уже счёл отозванным: такого токена не бывает.
*Чего стоит:* окно между записью отметки и её снятием, в котором параллельный запрос с тем же токеном получает `401`. Это лишь ложный отказ, доступа он не открывает. Неоднозначный `COMMIT` (сервер зафиксировал, клиент получил ошибку соединения) тоже снимает отметку, но строки в БД уже нет, поэтому следующая проверка из БД даёт `401`. Если в это же окно гонку выиграет заполнение кэша, токен проживёт в кэше до `SESSION_CACHE_TTL_SECONDS`, а клиент получил `503` и повторит выход. Без двухфазной фиксации между Valkey и PostgreSQL этот остаток не устранить, и он принят.
### D2. Пустой курсор — ошибка запроса
`PageQuery.cursor` объявлен с `min_length=1`, как в `contracts/openapi.json`. Пустое значение становится `400 invalid_request` на границе HTTP, а запросы `ListChats` и `ReadHistory` различают «курсора нет» (`None`) и «курсор есть» через `is not None`, а не через истинность строки.
### D3. Срок завершения задаёт одна настройка
`TransportSettings.shutdown_timeout_seconds` (умолчание 10, `le=10`) никто не читал. Срок задаёт `SHUTDOWN_TIMEOUT_SECONDS` в образе и в `gunicorn_conf.py` (8 с при `stop_grace_period` 10 с). Поле удаляется, чтобы второй источник с противоположным умолчанием не вводил в заблуждение.
Воркер uvicorn ждёт принятые запросы на 1 с меньше, чем gunicorn ждёт воркеры: `timeout_graceful_shutdown = SHUTDOWN_TIMEOUT_SECONDS − 1` (7 с), `graceful_timeout` — 8 с. При равных сроках мастер gunicorn успевал убить воркер с зависшим запросом раньше, чем воркер отменял запрос сам. Теперь воркер отменяет зависший запрос, штатно закрывает пул и выходит. Клиент получает `500`, контейнер выходит с кодом 0 раньше `stop_grace_period`, как требует `lab1-service-operability`. *Чего стоит:* зависшему запросу отпущено на 1 с меньше. Контейнер не меняется: uid 10001, образ по digest, healthcheck прежний.
### D4. Зависимость отзыва от Valkey названа в требовании
Требование `lab1-event-publication` уточнено, кода это не касается: путь чтения и записи обязательного API зависит только от PostgreSQL, а подтверждение отзыва при включённом кэше требует ещё и Valkey. Так требование согласовано со сценарием `lab2-session-cache` «Выход при недоступном кэше».
## Risks
Новый метод порта реализуют оба адаптера, других реализаций нет. Контракт не меняется: пустой `cursor` уже запрещён `minLength: 1`.
@@ -0,0 +1,32 @@
## Why
Второе ревью лабы 2 нашло три расхождения с требованиями уровней «3» и «4» `README.md`. Выход пишет отметку отзыва в Valkey до удаления строки в PostgreSQL. Если удаление не удалось, клиент получает `503`, а отметка остаётся: повтор выхода отвечает `401`, хотя сессия в БД жива. После вытеснения отметки или `FLUSHALL` токен снова работает, и это нарушает `lab2-session-cache`. Пустой `cursor=` принимается как отсутствие курсора, хотя в `contracts/openapi.json` у параметра `minLength: 1`, а `contracts/README.md` относит неверный cursor к `400`. Требование `lab1-event-publication` утверждает, что обязательный API зависит только от PostgreSQL, а `lab2-session-cache` требует `503` на выход при остановленном Valkey. Изменение относится к строкам «4» «Политика expiry и инвалидации» и «3» «Минимум lab1 сохранён» таблицы доказательств `REPORT.md`.
## What Changes
- Выход: если удалить сессию в PostgreSQL не удалось, отметка отзыва снимается (best-effort), и ответ `503` означает «ничего не изменилось». Повторный выход после возвращения БД отвечает `204`.
- `GET /api/v1/chats` и `GET /api/v1/chats/{chat_id}/messages`: пустой `cursor` → `400 invalid_request`.
- Требование «Публикация событий не требует брокера» уточнено: путь чтения и записи зависит только от PostgreSQL, а подтверждение отзыва при включённом кэше требует ещё и Valkey.
- Удалено поле `TransportSettings.shutdown_timeout_seconds`, которое никто не читает. Срок завершения по-прежнему задаёт `SHUTDOWN_TIMEOUT_SECONDS` в `gunicorn_conf.py`.
- Воркер uvicorn отменяет зависший запрос на 1 с раньше, чем gunicorn убивает воркер, и выходит штатно.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `lab2-session-cache`: «Выход инвалидирует кэш» — отказ PostgreSQL при выходе снимает отметку отзыва.
- `lab1-messenger-history`: «Чтение истории keyset-курсором» — пустой курсор отклоняется.
- `lab1-messenger-chats`: «Список чатов пользователя» — испорченный и пустой курсор отклоняются.
- `lab1-event-publication`: «Публикация событий не требует брокера» — названа зависимость отзыва от Valkey.
## Impact
- Код: `identity/application/{ports,handlers}.py`, `identity/infrastructure/valkey.py`, `messaging/entrypoints/schemas.py`, `messaging/application/queries.py`, `shared/entrypoints/config.py`, `gunicorn_conf.py`.
- Тесты: `student-tests/api/test_cache.py`, `test_pagination.py`.
- Доказательства: `evidence/student-tests.txt`, строки `REPORT.md` про инвалидацию и пагинацию.
## Non-goals
Контракт, публичные тесты, рубрика, схема БД и миграции не меняются. Транзакции между Valkey и PostgreSQL (двухфазной фиксации) нет: отметка снимается после отказа, а не откатывается атомарно. Ничего из Out of scope лабы 2 не вводится.
@@ -0,0 +1,20 @@
## MODIFIED Requirements
### Requirement: Публикация событий не требует брокера
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера. Из сетевых сервисов путь чтения и записи обязательного API SHALL зависеть только от PostgreSQL; при включённом кэше сессий подтверждение отзыва сессии SHALL требовать ещё и Valkey (см. `lab2-session-cache`).
#### Scenario: События доставляются без брокера
- **WHEN** стенд поднят без брокера сообщений
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
#### Scenario: Публикация скрыта за портом
- **WHEN** проверяется слой приложения
- **THEN** он обращается к публикации только через порт и не знает её реализации
#### Scenario: Остановленный Valkey не останавливает чтение и запись
- **WHEN** при включённом кэше сессий Valkey остановлен
- **THEN** регистрация, вход, чтение и запись чатов и сообщений работают через PostgreSQL, а только `DELETE /api/v1/auth/sessions/current` отвечает `503`
@@ -0,0 +1,31 @@
## MODIFIED Requirements
### Requirement: Список чатов пользователя
Сервис SHALL отдавать по `GET /api/v1/chats` страницу `{"items":[...],"next_cursor":...}` с чатами, в которых состоит вызывающий, упорядоченными по `(created_at, id)` по возрастанию. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. Список SHALL NOT содержать чатов, недоступных вызывающему. Переданный `cursor` SHALL быть непустым ранее выданным сервером курсором списка, иначе ответ SHALL быть `400`.
#### 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`
#### Scenario: Испорченный или пустой курсор списка
- **WHEN** запрос `GET /api/v1/chats` содержит `cursor=` с пустым значением или строку, которую сервер не выдавал
- **THEN** ответ `400` с кодом `invalid_request`
@@ -0,0 +1,46 @@
## MODIFIED Requirements
### 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`. Переданный параметр `cursor` 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: Пустой курсор
- **WHEN** запрос истории содержит `cursor=` с пустым значением
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Limit вне допустимого диапазона
- **WHEN** запрос содержит `limit=0` или `limit=101`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Посторонний читает чужую историю
- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю
- **THEN** ответ `404` с кодом `not_found`
@@ -0,0 +1,21 @@
## MODIFIED Requirements
### Requirement: Выход инвалидирует кэш
Отзыв сессии SHALL записывать в кэш отметку отзыва на оставшийся срок сессии до удаления строки в БД, а заполнение кэша после промаха SHALL выполняться только при отсутствии ключа. Отозванный токен SHALL получать `401` и при гонке «чтение заполнило кэш после выхода». Если отметку отзыва записать нельзя, выход SHALL отвечать `503` и SHALL NOT удалять сессию. Если после записи отметки удалить сессию в PostgreSQL не удалось, выход SHALL отвечать `503` и SHALL снимать отметку отзыва: ответ `503` означает, что сессия осталась действующей и в БД, и для проверки токена.
#### 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`
#### Scenario: Выход при сбое PostgreSQL
- **WHEN** отметка отзыва записана, но удаление сессии в PostgreSQL завершилось ошибкой
- **THEN** выход отвечает `503` с кодом `unavailable`, токен по-прежнему получает `200`, отметки отзыва в кэше нет
- **AND** после возвращения PostgreSQL повторный выход отвечает `204`, а токен затем получает `401`
@@ -0,0 +1,19 @@
## 1. Зона `messaging`: пустой курсор (уровень «3»)
- [x] 1.1 `PageQuery.cursor` с `min_length=1`; `ListChats` и `ReadHistory` проверяют `cursor is not None`
- [x] 1.2 Тест: `cursor=` в истории и в списке чатов → `400 invalid_request`
- [x] 1.3 Проверка группы: `make student-test PYTEST_ARGS='-v -k cursor'`
## 2. Зона `identity`: выход при сбое PostgreSQL (уровень «4»)
- [x] 2.1 Порт `SessionRevocations.restore`; `CachedSessionDirectory.restore` — тихий `DEL` ключа; `NoRevocations.restore` — пусто
- [x] 2.2 `CloseSessionHandler`: при исключении транзакции снять отметку и пробросить ошибку
- [x] 2.3 Тест: удаление сессии падает → `503`, токен `200`, ключа в Valkey нет; после починки повторный выход `204`, затем `401`
- [x] 2.4 Тест обхода кэша: при недоступном Valkey создание чата и отправка сообщения → `201`
- [x] 2.5 Проверка группы: `make student-test PYTEST_ARGS='-v -k "cache or logout"'`
## 3. Платформа
- [x] 3.1 Удалить `TransportSettings.shutdown_timeout_seconds`
- [x] 3.2 Воркер отменяет зависший запрос за 1 с до `graceful_timeout` gunicorn: `timeout_graceful_shutdown = SHUTDOWN_TIMEOUT_SECONDS − 1`
- [x] 3.3 Проверка группы: `make lint`, `make student-test`, `make check`; стенд `make up`, `make test`, `make test-faults`, `make sigterm-evidence` (дописанный запрос `201`, зависший прерван воркером, код 0 меньше чем за 10 с)
+138
View File
@@ -0,0 +1,138 @@
schema: spec-driven
context: |
# Лабораторная 2 «PostgreSQL, сессии и Redis/Valkey» — контекст проекта
## Что это
Skeleton лабораторной 2 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение
в ветке `solution/bpi2303-kostylev`, построенное переносом решения лабы 1. Skeleton содержит
задание (`README.md`), нормативный контракт (`contracts/`, версия 1.2.0) и публичные black-box
проверки (`tests/`). Целевая оценка — «5»: весь уровень 4 плюс трек 2 «План запроса и восстановление».
## Границы (менять нельзя)
In scope лабы 2: состояние в PostgreSQL (пользователи, чаты, участники, сообщения, сессии),
версионируемые миграции, регистрация с паролем (Argon2id), вход `Basic` только на
`POST /api/v1/auth/sessions`, непрозрачный `Bearer` с абсолютным TTL и отзывом
`DELETE /api/v1/auth/sessions/current`, `X-User-Id` игнорируется. Данные и действующие сессии
переживают рестарт API и хранилищ с сохранёнными volumes. На «4» — Valkey с конкретной ролью.
Обязательный минимум lab1 (`/health/*`, users, chats, messages, keyset-пагинация) сохраняется
с объявленным переходом на новую аутентификацию.
Out of scope (не проектировать, не закладывать «на будущее»): несколько API-реплик за
балансировщиком, `X-Instance-Id` и `Idempotency-Key` (лаба 3); вложения и S3 (лаба 4); worker,
брокер и обработка изображений (лаба 5); OTel и Grafana (лаба 6); TLS, mTLS и OpenBao (лаба 7);
Web UI, WebSocket, редактирование и удаление сообщений, изменение состава участников, публичный
поиск пользователей, Kubernetes, Swarm, репликация и HA PostgreSQL.
## Стек
Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и
`from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими
`UvicornWorker` (пакет `uvicorn-worker`), dishka (DI), pydantic v2 + pydantic-settings, structlog,
asyncpg (параметризованный SQL без ORM), redis-py (`redis.asyncio`) для Valkey, argon2-cffi,
pytest + pytest-asyncio + httpx. Зависимости — uv и `uv.lock`; ruff и ty обязательны на `src/`
и `student-tests/`; `scripts/*.py` держат синтаксис Python 3.9.
Инфраструктура — Docker Compose: `postgres` (17.x-alpine по digest, именованный volume),
`valkey` (8.x-alpine по digest, AOF на volume), одноразовый `migrate` на образе приложения,
`api` (non-root, healthcheck по готовности, `SIGTERM` ≤10 с). Секреты — compose secrets из
gitignored `secrets/`, приложение читает их через `*_FILE`.
## Архитектура
Монолит с двумя доменными зонами по книге Персиваля и Грегори
(`openspec/notes/architecture-patterns-python.md`):
main.py сборка приложения: собирает вклады зон в один процесс
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
identity/ пользователи, пароли и сессии: ошибки, события, команды, значения, порты,
адаптеры PostgreSQL/Valkey/Argon2 и весь свой HTTP-слой, включая аутентификацию
messaging/ чаты и история: ошибки, события, команды, агрегат Chat, курсор, адаптеры
PostgreSQL и весь свой HTTP-слой
shared/ только платформа: domain / application / infrastructure (часы, id, журнал,
пул PostgreSQL, UoW-база) и entrypoints/ (конвейер, health, ошибки, настройки)
Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только
от портов, адаптеры подключаются в `ioc.py` зоны. Ядро `shared/` не импортирует веб-фреймворк.
Зоны не импортируют друг друга; общая точка — схема БД: внешние ключи между таблицами зон
допустимы как ограничение целостности, но SQL одной зоны не читает таблицы другой.
PostgreSQL — источник истины для всего, включая сессии; Valkey — только кэш, его потеря не
теряет данные и не открывает доступ.
## Источники норм
- `contracts/README.md` — нормативная семантика API; приоритетнее интуиции и поведения библиотек.
- `contracts/openapi.json` — OpenAPI 3.1.0, обязательный минимум.
- `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; не тащи в лабу 2 возможности лаб 3–7."
- "Связывай изменение с конкретным пунктом рубрики `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`."
- "Сценарии обязаны покрывать негативные пути: malformed JSON, лишние поля, чужой чат (404, не 403), пустой текст, дубль username, cursor от другого чата, limit вне 1–100, неверный пароль, истёкший и отозванный токен, Basic на бизнес-endpoint, недоступная зависимость."
- "Не вводи в контракт поля и коды, которых нет в `contracts/openapi.json`."
design:
- "Создавай, если изменение затрагивает границы доменных зон, слои, агрегаты, конкурентность, формат курсора, поведение при сигналах или конфигурацию контейнера."
- "Для каждого введённого паттерна отвечай по формуле книги: что за это получаем и чего это стоит."
- "Явно называй порт, его адаптеры и точку сборки; проверяй правило зависимостей: домен не импортирует инфраструктуру."
- "Указывай, к какой доменной зоне относится изменение; если оно задевает обе — объясняй, каким событием или внешним ключом схемы они связаны, и называй цену этой связи."
- "Всё, что кладётся в `shared/`, обосновывай отдельно: туда попадает только платформа и механизм связи, но не доменные понятия."
- "Ошибки, события и команды принадлежат зоне; в `shared/` живут лишь их базовые типы, без кодов контракта."
- "Фиксируй границы согласованности и способ защиты состояния от гонок; объясняй выбранную семантику времени и сортировки."
- "Секреты, токены и реальные данные в артефакт не попадают — только плейсхолдеры и имена переменных окружения."
- "Отмечай, что требуется от контейнера: пользователь, закрепление версий, healthcheck, обработка SIGTERM, переменные окружения."
- "Для каждого хранилища называй источник истины, границы транзакций, политику expiry и инвалидации, поведение при недоступности (503 или обход кэша) и что переживает рестарт."
- "SQL описывай вместе с индексом, который его обслуживает, и ожидаемым планом; схему, ограничения и индексы фиксируй до запросов."
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`."
- "Зоны не импортируют модули друг друга, включая объявления событий, — это проверяется тестом; в БД связь зон — только внешний ключ, SQL зоны читает лишь свои таблицы."
- "Пиши под Python 3.14 с ленивыми аннотациями: без `TYPE_CHECKING` и без `from __future__ import annotations`."
- "Логирование — только через порт `Logger`; второй логгер в приложении не заводится, сообщения сервера и библиотек идут через тот же поток."
- "Код приложения — в `src/`, собственные тесты — в `student-tests/`, обезличенные доказательства — в `evidence/`."
- "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`."
- "SQL только параметризованный (`$1`, `$2`); значения из запроса никогда не склеиваются в текст запроса."
- "Ошибка зависимости (PostgreSQL, Valkey) превращается в `503 unavailable` за ограниченное время; отказ кэша обходится и никогда не превращается в анонимный доступ."
- "Схема меняется только новым файлом миграции; применённую миграцию не редактируют."
- "Публичный `make test` и `make test-persistence ACTION_SCRIPT=scripts/restart.sh` запускаются против поднятого стенда (`make up`); сами тесты стенд не стартуют."
- "Каждый заявленный критерий рубрики подтверждай командой и наблюдаемым результатом в `REPORT.md`; PASS без команды доказательством не считается."
- "Отмечай выполнение в `tasks.md`; резюме держи кратким."
archive:
guidance:
- "Имя архивной папки начинается с даты архивации в формате `ГГГГ-ММ-ДД`, а не с даты создания change."
- "В `.openspec.yaml` архивной папки проставь `archived: <дата архивации>` и `lab: <номер из lab.json>` — по ним видно, когда и в какой лабе изменение закрыто."
- "Перед архивацией сверься с рубрикой `README.md`: какой уровень закрывает изменение и каким файлом доказательства."
- "Убедись, что `make check`, `make lint`, `make student-test`, `make test` и `make test-persistence ACTION_SCRIPT=scripts/restart.sh` против стенда проходят."
- "Сохранившиеся дальше требования должны попасть в `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,107 @@
# 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 выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера. Из сетевых сервисов путь чтения и записи обязательного API SHALL зависеть только от PostgreSQL; при включённом кэше сессий подтверждение отзыва сессии SHALL требовать ещё и Valkey (см. `lab2-session-cache`).
#### Scenario: События доставляются без брокера
- **WHEN** стенд поднят без брокера сообщений
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
#### Scenario: Публикация скрыта за портом
- **WHEN** проверяется слой приложения
- **THEN** он обращается к публикации только через порт и не знает её реализации
#### Scenario: Остановленный Valkey не останавливает чтение и запись
- **WHEN** при включённом кэше сессий Valkey остановлен
- **THEN** регистрация, вход, чтение и запись чатов и сообщений работают через PostgreSQL, а только `DELETE /api/v1/auth/sessions/current` отвечает `503`
### Requirement: Доменные зоны не вызывают друг друга; общая точка — схема БД
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и SHALL NOT импортировать ни одного её модуля, включая объявления событий; зона «пользователи» SHALL NOT импортировать модулей зоны «чаты и сообщения». Единственная точка связи зон — схема БД: существование участника SHALL проверяться внешним ключом схемы в той же транзакции, что и запись чата; SQL каждой зоны SHALL читать только таблицы своей зоны. События SHALL оставаться механизмом побочных эффектов внутри зоны и журнала, а не каналом связи зон.
#### Scenario: Регистрация видна чатам сразу
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
- **THEN** чат создаётся успешно: ответ регистрации отправлен после фиксации пользователя в БД
#### Scenario: Неизвестный зоне участник отклоняется
- **WHEN** в состав чата передан идентификатор, которому не соответствует ни один пользователь
- **THEN** ответ `400` с кодом `invalid_request`, чат не создаётся
#### Scenario: Зона пользователей не знает о чатах
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
#### Scenario: Зона чатов не импортирует зону пользователей
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
- **THEN** среди них нет ни одного модуля зоны «пользователи», а SQL зоны не упоминает таблиц `users` и `sessions`
@@ -0,0 +1,95 @@
# 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`
#### Scenario: Посторонний не ждёт блокировок чужого чата
- **WHEN** участник держит открытую транзакцию отправки сообщения в чат, а посторонний в это время отправляет `POST /api/v1/chats/{chat_id}/messages` в тот же чат
- **THEN** посторонний сразу получает `404` с кодом `not_found`, не дожидаясь завершения транзакции участника
### Requirement: Список чатов пользователя
Сервис SHALL отдавать по `GET /api/v1/chats` страницу `{"items":[...],"next_cursor":...}` с чатами, в которых состоит вызывающий, упорядоченными по `(created_at, id)` по возрастанию. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. Список SHALL NOT содержать чатов, недоступных вызывающему. Переданный `cursor` SHALL быть непустым ранее выданным сервером курсором списка, иначе ответ SHALL быть `400`.
#### 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`
#### Scenario: Испорченный или пустой курсор списка
- **WHEN** запрос `GET /api/v1/chats` содержит `cursor=` с пустым значением или строку, которую сервер не выдавал
- **THEN** ответ `400` с кодом `invalid_request`

Some files were not shown because too many files have changed in this diff Show More