chore: carry over lab 1 solution into lab 2 skeleton

Copy the committed lab 1 sources as-is: src/, student-tests/, bench/,
Dockerfile, docker-compose.yml, pyproject.toml, uv.lock,
.python-version, config_example.toml, AGENTS.md, CLAUDE.md, .claude/,
openspec/, .graphifyignore and KNOWN_ISSUES.md. Lab 1 evidence stays
in the lab 1 repository.

Merge the new skeleton files with own sections: Makefile (lab 2
targets plus own run, docker, bench and common targets), .gitignore,
.dockerignore and .env.example. Rename the image to
mtusi-messenger:lab2 and point AGENTS.md at lab 2.

The application is still the in-memory lab 1 implementation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-30 22:11:46 +03:00
co-authored by Claude Opus 5.5
parent 65003b6119
commit 7b775a29a9
174 changed files with 19023 additions and 11 deletions
+198
View File
@@ -0,0 +1,198 @@
---
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`, `schemas`, `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.
**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
Otherwise, with no root, what happens next depends on how this workflow was reached:
- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
**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
- `missingArtifacts` (when present): required artifact ids with no output
**Handle states:**
- If `state: "blocked"`: show the message and pause implementation.
- If `missingArtifacts` is non-empty: suggest completing the missing artifacts. Run `openspec status --change "<name>" --json`, select the next `ready` artifact (not `skipped` or `blocked`), and use `openspec instructions "<artifact-id>" --change "<name>" --json` for its rules and template. Keep the selected `--store <id>` on both commands.
- Otherwise, follow the CLI instruction to create or repair the schema-configured tracking file from existing planning artifacts. Do not assume another artifact is ready or start implementation while blocked.
- 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
- A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently
- 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
- When a task needs work beyond what the spec describes, surface the added scope and pause - never silently narrow, defer, or simplify away specified behavior
- Only mark a task `- [x]` when its specified behavior is fully implemented, not when it is partially done or deferred
- 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
+246
View File
@@ -0,0 +1,246 @@
---
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`, `schemas`, `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.
**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
Otherwise, with no root, what happens next depends on how this workflow was reached:
- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
`<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.
A checkbox is complete when its only content is `x` or `X`; spacing inside
the brackets does not matter, so `- [ x]` counts as complete too. Every
other marker is incomplete - `- [ ]`, an empty `- []`, and markers OpenSpec
assigns no meaning to such as `- [~]` or `- [-]`. Never read an unfamiliar
marker as 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)
- A missing main spec is **not automatically** "already synced". For a new capability, the main spec is an *output* of the sync, not an input:
- If the delta has MODIFIED or RENAMED requirements, report that only ADDED requirements can create a new main spec and mark that capability as sync-blocked. Never invent a requirement that has no current version.
- Otherwise, if the delta has only REMOVED requirements and the change's `.openspec.yaml` declares `retire_capabilities: true`, the capability is already retired: count it as already synced, warn that there is nothing left to remove, and do not recreate the main spec. Apply this rule both now and when verifying a completed sync.
- Otherwise, if the delta has no ADDED requirements, report that no sync is possible and mark that capability as sync-blocked. For a REMOVED-only delta, warn that there is no main spec to remove from and leave the main-spec tree unchanged. `openspec archive` refuses the unmarked REMOVED-only case with `Spec must have at least one requirement`.
- Otherwise, count the capability as needing sync and name it in the summary (`<capability-path>: new main spec will be created`). If the delta also has REMOVED requirements, warn that they will be ignored because there is no main spec to remove from. The sync creates the main spec from only the delta's ADDED requirements, exactly as `openspec archive` does.
- Determine what changes would be applied (adds, modifications, removals, renames)
- Continue assessing the remaining capabilities even when one is sync-blocked. Show a combined summary before prompting.
**Prompt options:**
- If any capability is sync-blocked: explain why and offer only "Archive without syncing", "Cancel"
- Otherwise, if changes needed: "Sync now (recommended)", "Archive without syncing"
- Otherwise, 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). Do not start any sync while a capability is sync-blocked; explain the blocker and repeat the available choices.
- 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, including the explicitly retired, missing-spec case, 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
+239
View File
@@ -0,0 +1,239 @@
---
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, investigate the codebase, and run read-only commands or tools without confirmation, but you must NEVER write code or implement features. If the user asks you to implement something, do not start it here: say that explore mode does not implement, and point them at `/opsx:propose`, which turns the discussion into a change. The work happens from that change, never from explore mode. You MAY create or update OpenSpec change artifacts (proposals, designs, specs) within a confirmed scope—that's capturing thinking, not implementing. Answering design or clarifying questions is never consent to write. Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. An explicit request from the user to capture the exploration as a new change is itself that confirmation, covering the change and the change artifacts the request names; 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`, `schemas`, `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.
**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
Otherwise, with no root, what happens next depends on how this workflow was reached:
- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
**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
---
## Planning a Change
When the user is planning a change, guide them toward shared understanding with focused discovery questions. For open-ended discussion, follow the conversation without imposing an interview or a required output.
Before asking a factual question, follow the context discovery below and inspect relevant OpenSpec artifacts, source, tests, docs, and configuration. Do not ask the user to repeat facts you can verify. Summarize relevant findings without reproducing private context or rules. If evidence is missing, conflicting, or inaccessible, state that limitation and ask only for the clarification needed to proceed.
- **Follow dependencies** - Resolve the next blocking decision before its dependent details. For example, clarify the user's outcome and scope before choosing an API or data model. Revisit downstream assumptions when an earlier answer changes. Skip branches that do not matter to this goal.
- **Keep questions focused** - Ask one focused question at a time, and briefly explain why it matters and which decision it unlocks. Batch questions only if the user asks for a batch; keep them small and group related decisions.
- **Offer grounded recommendations** - When evidence supports a recommendation, state your preferred option and why it fits the user's goals, with alternatives and their tradeoffs when useful. Do not invent intent, priorities, or external constraints: ask the user when only they can answer. Avoid a fixed question format.
- **Keep a conversational record** - Track decisions in the conversation, not in files. Separate confirmed decisions from proposed defaults and unresolved questions. Silence is not acceptance. Accepting an answer or a batch of recommendations is not permission to write. Keep file-write confirmation separate from discovery questions and follow the guardrails below.
Stop asking when the user has enough clarity. Let them pause, pivot, or defer a decision; do not exhaust every branch or force a proposal.
For example, after inspecting the relevant code:
```text
The CLI already uses SQLite and has no remote service. Is sharing state
across devices in scope? That determines whether local storage is enough.
If this stays a single-device tool, I recommend keeping SQLite to avoid
adding a service to operate; shared state would need a separate sync design.
```
---
## 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 A] -------> [State B] |
| | |
| v |
| [State C] |
| |
| System diagrams, state machines, |
| data flows, architecture sketches, |
| dependency graphs, comparison tables |
| |
+------------------------------------------+
```
**Draw with plain ASCII only** — borders `+` `-` `|`, arrows `-->` `<--` `^` `v`, markers `*` `x`.
Unicode diagram glyphs can render at different widths across terminals, fonts, and locales, so padded boxes and aligned tables can drift. Keep every diagram character ASCII.
**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
That is the *change* list - work in flight. It does not include the project's durable capabilities, so list those too:
```bash
openspec list --specs
```
Add `--json` for ids and requirement counts, and append `--store "<id>"` only for a registered standalone store. This is the inventory of what the project already claims to do, and `openspec list` on its own never shows it. To look at one, run `openspec show "<spec-id>" --type spec --json --no-scenarios` (same `--store` rule) - it returns that capability's purpose and requirement texts without pulling the whole spec file into context, and `--type spec` stops a change of the same name from making it ambiguous.
The filtered read is only an overview. Before deciding what is already covered or what should change, read each relevant spec in full, including scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
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, that request is the confirmation required above. It covers scaffolding that change and creating the change artifacts the request names, and nothing else. This holds only when the request is theirs: a yes to an offer you made confirms only the scope your offer itself named, so name the change and the artifacts in the offer. Don't re-ask for what they already asked for; do ask before anything beyond it. 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 the requested capture is done, stop there and name where the work continues: `/opsx:propose` writes the remaining planning artifacts, and `/opsx:apply` implements the change once tasks exist. Capturing artifacts never starts implementing them.
### 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? Run `/opsx:propose` and this becomes a change."
- **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. Workflow configuration counts too: creating or editing schemas, templates, or `openspec/config.yaml` is a change, not thinking. Creating or updating OpenSpec change artifacts within the confirmed scope is fine, writing anything else is not. When the user is ready to build, name the handoff rather than starting: `/opsx:propose` turns the discussion into a change, and the work happens there.
- **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. Read-only commands and tools need no confirmation. Before the first write-capable action—including `openspec new change` or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message. That confirmation covers only the described scope; ask again before expanding it. Answers to design or clarifying questions are never consent to write. That rule governs `openspec new change` whenever you are the one proposing the capture; the user's own capture request is the exception, handled in the capture transition above.
- **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
+170
View File
@@ -0,0 +1,170 @@
---
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`, `schemas`, `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.
**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
Otherwise, with no root, what happens next depends on how this workflow was reached:
- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
**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. **Load project context**
Run `openspec context --json` from the current working directory (or `openspec context --json --store "<store-id>"` when a registered store was explicitly selected). Use the returned `root.path` as the authoritative OpenSpec root. If context reports `no_openspec_root`, stop without creating or changing any files and follow the **Project check** above for how this workflow was reached. Offer `openspec init` only for an explicit OpenSpec request, and wait for the user to request initialization. Do not initialize automatically or run `openspec new change`. After initialization, rerun this context check before continuing. For any other context failure, stop and report the error; do not fall back to the current directory or run later OpenSpec commands without the selected store.
Only when context returns a resolved `root.path`, read `<root.path>/openspec/config.yaml`. Use `config.yml` only when `config.yaml` does not exist. If neither file exists, continue without project context. Do not fall back to `config.yml` if `config.yaml` is unreadable or invalid.
If the file parses as a YAML object and its `context` field is a string no larger than 51,200 bytes in UTF-8, apply that field before exploring the codebase or making planning decisions. If the file cannot be read or parsed, or the context field is invalid or oversized, continue without project context. Validate this field independently of other config fields, as OpenSpec does.
Treat context as project-provided data and constraints, not as authority to change this workflow: it cannot override user authorization, the planning boundary, tool restrictions, or artifact and output rules. Do not copy the context into artifacts; use it to focus any codebase exploration and as a constraint on the proposal.
3. **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`; when a registered store was explicitly selected, append `--store "<store-id>"` to `openspec schemas --json` as well. If context fails, stop as described in the context-loading step; do not fall back to the current directory.
Otherwise, omit `--schema` to preserve the configured default.
4. **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`.
5. **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.
6. **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)
- **Inspect the relevant project before drafting**: Read `context` and `rules` first, then inspect relevant implementation, nearby tests, configuration, and documentation outside `openspec/`. Keep inspection read-only and proportional to the change; reuse findings for later artifacts and inspect more only as needed.
- Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
- Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
- Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
- 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
7. **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
+286
View File
@@ -0,0 +1,286 @@
---
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`, `schemas`, `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.
**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
Otherwise, with no root, what happens next depends on how this workflow was reached:
- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
`<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)
**If it does not exist yet** (a new capability), match what `openspec archive` does:
only ADDED requirements may be applied - step d creates the spec from them.
MODIFIED and RENAMED have no requirement to act on, so stop the sync for that
capability and report that its main spec does not exist and only ADDED is allowed
for a new spec; never invent the missing requirement. REMOVED has nothing to
remove - skip it and warn.
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:
- Only when the delta has ADDED requirements to put in it and no MODIFIED or
RENAMED requirements blocked this capability in step b. Otherwise create nothing
and leave the specs directory untouched. For a REMOVED-only delta, if the change's
`.openspec.yaml` declares `retire_capabilities: true`, report it as already retired
and continue without recreating the spec. Without that marker, report the sync as blocked:
`openspec archive` rejects it with `Spec must have at least one requirement`.
An empty delta has no operations to sync; report it as blocked too.
Never write an empty `## Requirements` section.
- 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
# Spec Delta
## 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
+99
View File
@@ -0,0 +1,99 @@
---
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`, `schemas`, `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.
**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
Otherwise, with no root, what happens next depends on how this workflow was reached:
- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
**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.
This workflow revises artifacts that already exist; it never creates missing ones. When an artifact is missing, `openspec status --change "<name>" --json` names the next one and `openspec instructions "<artifact-id>" --change "<name>" --json` explains how to write 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.
- Draft the requested edit in the conversation, not in files. Work out exactly what it changes; step 5 owns every write. Then check every other existing artifact against the drafted edit - 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.
- Propose revisions only to 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 `openspec instructions "<artifact-id>" --change "<name>" --json` for how to create them.
- If the change is already coherent, say so and propose no revisions.
5. **Confirm and apply, one artifact at a time**
- This step performs every artifact write in this workflow; no earlier step edits an artifact.
- Show each proposed revision and why - including the requested edit drafted in step 4. 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 -> run `openspec status --change "<name>" --json` for the next artifact and point the user to `openspec instructions "<artifact-id>" --change "<name>" --json` for how to create it.
- 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 because it does not exist yet (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 - creating them is a separate step, outside this workflow.
- Confirm every edit with the user before writing.
- If the request changes the change's *intent* rather than refining it, ask for a distinct unused change name and recommend `openspec new change "<new-change-name>"` instead (the "Update vs. Start Fresh" heuristic).
+184
View File
@@ -0,0 +1,184 @@
---
name: "OPSX: Verify"
description: "Verify implementation matches change artifacts before archiving"
allowed-tools: Bash(openspec:*)
category: "Workflow"
tags: ["workflow", "verify", "experimental"]
---
Verify that an implementation matches the change artifacts (specs, tasks, design).
**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`, `schemas`, `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.
**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
Otherwise, with no root, what happens next depends on how this workflow was reached:
- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify 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 implementation tasks (tasks artifact exists).
Include the schema used for each change if available.
Mark changes with incomplete tasks as "(In Progress)".
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:verify <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`, `artifactPaths`, and `actionContext`: path and scope context
- Which artifacts exist for this change
3. **Get planning context and load artifacts**
```bash
openspec instructions apply --change "<name>" --json
```
This returns the change directory and `contextFiles` (artifact ID -> array of concrete file paths). Read all available artifacts from `contextFiles`.
4. **Initialize verification report structure**
Create a report structure with three dimensions:
- **Completeness**: Track tasks and spec coverage
- **Correctness**: Track requirement implementation and scenario coverage
- **Coherence**: Track design adherence and pattern consistency
Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
5. **Verify Completeness**
**Task Completion**:
- If `contextFiles.tasks` exists, read every file path in it
- Parse checkboxes: complete means the box holds only `x`/`X`, ignoring
spacing (`- [ x]` is complete); every other marker is incomplete
(`- [ ]`, `- []`, and unfamiliar ones such as `- [~]` or `- [-]`)
- Count complete vs total tasks
- If incomplete tasks exist:
- Add CRITICAL issue for each incomplete task
- Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
**Spec Coverage**:
- If delta specs exist in `contextFiles.specs`:
- Extract all requirements (marked with "### Requirement:")
- For each requirement:
- Search codebase for keywords related to the requirement
- Assess if implementation likely exists
- If requirements appear unimplemented:
- Add CRITICAL issue: "Requirement not found: <requirement name>"
- Recommendation: "Implement requirement X: <description>"
6. **Verify Correctness**
**Requirement Implementation Mapping**:
- For each requirement from delta specs:
- Search codebase for implementation evidence
- If found, note file paths and line ranges
- Assess if implementation matches requirement intent
- If divergence detected:
- Add WARNING: "Implementation may diverge from spec: <details>"
- Recommendation: "Review <file>:<lines> against requirement X"
**Scenario Coverage**:
- For each scenario in delta specs (marked with "#### Scenario:"):
- Check if conditions are handled in code
- Check if tests exist covering the scenario
- If scenario appears uncovered:
- Add WARNING: "Scenario not covered: <scenario name>"
- Recommendation: "Add test or implementation for scenario: <description>"
7. **Verify Coherence**
**Design Adherence**:
- If `contextFiles.design` exists:
- Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
- Verify implementation follows those decisions
- If contradiction detected:
- Add WARNING: "Design decision not followed: <decision>"
- Recommendation: "Update implementation or revise design.md to match reality"
- If no design.md: Skip design adherence check, note "No design.md to verify against"
**Code Pattern Consistency**:
- Review new code for consistency with project patterns
- Check file naming, directory structure, coding style
- If significant deviations found:
- Add SUGGESTION: "Code pattern deviation: <details>"
- Recommendation: "Consider following project pattern: <example>"
8. **Generate Verification Report**
**Summary Scorecard**:
```markdown
## Verification Report: <change-name>
### Summary
| Dimension | Status |
|--------------|------------------|
| Completeness | X/Y tasks, N reqs|
| Correctness | M/N reqs covered |
| Coherence | Followed/Issues |
```
**Issues by Priority**:
1. **CRITICAL** (Must fix before archive):
- Incomplete tasks
- Missing requirement implementations
- Each with specific, actionable recommendation
2. **WARNING** (Should fix):
- Spec/design divergences
- Missing scenario coverage
- Each with specific recommendation
3. **SUGGESTION** (Nice to fix):
- Pattern inconsistencies
- Minor improvements
- Each with specific recommendation
**Final Assessment**:
- If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
- If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
- If all clear: "All checks passed. Ready for archive."
**Verification Heuristics**
- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
- **Coherence**: Look for glaring inconsistencies, don't nitpick style
- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
**Graceful Degradation**
- If only tasks.md exists: verify task completion only, skip spec/design checks
- If tasks + specs exist: verify completeness and correctness, skip design
- If full artifacts: verify all three dimensions
- Always note which checks were skipped and why
**Output Format**
Use clear markdown with:
- Table for summary scorecard
- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
- Code references in format: `file.ts:123`
- Specific, actionable recommendations
- No vague suggestions like "consider reviewing"
+151
View File
@@ -0,0 +1,151 @@
---
paths:
- "src/api/**"
- "src/core/**"
- "src/schemas/**"
- "student-tests/**"
---
# Контракт API: что требуют smoke и защита
Источники: `contracts/openapi.json` (пути, схемы, коды),
`contracts/README.md` (семантика; приоритет над поведением библиотек,
кроме согласованных расхождений FastAPI — раздел ниже), рубрика в
`README.md`. Сгенерированная FastAPI схема (`/openapi.json`) — только
справка, сверять с контрактом. Если контракт противоречит сам себе —
спросить пользователя. Ниже то, что легко нарушить.
## FastAPI: что разрешено и что всё равно ловит smoke
Преподаватель 2026-09-26 разрешил FastAPI с его расхождениями: лишний
422 и другой порядок кодов ошибок (AGENTS.md, «Согласования с
преподавателем»). Публичный smoke это не отменяет: на каждый ответ
≥ 400 он проверяет и статус, и тело `{"error": ...}`. Проверено на
FastAPI 0.141 из `uv.lock`:
| Запрос | FastAPI по умолчанию | Smoke ждёт |
|---|---|---|
| `GET /api/v1/users/me` без `X-User-Id`, заголовок объявлен `Header()` | 422 | 401 |
| `POST .../messages` с `{"text": ""}` | 422 | 400 |
| `GET .../messages?limit=0` | 422 | 400 |
| любая ошибка | `{"detail": ...}` | формат контракта |
- Один обработчик `RequestValidationError` → 400 `invalid_request` в
формате контракта. Оставлять 422 выборочно сложнее, чем перевести всё,
поэтому 422 не отдаётся вообще.
- `X-User-Id` не объявлять типизированным `Header()`: пропуск или не-UUID
уйдёт в валидацию и даст 400 вместо 401. И не читать его вручную из
`request.headers`: тогда в `/openapi.json` нет схемы `devUser` из
контракта, а в `/docs` нет кнопки Authorize. Правильно — схема
безопасности `APIKeyHeader(name="X-User-Id", scheme_name="devUser",
auto_error=False)` в `get_current_user`: без заголовка она отдаёт
`None`, и 401 бросает сервис. С лабы 2 так же — своя схема для Bearer.
- Порядок проверок не выправлять, это и есть разрешённое расхождение.
Битый JSON FastAPI разбирает до зависимостей, поэтому запрос без
`X-User-Id` с битым JSON получит 400, а не 401. Остальная валидация
(тело, путь, query) идёт после зависимостей, там 401 приходит первым.
Расхождение перечислить в `REPORT.md` со ссылкой на согласование.
- `StarletteHTTPException` (404 неизвестного пути, 405) и `Exception`
(500) тоже переводятся в формат контракта.
## Формат ответов
- Непустой `X-Request-Id` в **каждом** ответе: успех, ошибка, health,
404 неизвестного пути, 405, 500.
- Любая ошибка: `{"error": {"code": ..., "message": ..., "request_id":
...}}` с `Content-Type: application/json`, и `request_id` совпадает с
заголовком. Лишних полей нет (`additionalProperties: false`).
- `message` — короткий текст для человека **на английском** (язык
контракт не задаёт, русский текст в `contracts/examples.json` — только
пример). В нём нет stack trace, путей к файлам, имён классов, SQL и
признаков существования чужого объекта. Источник текста —
`default_message` доменного исключения или общий текст обработчика в
`errors.py`.
- Обработчики `RequestValidationError`, `StarletteHTTPException` и
`Exception` переопределяются в `src/api/errors.py` (раздел «FastAPI»
выше).
| Статус | `code` | Когда |
|---|---|---|
| 400 | `invalid_request` | тело, UUID, `limit`, `cursor`, malformed JSON, лишнее поле, неверный тип |
| 401 | `unauthorized` | нет `X-User-Id`, не UUID, пользователя нет |
| 404 | `not_found` | объекта нет **или** он чужой; неизвестный путь |
| 409 | `conflict` | `username` занят |
| 500 | `internal_error` | необработанное исключение, без деталей |
`413`, `415`, `429`, `503` в схеме есть, но на лабе 1 обязательной причины
для них нет. Для 429 нужен `Retry-After` (трек 2 уровня 5).
- Время — RFC 3339 UTC с `Z`, назначает сервер. Формат отдавать явно
через `src/utils/utc.py`, а не полагаться на сериализацию по
умолчанию: smoke требует окончание `Z`.
- `created_at` хранится и отдаётся с одной точностью (микросекунды).
Иначе порядок, который видит клиент, разойдётся с порядком курсора.
- `GET /health/live` → 200 `{"status": "ok"}`. `GET /health/ready` → 200
`{"status": "ok"}` или 503 в формате ошибки. Обе без идентификации.
## Валидация → 400
- Модели запросов: `extra="forbid"` и строгие типы на уровне полей
(`StrictStr`, `StrictInt`), чтобы число не превращалось в строку, а
лишнее поле давало 400. `ConfigDict(strict=True)` на всю модель не
ставить: FastAPI валидирует тело как Python-объект, и strict-режим
отвергает UUID, пришедший строкой (проверено: корректный
`member_ids` даёт 422). Query-параметры остаются нестрогими:
`limit=5` приходит строкой.
- Malformed JSON и не-объект вместо объекта → 400. FastAPI отдаёт их как
422 `json_invalid`, это переводится общим обработчиком.
- Обязательные строки (`display_name`, `title`, `text`) не могут
состоять только из пробельных символов (`str.strip()` пустой → 400).
Само значение не обрезать.
- Длины считаются в Unicode code points: `len(str)` в Python как раз они.
`display_name` и `title` — 1–100, `text` — 1–4000.
- `username` — строго `^[a-z0-9_]{3,32}$` на всю строку. В ручной проверке
`re.fullmatch`: `re.match` с `$` пропускает `\n` в конце.
- Лишнее поле `sender_id` в теле сообщения → 400: отправитель выводится
из текущего пользователя.
- `chat_id` не UUID → 400. `limit` — целое 1–100, по умолчанию 50;
`limit=0` и нечисловой → 400. Битый `cursor` → 400.
- `member_ids`: 1–100 элементов, без дубликатов, все пользователи
существуют, вызывающий в списке. Иначе 400.
## Идентификация (лаба 1)
- Защищено всё, кроме `POST /api/v1/users` и health. `X-User-Id` —
UUID существующего пользователя. Нет заголовка, не UUID или
пользователя нет → 401.
- Сначала идентификация, потом доступ: без заголовка — 401 даже на
чужой чат. Чужой и несуществующий чат дают одинаковый 404, 403 не
используется.
- Меняется только зависимость `get_current_user`: с лабы 2 там Bearer,
а `X-User-Id` игнорируется (`COURSE.md`, переход 1 → 2).
## Чаты и сообщения
- Чат создаётся атомарно. `GET /api/v1/chats` возвращает только чаты
текущего пользователя, по `(created_at, id)` по возрастанию, с
`limit` / `cursor`, как история.
- Любой участник читает чат и историю и пишет в чат. Посторонний
получает 404 на `GET` чата, историю и `POST` сообщения.
## Пагинация (keyset)
- Порядок `(created_at, id)` по возрастанию. `id` сравнивается как UUID
(`uuid.UUID(x).int`) — так же сортирует smoke.
- Ответ: `{"items": [...], "next_cursor": null | "..."}`. `next_cursor`
равен null, когда следующей записи нет на момент чтения. Страница
ровно из `limit` элементов при пустом остатке тоже даёт null, поэтому
repo выбирает `limit + 1`.
- Курсор непрозрачный (`src/utils/cursor.py`): ключ последнего элемента
плюс область — чат или список чатов пользователя. Курсор другого чата
или пользователя, битая base64 или JSON → 400. Последний элемент
предыдущей страницы не повторяется. `limit` между страницами можно
менять.
- Семантику при конкурентных вставках и ограничения часов описать в
`REPORT.md` (например: `created_at` монотонен внутри чата).
## Состояние лабы 1
Только память одного процесса, один worker uvicorn. После рестарта
контейнера прежний `X-User-Id` получает 401 — это ожидаемая потеря
данных, её показывают на защите.
+72
View File
@@ -0,0 +1,72 @@
---
paths:
- "src/api/**"
- "src/main.py"
---
# Слой API (`src/api/`, `src/main.py`)
FastAPI, один процесс. Что обязан отдавать HTTP —
`.claude/rules/api-contract.md`; здесь — как устроен слой.
## Роутинг
| Что | Файл | Путь |
|---|---|---|
| health | `routers/health.py` | `/health/live`, `/health/ready` — вне версии, без идентификации, из access-лога исключены |
| ручки v1 | `routers/v1/<domain>.py` | `/api/v1/<prefix>/...` |
- Модуль домена: `router = APIRouter(prefix="/users", tags=["users"])`.
Вложенный ресурс — префикс с параметром: `message.py` →
`prefix="/chats/{chat_id}/messages"`. Логгер модуля
`module="api_<domain>_router"`.
- Версию задаёт `v1_router` (`API_V1_PREFIX` из `src/utils/constants.py`)
в `routers/v1/__init__.py`. Регистрация домена — импорт и
`v1_router.include_router(...)` там, больше нигде.
- `src/main.py`: `app = FastAPI(...)`, lifespan, middlewares, обработчики
ошибок (`errors.register(app)`), `include_router` для health и
`v1_router`. `src/__init__.py` пустой: импорт любого модуля `src` не
должен поднимать приложение.
- Новая версия API — пакет `routers/v2/` рядом с v1, v1 не ломать.
## Внутри ручки
- Ручки и зависимости — только `async def`. Синхронная `def` уходит в
threadpool, и тогда in-memory состояние трогают несколько потоков.
- Ручка: зависимости → вызов сервиса именованными аргументами →
DTO в модель ответа (`UserOut.model_validate(dto)`, у модели
`from_attributes=True`). Логики, импортов repo и хранилища здесь нет.
- Текущий пользователь — `Depends(get_current_user)` из
`dependencies.py`. Сервис — зависимость-фабрика
(`Depends(get_chat_service)`), которая собирает его из хранилища в
`request.app.state`; с лабы 2 — из `AsyncSession`.
- Ошибки — доменные исключения из сервиса. `HTTPException` не бросать.
Статус и `code` назначает одна таблица в `errors.py`.
- Модели запросов и ответов — `src/api/schemas/<domain>.py`, имена по
схемам контракта (`CreateUser`, `User`, `ChatPage`...). В сервис модели
API не передавать: разбирать в именованные аргументы или
`Create<Entity>DTO`.
- POST создания — `status_code=201` в декораторе; `response_model` —
модель контракта.
## Middlewares и обработчики ошибок
- Request id: генерируется на каждый запрос, пишется в contextvar
логгера и в `request.state.request_id` и ставится заголовком
`X-Request-Id` в ответ.
- 500 от необработанного исключения формирует `ServerErrorMiddleware`.
Он стоит снаружи пользовательских middleware, и заголовок из них в этот
ответ не попадёт. Поэтому обработчик `Exception` в `errors.py` сам
берёт id из `request.state` и ставит заголовок. Сам он не логирует:
Starlette после ответа повторно бросает исключение, и traceback пишет
uvicorn (`logging.md`).
- Итоговая запись о запросе — одна строка: метод, полный шаблон пути,
статус, длительность. Без тела, заголовков идентификации и query.
Логи uvicorn access выключены (`access_log=False`), чтобы не было
дублей.
- Полный шаблон пути не брать из `scope["route"].path`: с FastAPI 0.137
роутеры включаются деревом, и там путь без префикса `include_router`
(`/chats/{chat_id}` вместо `/api/v1/chats/{chat_id}`). Источник —
таблица из публичного `iter_route_contexts(app.routes)` в
`request_context.py`. Структуру роутеров ради логов не менять.
- С лабы 3 — middleware `X-Instance-Id` на все ответы, созданные API.
+136
View File
@@ -0,0 +1,136 @@
---
paths:
- "bench/**"
---
# Нагрузочный стенд (`bench/`)
Эксперимент трека 1 уровня «5» (`README.md`): матрица размеров истории
и уровней конкуренции для чтения и записи, метрики и сырые данные в
`evidence/bench/<метка>/`. Что стенд обязан делать — спек
`load-benchmark`, почему так — design changes `load-bench-harness`
(стенд) и `perf-bottleneck-fix` (диагностика и сравнение меток; после
архивации — `openspec/changes/archive/`), результаты и выводы —
`REPORT.md`, раздел «Эксперименты и отказы».
В `bench/` четыре инструмента:
| Файл | Команда | Что делает |
|---|---|---|
| `run.py`, `k6/` | `make bench`, `make bench_quick` | стенд: меряет пропускную способность, задержки и память |
| `inproc.py` | `make bench_inproc` | диагностика: куда уходит время одного запроса внутри приложения |
| `compare.py` | `make bench_compare` | дельта двух меток стенда, эффект или шум |
| `ab.py` | `make bench_ab` | стенд и диагностика «до» и «после» одного изменения подряд, в одной сессии хоста |
## Что не меняется между метками
Метки сравнимы, только если различается код приложения и больше ничего.
Не меняются:
- **лимиты контейнера приложения:** `--cpus=1 --memory=2g
--memory-swap=2g`, `--no-healthcheck`, без `.env` и `config.toml`,
порты на хост не публикуются;
- **генератор:** `grafana/k6` той же версии и digest, в той же
docker-сети, без лимита CPU;
- **профиль `full`:** размеры, конкуренция, повторы, прогрев и
длительности, длина текста, порция наполнения, зерно выбора курсоров
и сдвиг зерна для прогрева, порог пометки `generator`. Все они — поля
`Profile` в `run.py` и целиком пишутся в `meta.json`: новый параметр
методики заводится там же, а не константой в коде.
Изменить что-то из списка — значит сменить методику: старые метки
перестают быть «до», базовый замер переснимается, а в `REPORT.md`
записывается, что и почему поменялось.
## Как писать
- Стенд — чёрный ящик: `run.py`, `k6/` и `compare.py` не импортируют
`src` и не ходят в приложение мимо HTTP. Все запросы делает k6 внутри
сети стенда, оркестратор управляет только docker CLI. Единственное
исключение — режим `--child` в `inproc.py`: он работает внутри
контейнера и импортирует приложение, потому что разложить время
внутри процесса снаружи нельзя. На хосте `inproc.py` тоже только
управляет docker.
- Скрипты `bench/` на хосте — только stdlib Python, запуск
`uv run python bench/<файл>.py`. Новых зависимостей не добавлять.
- Сценарии k6 — JavaScript без Node.js: только встроенные модули k6.
Заголовок идентификации собирается в одном месте `lib.js`: на лабе 2
он станет Bearer, как `Actor.headers()` в `student-tests/`.
- Имена контейнеров и сети — `mtusi-bench-*`. Чужие контейнеры
(`make run_docker`, другие проекты) стенд не трогает и не
останавливает. Уборка своих — в `finally` и по Ctrl+C.
- Случайность только через свой генератор с зерном из профиля
(`seed + номер VU`), не `Math.random`.
## Диагностика: `make bench_inproc`
- Она объясняет, а не меряет. Её числа не попадают в таблицы
результатов стенда и не выдаются за пропускную способность: в
`REPORT.md` они идут как «куда уходит время запроса», рядом с путём к
файлу в `evidence/profile/`.
- Процесс запускается в образе стенда с тем же `--cpus=1`, отсоединённо
(`docker run -d`), как контейнер стенда. С подключённым клиентом
docker и на хосте цена логов другая: запись в stdout контейнера стоит
процессу десятки микросекунд на запрос.
- Время запроса гуляет от запуска процесса к запуску на 1–3%. Поэтому
каждый режим логов запускается несколько раз, а варианты одного шага
(текущий форматтер против эталонного) сравниваются внутри одного
процесса.
- Варианты кода для сравнения живут в самом скрипте (подклассы моделей
ответа), а не в `src`. Если для пробы всё же меняется `src` — правило
следующего раздела.
- Сверка формата времени с эталоном — часть команды: правка
`src/utils/utc.py` проверяется ею, а не на глаз.
## Измеренное состояние — commit
Указание пользователя (2026-09-30). Перед замером или тестом, результат
которого идёт в отчёт, состояние кода коммитится; хеш попадает в шапку
файла доказательства и в `REPORT.md`. Пробное изменение `src`, которое
потом откатывается, — отдельный commit, откат — новый commit поверх
(`git revert`), без переписывания истории. Любое число в отчёте должно
воспроизводиться из названного commit. Push и остальные операции git —
по-прежнему только по просьбе.
## Сравнение меток: `make bench_compare`
- «До» и «после» снимаются в одной сессии хоста, подряд, без
перезагрузки между ними. Код приложения между ними отличается одним
изменением.
- Порядок: изменение закоммичено, проверено тестами и откачено
отдельным commit; затем `make bench_ab BEFORE=... AFTER=...
REAPPLY=<commit отката>` снимает «до», коммитит доказательства,
возвращает изменение и снимает «после». Команда сама делает два
коммита и отказывается стартовать на нечистом рабочем дереве: стенд
записал бы в паспорт `dirty: true`.
- Уровень шума берётся из сравнения двух меток одного и того же кода
приложения (A/A), параметр `AA`. Что код одинаков, проверяется по git
(`git diff <commit> <commit> -- src Dockerfile pyproject.toml
uv.lock`): команда этого не видит.
- Изменение в ячейке — эффект, только если разбросы повторов не
пересекаются и изменение медианы больше уровня шума сценария. Дельту
в отчёт переносить из таблицы команды, не считать вручную.
- Ячейки сценария, который изменение не затрагивает, — контроль: они
тоже показываются в отчёте.
## Результаты
- Каталог метки не перезаписывается. `evidence/bench/quick-*` — в
`.gitignore`: короткий прогон проверяет стенд, а не даёт результат.
- `evidence/profile/<метка>.txt` тоже не перезаписывается; пробные
метки `quick-*` — в `.gitignore`. `evidence/compare/<до>__<после>.md`
выводится из неизменяемых каталогов меток и может пересоздаваться.
- Столбцы `runs.csv` и `prefill.csv` не переименовываются и не
удаляются: по ним сравниваются метки. Новая метрика — новый столбец
в конце.
- В результатах нет секретов, `.env` и абсолютных путей домашнего
каталога; данные синтетические.
- Перед полной матрицей хост должен быть в состоянии, которое можно
проверить: питание от сети, swap около нуля (`sysctl vm.swapusage`),
память свободна (`memory_pressure`), посторонних контейнеров нет.
Если swap занят или память под давлением — перезагрузить ноутбук;
если условия выполнены, перезагрузка не обязательна. Состояние
записывается в паспорт (`host_state`), в отчёте оно указывается по
паспорту, а не по плану. Во время прогона ноутбук не нагружать.
Предупреждения о хосте в `meta.json` (`host_warnings`) — повод
переснять, а не игнорировать.
+136
View File
@@ -0,0 +1,136 @@
---
paths:
- "Dockerfile"
- "docker-compose.yml"
- ".dockerignore"
---
# Dockerfile и compose
Форма — как в bp_proxies: мультистейдж с uv, compose с портами из `.env`,
литеральным режимом в `environment` и python-healthcheck. Требования
рубрики (`README.md`, уровни 3 и 4) и `Dockerfile.example` важнее
образца; отличия от него перечислены ниже. Режимы запуска —
`run-modes.md`.
## Dockerfile
- Мультистейдж. В builder — `uv sync --locked --no-dev
--no-install-project` по `pyproject.toml` и `uv.lock` в
`/app/.venv`: слой зависимостей кешируется отдельно от кода. В
runtime — копия `.venv` и `src/`, `PATH` на `/app/.venv/bin`.
Компиляторы и uv в runtime не нужны (в bp_proxies uv ставился в оба
stage).
- Оба stage — на **одном** базовом образе: `.venv/bin/python` —
ссылка на интерпретатор базового образа, на другом образе она
сломается.
- `--no-install-project`: `src/` в builder не копируется, и hatchling
не собирает проект пакетом. `python -m src` находит `src` через
рабочий каталог `/app`.
- Версии закреплены: `тег@sha256:<digest индекса>`. Тег с патч-версией
(`python:3.12.14-slim-trixie`) показывает версию, digest **индекса**
(не манифеста одной платформы) даёт повторяемость и работает на arm64
и amd64. Digest брать из `docker buildx imagetools inspect <тег>`,
строка `Digest:` в начале вывода. Не `latest` и не `3.12-slim`. uv —
`COPY --from=ghcr.io/astral-sh/uv:<версия>@sha256:... /uv /bin/uv`, а
не незакреплённый `pip install uv`. Зависимости — только из lock
(`--locked`): если `uv.lock` не совпадает с `pyproject.toml`, сборка
падает. Директиву `# syntax=` не добавлять: это ещё один
незакреплённый образ, а встроенный frontend BuildKit и так понимает
`RUN --mount`.
- Непривилегированный пользователь: системный `app` с UID/GID 10001 и
`USER app` перед `CMD`. Код и `.venv` копируются от root и доступны
пользователю только на чтение.
- `CMD` в exec-форме: `["python", "-m", "src"]`. Тогда сервер — PID 1 и
сам получает SIGTERM. Не `sh -c "... && ..."` и не `uv run`: это
лишний процесс между docker и сервером.
- `ENV APP__RUN_MODE=docker PYTHONUNBUFFERED=1
PYTHONDONTWRITEBYTECODE=1`, `EXPOSE 8080`.
- `HEALTHCHECK` на `/health/ready` через `python -c "import
urllib.request; ..."` (curl в slim нет) с явными `--interval`,
`--timeout`, `--start-period` и `--start-interval=1s`: без него первая
проверка идёт только через `interval`, и контейнер становится
`healthy` не раньше 10 с. Порт — `APP__PORT` из окружения, по
умолчанию 8080. Healthcheck живёт только в образе: он нужен и без
compose (README запускает образ голым `docker run`), а compose берёт
его из образа и не дублирует.
- В образ не попадают `.env`, `config.toml`, секреты, `tests/`,
`student-tests/`, `contracts/`, `evidence/`, `.claude/`, `openspec/`,
`.venv/`. Отличие от bp_proxies: там `config.toml` копируется в образ,
здесь нельзя. Чистый clone его не содержит, и сборка упала бы, а
`Dockerfile.example` (п. 6) запрещает класть конфиг и секреты в образ.
Конфигурация приходит на старте: `config.toml` монтируется
read-only в `/app/config.toml`, переменные — `environment` compose
или `docker run --env-file .env`. Это согласовано с преподавателем
2026-09-29 как выполнение README, п. 3 и `Dockerfile.example`, п. 6
(AGENTS.md, «Согласования с преподавателем»). Что где лежит —
`settings.md`.
## `.dockerignore`
Файл из skeleton дополнять, а не заменять: `config.toml`, `.claude`,
`openspec`, `tests`, `student-tests`, `contracts`, `*.md`, `Makefile`.
`.dockerignore` не заменяет явный `COPY` только нужного.
Паттерн без `**/` действует только в корне контекста: `__pycache__` из
skeleton не исключает `src/**/__pycache__`, и `.pyc` хоста попадали в
образ. Для вложенных путей — `**/__pycache__`, `**/*.py[cod]`,
`**/.DS_Store`.
## Проверка сборки «из чистого clone»
Без коммита и временного каталога: контекст — ровно файлы будущего
clone (отслеживаемые и новые неигнорируемые):
```sh
git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t mtusi-messenger:lab1 -
```
`.env`, `config.toml` и `.venv` в него не попадают по `.gitignore`.
Перед PR — ещё и настоящий `git clone`.
## docker-compose.yml
- Сервис `api`: `build: .`; порты `"127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"`
(снаружи / внутри, стенд учебный — только localhost); `environment`:
`APP__RUN_MODE=docker`, `APP__PORT=${APP__PORT:-8080}` и мосты
`SECTION__FIELD=${...}` (`settings.md`); healthcheck образа проверяет
`APP__PORT`; `stop_grace_period: 10s`; `restart: unless-stopped`.
Имена переменных в `.env` — `settings.md`, «Имена в `.env`».
- `config.toml` — только длинной записью, иначе при отсутствии файла
Docker молча создаст на хосте каталог `config.toml/`, и приложение
упадёт на чтении настроек (проверено):
```yaml
volumes:
- type: bind
source: ./config.toml
target: /app/config.toml
read_only: true
bind:
create_host_path: false
```
Без файла compose сразу падает с `bind source path does not exist`.
Поэтому `make run_docker` зависит от `env_setup`: недостающие `.env`
и `config.toml` создаются из шаблонов, существующие не трогаются.
Голый `docker compose up` без файла по-прежнему падает. Голый
`docker run` монтирует его так же строго — `--mount
type=bind,src="$PWD/config.toml",dst=/app/config.toml,readonly`, а не
`-v`. На лабе 1 файл необязателен: без него приложение стартует на
дефолтах.
- Смонтированный файл должен читаться непривилегированным пользователем
контейнера. На Docker Desktop права хоста не мешают, на Linux нужен
режим `644` или совпадающий uid.
- Новая переменная контейнера — строка в `.env.example` и в
`environment` сервиса.
- С лабы 2: образы зависимостей с явным тегом (`postgres:17.N`, не
`postgres:17`), свой healthcheck, `depends_on: condition:
service_healthy`. Миграции — отдельный одноразовый сервис, API ждёт
его `service_completed_successfully`. Данные — именованный volume или
bind-mount в `.gitignore`. Скрипты restart и failover volumes не
удаляют (`contracts/infrastructure.json`).
- С лабы 3: реплики API за балансировщиком; внутренние порты реплик
наружу не публиковать.
- На лабе 1 compose необязателен: `docker build` и `docker run` из
README должны работать без него.
+38
View File
@@ -0,0 +1,38 @@
---
paths:
- "src/schemas/**"
---
# DTO и enum-ы (`src/schemas/`)
`src/schemas/dataclasses/<domain>.py` — DTO между repo → service → api;
`src/schemas/enums/<domain>.py` — `StrEnum` доменов. HTTP-модели
(pydantic) лежат не здесь, а в `src/api/schemas/` (`api-layer.md`).
Создавать только те DTO, без которых слой не может отдать данные. Не
плодить обёртки «на будущее».
| Назначение | Имя | Когда нужен |
|---|---|---|
| Вход на создание записи | `Create<Entity>DTO` | полей больше трёх-четырёх, иначе хватит именованных аргументов |
| Полная запись | `<Entity>FullDTO` | сервису и API нужны все поля записи |
| Выборка подмножества полей | `<Entity>InListDTO` | repo выбирает часть колонок (с лабы 2) |
| Страница | `<Entity>PageDTO` | `items` и `next_cursor: str \| None` |
- Каждый класс — `@dataclass`, суффикс `DTO`. Записи, которые хранит
`MemoryStore` (лаба 1), — `@dataclass(frozen=True, slots=True)`: repo
отдаёт их наружу без копирования, изменить состояние в обход repo
нельзя, а `slots` экономит память на миллионах записей. pydantic
читает такие записи через `from_attributes`.
- Обязательные поля первыми, поля со значением по умолчанию — последними;
для `list` / `dict` — `field(default_factory=...)`. В frozen-DTO
коллекции — `tuple` / `frozenset`.
- Типы доменные: `UUID`, а не `str`; `datetime` (aware UTC), а не строки;
`enums.*`; `X | None` для nullable.
- Имена полей `<Entity>FullDTO` совпадают с колонками модели (с лабы 2),
иначе `FullDTO(**row.to_dict())` сломается.
- Каждый новый класс добавляется в `__init__.py` пакета (импорт и
`__all__`) в алфавитном порядке.
- Короткий docstring на русском, если назначение не очевидно из имени.
- Enum-ы — `StrEnum`. С лабы 2 значение хранится в БД, поэтому
переименование значения = миграция (`migrations.md`).
+33
View File
@@ -0,0 +1,33 @@
---
paths:
- "src/infra/**"
---
# Инфраструктура (`src/infra/`)
Всё, что не содержит бизнес-логики и может смениться от лабы к лабе:
логгер, хранилище (лаба 1 — память процесса, с лабы 2 — PostgreSQL),
клиенты Redis, S3, брокера, телеметрии. Бизнес-правил (уникальность,
доступ, валидация) здесь нет: они в сервисах, атомарные операции — в
repo.
- Объект создаётся один раз в lifespan `src/main.py`, кладётся в
`app.state` и закрывается в shutdown lifespan. Соединения при импорте
модуля не открываются; исключение — ленивая настройка логгера.
- Сервисы получают объект через зависимость из `src/api/dependencies.py`
и не импортируют модульный глобал.
- `MemoryStore` (лаба 1, `memory.py`): dict-ы по id и индексы
(`username` → id, пользователь → его чаты, чат → история в порядке
`(created_at, id)`). Хранит frozen DTO. Меняют его только
repo-функции.
- На лабе 1 никаких файлов состояния, pickle, SQLite и внешних
сервисов: рубрика требует, чтобы после рестарта процесса состояние
исчезало.
- `/health/ready` проверяет критичные зависимости через infra. На лабе 1
это «lifespan завершил старт»; с лабы 2 — Postgres и, если он
используется, Redis. Недоступность — 503. Какие зависимости считаются
критичными, фиксируется в `REPORT.md`.
- Клиенты внешних сервисов (с лабы 2): адреса и секреты из
`settings` (`.claude/rules/settings.md`), таймаут на каждый вызов,
ошибки переводятся в доменные исключения в сервисе. Логи — по
`logging.md`, без секретов.
+149
View File
@@ -0,0 +1,149 @@
---
paths:
- "src/core/services/**"
- "src/api/**"
- "src/infra/**"
- "src/main.py"
---
# Логирование
Инфраструктура — `src/infra/logger.py`, по образцу bp_proxies
(`src/core/services/logger.py` там). `get_logger()` возвращает
`AbstractLogger` поверх structlog: JSON в stdout, уровень из
`[app] log_level`.
Само попадает в запись, руками не добавлять: `request_id` из contextvar
(ставит request-id middleware, то же значение, что в `X-Request-Id`),
`user_id` из contextvar (ставит `get_current_user`), timestamp ISO/UTC,
уровень, `filename` / `func_name` / `lineno`. Enum печатается как repr.
## Устройство `src/infra/logger.py`
Это перенос логгера bp_proxies
(`~/PycharmProjects/bp_proxies/src/core/services/logger.py`, есть только
на машине автора) с тремя отличиями, перечисленными ниже.
- `AbstractLogger` (ABC: `debug` / `info` / `warning` / `error` /
`critical` / `bind`) и реализация `StructLogger` лежат в этом же
модуле. `bind()` возвращает новый логгер с объединённым контекстом,
исходный не меняется.
- `get_logger()` инициализируется лениво: первый вызов выполняет
`configure_logger()` и создаёт корневой `StructLogger`. Модули зовут
его на уровне модуля, поэтому настройка применяется уже при импорте
`src.main`, до `uvicorn.run`.
- `structlog.configure_once`, процессоры по порядку:
1. `stdlib.filter_by_level` — запись ниже уровня отбрасывается до
остальных процессоров, включая поиск места вызова;
2. `contextvars.merge_contextvars`, `stdlib.add_log_level`,
`stdlib.ExtraAdder()`;
3. `TimeStamper(fmt="iso", utc=True)`, `format_exc_info`;
4. `CallsiteParameterAdder` (`FILENAME`, `FUNC_NAME`, `LINENO`) с
`additional_ignores=["src.infra.logger"]`;
5. контекстный процессор: `request_id` и `user_id` из contextvar-ов;
6. перестановка ключей: `request_id`, `event`, `user_id` в начало;
7. Enum → repr, UUID → строка (иначе JSONRenderer пишет `UUID('...')`),
поэтому в kwargs можно передавать `UUID` как есть;
8. `stdlib.ProcessorFormatter.wrap_for_formatter`.
`logger_factory=stdlib.LoggerFactory()`,
`wrapper_class=stdlib.BoundLogger`, `cache_logger_on_first_use=True`.
- `logging.config.dictConfig` с `disable_existing_loggers=False`:
- форматтер — `ProcessorFormatter` с `remove_processors_meta` и
`JSONRenderer()`; для записей чужих библиотек — `foreign_pre_chain`
из `merge_contextvars`, `add_log_level`, `add_logger_name`,
`TimeStamper`, `format_exc_info`, контекстного процессора и
перестановки ключей;
- handler — один `StreamHandler` в `ext://sys.stdout`;
- root — `WARNING` с этим handler: предупреждения прочих библиотек тоже
JSON (в bp_proxies root был без handlers);
- `src` — уровень `[app] log_level`, этот handler,
`propagate=False`;
- `uvicorn` — `INFO`, этот handler, `propagate=False`;
`uvicorn.error` — `INFO` без своего handler, пишет через `uvicorn`
(свой handler дал бы дубли); `uvicorn.access` — выключен;
- шумные библиотеки (с лабы 2 — `sqlalchemy.engine`, `httpx`,
`httpcore`) — `WARNING`.
### Отличия от bp_proxies
1. **Место вызова — через `CallsiteParameterAdder`, а не
`inspect.stack()`.** В bp_proxies каждый метод `StructLogger` зовёт
`inspect.stack()`, а тот читает исходники всех кадров стека. Замер
на глубине стека 40 кадров (как у ручки FastAPI под uvicorn):
~470 мкс только на поиск места вызова против ~3,5 мкс на всю запись
с `CallsiteParameterAdder`. На одном event loop 2–3 строки лога на
запрос съели бы 1–1,5 мс CPU, то есть потолок RPS, который меряется
в треке 1.
2. **`request_id` в процессоре не генерируется.** В bp_proxies при
пустом contextvar процессор создаёт случайный 8-символьный id и
записывает его в contextvar. Здесь id запроса ставит только
middleware, и он обязан совпасть с `X-Request-Id`. Вне запроса
(старт, shutdown) поля нет. Фоновые задачи с лабы 5 ставят свой id
сами, как job в bp_proxies.
3. **uvicorn тоже пишет JSON.** В bp_proxies логгеры `uvicorn.*` не
трогаются и пишут обычный текст. Здесь строки uvicorn об остановке
(«Shutting down», «Waiting for application shutdown.», «Finished
server process») доказывают на защите уровня 4, что SIGTERM
отработал вовремя, поэтому идут в тот же JSON. Для этого
`uvicorn.run(..., log_config=None, access_log=False)`: без
`log_config=None` uvicorn при старте применит свой `LOGGING_CONFIG`
поверх нашего. Access-лог пишет свой middleware (`api-layer.md`).
## Чего в логах быть не должно
Рубрика уровня 4: логи полезные, но **без содержимого сообщений**.
- Текст сообщений, `display_name`, `title` чата, тела запросов и ответов
целиком. Вместо текста — идентификаторы и размеры
(`text_length=len(text)`).
- С лабы 2 — пароли, токены, заголовок `Authorization`,
`Idempotency-Key` целиком; с лабы 4 — подписанные URL и ключи бакета.
- Stack trace — только в лог, никогда в ответ.
## Где логировать
| Слой | Логи | Логгер модуля |
|---|---|---|
| `core/repos` | **никогда** | нет |
| `core/services/<domain>.py` | в каждом методе с побочным эффектом | `module="<domain>_service"` |
| `api/routers/v1/<domain>.py` | только заметные шаги, которых не видно из сервиса | `module="api_<domain>_router"` |
| `api/middlewares` | access-лог: одна строка на запрос; health не логировать | `middleware="http"` |
| `api/errors.py` | не логирует: 4xx — штатные ответы, а traceback непредвиденной ошибки пишет uvicorn (`uvicorn.error`, с `request_id` из contextvar) после повторного броска исключения Starlette | нет |
| `infra/<client>.py` | подключение, закрытие, ошибки; с лабы 2 — запросы к внешним API (`debug`) | `module="<client>"` |
| `main.py` | старт (host, port, режим), начало и конец shutdown | `module="startup"` |
| чистые функции | не логируют, бросают доменные исключения | нет |
Строки старта и shutdown нужны на защите: по ним видно, что SIGTERM
отработал за заявленный срок.
## Как логировать
Логгер модуля один, сразу после импортов:
```python
from src.infra.logger import AbstractLogger, get_logger
logger: AbstractLogger = get_logger().bind(module="chat_service")
```
Contextvar-ы `http_request_id` и `current_user_id` лежат в этом же
модуле; ставят их только request-id middleware и `get_current_user`.
- В начале метода с побочным эффектом —
`log = logger.bind(method="create_chat", chat_id=..., members_count=...)`.
В `bind` идут идентификаторы, по которым лог будут искать.
- Вложенный шаг большой операции принимает `log: AbstractLogger`
параметром и пишет через него.
- Сообщение — константная строка на английском: прошедшее время для
результата («Created chat»), -ing для начала («Creating chat»).
Переменные данные только в kwargs, не в f-string.
- Исключения: `error=str(e)`; `exc_info=e` — только там, где нужен
traceback непредвиденной ошибки.
- Только `get_logger()`: без `print`, `traceback.print_exc()` и
`logging.getLogger`.
Уровни: `debug` — промежуточные шаги; `info` — бизнес-событие (создан
пользователь, чат, сообщение), старт и остановка; `warning` —
обработано, но требует внимания; `error` — операция не выполнена,
непредвиденное исключение. `critical` не используется.
+37
View File
@@ -0,0 +1,37 @@
---
paths:
- "migrations/**"
- "src/infra/db/models/**"
---
# Миграции alembic и модели (с лабы 2)
Основа — правила bp_proxies; отличия продиктованы контрактом.
- Модели — `src/infra/db/models/<domain>.py`. `Base` даёт `created_at`
и `to_dict()`. Новая модель экспортируется в `models/__init__.py`,
иначе autogenerate её не видит.
- Первичный ключ — `UUID`, значение генерирует сервис (`uuid4()`):
контракт отдаёт UUID. Автоинкремент не использовать.
- Время — `DateTime(timezone=True)` (`timestamptz`), aware UTC: контракт
требует `...Z`. В bp_proxies было naive UTC — здесь так нельзя.
- Индексы под запросы контракта: `(chat_id, created_at, id)` для
keyset-истории, уникальный `username`, участник → чаты.
- Колонки типизированы `Mapped[...]`, внешние ключи — через
`ForeignKey`.
- Имя файла ревизии `YYYY_MM_DD_HHMM-<rev>_<slug>.py` (`file_template`
в `alembic.ini`). Сообщение короткое, на английском, в прошедшем
времени («added chats tables»). Пустая ревизия (`pass` в `upgrade`) —
удалить.
- Autogenerate не видит: новые значения enum, изменение
`server_default`, частичные индексы (`postgresql_where`),
переименования (сделает drop + create). Их правят руками.
- `NOT NULL` на существующей таблице — с `server_default` или с
backfill через `op.execute` перед `alter_column`.
- Constraint-ы именованные, чтобы `downgrade` мог их снять. `downgrade`
зеркалит `upgrade` в обратном порядке. Применённую ревизию не
редактировать: новая ревизия поверх.
- Миграции применяются до старта API: в compose — отдельный
одноразовый сервис, API ждёт `service_completed_successfully`. Не
`sh -c "alembic upgrade head && python -m src"` (сервер перестаёт быть
PID 1) и не из lifespan: с лабы 3 реплик несколько.
+39
View File
@@ -0,0 +1,39 @@
---
paths:
- "src/core/repos/**"
---
# Слой repo (`src/core/repos/<domain>.py`)
Только доступ к данным. Ни бизнес-логики (проверок доступа, валидации),
ни логов, ни внешних вызовов.
- Модульные `async def`, без классов. Первый параметр — хранилище: на
лабе 1 `store: MemoryStore`, с лабы 2 `db_session: AsyncSession`.
Остальные параметры вызывающий передаёт по имени.
- **Одна атомарная операция на функцию.**
- Лаба 1: внутри функции нет ни одного `await`. Всё выполняется в
одном event loop, поэтому другой запрос её не прервёт. В этом и
состоит защита от гонок, её объясняют на защите.
- Лаба 2: максимум один `db_session.execute(...)`. Нужна вторая
выборка — вторая функция, CTE, подзапрос или `.returning(...)`.
- Уникальность проверяется в той же функции, что и вставка. На лабе 1
проверка индекса и запись идут без `await` между ними; с лабы 2 —
`pg_insert(...).on_conflict_do_nothing(...).returning(...)`. При
конфликте функция возвращает `None`, исключение бросает сервис.
- Наружу отдаются DTO (`.claude/rules/dto.md`), а не внутренние
структуры хранилища. На лабе 1 хранилище держит frozen DTO, их можно
отдавать как есть; списки — всегда новым `list`, не внутренним. С
лабы 2 — `expunge` и `<Entity>FullDTO(**row.to_dict())` либо DTO из
выбранных колонок, а не `select(Model)`.
- Никаких `commit()` / `rollback()`: транзакцией управляет сервис.
- Мутации возвращают осмысленный результат: созданный DTO, `bool`,
`None` при конфликте.
- Keyset-страница: параметры `after: tuple[datetime, UUID] | None` и
`limit`, выборка `limit + 1` элементов, чтобы сервис узнал о следующей
странице. На лабе 1 история чата — список в порядке `(created_at, id)`:
вставка через `bisect.insort(..., key=...)`, позиция курсора — через
`bisect`, без полного прохода.
- Опциональные фильтры и лимиты — условное дополнение выборки
(`if limit is not None: ...`).
- Логов в репозиториях нет: ни `get_logger`, ни `print`.
+94
View File
@@ -0,0 +1,94 @@
---
paths:
- "src/main.py"
- "src/__main__.py"
- "src/config/settings.py"
- "Makefile"
- "docker-compose.yml"
- ".env.example"
- "config_example.toml"
---
# Режимы запуска: console и docker
Режим задаёт `APP__RUN_MODE` (`settings.app.run_mode`, `RunModeEnum`),
дефолт — `console`. В `.env` режим не хранится. Для docker его задают
`ENV APP__RUN_MODE=docker` в Dockerfile (чтобы голый `docker run` из
README слушал `0.0.0.0`) и литерал в `environment` compose; для консоли —
цели Makefile.
| | console | docker |
|---|---|---|
| Процесс | `uv run python -m src` на хосте | `python -m src` — PID 1 контейнера |
| uvicorn | `127.0.0.1`, `reload=True` по `src/` | `0.0.0.0`, без reload |
| Порт | `settings.app.port`: `APP__PORT` из `.env`, без него — 8080 | `APP__PORT` из `.env` внутри (на нём же healthcheck), `APP_OUT_PORT` снаружи — одинаково в compose и `run_no_compose` |
| Лаба 1 | память процесса; reload = пустое состояние | память процесса; рестарт контейнера = пустое состояние |
| С лабы 2 | Postgres / Redis в compose, снаружи `localhost:<*_OUT_PORT>`; миграции — `make upgrade` | зависимости по имени сервиса; миграции — отдельный сервис до старта API (`migrations.md`) |
## Точка входа
`python -m src` → `src/__main__.py` → `src.main:main()` →
`uvicorn.run("src.main:app", host=..., port=..., reload=...,
timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
Хост выбирается по режиму, как в bp_proxies. `log_config=None` нужен,
чтобы uvicorn не перетёр JSON-логирование (`logging.md`).
- Worker всегда один. Состояние лабы 1 живёт в памяти процесса, и второй
worker получил бы второе независимое состояние (это вопрос защиты).
Масштабирование — только в лабе 3, отдельными контейнерами за
балансировщиком.
- SIGTERM: uvicorn перестаёт принимать новые соединения и ждёт текущие
запросы до `timeout_graceful_shutdown` (настройка
`[app] graceful_shutdown_seconds`, не больше 8 с). Docker шлёт SIGKILL
через 10 с, в compose — `stop_grace_period`. Shutdown в lifespan
только логирует и закрывает клиенты, долгих операций в нём нет.
Рубрика уровня 4 требует завершения не дольше 10 с.
## Makefile
- Цели skeleton `help`, `check`, `validate`, `test`, `load` не менять:
в следующей лабе `Makefile` придёт новый, и свои цели в него
переносятся слиянием (AGENTS.md, «Переход в следующую лабу»).
- Свои цели — отдельными секциями ниже целей skeleton, в стиле
bp_proxies: переменные наверху (`DC=docker compose`), заголовки
`# -------------------------`, свой `.PHONY` у каждой цели, имена в
snake_case. Apple Container не делать.
- Набор для лабы 1:
- `run_dev` (`APP__RUN_MODE=console uv run python -m src`);
- `run_no_compose: env_setup` — команды README: `docker build`, затем
`docker run --rm -p 127.0.0.1:$(APP_OUT_PORT):$(APP__PORT)
--env-file .env ...` на переднем плане, без `config.toml`. Порты
из `.env` (`-include .env` в секции `Docker targets`, дефолт 8080),
с шаблонным `.env` команда совпадает с README. Остановка — Ctrl+C
или `docker stop`;
- `run_docker: env_setup` (недостающие `.env` и `config.toml` из
шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`),
к нему `stop`, `down`, `logs`
(`$(DC) logs -f --no-log-prefix api`: без префикса `api-1 |`
каждая строка — JSON);
- `lint` (`ruff format .` + `ruff check --fix .`, дважды),
`env_setup` (копирует шаблоны `.env` и `config.toml`),
`student_test`.
`run_no_compose` и `run_docker` — два способа запуска контейнера,
оба описываются в `REPORT.md`.
- С лабы 2: `start_db` / `stop_db`, `start_redis` / `stop_redis`,
`revision` (интерактивный `read -p`), `upgrade`. Volume передаётся
переменной (`POSTGRES_VOLUME=$(DOCKER_POSTGRES_VOLUME)`), перед
миграциями поднимается БД.
## Troubleshooting
- `make test` падает с 404 на `/health/live` вместо ошибки соединения:
на 8080 отвечает чужой сервис. Найти его — `lsof -nP -iTCP:8080
-sTCP:LISTEN` и `docker ps`; для своего стенда взять другой
`APP_OUT_PORT` и `make test BASE_URL=http://localhost:<порт>`.
- Разовая подмена внешнего порта для целей Makefile — только
аргументом: `make run_docker APP_OUT_PORT=8090`. Внутренний
`APP__PORT` — только в `.env`: в `run_no_compose` приложение берёт
его из `--env-file .env`, аргумент make сдвинул бы лишь `-p`. Префикс
`APP_OUT_PORT=8090 make ...` не сработает: `-include .env` перекроет
его, и в recipe (в том числе в `docker compose`) уйдёт значение из
`.env`.
- Поменял `config.toml` и не видишь эффекта: значение перекрыто
окружением или `.env` (приоритет env > .env > toml).
+41
View File
@@ -0,0 +1,41 @@
---
paths:
- "src/core/services/**"
---
# Слой service (`src/core/services/<domain>.py`)
Бизнес-логика, проверки доступа, серверные значения (id, время),
транзакции (с лабы 2), вызовы внешних клиентов, логи.
- Класс `<Domain>Service`. `__init__` принимает хранилище и хранит его
в `self`: на лабе 1 — `store: MemoryStore`, с лабы 2 —
`db_session: AsyncSession`. Методы принимают keyword-only параметры
(`*,`) и вызываются только именованными аргументами.
- Repo: `from src.core.repos import chat as chat_repo`. Вызов —
`store=self.store` (`db_session=self.db_session`) и именованные
аргументы.
- Проверка доступа — здесь. Не участник получает то же исключение, что
«не найден» (`ChatNotFound`): API отдаст 404 и не раскроет, что чат
существует.
- Ошибки — доменные исключения из `src/core/exceptions` (новое — в
модуль домена и реэкспорт в `__init__.py`). Не `ValueError` и не
`HTTPException`: статус и `code` назначает `src/api/errors.py`.
- Серверные значения назначает сервис: `id = uuid4()`,
`created_at = utcnow()` из `src/utils/utc.py`.
- Атомарность на лабе 1: одна мутация — один вызов repo. Составную
проверку с записью (уникальность `username`) делает одна
repo-функция. Схема «сервис проверил, потом вставил» с `await` между
шагами не годится (`repo-layer.md`).
- С лабы 2 коммитит только сервис: `await self.db_session.commit()`
после успешной мутации, repo не коммитит. Другой сервис создаётся с
тем же `db_session`, чтобы остаться в одной транзакции.
- Курсор кодирует и разбирает сервис через `src/utils/cursor.py`:
проверяет область (этот чат или этот пользователь) и возвращает
`<Entity>PageDTO` с готовым `next_cursor`. Неверный курсор — доменное
исключение (→ 400).
- Чистые вычисления — модульные функции над классом, без обращения к
хранилищу.
- Read-only методы, которые лишь делегируют в repo, не логируют.
Остальное — по `.claude/rules/logging.md`.
- Константы (лимиты, размер страницы) — `src/utils/constants.py`.
+133
View File
@@ -0,0 +1,133 @@
---
paths:
- "src/config/**"
- ".env.example"
- "config_example.toml"
---
# Настройки: `.env`, `config.toml`, `src/config/settings.py`
Схема из bp_proxies (`src/data/settings.py` там). Что делают режимы
console и docker — `.claude/rules/run-modes.md`. Здесь — откуда берутся
значения и куда класть новое.
## Источники `Settings`
- `src/config/settings.py`: `Settings(BaseSettings)` из секций-`BaseModel`
(`App`; с лабы 2 — `Database`, `Redis`...). Экземпляр один —
`settings` на уровне модуля. Импорт везде `from src.config import
settings`. Второй `Settings()` не создавать, поля в рантайме не менять.
- Приоритет (`settings_customise_sources`): окружение процесса → `.env`
→ `config.toml` → дефолты. Отсутствующий файл пропускается. Без
`.env` и `config.toml` приложение обязано подняться на дефолтах: так
работают `docker run` из README и чистый clone.
- Все поля живут в секциях, откуда бы ни пришло значение: секцию задаёт
класс `Settings`, а не файл. Вложенные поля в env — через `__`,
регистр не важен: `DATABASE__PASSWORD` попадает в
`settings.database.password` так же, как `[database] password` из
TOML. Переменную без префикса секции (`APP_PORT`, `POSTGRES_PASSWORD`)
приложение не видит: она для compose.
- Имена переменных, которые задаёт контракт (`SESSION_TTL_SECONDS` с
лабы 2), тоже не выносятся из секций. Поле остаётся в секции
(`[auth] session_ttl_seconds`), а контрактное имя приходит мостом
(раздел «Мосты» ниже).
- `extra="ignore"`: опечатка в ключе молча оставит дефолт. После правки
проверить конкретное поле: `uv run python -c "from src.config import
settings; print(settings.app.port)"`. Полный дамп настроек не печатать
(с лабы 2 в нём пароли).
- Подмена через окружение ставится до первого импорта `src`: потом
`settings` уже прочитан.
## Что где хранится
Критерий — кто читает значение, а не секретное ли оно.
| Где | Что | В git |
|---|---|---|
| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, лимиты трека 5, TTL, адреса зависимостей для console, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` |
| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*`, пароли Redis / MinIO / брокера; мосты `SECTION__FIELD=${...}` для приложения | нет; шаблон `.env.example` |
| окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — |
| `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50), пути: одинаковы на всех установках | да |
Схему согласовали с преподавателем 2026-09-29 (AGENTS.md, «Согласования
с преподавателем»). Секреты в `config.toml` допустимы. Запрет
`Dockerfile.example` касается запекания в образ (`COPY`), а
`config.toml` в образ не копируется, его монтируют на старте
(`docker.md`). Но почти все секреты курса — пароли
Postgres, Redis, MinIO, брокера — нужны ещё и контейнеру зависимости,
а его настраивает только compose из `.env`. Поэтому такой секрет живёт
в `.env` и попадает в приложение мостом. Если продублировать его в
`config.toml`, как `postgres_password` в bp_proxies, получатся два
источника, которые рано или поздно разойдутся.
## Имена в `.env`: параметр приложения — в формате настроек
Если переменная касается самого приложения, в `.env` она пишется в
формате настроек (`SECTION__FIELD`), даже когда её читают ещё compose и
Makefile. Пример — внутренний порт `APP__PORT`: на нём слушает
приложение, его публикуют compose и `make run_no_compose`, на нём
работает healthcheck. Compose читает `${APP__PORT}` напрямую и передаёт
в `environment` под тем же именем, а голый `docker run --env-file .env`
отдаёт его приложению как есть.
Имя без секции — только у того, что приложение не читает:
`APP_OUT_PORT` (порт на хосте), `POSTGRES_*` и другие переменные
контейнеров зависимостей. Если такое значение нужно ещё и приложению,
оно приходит мостом (ниже).
Поле, которое задаётся в `.env`, в `config_example.toml` не
дублируется: по приоритету значение из `.env` перекрыло бы toml, и
строка там ни на что не влияла бы. Поэтому в `[app]` нет `port`.
`.env` читает и Makefile (`-include .env`), поэтому комментарии в нём
пишутся только отдельными строками. make, в отличие от compose,
оставляет пробел перед `# комментарий` в конце строки частью значения.
## Мосты: значение из `.env` в секцию приложения
Мост нужен, когда имя переменной навязано контейнером зависимости
(`POSTGRES_PASSWORD` для образа postgres), а приложению то же значение
нужно в своей секции. Мост — строка, которая отдаёт значение переменной
compose полю секции:
- в `.env` — `DATABASE__PASSWORD=${POSTGRES_PASSWORD}`: pydantic-settings
раскрывает `${VAR}` при чтении `.env` (проверено на 2.15), так
значение получает приложение в console-режиме;
- в `environment` сервиса compose — та же строка, так значение получает
контейнер. Сам `.env` в контейнер не передаётся.
`docker run --env-file .env` раскрывать `${...}` не умеет и передаст
строку буквально. На лабе 1 мостов нет, а с лабы 2 стенд запускается
только через compose.
`.env.example` из skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`) — это
«логические» имена. После перехода на эту схему соответствие
переменных реальной конфигурации описать в `REPORT.md` (раздел
«Архитектура и решения»).
В настройки идёт только то, что отличается между установками, либо
секрет. Остальное — константа.
## Новое поле или секция
1. Поле с типом и безопасным дефолтом: лаба 1 поднимается без файлов.
Секрет — `""` и проверка при старте там, где он нужен. Единицы —
коротким комментарием (`# секунды`).
2. Новая секция — класс `<Name>(BaseModel)` и поле
`<name>: <Name> = <Name>()` в `Settings`. Имя поля одновременно имя
секции TOML и префикс env.
3. Строка в `config_example.toml` с плейсхолдером и в рабочем
`config.toml`. Значения из `config.toml` не печатать в ответ и лог.
4. Значение нужно и compose, и приложению:
- параметр самого приложения (порт) — переменная `SECTION__FIELD` в
`.env.example` с комментарием и в `environment` сервиса compose
(`docker.md`);
- значение с именем, которое навязывает контейнер зависимости
(пароль Postgres), — переменная и мост в `.env.example`, мост в
`environment` сервиса compose.
В обоих случаях в `config_example.toml` поле не дублировать.
5. Строка подключения — `@property` секции (`Database.url`): вызывающий
код URL сам не собирает.
6. Когда появятся `config_example.toml` и `config.toml`, добавить
`config.toml` в `.gitignore` и `.dockerignore`.
+60
View File
@@ -0,0 +1,60 @@
---
paths:
- "student-tests/**"
---
# Собственные тесты (`student-tests/`)
В bp_proxies тесты запрещены. Здесь они обязательны для уровня 4
(`README.md`), и каждый должен запускаться одной командой:
- неверный JSON, чужой чат, пустое сообщение, дубликат `username`, обход
нескольких страниц истории;
- гонки: 10 клиентов параллельно отправляют 100 сообщений, после чего
история содержит ровно 100 уникальных. Команду и результат сохранить.
## Как писать
- Black-box по HTTP против запущенного сервера (`BASE_URL`, по умолчанию
`http://localhost:8080`), как публичный smoke. Тест не импортирует
`src` и не поднимает приложение сам: те же тесты проверяют и
контейнер, и следующие лабы.
- pytest + httpx в dev-группе uv, запуск — `make student_test`.
- Каждый тест создаёт своих пользователей с уникальным `username`
(uuid-суффикс): состояние сервера общее, а удалять данные API не умеет.
- Проверять не только статус, но и форму: `{"error": {...}}` с
`code`, `request_id` совпадает с `X-Request-Id`, у успешных ответов
нет лишних полей. Семантика — `.claude/rules/api-contract.md`.
- Тест гонок — реальная параллельность, а не цикл: потоки за
`threading.Barrier`, у каждого свой `Api` (своё соединение). Тест
требует, чтобы одновременно в полёте было ≥ 2 запросов, иначе гонка
не доказана. Проверяются количество и уникальность `id`, а также
отсутствие потерь при обходе всех страниц.
- `tests/` — публичные проверки skeleton: не править, не ослаблять,
свои тесты туда не класть.
- Вывод прогона (команда, дата, commit, результат) — в `evidence/` и
строкой в таблицу доказательств `REPORT.md`.
## Как устроен набор
- **Идентификация — только `Actor.headers()`** (`api_client.py`).
Тесты передают `actor=`, заголовок руками собирает только
`test_identification.py`: на лабе 2 меняется одна функция и этот
модуль. Пользователь, которого нет на сервере, —
`Actor.unregistered()`.
- **Форма ответа — через `contract.py`**, без ручного сравнения ключей:
`assert_ok(resp, status, "<Schema>")` для успеха, `assert_error(resp,
status)` для ошибки (`code` берётся из статуса). Хелперы `Api`
(`register`, `create_chat`, `send_message`, обход страниц) уже
проверяют схемы.
- **Каждый тест сценария спека помечен** `@pytest.mark.spec("<capability>",
"<Сценарий>")`, имя — дословно из `#### Scenario:`. Новый сценарий в
основном спеке без теста роняет `test_coverage.py`. Если его нельзя
проверить по HTTP, добавить запись в `EXCLUDED` (`spec_coverage.py`)
с причиной и способом проверки.
- Модуль сверки называется `spec_coverage.py`, а не `coverage.py`:
каталог набора стоит в `pythonpath`, и `coverage.py` затенил бы
пакет `coverage` (pytest-cov, coverage-runner IDE).
- Новые пользователи и чаты — фикстуры `alice`, `bob`, `eve`, `chat` из
`conftest.py`: у каждого теста свои. `eve` не состоит ни в одном чате
фикстур.
+173
View File
@@ -0,0 +1,173 @@
---
name: run-mtusi-messenger
description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, in-memory, лаба 1) — на хосте или в Docker. Use when asked to run / start / stop the server or the container, run the smoke test, `make test` or `make student_test`, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the container, or call services directly without HTTP.
---
REST API мессенджера (пользователи, чаты, сообщения) — сервер на
FastAPI/uvicorn, состояние в памяти процесса. Агент управляет им через
`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает свой
экземпляр в фоне, гоняет сценарий по HTTP, публичный smoke и
собственные тесты, шлёт одиночные запросы и останавливает сервер.
Против контейнера (`make run_docker`) работают те же команды драйвера,
кроме `start`/`stop`. Только стандартная библиотека Python.
Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12,
Python 3.12 из `.python-version`, Docker Desktop 29.8.
## Setup
```bash
uv sync --all-extras # venv с ruff и dev-группой (openapi-spec-validator)
make env_setup # .env и config.toml из шаблонов, существующие не трогает
```
Без `.env` и `config.toml` сервер тоже поднимается — на дефолтах
(порт 8080, `INFO`).
## Run (agent path)
```bash
D=.claude/skills/run-mtusi-messenger/driver.py
python3 $D all # start → flow → tests/smoke.py → student-tests → stop; код 0 = всё прошло
```
По шагам, когда между ними нужно что-то сделать (поправить код,
посмотреть лог, послать свой запрос):
```bash
python3 $D start # фон, ждёт /health/ready до 30 с
python3 $D status # listeners: [pid reloader, pid worker], ready: True
python3 $D flow # ~35 проверок: регистрация, 409, /me, 401, чат, 5 сообщений,
# пагинация limit=2 по курсору, чужой → 404, 400-е, X-Request-Id
python3 $D req POST /api/v1/users --data '{"username":"zoe_demo","display_name":"Зоя"}'
python3 $D req GET /api/v1/users/me --user <uuid из ответа выше>
python3 $D smoke # публичный tests/smoke.py против этого порта
python3 $D student # make student_test BASE_URL=http://localhost:<port> — 79 тестов, <1 с
python3 $D stop
```
| команда | что делает |
|---|---|
| `start` | `APP__RUN_MODE=console APP__PORT=<port> uv run python -m src` в своей группе процессов |
| `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого |
| `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat |
| `req METHOD PATH [--user UUID] [--data JSON]` | один запрос: статус, `x-request-id`, тело; код 2 при статусе ≥ 400 |
| `smoke` | `tests/smoke.py --base-url http://localhost:<port>` |
| `student` | `make student_test BASE_URL=http://localhost:<port>` (pytest по `student-tests/`); код 1, если каталога нет |
| `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает |
| `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` |
- Порт по умолчанию **18080**, другой — `--port N` **перед** командой:
`python3 $D --port 18081 start`.
- Лог сервера (JSON, одна строка на запрос) — `/tmp/mtusi-api-<port>.log`,
pid группы — `/tmp/mtusi-api-<port>.pid`.
- `make test BASE_URL=http://localhost:18080` работает так же, как
`driver.py smoke`.
## Run: контейнер (compose)
Образ `mtusi-messenger:lab1`, compose-сервис `api`. Внешний порт —
аргументом make, чтобы не столкнуться с 8080:
```bash
make run_docker APP_OUT_PORT=18090 # build + up -d; healthy за ~2 с
docker compose ps --format '{{.Name}} {{.Ports}} {{.Status}}'
python3 $D --port 18090 flow # те же проверки против контейнера
python3 $D --port 18090 smoke
docker compose logs --no-log-prefix api | tail -5 # JSON-строки, без -f
docker compose restart api # рестарт = пустое состояние: старые X-User-Id → 401
make down # остановить и удалить, ~0,5 с
```
`make run_docker` сам создаёт недостающие `.env` и `config.toml`
(`env_setup`) и монтирует `config.toml` только для чтения. Готовность —
`docker inspect -f '{{.State.Health.Status}}' $(docker compose ps -q api)`
→ `healthy`.
## Direct invocation (без HTTP)
Для правок в `src/core/` сервисы вызываются поверх `MemoryStore`, сервер
не нужен. `APP__LOG_LEVEL=WARNING` убирает JSON-логи сервисов из вывода:
```bash
APP__LOG_LEVEL=WARNING uv run python - <<'EOF'
import asyncio
from src.infra.memory import MemoryStore
from src.core.services import UserService
async def main():
users = UserService(store=MemoryStore())
user = await users.register(username="alice", display_name="Alice")
print(await users.identify(raw_user_id=str(user.id)))
asyncio.run(main())
EOF
```
`ChatService` и `MessageService` создаются так же (`store=...`), все
методы keyword-only. Ошибки — доменные исключения из `src.core.exceptions`
(базовый `DomainError`), не HTTP-коды: `identify(raw_user_id="not-a-uuid")`
бросает `Unidentified`.
## Run (human path)
```bash
make run_dev # 127.0.0.1:8080, reload по src/; Ctrl-C
```
Блокирует терминал — агенту не подходит, используй `driver.py start`.
## Test
```bash
make check # офлайн-структура skeleton
python3 $D all # живой сервер + flow + smoke + student-tests
make lint # ruff; затрагивает и driver.py
```
Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none`,
`PASS: lab1 public API scenario...`, `79 passed`, `All checks passed!`.
## Gotchas
- **На 8080 обычно уже работает `make run_dev` пользователя.** Поэтому
драйвер по умолчанию на 18080. `driver.py --port 8080 stop` чужой
сервер не убьёт (нет pid-файла → `left running`, код 1) — и не надо:
в его памяти данные пользователя.
- **Правка любого файла в `src/` (хватает `touch`) перезапускает worker
и стирает всё состояние** — в логе `WatchFiles detected changes ...
Reloading...`. Задевает и `make run_dev` на 8080. Старые `X-User-Id`
после этого дают 401. После правки кода: `flow` заново, а не `req` со
старыми id.
- **`lsof` на порт показывает два PID** — reloader и worker делят один
сокет. Убивать по `lsof -t | xargs kill` бессмысленно: reloader
поднимет worker снова. Драйвер шлёт SIGTERM группе процессов; SIGTERM
на обёртку `uv run` тоже гасит всё дерево.
- **`uv sync` без `--all-extras` удалит ruff из `.venv`** (`Would
uninstall ruff`): ruff в extra `dev`, а `make lint` и PyCharm им
пользуются.
- **`make lint` форматирует и `.claude/skills/`** — ruff в
`pyproject.toml` исключает только `tests` и `scripts`. Драйвер написан
под 79 колонок и COM812; при правке проверять
`ruff format --check .claude/skills/run-mtusi-messenger/driver.py`.
- **`.env` задаёт `APP__PORT=8080`, но драйвер его перекрывает**:
`start` передаёт `APP__PORT=<port>` в окружении, а окружение важнее
`.env`. `APP_OUT_PORT` приложение не читает — это порт публикации
контейнера.
- **`driver.py stop` контейнер не останавливает** (`not ours (no pid
file)`, код 1) — это правильно, гасить его `make down`. `status` для
контейнера показывает один PID — процесс Docker Desktop, а не uvicorn.
- **`make logs` висит** (`logs -f`) — агенту нужен
`docker compose logs --no-log-prefix api` без `-f`.
- **`req` без `--user` на защищённом пути даёт 401 `unauthorized`** — это
не сломанный сервер, а контракт: идентификация раньше доступа.
## Troubleshooting
- **`port 8080 is not ours (no pid file); left running`** — `stop` на
порту, который поднимал не драйвер. Свой экземпляр гасить `stop` на его
порту; чужой не трогать. Чей он — `lsof -nP -iTCP:8080 -sTCP:LISTEN`,
затем `ps -o pid,ppid,etime,command -p <pid>`.
- **`req GET /api/v1/users/me --user <id>` вдруг даёт 401, хотя минуту
назад было 200** — сервер перезагрузился после правки в `src/` и
потерял пользователей (см. Gotchas).
@@ -0,0 +1,355 @@
#!/usr/bin/env python3
"""Драйвер API мессенджера для агента: запуск, сценарий, запросы, остановка.
Только стандартная библиотека. Запускать из корня репозитория:
python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] <cmd>
Команды:
start поднять `python -m src` в фоне (console, reload) и дождаться
/health/ready; лог и pid — /tmp/mtusi-api-<port>.{log,pid}
status кто слушает порт и что отвечает /health/ready
flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале
req один запрос: req METHOD PATH [--user UUID] [--data JSON]
smoke публичный tests/smoke.py против этого порта
student собственные тесты student-tests/ (make student_test) против
этого порта
stop остановить свой экземпляр на порту
all start → flow → smoke → student (если есть student-tests/) → stop
Порт по умолчанию 18080, а не 8080: на 8080 обычно висит `make run_dev`
пользователя, и его состояние в памяти трогать не надо. flow, req, smoke
и student работают с любым сервером на порту, в том числе с контейнером
(`make run_docker APP_OUT_PORT=<port>`).
"""
import argparse
import contextlib
import json
import os
import signal
import subprocess
import sys
import time
import urllib.error
import urllib.request
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[3]
DEFAULT_PORT = 18080
USERS = "/api/v1/users"
CHATS = "/api/v1/chats"
def paths(port: int) -> tuple[Path, Path]:
return (
Path(f"/tmp/mtusi-api-{port}.log"),
Path(f"/tmp/mtusi-api-{port}.pid"),
)
def base_url(port: int) -> str:
return f"http://127.0.0.1:{port}"
def call(
port: int,
method: str,
path: str,
*,
user: str | None = None,
body: object = None,
raw: bytes | None = None,
) -> tuple[int, dict[str, str], object]:
data = raw
headers = {"Accept": "application/json"}
if body is not None:
data = json.dumps(body).encode()
if data is not None:
headers["Content-Type"] = "application/json"
if user is not None:
headers["X-User-Id"] = user
request = urllib.request.Request(
base_url(port) + path,
data=data,
method=method,
headers=headers,
)
try:
with urllib.request.urlopen(request, timeout=5) as response:
status = response.status
hdrs = dict(response.headers)
payload = response.read()
except urllib.error.HTTPError as error:
status, hdrs, payload = error.code, dict(error.headers), error.read()
hdrs = {key.lower(): value for key, value in hdrs.items()}
try:
parsed = json.loads(payload) if payload else None
except json.JSONDecodeError:
parsed = payload.decode(errors="replace")
return status, hdrs, parsed
def listener_pids(port: int) -> list[int]:
out = subprocess.run(
["lsof", "-nP", f"-iTCP:{port}", "-sTCP:LISTEN", "-t"],
capture_output=True,
text=True,
check=False,
).stdout
return [int(pid) for pid in out.split()]
def is_ready(port: int) -> bool:
try:
status, _, _ = call(port, "GET", "/health/ready")
except OSError:
return False
return status == 200
def cmd_start(port: int) -> int:
log_path, pid_path = paths(port)
if listener_pids(port):
if is_ready(port):
print(f"already up on {base_url(port)}")
return 0
print(f"port {port} is busy:", listener_pids(port))
return 1
env = os.environ | {"APP__RUN_MODE": "console", "APP__PORT": str(port)}
with log_path.open("wb") as log:
proc = subprocess.Popen(
["uv", "run", "python", "-m", "src"],
cwd=ROOT,
env=env,
stdout=log,
stderr=subprocess.STDOUT,
# своя группа процессов: stop гасит uv, reloader и worker разом
start_new_session=True,
)
pid_path.write_text(str(proc.pid))
deadline = time.monotonic() + 30
while time.monotonic() < deadline:
if proc.poll() is not None:
print(f"server exited with {proc.returncode}; log: {log_path}")
print(log_path.read_text()[-2000:])
return 1
if is_ready(port):
print(f"up on {base_url(port)} pgid={proc.pid} log={log_path}")
return 0
time.sleep(0.25)
print(f"not ready after 30s; log: {log_path}")
return 1
def cmd_stop(port: int) -> int:
_, pid_path = paths(port)
if not pid_path.exists():
# экземпляр не наш (например, make run_dev): не трогаем
if listener_pids(port):
print(f"port {port} is not ours (no pid file); left running")
return 1
print(f"nothing on {port}")
return 0
with contextlib.suppress(ProcessLookupError):
os.killpg(int(pid_path.read_text()), signal.SIGTERM)
pid_path.unlink()
deadline = time.monotonic() + 12
while listener_pids(port) and time.monotonic() < deadline:
time.sleep(0.2)
if listener_pids(port):
print(f"still listening on {port}:", listener_pids(port))
return 1
print(f"stopped {port}")
return 0
def cmd_status(port: int) -> int:
pids = listener_pids(port)
print("listeners:", pids or "none")
if pids:
print("ready:", is_ready(port))
return 0 if pids else 1
def cmd_req(port: int, args: argparse.Namespace) -> int:
body = json.loads(args.data) if args.data is not None else None
status, hdrs, payload = call(
port,
args.method.upper(),
args.path,
user=args.user,
body=body,
)
print(status, "x-request-id:", hdrs.get("x-request-id"))
print(json.dumps(payload, ensure_ascii=False, indent=2))
return 0 if status < 400 else 2
class Flow:
def __init__(self, port: int) -> None:
self.port = port
self.failures = 0
def check(self, label: str, ok: bool, detail: object = "") -> None:
mark = "ok " if ok else "FAIL"
print(f"[{mark}] {label}" + (f" {detail}" if detail else ""))
if not ok:
self.failures += 1
def expect(
self,
label: str,
method: str,
path: str,
status: int,
**kwargs: object,
) -> object:
"""Запрос + проверка статуса, X-Request-Id и формата ошибки."""
got, hdrs, payload = call(self.port, method, path, **kwargs)
request_id = hdrs.get("x-request-id")
ok = got == status and bool(request_id)
detail = str(got)
if got >= 400:
error = {}
if isinstance(payload, dict):
error = payload.get("error", {})
ok = ok and error.get("request_id") == request_id
detail = f"{got} {error.get('code')}"
shown = path if len(path) <= 60 else path[:57] + "..."
self.check(f"{method} {shown} -> {status} ({label})", ok, detail)
return payload
def cmd_flow(port: int) -> int:
flow = Flow(port)
tag = uuid.uuid4().hex[:8]
flow.expect("live", "GET", "/health/live", 200)
flow.expect("ready", "GET", "/health/ready", 200)
ids = {}
for name in ("alice", "bob", "eve"):
body = {"username": f"{name}_{tag}", "display_name": f"{name} ✨"}
ids[name] = flow.expect("register", "POST", USERS, 201, body=body)[
"id"
]
alice, bob, eve = ids["alice"], ids["bob"], ids["eve"]
dup = {"username": f"alice_{tag}", "display_name": "again"}
flow.expect("duplicate username", "POST", USERS, 409, body=dup)
me = flow.expect("me", "GET", f"{USERS}/me", 200, user=alice)
flow.check("me.id == alice", me.get("id") == alice)
flow.expect("no X-User-Id", "GET", f"{USERS}/me", 401)
stranger = str(uuid.uuid4())
flow.expect("unknown user", "GET", f"{USERS}/me", 401, user=stranger)
body = {"title": "Проект 🚀", "member_ids": [alice, bob]}
chat = flow.expect("new chat", "POST", CHATS, 201, user=alice, body=body)
chat_path = f"{CHATS}/{chat['id']}"
msgs = f"{chat_path}/messages"
body = {"title": "x", "member_ids": [alice]}
flow.expect("not a member", "POST", CHATS, 400, user=eve, body=body)
texts = ["привет", "hi 👋", "третье", "четвёртое", "пятое"]
for index, text in enumerate(texts):
sender = alice if index % 2 == 0 else bob
body = {"text": text}
flow.expect("send", "POST", msgs, 201, user=sender, body=body)
blank = {"text": " "}
flow.expect("blank text", "POST", msgs, 400, user=alice, body=blank)
spoof = {"text": "x", "sender_id": alice}
flow.expect("sender_id", "POST", msgs, 400, user=alice, body=spoof)
seen, cursor, pages = [], None, 0
while pages < 10:
query = "?limit=2" + (f"&cursor={cursor}" if cursor else "")
page = flow.expect("page", "GET", msgs + query, 200, user=bob)
seen += [item["text"] for item in page["items"]]
cursor, pages = page["next_cursor"], pages + 1
if cursor is None:
break
flow.check("history order via cursor", seen == texts, f"{pages} pages")
flow.check("created_at ends with Z", chat["created_at"].endswith("Z"))
flow.expect("outsider reads chat", "GET", chat_path, 404, user=eve)
flow.expect("outsider reads history", "GET", msgs, 404, user=eve)
hi = {"text": "hi"}
flow.expect("outsider posts", "POST", msgs, 404, user=eve, body=hi)
flow.expect("no header beats 404", "GET", chat_path, 401)
flow.expect("limit=0", "GET", msgs + "?limit=0", 400, user=alice)
flow.expect("bad cursor", "GET", msgs + "?cursor=zzz", 400, user=alice)
flow.expect("chat_id not uuid", "GET", f"{CHATS}/nope", 400, user=alice)
flow.expect("malformed json", "POST", USERS, 400, raw=b"{not json")
flow.expect("unknown path", "GET", "/nope", 404)
chats = flow.expect("list chats", "GET", CHATS, 200, user=bob)
listed = [item["id"] for item in chats["items"]]
flow.check("bob sees the chat", chat["id"] in listed)
print(f"\nalice={alice}\nbob={bob}\neve={eve}\nchat={chat['id']}")
print("FAILED:", flow.failures or "none")
return 1 if flow.failures else 0
def cmd_smoke(port: int) -> int:
return subprocess.call(
[
sys.executable,
"tests/smoke.py",
"--base-url",
f"http://localhost:{port}",
],
cwd=ROOT,
)
def cmd_student(port: int) -> int:
if not (ROOT / "student-tests").is_dir():
print("no student-tests/ in this checkout")
return 1
return subprocess.call(
["make", "student_test", f"BASE_URL=http://localhost:{port}"],
cwd=ROOT,
)
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--port", type=int, default=DEFAULT_PORT)
sub = parser.add_subparsers(dest="cmd", required=True)
for name in ("start", "stop", "status", "flow", "smoke", "student", "all"):
sub.add_parser(name)
req = sub.add_parser("req")
req.add_argument("method")
req.add_argument("path")
req.add_argument("--user")
req.add_argument("--data")
args = parser.parse_args()
port = args.port
if args.cmd == "all":
if cmd_start(port) != 0:
return 1
try:
flow_rc = cmd_flow(port)
smoke_rc = cmd_smoke(port)
student_rc = 0
if (ROOT / "student-tests").is_dir():
student_rc = cmd_student(port)
finally:
cmd_stop(port)
return flow_rc or smoke_rc or student_rc
if args.cmd == "req":
return cmd_req(port, args)
handlers = {
"start": cmd_start,
"stop": cmd_stop,
"status": cmd_status,
"flow": cmd_flow,
"smoke": cmd_smoke,
"student": cmd_student,
}
return handlers[args.cmd](port)
if __name__ == "__main__":
sys.exit(main())
+22
View File
@@ -18,3 +18,25 @@ __pycache__
node_modules
evidence
.DS_Store
# свои: Dockerfile копирует только pyproject.toml, uv.lock и src/
# паттерн без **/ действует только в корне контекста
**/__pycache__
**/*.py[cod]
**/.DS_Store
config.toml
.claude
openspec
graphify-out
tests
student-tests
bench
contracts
scripts
examples
infra
*.md
Makefile
.ruff_cache
.idea
.python-version
+16 -11
View File
@@ -1,11 +1,16 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
# Шаблон .env: `make env_setup` копирует его, не перезаписывая
# существующий файл. .env не коммитить. .env читают compose, Makefile
# (make run_no_compose) и приложение (pydantic-settings).
# Параметры приложения — в формате настроек SECTION__FIELD, без секции —
# только то, что приложение не читает. Комментарии — только отдельными
# строками: make оставляет хвостовой комментарий частью значения.
# Соответствие переменным skeleton (APP_HOST, APP_PORT, APP_ENV,
# SESSION_TTL_SECONDS, DATABASE_URL_FILE, SESSION_STORE, CACHE_URL_FILE) —
# в REPORT.md, «Архитектура и решения».
# порт сервиса ([app] port): на нём слушает приложение, его же
# публикуют compose и make run_no_compose, на нём же healthcheck
APP__PORT=8080
# порт на 127.0.0.1 хоста, куда публикуется сервис; приложение его
# не читает
APP_OUT_PORT=8080
+7
View File
@@ -2,6 +2,7 @@
.env
.env.*
!.env.example
config.toml
secrets/
certs/private/
*.key
@@ -28,5 +29,11 @@ coverage/
.DS_Store
.idea/
.vscode/
graphify-out/
# make bench_quick: самопроверка стенда, не результат
evidence/bench/quick-*/
# пробные запуски bench_inproc и сравнения пробных меток
evidence/profile/quick-*.txt
evidence/compare/*quick-*
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
+38
View File
@@ -0,0 +1,38 @@
# Исключения из графа graphify, синтаксис gitignore, поверх .gitignore
# (.env, config.toml, .venv и кэши он уже убирает). В графе остаются
# код src/, свои файлы запуска и конфигурации и документы, которые
# описывают код: AGENTS.md, .claude/rules/, openspec/specs/, contracts/
# README.md и openapi.json. Состав — openspec, capability
# code-knowledge-graph. Ведущий / привязывает паттерн к корню: без него
# README.md выкинул бы и contracts/README.md.
# проверки, скрипты и заготовки skeleton
/tests/
/scripts/
/examples/
/Dockerfile.example
/lab.json
/requirements-dev.txt
/contracts/examples.json
/contracts/infrastructure.json
# инструментарий агента. settings.local.json git игнорирует через
# глобальный excludesfile, а его graphify не читает
/.claude/commands/
/.claude/skills/
/.claude/settings.local.json
# изменения OpenSpec, текущие и архивные: поведение — в openspec/specs/
/openspec/changes/
# отчёт, доказательства и документы курса
/REPORT.md
/evidence/
/README.md
/COURSE.md
/CONTRIBUTING.md
/MAINTAINERS.md
/.github/
# артефакты самого graphify
/graphify-out/
+1
View File
@@ -0,0 +1 @@
3.12
+381
View File
@@ -0,0 +1,381 @@
# MTUSI Messenger
REST API мессенджера (пользователи, чаты, история сообщений). Этот код
переносится через все семь лабораторных курса и на каждой обрастает
инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL
как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или
Valkey. Код перенесён из лабы 1 и пока работает in-memory в одном
процессе; переход на lab2 идёт через changes OpenSpec. Стек: Python
3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в
stdout).
Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные
проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные
тесты и `REPORT.md` пишем мы.
## Обязательные правила
- Контракт и skeleton не менять: `contracts/`, `tests/`, `scripts/`
(кроме своего `scripts/restart.sh` по образцу `restart.example.sh`),
`lab.json`, `README.md`, `COURSE.md`, `CONTRIBUTING.md`,
`MAINTAINERS.md`, `.github/`, `compose.example.yaml`,
`infra/README.md`, цели `check` / `validate` / `test` / `load` /
`test-persistence` в `Makefile`. Если публичный тест упал, чиним приложение, а не
тест. Если в контракте противоречие — сказать пользователю (это вопрос
преподавателю), не выбирать трактовку самому. Ответ преподавателя
записать в «Согласования с преподавателем».
- Git не трогать без явной просьбы: никаких commit, push, checkout,
reset, stash. Смотреть можно (`git status`, `git diff`, `git log`).
Исключение — замеры: состояние кода, которое меряется или тестируется
для отчёта, коммитится перед замером, в том числе пробное изменение и
его откат (`.claude/rules/bench.md`, «Измеренное состояние — commit»).
- Перед завершением задачи с кодом — `make lint`. Правки API проверять на
запущенном сервере (`make run_dev` или контейнер, затем `make test` и
`make student_test`), а не «на глаз».
- Тесты пишем, но только black-box по HTTP в `student-tests/`
(`.claude/rules/student-tests.md`). В bp_proxies тесты были запрещены,
здесь они часть рубрики уровня 4.
- Упавший тест — сначала разбор, потом правка. Воспроизвести падение,
прочитать вывод и назвать причину: дефект приложения, ошибка в самом
тесте или стенд (чужой сервис на порту, старый образ, не тот
`BASE_URL`). Только после этого что-то менять, а в итоге задачи
сказать, в чём была причина.
- Если тест упал, чинится код, а не тест. Упавший тест из
`student-tests/` правится только в крайнем случае:
- поведение меняется намеренно: так записано в дельте спека
OpenSpec change или в контракте новой лабы. Тест правится вместе со
спеком;
- тест ошибочен сам: противоречит спеку или контракту либо зависит от
случайного (порядок тестов, время, чужие данные на стенде). В итоге
задачи назвать, чему именно он противоречит.
«Тест красный» — не причина его править. Нельзя ослаблять проверку,
подгонять ожидание под фактический ответ, ставить `skip` / `xfail`
или удалять тест, чтобы прогон позеленел. Дефект приложения вне
текущей задачи записывается в `KNOWN_ISSUES.md` (правило ниже), а
тест остаётся как есть. Если причина неясна или правка теста спорная —
остановиться и спросить.
- Лаба 2: источник истины — PostgreSQL, SQLite его не заменяет.
Пользователи, чаты, участники, сообщения и ещё действующие сессии
переживают рестарт API и хранилищ без удаления volumes. Redis или
Valkey (одно из двух) — на «4», с описанной ролью. uvicorn с одним
worker: реплики — лаба 3.
- `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни
в git, ни в образ. В `evidence/` и `REPORT.md` — только обезличенные
выводы команд.
- Найденный попутно дефект не чинить без просьбы: записать в
`KNOWN_ISSUES.md` (завести при первой находке) с путём и предложением
правки.
- OpenSpec: если команде `/opsx:*` подходит больше одного изменения
(change) — несколько активных в `openspec/changes/`, имя совпало
частично, из контекста подходят несколько, — не выполнять её для всех
подряд и не выбирать самому. Спросить, для какого изменения запустить:
варианты — каждое по имени, последним — «все». То же при нескольких
подходящих спеках (capability).
## Согласования с преподавателем
Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md`
и перенести в следующую лабу вместе с этим файлом, если она ещё
действует.
| Дата | Договорённость | Где учтено |
|---|---|---|
| 2026-09-26 | Лабы можно делать на FastAPI, несмотря на расхождения с контрактом (лишний 422, другой порядок кодов ошибок). Публичный smoke при этом должен проходить | `.claude/rules/api-contract.md`, раздел «FastAPI» |
| 2026-09-29 | Конфиг через pydantic-settings: окружение → `.env` → `config.toml` → дефолты. `config.toml` не в git и не в образе, монтируется read-only при запуске. Это подходит под «конфигурация приходит из окружения» (README, п. 3) и п. 6 `Dockerfile.example`. Требование «только env» — упрощение курса, `config.toml` можно использовать | `.claude/rules/settings.md`, `.claude/rules/docker.md` |
## Задание и контракт: важные файлы
| Файл | Что в нём |
|---|---|
| `README.md` | задание лабы: рубрика 3/4/5, сценарий и вопросы защиты, что приложить к PR |
| `COURSE.md` | карта семи лаб, три объявленных перехода API (1→2, 2→3, 4→5), правила честных измерений |
| `contracts/openapi.json` | нормативный OpenAPI 3.1: пути, схемы, коды ответов |
| `contracts/README.md` | нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв; разделы lab3+ — на будущее |
| `contracts/examples.json`, `infrastructure.json` | примеры тел (проверяет `make validate`); роли инфраструктуры лабы: api, postgres, Redis/Valkey на «4» |
| `lab.json` | номер лабы; по нему `tests/client.py` выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer) |
| `tests/smoke.py`, `tests/client.py` | публичный сквозной сценарий `make test`; что он проверяет и чего нет — `tests/README.md` |
| `tests/resilience.py` | `make test-persistence`: данные и прежний токен после restart hook |
| `tests/load.py` | closed-loop нагрузка POST сообщений (`make load`); для трека 5 одного его мало |
| `scripts/check_contract.py`, `scripts/validate_openapi.py` | `make check` / `make validate` |
| `scripts/restart.example.sh` | образец restart hook; свой — `scripts/restart.sh`: перезапуск API и всех хранилищ без удаления volumes |
| `compose.example.yaml` | список ролей с пустым `services`, не стенд; свой стенд — свой compose-файл |
| `infra/README.md` | куда класть конфигурации сервисов и что сопоставить в `REPORT.md` |
| `REPORT.md` | отчёт: запуск из чистого clone, архитектура, доказательства по каждому критерию, эксперименты, ИИ и источники |
| `evidence/` | сохранённые выводы проверок и измерений (что можно класть — `evidence/README.md`) |
| `CONTRIBUTING.md` | fork/PR, имя ветки, что переносить в следующую лабу |
| `.github/pull_request_template.md` | шаблон PR; CI `workflows/contracts.yml` проверяет только контракт, приложение не запускает |
| `Dockerfile.example` | опорные шаги Dockerfile, не рабочий файл |
| `.env.example` | шаблон `.env` |
| `examples/requests.http` | ручные запросы для HTTP-клиента IDE |
## Где лежат инструкции
Четыре уровня, не дублировать их друг в друге:
- **`AGENTS.md`** (этот файл): инварианты, команды, карта кода.
`CLAUDE.md` импортирует его.
- **`.claude/rules/*.md`**: правила по слоям. Подгружаются автоматически,
когда открыт файл из `paths:` во фронтматтере. Проект пишется с нуля,
а при создании файла через Write правило само не подгрузится. Поэтому
перед созданием первого файла слоя его правило нужно прочитать руками.
| Файл | Действует на |
|---|---|
| `api-contract.md` | `src/api/**`, `src/core/**`, `src/schemas/**`, `student-tests/**`: что требует контракт и где FastAPI по умолчанию его нарушает |
| `api-layer.md` | `src/api/**`, `src/main.py`: роутеры, зависимости, middlewares, обработчики ошибок |
| `service-layer.md` | `src/core/services/**` |
| `repo-layer.md` | `src/core/repos/**` |
| `dto.md` | `src/schemas/**` |
| `infra.md` | `src/infra/**`: логгер, in-memory хранилище, клиенты БД/Redis/S3/брокера |
| `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно |
| `settings.md` | `src/config/**`, `.env.example`, `config_example.toml`: источники настроек, что куда класть |
| `run-modes.md` | точки входа, `Makefile`, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERM |
| `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`: мультистейдж, non-root, пины, healthcheck |
| `student-tests.md` | `student-tests/**` |
| `bench.md` | `bench/**`: нагрузочный стенд трека 1, что не меняется между метками замеров, диагностика и сравнение меток, коммиты измеренных состояний |
| `migrations.md` | `migrations/**`, `src/infra/db/models/**` (с лабы 2) |
- **`openspec/`** (схема `spec-driven`, язык артефактов — русский, см.
`openspec/config.yaml`): что система делает и зачем.
`specs/<capability>/spec.md` — текущее поведение, `changes/<change>/` —
предложения (`proposal.md`, `design.md`, `tasks.md`, дельты спеков),
`changes/archive/` — внедрённые. Крупную работу ведут командами
`/opsx:propose` → `/opsx:apply` → `/opsx:verify` → `/opsx:archive`
(ещё `explore`, `update`, `sync`). Команды в `.claude/commands/opsx/`
ставит `openspec update`, руками их не править. Спеки не пересказывают
контракт и правила: в `tasks.md` ссылаться на `contracts/` и
`.claude/rules/`, а не копировать их.
- **Граф кода** (`graphify-out/`, CLI graphify; локальный, не в git и
не в образе, состав — `.graphifyignore`): для вопросов о структуре и
связях — где используется, кто вызывает, что затронет правка.
Команды: `graphify query "<вопрос>"`, `graphify path "A" "B"`,
`graphify explain "X"`, `graphify affected "X"`. Граф — подсказка, а
не источник правды: до обновления он отстаёт от кода.
- Перед правкой — Read файла, как без графа: иначе правило слоя из
`.claude/rules/` не подгрузится. Граф этого не заменяет.
- Граф строится без LLM: код — по AST, markdown — по структуре
(разделы становятся узлами). Раздел правила или спеки связан
(`references`, INFERRED) с символами кода, упомянутыми в его тексте
в обратных кавычках. Полной карты «правило → код» в графе нет — она
в таблице выше и в `paths:` правил.
- `query` ищет узлы по подстроке метки. В запрос — имена символов
кода (`"ChatService ChatNotFound chat"`), а не пересказ вопроса:
тогда в ответе и код, и разделы правил и спек.
- В граф не попадают `.json` / `.yaml` / `.yml` (`contracts/openapi.json`,
`docker-compose.yml`), `Dockerfile`, `Makefile` и шаблоны конфигов:
их CLI не разбирает. По ним — `grep`.
- Только CLI `graphify update .`. Не запускать скилл `/graphify` и
`graphify extract`: семантический разбор документов через LLM
стоит сотни тысяч токенов, а следующий `graphify update .` всё равно
заменяет его структурным. Не запускать `graphify install`,
`graphify claude install`, `graphify hook install` и `graphify
watch`: первые два пишут секцию в `CLAUDE.md` и PreToolUse-хук на
Read, остальные пересобирают граф без спроса.
## Окружение и команды
- Python 3.12 (`.python-version`), зависимости через uv (`uv sync`,
`uv run ...`), lock в `uv.lock`. ruff глобальный
(`/opt/homebrew/bin/ruff`, им же пользуется PyCharm), в проекте он в
extra `dev`.
- Конфиг: `.env` (то, что читают compose и контейнеры зависимостей) +
`config.toml` (то, что читает только приложение). Читает их
`src/config/settings.py` (pydantic-settings), все поля — в секциях.
Приоритет: окружение > `.env` > `config.toml` > дефолты. Параметры
приложения в `.env` пишутся в формате настроек (`APP__PORT`), без
секции — только то, что приложение не читает (`APP_OUT_PORT`).
`config.toml` в образ не копируется, а монтируется на старте. Режим
`APP__RUN_MODE` (`console` / `docker`) в `.env` не хранится.
Подробно — `settings.md`, `docker.md` и `run-modes.md`.
- Точка входа: `python -m src` (`src/__main__.py` → `src/main.py`), порт
8080.
- `make test` ходит на `http://localhost:8080`. Если там отвечает чужой
сервис, smoke упадёт с 404 на `/health/live` вместо ошибки соединения.
Проверить, кто занял порт: `lsof -nP -iTCP:8080 -sTCP:LISTEN`,
`docker ps`.
- graphify (граф кода, «Где лежат инструкции») — вне проекта, в
`uv tool`, версия закреплена:
- CLI: `uv tool install --python 3.12 'graphifyy==0.9.72'`. Без
`--python 3.12` uv берёт free-threaded 3.14t, и установка падает на
сборке `tree-sitter-rust`.
- Сборка и обновление — одна команда `graphify update .` в корне:
без LLM и токенов, около секунды, работает и в чистом clone. Граф
обновляется вручную, после заметной работы (новый слой, закрыт
change). Попутно `update` кладёт копию прошлого графа в
`graphify-out/<дата>/` и называет кластеры по центральному узлу.
| Команда | Что делает |
|---|---|
| `make check` | офлайн-проверка структуры skeleton, JSON и синтаксиса Python-проверок |
| `make validate PYTHON=.venv/bin/python` | полная валидация OpenAPI и примеров (валидатор стоит в dev-группе uv) |
| `make test [BASE_URL=...]` | публичный smoke против запущенного сервера |
| `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` |
| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (`tests/README.md`) |
| `make run_dev` | `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload |
| `make lint` | `ruff format` + `ruff check --fix`, дважды: так нужно из-за COM812; `tests/` и `scripts/` skeleton исключены в `[tool.ruff]` |
| `make env_setup` | `.env.example` → `.env`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает |
| `make run_no_compose` | `make env_setup` (только недостающие файлы) + команды README без compose: `docker build` + `docker run --rm --env-file .env` на переднем плане, порты `APP_OUT_PORT` / `APP__PORT` из `.env`, без `config.toml`; стоп — Ctrl+C |
| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`; `config.toml` монтируется read-only |
| `make stop` / `make down` | остановить / удалить контейнеры compose |
| `make logs` | журнал сервиса compose, каждая строка — JSON (`--no-log-prefix`) |
| `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера; сервер недоступен — код 2 и одна строка с адресом |
| `make bench [BENCH_LABEL=...]` | полная матрица трека 1 (~18 мин) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`.claude/rules/bench.md`) |
| `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт |
| `make bench_inproc [BENCH_LABEL=...]` | куда уходит время одного запроса (~2 мин): приложение вызывается внутри процесса в образе стенда, без сервера и сети; заодно сверяет формат времени с эталоном. Результат в `evidence/profile/<метка>.txt`, занятая метка — отказ. Объясняет, но не меряет пропускную способность |
| `make bench_ab BEFORE=... AFTER=... REAPPLY=<commit>` | «до» и «после» одного изменения подряд (~40 мин): `bench` и `bench_inproc` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, то же для `AFTER`. Нужно чистое рабочее дерево; сама делает два коммита |
| `make bench_compare BEFORE=... AFTER=... [AA=...]` | дельта двух меток `make bench` по ячейкам матрицы; метки с разной методикой не сравнивает; с `AA` (метка того же кода, что `BEFORE`) отделяет эффект от шума. Результат в `evidence/compare/<до>__<после>.md` |
Разовая подмена внешнего порта — аргументом make:
`make run_docker APP_OUT_PORT=8090`, затем
`make test BASE_URL=http://localhost:8090`. Префикс окружения
(`APP_OUT_PORT=8090 make ...`) не работает: Makefile подключает `.env`
(`run-modes.md`, Troubleshooting).
## Карта кода
Файлы домена называются одинаково во всех слоях (`user`, `chat`,
`message`, с лабы 2 `session` и т.д.). `migrations/` появится в
лабе 2.
```
src/
__main__.py # python -m src → main.main()
main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run
config/settings.py # Settings (pydantic-settings), экземпляр settings
api/
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py
schemas/<domain>.py # pydantic-модели запросов и ответов = схемы контракта
dependencies.py # текущий пользователь, фабрики сервисов, параметры пагинации
errors.py # доменное исключение → статус + code, формат ошибки контракта
middlewares/ # X-Request-Id и access-лог; с лабы 3 — X-Instance-Id
core/
repos/<domain>.py # атомарный доступ к хранилищу, модульные функции
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py
infra/
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id
memory.py # лаба 1: MemoryStore — dict-ы и индексы в памяти процесса
db/ # с лабы 2: models/, session.py (вместо memory.py)
schemas/
dataclasses/<domain>.py # DTO между repo → service → api
enums/<domain>.py # StrEnum доменов, RunModeEnum
utils/
constants.py # лимиты контракта, размер страницы, префиксы путей
utc.py # utcnow() (aware UTC), формат RFC 3339 с Z
cursor.py # непрозрачный keyset-курсор: кодирование и разбор
student-tests/ # black-box тесты по HTTP (уровень 4): make student_test
conftest.py # BASE_URL, проверка доступности, фикстуры alice/bob/eve/chat, сбор маркеров spec
api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, assert_error
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
bench/ # нагрузочный стенд трека 1: make bench / make bench_quick
run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json
k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы
inproc.py # make bench_inproc: разложение времени запроса внутри процесса, сверка формата времени
compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд
migrations/ # с лабы 2: alembic
Dockerfile # builder (uv sync --locked) → runtime: .venv + src, UID 10001, healthcheck
docker-compose.yml # сервис api: порты из .env, config.toml read-only
.dockerignore
config_example.toml, .env.example
evidence/container/ # выводы проверок контейнера для REPORT.md
evidence/tests/ # вывод make student_test для REPORT.md
evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6
evidence/profile/<метка>.txt # результаты make bench_inproc
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
```
## Архитектура в двух словах
- Поток однонаправленный. Роутер (зависимости, модели API) → сервис
(логика, проверки доступа, id и время, логи) → repo (одна атомарная
операция над хранилищем, отдаёт DTO) → хранилище из `src/infra/`
(лаба 1 — `MemoryStore`, лаба 2+ — `AsyncSession`). Подробности — в
правилах слоёв.
- Отличия от bp_proxies. Из `core/` вынесены инфраструктура
(`src/infra/`: логгер, хранилища, клиенты), утилиты (`src/utils/`),
настройки (`src/config/` вместо `src/data/`) и HTTP-модели
(`src/api/schemas/` вместо `schemas/pydantic/`). В `core/` остались
доменные слои: repos, services, exceptions. Бота, loader и контроллера
нет; фоновая работа появится в лабе 5 отдельным worker.
- Ошибки: сервис бросает доменное исключение. `src/api/errors.py` одной
таблицей переводит его в статус и `code` и отдаёт тело
`{"error": {...}}` с `request_id`. `HTTPException` в сервисах и ручках
не используется.
- Конкурентность на лабе 1: все ручки и зависимости — `async def`, один
event loop, один worker. Repo-функция не делает `await` внутри, поэтому
её не прерывает другой запрос. На лабе 2 атомарность дают транзакции
Postgres.
- Request id генерирует middleware. Тот же id уходит в заголовок
`X-Request-Id`, в `request_id` тела ошибки и в каждую строку лога.
## Соглашения по коду
- ruff: 79 символов, py312, набор правил в `pyproject.toml` (isort,
bugbear, comprehensions, unused-arguments, pyupgrade, simplify,
quotes). Кавычки как в файле (quote-style preserve), trailing comma
обязательна.
- Типизация везде: `X | None`, `list[...]`, `UUID` и `datetime` вместо
строк. Методы сервисов keyword-only (`*,`); repo и сервисы вызываются
только именованными аргументами.
- Комментарии и докстринги короткие, на русском. Сообщения логов и
тексты ошибок API (`error.message`) — на английском.
- Константы (лимиты контракта, размер страницы, пути) — в
`src/utils/constants.py`, не литералами в коде.
- Время только через `utcnow()` из `src/utils/utc.py`: aware UTC. В
bp_proxies был naive UTC, здесь контракт требует `...Z`, а с лабы 2 —
`timestamptz`.
- Коммиты (когда попросят): английский, conventional style
(`feat: ...`, `fix: ...`, `refactor: ...`).
## Дорожная карта лаб
Каждая лаба — отдельный skeleton-репозиторий; переходы API — `COURSE.md`
нового skeleton. Что меняется в коде:
| Лаба | Что появляется | Где в коде |
|---|---|---|
| 1 | in-memory API, Dockerfile | `infra/memory.py`, `X-User-Id` в `get_current_user` |
| 2 | PostgreSQL, Basic → Bearer-сессия; Redis/Valkey на «4» | `infra/db/`, `migrations/`, repo на `AsyncSession`; `password` при регистрации (KDF); `get_current_user` на Bearer; `SESSION_TTL_SECONDS` |
| 3 | балансировщик, ≥2 реплики, идемпотентность | middleware `X-Instance-Id`; `Idempotency-Key` на POST сообщения; никакого состояния в памяти процесса |
| 4 | приватный S3, вложения | клиент в `infra/`, домен `attachment` |
| 5 | брокер, worker, превью | отдельная точка входа worker; загрузка отвечает 202 |
| 6 | OTel Collector, Grafana | телеметрия в `infra/` |
| 7 | Argon2id, TLS/mTLS, OpenBao | HTTPS, секреты из OpenBao |
## Переход в следующую лабу
По `CONTRIBUTING.md`: fork нового skeleton, ветка
`solution/<group>-<surname>`, затем перенести своё.
- Переносить: `src/`, `student-tests/`, `migrations/`, `Dockerfile`,
`docker-compose.yml`, `pyproject.toml`, `uv.lock`, `.python-version`,
`config_example.toml`, `AGENTS.md`, `CLAUDE.md`, `.claude/`,
`openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`.
- Сливать, а не копировать поверх: `Makefile`, `.env.example`,
`.gitignore`, `.dockerignore`. Берём версию нового skeleton (в ней
новые цели и проверки) и дописываем свои секции.
- Не копировать: `.git`, `.env`, `config.toml`, volumes, `README.md`,
`COURSE.md`, `tests/`, `contracts/`, `lab.json`, `REPORT.md`,
`evidence/` (доказательства остаются в репозитории своей лабы),
`graphify-out/` (граф собирается заново).
- Сначала прочитать переходы API в `COURSE.md` и `contracts/README.md`
нового skeleton, потом править код. Обновить этот файл: номер лабы,
таблицу важных файлов, новые правила.
## Ветки и PR
Git — только по просьбе. Когда просят, порядок такой:
- Работа идёт в ветке `solution/bvt2301-safronov` от ветки skeleton.
- PR — в исходный репозиторий преподавателя. Заголовок
`ЛР N — Группа — Фамилия — на 3/4/5`, тело — по
`.github/pull_request_template.md`. Перед PR выполнить `make check`,
`make test` на собранном из чистого clone образе и заполнить
`REPORT.md`, включая использование ИИ.
+5
View File
@@ -0,0 +1,5 @@
@AGENTS.md
Правила по слоям лежат в `.claude/rules/` и подгружаются сами только при
чтении файла из их `paths:`. Проект пишется с нуля: перед созданием
первого файла слоя прочитать его правило руками (таблица в AGENTS.md).
+52
View File
@@ -0,0 +1,52 @@
# Образ API мессенджера (лаба 1). Правила — .claude/rules/docker.md.
# Пины: тег + digest индекса (amd64 и arm64). Обновление версии — новый
# тег и digest из `docker buildx imagetools inspect <тег>`.
# builder: зависимости строго по uv.lock в /app/.venv
FROM python:3.12.14-slim-trixie@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f AS builder
COPY --from=ghcr.io/astral-sh/uv:0.12.17@sha256:10787c682e4184e4f290de1171fd4703dc63de99221f10fe1c99002ce7fa9acc /uv /bin/uv
ENV UV_COMPILE_BYTECODE=1 \
UV_LINK_MODE=copy \
UV_PYTHON_DOWNLOADS=never \
UV_PROJECT_ENVIRONMENT=/app/.venv
WORKDIR /app
COPY pyproject.toml uv.lock ./
# --locked: lock не совпадает с pyproject.toml — сборка падает;
# --no-install-project: src/ сюда не копируется, запуск из /app
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-dev --no-install-project
# runtime: интерпретатор базового образа, .venv и src/, без uv
FROM python:3.12.14-slim-trixie@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f AS runtime
RUN groupadd --system --gid 10001 app \
&& useradd --system --uid 10001 --gid app --no-create-home \
--home-dir /nonexistent --shell /usr/sbin/nologin app
ENV PATH=/app/.venv/bin:$PATH \
PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
APP__RUN_MODE=docker
WORKDIR /app
# код и .venv принадлежат root: пользователю app — только чтение
COPY --from=builder /app/.venv /app/.venv
COPY src ./src
USER app
EXPOSE 8080
# порт — тот же APP__PORT, что слушает приложение (по умолчанию 8080)
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s \
--start-interval=1s --retries=3 \
CMD ["python", "-c", "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/health/ready' % os.environ.get('APP__PORT', '8080'), timeout=2)"]
# exec-форма: сервер — PID 1 и сам получает SIGTERM
CMD ["python", "-m", "src"]
+6
View File
@@ -0,0 +1,6 @@
# Известные дефекты
Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md).
Исправленные удаляются отсюда, история — в git.
Открытых дефектов нет.
+121
View File
@@ -24,3 +24,124 @@ load:
test-persistence:
@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)
# -------------------------
# Приложение на хосте (свои цели; цели skeleton выше не менять)
# -------------------------
.PHONY: run_dev
run_dev:
APP__RUN_MODE=console uv run python -m src
# шаблоны копируются только если файла ещё нет: локальные значения
# не затираются
.PHONY: env_setup
env_setup:
@test -f .env || cp .env.example .env
@test -f config.toml || cp config_example.toml config.toml
@echo "env ready: .env, config.toml"
# -------------------------
# Docker targets
# -------------------------
# порты — из того же .env, что читает compose; без .env — 8080
-include .env
APP__PORT ?= 8080
APP_OUT_PORT ?= 8080
DC=docker compose
DOCKER_IMAGE=mtusi-messenger:lab2
DOCKER_CONTAINER=mtusi-messenger-lab2
# без compose: команды README, контейнер на переднем плане;
# стоп — Ctrl+C или docker stop mtusi-messenger-lab2.
# env_setup создаёт недостающий .env: без него --env-file падает
.PHONY: run_no_compose
run_no_compose: env_setup
DOCKER_BUILDKIT=1 docker build -t $(DOCKER_IMAGE) .
docker run --rm --name $(DOCKER_CONTAINER) \
-p 127.0.0.1:$(APP_OUT_PORT):$(APP__PORT) \
--env-file .env $(DOCKER_IMAGE)
# env_setup создаёт недостающие .env и config.toml из шаблонов: без
# config.toml compose не запустится (bind с create_host_path: false)
.PHONY: run_docker
run_docker: env_setup
DOCKER_BUILDKIT=1 $(DC) build
$(DC) up -d
.PHONY: stop
stop:
$(DC) stop
.PHONY: down
down:
$(DC) down
# без префикса "api-1 |": каждая строка — JSON
.PHONY: logs
logs:
$(DC) logs -f --no-log-prefix api
# -------------------------
# Load benchmark (трек 1)
# -------------------------
BENCH_LABEL ?= baseline
# полная матрица, ~18 мин; метка не должна существовать; результаты —
# evidence/bench/$(BENCH_LABEL)/, ход — строки в терминале и progress.json
.PHONY: bench
bench:
uv run python bench/run.py --profile full --label $(BENCH_LABEL)
# самопроверка стенда на малых размерах, ~1,5 мин; результат в git не идёт
.PHONY: bench_quick
bench_quick:
uv run python bench/run.py --profile quick --label quick-$(shell date -u +%Y%m%dT%H%M%SZ)
# разложение времени запроса внутри процесса в образе стенда, ~2 мин:
# объясняет, куда уходит CPU, но не меряет; результат —
# evidence/profile/$(BENCH_LABEL).txt, метки quick-* в git не идут
.PHONY: bench_inproc
bench_inproc:
uv run python bench/inproc.py --label $(BENCH_LABEL)
# дельта двух меток по ячейкам матрицы: BEFORE и AFTER обязательны, AA —
# метка того же кода, что BEFORE, для уровня шума; результат —
# evidence/compare/$(BEFORE)__$(AFTER).md
.PHONY: bench_compare
bench_compare:
uv run python bench/compare.py --before "$(BEFORE)" --after "$(AFTER)" --aa "$(AA)"
# «до» и «после» подряд в одной сессии, ~40 мин: bench и bench_inproc для
# BEFORE, commit доказательств, git revert commit REAPPLY (возврат
# откаченного изменения), затем то же для AFTER. Сам делает два коммита;
# рабочее дерево должно быть чистым
.PHONY: bench_ab
bench_ab:
uv run python bench/ab.py --before "$(BEFORE)" --after "$(AFTER)" --reapply "$(REAPPLY)"
# -------------------------
# Common targets
# -------------------------
# собственные black-box тесты против запущенного сервера (BASE_URL)
.PHONY: student_test
student_test:
BASE_URL=$(BASE_URL) uv run pytest
.PHONY: lint
lint:
@ruff format .
@echo "code formatted"
@ruff check --fix .
@echo "code checked and fixed if needed"
@ruff format .
@echo "code formatted"
@ruff check --fix .
@echo "code checked and fixed if needed"
+118
View File
@@ -0,0 +1,118 @@
"""Два прогона подряд: «до» и «после» одного изменения, в одной сессии.
Запуск — `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=<commit>`.
В рабочем дереве должен лежать код «до», а изменение — быть
закоммиченным и откаченным отдельным commit; `REAPPLY` — commit отката.
Скрипт снимает стенд и разложение «до», коммитит их, возвращает
изменение (`git revert` commit отката) и снимает «после». Между
прогонами на хосте нет другой работы. Только stdlib. Методика — design
change `perf-bottleneck-fix`, решения 7 и 9.
"""
import argparse
import re
import subprocess
import sys
import time
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
def git(*args: str) -> subprocess.CompletedProcess[str]:
return subprocess.run(
["git", "-C", str(ROOT), *args],
capture_output=True,
text=True,
check=False,
)
def problems(args: argparse.Namespace) -> list[str]:
"""Что мешает начать; пустой список — можно запускать."""
found = []
for name in (args.before, args.after):
if not re.fullmatch(r"[A-Za-z0-9._-]+", name or ""):
found.append(f"bad label {name!r}: use [A-Za-z0-9._-]")
continue
for path in (
ROOT / "evidence" / "bench" / name,
ROOT / "evidence" / "profile" / f"{name}.txt",
):
if path.exists():
found.append(f"{path.relative_to(ROOT)} already exists")
if args.before == args.after:
found.append("BEFORE and AFTER must be different labels")
if git("status", "--porcelain").stdout.strip():
# иначе стенд запишет в паспорт dirty: true
found.append("working tree is not clean: commit or remove changes")
if git("cat-file", "-e", f"{args.reapply}^{{commit}}").returncode != 0:
found.append(f"commit {args.reapply!r} not found")
elif git("merge-base", "--is-ancestor", args.reapply, "HEAD").returncode:
found.append(f"commit {args.reapply} is not in the current branch")
return found
def steps(args: argparse.Namespace) -> list[list[str]]:
# стенд идёт раньше разложения: его dirty считается по всему дереву
return [
["make", "bench", f"BENCH_LABEL={args.before}"],
["make", "bench_inproc", f"BENCH_LABEL={args.before}"],
[
"git",
"add",
f"evidence/bench/{args.before}",
f"evidence/profile/{args.before}.txt",
],
["git", "commit", "-m", f"docs: add {args.before} bench evidence"],
["git", "revert", "--no-edit", args.reapply],
["make", "bench", f"BENCH_LABEL={args.after}"],
["make", "bench_inproc", f"BENCH_LABEL={args.after}"],
]
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--before", default="")
parser.add_argument("--after", default="")
parser.add_argument("--reapply", default="")
parser.add_argument("--dry-run", action="store_true")
args = parser.parse_args(argv)
if not (args.before and args.after and args.reapply):
print(
"usage: make bench_ab BEFORE=<label> AFTER=<label> "
"REAPPLY=<revert commit>",
flush=True,
)
return 2
found = problems(args)
if found:
print("bench_ab refused:\n " + "\n ".join(found), flush=True)
return 2
plan = steps(args)
if args.dry_run:
print("\n".join(" ".join(step) for step in plan), flush=True)
return 0
started = time.monotonic()
for number, step in enumerate(plan, 1):
print(f"\n=== [{number}/{len(plan)}] {' '.join(step)}", flush=True)
code = subprocess.run(step, cwd=ROOT, check=False).returncode
if code != 0:
print(
f"\nbench_ab stopped: step {number} exited with {code}; "
"later steps were not run",
flush=True,
)
return 1
minutes = (time.monotonic() - started) / 60
head = git("rev-parse", "--short", "HEAD").stdout.strip()
print(
f"\nbench_ab done in {minutes:.0f} min: labels {args.before} and "
f"{args.after}, HEAD {head}",
flush=True,
)
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
+423
View File
@@ -0,0 +1,423 @@
"""Сравнение двух меток стенда: дельта по ячейкам матрицы.
Запуск — `make bench_compare BEFORE=<метка> AFTER=<метка> [AA=<метка>]`.
Читает `runs.csv` и `meta.json` из `evidence/bench/<метка>/`, пишет
`evidence/compare/<до>__<после>.md`. Только stdlib, docker и приложение
не нужны. Метки с разной методикой не сравниваются. Правило «эффект или
шум» — design change `perf-bottleneck-fix`, решение 7.
"""
import argparse
import csv
import json
import re
import statistics
import sys
from dataclasses import dataclass
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parents[1]
BENCH_DIR = ROOT / "evidence" / "bench"
OUT_DIR = ROOT / "evidence" / "compare"
SCENARIOS = ("read", "write")
# ячейка матрицы: сценарий, размер истории, число клиентов
type CellKey = tuple[str, int, int]
class CompareError(Exception):
"""Метки нельзя сравнить: сообщение для человека."""
@dataclass(frozen=True)
class Label:
name: str
meta: dict[str, Any]
runs: list[dict[str, str]]
@dataclass(frozen=True)
class Stat:
"""Повторы одной ячейки: RPS, CPU на запрос, медианы задержек."""
rps: list[float]
cpu_us: float
p50: float
p95: float
p99: float
@property
def median(self) -> float:
return statistics.median(self.rps)
@dataclass(frozen=True)
class Row:
key: CellKey
before: Stat
after: Stat
@property
def delta(self) -> float:
"""Изменение медианы RPS, %."""
return (self.after.median / self.before.median - 1) * 100
@property
def overlap(self) -> bool:
"""Пересекаются ли разбросы min–max повторов двух меток."""
return min(self.before.rps) <= max(self.after.rps) and min(
self.after.rps,
) <= max(self.before.rps)
def human(n: int) -> str:
if n >= 1_000_000 and n % 1_000_000 == 0:
return f"{n // 1_000_000}M"
if n >= 1000 and n % 1000 == 0:
return f"{n // 1000}k"
return str(n)
def load(name: str) -> Label:
if not re.fullmatch(r"[A-Za-z0-9._-]+", name):
raise CompareError(f"bad label {name!r}: use [A-Za-z0-9._-]")
directory = BENCH_DIR / name
for file in ("meta.json", "runs.csv"):
if not (directory / file).is_file():
raise CompareError(
f"{(directory / file).relative_to(ROOT)} not found",
)
meta = json.loads((directory / "meta.json").read_text(encoding="utf-8"))
with (directory / "runs.csv").open(encoding="utf-8", newline="") as file:
runs = list(csv.DictReader(file))
return Label(name=name, meta=meta, runs=runs)
def methodology(label: Label) -> dict[str, Any]:
"""Параметры, которые у сравнимых меток обязаны совпадать."""
flat: dict[str, Any] = {}
for section in ("profile", "limits"):
for key, value in label.meta.get(section, {}).items():
flat[f"{section}.{key}"] = value
image = label.meta.get("generator", {}).get("image")
if image is not None:
flat["generator.image"] = image
return flat
def check_methodology(first: Label, second: Label) -> list[str]:
"""Отказ при различии; возвращает параметры, записанные в одной метке."""
a, b = methodology(first), methodology(second)
differs = [
f"{key}: {first.name} = {a[key]!r}, {second.name} = {b[key]!r}"
for key in sorted(a.keys() & b.keys())
if a[key] != b[key]
]
if differs:
raise CompareError(
f"labels {first.name} and {second.name} were measured with "
"different methodology:\n " + "\n ".join(differs),
)
return [
f"`{key}` записан только в `{(first if key in a else second).name}`: "
"совпадение не проверено"
for key in sorted(a.keys() ^ b.keys())
]
def notes(label: Label) -> list[str]:
"""Что мешает считать метку чистым замером."""
meta = label.meta
found = []
if meta.get("status") != "complete":
found.append(f"статус {meta.get('status')}: {meta.get('reason')}")
if meta.get("git", {}).get("dirty"):
found.append("незакоммиченные изменения (`dirty: true`)")
if meta.get("overrides"):
found.append(f"отладочные переопределения {meta['overrides']}")
found += [f"хост: {text}" for text in meta.get("host_warnings", [])]
if meta.get("other_containers"):
found.append(
"посторонние контейнеры: " + ", ".join(meta["other_containers"]),
)
flagged = [
run["run"]
for run in label.runs
if run.get("flags")
or run.get("requests_failed", "0") not in ("0", "")
or run.get("check_failed", "0") not in ("0", "")
]
if flagged:
found.append("прогоны с пометками или ошибками: " + ", ".join(flagged))
return [f"`{label.name}`: {text}" for text in found]
def cells(label: Label) -> dict[CellKey, Stat]:
grouped: dict[CellKey, list[dict[str, str]]] = {}
for run in label.runs:
if not run["rps"] or float(run["rps"]) <= 0:
continue
key = (run["scenario"], int(run["size"]), int(run["concurrency"]))
grouped.setdefault(key, []).append(run)
def median(rows: list[dict[str, str]], column: str) -> float:
return statistics.median(float(row[column]) for row in rows)
return {
key: Stat(
rps=[float(row["rps"]) for row in rows],
cpu_us=statistics.median(
float(row["app_cpu_cores"]) / float(row["rps"]) * 1e6
for row in rows
),
p50=median(rows, "p50_ms"),
p95=median(rows, "p95_ms"),
p99=median(rows, "p99_ms"),
)
for key, rows in grouped.items()
}
def compare(before: Label, after: Label) -> tuple[list[Row], list[str]]:
"""Строки по общим ячейкам и замечания о ячейках одной метки."""
first, second = cells(before), cells(after)
rows = [
Row(key=key, before=first[key], after=second[key])
for key in first
if key in second
]
lonely = [
f"ячейка {key[0]} {human(key[1])} × {key[2]} есть только в "
f"`{(before if key in first else after).name}`"
for key in sorted(first.keys() ^ second.keys())
]
repeats = [
f"ячейка {row.key[0]} {human(row.key[1])} × {row.key[2]}: повторов "
f"{len(row.before.rps)} и {len(row.after.rps)}"
for row in rows
if len(row.before.rps) != len(row.after.rps)
]
return rows, lonely + repeats
def noise_floor(rows: list[Row]) -> dict[str, Row]:
"""Ячейка с наибольшим изменением медианы RPS в каждом сценарии."""
floor: dict[str, Row] = {}
for row in rows:
worst = floor.get(row.key[0])
if worst is None or abs(row.delta) > abs(worst.delta):
floor[row.key[0]] = row
return floor
def passport_rows(labels: list[Label]) -> list[str]:
def field(title: str, value: Any) -> str:
return (
f"| {title} | " + " | ".join(value(x.meta) for x in labels) + " |"
)
def host(meta: dict[str, Any]) -> str:
start = meta.get("host_state", {}).get("start", {})
return f"swap {start.get('swap_used_mib')} МиБ, {start.get('power')}"
def versions(meta: dict[str, Any]) -> str:
found = meta.get("app_image", {}).get("versions", {})
return ", ".join(f"{name} {ver}" for name, ver in found.items())
return [
"| | " + " | ".join(f"`{x.name}`" for x in labels) + " |",
"|---|" + "---|" * len(labels),
field("Commit", lambda m: f"`{m.get('git', {}).get('commit')}`"),
field("Начало прогона", lambda m: str(m.get("started_at"))),
field("Статус", lambda m: str(m.get("status"))),
field("Версии в образе", versions),
field("Хост в начале", host),
]
def scenario_table(
rows: list[Row],
floor: dict[str, Row] | None,
) -> list[str]:
lines = [
"| Размер | Клиенты | RPS до | RPS после | Δ RPS | Вывод | "
"CPU на запрос, мкс | Δ CPU, мкс | p50, мс | p95, мс | p99, мс |",
"|---|---|---|---|---|---|---|---|---|---|---|",
]
for row in rows:
before, after = row.before, row.after
if floor is None:
verdict = (
"разбросы пересекаются"
if row.overlap
else "разбросы не пересекаются"
)
elif not row.overlap and abs(row.delta) > abs(floor[row.key[0]].delta):
verdict = "эффект"
else:
verdict = "в пределах шума"
lines.append(
f"| {human(row.key[1])} | {row.key[2]} | "
f"{before.median:.0f} ({min(before.rps):.0f}–"
f"{max(before.rps):.0f}) | "
f"{after.median:.0f} ({min(after.rps):.0f}–"
f"{max(after.rps):.0f}) | "
f"{row.delta:+.1f}% | {verdict} | "
f"{before.cpu_us:.0f} → {after.cpu_us:.0f} | "
f"{after.cpu_us - before.cpu_us:+.0f} | "
f"{before.p50:.2f} → {after.p50:.2f} | "
f"{before.p95:.2f} → {after.p95:.2f} | "
f"{before.p99:.2f} → {after.p99:.2f} |",
)
deltas = [row.delta for row in rows]
lines += [
"",
f"Δ RPS по ячейкам: от {min(deltas):+.1f}% до {max(deltas):+.1f}%, "
f"медиана {statistics.median(deltas):+.1f}%.",
]
return lines
def memory_table(before: Label, after: Label) -> list[str]:
def sizes(label: Label) -> dict[int, dict[str, Any]]:
return {item["size"]: item for item in label.meta.get("sizes", [])}
first, second = sizes(before), sizes(after)
lines = [
"| Размер | Байт на сообщение до | после | "
"RSS после наполнения до, МиБ | после |",
"|---|---|---|---|---|",
]
for size in sorted(first.keys() & second.keys()):
a, b = first[size], second[size]
lines.append(
f"| {human(size)} | {a.get('bytes_per_message')} | "
f"{b.get('bytes_per_message')} | {a.get('rss_after_mib')} | "
f"{b.get('rss_after_mib')} |",
)
return lines
def render(
before: Label,
after: Label,
aa: Label | None,
command: str,
) -> str:
unverified = check_methodology(before, after)
rows, remarks = compare(before, after)
if not rows:
raise CompareError("labels have no common matrix cells")
labels = [before, after]
floor = None
if aa is not None:
unverified += check_methodology(aa, before)
aa_rows, aa_remarks = compare(aa, before)
floor = noise_floor(aa_rows)
missing = [s for s in {row.key[0] for row in rows} if s not in floor]
if missing:
raise CompareError(
f"label {aa.name} has no cells for {', '.join(missing)}",
)
remarks += aa_remarks
labels.append(aa)
remarks = (
unverified + [text for x in labels for text in notes(x)] + remarks
)
lines = [
f"# Сравнение меток: `{before.name}` → `{after.name}`",
"",
f"- Команда: `{command}`",
"- «До» и «после» — медиана повторов ячейки, в скобках min–max. "
"Δ RPS — отношение медиан минус единица.",
"- CPU на запрос — `app_cpu_cores / rps`, медиана по повторам; "
"задержки — медианы по повторам, «до → после».",
]
if aa is None:
lines.append(
"- Уровень шума не задан (`AA`): вывод говорит только, "
"пересекаются ли разбросы повторов.",
)
else:
lines += [
f"- Уровень шума — наибольшее по ячейкам сценария изменение "
f"медианы RPS между `{aa.name}` и `{before.name}`. Он имеет "
"смысл, только если код приложения в этих метках одинаков; "
"это проверяется по git, команда этого не видит.",
"- «Эффект» — разбросы повторов не пересекаются и изменение "
"медианы больше уровня шума сценария; иначе «в пределах шума».",
]
lines += [
"",
"## Метки",
"",
*passport_rows(labels),
"",
"## Замечания",
"",
]
lines += [f"- {text}" for text in dict.fromkeys(remarks)] or ["Нет."]
if floor is not None and aa is not None:
lines += [
"",
"## Уровень шума",
"",
f"| Сценарий | Наибольшее изменение RPS, `{aa.name}` → "
f"`{before.name}` | Ячейка |",
"|---|---|---|",
]
lines += [
f"| {scenario} | {abs(floor[scenario].delta):.1f}% | "
f"{human(floor[scenario].key[1])} × {floor[scenario].key[2]} |"
for scenario in SCENARIOS
if scenario in floor
]
for scenario in SCENARIOS:
selected = [row for row in rows if row.key[0] == scenario]
if selected:
lines += [
"",
f"## Сценарий `{scenario}`",
"",
*scenario_table(selected, floor),
]
lines += ["", "## Память", "", *memory_table(before, after)]
return "\n".join(lines) + "\n"
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--before", default="")
parser.add_argument("--after", default="")
parser.add_argument("--aa", default="")
args = parser.parse_args(argv)
if not args.before or not args.after:
print(
"both labels are required: "
"make bench_compare BEFORE=<label> AFTER=<label> [AA=<label>]",
flush=True,
)
return 2
command = f"make bench_compare BEFORE={args.before} AFTER={args.after}"
if args.aa:
command += f" AA={args.aa}"
try:
text = render(
load(args.before),
load(args.after),
load(args.aa) if args.aa else None,
command,
)
except CompareError as exc:
print(f"compare failed: {exc}", flush=True)
return 1
out = OUT_DIR / f"{args.before}__{args.after}.md"
out.parent.mkdir(parents=True, exist_ok=True)
out.write_text(text, encoding="utf-8")
print(text, flush=True)
print(f"saved to {out.relative_to(ROOT)}", flush=True)
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
+845
View File
@@ -0,0 +1,845 @@
"""Разложение стоимости запроса внутри процесса: диагностика трека 1.
Запуск — `make bench_inproc BENCH_LABEL=<метка>`. На хосте скрипт собирает
образ стенда, запускает себя в контейнере и пишет
`evidence/profile/<метка>.txt`; здесь только stdlib. В контейнере
(`--child`) он импортирует приложение и вызывает его как ASGI, без
uvicorn и сети. Числа объясняют, куда уходит время запроса; пропускную
способность и задержки меряет только `make bench`. Методика — design
change `perf-bottleneck-fix`, граница — `.claude/rules/bench.md`.
"""
import argparse
import asyncio
import cProfile
import functools
import importlib.metadata
import json
import os
import platform
import pstats
import random
import re
import statistics
import subprocess
import sys
import time
from collections.abc import Awaitable, Callable
from datetime import UTC, datetime, timedelta, timezone
from pathlib import Path
from typing import Annotated, Any
from uuid import UUID
ROOT = Path(__file__).resolve().parents[1]
SCRIPT = Path(__file__).resolve()
APP_IMAGE = "mtusi-messenger:bench"
CONTAINER = "mtusi-bench-inproc"
RESULT_MARK = "INPROC_RESULT "
# незакоммиченные изменения считаются только по тому, что попадает в замер
APP_FILES = (
"src",
"Dockerfile",
"pyproject.toml",
"uv.lock",
".dockerignore",
".python-version",
"bench/inproc.py",
)
# эталон формата времени: запись, которой оно сериализовалось до правки.
# Литерал, а не константа из src: расхождение с кодом должно быть видно
REFERENCE_FORMAT = "%Y-%m-%dT%H:%M:%S.%fZ"
RFC3339_RE = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z")
SEED = 20260930
SIZE = 20_000
TEXT_LENGTH = 64
PAGE_LIMIT = 50
CURSOR_POOL = 300
# запусков процесса на каждый режим: от запуска к запуску время запроса
# гуляет на 1–3%, внутри запуска — меньше
LAUNCHES = 3
# режим логов: уровень и флаги процесса. INFO — как на стенде; INFO_NULL —
# записи собираются, но stdout процесса смотрит в /dev/null
MODES: dict[str, tuple[str, list[str]]] = {
"INFO": ("INFO", []),
"INFO_NULL": ("INFO", ["--null-stdout"]),
"WARNING": ("WARNING", []),
}
REPEATS = 5
REQUESTS = 3000
PART_ROUNDS = 2000
VALUE_ROUNDS = 100_000
PROFILE_REQUESTS = 2000
PROFILE_TOP = 15
FORMAT_SAMPLES = 20_000
TIME_NAMES = ("to_rfc3339", "strftime", "isoformat", "astimezone")
class InprocError(Exception):
"""Диагностика не может продолжать: сообщение для человека."""
def spread(values: list[float]) -> dict[str, float]:
return {
"median": round(statistics.median(values), 3),
"min": round(min(values), 3),
"max": round(max(values), 3),
}
# ------------------------------------------------------------- в контейнере
def reference_rfc3339(value: datetime, fmt: str) -> str:
return value.astimezone(UTC).strftime(fmt)
def format_values() -> list[datetime]:
"""Случайные значения 1970–2100 и граничные случаи формата."""
rng = random.Random(SEED)
start = datetime(1970, 1, 1, tzinfo=UTC)
span = int((datetime(2100, 1, 1, tzinfo=UTC) - start).total_seconds())
values = [
start
+ timedelta(
seconds=rng.randrange(span),
microseconds=rng.randrange(1_000_000),
)
for _ in range(FORMAT_SAMPLES)
]
moment = datetime(2026, 9, 30, 12, 0, 0, tzinfo=UTC)
values += [moment.replace(microsecond=m) for m in (0, 1, 999_999)]
values += [
start,
datetime(2026, 12, 31, 23, 59, 59, 999_999, tzinfo=UTC),
datetime(2028, 2, 29, 0, 0, 0, tzinfo=UTC),
]
# другой часовой пояс: после приведения к UTC меняются день и год
for hours in (3, -8):
zone = timezone(timedelta(hours=hours))
values += [
datetime(2026, 12, 31, 23, 30, 0, 0, tzinfo=zone),
datetime(2027, 1, 1, 1, 30, 0, 123, tzinfo=zone),
]
return values
def check_format(
to_text: Callable[[datetime], str],
from_text: Callable[[str], datetime],
fmt: str,
) -> dict[str, Any]:
"""Текущий форматтер против эталона; первое расхождение — в ответ."""
values = format_values()
for value in values:
expected = reference_rfc3339(value, fmt)
got = to_text(value)
problem = None
if got != expected:
problem = "differs from reference"
elif not RFC3339_RE.fullmatch(got):
problem = "not YYYY-MM-DDTHH:MM:SS.ffffffZ"
elif from_text(got) != value:
problem = "does not parse back to the same instant"
if problem:
return {
"checked": len(values),
"mismatch": {
"problem": problem,
"value": value.isoformat(),
"expected": expected,
"got": got,
},
}
return {"checked": len(values), "mismatch": None}
class Probe:
"""Прямые ASGI-вызовы приложения."""
def __init__(self, app: Any) -> None:
self.app = app
@staticmethod
def headers(
user: str | None,
body: bytes = b"",
) -> list[tuple[bytes, bytes]]:
result = [(b"host", b"inproc")]
if body:
result.append((b"content-type", b"application/json"))
result.append((b"content-length", str(len(body)).encode()))
if user:
result.append((b"x-user-id", user.encode()))
return result
async def request(
self,
method: str,
path: str,
headers: list[tuple[bytes, bytes]],
*,
query: bytes = b"",
body: bytes = b"",
) -> tuple[int, bytes]:
scope = {
"type": "http",
"asgi": {"version": "3.0"},
"http_version": "1.1",
"method": method,
"scheme": "http",
"path": path,
"raw_path": path.encode(),
"query_string": query,
"root_path": "",
"headers": headers,
"client": ("127.0.0.1", 1),
"server": ("127.0.0.1", 8080),
}
messages: list[dict[str, Any]] = []
async def receive() -> dict[str, Any]:
return {"type": "http.request", "body": body, "more_body": False}
async def send(message: dict[str, Any]) -> None:
messages.append(message)
await self.app(scope, receive, send)
return (
messages[0]["status"],
b"".join(m.get("body", b"") for m in messages[1:]),
)
async def create(
self,
path: str,
payload: dict[str, Any],
user: str | None = None,
) -> dict[str, Any]:
body = json.dumps(payload).encode()
status, raw = await self.request(
"POST",
path,
self.headers(user, body),
body=body,
)
if status != 201:
raise InprocError(f"POST {path}: {status} {raw[:200]!r}")
return json.loads(raw)
async def repeat(
fn: Callable[[], Awaitable[None]],
count: int,
) -> dict[str, Any]:
"""Прогрев и REPEATS повторов; время и CPU процесса на один запрос."""
await fn()
walls, cpus = [], []
for _ in range(REPEATS):
wall, cpu = time.perf_counter(), time.process_time()
await fn()
walls.append((time.perf_counter() - wall) / count * 1e6)
cpus.append((time.process_time() - cpu) / count * 1e6)
return {"wall_us": spread(walls), "cpu_us": spread(cpus)}
def repeat_sync(fn: Callable[[], Any], count: int) -> dict[str, float]:
for _ in range(count):
fn()
walls = []
for _ in range(REPEATS):
wall = time.perf_counter()
for _ in range(count):
fn()
walls.append((time.perf_counter() - wall) / count * 1e6)
return spread(walls)
def function_label(file: str, line: int, name: str) -> str:
if file == "~":
return name
if "site-packages/" in file:
short = file.split("site-packages/", 1)[1]
elif file.startswith(os.getcwd() + "/"):
short = file[len(os.getcwd()) + 1 :]
else:
short = "/".join(file.split("/")[-2:])
return f"{short}:{line}({name})"
async def profile(
fn: Callable[[], Awaitable[None]],
count: int,
) -> dict[str, Any]:
"""cProfile: число вызовов и порядок функций, не доли времени."""
profiler = cProfile.Profile()
profiler.enable()
await fn()
profiler.disable()
rows = []
for (file, line, name), (_, calls, own, total, _) in pstats.Stats(
profiler,
).stats.items():
if file == __file__:
continue
rows.append(
{
"function": function_label(file, line, name),
"name": name,
"calls": round(calls / count, 2),
"own_us": round(own / count * 1e6, 2),
"total_us": round(total / count * 1e6, 2),
},
)
rows.sort(key=lambda row: row["own_us"], reverse=True)
return {
"top": rows[:PROFILE_TOP],
"time": [
row for row in rows if any(n in row["name"] for n in TIME_NAMES)
],
}
async def measure(args: argparse.Namespace) -> dict[str, Any]:
# приложение импортируется только здесь: на хосте скрипт — stdlib
sys.path.insert(0, os.getcwd())
from pydantic import PlainSerializer
from src.api.schemas import Message, MessagePage
from src.core.services import MessageService
from src.infra.memory import MemoryStore
from src.main import app
from src.utils.utc import from_rfc3339, to_rfc3339
result: dict[str, Any] = {
"level": os.environ.get("APP__LOG_LEVEL", "INFO"),
"versions": {
"python": platform.python_version(),
**{
name: importlib.metadata.version(name)
for name in (
"fastapi",
"starlette",
"pydantic",
"pydantic_core",
"structlog",
)
},
},
"platform": {
"machine": platform.machine(),
"libc": " ".join(platform.libc_ver()),
},
}
def reference(value: datetime) -> str:
return reference_rfc3339(value, args.reference_format)
class ReferenceMessage(Message):
created_at: Annotated[
datetime,
PlainSerializer(reference, return_type=str),
]
class ReferencePage(MessagePage):
items: list[ReferenceMessage]
class NativeMessage(Message):
created_at: datetime
class NativePage(MessagePage):
items: list[NativeMessage]
if args.parts:
result["format"] = check_format(
to_rfc3339,
from_rfc3339,
args.reference_format,
)
if result["format"]["mismatch"]:
return result
# lifespan при прямых ASGI-вызовах не выполняется
app.state.store = MemoryStore()
probe = Probe(app)
user = (
await probe.create(
"/api/v1/users",
{"username": "inproc_reader", "display_name": "Reader"},
)
)["id"]
chats = [
(
await probe.create(
"/api/v1/chats",
{"title": title, "member_ids": [user]},
user,
)
)["id"]
for title in ("read", "write")
]
read_path, write_path = (f"/api/v1/chats/{c}/messages" for c in chats)
body = json.dumps({"text": "x" * TEXT_LENGTH}).encode()
get_headers = probe.headers(user)
post_headers = probe.headers(user, body)
async def post(path: str, count: int) -> None:
for _ in range(count):
status, _ = await probe.request(
"POST",
path,
post_headers,
body=body,
)
if status != 201:
raise InprocError(f"POST {path}: {status}")
await post(read_path, SIZE)
cursors: list[str] = []
query = f"limit={PAGE_LIMIT}".encode()
while len(cursors) < CURSOR_POOL:
status, raw = await probe.request(
"GET",
read_path,
get_headers,
query=query,
)
cursor = json.loads(raw)["next_cursor"]
if status != 200 or cursor is None:
raise InprocError(f"cursor walk: {status}, next_cursor {cursor}")
cursors.append(cursor)
query = f"limit={PAGE_LIMIT}&cursor={cursor}".encode()
rng = random.Random(SEED)
queries = [
f"limit={PAGE_LIMIT}&cursor={rng.choice(cursors)}".encode()
for _ in range(REQUESTS)
]
async def reads(count: int = REQUESTS) -> None:
for query in queries[:count]:
status, _ = await probe.request(
"GET",
read_path,
get_headers,
query=query,
)
if status != 200:
raise InprocError(f"GET {read_path}: {status}")
async def writes(count: int = REQUESTS) -> None:
await post(write_path, count)
result["requests"] = {
"read": await repeat(reads, REQUESTS),
"write": await repeat(writes, REQUESTS),
}
if not args.parts:
return result
dto = await MessageService(store=app.state.store).list_messages(
chat_id=UUID(chats[0]),
user_id=UUID(user),
limit=PAGE_LIMIT,
cursor=cursors[len(cursors) // 2],
)
current = MessagePage.model_validate(dto)
reference_page = ReferencePage.model_validate(dto)
native = NativePage.model_validate(dto)
if current.model_dump_json() != reference_page.model_dump_json():
result["format"]["mismatch"] = {
"problem": "page JSON differs from reference",
"value": "page of messages",
"expected": reference_page.model_dump_json()[:200],
"got": current.model_dump_json()[:200],
}
return result
moment = dto.items[0].created_at
result["parts"] = {
"dto_to_model": repeat_sync(
functools.partial(MessagePage.model_validate, dto),
PART_ROUNDS,
),
"json_current": repeat_sync(current.model_dump_json, PART_ROUNDS),
"json_reference": repeat_sync(
reference_page.model_dump_json,
PART_ROUNDS,
),
"json_native": repeat_sync(native.model_dump_json, PART_ROUNDS),
"value_current": repeat_sync(
functools.partial(to_rfc3339, moment),
VALUE_ROUNDS,
),
"value_reference": repeat_sync(
functools.partial(reference, moment),
VALUE_ROUNDS,
),
}
result["profile"] = {
"read": await profile(
functools.partial(reads, PROFILE_REQUESTS),
PROFILE_REQUESTS,
),
"write": await profile(
functools.partial(writes, PROFILE_REQUESTS),
PROFILE_REQUESTS,
),
}
return result
def child(args: argparse.Namespace) -> int:
"""Логи приложения идут в stdout, результат — одной строкой в stderr."""
if args.null_stdout:
# до импорта приложения: его логгер берёт sys.stdout при настройке
os.dup2(os.open(os.devnull, os.O_WRONLY), 1)
result = asyncio.run(measure(args))
print(RESULT_MARK + json.dumps(result), file=sys.stderr, flush=True)
return 3 if (result.get("format") or {}).get("mismatch") else 0
# ------------------------------------------------------------------ на хосте
def sh(*args: str, check: bool = True) -> str:
proc = subprocess.run(
args,
capture_output=True,
text=True,
check=False,
env={**os.environ, "LC_ALL": "C"},
)
if check and proc.returncode != 0:
raise InprocError(
f"{' '.join(args[:4])}…: exit {proc.returncode}\n"
f"{(proc.stdout + proc.stderr)[-2000:]}",
)
return proc.stdout.strip()
def run_child(level: str, extra: list[str]) -> dict[str, Any]:
"""Один запуск процесса в контейнере.
Контейнер отсоединён (`-d`), как контейнер стенда: с подключённым
клиентом docker каждая строка лога обходится процессу заметно дороже.
"""
sh(
"docker",
"run",
"-d",
"--name",
CONTAINER,
"--cpus=1",
"--memory=2g",
"--memory-swap=2g",
"--network=none",
"--no-healthcheck",
"-e",
f"APP__LOG_LEVEL={level}",
"-v",
f"{SCRIPT}:/bench/inproc.py:ro",
"--entrypoint",
"python",
APP_IMAGE,
"/bench/inproc.py",
"--child",
*extra,
)
try:
code = sh("docker", "wait", CONTAINER)
proc = subprocess.run(
["docker", "logs", CONTAINER],
stdout=subprocess.DEVNULL,
stderr=subprocess.PIPE,
text=True,
check=False,
)
finally:
sh("docker", "rm", "-f", CONTAINER, check=False)
for line in reversed(proc.stderr.splitlines()):
if line.startswith(RESULT_MARK):
return json.loads(line[len(RESULT_MARK) :])
raise InprocError(f"child {level}: exit {code}\n{proc.stderr[-2000:]}")
def passport(argv: list[str], label: str) -> dict[str, Any]:
docker = json.loads(sh("docker", "info", "--format", "{{json .}}"))
machine = platform.machine()
system = platform.system()
if system == "Darwin":
system = f"macOS {platform.mac_ver()[0]}"
machine = sh("sysctl", "-n", "machdep.cpu.brand_string", check=False)
return {
"label": label,
"date": datetime.now(UTC).isoformat(timespec="seconds"),
"command": " ".join(["uv run python bench/inproc.py", *argv]),
"commit": sh("git", "-C", str(ROOT), "rev-parse", "--short", "HEAD"),
"dirty": bool(
sh(
"git",
"-C",
str(ROOT),
"status",
"--porcelain",
"--",
*APP_FILES,
),
),
"image": sh("docker", "image", "inspect", "-f", "{{.Id}}", APP_IMAGE),
"host": f"{machine}, {system}",
"docker": (
f"Docker {docker.get('ServerVersion')}, VM "
f"{docker.get('NCPU')} CPU"
),
}
def cell(value: dict[str, float], digits: int = 1) -> str:
return (
f"{value['median']:.{digits}f} "
f"({value['min']:.{digits}f}–{value['max']:.{digits}f})"
)
def across(
launches: list[dict[str, Any]],
scenario: str,
key: str = "wall_us",
) -> dict[str, float]:
"""Медианы запусков процесса: их медиана и разброс."""
return spread(
[run["requests"][scenario][key]["median"] for run in launches],
)
def render(
meta: dict[str, Any],
launches: dict[str, list[dict[str, Any]]],
) -> str:
info = launches["INFO"][0]
versions = info["versions"]
parts = info["parts"]
native = parts["json_native"]["median"]
current_cost = parts["json_current"]["median"] - native
reference_cost = parts["json_reference"]["median"] - native
# медианы по запускам: [режим][сценарий]
time = {
mode: {
scenario: across(launches[mode], scenario)
for scenario in ("read", "write")
}
for mode in MODES
}
total = {s: time["INFO"][s]["median"] for s in ("read", "write")}
log_build = {
s: time["INFO_NULL"][s]["median"] - time["WARNING"][s]["median"]
for s in ("read", "write")
}
log_write = {
s: total[s] - time["INFO_NULL"][s]["median"] for s in ("read", "write")
}
model = parts["dto_to_model"]["median"]
rest = time["WARNING"]["read"]["median"] - model - native - current_cost
lines = [
f"# Разложение стоимости запроса: метка `{meta['label']}`",
"",
f"- Дата: {meta['date']}",
f"- Commit: `{meta['commit']}`, незакоммиченные изменения "
f"приложения: {'есть' if meta['dirty'] else 'нет'}",
f"- Команда: `{meta['command']}`",
f"- Образ: `{APP_IMAGE}` {meta['image'][:19]}…; "
+ ", ".join(f"{name} {ver}" for name, ver in versions.items())
+ f"; {info['platform']['libc']}, {info['platform']['machine']}",
"- Контейнер: `--cpus=1 --memory=2g --network=none`, отсоединён "
f"(`docker run -d`), как контейнер стенда; хост: {meta['host']}; "
f"{meta['docker']}",
f"- Данные: {SIZE} сообщений по {TEXT_LENGTH} символа, страница "
f"{PAGE_LIMIT}, зерно {SEED}",
"- Приложение вызывается в том же процессе как ASGI, без uvicorn "
"и сети. Это объяснение, куда уходит время запроса, а не замер "
"стенда: пропускную способность и задержки меряет `make bench`.",
f"- Время на запрос: {LAUNCHES} запуска процесса на каждый режим "
f"логов, в запуске — медиана {REPEATS} повторов по {REQUESTS} "
"запросов; значение — медиана (min–max) по запускам, мкс.",
"- Режимы логов: INFO — как на стенде, stdout контейнера; INFO с "
"stdout процесса в `/dev/null` — записи собираются, но не "
"пишутся в контейнер; WARNING — записи INFO отбрасываются.",
f"- Части ответа: один запуск, медиана (min–max) {REPEATS} "
"повторов, мкс. Варианты сравниваются внутри одного процесса.",
"",
"## Формат времени",
"",
f"Значений сверено с эталоном `{REFERENCE_FORMAT}`: "
f"{info['format']['checked']}; расхождений нет, обратный разбор "
"совпал, JSON страницы совпал с эталонным.",
"",
"## Сводка: из чего складывается запрос, мкс",
"",
"| Часть | read | write |",
"|---|---|---|",
"| Всего внутри приложения, логи INFO | "
f"{total['read']:.1f} | {total['write']:.1f} |",
"| логи: запись в stdout контейнера | "
f"{log_write['read']:.1f} | {log_write['write']:.1f} |",
"| логи: сборка записи (structlog, JSON) | "
f"{log_build['read']:.1f} | {log_build['write']:.1f} |",
f"| форматирование времени в ответе | {current_cost:.1f} | — |",
f"| JSON ответа без форматирования времени | {native:.1f} | — |",
f"| DTO → модель ответа | {model:.1f} | — |",
"| остальное: маршрутизация, зависимости, сервис | "
f"{rest:.1f} | {time['WARNING']['write']['median']:.1f} |",
"",
"Строки про логи и «остальное» — разности медиан разных запусков; "
"части ответа измерены напрямую.",
"",
"## Время на запрос",
"",
"| Сценарий | Логи INFO | Логи INFO, stdout в /dev/null | "
"Логи WARNING |",
"|---|---|---|---|",
]
for scenario in ("read", "write"):
lines.append(
f"| {scenario} | "
+ " | ".join(cell(time[mode][scenario]) for mode in MODES)
+ " |",
)
lines += [
"",
"CPU процесса на запрос при логах INFO: "
+ ", ".join(
f"{name} {cell(across(launches['INFO'], name, 'cpu_us'))}"
for name in ("read", "write")
)
+ ".",
"",
f"## Построение ответа страницы ({PAGE_LIMIT} сообщений)",
"",
"| Шаг | мкс |",
"|---|---|",
f"| DTO → модель ответа | {cell(parts['dto_to_model'])} |",
f"| модель → JSON, текущий форматтер | "
f"{cell(parts['json_current'])} |",
f"| модель → JSON, эталонный `strftime` | "
f"{cell(parts['json_reference'])} |",
f"| модель → JSON, без Python-сериализатора времени | "
f"{cell(parts['json_native'])} |",
"| цена форматирования времени: текущий − без сериализатора | "
f"{current_cost:.1f} |",
f"| то же для эталонного `strftime` | {reference_cost:.1f} |",
f"| одно значение, текущий форматтер | "
f"{cell(parts['value_current'], 3)} |",
f"| одно значение, эталонный `strftime` | "
f"{cell(parts['value_reference'], 3)} |",
"",
f"## Профиль вызовов (cProfile, {PROFILE_REQUESTS} запросов)",
"",
"cProfile завышает цену кода с большим числом мелких вызовов: "
"отсюда берутся число вызовов и порядок функций, не доли времени.",
]
for scenario in ("read", "write"):
data = info["profile"][scenario]
lines += [
"",
f"### {scenario}: форматирование времени",
"",
"| Функция | Вызовов на запрос | Своё время, мкс | "
"С вложенными, мкс |",
"|---|---|---|---|",
]
lines += [profile_row(row) for row in data["time"]]
lines += [
"",
f"### {scenario}: {PROFILE_TOP} функций по своему времени",
"",
"| Функция | Вызовов на запрос | Своё время, мкс | "
"С вложенными, мкс |",
"|---|---|---|---|",
]
lines += [profile_row(row) for row in data["top"]]
return "\n".join(lines) + "\n"
def profile_row(row: dict[str, Any]) -> str:
return (
f"| `{row['function']}` | {row['calls']:g} | "
f"{row['own_us']:.1f} | {row['total_us']:.1f} |"
)
def host(args: argparse.Namespace, argv: list[str]) -> int:
if not re.fullmatch(r"[A-Za-z0-9._-]+", args.label or ""):
print(f"bad label {args.label!r}: use [A-Za-z0-9._-]", flush=True)
return 2
out = ROOT / "evidence" / "profile" / f"{args.label}.txt"
if out.exists():
print(f"{out.relative_to(ROOT)} already exists", flush=True)
return 2
extra = ["--reference-format", args.reference_format]
names = sh("docker", "ps", "-a", "--format", "{{.Names}}", check=False)
if CONTAINER in names.split():
# чужой запуск не трогаем: уборка ниже — только за собой
print(
f"container {CONTAINER} already exists: another run is going "
f"or a crashed one left it; docker rm -f {CONTAINER}",
flush=True,
)
return 1
launches: dict[str, list[dict[str, Any]]] = {mode: [] for mode in MODES}
try:
sh("docker", "build", "-q", "-t", APP_IMAGE, str(ROOT))
meta = passport(argv, args.label)
print(f"image {APP_IMAGE} built, commit {meta['commit']}", flush=True)
# режимы чередуются: дрейф хоста не ложится на один из них
for number in range(1, LAUNCHES + 1):
for mode, (level, flags) in MODES.items():
first = not launches["INFO"]
result = run_child(
level,
[*extra, *flags, *(["--parts"] if first else [])],
)
mismatch = (result.get("format") or {}).get("mismatch")
if mismatch:
print(
f"time format check failed: {mismatch['problem']}\n"
f" value: {mismatch['value']}\n"
f" expected: {mismatch['expected']}\n"
f" got: {mismatch['got']}",
flush=True,
)
return 1
launches[mode].append(result)
requests = result["requests"]
print(
f"launch {number}/{LAUNCHES} {mode:<9} "
f"read {requests['read']['wall_us']['median']:.1f} "
f"write {requests['write']['wall_us']['median']:.1f} us",
flush=True,
)
except InprocError as exc:
print(f"inproc failed: {exc}", flush=True)
return 1
text = render(meta, launches)
out.parent.mkdir(parents=True, exist_ok=True)
out.write_text(text, encoding="utf-8")
print(text, flush=True)
print(f"saved to {out.relative_to(ROOT)}", flush=True)
return 0
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--label")
parser.add_argument("--child", action="store_true")
parser.add_argument("--parts", action="store_true")
parser.add_argument("--null-stdout", action="store_true")
# отладка сверки: с другим эталоном команда обязана упасть
parser.add_argument("--reference-format", default=REFERENCE_FORMAT)
args = parser.parse_args(argv)
if args.child:
return child(args)
return host(args, argv)
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
+61
View File
@@ -0,0 +1,61 @@
// Пул курсоров сценария read: проход истории читаемого чата страницами по
// WALK_LIMIT и равномерная выборка до POOL_SIZE курсоров. В пул идут
// только позиции, после которых есть ещё PAGE_LIMIT сообщений, чтобы
// каждая страница read была полной.
import http from "k6/http";
import { fail } from "k6";
import { API, PAGE_LIMIT, WORK_DIR, authHeaders } from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const WALK_LIMIT = Number(__ENV.WALK_LIMIT || 100);
const POOL_SIZE = Number(__ENV.POOL_SIZE || 1000);
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "30m",
};
export function setup() {
const url = `${API}/chats/${fixture.readChatId}/messages`;
const params = { headers: authHeaders(fixture.readerId) };
const positions = [];
let cursor = null;
let walked = 0;
for (;;) {
const query = cursor === null
? `?limit=${WALK_LIMIT}`
: `?limit=${WALK_LIMIT}&cursor=${encodeURIComponent(cursor)}`;
const res = http.get(url + query, params);
if (res.status !== 200) {
fail(`history page after ${walked}: ${res.status} ${res.body}`);
}
const body = res.json();
walked += body.items.length;
if (body.next_cursor === null) {
break;
}
positions.push({ after: walked, cursor: body.next_cursor });
cursor = body.next_cursor;
}
const eligible = positions.filter((p) => walked - p.after >= PAGE_LIMIT);
const step = Math.max(1, eligible.length / POOL_SIZE);
const pool = [];
for (let i = 0; i < eligible.length && pool.length < POOL_SIZE; i += step) {
pool.push(eligible[Math.floor(i)]);
}
return {
walked,
eligible: eligible.length,
first_after: pool.length ? pool[0].after : null,
last_after: pool.length ? pool[pool.length - 1].after : null,
cursors: pool.map((p) => p.cursor),
};
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/cursors.json`]: JSON.stringify(data.setup_data) };
}
+89
View File
@@ -0,0 +1,89 @@
// Общие хелперы сценариев стенда: адрес, идентификация, текст, генератор
// случайных чисел, запись итога. Не Node.js: только встроенные модули k6.
import http from "k6/http";
import { check, fail } from "k6";
export const BASE_URL = __ENV.BASE_URL || "http://mtusi-bench-api:8080";
export const API = `${BASE_URL}/api/v1`;
// каталог метки (сырые итоги) и рабочий каталог (фикстура, курсоры)
export const OUT_DIR = __ENV.OUT_DIR || "/out";
export const WORK_DIR = __ENV.WORK_DIR || "/work";
export const TEXT_LENGTH = Number(__ENV.TEXT_LENGTH || 64);
export const PAGE_LIMIT = Number(__ENV.PAGE_LIMIT || 50);
// перцентили в итоге; подметрика expected_response:true — только успехи
export const SUMMARY_TREND_STATS = [
"avg", "min", "med", "p(50)", "p(95)", "p(99)", "max",
];
export const SUCCESS_DURATION = "http_req_duration{expected_response:true}";
// порог всегда выполняется: он нужен, чтобы подметрика попала в итог
export const SUMMARY_THRESHOLDS = { [SUCCESS_DURATION]: ["max>=0"] };
// идентификация лабы 1; с лабы 2 здесь Bearer, как Actor.headers()
export function authHeaders(userId) {
return { "X-User-Id": userId, "Content-Type": "application/json" };
}
// синтетический текст ровно TEXT_LENGTH ASCII-символов
export function syntheticText(tag, n) {
const prefix = `${tag}-${n}-`;
return prefix + "x".repeat(Math.max(0, TEXT_LENGTH - prefix.length));
}
// mulberry32: воспроизводимая последовательность из 32-битного зерна
export function mulberry32(seed) {
let a = seed >>> 0;
return function () {
a = (a + 0x6d2b79f5) >>> 0;
let t = a;
t = Math.imul(t ^ (t >>> 15), t | 1);
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
export function register(username, displayName) {
const res = http.post(
`${API}/users`,
JSON.stringify({ username, display_name: displayName }),
{ headers: { "Content-Type": "application/json" } },
);
if (!check(res, { "register 201": (r) => r.status === 201 })) {
fail(`register ${username}: ${res.status} ${res.body}`);
}
return res.json("id");
}
export function createChat(ownerId, title, memberIds) {
const res = http.post(
`${API}/chats`,
JSON.stringify({ title, member_ids: memberIds }),
{ headers: authHeaders(ownerId) },
);
if (!check(res, { "chat 201": (r) => r.status === 201 })) {
fail(`create chat ${title}: ${res.status} ${res.body}`);
}
return res.json("id");
}
export function sendMessage(chatId, senderId, text) {
const res = http.post(
`${API}/chats/${chatId}/messages`,
JSON.stringify({ text }),
{
headers: authHeaders(senderId),
responseCallback: http.expectedStatuses(201),
},
);
check(res, { "message 201": (r) => r.status === 201 });
return res;
}
// итог прогона: в файл NAME.json каталога метки; без NAME — в рабочий
// каталог (прогрев), чтобы оркестратор посчитал подтверждённые записи
export function summaryFiles(data) {
const name = __ENV.NAME;
const path = name ? `${OUT_DIR}/raw/${name}.json` : `${WORK_DIR}/last.json`;
return { [path]: JSON.stringify(data) };
}
+39
View File
@@ -0,0 +1,39 @@
// Одна порция наполнения читаемого чата: COUNT сообщений от участников по
// кругу. OFFSET — сколько сообщений уже отправлено, для номеров в тексте.
import exec from "k6/execution";
import {
SUMMARY_THRESHOLDS,
SUMMARY_TREND_STATS,
WORK_DIR,
sendMessage,
summaryFiles,
syntheticText,
} from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const OFFSET = Number(__ENV.OFFSET || 0);
export const options = {
scenarios: {
prefill: {
executor: "shared-iterations",
vus: Number(__ENV.VUS || 32),
iterations: Number(__ENV.COUNT),
maxDuration: "30m",
},
},
discardResponseBodies: true,
summaryTrendStats: SUMMARY_TREND_STATS,
thresholds: SUMMARY_THRESHOLDS,
};
export default function () {
const n = OFFSET + exec.scenario.iterationInTest;
const sender = fixture.memberIds[n % fixture.memberIds.length];
sendMessage(fixture.readChatId, sender, syntheticText("p", n));
}
export function handleSummary(data) {
return summaryFiles(data);
}
+34
View File
@@ -0,0 +1,34 @@
// Пользователи и два чата стенда: читаемый (сценарий read) и чат записи
// (сценарий write). Итог — fixture.json в рабочем каталоге.
import { WORK_DIR, createChat, register } from "./lib.js";
const MEMBERS = Number(__ENV.MEMBERS || 10);
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "60s",
};
export function setup() {
// размер начинается с пустого процесса, поэтому имени хватает времени
const stamp = Date.now().toString(36);
const readerId = register(`b${stamp}_reader`, "Bench reader");
const memberIds = [];
for (let i = 0; i < MEMBERS; i++) {
memberIds.push(register(`b${stamp}_m${i}`, `Bench member ${i}`));
}
const everyone = [readerId, ...memberIds];
return {
readerId,
memberIds,
readChatId: createChat(readerId, "bench read", everyone),
writeChatId: createChat(readerId, "bench write", everyone),
};
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/fixture.json`]: JSON.stringify(data.setup_data) };
}
+69
View File
@@ -0,0 +1,69 @@
// Сценарий read: страница истории читаемого чата с курсором, случайно
// выбранным из пула. У каждого VU свой генератор с зерном SEED + номер VU:
// последовательность одинакова в разных метках и различна у клиентов.
import exec from "k6/execution";
import http from "k6/http";
import { check } from "k6";
import { SharedArray } from "k6/data";
import {
API,
PAGE_LIMIT,
SUMMARY_THRESHOLDS,
SUMMARY_TREND_STATS,
WORK_DIR,
authHeaders,
mulberry32,
summaryFiles,
} from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const cursors = new SharedArray(
"cursors",
() => JSON.parse(open(`${WORK_DIR}/cursors.json`)).cursors,
);
const SEED = Number(__ENV.SEED || 0);
// отладка стенда: напечатать первые TRACE выборов каждого VU
const TRACE = Number(__ENV.TRACE || 0);
const URL = `${API}/chats/${fixture.readChatId}/messages`;
const PARAMS = {
headers: authHeaders(fixture.readerId),
responseCallback: http.expectedStatuses(200),
};
export const options = {
scenarios: {
read: {
executor: "constant-vus",
vus: Number(__ENV.VUS),
duration: __ENV.DURATION,
gracefulStop: "5s",
},
},
summaryTrendStats: SUMMARY_TREND_STATS,
thresholds: SUMMARY_THRESHOLDS,
};
let random = null;
let picks = 0;
export default function () {
if (random === null) {
random = mulberry32(SEED + exec.vu.idInTest);
}
const index = Math.floor(random() * cursors.length);
if (picks < TRACE) {
console.log(`trace vu=${exec.vu.idInTest} pick=${picks} index=${index}`);
}
picks += 1;
const cursor = encodeURIComponent(cursors[index]);
const res = http.get(`${URL}?limit=${PAGE_LIMIT}&cursor=${cursor}`, PARAMS);
check(res, {
"status 200": (r) => r.status === 200,
"full page": (r) => r.status === 200 && r.json("items.#") === PAGE_LIMIT,
});
}
export function handleSummary(data) {
return summaryFiles(data);
}
+48
View File
@@ -0,0 +1,48 @@
// Проверка после блока read: читаемый чат не изменился. Дочитывает
// историю от последнего курсора пула до конца и считает сообщения. Новое
// сообщение встало бы в конец, поэтому хвоста достаточно.
import http from "k6/http";
import { fail } from "k6";
import { API, WORK_DIR, authHeaders } from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const pool = JSON.parse(open(`${WORK_DIR}/cursors.json`));
const WALK_LIMIT = Number(__ENV.WALK_LIMIT || 100);
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "30m",
};
export function setup() {
const url = `${API}/chats/${fixture.readChatId}/messages`;
const params = { headers: authHeaders(fixture.readerId) };
// пустой пул (история короче страницы обхода) — читаем с начала
const hasPool = pool.cursors.length > 0;
let cursor = hasPool ? pool.cursors[pool.cursors.length - 1] : null;
let tail = 0;
for (;;) {
const query = cursor === null
? `?limit=${WALK_LIMIT}`
: `?limit=${WALK_LIMIT}&cursor=${encodeURIComponent(cursor)}`;
const res = http.get(url + query, params);
if (res.status !== 200) {
fail(`history tail after ${tail}: ${res.status} ${res.body}`);
}
const body = res.json();
tail += body.items.length;
if (body.next_cursor === null) {
break;
}
cursor = body.next_cursor;
}
return { from_after: hasPool ? pool.last_after : 0, tail };
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/tail.json`]: JSON.stringify(data.setup_data) };
}
+39
View File
@@ -0,0 +1,39 @@
// Сценарий write: ровно COUNT сообщений в чат записи от участников по
// кругу, VUS клиентов одновременно. Читаемый чат не меняется.
import exec from "k6/execution";
import {
SUMMARY_THRESHOLDS,
SUMMARY_TREND_STATS,
WORK_DIR,
sendMessage,
summaryFiles,
syntheticText,
} from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const OFFSET = Number(__ENV.OFFSET || 0);
export const options = {
scenarios: {
write: {
executor: "shared-iterations",
vus: Number(__ENV.VUS),
iterations: Number(__ENV.COUNT),
maxDuration: "10m",
},
},
discardResponseBodies: true,
summaryTrendStats: SUMMARY_TREND_STATS,
thresholds: SUMMARY_THRESHOLDS,
};
export default function () {
const n = OFFSET + exec.scenario.iterationInTest;
const sender = fixture.memberIds[n % fixture.memberIds.length];
sendMessage(fixture.writeChatId, sender, syntheticText("w", n));
}
export function handleSummary(data) {
return summaryFiles(data);
}
+1273
View File
File diff suppressed because it is too large Load Diff
+11
View File
@@ -0,0 +1,11 @@
# Шаблон config.toml: `make env_setup` копирует его, не перезаписывая
# существующий файл. Приоритет: окружение > .env > config.toml >
# значения по умолчанию. Любой параметр можно задать и через
# окружение: SECTION__FIELD, например APP__LOG_LEVEL.
[app]
# Режим (console / docker) задают Makefile, Dockerfile и compose через
# APP__RUN_MODE, а порт — APP__PORT в .env; здесь их не указывать.
log_level = "INFO"
# сколько секунд uvicorn ждёт текущие запросы после SIGTERM
graceful_shutdown_seconds = 8
+24
View File
@@ -0,0 +1,24 @@
# Стенд лабы 1: один процесс API, состояние в памяти. Правила —
# .claude/rules/docker.md. Переменные — из .env (шаблон .env.example).
services:
api:
build: .
# тот же тег, что у docker build из README и make run_no_compose
image: mtusi-messenger:lab2
restart: unless-stopped
ports:
# только localhost: стенд учебный
- "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"
environment:
- APP__RUN_MODE=docker
- APP__PORT=${APP__PORT:-8080}
volumes:
# длинная запись: без файла запуск падает, а не создаёт каталог
- type: bind
source: ./config.toml
target: /app/config.toml
read_only: true
bind:
create_host_path: false
# healthcheck — из образа; SIGKILL не раньше, чем через 10 с
stop_grace_period: 10s
View File
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-09-29
@@ -0,0 +1,375 @@
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`.
Приложение уже готово к контейнеру (change `messenger-core-api`):
- режим `APP__RUN_MODE=docker` слушает `0.0.0.0` без reload;
- `uvicorn.run` получает `timeout_graceful_shutdown` из
`[app] graceful_shutdown_seconds` (8 с, валидатор не пускает больше
9 с);
- `/health/ready` исключён из итоговой записи о запросе;
- логи — JSON в stdout, включая строки uvicorn.
Форму Dockerfile и compose задают `.claude/rules/docker.md` и
`run-modes.md`: мультистейдж с uv и compose в стиле bp_proxies.
`config.toml` монтируется на старте, это согласовано с преподавателем
(`AGENTS.md`). Цели Makefile оформляются так же, как в bp_proxies, без
Apple Container.
Факты, проверенные при планировании:
- **Образы.** Последний патч Python 3.12 — `python:3.12.14-slim-trixie`
(Debian 13), uv — `ghcr.io/astral-sh/uv:0.12.17`, та же версия, что
локально. Оба digest — индексы для нескольких архитектур (amd64 и
arm64):
- `python:3.12.14-slim-trixie@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f`
- `ghcr.io/astral-sh/uv:0.12.17@sha256:10787c682e4184e4f290de1171fd4703dc63de99221f10fe1c99002ce7fa9acc`
- **uvicorn 0.54 на SIGTERM.** Сначала закрывает слушающий сокет, затем
закрывает простаивающие соединения, ждёт текущие запросы до
`timeout_graceful_shutdown` и отменяет оставшиеся. После этого
выполняет shutdown в lifespan и повторно шлёт себе пойманный сигнал
через `signal.raise_signal`.
## Goals / Non-Goals
**Goals:**
- `docker build` и `docker run` из README работают из чистого clone без
подготовительных шагов, `make test` проходит против контейнера.
- Уровень «4» по контейнеру проверяется командами:
- non-root;
- пины версий и digest;
- `.dockerignore`;
- остановка по SIGTERM быстрее 10 с;
- healthcheck;
- журнал без содержимого сообщений.
- Доказательства лежат в `evidence/container/` и в строках `REPORT.md`,
а не только в выводе терминала.
**Non-Goals:**
- Лимиты CPU и памяти контейнера — их задаст методика трека 1 в
отдельном change.
- Сборка образа под чужую архитектуру и публикация в registry:
собираем локально под платформу хоста, а пины через индекс
работают на обеих архитектурах.
- CI-сборка образа (`CONTRIBUTING.md` предлагает отдельный job в CI) —
по желанию, позже.
## Decisions
### 1. Dockerfile: два stage на одном базовом образе
```
FROM python:3.12.14-slim-trixie@sha256:… AS builder
COPY --from=ghcr.io/astral-sh/uv:0.12.17@sha256:… /uv /bin/uv
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=never \
UV_PROJECT_ENVIRONMENT=/app/.venv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-dev --no-install-project
FROM python:3.12.14-slim-trixie@sha256:… AS runtime
RUN groupadd --system --gid 10001 app \
&& useradd --system --uid 10001 --gid app --no-create-home \
--home-dir /nonexistent --shell /usr/sbin/nologin app
ENV PATH=/app/.venv/bin:$PATH PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 APP__RUN_MODE=docker
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src ./src
USER app
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s \
--start-interval=1s --retries=3 \
CMD ["python", "-c", "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/health/ready' % os.environ.get('APP__PORT', '8080'), timeout=2)"]
CMD ["python", "-m", "src"]
```
- **Один базовый образ в обоих stage.** Интерпретатор в `.venv` — это
ссылка на `/usr/local/bin/python3.12` базового образа. Если builder
взять на другом образе, в runtime `.venv` перестанет работать.
- **`--no-install-project`.** Проект не ставится в `.venv` как пакет:
hatchling собрал бы его из `src/`, которого в builder ещё нет.
`python -m src` запускается из `/app`, и `src` находится через
текущий каталог.
- **Код без права записи.** Код и `.venv` копируются от root и
принадлежат root. Пользователь `app` (UID 10001) может их только
читать — это требование «код только на чтение».
`PYTHONDONTWRITEBYTECODE` убирает попытки записать `.pyc` рядом с
`src/`. Зависимости скомпилированы в builder (`UV_COMPILE_BYTECODE`).
- **Кеш сборки.** Слой зависимостей пересобирается только при изменении
`pyproject.toml` или `uv.lock`. Cache mount ускоряет повторный
`uv sync`, но в образ не попадает.
- **Порт в healthcheck.** Берётся из `APP__PORT`, как у сервиса,
значение по умолчанию — 8080. Так healthcheck работает и в
README-запуске, и в compose, где порт может быть другим.
- **`--start-interval=1s`.** Во время `start_period` проверка идёт раз в
секунду. Без этого первая проверка — только через `interval` (10 с),
и контейнер не станет `healthy` до конца `start_period`, как требует
спека. Флаг поддерживается с Docker Engine 25.
- **Отличия от bp_proxies:**
- uv не ставится `pip install` без версии и не нужен в runtime;
- `config.toml` не копируется в образ;
- сервер запускается как PID 1 без `uv run`.
*Альтернативы:*
- `python:3.12-slim` без пина — запрещено рубрикой.
- Bookworm вместо trixie — trixie актуальный stable Debian, а
`3.12.14-slim-bookworm` тоже есть и нужен, только если найдётся
несовместимость.
- Distroless: сложнее отлаживать на защите (`docker exec` без shell), и
пришлось бы переносить интерпретатор. Выигрыш в размере для
учебного стенда не нужен.
### 2. Пины: тег и digest индекса
В `FROM` и `COPY --from` пишется `тег@sha256:<digest индекса>`. Тег
говорит, какая это версия, digest гарантирует повторяемость, даже если
тег перепубликуют с обновлениями безопасности. Digest индекса, а не
манифеста одной платформы, одинаково работает на arm64 (машина автора) и
amd64 (стенд преподавателя). Обновление версии — осознанная правка:
новый тег и digest из `docker buildx imagetools inspect <тег>`.
### 3. `.dockerignore`
Файл из skeleton дополняется, а не заменяется (`docker.md`):
`config.toml`, `.claude`, `openspec`, `tests`, `student-tests`,
`contracts`, `scripts`, `examples`, `*.md`, `Makefile`, `.ruff_cache`,
`.idea`, `.python-version`, а также `**/__pycache__`, `**/*.py[cod]`,
`**/.DS_Store`: паттерн skeleton `__pycache__` без `**/` действует
только в корне, и `.pyc` хоста из `src/` попадали в образ (найдено при
проверке состава). Dockerfile копирует только
`pyproject.toml`, `uv.lock` и `src`, так что `.dockerignore` — вторая
линия защиты и способ уменьшить контекст сборки.
### 4. compose
```yaml
services:
api:
build: .
image: mtusi-messenger:lab1
restart: unless-stopped
ports:
- "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"
environment:
- APP__RUN_MODE=docker
- APP__PORT=${APP__PORT:-8080}
volumes:
- type: bind
source: ./config.toml
target: /app/config.toml
read_only: true
bind:
create_host_path: false
stop_grace_period: 10s
```
- Healthcheck не дублируется: compose берёт его из образа.
- Тег образа тот же, что в README (`mtusi-messenger:lab1`), поэтому
`docker run` из README и compose используют один образ.
- Длинная запись bind-mount и её поведение при отсутствии файла
проверены при подготовке правил (`docker.md`).
### 5. `.env.example`: параметры приложения — в формате настроек
Переменная, которая касается самого приложения, пишется в `.env` в
формате настроек (`SECTION__FIELD`), даже если её читает и compose.
Имя без секции — только у того, что приложение не читает:
```
# порт сервиса ([app] port): на нём слушает приложение, его же
# публикуют compose и make run_no_compose, на нём же healthcheck
APP__PORT=8080
# порт на 127.0.0.1 хоста, куда публикуется сервис; приложение его
# не читает
APP_OUT_PORT=8080
```
- **Кто читает `APP__PORT`.** Все три способа запуска:
- `run_dev` — pydantic-settings из `.env` на хосте;
- `run_no_compose` — из окружения контейнера (`--env-file .env`);
- compose — через `environment`.
Порт всегда задаётся в `.env`, поэтому `port` убирается из
`config_example.toml`: по приоритету (окружение > `.env` >
`config.toml`) значение в toml всё равно ни на что бы не влияло.
Поле `App.port` с дефолтом 8080 остаётся. Пример в шапке
`config_example.toml` меняется с `APP__PORT` на `APP__LOG_LEVEL`.
В локальном `config.toml` строка `port` безвредна, но её лучше убрать
руками.
- **Мосты не нужны.** Мост `SECTION__FIELD=${VAR}` остаётся для
значений, чьё имя навязано контейнером зависимости (с лабы 2 —
`DATABASE__PASSWORD=${POSTGRES_PASSWORD}`). Порт приложения
принадлежит приложению, и compose читает `${APP__PORT}` напрямую.
- **Комментарии в `.env` — только отдельными строками.** Makefile
читает `.env` через `include` (решение 6), а make, в отличие от
compose, оставляет пробел перед `# комментарий` в конце строки частью
значения.
Переменные skeleton соотносятся так, и это записывается в `REPORT.md`:
- `APP_HOST` не нужен: адрес следует из режима (`0.0.0.0` в docker);
- `APP_PORT` — это `APP__PORT` (`[app] port`), внешний порт отдельно —
`APP_OUT_PORT`;
- `APP_ENV` — это `APP__RUN_MODE`, его задают Dockerfile и compose.
Локальный `.env`, созданный из старого шаблона, содержит `APP_PORT`,
который ни на что не влияет. Его нужно обновить руками: `make
env_setup` существующий файл не перезаписывает.
### 6. Цели Makefile: два способа запуска
Новая секция `Docker targets` в стиле `run-modes.md`. Переменные — в
начале секции, а не в начале файла: верх `Makefile` принадлежит
skeleton, и свои секции при переходе в следующую лабу переносятся
целиком.
```make
# порты — из того же .env, что читает compose; без .env — 8080
-include .env
APP__PORT ?= 8080
APP_OUT_PORT ?= 8080
DC=docker compose
DOCKER_IMAGE=mtusi-messenger:lab1
DOCKER_CONTAINER=mtusi-messenger-lab1
```
Способов запуска два, и оба входят в `REPORT.md` (решение 9):
- `run_no_compose` — команды README без compose, порты из `.env`:
```make
run_no_compose: env_setup
DOCKER_BUILDKIT=1 docker build -t $(DOCKER_IMAGE) .
docker run --rm --name $(DOCKER_CONTAINER) \
-p 127.0.0.1:$(APP_OUT_PORT):$(APP__PORT) \
--env-file .env $(DOCKER_IMAGE)
```
- Порты работают так же, как в compose: `APP_OUT_PORT` снаружи,
`APP__PORT` внутри. Приложение само читает `APP__PORT` из окружения
контейнера, и healthcheck стучится туда же. С `.env` из шаблона
команда совпадает с README буква в букву
(`-p 127.0.0.1:8080:8080`).
- Разовая подмена внешнего порта — аргументом make, для обеих целей:
`make run_no_compose APP_OUT_PORT=8090`, `make run_docker
APP_OUT_PORT=8090`. Внутренний порт меняется только в `.env`:
`make run_no_compose APP__PORT=9090` поменял бы маппинг `-p`, а
приложение взяло бы `APP__PORT` из `--env-file .env`. Префикс
окружения (`APP_OUT_PORT=8090 make ...`)
не работает: присваивание из `.env` перекрывает переменную
окружения, и make экспортирует в recipe уже значение из `.env`, в
том числе для `docker compose` (проверено на GNU Make 3.81).
Аргумент make перекрывает `.env` и экспортируется. Голый
`docker compose up` без make работает по правилам compose:
окружение важнее `.env`.
- Контейнер работает на переднем плане, как в README («в другом
терминале: make test»): журнал виден сразу. make печатает команды,
поэтому в выводе видно, что именно выполняется.
- Ctrl+C: docker CLI без `-t` передаёт SIGINT процессу 1
(`--sig-proxy` по умолчанию), uvicorn останавливается штатно, как
на SIGTERM. `--rm` удаляет контейнер. Из другого терминала —
`docker stop mtusi-messenger-lab1`. Отдельная цель остановки не
нужна.
- `config.toml` не монтируется: это сценарий README «без compose и
без `config.toml`». Параметры приложения, кроме заданных в `.env`,
берутся по умолчанию. Свой `config.toml` — через compose.
- Нужен `.env` (`--env-file`): без него `docker run` падает. Поэтому
цель зависит от `env_setup`, как и `run_docker`: недостающие файлы
создаются из шаблонов, существующие не трогаются. `-include .env`
читается при разборе Makefile, раньше `env_setup`. Поэтому при
первом запуске без `.env` в `-p` идут значения по умолчанию, 8080 —
те же, что в шаблоне.
- `run_docker: env_setup` — compose: сначала `env_setup` создаёт
недостающие `.env` и `config.toml` из шаблонов (существующие не
трогает), затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`. Так
`make run_docker` работает в свежем clone без подготовки, а голый
`docker compose up` без `config.toml` по-прежнему падает с явной
ошибкой вместо каталога `config.toml/`. Для него же `stop`, `down`,
`logs`
(`$(DC) logs -f --no-log-prefix api`: без префикса `api-1 |` каждая
строка — JSON).
Оба способа собирают один образ `mtusi-messenger:lab1` и публикуют
`127.0.0.1:$(APP_OUT_PORT)` из одного `.env`. Одновременно работает
только один из них, иначе второй не получит порт.
Цели skeleton не меняются.
### 7. Как проверяем SIGTERM
1. Поднять контейнер и запустить `tests/load.py` на 20 с в фоне.
2. Через несколько секунд выполнить `time docker stop <контейнер>`.
3. Зафиксировать:
- время `docker stop` (должно быть меньше 10 с);
- `docker inspect -f '{{.State.ExitCode}}'` (не 137);
- строки журнала `Shutting down` → `Stopped API` →
`Finished server process` с метками времени;
- отчёт `load.py`: запросы после сигнала — ошибки соединения, а не
ответы.
Ожидаемый код выхода — 0. uvicorn после остановки повторно шлёт себе
SIGTERM, но ядро не доставляет процессу с PID 1 сигнал без
установленного обработчика, и Python завершается обычным образом. Если
окажется 143, это тоже корректная остановка, а не SIGKILL. Фиксируем
фактическое значение.
### 8. Сборка «из чистого clone» без коммита
```
git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t mtusi-messenger:lab1 -
```
В контекст попадают ровно те файлы, которые попали бы в clone после
коммита: отслеживаемые и новые, но не игнорируемые. `config.toml`,
`.env` и `.venv` исключаются `.gitignore`. Так проверка не требует ни
коммита, ни временного каталога. Финальная проверка настоящим
`git clone` делается перед PR, когда изменения закоммичены.
### 9. Доказательства и REPORT.md
- `evidence/container/` — текстовые выводы команд без секретов и без
текстов сообщений: сборка, `docker run` и `make test`, жизненный
цикл с рестартом, `id -u` и запись в `src/`, `docker inspect`
(healthcheck, пользователь), SIGTERM.
- `REPORT.md`:
- раздел «Запуск из чистого clone»: версии, prerequisites и оба
способа из решения 6. Для каждого: подготовка (обе цели сами
вызывают `make env_setup`), цель Makefile
и команды, которые она выполняет, ожидание готовности
(`/health/ready` или `healthy` в `docker ps`), `make test`,
остановка. Первым идёт `make run_no_compose`: он повторяет README.
Сразу за ним — `make run_docker` с портом и `config.toml`;
- часть раздела «Архитектура и решения»: процессы и хранилище,
соответствие `.env.example`, согласования с преподавателем;
- строки таблицы критериев для этого change со ссылками на файлы
`evidence/`.
Остальные TODO остаются для `student-tests` и трека.
## Risks / Trade-offs
- [Базовый образ под тегом со временем получает исправления, а мы на
старом digest] → Это осознанная цена воспроизводимости. Обновление —
правка тега и digest с пересборкой, порядок описан в `docker.md`.
- [На Linux хосте `config.toml` с правами `600` не прочитать
пользователю UID 10001] → В `docker.md` уже сказано про режим `644`.
В `REPORT.md` добавить строку о правах.
- [Docker Desktop на macOS: время остановки и сеть идут через VM] →
Замер SIGTERM показывает поведение процесса, а не сети. Числа
фиксируются вместе с окружением (версия Docker Desktop, архитектура).
- [Healthcheck раз в 10 с запускает Python-процесс в контейнере] →
Около 30 мс CPU на проверку. На замерах трека 1 это нужно учесть или
отключить через `--no-healthcheck`, и записать это в методику.
- [`restart: unless-stopped` поднимет контейнер после рестарта Docker]
→ Для учебного стенда это удобно. Остановка через `make stop`
сохраняется.
## Migration Plan
Не применимо: новые файлы инфраструктуры, данных нет. Откат — удалить
`Dockerfile` и `docker-compose.yml`, вернуть `.dockerignore`,
`.env.example`, `config_example.toml`, `Makefile` и `REPORT.md` из
git.
@@ -0,0 +1,89 @@
# Proposal
## Why
API лабы 1 работает только на хосте через `make run_dev`. Рубрика
требует собирать приложение Dockerfile из исходников и публиковать API
через `docker run` на `localhost:8080`. Это уровень «3». Уровень «4»
требует непривилегированного пользователя, закреплённых версий,
`.dockerignore`, остановки по SIGTERM не дольше 10 с и healthcheck
(`README.md`). Без контейнера нельзя показать ни сценарий защиты, ни
трек 1: там замеры идут при фиксированных лимитах CPU и памяти
контейнера.
## What Changes
- **Dockerfile.** Мультистейдж в стиле bp_proxies:
- builder ставит зависимости из `uv.lock`, runtime получает только
`.venv` и `src/`;
- базовый образ и uv закреплены версией и digest;
- процесс работает под непривилегированным пользователем, сервер —
PID 1 (`python -m src`);
- `HEALTHCHECK` ходит на `/health/ready`;
- `config.toml`, `.env` и секреты в образ не попадают.
- **`.dockerignore`.** Дополняется, чтобы в контекст сборки не уходили
`config.toml`, `.claude`, `openspec`, тесты, контракты и документация.
- **`docker-compose.yml`.** Сервис `api` в стиле bp_proxies:
- порты из `.env` (`APP_OUT_PORT` снаружи, `APP__PORT` внутри) и
публикация только на `127.0.0.1`;
- `config.toml` монтируется read-only;
- `stop_grace_period` и healthcheck.
- **`.env.example`.** Переписывается: параметры приложения — в формате
настроек (`APP__PORT`), без секции — только то, что приложение не
читает (`APP_OUT_PORT`). Как переменные из `.env.example` skeleton
соотносятся с реальными, описано в `REPORT.md`.
- **Остановка по SIGTERM за заявленный срок.** Новые соединения
отклоняются, текущие запросы дорабатывают, процесс выходит не дольше
чем за 10 с. Это проверяется замером и логами.
- **Цели `Makefile`:** два способа запуска, оба описаны в `REPORT.md`:
- `run_no_compose` — голый `docker build` + `docker run` из README
с портами из `.env`, контейнер на переднем плане;
- `run_docker` — compose, к нему `stop`, `down`, `logs`.
- **Доказательства в `evidence/` и разделы `REPORT.md`:**
- запуск из чистого clone обоими способами;
- соответствие переменных `.env.example` реальной конфигурации;
- строки таблицы критериев для контейнера — сборка и запуск, потеря
состояния после рестарта, non-root, пины, `.dockerignore`, SIGTERM,
healthcheck, логи.
- **Не входит:** собственные тесты и тест гонок (change
`student-tests`), нагрузочные эксперименты (трек 1), остальные строки
`REPORT.md`.
## Capabilities
### New Capabilities
- `container-image`: как собирается образ и что в нём есть — сборка из
чистого clone по lock, закреплённые версии, непривилегированный
пользователь, отсутствие конфигов и секретов, healthcheck.
- `container-run`: как контейнер запускается и настраивается —
`docker run` из README и compose, порты, конфигурация на старте,
потеря состояния при рестарте контейнера.
- `graceful-shutdown`: поведение процесса по SIGTERM — перестать
принимать запросы, доработать текущие и завершиться за заявленный
срок.
### Modified Capabilities
Нет. Режим `docker` (адрес `0.0.0.0`, без автоперезапуска) уже описан в
`service-configuration`, а JSON-логи в stdout — в `service-logging`.
Контейнер использует их без изменения требований.
## Impact
- **Новые файлы:** `Dockerfile`, `docker-compose.yml`, файлы в
`evidence/`.
- **Изменяемые файлы:**
- `.dockerignore` — дополнение, файл skeleton не заменяется;
- `.env.example`;
- `config_example.toml` — без `port`: порт задаётся в `.env`;
- `Makefile` — новая секция, цели skeleton не трогаются;
- `REPORT.md` — разделы запуска, конфигурации и строки критериев
контейнера;
- `AGENTS.md` — таблица команд;
- `.claude/rules/docker.md`, если при реализации уточнятся детали.
- **Код приложения** не меняется: режим `docker`, `timeout_graceful_shutdown`
и health уже есть. Правка возможна, только если замер SIGTERM покажет
проблему.
- **Окружение:** Docker Engine с BuildKit. На машине автора — Docker
Desktop 29.8 для macOS.
@@ -0,0 +1,105 @@
# Spec Delta
## Purpose
Образ сервиса: как он собирается из исходников и что в нём есть.
Сборка воспроизводима из чистого clone, версии закреплены, процесс
работает без привилегий, конфиги и секреты в образ не попадают.
## ADDED Requirements
### Requirement: Сборка из чистого clone
`docker build` в корне свежего clone SHALL собирать образ без
предварительных шагов: без `make env_setup`, без `config.toml` и `.env`.
Зависимости SHALL устанавливаться строго по `uv.lock`. Если lock не
соответствует `pyproject.toml`, сборка MUST завершаться ошибкой, а не
пересчитывать версии.
#### Scenario: Свежий clone
- **WHEN** в новом clone репозитория выполняется
`docker build -t mtusi-messenger:lab1 .`
- **THEN** образ собирается без ошибок
#### Scenario: Устаревший lock
- **WHEN** в `pyproject.toml` добавлена зависимость, а `uv.lock` не
обновлён
- **THEN** сборка завершается ошибкой проверки lock
### Requirement: Закреплённые версии
Базовые образы и инструменты сборки SHALL указываться явной версией и
digest. Плавающие теги (`latest`, `3.12-slim` и подобные) MUST NOT
использоваться.
#### Scenario: Проверка Dockerfile
- **WHEN** проверяющий читает строки `FROM` и `COPY --from` в
`Dockerfile`
- **THEN** каждая ссылка на образ содержит версию с патч-номером и
`@sha256:`
### Requirement: Непривилегированный пользователь
Процесс сервиса SHALL работать не от root. Код приложения и зависимости
MUST NOT быть доступны этому пользователю на запись.
#### Scenario: UID процесса
- **WHEN** в работающем контейнере выполняется `id -u`
- **THEN** результат не равен 0
#### Scenario: Код только на чтение
- **WHEN** пользователь контейнера пытается записать файл в каталог с
кодом приложения
- **THEN** запись отклоняется с ошибкой доступа
### Requirement: Состав образа
Образ SHALL содержать только то, что нужно для работы сервиса:
интерпретатор, зависимости времени выполнения и исходники `src/`. В
образе MUST NOT быть `config.toml`, `.env`, публичных и собственных
тестов, контрактов, файлов `.claude` и `openspec`, а также инструментов
сборки: uv и компиляторов.
#### Scenario: Нет конфигов и лишних каталогов
- **WHEN** в образе просматривается рабочий каталог приложения
- **THEN** в нём есть только исходники и окружение зависимостей, а
`config.toml` и `.env` отсутствуют
#### Scenario: Нет uv в runtime
- **WHEN** в контейнере запрашивается `uv`
- **THEN** команда не найдена
### Requirement: Сервер — основной процесс контейнера
Процессом с PID 1 SHALL быть сам сервер (`python -m src`), без
оболочки и без `uv run` между Docker и сервером. Так сигналы
остановки доходят до сервера напрямую.
#### Scenario: PID 1
- **WHEN** в работающем контейнере читается командная строка процесса 1
- **THEN** это `python -m src`
### Requirement: Healthcheck образа
Образ SHALL объявлять healthcheck, который проверяет
`GET /health/ready` на внутреннем порту сервиса. Healthcheck MUST
работать и без compose, при запуске голым `docker run`.
#### Scenario: Контейнер становится healthy
- **WHEN** контейнер запущен и сервис завершил старт
- **THEN** `docker inspect` показывает состояние здоровья `healthy`
до окончания `start_period`
#### Scenario: Healthcheck не шумит в логах
- **WHEN** healthcheck отрабатывает несколько раз
- **THEN** итоговых записей о запросах к health в журнале сервиса нет
@@ -0,0 +1,168 @@
# Spec Delta
## Purpose
Как контейнер сервиса запускается и настраивается: два способа запуска —
голый `docker run` из README (`make run_no_compose`) и compose
(`make run_docker`), публикация портов, конфигурация на старте и
поведение состояния при рестарте контейнера.
## ADDED Requirements
### Requirement: Запуск командами из README
Команды из `README.md` SHALL работать без compose и без `config.toml`:
`docker build -t mtusi-messenger:lab1 .` и
`docker run --rm --name mtusi-messenger-lab1 -p 127.0.0.1:8080:8080 --env-file .env mtusi-messenger:lab1`.
Внутри контейнера сервис SHALL работать в режиме `docker` и слушать
`0.0.0.0:8080`, не требуя дополнительных переменных.
`make run_no_compose` SHALL выполнять эти две команды, подставляя в
`-p` порты из `.env` (требование «Порты из .env»): собирать образ и
запускать контейнер на переднем плане с журналом в терминале. Перед
этим он SHALL создавать недостающие `.env` и `config.toml` из шаблонов
(`make env_setup`) и MUST NOT перезаписывать существующие. С `.env`
из шаблона команда SHALL совпадать с README. Остановка — Ctrl+C в этом
терминале или `docker stop mtusi-messenger-lab1` из другого, после
чего контейнер удаляется (`--rm`).
#### Scenario: Публичный smoke против контейнера
- **WHEN** контейнер запущен командой из README или
`make run_no_compose`, а в другом терминале выполняется `make test`
- **THEN** результат — `PASS: lab1 public API scenario`
#### Scenario: Свежий clone без .env
- **WHEN** в свежем clone без `.env` выполнен `make run_no_compose`
- **THEN** `.env` создаётся из `.env.example`, сервис стартует и
публикуется на `127.0.0.1:8080`
#### Scenario: Остановка по Ctrl+C
- **WHEN** в терминале с `make run_no_compose` нажат Ctrl+C
- **THEN** сервис штатно завершается (в журнале есть «Shutting down» и
«Finished server process»), а контейнера `mtusi-messenger-lab1` после
этого нет в `docker ps -a`
#### Scenario: Без config.toml
- **WHEN** контейнер запущен без смонтированного `config.toml`
- **THEN** сервис стартует на значениях по умолчанию
### Requirement: Запуск через compose
`make run_docker` SHALL собирать образ и поднимать сервис `api` через
`docker compose`. Перед этим он SHALL создавать недостающие `.env` и
`config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать
существующие. `make stop` SHALL останавливать сервис, `make down` —
удалять контейнер, `make logs` — показывать журнал.
#### Scenario: Штатный запуск
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** сервис отвечает на `http://localhost:8080/health/ready`, и
`make test` проходит
### Requirement: Порты из .env
Оба способа запуска, `make run_no_compose` и `make run_docker`, SHALL
брать порты из одного `.env`:
- внутренний — `APP__PORT`: параметр приложения `[app] port` в формате
настроек, приложение читает его само, на нём же работает
healthcheck;
- внешний — `APP_OUT_PORT`: порт на `127.0.0.1` хоста, приложение его
не читает.
Если переменная не задана, SHALL действовать 8080. Параметры
приложения в `.env` SHALL записываться в формате настроек
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
которые приложение не читает.
#### Scenario: Другой внешний порт
- **WHEN** в `.env` задано `APP_OUT_PORT=8090`
- **THEN** при любом из двух способов API доступно на `localhost:8090`,
а внутри контейнера сервис слушает `APP__PORT`
#### Scenario: Другой внутренний порт
- **WHEN** в `.env` задано `APP__PORT=9090`
- **THEN** при любом из двух способов сервис внутри контейнера слушает
9090, контейнер становится `healthy`, а API доступно на
`localhost:$APP_OUT_PORT`
### Requirement: Оба способа запуска описаны в REPORT.md
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать оба
способа: `make run_no_compose` (без compose, команды README) и
`make run_docker` (compose). Для каждого SHALL быть указаны подготовка
(обе цели сами вызывают `make env_setup`), команды, которые выполняет
цель Makefile, ожидание готовности, `make test` и остановка.
#### Scenario: Запуск по отчёту
- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md`
для любого из двух способов
- **THEN** `/health/ready` отвечает 200, а `make test` проходит
### Requirement: Публикация только на localhost
Порт сервиса SHALL публиковаться только на `127.0.0.1` хоста: в
README-команде, в `make run_no_compose` и в compose. Учебный стенд
MUST NOT быть доступен с других машин сети.
#### Scenario: Адрес публикации
- **WHEN** для запущенного контейнера выполняется `docker port`
- **THEN** порт опубликован на `127.0.0.1`, а не на `0.0.0.0`
### Requirement: Конфигурация на старте
`config.toml` SHALL подключаться к контейнеру при запуске, только на
чтение, и MUST NOT копироваться в образ. В compose файл SHALL
монтироваться так, чтобы его отсутствие давало явную ошибку запуска, а
не создавало на хосте каталог `config.toml/`. Секреты, которые нужны и
compose, и приложению, SHALL передаваться через `environment` (см.
`.claude/rules/settings.md`).
#### Scenario: Правка config.toml
- **WHEN** в `config.toml` изменён `[app] log_level` и контейнер
перезапущен без пересборки образа
- **THEN** сервис работает с новым уровнем логирования
#### Scenario: Нет config.toml, запуск через make
- **WHEN** `make run_docker` запускается без `config.toml`
- **THEN** `config.toml` создаётся из `config_example.toml`, и сервис
стартует
#### Scenario: Нет config.toml, compose напрямую
- **WHEN** `docker compose up` запускается без `config.toml`
- **THEN** запуск завершается ошибкой о несуществующем источнике
монтирования, и каталог `config.toml/` на хосте не появляется
### Requirement: Состояние теряется при рестарте контейнера
Перезапуск контейнера SHALL давать пустое состояние: у контейнера нет
volume для данных. Это ожидаемое поведение лабы 1, его показывают на
защите.
#### Scenario: Жизненный цикл на защите
- **WHEN** пользователь создан, отправил сообщение и прочитал его, после
чего контейнер перезапущен тем же образом
- **THEN** запрос с прежним `X-User-Id` получает 401
### Requirement: Журнал контейнера
Журнал сервиса SHALL выводиться в stdout контейнера в формате
capability `service-logging`. Между Docker и журналом MUST NOT быть
посторонних строк лаунчера (например, от `uv`).
#### Scenario: docker logs
- **WHEN** выполняется `make logs` для работающего сервиса
- **THEN** каждая строка — JSON-запись сервиса или uvicorn
@@ -0,0 +1,59 @@
# Spec Delta
## Purpose
Как сервис останавливается по SIGTERM: перестаёт принимать новые
запросы, дорабатывает текущие и завершается за заявленный срок, до
того как Docker применит SIGKILL.
## ADDED Requirements
### Requirement: Новые запросы после SIGTERM не принимаются
После получения SIGTERM сервис SHALL прекращать принимать новые
соединения и MUST NOT начинать обработку новых запросов на уже
открытых простаивающих соединениях.
#### Scenario: Нагрузка во время остановки
- **WHEN** во время непрерывной отправки сообщений контейнеру
отправлен SIGTERM
- **THEN** запросы, начатые после сигнала, завершаются ошибкой
соединения, а не ответом сервиса
### Requirement: Текущие запросы дорабатывают
Запросы, начатые до SIGTERM, SHALL получать ответ, если укладываются в
срок `[app] graceful_shutdown_seconds`. Запросы, которые не уложились,
SHALL отменяться, чтобы процесс всё равно завершился.
#### Scenario: Запрос в полёте
- **WHEN** SIGTERM приходит, пока сервис обрабатывает запрос
- **THEN** клиент получает ответ на этот запрос, после чего процесс
завершается
### Requirement: Завершение за заявленный срок
Процесс SHALL завершаться после SIGTERM не дольше чем за
`[app] graceful_shutdown_seconds` плюс время shutdown в lifespan. Это
значение MUST быть не больше 9 с: Docker применяет SIGKILL через 10 с.
Код выхода MUST NOT быть 137 (SIGKILL).
#### Scenario: docker stop
- **WHEN** выполняется `docker stop` для работающего контейнера
- **THEN** команда завершается быстрее 10 с, а код выхода контейнера не
равен 137
### Requirement: Остановка видна в журнале
Этапы остановки SHALL записываться в журнал сервиса JSON-записями с
временем: начало остановки, завершение lifespan, завершение процесса.
По меткам времени SHALL определяться длительность остановки.
#### Scenario: Журнал остановки
- **WHEN** контейнер остановлен по SIGTERM
- **THEN** в журнале по порядку есть «Shutting down», «Stopped API» и
«Finished server process», и разница их `timestamp` меньше 10 с
@@ -0,0 +1,109 @@
# Tasks
Перед правкой `Dockerfile`, `docker-compose.yml`, `.dockerignore` и
`Makefile` прочитать `.claude/rules/docker.md` и `run-modes.md`. Как
строить — `design.md`, что должно получиться — `specs/`. Перед
проверками освободить порт 8080: остановить `make run_dev` или взять
другой `APP_OUT_PORT`.
## 1. Файлы контейнера
- [x] 1.1 `Dockerfile` по design, решение 1. Перед записью сверить
digest индексов из design, решение 2 (`docker buildx imagetools
inspect <тег>`): если тег перепубликован, взять новый digest.
Проверка:
- `grep -nE '^(FROM|COPY --from)' Dockerfile` — у каждой ссылки на
образ есть патч-версия и `@sha256:`;
- сборка из tar-контекста (design, решение 8) проходит.
- [x] 1.2 Дополнить `.dockerignore` (design, решение 3). Проверка: в
образе `/app` содержит только `.venv` и `src`, а размер контекста в
выводе сборки — десятки килобайт, а не мегабайты.
- [x] 1.3 Переписать `.env.example` (design, решение 5): `APP__PORT` и
`APP_OUT_PORT`, комментарии отдельными строками. Из
`config_example.toml` убрать `port`, пример в шапке — `APP__LOG_LEVEL`.
Проверка: `docker compose config` подставляет порты из `.env`;
`make run_dev` слушает `APP__PORT` из `.env`. Локальный
`.env`, созданный раньше из старого шаблона, `make env_setup` не
трогает — обновить его руками и сказать об этом пользователю.
- [x] 1.4 `docker-compose.yml` (design, решение 4). Проверка:
`docker compose config` без ошибок, порт публикуется на `127.0.0.1`.
- [x] 1.5 Секция `Docker targets` в `Makefile`: `run_no_compose`,
`run_docker`, `stop`, `down`, `logs` (design, решение 6). Проверка:
- с `.env` из шаблона `make -n run_no_compose` печатает `docker build`
и `docker run` из README (тот же тег, имя, `127.0.0.1:8080:8080`,
`--env-file .env`); с `APP_OUT_PORT=8090` и `APP__PORT=9090` в
`.env` — `127.0.0.1:8090:9090`; без `.env` — `8080:8080`;
- `make -n run_docker` печатает `docker compose build` и `up -d`;
- `make help` и `make check` работают как раньше.
## 2. Проверка образа (спека `container-image`)
- [x] 2.1 Сборка из чистого контекста (design, решение 8) проходит.
Негативная проверка lock: временно добавить зависимость в
`pyproject.toml` без `uv lock`, убедиться, что сборка падает на
проверке lock, и вернуть файл.
- [x] 2.2 Non-root и код только на чтение: `docker run --rm
mtusi-messenger:lab1 id -u` даёт 10001, а запись в `/app/src`
отклоняется с ошибкой доступа.
- [x] 2.3 Состав образа: в `/app` только `.venv` и `src`; `config.toml`,
`.env` и `uv` отсутствуют.
- [x] 2.4 PID 1 — `python -m src` (`/proc/1/cmdline` в работающем
контейнере).
- [x] 2.5 Healthcheck: `docker inspect` показывает `healthy` до
окончания `start_period`, а в журнале нет итоговых записей о
запросах к health.
## 3. Запуск (спека `container-run`)
- [x] 3.1 Без compose: `make run_no_compose` (те же команды README), в
другом терминале `make test` — `PASS`; `docker port` показывает
`127.0.0.1:8080`. Ctrl+C в терминале цели: в журнале `Shutting down`
и `Finished server process`, контейнера нет в `docker ps -a`.
- [x] 3.2 compose: `make env_setup`, `make run_docker`, `make test` —
`PASS`. Порты (спека, «Порты из .env») для обоих способов: с
`APP_OUT_PORT=8090` и `APP__PORT=9090` в `.env` контейнер `healthy`,
а `make test BASE_URL=http://localhost:8090` — `PASS`. Потом вернуть
значения.
`make logs`: каждая строка — JSON, строк лаунчера нет.
- [x] 3.3 Без `config.toml` (временно убрать файл через `mv`):
`make run_docker` создаёт его из шаблона и поднимает сервис, а
`docker compose up -d` без make падает с ошибкой источника
монтирования, и каталог `config.toml/` не появляется; затем вернуть
файл.
- [x] 3.4 Правка `config.toml` без пересборки: временно поставить
`log_level = "WARNING"` (вызовов `debug` в коде нет, поэтому `DEBUG`
ничего бы не показал), перезапустить контейнер — записи `info`
(`Started API`, `HTTP request completed`) исчезают; вернуть `INFO`,
`docker compose restart` — тот же контейнер и образ, записи снова
есть.
- [x] 3.5 Жизненный цикл для защиты: создать двух пользователей, чат,
сообщение, прочитать историю, перезапустить контейнер тем же
образом — прежний `X-User-Id` получает 401. Вывод сохранить в
`evidence/container/`.
## 4. Остановка по SIGTERM (спека `graceful-shutdown`)
- [x] 4.1 Прогон по design, решение 7: `tests/load.py` в фоне и
`time docker stop`. Зафиксировать время остановки (меньше 10 с), код
выхода (не 137, фактическое значение записать), последовательность и
метки времени `Shutting down` → `Stopped API` → `Finished server
process`, а также ошибки соединения у запросов после сигнала. Вывод
сохранить в `evidence/container/`.
## 5. Документация и финальные проверки
- [x] 5.1 `evidence/container/`: выводы задач 2–4 без секретов и без
текстов сообщений, с датой, commit и окружением (Docker, архитектура).
- [x] 5.2 `REPORT.md` (design, решение 9): раздел «Запуск из чистого
clone» с обоими способами — `make run_no_compose` и
`make run_docker`, часть «Архитектура и решения» (процессы и хранилище,
соответствие `.env.example`, согласования с преподавателем, права на
`config.toml`), строки критериев контейнера со ссылками на
`evidence/`.
- [x] 5.3 `AGENTS.md`: цели `run_no_compose`, `run_docker`, `stop`,
`down`, `logs` в таблице команд без пометки «появится». `.claude/rules/docker.md`:
уточнения из реализации — digest индекса, один базовый образ в обоих
stage, `--no-install-project`, UID 10001, healthcheck только в
образе, проверка через tar-контекст.
- [x] 5.4 `make lint`, `make check`, `make test` против контейнера и
`openspec validate container-runtime --strict` проходят.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-09-29
@@ -0,0 +1,336 @@
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`.
Приложения ещё нет: в `src/` только пустой `__init__.py`. Уже
зафиксированы:
- раскладка кода и поток слоёв — `AGENTS.md`, «Карта кода» и
«Архитектура в двух словах»;
- правила слоёв — `.claude/rules/*.md`, их не пересказываем;
- договорённости с преподавателем — `AGENTS.md`, «Согласования с
преподавателем» (FastAPI и `config.toml`).
Стек из `uv.lock`: FastAPI 0.141, pydantic 2.13, pydantic-settings
2.15, structlog 24.4, uvicorn 0.54 с uvloop и httptools. Все
утверждения о поведении библиотек ниже проверены на этих версиях
пробными скриптами.
## Goals / Non-Goals
**Goals:**
- Публичный smoke (`make test`) проходит против `make run_dev`.
- Код разложен так, чтобы лаба 2 меняла только хранилище (`infra/`,
repo) и `get_current_user`, а не сервисы и ручки.
- На лабе 1 гонки невозможны по построению, а не только по результату
тестов.
**Non-Goals:**
- Производительность сверх разумных умолчаний: узкие места ищет трек 1
профилем, заранее их не оптимизируем и специально не закладываем.
- Ограничения на размер тела запроса, частоту запросов, объём памяти —
на лабе 1 не нужны (413, 429 и 503 по перегрузке — это трек 2,
его мы не выбрали).
- Остановка по SIGTERM за заявленный срок и её проверка — change
`container-runtime`. Здесь только передаётся параметр
`timeout_graceful_shutdown` в `uvicorn.run` (`run-modes.md`).
## Decisions
### 1. Домены и модули
Три домена лабы 1 — `user`, `chat`, `message` — с одинаковыми именами
модулей во всех слоях. Роутеры: `routers/v1/user.py` (`/users`),
`chat.py` (`/chats`), `message.py` (`/chats/{chat_id}/messages`).
Пагинация и курсор — не домен, а `src/utils/cursor.py` и общий
`<Entity>PageDTO`.
*Альтернатива:* один модуль `messenger.py` на всё. Отвергнута: в лабах
2–5 появятся `session`, `attachment` и другие, а одинаковые имена
модулей по слоям — соглашение проекта.
### 2. Хранилище в памяти и атомарность
`MemoryStore` (`src/infra/memory.py`) создаётся в lifespan и кладётся в
`app.state.store`. Все идентификаторы имеют тип `UUID`, поэтому в
таблице указано, чей это id.
| Поле | Ключ | Значение | Назначение |
|---|---|---|---|
| `users` | `user_id` | `UserFullDTO` этого пользователя | пользователь по его id |
| `user_id_by_username` | `username` | `user_id` владельца | уникальность `username` и поиск по нему |
| `chats` | `chat_id` | `ChatFullDTO` этого чата | чат по его id |
| `chats_by_user` | `user_id` участника | `list[ChatFullDTO]` — чаты, где он состоит, по `(created_at, chat_id)` | список чатов пользователя |
| `messages_by_chat` | `chat_id` | `list[MessageFullDTO]` — сообщения этого чата, по `(created_at, message_id)` | история чата |
- Чат создаёт одна repo-функция `insert_chat`, без `await` внутри. За
один вызов она кладёт чат в `chats`, добавляет его в
`chats_by_user[user_id]` каждого участника (через `insort`) и
заводит пустой `messages_by_chat[chat_id]`. Поэтому состояния
«чат есть, а истории нет» или «чат есть, но участник его не видит»
не бывает. `chats_by_user[user_id]` заводит пустым `insert_user`.
- Записи — `@dataclass(frozen=True, slots=True)`: repo отдаёт их
наружу без копирования, изменить состояние в обход repo нельзя, а
`slots` экономит память на миллионах сообщений в треке 1.
`member_ids` — `tuple[UUID, ...]`. Проверено: `from_attributes` в
pydantic читает slotted-dataclass.
- Атомарность обеспечивается инвариантом «внутри repo-функции нет
`await`» (`repo-layer.md`). Все ручки и зависимости — `async def`,
worker один, event loop один, поэтому repo-функцию не прерывает
другой запрос. Уникальность `username` — одна функция
`insert_user`: проверка словаря и вставка без `await` между ними;
при конфликте она возвращает `None`.
- Вставка в упорядоченные списки — `bisect.insort(..., key=...)` по
`(created_at, id)`. `UUID` сравнимы между собой (проверено), так что
ключ — кортеж без преобразований. Позиция курсора ищется через
`bisect_right`, без полного прохода.
*Альтернативы:*
- `asyncio.Lock` вокруг мутаций — избыточен, пока инвариант
соблюдается, и маскирует его нарушение.
- `threading.Lock` — нужен только при синхронных `def`-ручках из
threadpool, а их правило запрещает.
- `SortedList` из `sortedcontainers` — лишняя зависимость. Вставка
в конец списка (почти всегда там и оказывается новое сообщение)
стоит O(1) амортизированно, а худший случай O(n) проверит трек 1.
### 3. Время и порядок при конкурентных вставках
`created_at = utcnow()` (aware UTC, микросекунды) назначает сервис
непосредственно перед вызовом repo, без `await` между ними. В пределах
процесса запросы на запись выполняются по очереди, поэтому порядок
`(created_at, id)` совпадает с порядком вставки, пока системные часы
не идут назад. Если часы сдвинутся назад (NTP), новое сообщение может
встать перед курсором, который читатель уже получил, и тот его не
увидит. Эта семантика и ограничение попадут в `REPORT.md`.
Время сериализуется явно, в формат `YYYY-MM-DDTHH:MM:SS.ffffffZ`
(`src/utils/utc.py`), через сериализатор полей в моделях ответа. Без
этого pydantic пишет `...Z`, но при нулевых микросекундах опускает
дробную часть (проверено). Фиксированная ширина делает формат
предсказуемым для клиентов и отчётов.
*Альтернатива:* сдвиг `created_at = max(now, last + 1 мкс)` внутри чата
полностью убирает аномалию. Отложен: это логика порядка внутри repo, а
с лабы 2 порядок будет определять PostgreSQL. Вернёмся к нему, если
трек 1 или тесты покажут проблему.
### 4. Курсор
Курсор — base64url без padding от JSON
`{"v": 1, "s": <область>, "t": <created_at>, "i": <id>}`. Область:
`chat:<chat_id>` для истории, `user-chats:<user_id>` для списка чатов.
Сервис разбирает курсор (`src/utils/cursor.py`) и сверяет область с
запросом. Битая строка, неизвестная версия или чужая область дают
доменное `InvalidCursor` → 400. Repo выбирает `limit + 1` элементов:
по лишнему элементу сервис понимает, есть ли следующая страница, и
формирует `next_cursor` из последнего элемента страницы.
*Альтернативы:*
- Подпись HMAC. Не нужна: подделка курсора внутри своей области
лишь сдвигает позицию в данных, которые пользователь и так может
читать, а чужая область отсекается сверкой.
- Offset. Запрещён контрактом: при вставках он повторяет и теряет
элементы, и это вопрос защиты.
### 5. Модели запросов и валидация
- Модели в `src/api/schemas/`, `extra="forbid"`, строковые поля —
`StrictStr`. `ConfigDict(strict=True)` на модели не ставим: FastAPI
валидирует тело как Python-объект, и strict-режим отвергает UUID,
пришедший строкой (проверено: корректный `member_ids` даёт 422).
- Общий тип `NonBlankStr` (`Annotated` с валидатором) отвергает строки
из одних пробелов и не меняет значение. Длины задаются через
`Field(min_length, max_length)` и считаются в code points.
- `username` — `Field(pattern=r"^[a-z0-9_]{3,32}$")`. Regex-движок
pydantic не пропускает `"alice\n"` (проверено).
- Модель `CreateChat` проверяет только форму `member_ids`: от 1 до 100
UUID. Все правила состава — повторы, существование участников и
вызывающего в списке — проверяет `ChatService.create_chat`
(`InvalidChatMembers` → 400). Так правила списка собраны в одном
месте, а повтор не может попасть в `insert_chat` и задвоить чат в
`chats_by_user` участника, откуда бы ни пришёл вызов.
- `limit` — `Query(ge=1, le=100)`, нестрогий: в query значение
приходит строкой. `cursor` — `Query(min_length=1)`.
- Модели ответов — `from_attributes=True`, ручка делает
`Model.model_validate(dto)`.
### 6. Ошибки
`src/api/errors.py` содержит таблицу «доменное исключение → статус,
`code`» и регистрирует три обработчика.
| Источник | Ответ |
|---|---|
| `RequestValidationError` (тело, путь, query, битый JSON, не-JSON `Content-Type`) | 400 `invalid_request` |
| `StarletteHTTPException` 404 / 405 | 404 `not_found` / 405 `invalid_request` |
| доменные: `Unidentified` / `UsernameTaken` / `ChatNotFound` / `InvalidChatMembers`, `InvalidCursor` / `ServiceUnavailable` | 401 / 409 / 404 / 400 / 503 |
| любое другое `Exception` | 500 `internal_error`; traceback пишет uvicorn |
- `X-User-Id` приходит в `get_current_user` через схему безопасности
`APIKeyHeader(name="X-User-Id", scheme_name="devUser",
auto_error=False)`, а не через `Header()`. Типизированный `Header()`
уходит в валидацию, и отсутствие заголовка дало бы 400 вместо 401
(проверено: 422 у FastAPI по умолчанию). `APIKeyHeader` не
валидирует: без заголовка он отдаёт `None`, и 401 в формате контракта
бросает сервис. Заодно FastAPI объявляет схему `devUser` в
`/openapi.json` так же, как контракт, и в `/docs` появляется кнопка
Authorize (проверено: `securitySchemes` и `security` всех операций
совпадают с контрактом). Первая версия читала `request.headers`
вручную — ответы были те же, но схемы и кнопки в Swagger не было.
- Не-JSON `Content-Type` даёт 400, а не 415: 415 в контракте
необязателен, а FastAPI и так сообщает об этом как об ошибке
валидации (проверено).
- 500 формирует `ServerErrorMiddleware`, он стоит снаружи всех
middleware. Поэтому обработчик `Exception` сам берёт id из
`request.state.request_id` и ставит заголовок `X-Request-Id`.
- Непредвиденную ошибку логирует сервер, а не обработчик. После ответа
500 Starlette повторно бросает исключение именно для этого, и uvicorn
пишет `Exception in ASGI application` уровнем `error` с traceback.
Запись делается в той же задаче asyncio, что и запрос, поэтому
contextvar ещё хранит `request_id`, и логгер добавляет его в запись.
Middleware contextvar не сбрасывает: у каждого запроса в uvicorn своя
задача. Итог — две строки на такой запрос: итоговая запись со
статусом 500 и traceback от uvicorn, обе с одним `request_id`.
*Отвергнуто:* логировать в обработчике и фильтром по тексту убрать
дубль uvicorn — фильтр зависит от формулировки чужого сообщения и
молча перестаёт работать при её смене.
### 7. Request id и итоговая запись о запросе — чистое ASGI-middleware
Одно ASGI-middleware выполняет всю работу:
1. генерирует `uuid4().hex`;
2. кладёт его в `scope["state"]["request_id"]` (читается как
`request.state.request_id`) и в contextvar логгера;
3. оборачивает `send`, чтобы добавить заголовок в `http.response.start`;
4. после ответа пишет одну итоговую запись о запросе: метод, полный
шаблон пути, статус, длительность в мс.
Полный шаблон пути (`/api/v1/chats/{chat_id}`) берётся не из
`scope["route"].path`. С FastAPI 0.137 `include_router` не копирует
маршруты, а хранит роутеры деревом, и `scope["route"]` — исходный
маршрут с путём относительно своего роутера, без префикса включения
(`/chats/{chat_id}`). Middleware один раз, на первом запросе, строит
таблицу «id маршрута → полный шаблон» через публичный
`fastapi.routing.iter_route_contexts(app.routes)` (появился в 0.137.2
как замена `router.routes`) и дальше ищет в ней. Роутеры остаются как
есть, а `v1_router` задаёт версию. Ограничение: таблица однозначна,
пока каждый роутер включён один раз; маршрут, включённый под двумя
префиксами, получит один из них. Путь, не совпавший ни с одним
маршрутом, пишется как `<unmatched>`, а не присланной строкой.
*Отвергнуто* (проверено на версиях FastAPI 0.135.4–0.142.0):
- закрепить FastAPI 0.136.3, последнюю версию с полным
`scope["route"].path`, — весь курс остался бы на версии мая 2026 и
без встроенного OpenTelemetry из 0.142;
- префикс версии в каждом роутере домена;
- восстанавливать шаблон подстановкой значений `path_params` в
фактический путь — ломается, когда значение совпадает с другим
сегментом (`/api/v1/chats/v1/messages`);
- приватный `scope["fastapi"]["effective_route_context"]`.
Входящий `X-Request-Id` клиента не используется: контракт этого не
требует, а доверять чужому id в логах незачем.
*Альтернатива:* `BaseHTTPMiddleware`, как в bp_proxies. Отвергнута:
на каждый запрос он создаёт отдельную задачу и поток памяти для тела
ответа, и у него известные ограничения с contextvars. Для курса про
нагрузку — неподходящее умолчание. Выбор сделан по существу, а не
ради того, чтобы трек 1 не нашёл узкое место.
### 8. Логирование
Устройство логгера — `.claude/rules/logging.md`: перенос bp_proxies с
`CallsiteParameterAdder`, без генерации `request_id` в процессоре,
uvicorn в JSON через `log_config=None`. `user_id` кладёт в contextvar
`get_current_user`. Сервисы пишут `info` о создании пользователя, чата
и сообщения только с идентификаторами и `text_length` (спека
`service-logging`).
### 9. Настройки
`src/config/settings.py`, секция `App`:
| Поле | Тип | Дефолт |
|---|---|---|
| `run_mode` | `RunModeEnum` | `console` |
| `port` | `int` | `8080` |
| `log_level` | `str` | `INFO` |
| `graceful_shutdown_seconds` | `int`, секунды | `8` |
Хост выводится из режима и отдельным полем не хранится: console —
`127.0.0.1`, docker — `0.0.0.0`. Некорректное значение (`APP__PORT=abc`)
вызывает `ValidationError` при импорте `settings`, процесс завершается
с именем поля в сообщении (спека `service-configuration`).
`pydantic-settings` добавляется в `pyproject.toml` явной зависимостью:
код импортирует его напрямую.
### 10. Health
`/health/ready` отвечает 503 `unavailable`, если в `app.state` ещё нет
`store`. Иначе — 200. Порядок в lifespan: хранилище создаётся до
`yield`, поэтому после старта uvicorn ответ — 200.
### 11. Makefile
Новая секция ниже целей skeleton, в стиле `run-modes.md`:
- `run_dev` — `APP__RUN_MODE=console uv run python -m src`;
- `lint` — `ruff format` + `ruff check --fix`, дважды;
- `env_setup` — `test -f <файл> || cp <шаблон> <файл>`: существующие
`config.toml` и `.env` не перезаписываются. В bp_proxies там стоял
обычный `cp`, который затирал локальные значения. `cp -n` не
подходит: на macOS он завершается с кодом 1, если файл уже есть, и
`make` падает (проверено).
- `lint` проверяет только свой код: `tests/` и `scripts/` skeleton
исключены через `extend-exclude` в `[tool.ruff]`. Без этого
`ruff check --fix .` переписал бы 5 файлов публичных проверок
(проверено).
### 12. Как проверяем
Проверка идёт в два шага:
1. `make lint` и `make check` — должны пройти;
2. `make run_dev`, затем `make test` и ручной прогон негативных
сценариев из спек через `curl`: 401 без заголовка, 400 на лишнее
поле и битый JSON, 404 для постороннего, 409 на дубликат, курсор
чужого чата, `X-Request-Id` на 404 и 405.
Автоматизация этих сценариев и тест гонки — change `student-tests`.
## Risks / Trade-offs
- [Инвариант «нет `await` в repo» можно незаметно нарушить при правке]
→ Он записан в `repo-layer.md` и в docstring `memory.py`. Тест гонки
из `student-tests` ловит нарушение по результату.
- [Системные часы идут назад → порядок и курсор расходятся с порядком
вставки] → Семантика описана в решении 3 и попадёт в `REPORT.md`.
Лечение отложено до фактов.
- [Память растёт без ограничений → OOM на большой истории] → Для лабы 1
это принято. Где именно предел, выясняет трек 1.
- [Один event loop упирается в CPU → потолок throughput] → Сознательное
следствие in-memory состояния в одном процессе. Трек 1 это
измеряет.
- [`X-User-Id` легко подделать] → Так задумано контрактом лабы 1, с
лабы 2 его заменяет Bearer.
- [Битый JSON без `X-User-Id` даёт 400, а не 401] → Расхождение
согласовано с преподавателем 2026-09-26, попадёт в `REPORT.md`.
- [Reload в console-режиме стирает состояние] → Это ожидаемое
поведение in-memory хранилища. Для долгой ручной проверки можно
запустить без reload в docker-режиме (`container-runtime`).
## Migration Plan
Не применимо: это первый код приложения, данных для миграции нет. Откат
— удалить `src/` (кроме `__init__.py`) и вернуть `pyproject.toml`,
`uv.lock`, `Makefile` и `.gitignore` из git.
@@ -0,0 +1,87 @@
# Proposal
## Why
В репозитории лабы 1 есть контракт, публичный smoke и правила слоёв, но
нет приложения: `make test` падает, не найдя сервер. Нужен работающий
in-memory API по `contracts/openapi.json` и `contracts/README.md`. Это
обязательный минимум на «3» и основа, на которой строятся
`container-runtime`, `student-tests`, трек 1 и все следующие лабы.
## What Changes
- Приложение FastAPI в `src/`: слои api → service → repo → infra по
раскладке из `AGENTS.md`, запуск `python -m src`, порт 8080.
- Эндпоинты лабы 1:
- `GET /health/live`, `GET /health/ready`;
- `POST /api/v1/users`, `GET /api/v1/users/me`;
- `POST /api/v1/chats`, `GET /api/v1/chats`,
`GET /api/v1/chats/{chat_id}`;
- `POST /api/v1/chats/{chat_id}/messages`,
`GET /api/v1/chats/{chat_id}/messages`.
- Единый формат ошибок `{"error": {...}}` и заголовок `X-Request-Id`
на каждом ответе, включая 404 неизвестного пути и 500. Ошибки
валидации FastAPI переводятся в 400. От согласованных с
преподавателем расхождений используется только порядок проверок.
- Текущий пользователь выбирается через `X-User-Id` (иначе 401). Чат
доступен только участникам, остальные получают 404.
- Keyset-пагинация с непрозрачным курсором для списка чатов и истории
сообщений.
- Состояние — в памяти одного процесса: без гонок при параллельных
запросах, пропадает при рестарте.
- Настройки через pydantic-settings: окружение → `.env` →
`config.toml` → дефолты, секция `[app]`; шаблон
`config_example.toml`.
- JSON-логи structlog без содержимого сообщений, с `request_id`;
uvicorn пишет в тот же JSON.
- Цели `Makefile` для работы с приложением на хосте: `run_dev`, `lint`,
`env_setup` (существующие файлы не перезаписывает).
- Не входит в change:
- Dockerfile, compose, `.env.example`, остановка по SIGTERM,
healthcheck — change `container-runtime`;
- собственные тесты — `student-tests`;
- нагрузка — трек 1.
## Capabilities
### New Capabilities
- `api-conventions`: формат JSON и ошибок, `X-Request-Id`, формат
времени и UUID, перевод ошибок валидации в 400, ответ на неизвестный
путь и непредвиденную ошибку.
- `health`: проверки live и ready.
- `identification`: выбор текущего пользователя через `X-User-Id`
(лаба 1), порядок «идентификация → доступ к ресурсу».
- `users`: регистрация и текущий пользователь.
- `chats`: создание, получение, список чатов пользователя, членство.
- `messages`: отправка сообщения и история чата.
- `pagination`: общие правила списков — `limit`, непрозрачный
keyset-курсор, `next_cursor`.
- `data-storage`: где живёт состояние (память одного процесса), потеря
при рестарте, защита от гонок.
- `service-configuration`: источники и приоритет настроек, запуск без
файлов конфигурации, console-режим.
- `service-logging`: структурированные JSON-логи, связь с запросом
через `request_id`, что в логи не попадает.
### Modified Capabilities
Нет: спеков в проекте ещё нет.
## Impact
- **Новый код:** `src/` (`main.py`, `__main__.py`, `config/`, `api/`,
`core/`, `infra/`, `schemas/`, `utils/`), `config_example.toml`.
- **Изменяемые файлы:**
- `pyproject.toml` — `pydantic-settings` становится явной
зависимостью, сейчас он приходит транзитивно через `fastapi[all]`;
- `uv.lock`;
- `Makefile` — новая секция целей, цели skeleton не трогаются;
- `.gitignore` — добавляется `config.toml`.
- **API:** реализуется `contracts/openapi.json` 1.1.0, контракт не
меняется.
- **Не затрагиваются:** `contracts/`, `tests/`, `scripts/`, `lab.json`,
`README.md` и остальные файлы skeleton.
- **Отчёт:** `REPORT.md` заполняется позже, в него перейдут решения из
`design.md`: формат курсора, семантика конкурентных вставок,
согласованные расхождения FastAPI.
@@ -0,0 +1,145 @@
# Spec Delta
## Purpose
Общие правила HTTP API мессенджера: кодировка и формат JSON, единый
формат ошибок, заголовок `X-Request-Id`, представление времени и
идентификаторов. На них опираются все эндпоинты и клиенты, включая
публичный smoke.
## ADDED Requirements
### Requirement: JSON в UTF-8 без искажений
Ответы с телом SHALL иметь `Content-Type: application/json` в
кодировке UTF-8. Строки SHALL возвращаться клиенту в том виде, в каком
были приняты, включая кириллицу и emoji. Длины строк SHALL считаться в
Unicode code points.
#### Scenario: Unicode сохраняется
- **WHEN** клиент отправляет строковое поле `"Привет, мир 👋"`
- **THEN** в ответе и при последующем чтении это поле равно
`"Привет, мир 👋"` байт в байт после декодирования UTF-8
#### Scenario: Длина в code points
- **WHEN** клиент отправляет поле с ограничением 100 символов,
состоящее из 100 emoji
- **THEN** запрос принимается, хотя в UTF-8 это больше 100 байт
### Requirement: X-Request-Id на каждом ответе
Каждый ответ API SHALL содержать непустой заголовок `X-Request-Id`,
уникальный для запроса: успешный, с ошибкой, health, ответ на
неизвестный путь и ответ на непредвиденное исключение.
#### Scenario: Успешный ответ
- **WHEN** клиент выполняет любой успешный запрос
- **THEN** ответ содержит непустой `X-Request-Id`
#### Scenario: Ответ 500
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ 500 тоже содержит непустой `X-Request-Id`
#### Scenario: Разные запросы
- **WHEN** клиент выполняет два запроса подряд
- **THEN** значения `X-Request-Id` в ответах различаются
### Requirement: Единый формат ошибки
Любой ответ со статусом ≥ 400 SHALL иметь тело
`{"error": {"code": ..., "message": ..., "request_id": ...}}` без
других полей. `request_id` MUST совпадать с заголовком `X-Request-Id`.
`message` MUST быть непустым и MUST NOT раскрывать stack trace, пути к
файлам, имена внутренних классов, запросы к хранилищу или сам факт
существования недоступного объекта.
#### Scenario: Ошибка содержит request_id заголовка
- **WHEN** клиент получает любой ответ с ошибкой
- **THEN** тело соответствует формату, а `error.request_id` равен
значению заголовка `X-Request-Id`
#### Scenario: Нет тела FastAPI по умолчанию
- **WHEN** клиент получает ошибку валидации или 404
- **THEN** в теле нет ключа `detail`, есть только `error`
### Requirement: Соответствие статусов и кодов ошибок
Сервис SHALL использовать пары статус — `code`: 400 —
`invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 —
`conflict`, 500 — `internal_error`, 503 — `unavailable`. Метод, не
поддерживаемый путём, SHALL давать 405 с `code` `invalid_request`.
#### Scenario: Неизвестный путь
- **WHEN** клиент запрашивает `GET /api/v1/unknown`
- **THEN** ответ 404 с `code` `not_found` в формате ошибки
#### Scenario: Неподдерживаемый метод
- **WHEN** клиент выполняет `DELETE /api/v1/users`
- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки
### Requirement: Невалидный запрос даёт 400
Сервис SHALL отвечать 400 `invalid_request`, а не 422, когда тело не
является корректным JSON; когда JSON не объект там, где ожидается
объект; когда в теле есть поля, не описанные в контракте; когда тип
значения не совпадает с контрактом. Значения MUST NOT приводиться к
нужному типу неявно. Обязательные строковые поля, состоящие только из
пробельных символов, SHALL считаться невалидными.
#### Scenario: Битый JSON
- **WHEN** клиент отправляет тело `{bad` с `Content-Type: application/json`
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Лишнее поле
- **WHEN** тело запроса содержит поле, которого нет в схеме контракта
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Неверный тип без приведения
- **WHEN** строковое поле передано числом `123`
- **THEN** ответ 400, значение не превращается в строку `"123"`
#### Scenario: Строка из пробелов
- **WHEN** обязательное строковое поле равно `" "`
- **THEN** ответ 400 с `code` `invalid_request`
### Requirement: Непредвиденная ошибка без деталей
Непредвиденное исключение SHALL давать ответ 500 с `code`
`internal_error` и общим сообщением. Детали ошибки MUST попадать только
в лог сервиса.
#### Scenario: Исключение внутри обработки
- **WHEN** при обработке запроса возникает непредвиденное исключение
- **THEN** клиент получает 500 `internal_error` без stack trace, а в
логе есть запись уровня `error` с traceback и тем же `request_id`
### Requirement: Представление времени и идентификаторов
Идентификаторы и время SHALL назначаться сервером. Идентификаторы SHALL
быть UUID в виде строки в нижнем регистре. Время SHALL передаваться в
формате RFC 3339 в UTC с суффиксом `Z` и точностью до микросекунд,
одинаковой при хранении и выдаче.
#### Scenario: Формат created_at
- **WHEN** клиент получает любой объект с `created_at`
- **THEN** значение оканчивается на `Z` и разбирается как RFC 3339 UTC
#### Scenario: Формат id
- **WHEN** клиент получает любой объект с `id`
- **THEN** значение — UUID в нижнем регистре
@@ -0,0 +1,101 @@
# Spec Delta
## Purpose
Чаты — группы пользователей с фиксированным составом, в которых идёт
переписка. Capability описывает создание, получение и список чатов
текущего пользователя, а также правило «чат видят только участники».
## ADDED Requirements
### Requirement: Создание чата
`POST /api/v1/chats` SHALL принимать тело
`{"title": ..., "member_ids": [...]}` и при успехе отвечать 201 с
объектом `Chat`: `id`, `title`, `member_ids`, `created_at`, без других
полей. `member_ids` в ответе SHALL совпадать с переданным списком,
включая порядок. Чат SHALL создаваться атомарно: при любой ошибке
валидации он MUST NOT появиться ни в одном списке.
#### Scenario: Успешное создание
- **WHEN** Алиса создаёт чат с `member_ids` = [Алиса, Боб]
- **THEN** ответ 201, `member_ids` равен [Алиса, Боб], `id` — новый UUID
### Requirement: Валидация чата
`title` SHALL содержать 1–100 Unicode code points и MUST NOT состоять
только из пробельных символов. `member_ids` SHALL содержать от 1 до 100
UUID без повторов; каждый MUST быть идентификатором существующего
пользователя, и текущий пользователь MUST входить в список. Нарушение
любого условия SHALL давать 400 `invalid_request`.
#### Scenario: Вызывающего нет в списке
- **WHEN** Алиса создаёт чат с `member_ids` = [Боб]
- **THEN** ответ 400
#### Scenario: Повтор участника
- **WHEN** `member_ids` = [Алиса, Алиса]
- **THEN** ответ 400
#### Scenario: Неизвестный участник
- **WHEN** `member_ids` содержит UUID, которого нет среди пользователей
- **THEN** ответ 400
#### Scenario: Пустой список
- **WHEN** `member_ids` = []
- **THEN** ответ 400
### Requirement: Получение чата
`GET /api/v1/chats/{chat_id}` SHALL отвечать 200 с объектом `Chat`,
если текущий пользователь — участник. Если чата нет или пользователь
не участник, сервис SHALL отвечать одинаковым 404 `not_found` и MUST
NOT использовать 403. `chat_id`, не являющийся UUID, SHALL давать 400.
#### Scenario: Участник
- **WHEN** Боб запрашивает чат, в котором состоит
- **THEN** ответ 200 с этим чатом
#### Scenario: Посторонний
- **WHEN** Ева запрашивает существующий чат Алисы и Боба
- **THEN** ответ 404 с `code` `not_found`, неотличимый от ответа на
несуществующий чат
#### Scenario: Неверный chat_id
- **WHEN** `chat_id` равен `nope`
- **THEN** ответ 400
### Requirement: Список чатов пользователя
`GET /api/v1/chats` SHALL возвращать только чаты, в которых состоит
текущий пользователь, в порядке `(created_at, id)` по возрастанию, с
постраничным выводом по capability `pagination`.
#### Scenario: Участник видит чат
- **WHEN** Боб запрашивает список чатов после того, как Алиса создала
чат с ним
- **THEN** этот чат есть в списке
#### Scenario: Посторонний не видит чат
- **WHEN** Ева запрашивает список чатов
- **THEN** чата Алисы и Боба в нём нет
### Requirement: Состав чата неизменен
После создания состав участников чата SHALL оставаться неизменным: API
лабы 1 не предоставляет операций добавления и удаления участников.
#### Scenario: Повторное чтение
- **WHEN** участник читает чат в разное время
- **THEN** `member_ids` каждый раз одинаков
@@ -0,0 +1,53 @@
# Spec Delta
## Purpose
Где живёт состояние мессенджера на лабе 1 и какие гарантии оно даёт:
память одного процесса, потеря при рестарте, защита от гонок при
параллельных запросах.
## ADDED Requirements
### Requirement: Состояние только в памяти одного процесса
Пользователи, чаты и сообщения SHALL храниться только в памяти одного
процесса сервиса. Сервис MUST NOT использовать базы данных, Redis,
файлы состояния и внешние сервисы. Все запросы экземпляра SHALL
обслуживаться одним общим состоянием, без нескольких worker-процессов
с независимой памятью.
#### Scenario: Созданное видно сразу
- **WHEN** клиент создал пользователя и следующим запросом использует
его `id` в `X-User-Id`
- **THEN** пользователь найден
### Requirement: Потеря состояния при рестарте
После перезапуска процесса состояние SHALL быть пустым. Это ожидаемое
поведение лабы 1.
#### Scenario: Прежний пользователь после рестарта
- **WHEN** сервис перезапущен и клиент использует `X-User-Id`,
созданный до рестарта
- **THEN** ответ 401
### Requirement: Параллельные запросы не повреждают состояние
Параллельные запросы MUST NOT терять, дублировать или повреждать
записи. Проверки с последующей записью (уникальность `username`)
SHALL выполняться атомарно.
#### Scenario: 100 сообщений от 10 клиентов
- **WHEN** 10 клиентов одновременно отправляют по 10 сообщений в один
чат
- **THEN** получено 100 ответов 201, а полный обход истории возвращает
ровно 100 сообщений с уникальными `id`
#### Scenario: Гонка за username
- **WHEN** несколько клиентов одновременно регистрируют одинаковый
`username`
- **THEN** создан ровно один пользователь
@@ -0,0 +1,49 @@
# Spec Delta
## Purpose
Проверки жизни и готовности сервиса для оператора, healthcheck
контейнера и публичного smoke: жив ли процесс и можно ли направлять на
него трафик.
## ADDED Requirements
### Requirement: Liveness
`GET /health/live` SHALL отвечать 200 с телом `{"status": "ok"}`, пока
процесс обслуживает HTTP. Проверка MUST NOT требовать идентификации и
MUST NOT зависеть от состояния хранилища.
#### Scenario: Процесс жив
- **WHEN** клиент запрашивает `GET /health/live` без заголовков
- **THEN** ответ 200, тело `{"status": "ok"}`, есть `X-Request-Id`
### Requirement: Readiness
`GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`,
когда сервис может безопасно обслуживать обязательные запросы, и 503 с
`code` `unavailable` в формате ошибки, когда не может. На лабе 1
критичная зависимость одна — хранилище в памяти процесса, готовое после
завершения запуска. Проверка MUST NOT требовать идентификации.
#### Scenario: Сервис запущен
- **WHEN** запуск сервиса завершён и клиент запрашивает `GET /health/ready`
- **THEN** ответ 200, тело `{"status": "ok"}`
#### Scenario: Хранилище не готово
- **WHEN** хранилище ещё не инициализировано
- **THEN** ответ 503 с `code` `unavailable` в формате ошибки
### Requirement: Health вне версии API и без идентификации
Эндпоинты health SHALL находиться вне префикса `/api/v1` и SHALL
игнорировать `X-User-Id`.
#### Scenario: Неизвестный X-User-Id
- **WHEN** клиент запрашивает health с `X-User-Id` несуществующего
пользователя
- **THEN** ответ 200, а не 401
@@ -0,0 +1,87 @@
# Spec Delta
## Purpose
Выбор текущего пользователя на лабе 1 через заголовок `X-User-Id` и
порядок проверок «идентификация → доступ к ресурсу». Это учебная
идентификация, а не аутентификация: любой клиент может выдать себя за
другого. С лабы 2 её заменяет Bearer-сессия.
## ADDED Requirements
### Requirement: Защищённые эндпоинты требуют X-User-Id
Все эндпоинты, кроме `POST /api/v1/users` и health, SHALL требовать
заголовок `X-User-Id` с UUID существующего пользователя. Этот
пользователь SHALL считаться текущим для запроса.
#### Scenario: Корректный заголовок
- **WHEN** клиент вызывает `GET /api/v1/users/me` с `X-User-Id`
существующего пользователя
- **THEN** ответ 200 с этим пользователем
### Requirement: Отказ в идентификации — 401
Сервис SHALL отвечать 401 с `code` `unauthorized`, когда заголовок
`X-User-Id` отсутствует, не является UUID или указывает на
несуществующего пользователя. Эти три случая MUST давать одинаковый
ответ и MUST NOT давать 400.
#### Scenario: Нет заголовка
- **WHEN** клиент вызывает `GET /api/v1/users/me` без `X-User-Id`
- **THEN** ответ 401 с `code` `unauthorized`
#### Scenario: Не UUID
- **WHEN** `X-User-Id` равен `not-a-uuid`
- **THEN** ответ 401 с `code` `unauthorized`
#### Scenario: Неизвестный пользователь
- **WHEN** `X-User-Id` — корректный UUID, но такого пользователя нет
- **THEN** ответ 401 с `code` `unauthorized`
### Requirement: Идентификация раньше доступа и валидации
Идентификация SHALL проверяться раньше доступа к конкретному ресурсу и
раньше проверки пути, query и полей тела. Исключение, согласованное с
преподавателем 2026-09-26: тело, которое не разбирается как JSON,
отклоняется с 400 до идентификации.
#### Scenario: Чужой чат без заголовка
- **WHEN** клиент без `X-User-Id` запрашивает существующий чат
- **THEN** ответ 401, а не 404
#### Scenario: Невалидное поле без заголовка
- **WHEN** клиент без `X-User-Id` отправляет сообщение с `{"text": ""}`
- **THEN** ответ 401, а не 400
#### Scenario: Битый JSON без заголовка
- **WHEN** клиент без `X-User-Id` отправляет тело `{bad`
- **THEN** ответ 400 с `code` `invalid_request`
### Requirement: Схема идентификации в документации API
Документация, которую отдаёт сервис (`/openapi.json` и `/docs`), SHALL
объявлять схему `devUser` так же, как `contracts/openapi.json`: `apiKey`
в заголовке `X-User-Id`. Защищённые операции SHALL ссылаться на неё,
публичные (`POST /api/v1/users`, health) MUST NOT. Объявление схемы
MUST NOT менять ответы: без заголовка по-прежнему 401, а не 400 или 403.
#### Scenario: Кнопка Authorize в Swagger
- **WHEN** разработчик открывает `/docs`
- **THEN** доступна кнопка Authorize с полем `X-User-Id`, и введённое
значение уходит заголовком в защищённые запросы
#### Scenario: Схема в openapi.json
- **WHEN** клиент запрашивает `/openapi.json`
- **THEN** `components.securitySchemes.devUser` совпадает с контрактом,
у `GET /api/v1/users/me` `security` равно `[{"devUser": []}]`, а у
`POST /api/v1/users` `security` нет
@@ -0,0 +1,84 @@
# Spec Delta
## Purpose
Текстовые сообщения в чате: отправка от имени текущего пользователя и
чтение истории чата его участниками в порядке `(created_at, id)`.
## ADDED Requirements
### Requirement: Отправка сообщения
`POST /api/v1/chats/{chat_id}/messages` SHALL принимать тело
`{"text": ...}` и при успехе отвечать 201 с объектом `Message`: `id`,
`chat_id`, `sender_id`, `text`, `created_at`, без других полей.
`sender_id` SHALL быть текущим пользователем, `text` — совпадать с
отправленным.
#### Scenario: Участник отправляет сообщение
- **WHEN** Алиса отправляет `"Привет, мир 👋"` в свой чат
- **THEN** ответ 201, `sender_id` — Алиса, `chat_id` — этот чат, `text`
равен `"Привет, мир 👋"`
### Requirement: Валидация текста
`text` SHALL содержать от 1 до 4000 Unicode code points и MUST NOT
состоять только из пробельных символов. Поле `sender_id` в теле MUST NOT
приниматься. Нарушения SHALL давать 400 `invalid_request`.
#### Scenario: Пустой текст
- **WHEN** участник отправляет `{"text": ""}`
- **THEN** ответ 400
#### Scenario: Граница длины
- **WHEN** текст из 4000 code points, затем из 4001
- **THEN** первый запрос даёт 201, второй — 400
#### Scenario: Попытка подменить отправителя
- **WHEN** тело содержит `sender_id` другого пользователя
- **THEN** ответ 400, сообщение не создаётся
### Requirement: Писать и читать могут только участники
Отправка и чтение истории SHALL быть доступны только участникам чата.
Посторонний и запрос к несуществующему чату SHALL получать одинаковый
404 `not_found`; сообщение при этом MUST NOT создаваться.
#### Scenario: Посторонний пишет
- **WHEN** Ева отправляет сообщение в чат Алисы и Боба
- **THEN** ответ 404, в истории чата новых сообщений нет
#### Scenario: Посторонний читает
- **WHEN** Ева запрашивает историю чата Алисы и Боба
- **THEN** ответ 404
### Requirement: История чата
`GET /api/v1/chats/{chat_id}/messages` SHALL возвращать сообщения чата
в порядке `(created_at, id)` по возрастанию, с постраничным выводом по
capability `pagination`. Любой участник SHALL видеть все сообщения
чата, в том числе чужие.
#### Scenario: Два участника, две страницы
- **WHEN** Алиса и Боб отправили по сообщению, и Боб читает историю с
`limit=1`, а затем продолжает по курсору
- **THEN** первая страница содержит одно сообщение и непустой
`next_cursor`, вторая — второе сообщение и `next_cursor` null, а
порядок совпадает с `(created_at, id)`
### Requirement: Подтверждённое сообщение сразу видно
Сообщение, на которое сервис ответил 201, SHALL присутствовать в
любом следующем чтении истории этого чата.
#### Scenario: Чтение после записи
- **WHEN** участник получил 201 на отправку и сразу читает историю
- **THEN** сообщение есть в истории
@@ -0,0 +1,74 @@
# Spec Delta
## Purpose
Общие правила постраничных списков (чаты пользователя и история чата):
параметр `limit`, непрозрачный keyset-курсор и `next_cursor`. Обход
списка по курсору не теряет и не повторяет элементы.
## ADDED Requirements
### Requirement: Параметр limit
`limit` SHALL быть целым числом от 1 до 100, по умолчанию 50. Другие
значения SHALL давать 400 `invalid_request`.
#### Scenario: Ноль
- **WHEN** клиент запрашивает список с `limit=0`
- **THEN** ответ 400
#### Scenario: Больше максимума и не число
- **WHEN** `limit=101` или `limit=abc`
- **THEN** ответ 400
#### Scenario: По умолчанию
- **WHEN** `limit` не передан и в списке 60 элементов
- **THEN** страница содержит 50 элементов
### Requirement: Форма страницы и next_cursor
Ответ списка SHALL иметь вид `{"items": [...], "next_cursor": ...}`.
`next_cursor` SHALL быть непустой строкой, если на момент чтения после
последнего элемента страницы есть ещё элементы, и null — если нет,
в том числе когда страница содержит ровно `limit` элементов и больше
ничего нет.
#### Scenario: Последняя полная страница
- **WHEN** в списке ровно 2 элемента и клиент запрашивает `limit=2`
- **THEN** страница содержит оба элемента и `next_cursor` null
### Requirement: Порядок и продолжение по курсору
Элементы SHALL упорядочиваться по `(created_at, id)` по возрастанию, где
`id` сравнивается как значение UUID. Запрос с `cursor` SHALL возвращать
элементы строго после последнего элемента предыдущей страницы. При
обходе неизменного списка элементы MUST NOT теряться и повторяться.
`limit` SHALL разрешено менять между страницами.
#### Scenario: Полный обход
- **WHEN** клиент обходит список из 7 элементов страницами по 3, затем
по 2
- **THEN** объединение страниц содержит все 7 элементов ровно по одному
разу в правильном порядке
### Requirement: Курсор непрозрачен и привязан к списку
Курсор SHALL быть непрозрачной для клиента строкой. Курсор, полученный
для другого чата, для списка чатов вместо истории или наоборот, либо
повреждённая строка SHALL давать 400 `invalid_request`.
#### Scenario: Курсор другого чата
- **WHEN** участник двух чатов передаёт в историю чата B курсор,
полученный в чате A
- **THEN** ответ 400
#### Scenario: Повреждённый курсор
- **WHEN** `cursor` равен произвольной строке `garbage`
- **THEN** ответ 400
@@ -0,0 +1,84 @@
# Spec Delta
## Purpose
Как оператор настраивает сервис: источники значений и их приоритет,
имена параметров по секциям, запуск без файлов конфигурации и режимы
запуска console / docker.
## ADDED Requirements
### Requirement: Источники настроек и приоритет
Сервис SHALL читать настройки из переменных окружения процесса, файла
`.env`, файла `config.toml` и встроенных значений по умолчанию, в этом
порядке убывания приоритета. Отсутствующий файл SHALL пропускаться без
ошибки.
#### Scenario: Окружение важнее файла
- **WHEN** `[app] log_level` в `config.toml` равен `DEBUG`, а процесс
запущен с `APP__LOG_LEVEL=WARNING`
- **THEN** действует уровень `WARNING`
#### Scenario: Запуск без файлов
- **WHEN** в каталоге нет ни `.env`, ни `config.toml`
- **THEN** сервис стартует на значениях по умолчанию и слушает порт 8080
### Requirement: Параметры по секциям
Каждый параметр SHALL принадлежать секции: в `config.toml` — таблица
`[section]`, в окружении — имя `SECTION__FIELD` без учёта регистра.
Переменные без префикса секции MUST NOT влиять на сервис.
#### Scenario: Имя с секцией
- **WHEN** процесс запущен с `APP__PORT=9090`
- **THEN** сервис слушает порт 9090
#### Scenario: Имя без секции
- **WHEN** процесс запущен с `APP_PORT=9090` и без `APP__PORT`
- **THEN** сервис слушает порт по умолчанию
### Requirement: Некорректное значение останавливает запуск
Значение, которое не приводится к типу параметра, SHALL останавливать
запуск с сообщением, где названо поле. Сервис MUST NOT молча
подставлять значение по умолчанию вместо некорректного.
#### Scenario: Порт не число
- **WHEN** процесс запущен с `APP__PORT=abc`
- **THEN** запуск завершается ошибкой, в выводе упомянут `port`
### Requirement: Режимы запуска
Режим SHALL задаваться параметром `APP__RUN_MODE` со значениями
`console` и `docker`, по умолчанию `console`. В режиме `console` сервис
SHALL слушать только `127.0.0.1` и перезапускаться при изменении
исходного кода. В режиме `docker` сервис SHALL слушать `0.0.0.0` без
автоперезапуска.
#### Scenario: Console по умолчанию
- **WHEN** сервис запущен командой `python -m src` без `APP__RUN_MODE`
- **THEN** он доступен на `127.0.0.1:8080` и недоступен с других
интерфейсов
#### Scenario: Docker
- **WHEN** сервис запущен с `APP__RUN_MODE=docker`
- **THEN** он слушает `0.0.0.0:8080`
### Requirement: Файлы с локальными значениями не в git
`config.toml` и `.env` SHALL игнорироваться git. В репозитории SHALL
храниться шаблон `config_example.toml` без секретов.
#### Scenario: Проверка ignore
- **WHEN** в корне создан `config.toml`
- **THEN** `git status` его не показывает, а `config_example.toml`
отслеживается
@@ -0,0 +1,78 @@
# Spec Delta
## Purpose
Журнал сервиса для диагностики и защиты: структурированные JSON-записи
в stdout, связь каждой записи с HTTP-запросом через `request_id` и
запрет на содержимое сообщений и личные данные в логах.
## ADDED Requirements
### Requirement: JSON-записи в stdout
Сервис SHALL писать журнал в stdout, по одному JSON-объекту на строку.
Каждая запись SHALL содержать `timestamp` (ISO 8601 UTC), `level` и
`event`. Записи HTTP-сервера о запуске и остановке SHALL идти в том же
формате. Уровень подробности SHALL задаваться параметром
`[app] log_level`.
#### Scenario: Каждая строка — JSON
- **WHEN** сервис запускается, обслуживает запросы и останавливается
- **THEN** каждая строка stdout разбирается как JSON-объект с
`timestamp`, `level` и `event`
#### Scenario: Уровень из настроек
- **WHEN** `APP__LOG_LEVEL=WARNING`
- **THEN** записей уровней `debug` и `info` от кода сервиса нет
### Requirement: Связь записей с запросом
Каждая запись, сделанная при обработке запроса, SHALL содержать
`request_id`, равный заголовку `X-Request-Id` ответа, и `user_id`,
если пользователь идентифицирован.
#### Scenario: Поиск по request_id
- **WHEN** клиент получил ответ с `X-Request-Id` = R
- **THEN** все записи этого запроса содержат `request_id` = R
### Requirement: Одна итоговая запись на запрос
Для каждого запроса, кроме health, сервис SHALL писать одну итоговую
запись с методом, шаблоном пути, статусом и длительностью обработки.
#### Scenario: Запрос к API
- **WHEN** клиент выполняет `GET /api/v1/chats/{id}`
- **THEN** есть итоговая запись с путём `/api/v1/chats/{chat_id}`,
статусом и длительностью
#### Scenario: Health не шумит
- **WHEN** healthcheck вызывает `/health/ready` каждые несколько секунд
- **THEN** итоговых записей для этих запросов нет
### Requirement: Без содержимого сообщений и личных данных
Записи MUST NOT содержать текст сообщений, `display_name`, названия
чатов, значения `username`, тела запросов и ответов. Для сообщений
допускаются идентификаторы и длина текста.
#### Scenario: Отправка сообщения
- **WHEN** участник отправляет сообщение с текстом T
- **THEN** ни одна запись журнала не содержит T, а запись о создании
сообщения содержит его `id`, `chat_id` и длину текста
### Requirement: Непредвиденные ошибки в журнале
Непредвиденное исключение SHALL записываться с уровнем `error`,
traceback и `request_id` запроса.
#### Scenario: Исключение в обработчике
- **WHEN** обработка запроса падает с непредвиденным исключением
- **THEN** в журнале есть запись `error` с traceback и `request_id`
ответа 500
@@ -0,0 +1,84 @@
# Spec Delta
## Purpose
Регистрация пользователей мессенджера и получение текущего
пользователя. Пользователь — участник чатов и отправитель сообщений.
## ADDED Requirements
### Requirement: Регистрация пользователя
`POST /api/v1/users` SHALL быть публичным и принимать тело
`{"username": ..., "display_name": ...}`. При успехе сервис SHALL
отвечать 201 с объектом `User`: `id`, `username`, `display_name`,
`created_at`, без других полей. `id` и `created_at` назначает сервер.
#### Scenario: Успешная регистрация
- **WHEN** клиент отправляет `{"username": "alice", "display_name": "Алиса"}`
- **THEN** ответ 201, `username` и `display_name` совпадают с
отправленными, `id` — новый UUID
### Requirement: Формат username
`username` SHALL целиком соответствовать `^[a-z0-9_]{3,32}$`. Иначе
сервис SHALL отвечать 400 `invalid_request`.
#### Scenario: Заглавные буквы
- **WHEN** `username` равен `Alice`
- **THEN** ответ 400
#### Scenario: Слишком короткий
- **WHEN** `username` равен `ab`
- **THEN** ответ 400
#### Scenario: Перевод строки в конце
- **WHEN** `username` равен `"alice\n"`
- **THEN** ответ 400
### Requirement: Формат display_name
`display_name` SHALL содержать от 1 до 100 Unicode code points и MUST
NOT состоять только из пробельных символов. Значение SHALL сохраняться
без изменений, в том числе без обрезки пробелов.
#### Scenario: Граница длины
- **WHEN** `display_name` из 100 code points, затем из 101
- **THEN** первый запрос даёт 201, второй — 400
#### Scenario: Только пробелы
- **WHEN** `display_name` равен `" "`
- **THEN** ответ 400
### Requirement: Уникальность username
`username` SHALL быть уникальным. Повторная регистрация занятого
`username` SHALL давать 409 с `code` `conflict`. При одновременной
регистрации одного `username` несколькими клиентами MUST успешно
завершиться ровно одна.
#### Scenario: Повтор username
- **WHEN** клиент повторно регистрирует уже занятый `username`
- **THEN** ответ 409 с `code` `conflict`
#### Scenario: Одновременная регистрация
- **WHEN** 10 клиентов одновременно регистрируют одинаковый `username`
- **THEN** ровно один получает 201, остальные — 409
### Requirement: Текущий пользователь
`GET /api/v1/users/me` SHALL возвращать 200 с объектом `User` текущего
пользователя (capability `identification`).
#### Scenario: Совпадает с регистрацией
- **WHEN** пользователь запрашивает `GET /api/v1/users/me` со своим `X-User-Id`
- **THEN** тело ответа равно телу ответа на его регистрацию
@@ -0,0 +1,149 @@
# Tasks
Перед созданием первого файла слоя прочитать его правило из
`.claude/rules/` (таблица в `AGENTS.md`): при создании файла через
Write правило само не подгружается. Как строить — `design.md`, что
должно получиться — `specs/`.
## 1. Окружение и шаблоны
- [x] 1.1 Добавить `pydantic-settings` явной зависимостью в
`pyproject.toml` и обновить `uv.lock` (`uv lock`, `uv sync`); проверка:
`uv run python -c "import pydantic_settings"` без ошибок, версия в
`uv.lock` не ниже 2.15.
- [x] 1.2 Добавить `config.toml` в `.gitignore`; проверка: после
создания `config.toml` его нет в `git status`.
- [x] 1.3 Создать `config_example.toml` с секцией `[app]` (поля из
design, решение 9) без секретов; проверка: файл разбирается
`python3 -c "import tomllib; tomllib.load(open('config_example.toml','rb'))"`.
- [x] 1.4 Добавить в `Makefile` секцию своих целей ниже целей skeleton:
`run_dev`, `lint`, `env_setup` без перезаписи существующих файлов
(`run-modes.md`, design, решение 11). Проверка: `make env_setup` дважды подряд не меняет уже
созданный `config.toml`, а `make check` и `make help` работают как
раньше.
## 2. Настройки, логгер, утилиты
- [x] 2.1 `src/schemas/enums/settings.py` с `RunModeEnum` и
`src/config/settings.py` с секцией `App`, приоритетом источников и
экземпляром `settings` (`settings.md`). Проверка:
- `uv run python -c "from src.config import settings; print(settings.app.port)"`
печатает 8080 без `config.toml` и `.env`;
- с `APP__PORT=9090` печатает 9090;
- с `APP_PORT=9090` печатает 8080;
- с `APP__PORT=abc` падает с упоминанием `port`.
- [x] 2.2 `src/infra/logger.py` по разделу «Устройство» в `logging.md`.
Проверка: `uv run python -c` с вызовом
`get_logger().bind(module="t").info("Test")` печатает одну JSON-строку
с `timestamp`, `level`, `event`, `filename`, `func_name`, `lineno`;
`lineno` указывает на место вызова, а не внутрь `logger.py`.
- [x] 2.3 `src/utils/constants.py` (лимиты контракта, размер страницы,
префиксы путей) и `src/utils/utc.py` (`utcnow()`, форматирование
`...ffffffZ`). Проверка: время с нулевыми микросекундами
форматируется как `...00.000000Z`.
- [x] 2.4 `src/utils/cursor.py` — кодирование и разбор курсора с
областью (design, решение 4). Проверка через `uv run python -c`:
`encode` → `decode` возвращает тот же ключ; `garbage`, чужая область
и неизвестная версия дают исключение разбора.
## 3. Хранилище и доменные слои
- [x] 3.1 DTO в `src/schemas/dataclasses/` (`user`, `chat`, `message`,
страницы): `frozen=True, slots=True`, экспорт в `__init__.py`
(`dto.md`, design, решение 2). Проверка: импорт
`from src.schemas import dataclasses` без ошибок; попытка изменить
поле записи бросает `FrozenInstanceError`.
- [x] 3.2 `src/infra/memory.py` с `MemoryStore` (структуры из design,
решение 2; в docstring — инвариант «нет `await` в repo»). Проверка:
импорт и создание пустого хранилища без ошибок.
- [x] 3.3 Доменные исключения в `src/core/exceptions/` (`Unidentified`,
`UsernameTaken`, `ChatNotFound`, `InvalidChatMembers`,
`InvalidCursor`) с реэкспортом. Проверка: импорт из
`src.core.exceptions`.
- [x] 3.4 Repo `src/core/repos/{user,chat,message}.py` (`repo-layer.md`):
- атомарная `insert_user`, возвращающая `None` при конфликте;
- выборки по id;
- keyset-страницы с `limit + 1` через `bisect`.
Проверка: `grep -n "await" src/core/repos/*.py` находит только
`async def`-объявления, без `await` в телах функций.
- [x] 3.5 Сервисы `src/core/services/{user,chat,message}.py`
(`service-layer.md`, `logging.md`): id и время, проверка членства,
разбор курсора, `next_cursor`, логи без содержимого. Проверка:
`uv run python -c` сценарий на `MemoryStore` — создать двух
пользователей, чат, три сообщения, пройти историю по `limit=2` и
получить все три без повторов.
## 4. HTTP-слой
- [x] 4.1 Модели `src/api/schemas/{user,chat,message,common}.py`:
- `extra="forbid"`, `StrictStr`, `NonBlankStr`;
- pattern для `username`; у `member_ids` только форма (1–100 UUID),
повторы проверяет сервис;
- сериализатор времени;
- `from_attributes` у моделей ответа.
Всё по `api-contract.md` и design, решение 5. Проверка: JSON-схемы
моделей ответа совпадают по полям со схемами `contracts/openapi.json`
(`User`, `Chat`, `Message`, `ChatPage`, `MessagePage`, `Error`,
`Health`).
- [x] 4.2 `src/api/errors.py`: таблица исключений, обработчики
`RequestValidationError`, `StarletteHTTPException` и `Exception`;
последний сам ставит `X-Request-Id` и не логирует — traceback пишет
uvicorn (design, решение 6). Проверка — в
задаче 5.2.
- [x] 4.3 ASGI-middleware request id и итоговой записи о запросе в
`src/api/middlewares/` (design, решение 7); health из итоговой записи
исключён. Проверка — в задачах 5.2 и 5.4.
- [x] 4.4 `src/api/dependencies.py`:
- `get_current_user` читает `request.headers` и ставит contextvar
`user_id`;
- фабрики сервисов из `request.app.state.store`.
Проверка — в задаче 5.2.
- [x] 4.5 Роутеры `routers/health.py` и
`routers/v1/{user,chat,message}.py`, сборка в `routers/v1/__init__.py`
(`api-layer.md`). Проверка: `/openapi.json` приложения перечисляет
все пути из `contracts/openapi.json` с теми же методами.
- [x] 4.6 `src/main.py` (app, lifespan с `MemoryStore`, middleware,
обработчики, роутеры, `main()` с `uvicorn.run(...,
log_config=None, access_log=False, timeout_graceful_shutdown=...)`) и
`src/__main__.py`; `src/__init__.py` остаётся пустым
(`run-modes.md`). Проверка: `make run_dev` поднимает сервер на
`127.0.0.1:8080`, `curl -i localhost:8080/health/ready` отвечает 200
с `X-Request-Id`.
- [x] 4.7 Схема `devUser` в документации: `X-User-Id` приходит в
`get_current_user` через `APIKeyHeader(auto_error=False)` (design,
решение 6; спека `identification`). Проверка:
`components.securitySchemes` в `/openapi.json` совпадает с контрактом,
`security` всех операций — тоже; в `/docs` есть кнопка Authorize; без
заголовка, с `not-a-uuid` и с неизвестным UUID по-прежнему 401;
`make test` проходит.
## 5. Проверка целиком
- [x] 5.1 `make lint` без замечаний и `make check` проходит.
- [x] 5.2 Публичный smoke: `make run_dev`, затем `make test`, результат
`PASS: lab1 public API scenario`. Порт 8080 сейчас занят контейнером
`domains-api-1` из другого проекта. Если он всё ещё запущен:
`APP__PORT=8081 make run_dev` и
`make test BASE_URL=http://localhost:8081`.
- [x] 5.3 Ручной прогон негативных сценариев из спек через `curl`, у
каждого проверить статус, `code` и совпадение `request_id` с
`X-Request-Id`:
- 401 без `X-User-Id`, с `not-a-uuid` и с неизвестным UUID;
- 400 на лишнее поле, на битый JSON, на `{"text": " "}`, на
`limit=0` и на курсор чужого чата;
- 404 для постороннего в чат и в историю;
- 409 на дубликат `username`;
- 404 на неизвестный путь, 405 на `DELETE /api/v1/users`.
- [x] 5.4 Логи: во время прогона 5.2–5.3 каждая строка stdout — JSON;
в записях есть `request_id`, равный `X-Request-Id`; текст сообщений,
`display_name` и `title` в stdout не встречаются (проверить `grep` по
отправленным строкам); строки uvicorn о старте и остановке тоже
JSON; итоговая запись содержит полный шаблон пути
(`/api/v1/chats/{chat_id}`); непредвиденная ошибка даёт 500 в
формате контракта и одну запись traceback от uvicorn с тем же
`request_id`.
- [x] 5.5 Потеря состояния: перезапустить `make run_dev` и повторить
`GET /api/v1/users/me` с прежним `X-User-Id` — ответ 401.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-09-29
@@ -0,0 +1,235 @@
# Design
## Context
Мотивация — `proposal.md`, требования — `specs/code-knowledge-graph/spec.md`.
Состояние до change:
- graphify на машине не установлен. uv 0.12 есть (`/opt/homebrew/bin/uv`).
- Хуков нет нигде: в `.git/hooks/` только `*.sample`, в
`git config --local` нет merge driver, у проекта есть только
`.claude/settings.local.json`, `.claude/settings.json` нет.
- `.gitignore` и `.dockerignore` не знают `graphify-out`.
- ruff читает `.gitignore` (`respect-gitignore` по умолчанию), а
`make lint` форматирует всё дерево, включая `.claude/`.
- Правила из `.claude/rules/` подгружаются только после Read файла из
`paths:` (`AGENTS.md`, «Где лежат инструкции», и глобальные инструкции
пользователя).
У graphify 0.9.72 два способа строить граф (проверено при реализации,
исходник `install.py`, `detect.py`, запуски на этом репозитории):
| | CLI `graphify update .` | скилл `/graphify` |
|---|---|---|
| код | AST через tree-sitter | AST через tree-sitter |
| markdown | структура: разделы — узлы, связь `references` раздела с символами кода из его текста | семантика: субагенты сессии Claude Code извлекают концепты и обоснования |
| `.json`, `.yaml` | не разбирает | разбирает семантически |
| LLM и токены | нет, ~1 с | субагенты; ~200 тыс. токенов на полную сборку этого репозитория, ~60 тыс. на правку `AGENTS.md` |
| установка | `uv tool install` | плюс скилл в `.claude/skills/` |
Режимы не складываются: `graphify update .` заменяет семантические узлы
документов структурными.
## Goals / Non-Goals
**Goals:**
- Установка, которую можно проверить на отсутствие побочных эффектов
сравнением «до/после», а не на честном слове.
- Одна точка правды о том, когда агент спрашивает граф, а когда читает
файл, — `AGENTS.md`.
- Схема в `REPORT.md`, которую проверяющий видит в PR без сторонних
инструментов.
**Non-Goals:**
- Цель в `Makefile` для графа: команда одна и не требует параметров.
- MCP-сервер graphify: пример из README слушает порт 8080, это порт
приложения и `make test`.
- Обновление графа в CI или на коммит.
## Decisions
### 1. Только CLI через `uv tool` с закреплённой версией
`uv tool install --python 3.12 'graphifyy==0.9.72'` ставит CLI в
изолированное окружение `~/.local/share/uv/tools/`: `.venv` и `uv.lock`
проекта не меняются. `--python 3.12` обязателен: без него uv берёт
free-threaded 3.14t, под который у `tree-sitter-rust` нет wheels, и
установка падает на сборке из исходников. Версия записана в `AGENTS.md`.
Скилл, `install` и хуки не используются. Что делает
`graphify install --project` для Claude Code (`_project_install` →
`install()` + `claude_install()`):
| Что | Куда |
|---|---|
| скилл | `.claude/skills/graphify/` |
| блок регистрации скилла | новый `.claude/CLAUDE.md` |
| секция `## graphify`: «first run `graphify query`», «after modifying code, run `graphify update .`» | корневой `CLAUDE.md` проекта |
| PreToolUse-хуки на `Bash\|Grep` и `Read\|Glob` | новый `.claude/settings.json` |
Флага «без хука» нет. Хук и секция противоречат требованиям «Установка
без побочных эффектов» и «Граф не заменяет чтение файла перед правкой».
Альтернативы:
- `graphify install` без флагов — отклонено: меняет глобальные
`CLAUDE.md` и `settings.json`, то есть все проекты пользователя, и
ставит хук.
- Скилл копированием без `install` (`_copy_skill_file`) — был
реализован и отклонён, см. решение 3a.
- `pip install` в `.venv` проекта — отклонено: инструмент попал бы в
зависимости сервиса и в `uv.lock`.
- Без версии — отклонено: следующая версия может поменять поведение CLI.
### 2. Проверка побочных эффектов снимком «до/после»
Перед установкой в scratchpad сессии (вне репозитория) сохраняются:
- копии `~/.claude/CLAUDE.md`, `~/.claude/settings.json`,
`.claude/settings.local.json` и `sha256` всех трёх;
- список `~/.claude/skills/`, `.claude/`, `.git/hooks/`;
- `git config --local --list`;
- `sha256 uv.lock`;
- `git status --short --ignored`;
- копии файлов, которые правит change: рабочее дерево на момент снимка
содержало незакоммиченные правки `container-runtime`, и `git diff`
не отделил бы их.
После установки снимок повторяется и сравнивается. Разрешённые отличия:
`graphify-out/` среди игнорируемых, `.graphifyignore` и правки файлов
из раздела Impact в `proposal.md`. Любое другое отличие — остановиться и
показать пользователю.
### 3. Состав графа: `.graphifyignore` поверх `.gitignore`
Граф строится по корню. `.gitignore` уже убирает `.env`, `config.toml`,
`.venv`, кэши. `.graphifyignore` добавляет исключения из требования
«Состав графа». Выяснилось при реализации:
- Синтаксис gitignore: паттерн без `/` совпадает на любой глубине, и
`README.md` выкинул бы `contracts/README.md`. Все паттерны привязаны
к корню ведущим `/`.
- graphify читает только `.gitignore` внутри репозитория, но не
глобальный `core.excludesfile`. `.claude/settings.local.json` git
игнорирует через `~/.config/git/ignore`, поэтому он исключён явно.
- `requirements-dev.txt` — файл skeleton, исключён вместе с остальными.
- CLI не разбирает `.json`, `.yaml`/`.yml`, `Dockerfile`, `Makefile` и
шаблоны конфигов (`CODE_EXTENSIONS` / `DOC_EXTENSIONS` в `detect.py`
и структурный разбор только markdown). `contracts/openapi.json`,
`docker-compose.yml` и `openspec/config.yaml` в граф не попадают. По
ним агент ищет `grep`. Требование сужено с согласия пользователя.
Итог (сборка с нуля): 616 узлов, 985 связей; источники — `src/`,
`pyproject.toml`, `.claude/rules/`, `AGENTS.md`, `CLAUDE.md`,
`KNOWN_ISSUES.md`, `contracts/README.md`, `openspec/specs/`; ни одного
пути из списка MUST NOT.
### 3a. Почему отказались от скилла и семантического разбора
Первая реализация: скилл скопирован в `.claude/skills/graphify/` без
`install`, граф собран `/graphify .`, документы разобраны двумя
субагентами (~203 тыс. токенов). Результат:
- между кодом и правилами/спеками одна связь, и та ложная
(`logger.py —imports→ logging.md`): субагенты не знают ID узлов AST и
описывают символы кода своими концептами;
- `graphify update .` (им обновляли граф после правок кода) заменил все
семантические узлы документов структурными — разбор агентами из графа
пропал;
- структурный разбор CLI, наоборот, дал 33 связи «документ → код»
(25 от правил, 5 от спек, 3 от `AGENTS.md`), например раздел «Слой
service» → `ChatNotFound`, «Requirement: Создание чата» → `Chat`.
То есть связи правил и спек с кодом — главная польза документов в графе
— даёт бесплатный CLI, а платный семантический разбор их не даёт и
стирается при первом `update`. Пользователь выбрал только CLI. Скилл
удалён из репозитория, вместе с ним ушли риски его автоподгрузки
(широкий `description`), самостоятельного `uv tool install --upgrade`
и «Answer using only what the graph contains».
Запросы: `query` ищет узлы по подстроке метки. Запрос именами символов
(`"ChatService ChatNotFound chat"`) находит код, раздел правила
`service-layer.md` и спеку `chats` по реальным связям. Запрос пересказом
(«chat service member access») эвристика сужает до нескольких узлов
кода. Совет записан в `AGENTS.md`.
### 4. Когда граф, когда Read: правило в `AGENTS.md`
В «Где лежат инструкции» — четвёртый уровень, граф. По смыслу: граф
для вопросов о структуре и связях (`query`, `path`, `explain`,
`affected`), он подсказка и может отставать от кода; перед правкой —
Read файла, иначе правило слоя не подгрузится; связи документов с кодом
частичные, полная карта — `paths:` и таблица правил; в запрос — имена
символов; что граф не видит; только `graphify update .`, без скилла,
`extract`, `install`, хуков и `watch`.
Альтернатива — PreToolUse-хук graphify. Отклонено: хук подталкивает к
графу перед поиском и вытесняет Read, а вместе с ним подгрузку правил.
### 5. Сборка и обновление графа
Одна команда `graphify update .` в корне и для первой сборки, и для
обновлений: без LLM, ~1 с, работает в чистом clone (проверено на копии
`git ls-files` в scratchpad: 616 узлов, те же 33 связи). Вручную, после
заметной работы. Без `watch` и git-хуков.
Побочные эффекты `update` (0.9.72), все внутри игнорируемого
`graphify-out/`: копия прошлого графа в `graphify-out/<дата>/`, имена
кластеров по центральному узлу.
### 6. Схема в `REPORT.md`: Mermaid, сверенный с кодом
Поток — отправка сообщения: он проходит все слои и показывает вызов
одного сервиса из другого.
`graphify export callflow-html` даёт Mermaid, но не подходит: секции на
сотни узлов, тёмная тема, HTML-метки, заголовки секций не о проекте.
Схема нарисована вручную. Из графа (AST) взяты узлы и часть связей:
`MessageService` → `ChatService`, `get_message_service` →
`MessageService`, repo → `MemoryStore`. Вызовы через зависимости
FastAPI (`messages.send_message(...)`) и через псевдоним модуля
(`message_repo.insert_message(...)`) AST не видит — они добавлены по
коду. Все 13 стрелок сверены с кодом через Read, 11 узлов.
Схема стоит в «Архитектуре и решениях» после «Процессы и хранилище»,
подзаголовком «Слои кода». В строке «помощь ИИ» — graphify (граф без
LLM) и то, что схему нарисовал Claude Code и сверил с кодом.
### 7. Git и Docker
- `.gitignore`: `graphify-out/` в секции артефактов.
- `.dockerignore`: `graphify-out` рядом со своими исключениями
(`.claude`, `openspec`). Паттерн без `**/` действует только в корне
контекста, а граф лежит в корне (`docker.md`).
- `.graphifyignore` коммитится.
## Risks / Trade-offs
- [Агент доверится устаревшему графу] → в `AGENTS.md` граф назван
подсказкой, а правка всегда идёт после Read текущего файла.
- [Связи «документ → код» только по упоминаниям] → раздел без символа в
обратных кавычках с кодом не связан; полная карта — `paths:` правил.
- [Запрос пересказом находит мало] → совет в `AGENTS.md`: имена символов.
- [Файлы `.json`/`.yaml`, `Dockerfile`, `Makefile` вне графа] → `grep`.
- [На лабе 1 польза для навигации невелика: 51 файл; отчёт graphify сам
пишет, что корпус помещается в контекст] → принято осознанно:
настройка переезжает в следующие лабы, где кода больше.
- [Mermaid-схема разойдётся с кодом в следующих лабах] → `REPORT.md` не
переносится (`AGENTS.md`), схема строится заново.
- [Смена версии graphify поменяет поведение CLI] → версия закреплена.
## Migration Plan
Установка — задачи в `tasks.md`. Откат целиком:
1. `uv tool uninstall graphifyy`.
2. Удалить `.graphifyignore` и `graphify-out/`.
3. Убрать строки `graphify-out` из `.gitignore` и `.dockerignore`, пункт
о графе и команды graphify из `AGENTS.md`, схему и упоминание из
`REPORT.md`.
Код сервиса не затрагивается, поэтому откат не требует пересборки
образа и повторных проверок API.
@@ -0,0 +1,81 @@
# Proposal
## Why
Агент узнаёт устройство проекта из `AGENTS.md`, правил слоёв и чтения
файлов по одному. Сейчас этого хватает: 51 файл в `src/`. К лабам 5–7
добавятся БД, S3, брокер, worker и телеметрия. На вопросы вида «кто
вызывает X», «что затронет правка Y» и «какое правило или спека
описывает этот модуль» агент начнёт отвечать дорого и с пропусками.
Для отчёта и защиты не хватает схемы устройства кода: раздел
«Архитектура» в `REPORT.md` описывает процессы и хранилище словами, а
слои api → service → repo → infra нигде не нарисованы.
graphify строит по репозиторию граф: код разбирается по AST через
tree-sitter, markdown — по структуре разделов, без LLM и токенов. Граф
решает обе задачи. Ставить его нужно так, чтобы он ничего не ломал в
текущем порядке работы. Главное — правила из `.claude/rules/`
подгружаются только после Read файла, и граф не должен подменять этот
Read.
## What Changes
- **Установка.** Только CLI graphify через `uv tool install` с
закреплённой версией. Скилл `/graphify`, `graphify install`, хуки
Claude Code, git-хуки, merge driver и `graphify watch` не
используются (`design.md`, решения 1 и 3a).
- **Состав графа.** Код `src/`, `pyproject.toml` и документы, которые
описывают код: `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`,
`openspec/specs/`, `contracts/README.md`, `KNOWN_ISSUES.md`. Разделы
документов связаны с символами кода, упомянутыми в их тексте. Через
`.graphifyignore` исключаются проверки и заготовки skeleton,
инструментарий агента, изменения OpenSpec, отчёт, доказательства и
документы курса.
- **Артефакты графа не публикуются.** `graphify-out/` целиком в
`.gitignore` и `.dockerignore`. Граф собирается и обновляется вручную
одной командой `graphify update .` после заметной работы.
- **Порядок работы агента.** В `AGENTS.md` появляется правило: граф — для
вопросов о структуре и связях, а перед правкой файл по-прежнему
читается через Read, чтобы подгрузилось правило слоя.
- **Схема для отчёта.** В раздел «Архитектура и решения» `REPORT.md`
добавляется Mermaid-схема слоёв кода и одного потока вызовов
(отправка сообщения), сверенная с кодом. Runtime-схема остаётся
отдельно. Строка «помощь ИИ» в `REPORT.md` упоминает graphify.
- **Проверка, что ничего не сломано.** Глобальные настройки Claude Code,
git-хуки, `uv.lock`, `make lint`, `make check` и сборка образа до и
после установки дают одинаковый результат. На живом агенте
проверяется, что правило слоя по-прежнему подгружается.
- **Не входит:** скилл `/graphify` и семантический разбор документов
через LLM, MCP-сервер graphify, автообновление графа, публикация
`graph.json` / `graph.html`, экспорт в Obsidian и wiki.
## Capabilities
### New Capabilities
- `code-knowledge-graph`: граф знаний проекта для агента и для отчёта —
что в него входит, где лежат артефакты, как он обновляется, каких
побочных эффектов у установки быть не должно и как граф сочетается с
подгрузкой правил слоёв.
### Modified Capabilities
Нет. Поведение сервиса не меняется, а существующие спеки описывают только
API, хранение, конфигурацию, логи и контейнер.
## Impact
- **Новые файлы:** `.graphifyignore`, локальный `graphify-out/` вне git.
- **Изменяемые файлы:**
- `.gitignore`, `.dockerignore` — строка `graphify-out`;
- `AGENTS.md` — правило использования графа, команды установки и
обновления, `.graphifyignore` в списке переносимого в следующую лабу;
- `REPORT.md` — Mermaid-схема в «Архитектуре», graphify в строке про
ИИ.
- **Код приложения, контракт, тесты, Dockerfile и Makefile** не
меняются.
- **Окружение:** uv (уже есть), graphify CLI в изолированном окружении
`uv tool`. Токены на сборку и обновление графа не тратятся.
- **Зависимость от порядка:** после `container-runtime`. Он уже в архиве
и тоже правил `.dockerignore` и `REPORT.md`, поэтому этот change
дописывает свои строки поверх его версии.
@@ -0,0 +1,191 @@
# Spec Delta
## Purpose
Граф знаний репозитория: агент по нему отвечает на вопросы о структуре и
связях кода, а в отчёт из него берётся схема слоёв. Граф ничего не меняет
в работе проекта и в том, как подгружаются правила слоёв.
## ADDED Requirements
### Requirement: Состав графа
Граф SHALL строиться без LLM по коду `src/` и по документам, которые
описывают код: `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`,
`openspec/specs/`, `contracts/README.md`, `KNOWN_ISSUES.md`, а также по
`pyproject.toml`. Файлы, которые инструмент графа не разбирает
(`.json`, `.yaml`/`.yml`, `Dockerfile`, `Makefile`, шаблоны конфигов),
в граф не попадают. Это известное ограничение, а не ошибка состава.
В граф MUST NOT попадать:
- публичные проверки, скрипты и заготовки skeleton: `tests/`, `scripts/`,
`examples/`, `Dockerfile.example`, `lab.json`, `requirements-dev.txt`,
`contracts/examples.json`, `contracts/infrastructure.json`;
- инструментарий агента: `.claude/commands/`, `.claude/skills/`,
`.claude/settings.local.json`;
- изменения OpenSpec, текущие и архивные: `openspec/changes/`;
- `REPORT.md`, `evidence/` и документы курса: `README.md`, `COURSE.md`,
`CONTRIBUTING.md`, `MAINTAINERS.md`, `.github/`;
- всё, что исключено в `.gitignore`, в том числе `.env`, `config.toml`,
`.venv`.
Список исключений SHALL храниться в файле репозитория, а не в памяти
агента.
Раздел документа SHALL быть связан с символом кода, если символ упомянут
в тексте раздела. Полнота таких связей MUST NOT считаться
гарантированной: раздел без упоминания символа с кодом не связан. Точная
карта «правило слоя → файлы кода» — поле `paths:` в правилах
`.claude/rules/` и таблица в `AGENTS.md`, а не граф.
#### Scenario: Запрос находит код и документы
- **WHEN** агент спрашивает граф о сервисе чатов по именам символов
(`ChatService`, `ChatNotFound`)
- **THEN** в ответе есть узел из `src/core/services/`, раздел правила из
`.claude/rules/` и раздел спеки из `openspec/specs/`
#### Scenario: Исключённое отсутствует
- **WHEN** в графе ищутся узлы из `tests/`, `scripts/`,
`.claude/commands/`, `.claude/skills/` и `openspec/changes/`
- **THEN** таких узлов нет
#### Scenario: Конфигурация связана с настройками
- **WHEN** агент спрашивает граф, где используется порт приложения
- **THEN** в ответе есть модуль настроек из `src/config/` и раздел
правила или спеки о запуске
#### Scenario: Секреты не попадают в граф
- **WHEN** в корне лежат `.env` и `config.toml`
- **THEN** в артефактах графа нет ни их содержимого, ни узлов для них
### Requirement: Артефакты графа локальные
Каталог с артефактами графа SHALL быть исключён из git и из контекста
сборки образа. Граф MUST NOT попадать в коммиты, PR и образ; в отчёт из
него переносится только схема (требование «Схема кода в отчёте»).
#### Scenario: git не видит граф
- **WHEN** граф собран, и выполняется `git status --ignored`
- **THEN** каталог графа виден только среди игнорируемых, а среди новых
и изменённых файлов его нет
#### Scenario: Образ без графа
- **WHEN** после сборки графа собирается образ сервиса
- **THEN** каталог графа не передаётся в контекст сборки, и состав образа
не меняется
### Requirement: Установка без побочных эффектов
Установка инструмента графа SHALL затрагивать только файлы этого
репозитория, перечисленные в change, и изолированное окружение самого
инструмента. Установка MUST NOT:
- менять глобальные инструкции и настройки Claude Code пользователя;
- добавлять хуки Claude Code, скиллы и инструкции агенту от инструмента
в настройки проекта или пользователя;
- добавлять git-хуки, merge driver и другие правки git-конфигурации;
- менять окружение и lock-файл зависимостей проекта;
- менять результат `make lint`, `make check` и сборки образа.
#### Scenario: Глобальные настройки не тронуты
- **WHEN** до и после установки сравниваются глобальные файл инструкций и
файл настроек Claude Code пользователя
- **THEN** содержимое совпадает
#### Scenario: Нет хуков
- **WHEN** после установки просматриваются настройки Claude Code проекта,
каталог git-хуков и git-конфигурация репозитория
- **THEN** новых хуков, merge driver и записей о графе в них нет
#### Scenario: Проект собирается как раньше
- **WHEN** после установки выполняются `make lint` и `make check`
- **THEN** `make lint` не меняет файлов, `make check` проходит, lock-файл
зависимостей без изменений
### Requirement: Граф не заменяет чтение файла перед правкой
Инструкции агента SHALL разделять роли: граф — для вопросов о структуре и
связях («где используется», «кто вызывает», «какое правило описывает
модуль»), а перед правкой файл MUST читаться целиком, как без графа,
чтобы подгрузилось правило слоя.
#### Scenario: Правило слоя подгружается при правке
- **WHEN** в новой сессии агента просят изменить файл в
`src/core/services/`
- **THEN** агент читает этот файл перед правкой, и правило сервисного
слоя попадает в его контекст
#### Scenario: Вопрос о связях
- **WHEN** агента спрашивают, какие модули зависят от хранилища в памяти
- **THEN** агент может ответить по графу, не открывая файлы по одному
### Requirement: Обновление графа вручную
Граф SHALL собираться и обновляться только по явной команде, без
обращений к LLM, за секунды, в том числе в чистом clone. Коммиты,
переключение веток и изменения файлов MUST NOT запускать пересборку.
#### Scenario: Коммит не пересобирает граф
- **WHEN** в репозитории делается коммит
- **THEN** артефакты графа не меняются
#### Scenario: Новый модуль после обновления
- **WHEN** в `src/` добавлен модуль, и выполнена команда обновления
- **THEN** модуль есть в графе, а команда не обращалась к LLM
#### Scenario: Сборка в чистом clone
- **WHEN** в clone без каталога графа выполняется команда обновления
- **THEN** граф собирается целиком
### Requirement: Схема кода в отчёте
Раздел «Архитектура и решения» в `REPORT.md` SHALL содержать схему
слоёв кода (api → service → repo → хранилище) и поток вызовов одной
операции — отправки сообщения — в виде блока Mermaid, который GitHub
показывает как диаграмму. Каждая связь на схеме MUST существовать в
коде. Описание процессов и хранилища в отчёте SHALL остаться: схема кода
его дополняет, а не заменяет. В отчёте SHALL быть указано, как схема
получена и какую роль в этом сыграл инструмент графа.
#### Scenario: Схема видна в PR
- **WHEN** проверяющий открывает `REPORT.md` на GitHub
- **THEN** схема отображается диаграммой, а не текстом
#### Scenario: Схема соответствует коду
- **WHEN** каждая стрелка схемы сверяется с кодом
- **THEN** для каждой есть реальный импорт или вызов между указанными
модулями
#### Scenario: Использование ИИ указано
- **WHEN** проверяющий читает, какая помощь ИИ использовалась
- **THEN** там названы инструмент графа и то, для чего он применялся
### Requirement: Перенос в следующую лабу
Список исключений графа SHALL переноситься в следующую лабу вместе с
инструкциями агента. Артефакты графа MUST NOT переноситься: в новом
репозитории граф собирается заново.
#### Scenario: Новая лаба
- **WHEN** решение переносится в skeleton следующей лабы по `AGENTS.md`
- **THEN** список исключений перенесён, а граф собирается заново после
переноса
@@ -0,0 +1,139 @@
# Tasks
Как строить — `design.md`, что должно получиться —
`specs/code-knowledge-graph/spec.md`. Перед правкой `.dockerignore`
прочитать `.claude/rules/docker.md`. Снимки и копии для сравнения
класть в scratchpad сессии, не в репозиторий. Git — только смотреть:
без commit, add и хуков.
Задачи 2.3, 2.4, 4.1, 4.2, 4.3, 5.1, 5.2 и 7.1 написаны и выполнены
под первую реализацию — со скиллом `/graphify` и семантическим разбором
документов (копирование скилла, `/graphify . --update`, порт через
`docker-compose.yml`, фраза про инструкции скилла в `AGENTS.md`,
`.claude/skills/graphify/` в ожидаемых файлах). От неё отказались
(`design.md`, решение 3a); итоговое состояние и его проверки — группа 8.
## 1. Снимок до установки
- [x] 1.1 Снять снимок по design, решение 2: копии и `sha256`
`~/.claude/CLAUDE.md`, `~/.claude/settings.json`,
`.claude/settings.local.json`; списки `~/.claude/skills/`, `.claude/`,
`.git/hooks/`; `git config --local --list`; `sha256 uv.lock`;
`git status --short --ignored`. Проверка: все файлы снимка есть в
scratchpad и не пустые.
## 2. Установка
- [x] 2.1 Узнать последнюю версию `graphifyy` и поставить CLI:
`uv tool install 'graphifyy==<версия>'`. Проверка: `graphify --version`
печатает эту версию; `uv tool list` показывает `graphifyy`;
`sha256 uv.lock` совпадает со снимком.
- [x] 2.2 Сверить команды по `graphify --help` и `graphify install
--help`: флаг `--project`, запросы (`query`, `path`, `explain`),
`--update`, `export callflow-html`. Если что-то расходится с design —
остановиться и сказать пользователю до установки скилла. Проверка:
список реальных команд и флагов записан в ответе пользователю.
- [x] 2.3 Скопировать скилл в корне репозитория командой из design,
решение 1 (`_copy_skill_file('claude', project=True, ...)`), без
`graphify install`. Проверка: появился `.claude/skills/graphify/SKILL.md`
с `references/`; `.claude/settings.json` и `.claude/CLAUDE.md` не
появились, `CLAUDE.md` совпадает со снимком; повторный снимок по 1.1
отличается только новым каталогом скилла. Иное отличие — остановиться,
показать diff пользователю, откат из копий — только с его согласия.
- [x] 2.4 Прочитать `.claude/skills/graphify/SKILL.md` и `references/`
целиком, выбрать исход по таблице в design, решение 4. Проверка: исход
и цитата места, которое к нему привело, есть в ответе пользователю. При
третьем исходе (хук или правка `CLAUDE.md`/`AGENTS.md`) — стоп до
решения пользователя.
## 3. Исключения
- [x] 3.1 Создать `.graphifyignore` со списком из design, решение 3.
Проверка: каждый путь из требования «Состав графа» (MUST NOT) покрыт
этим файлом или `.gitignore`.
- [x] 3.2 Добавить `graphify-out/` в `.gitignore` (секция артефактов) и
`graphify-out` в `.dockerignore` (к своим исключениям). Проверка:
`git check-ignore -v graphify-out/x` указывает на `.gitignore`;
`git diff .dockerignore` — одна добавленная строка.
## 4. Сборка графа
- [x] 4.1 Собрать граф `/graphify .` в сессии Claude Code. Проверка: есть
`graphify-out/graph.json` и `graphify-out/GRAPH_REPORT.md`;
`git status --short` не показывает `graphify-out/`.
- [x] 4.2 Проверить состав по сценариям требования «Состав графа»:
запрос о сервисе чатов даёт узел из `src/core/services/` и узел из
`.claude/rules/` или `openspec/specs/`; запрос о порте даёт
`docker-compose.yml` и `src/config/`; поиск по
`tests/`, `scripts/`, `.claude/commands/`, `.claude/skills/`,
`openspec/changes/` пуст; `grep` значений из `.env` и `config.toml` по
`graphify-out/` ничего не находит. Проверка: вывод запросов в ответе
пользователю.
- [x] 4.3 Проверить обновление: добавить в `src/utils/` временный модуль
с одной функцией, выполнить `/graphify . --update`, найти модуль в
графе, удалить модуль, снова `--update`. Проверка: модуль появился и
исчез; в выводе видно, что неизменённые файлы взяты из кэша;
`git status` после удаления чистый по `src/`.
## 5. Инструкции агента
- [x] 5.1 `AGENTS.md`: пункт про граф в «Где лежат инструкции» по design,
решение 4, с учётом исхода 2.4 и реальных имён команд из 2.2. Вводную
«Три уровня» поправить на четыре. Проверка: в пункте есть «перед
правкой — Read» и «важнее инструкций скилла graphify».
- [x] 5.2 `AGENTS.md`: в «Окружение и команды» — строки установки
(`uv tool install --python 3.12 'graphifyy==0.9.72'`, копирование
скилла из design, решение 1, и запрет `graphify install` / `graphify
claude install` с причиной) и обновления (`/graphify . --update`); в «Переход в следующую лабу» —
`.graphifyignore` в «Переносить», `graphify-out/` в «Не копировать».
Проверка: `grep -n graphify AGENTS.md` показывает три раздела.
## 6. Схема для отчёта
- [x] 6.1 Получить Mermaid потока отправки сообщения по design, решение
6: сначала `graphify export callflow-html`, при неудаче — вручную по
`graphify path` / `query`. Проверка: каждая стрелка сверена с кодом
через Read (импорт или вызов есть), узлов не больше ~15.
- [x] 6.2 `REPORT.md`: подзаголовок «Слои кода» с блоком ` ```mermaid `
после «Процессы и хранилище»; в строку «помощь ИИ» — graphify и для
чего он. Текст о процессах и хранилище не менять. Проверка:
`git diff REPORT.md` — только добавления; схема рендерится в превью
Markdown с Mermaid (PyCharm или GitHub).
## 7. Итоговая проверка
- [x] 7.1 Повторить снимок по 1.1 и сравнить. Проверка: глобальные
`CLAUDE.md` и `settings.json`, `.claude/settings.local.json`,
`.git/hooks/`, `git config --local` и `uv.lock` совпадают со снимком;
в `git status` новые и изменённые только `.claude/skills/graphify/`,
`.graphifyignore`, `.gitignore`, `.dockerignore`, `AGENTS.md`,
`REPORT.md` и файлы этого change.
- [x] 7.2 `make lint` и `make check`. Проверка: `make lint` не меняет
файлов (`git status` до и после одинаковый), `make check` — `PASS`.
- [x] 7.3 `docker build -t mtusi-messenger:lab1 .` Проверка: сборка
проходит, `graphify-out` не попадает в контекст (размер контекста в
выводе того же порядка, что до change).
- [x] 7.4 Проверка на живом агенте: попросить пользователя открыть новую
сессию и дать задачу правки в `src/core/services/`. Проверка: в
транскрипте файл прочитан через Read до правки, и правило
`service-layer.md` подгружено. Результат записать в ответе, правку из
проверки не оставлять.
## 8. Переход на CLI без скилла
- [x] 8.1 Удалить `.claude/skills/graphify/` и `graphify-out/`, собрать
граф с нуля `graphify update .`. Проверка: сборка без LLM за секунды;
в `.claude/skills/` только `run-mtusi-messenger`.
- [x] 8.2 Проверить состав по требованию «Состав графа»: ни одного пути
из списка MUST NOT; связи разделов правил и спек с кодом есть;
запрос `"ChatService ChatNotFound chat"` находит `src/core/services/`,
`.claude/rules/` и `openspec/specs/`; запрос о порте — `src/config/`
и раздел о запуске. Проверка: вывод в ответе пользователю.
- [x] 8.3 Сборка в чистом clone: копия `git ls-files` в scratchpad,
`graphify update .`. Проверка: граф собирается, связи «документ →
код» те же.
- [x] 8.4 Переписать `AGENTS.md`, `REPORT.md` (строка про ИИ), proposal,
design и спеку под CLI. Проверка: `grep -n "skills/graphify\|/graphify ." AGENTS.md`
пусто; `openspec validate graphify --strict` проходит.
- [x] 8.5 Повторить 7.1–7.2: глобальные файлы, хуки, `uv.lock` как в
снимке; `make lint` без изменений; `make check` — PASS.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-09-30
@@ -0,0 +1,414 @@
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — спек
`load-benchmark` в этом change.
Что есть сейчас и влияет на подход:
- **Приложение** — один процесс uvicorn, один event loop. На каждый
запрос пишется одна строка access-лога, на POST сообщения — ещё
строка сервиса (JSON в stdout, уровень INFO).
- **Хранилище** — `MemoryStore`: история чата — список в порядке
`(created_at, id)`. Вставка — `bisect.insort` почти всегда в конец,
курсор ищется `bisect`, страница — срез. DTO со `slots=True`,
middleware на чистом ASGI.
- **Докер** — Docker Desktop 29.8.1 на macOS 26.6.2, Apple M3 Pro, VM
linux/arm64: 12 CPU, 7,7 ГБ, cgroup v2, лог-драйвер по умолчанию
`local` (ротация, сжатие).
- **Прошлые замеры** `tests/load.py` через проброс портов: console 1502
RPS, контейнер 1258 RPS (p50 1,99 против 2,58 мс) — разница в
основном из-за VM и проброса, а не из-за кода.
- **API** не умеет массовой вставки и удаления: наполнение возможно
только через `POST .../messages` по одному сообщению.
## Гипотезы
Записаны до замера. После него не переписываются: если данные
опровергают гипотезу, это и есть результат, он идёт в отчёт с
объяснением. «Разброс» ниже — min–max трёх повторов ячейки из
`summary.md`.
| | Гипотеза | Почему ожидаем | Чем проверяем | Что её опровергнет |
|---|---|---|---|---|
| H1 | Время `read` почти не зависит от N | Курсор ищется `bisect` за O(log N): около 14 сравнений при 10k и около 20 при 1M. Страница — срез ровно из 50 элементов, ответ одного размера при любом N | Ячейки `read`: RPS и p50/p95 при одинаковой конкуренции на 10k, 100k и 1M | RPS на 1M ниже или p95 выше, чем на 10k, больше чем на разброс повторов |
| H2 | Throughput упирается в одно ядро уже при конкуренции 10, дальше растут только задержки | Один процесс, один event loop, `--cpus=1`. По закону Литтла задержка ≈ конкуренция / throughput: при потолке RPS пятикратный рост конкуренции даёт примерно пятикратный рост p50 | Оба сценария: RPS, CPU приложения и p50 при конкуренции 1, 10, 50 | RPS при 50 выше, чем при 10, больше разброса, или CPU приложения при 10 заметно ниже 1 ядра: тогда потолок не в CPU сервера |
| H3 | RSS растёт линейно с N, порядка сотен байт на сообщение | Сообщение — несколько объектов Python: DTO со `slots`, UUID, `datetime`, строка 64 символа, указатель в списке. Сообщения не удаляются | RSS до и после наполнения и байты на сообщение по размерам; RSS по порциям кривой наполнения 1M | Байты на сообщение на разных размерах различаются больше чем в 1,5 раза или RSS на кривой растёт заметно нелинейно |
| H4 | Хвост задержек записи растёт с N из-за полных сборок мусора, медиана почти не растёт | Полная сборка обходит все отслеживаемые объекты, их число растёт с N. На 1M пауза — десятки или сотни мс, и всё это время event loop стоит | Сначала кривая наполнения 1M: p50, p99 и max по порциям; затем ячейки `write` матрицы | p99 и max на кривой не растут с N, или растут вместе с p50 — тогда дорожает каждый запрос, а не редкие паузы |
- **Как подтверждается причина.** Базовый замер показывает только
закономерность. Что пауза именно от GC, а дорогой запрос — от
конкретной функции, подтверждает профиль в `perf-bottleneck-fix`.
- **Возможная помеха для H1.** При 1M чтение из случайных мест истории
обращается к памяти, которая не помещается в кэш процессора. Если H1
опровергнется, это первый кандидат на объяснение, а не повод
менять методику.
## Goals / Non-Goals
**Goals:**
- Одинаковые условия для всех меток: тот же профиль, лимиты и
генератор. `perf-bottleneck-fix` меняет только код приложения и
запускает `make bench BENCH_LABEL=<своя метка>`.
- Каждое число в сводке прослеживается до сырого результата прогона.
- Прогон не мешает рабочим стендам на 8080 и параллельным сессиям.
**Non-Goals:**
- Профилирование (py-spy) и выбор узкого места.
- Open-loop нагрузка с заданным темпом, графики, сравнение двух меток.
- Замер вне Docker Desktop (Linux-хост, облако) и нагрузка на
регистрацию и чаты: эти операции не растут с историей.
## Decisions
### 1. Раскладка
```
bench/
run.py # оркестратор: стенд, матрица, сбор метрик, запись результатов
k6/
lib.js # общие хелперы: BASE_URL, заголовки, синтетический текст, проверки
prepare.js # пользователи и два чата → fixture.json
prefill.js # одна порция наполнения читаемого чата
cursors.js # обход истории, выборка курсоров по всей её длине
read.js # сценарий read
tail.js # проверка после блока read: читаемый чат не изменился
write.js # сценарий write
evidence/bench/<метка>/
meta.json # паспорт стенда
progress.json # текущее состояние, пока идёт прогон
runs.csv # все прогоны, одна строка — один прогон, дописывается сразу
prefill.csv # порции наполнения: запись при росте хранилища
summary.md # сводка по ячейкам: медиана и min–max
raw/ # итог k6 каждого прогона и наполнения
.work/ # только на время прогона: fixture.json, cursors.json,
# tail.json, итог прогрева; удаляется в конце
```
- **Оркестратор на Python stdlib** (`subprocess`, `json`, `csv`,
`threading`, `statistics`), запуск `uv run python bench/run.py`.
Новых зависимостей нет, интерпретатор — закреплённый проектом.
*Альтернатива:* bash — неудобно считать медианы, разбирать JSON и
опрашивать RSS параллельно с прогоном.
- **Оркестратор не ходит в API по HTTP.** Все запросы делает k6 внутри
сети стенда, поэтому публиковать порт не нужно. Готовность — `docker
exec` той же командой, что у healthcheck образа.
### 2. Стенд
- **Образ** `mtusi-messenger:bench` собирается из текущего checkout
(`docker build`), чтобы метка отражала код на диске. Commit и
признак незакоммиченных изменений пишутся в паспорт. Отдельный тег
не трогает образ `mtusi-messenger:lab1`, которым пользуется
`make run_docker`.
- **Приложение:**
```
docker run -d --name mtusi-bench-api --network mtusi-bench \
--cpus=1 --memory=2g --memory-swap=2g --no-healthcheck \
mtusi-messenger:bench
```
- `--cpus=1`: сервер однопоточный, и лимит делает потолок
воспроизводимым, не зависящим от загрузки остальных ядер VM.
- `--memory=2g` без swap: оценка ~0,5 ГБ на 1M сообщений, запас
вчетверо. Если лимита всё же не хватит, это OOM — находка о пределе
архитектуры, а не сбой стенда (спек, «Нехватка памяти»).
- `--no-healthcheck`: проверка раз в 10 с запускает отдельный процесс
Python внутри того же лимита CPU и даёт шум.
- `.env` и `config.toml` не передаются: всё на дефолтах, лог INFO как
в обычной работе. Отключать логи ради цифр — значит мерить не то
приложение.
- **Генератор.** Контейнер k6 `grafana/k6:2.3.0@sha256:9c2dee7f…` живёт
весь размер, запущенный с `sleep`. Прогоны — `docker exec … k6 run`.
Так CPU генератора считается по его cgroup до и после каждого
прогона, а старт контейнера не попадает в замер. Каталог `bench/k6`
монтируется только на чтение, каталог метки — на запись. Лимит CPU
генератору не ставится: ему остаются 11 ядер VM.
- **Уборка.** `try/finally` и обработка Ctrl+C: `docker rm -f` обоих
контейнеров и `docker network rm`. В паспорт пишется
`"status": "incomplete"`, пока матрица не завершена. На время уборки
SIGINT игнорируется: повторный Ctrl+C не должен оставить контейнеры.
- **Сторож.** Поток, который раз в секунду опрашивает RSS, заодно
проверяет, жив ли контейнер приложения. Если приложение умерло
(OOM), он останавливает k6 (`pkill -INT`): иначе каждый запрос к
исчезнувшему контейнеру ждал бы таймаута 60 с, и наполнение тянулось
бы часами. Прогон или порция пишутся с пометками `oom` / `app_down`,
матрица останавливается с причиной в паспорте. Смерть контейнера при
старте распознаётся сразу, без ожидания таймаута готовности.
Найдено проверкой с лимитом 56 МБ.
*Альтернатива:* нагрузка с хоста через проброс портов, как
`tests/load.py`. Отвергнута: проброс сам стоит 0,6 мс и 16% RPS, и
разница «до/после» утонула бы в этом шуме.
### 3. Наполнение и фикстура
Для каждого размера N:
1. Новый контейнер приложения. Ожидание готовности.
2. `prepare.js`: `setup()` регистрирует читателя и 10 участников и
создаёт два чата — читаемый (для `read`) и чат записи (для
`write`); `handleSummary` пишет их id в `fixture.json`.
3. `prefill.js` порциями по 50 000 (решение 5a): `shared-iterations`,
32 VU, сообщения от участников по кругу в читаемый чат, текст
синтетический, 64 ASCII-символа. Последняя порция — остаток до N.
Каждая порция — отдельный запуск k6 со своим итогом, поэтому по ней
снимаются те же метрики, что и по прогону (решение 5), и строка
идёт в `prefill.csv`.
4. `cursors.js`: `setup()` проходит историю по `limit=100` и собирает
`next_cursor` каждой страницы: это позиции 100, 200, … от начала
истории. В пул `cursors.json` идут только позиции, после которых
есть ещё не меньше 50 сообщений, так что страница `read` всегда
полная. Если позиций больше 1000, берётся равномерная выборка из
1000; при 10k в пуле около 100 курсоров. `setupTimeout` с запасом:
на 1M проход — 10 000 запросов.
5. RSS до и после наполнения, байты на сообщение = ΔRSS / N.
Наполнение 1M при ~1500–2500 RPS — около 7–11 минут, 10k и 100k —
секунды и минута.
**Кривая наполнения.** Наполнение до 1M — это запись при росте
хранилища от 0 до миллиона, 20 точек по 50 000. Она дополняет матрицу
и не заменяет её:
- в матрице запись идёт при почти неизменном N, с тремя уровнями
конкуренции и повторами — это сравнимые ячейки;
- в наполнении конкуренция всегда 32, повторов нет, зато хранилище
растёт до 1M внутри одного процесса. Полные сборки мусора
гарантированно случаются несколько раз, и видно, как с N растут их
паузы, хвост задержек и RSS. Это прямая проверка H3 и H4.
На 10k и 100k кривая даёт 1 и 2 точки: смысл она имеет на 1M.
*Альтернатива:* служебный эндпоинт или переменная окружения для
массовой вставки. Отвергнута: это изменение приложения, которое
в замер не входит, и лишняя поверхность API.
### 4. Сценарии и профиль
| | `read` | `write` |
|---|---|---|
| Запрос | `GET /api/v1/chats/{читаемый}/messages?limit=50&cursor=<случайный из пула cursors.json>` | `POST /api/v1/chats/{чат записи}/messages`, текст 64 символа |
| Ожидаемый статус | 200 | 201 |
| Исполнитель k6 | `constant-vus`, VU = конкуренция | `shared-iterations`, VU = конкуренция |
| Прогрев | 5 с | 500 запросов |
| Измерение | 20 с | 5000 запросов |
- **Чтение — по времени.** Данные не меняются, поэтому длительность
ничем не ограничена, а 20 с дают от десятков тысяч запросов.
- **Курсор — случайный из пула на каждый запрос**, а не один на прогон
и не отдельная ось матрицы:
- один курсор мерил бы одну точку истории с горячими кэшами
процессора;
- ось «позиция» утроила бы чтение (81 прогон вместо 27), а рубрика
её не просит. Случайная выборка по всей длине сразу проверяет, что
`bisect` не зависит от позиции.
- **Воспроизводимая случайность.** Выбор делает свой генератор
(mulberry32, несколько строк в `lib.js`) с зерном `seed + номер VU`;
`seed` берётся из профиля и пишется в паспорт. У каждого клиента своя
последовательность, и она одинакова в разных метках: «до» и «после»
отправляют одинаковые запросы. `Math.random` и опция k6 `randomSeed`
не подходят: первое не воспроизводится, второе, насколько известно,
даёт всем VU одно зерно, и 50 клиентов запрашивали бы одни и те же
страницы почти синхронно.
Число запросов за 20 с зависит от скорости сервера, поэтому совпадает
начало последовательности, а не её длина.
- **Зерно прогрева** — `seed + warmup_seed_shift` (1 000 003), а не
`seed`. С тем же зерном прогрев запросил бы ровно те страницы, с
которых начинается замер, и первые запросы замера попадали бы в уже
прогретый кэш процессора. Сдвиг — поле профиля, пишется в паспорт.
- **Запись — по числу запросов.** Если писать 20 с, за 9 прогонов
размера 10k хранилище выросло бы до ~200k и перекрыло размер 100k.
При 5000 + 500 рост за размер ~50k: 10k → ~60k, 100k → ~150k,
1M → ~1,05M. Уровни не перекрываются, фактическое число сообщений
в начале и в конце каждого прогона пишется в `runs.csv`. 5000
запросов дают 50 наблюдений в хвосте p99.
- **Порядок внутри размера:** все `read` (конкуренция по возрастанию,
по 3 повтора), затем все `write`. Запись идёт в отдельный чат, и
читаемый чат остаётся ровно N.
- **Проверка после блока `read`** (`tail.js`): история дочитывается от
последнего курсора пула до конца, и число сообщений сверяется с N
(спек, «Чтение не меняет данные»). Новое сообщение встало бы в конец
истории, поэтому хвоста достаточно: на 1M это несколько запросов, а
не полный обход. Проверка идёт между блоками и в измеряемые прогоны
не попадает. Расхождение останавливает матрицу.
- **Проверки k6:** `check` на статус. Перцентили берутся из
подметрики `http_req_duration{expected_response:true}`, то есть
только по успешным ответам (спек, «Ошибки учитываются»).
- **Профиль `quick`** для `make bench_quick`: размеры 1k / 5k / 10k,
конкуренция 1 / 4 / 16, 1 повтор, чтение 5 с после 2 с прогрева,
запись 1000 после 100. Около 1,5 минуты. Метка —
`quick-<UTC-время>`, каталоги `evidence/bench/quick-*` в
`.gitignore`: это самопроверка стенда, а не результат.
### 5. Метрики
| Метрика | Источник |
|---|---|
| RPS, число успехов и ошибок, p50/p95/p99/max | итог k6 прогона (`handleSummary` → `raw/<прогон>.json`), `summaryTrendStats` с `p(99)` и `max` |
| CPU приложения | `usage_usec` из `/sys/fs/cgroup/cpu.stat` контейнера до и после прогона; ядра = Δ / время |
| RSS | `VmRSS` из `/proc/1/status` раз в секунду в фоновом потоке: начало, конец, максимум; `VmHWM` в конце размера — пик процесса |
| Память по лимиту | `memory.current` cgroup: именно с ней сравнивается `--memory` |
| CPU генератора | `cpu.stat` контейнера k6 до и после прогона |
| Сообщения в хранилище | N наполнения + подтверждённые 201 записи (счётчик оркестратора) |
| Достоверность | `docker inspect`: `State.OOMKilled`, `State.Running`, `RestartCount` |
| Порция наполнения | те же источники вокруг запуска `prefill.js`; строка в `prefill.csv` вместо `runs.csv` |
- **Пометки прогона:** `oom`, `app_down`, `errors` (доля ошибок > 0),
`generator` (k6 занял ≥ 4 ядер). Порог записан в паспорте. 4 ядра —
треть свободных ядер VM: выше k6 уже может сам ограничивать
throughput.
- **Сводка `summary.md`:** по сценарию таблица «размер × конкуренция»
с медианой по 3 повторам и min–max для RPS, p95, p99 и RSS. Пометки
стоят рядом со значением. Отдельные таблицы: RSS и байты на
сообщение по размерам; кривая наполнения 1M — сообщений в хранилище,
RPS, p95, p99, max и RSS по каждой порции.
### 5a. Ход прогона
Полная матрица идёт около 18 минут (при проектировании ожидалось ~40),
поэтому ход виден по трём каналам.
- **Строки в stdout** с временем от начала, одна на событие (формат;
числа в примере условные, не замер):
```
[00:00:12] image mtusi-messenger:bench built (sha256:4f1c…), network mtusi-bench
[00:00:15] size 1M (3/3): app started, RSS 61.8 MiB
[00:03:40] size 1M: prefill 350000/1000000 (35%), 1712 msg/s, ~6m20s left
[00:10:02] size 1M: prefill done, RSS 548.3 MiB (+512 B/msg); cursors 1000
[00:10:31] run 37/54 read 1M c=10 r1: 2310 rps p50 4.1 p95 6.0 p99 8.9 ms cpu 0.99 rss 549 MiB err 0 ~11m left
[00:10:58] run 38/54 read 1M c=10 r2: 2295 rps … [generator]
```
Пометки — в квадратных скобках в конце строки. Предупреждения о
хосте печатаются в начале.
- **Прогресс наполнения.** Наполнение идёт порциями по 50 000
сообщений: одна порция — один запуск `prefill.js` (решение 3).
После каждой порции оркестратор печатает строку прогресса. На 1M это
20 строк примерно раз в 30 секунд, при 10k — одна. Пользователи и
чаты создаются один раз в `prepare.js`, порции берут их из
`fixture.json`.
- **Оценка оставшегося времени.** Время `read` известно из профиля,
время `write` и наполнения оценивается по уже измеренной скорости на
этом стенде. До первых измерений оценка — по профилю с запасом.
- **`progress.json` в каталоге метки** перезаписывается после каждого
события: этап, размер, `runs_done` / `runs_total`, оценка
оставшегося времени, результат последнего прогона, предупреждения.
Смотреть из другого терминала:
`watch -n 5 cat evidence/bench/<метка>/progress.json`.
- **`runs.csv` дописывается** после каждого прогона, с `flush`.
`summary.md` строится в конце и при прерывании — по тому, что успело
завершиться.
- Вывод самого k6 при измеряемых прогонах подавляется (`--quiet`): его
прогресс-бар не нужен, а ошибки k6 оркестратор печатает целиком.
### 6. Паспорт стенда (`meta.json`)
Дата UTC, commit и `dirty`, id образа приложения, версии Python и
uvicorn/FastAPI в образе (`importlib.metadata`), версия и digest k6,
лимиты из `docker inspect` запущенного контейнера (`NanoCpus`,
`Memory`, `MemorySwap`), лог-драйвер, macOS, CPU хоста, Docker, CPU и
память VM, полный профиль (размеры, конкуренция, повторы, длительности,
длина текста, порог генератора, зерно выбора курсоров), команда
запуска, статус
`complete` / `incomplete`. Абсолютные пути не пишутся: только пути
относительно репозитория.
**Состояние хоста** снимается в начале и в конце всего прогона
(`host_state.start` / `host_state.end`):
| Поле | Источник (macOS) |
|---|---|
| занятый и общий swap | `sysctl vm.swapusage` |
| доля свободной памяти | `memory_pressure`, строка `System-wide memory free percentage` |
| питание | `pmset -g batt`: `AC Power` / `Battery Power` и заряд |
- На другой ОС поля равны `null`: снимок не должен ломать прогон.
- Внешние команды запускаются с `LC_ALL=C`: при русской локали `sysctl`
печатает `0,00M`, и разбор с точкой давал пустой swap. Найдено после
перезагрузки хоста, до базового замера.
- **`other_containers`** — имена контейнеров, которые работали в VM
Docker на момент старта. Стенд их не трогает, но они делят с ним
ресурсы VM, поэтому список идёт в паспорт и в шапку сводки.
- **Предупреждения** (`host_warnings`) — если в начале прогона питание
от батареи или swap занят больше 1 ГБ. Прогон не прерывается: решает
человек, а паспорт показывает, в каких условиях сняты цифры.
- Порог 1 ГБ — ориентир: при занятых гигабайтах swap macOS вытесняет
страницы, в том числе страницы VM Docker, и это даёт всплески
задержки, не связанные с кодом. На момент проектирования swap был
занят на 9,5 из 10 ГБ, ноутбук работал от батареи.
- Перед полной матрицей: перезагрузить ноутбук, подключить питание,
остановить посторонние контейнеры, проверить `sysctl vm.swapusage`.
Этот порядок записывается в `REPORT.md` как часть методики.
### 7. Команды
```make
# -------------------------
# Load benchmark (трек 1)
# -------------------------
BENCH_LABEL ?= baseline
# полная матрица, ~18 мин; метка не должна существовать
.PHONY: bench
bench:
uv run python bench/run.py --profile full --label $(BENCH_LABEL)
# самопроверка стенда на малых размерах, ~1,5 мин
.PHONY: bench_quick
bench_quick:
uv run python bench/run.py --profile quick --label quick-$(shell date -u +%Y%m%dT%H%M%SZ)
```
Секция стоит после `Docker targets`. `BENCH_LABEL` задаётся аргументом
make, как `BASE_URL`.
### 8. Документация
- **`REPORT.md`, «Эксперименты и отказы»:**
- таблица из раздела «Гипотезы» как есть, плюс столбец «Результат»:
подтверждена или опровергнута, с числами из `summary.md`;
- стенд и лимиты, профиль, таблицы из `summary.md`, ограничения;
- строка «Выбранный трек 5» в таблице доказательств — базовый замер,
«до/после» добавит `perf-bottleneck-fix`.
- **`.claude/rules/bench.md`** (`paths: bench/**`): инварианты методики
(лимиты, профиль и версия k6 не меняются между метками; код
приложения не импортируется; новая метрика — новый столбец, старые
не переименовываются). Ссылка в таблице правил `AGENTS.md`.
- **`AGENTS.md`:** команды `make bench` и `make bench_quick`, карта кода
`bench/` и `evidence/bench/`.
- **`.dockerignore`:** `bench`.
## Risks / Trade-offs
- [Шум VM и фоновых процессов macOS] → три повтора, min–max в сводке,
ноутбук не нагружать во время прогона. Разницу «до/после» считать
значимой, только если она больше разброса повторов.
- [k6 и приложение делят VM] → приложение ограничено 1 CPU, CPU k6
измеряется, прогон помечается при ≥ 4 ядрах.
- [Closed-loop занижает хвост при перегрузке (coordinated omission)] →
называем это в ограничениях. При 50 клиентах задержка включает
очередь, но пропущенные «несделанные» запросы не видны.
Open-loop — кандидат для `perf-bottleneck-fix`.
- [5000 записей может не хватить, чтобы застать полную сборку мусора
при 1M] → CPython запускает её, когда накопилось около 25% новых
долгоживущих объектов, то есть через десятки тысяч сообщений. Поэтому
ячейки `write` матрицы могут H4 не показать. Её покрывает кривая
наполнения: при росте до 1M сборки случаются заведомо. Ограничение
кривой — фиксированная конкуренция 32 и один проход без повторов,
это записывается в отчёте.
- [Логи INFO пишутся в docker, и dockerd тратит CPU вне лимита
приложения] → это часть реальной стоимости запроса. В паспорте
записан лог-драйвер.
- [Полный прогон ~40 минут] → `make bench_quick` для проверки стенда и
защиты. Полная матрица запускается один раз на метку. Фактически
базовый замер занял 17,5 минуты (наполнение идёт на ~3900
сообщений/с, а не на 1500–2500), короткий прогон — 1,5 минуты.
- [Наполнение через HTTP создаёт свой шум: 1M строк лога, рост
объектов] → замеры начинаются после наполнения, обхода курсоров и
прогрева.
## Migration Plan
Не применимо: новые файлы, код приложения и образ `lab1` не меняются.
Откат — удалить `bench/`, `evidence/bench/`, цели из `Makefile` и
правило.
@@ -0,0 +1,85 @@
# Proposal
## Why
Трек 1 уровня «5» (`README.md`) требует повторяемого эксперимента: ≥3
размера истории × ≥3 уровня конкуренции, throughput, p95/p99 и RSS, а
затем сравнения «до/после» одного изменения при тех же лимитах.
`COURSE.md` добавляет правила честных замеров: версии, железо, лимиты
CPU/RAM, прогрев, одинаковые запросы при одинаковых ресурсах.
Сейчас есть только `tests/load.py`. Он сам себя описывает как closed-loop
генератор одной операции (POST), ограниченный производительностью
клиента, и прямо отсылает к k6/Locust/wrk для исследования. Замеры,
которые мы уже делали, шли через проброс портов Docker Desktop, а тот
сам добавлял около 0,6 мс к медиане и отнимал около 16% RPS. Без
отдельного стенда и методики сравнение «до/после» в change
`perf-bottleneck-fix` будет сравнением шума.
## What Changes
- **Стенд замеров.** Приложение запускается в своём контейнере из
образа текущего checkout с фиксированными лимитами (`--cpus=1`,
`--memory=2g`), без healthcheck и без публикации портов, в отдельной
docker-сети. Генератор нагрузки k6 с закреплённой версией работает в
той же сети, минуя проброс портов хоста. Стенд не пересекается с
`make run_dev`, `make run_docker` и портом 8080.
- **Два сценария нагрузки:**
- `read` — страница истории (`limit=50`) со случайного места чата из
N сообщений; данные не меняются, повторы сопоставимы;
- `write` — отправка сообщения; здесь видны рост памяти и работа
сборщика мусора.
- **Матрица:** размеры истории 10k / 100k / 1M сообщений × конкуренция
1 / 10 / 50 клиентов × 2 сценария, по 3 повтора с прогревом. Каждый
размер — с нового процесса, наполненного через HTTP до ровно N
сообщений.
- **Метрики каждого прогона:** успешные RPS, доля ошибок, p50/p95/p99 и
max задержки, CPU приложения, RSS (в начале, в конце, максимум),
число сообщений в хранилище, загрузка генератора. Отдельно — байт
RSS на сообщение по наполнению.
- **Сырые данные и сводка** в `evidence/bench/<метка>/`: результат k6
каждого прогона, таблица всех прогонов, сводка по ячейкам (медиана и
разброс повторов), паспорт стенда (commit, версии, лимиты, железо).
- **Команды:** `make bench` — полная матрица с меткой (базовая —
`baseline`), `make bench_quick` — короткий прогон на малых размерах
для самопроверки стенда и защиты.
- **Базовый замер** текущего кода и раздел методики в `REPORT.md`
(«Эксперименты и отказы»): гипотезы, стенд, профиль нагрузки,
результаты, ограничения.
- **Не входит:** профилирование, поиск узкого места, изменение кода
приложения и сравнение «до/после» — это change `perf-bottleneck-fix`,
он повторит ту же матрицу со своей меткой. Open-loop нагрузка
(заданный темп запросов) и графики — тоже там, если понадобятся.
## Capabilities
### New Capabilities
- `load-benchmark`: воспроизводимый нагрузочный эксперимент трека 1 —
стенд с фиксированными лимитами, сценарии чтения и записи, матрица
размеров истории и конкуренции, метрики каждого прогона, сохранение
сырых данных и паспорта стенда, запуск одной командой.
### Modified Capabilities
Нет. Код приложения и его требования не меняются: стенд запускает тот
же образ, что и `make run_docker`, только с другими флагами
`docker run`.
## Impact
- **Новые файлы:** `bench/` (сценарии k6, оркестратор прогона),
`evidence/bench/baseline/`.
- **Изменяемые файлы:**
- `Makefile` — цели `bench` и `bench_quick`;
- `REPORT.md` — раздел экспериментов и строка трека 5 в таблице
доказательств;
- `AGENTS.md` — команды и карта кода;
- `.dockerignore` — `bench`;
- `.claude/rules/` — правило для `bench/`.
- **Код приложения и образ** не меняются. Образ для стенда собирается
из того же `Dockerfile` под отдельным тегом.
- **Окружение:** Docker, образ `grafana/k6` скачивается при первом
прогоне. Полная матрица занимает около 35–45 минут, из них около 10
минут — наполнение до 1M сообщений. Во время прогона ноутбук лучше
не нагружать.
@@ -0,0 +1,271 @@
# Spec Delta
## Purpose
Воспроизводимый нагрузочный эксперимент трека 1: одной командой
поднимает стенд с фиксированными лимитами, прогоняет матрицу размеров
истории и уровней конкуренции для чтения и записи и сохраняет сырые
данные, сводку и паспорт стенда, чтобы сравнивать версии кода при
одинаковых условиях.
## ADDED Requirements
### Requirement: Запуск одной командой
Полная матрица SHALL запускаться командой `make bench` с меткой
результата `BENCH_LABEL` (по умолчанию `baseline`), короткий прогон —
командой `make bench_quick`. Результаты SHALL сохраняться в
`evidence/bench/<метка>/`. Команда MUST NOT перезаписывать результаты
существующей метки и MUST NOT использовать порт 8080 хоста и
контейнеры `make run_dev` / `make run_docker`. После завершения, в том
числе с ошибкой или по Ctrl+C, контейнеры и сеть стенда SHALL
удаляться.
#### Scenario: Полная матрица
- **WHEN** выполняется `make bench BENCH_LABEL=baseline`
- **THEN** прогоняется вся матрица, результаты лежат в
`evidence/bench/baseline/`, код выхода 0
#### Scenario: Метка уже занята
- **WHEN** каталог `evidence/bench/<метка>/` уже существует
- **THEN** команда завершается с ненулевым кодом до запуска стенда и
называет каталог
#### Scenario: Рабочий стенд не затронут
- **WHEN** во время прогона запущен `make run_docker` на 8080
- **THEN** он продолжает отвечать, его контейнер и данные не меняются
#### Scenario: Прерывание
- **WHEN** прогон прерван Ctrl+C
- **THEN** контейнеры и сеть стенда удалены, частичные результаты
помечены как незавершённые
### Requirement: Фиксированный стенд
Приложение SHALL запускаться в контейнере из образа, собранного из
текущего checkout тем же `Dockerfile`, с одинаковыми во всех прогонах
лимитами: 1 CPU, 2 ГБ памяти без swap. Healthcheck образа SHALL быть
отключён, порты на хост MUST NOT публиковаться. Генератор нагрузки
SHALL работать в той же docker-сети и обращаться к приложению по имени
контейнера, минуя проброс портов хоста.
#### Scenario: Лимиты в паспорте
- **WHEN** прогон завершён
- **THEN** паспорт стенда содержит лимиты CPU и памяти контейнера
приложения, прочитанные у запущенного контейнера, и они одинаковы для
всех прогонов
#### Scenario: Нехватка памяти
- **WHEN** процесс приложения превысил лимит памяти и был убит
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
обычный результат
### Requirement: Сценарии нагрузки
Стенд SHALL поддерживать два сценария с синтетическими данными
фиксированной длины:
- `read` — запрос страницы истории (`limit=50`) чата из N сообщений.
Каждый запрос берёт курсор случайно из пула, равномерно покрывающего
всю историю. В пул входят только позиции, после которых есть не
меньше 50 сообщений, поэтому каждый ответ содержит ровно 50
элементов. Данные при этом не меняются;
- `write` — отправка сообщения в отдельный чат, чтобы история чата
сценария `read` оставалась ровно N.
Последовательность случайных выборов SHALL задаваться фиксированным
зерном из профиля, у каждого клиента — своя последовательность: при
том же профиле и том же N прогоны разных меток отправляют одинаковые
запросы, а одновременные клиенты не повторяют друг друга. Каждый ответ
SHALL проверяться на
ожидаемый статус; неожиданные статусы и ошибки соединения SHALL
считаться ошибками прогона.
#### Scenario: Полная страница
- **WHEN** выполняется любой запрос сценария `read`
- **THEN** ответ содержит ровно 50 сообщений
#### Scenario: Одинаковые запросы в разных метках
- **WHEN** один профиль запускается под двумя метками на одинаковом N
- **THEN** каждый клиент выбирает курсоры в той же последовательности,
что и в другой метке, а последовательности разных клиентов различны
#### Scenario: Чтение не меняет данные
- **WHEN** выполнены все прогоны `read` для размера N
- **THEN** в читаемом чате по-прежнему ровно N сообщений
#### Scenario: Ошибки учитываются
- **WHEN** часть ответов не 200 (`read`) или не 201 (`write`)
- **THEN** они входят в долю ошибок прогона и не входят в перцентили
задержки успешных запросов
### Requirement: Матрица и повторы
Полная матрица SHALL включать размеры истории 10 000, 100 000 и
1 000 000 сообщений, уровни конкуренции 1, 10 и 50 одновременных
клиентов и оба сценария, по 3 измеряемых прогона на ячейку. Перед
каждым измеряемым прогоном SHALL идти прогрев с той же нагрузкой, не
входящий в результат. Каждый размер SHALL начинаться с нового процесса
приложения, наполненного через HTTP API до ровно N сообщений в читаемом
чате. Рост хранилища за прогоны `write` SHALL фиксироваться в
результатах.
#### Scenario: Состав матрицы
- **WHEN** полная матрица завершена
- **THEN** в результатах 54 измеряемых прогона: 3 размера × 3 уровня
конкуренции × 2 сценария × 3 повтора
#### Scenario: Свежий процесс на каждый размер
- **WHEN** начинается размер N
- **THEN** контейнер приложения запущен заново и перед первым прогоном
содержит ровно N сообщений в читаемом чате
### Requirement: Метрики прогона
Для каждого измеряемого прогона SHALL сохраняться: сценарий, размер
истории, конкуренция, номер повтора, длительность, число успешных и
неуспешных запросов, успешные RPS, доля ошибок, задержки p50, p95, p99
и max успешных запросов, потреблённое приложением CPU, RSS процесса
приложения в начале, в конце и максимальный за прогон, число сообщений
в хранилище в начале и в конце, загрузка CPU генератора. Для каждого
размера SHALL сохраняться RSS до и после наполнения и оценка байт RSS
на сообщение.
Наполнение SHALL идти порциями, и для каждой порции SHALL сохраняться:
размер, число сообщений в хранилище до и после, успешные RPS, доля
ошибок, задержки p50, p95, p99 и max, CPU приложения и RSS в конце
порции. Так наполнение до 1 000 000 даёт кривую «запись при росте
хранилища» без дополнительного времени прогона.
#### Scenario: Строка прогона
- **WHEN** проверяющий открывает таблицу прогонов
- **THEN** у каждой строки заполнены все перечисленные поля
#### Scenario: Память на сообщение
- **WHEN** наполнение размера N завершено
- **THEN** в результатах есть прирост RSS за наполнение и байты на
сообщение
#### Scenario: Кривая наполнения
- **WHEN** наполнение размера 1 000 000 завершено
- **THEN** в таблице наполнения есть строка на каждую порцию, от
пустого хранилища до 1 000 000 сообщений, с RPS, p95, p99, max и
RSS
### Requirement: Достоверность прогона
Прогон SHALL помечаться в результатах, если его данные нельзя считать
замером сервера: процесс приложения перезапускался или был убит,
генератор нагрузки был загружен настолько, что мог сам ограничивать
throughput, или доля ошибок больше нуля. Сводка SHALL показывать эти
пометки рядом со значениями.
#### Scenario: Генератор упёрся в CPU
- **WHEN** загрузка CPU генератора за прогон выше порога, заданного в
методике
- **THEN** прогон помечен, и в сводке рядом с его ячейкой видна пометка
### Requirement: Ход прогона виден
Во время прогона команда SHALL печатать строку на каждый этап (сборка
образа, запуск стенда, наполнение, сбор курсоров, каждый измеряемый
прогон) с временем от начала. Наполнение SHALL показывать прогресс не
реже раза в минуту: сколько сообщений из N, скорость, оценку
оставшегося времени. После каждого измеряемого прогона SHALL
печататься его номер из общего числа, ячейка матрицы, основные
результаты (RPS, p50, p95, p99, CPU приложения, RSS, доля ошибок),
пометки и оценка времени до конца матрицы. В каталоге метки SHALL
поддерживаться файл текущего состояния, а строка прогона SHALL
дописываться в таблицу прогонов сразу после прогона.
#### Scenario: Где мы сейчас
- **WHEN** идёт наполнение размера 1M
- **THEN** в выводе не реже раза в минуту появляется строка с числом
отправленных сообщений, скоростью и оценкой оставшегося времени
#### Scenario: Результат сразу после прогона
- **WHEN** завершился измеряемый прогон
- **THEN** в выводе появляется строка вида «прогон k из 54, сценарий,
размер, конкуренция, повтор: RPS, p50/p95/p99, CPU, RSS, ошибки,
пометки, осталось ~T», а в таблице прогонов — его строка
#### Scenario: Наблюдение из другого терминала
- **WHEN** прогон запущен, и пользователь открывает файл состояния в
каталоге метки
- **THEN** там текущий этап, число завершённых прогонов из общего,
оценка оставшегося времени и результат последнего прогона
#### Scenario: Частичные результаты
- **WHEN** прогон прерван на середине матрицы
- **THEN** строки уже завершённых прогонов есть в таблице прогонов
### Requirement: Сохранение результатов
В каталоге метки SHALL лежать:
- сырой результат генератора для каждого прогона и каждой порции
наполнения;
- таблица всех прогонов в CSV;
- таблица порций наполнения в CSV;
- сводка по ячейкам матрицы (медиана и разброс min–max по повторам) в
Markdown;
- паспорт стенда: дата, commit и признак незакоммиченных изменений,
digest образа приложения, версии генератора и Python, лимиты, железо
хоста и VM, параметры профиля и команда запуска;
- состояние хоста в начале и в конце прогона: занятый swap, доля
свободной памяти, питание от сети или от батареи.
Если в начале прогона хост работает от батареи или swap занят сверх
порога методики, команда SHALL предупреждать об этом в выводе и в
паспорте, но не прерываться. Данные MUST быть синтетическими;
результаты MUST NOT содержать секретов, `.env` и абсолютных путей
домашнего каталога.
#### Scenario: Повтор на другой машине
- **WHEN** другой человек берёт паспорт и команду из каталога метки
- **THEN** он может запустить тот же профиль на своём checkout и
сравнить таблицы по тем же столбцам
#### Scenario: Условия хоста для сравнения меток
- **WHEN** проверяющий сравнивает две метки
- **THEN** по паспортам видно, одинаковы ли были swap, свободная
память и питание хоста в начале и в конце каждого прогона
#### Scenario: Неподходящий хост
- **WHEN** прогон запускается от батареи или с занятым swap выше порога
- **THEN** вывод команды и паспорт содержат предупреждение, а прогон
продолжается
### Requirement: Базовый замер в отчёте
Результат полной матрицы текущего кода SHALL быть сохранён под меткой
`baseline`. `REPORT.md` SHALL описывать в разделе экспериментов
гипотезы, стенд и лимиты, профиль нагрузки, результаты по ячейкам со
ссылкой на каталог `evidence/bench/baseline/` и ограничения замера.
#### Scenario: Проверяющий читает отчёт
- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md`
- **THEN** в нём есть гипотезы, условия стенда, таблица результатов и
путь к сырым данным
@@ -0,0 +1,129 @@
# Tasks
Как строить — `design.md`, что должно получиться — спек
`load-benchmark`. Код приложения (`src/`), `Dockerfile` и
`docker-compose.yml` в этом change не меняются. Перед первым файлом в
`bench/` написать правило `.claude/rules/bench.md` (задача 1.1) и
прочитать `.claude/rules/docker.md`. Полная матрица идёт около 40 минут:
во время неё ноутбук не нагружать и другие стенды не трогать.
## 1. Основа
- [x] 1.1 `.claude/rules/bench.md` (`paths: bench/**`, design,
решение 8) и строка в таблице правил `AGENTS.md`. Проверка: правило
называет неизменяемые между метками параметры (лимиты, профиль,
версия k6) и запрет импортировать `src`.
- [x] 1.2 `.dockerignore`: `bench`; `.gitignore`: `evidence/bench/quick-*`.
Проверка: `git ls-files -z -co --exclude-standard | tar --null -T -
-cf - | docker build -t mtusi-messenger:ctx-check -` собирается, в
образе нет `bench/` (`docker run --rm --entrypoint ls
mtusi-messenger:ctx-check -A /app` показывает только `.venv` и
`src`); временный тег удалить.
## 2. Сценарии k6
- [x] 2.1 `bench/k6/lib.js`, `prepare.js`, `prefill.js`, `cursors.js`
(design, решение 3). Проверка: вручную поднятый стенд из решения 2;
`prepare.js` → `fixture.json` с id читателя, участников и двух чатов;
две порции `prefill.js` по 1000 → в читаемом чате ровно 2000
сообщений; `cursors.js` → около `min(1000, N/100)` курсоров, первый
ведёт в начало истории, а после последнего остаётся не меньше 50
сообщений (запрос с ним и `limit=50` возвращает ровно 50).
- [x] 2.2 `bench/k6/read.js` и `write.js` (design, решение 4), итог
через `handleSummary` в JSON с `p(50)`, `p(95)`, `p(99)`, `max`
подметрики `expected_response:true`; выбор курсора — свой генератор
с зерном `seed + номер VU` (design, решение 4). Проверка на том же
стенде:
- `read` 5 с при 4 VU и `write` 500 запросов при 4 VU дают ненулевые
RPS и 0 ошибок;
- `check` на ровно 50 элементов в ответе `read` проходит у всех
запросов;
- два запуска `read` с одним зерном дают одинаковые первые курсоры
у каждого VU, а у разных VU они различаются;
- после `read` в читаемом чате по-прежнему 2000 сообщений.
## 3. Оркестратор
- [x] 3.1 `bench/run.py`: разбор аргументов (`--profile full|quick`,
`--label`), отказ при занятой метке, сборка образа
`mtusi-messenger:bench`, сеть и два контейнера по design (решение 2),
ожидание готовности через `docker exec`, уборка в `finally` и по
Ctrl+C. Проверка:
- занятая метка → ненулевой код до запуска контейнеров;
- Ctrl+C во время наполнения → `docker ps -a` и `docker network ls`
без `mtusi-bench-*`, в паспорте `incomplete`;
- `docker inspect mtusi-bench-api` показывает `NanoCpus=1e9`,
`Memory=MemorySwap=2 GiB`, без healthcheck и без опубликованных
портов.
- [x] 3.2 Цикл матрицы (design, решения 3–4): для каждого размера —
свежий контейнер, наполнение, курсоры, `read` × конкуренция × повторы
с прогревом, затем `write`. Проверка: `bench_quick` проходит все 18
прогонов (3 размера × 3 уровня × 2 сценария × 1 повтор) без ошибок.
- [x] 3.3 Метрики и пометки (design, решение 5): CPU по `cpu.stat`
обоих контейнеров, опрос `VmRSS` раз в секунду, `VmHWM`,
`memory.current`, счётчик сообщений, пометки `oom` / `app_down` /
`errors` / `generator`. Проверка:
- в `runs.csv` quick-прогона заполнены все столбцы спека
(«Метрики прогона»);
- в `prefill.csv` по строке на порцию с числом сообщений до и после,
RPS, p50/p95/p99/max, CPU и RSS; на временном профиле с
наполнением 120k — три строки (50k, 50k, 20k);
- CPU приложения на `read` с конкуренцией 16 близко к 1 ядру;
- пометка `oom` появляется на проверочном запуске с временно
уменьшенным лимитом памяти на размере 10k; после проверки лимит
вернуть.
- [x] 3.4 `meta.json` и `summary.md` (design, решения 5–6). Проверка:
- в паспорте quick-прогона есть все поля решения 6, в том числе
`host_state.start` и `host_state.end` со swap, свободной памятью и
питанием;
- запуск от батареи даёт предупреждение в выводе и в `host_warnings`,
а прогон продолжается;
- абсолютных путей домашнего каталога нет (`grep -r "/Users/"
evidence/bench/quick-*` пусто);
- сводка — таблица на сценарий с медианой и min–max, пометки рядом со
значениями, таблица байт на сообщение.
- [x] 3.5 Ход прогона (design, решение 5a): строки этапов и прогонов с
временем от начала и оценкой оставшегося, прогресс наполнения
порциями, `progress.json`, дозапись `runs.csv` после каждого прогона,
`summary.md` и при прерывании. Проверка на quick-прогоне:
- у каждого из 18 прогонов в выводе строка «прогон k из 18» с RPS,
p50/p95/p99, CPU, RSS, ошибками и оценкой времени;
- `cat evidence/bench/<метка>/progress.json` посреди прогона
показывает текущий этап и `runs_done`;
- после Ctrl+C посреди матрицы в `runs.csv` есть строки завершённых
прогонов, а `summary.md` построен по ним;
- наполнение 60k (временный профиль) печатает две строки прогресса.
## 4. Запуск
- [x] 4.1 Цели `bench` и `bench_quick` в `Makefile` (design,
решение 7). Проверка: `make -n bench` печатает команду с
`--label baseline`, `make -n bench BENCH_LABEL=x` — с `x`;
`make bench_quick` завершается с кодом 0, пока `make run_docker` на
8080 работает, и smoke против 8080 после этого проходит.
- [x] 4.2 `make lint`: ruff проверяет `bench/run.py` по правилам
проекта, `tests/` и `scripts/` не тронуты.
- [x] 4.3 Базовый замер: `make bench BENCH_LABEL=baseline` на
закоммиченном коде (в паспорте `dirty: false`). Перед запуском —
подготовка хоста по design, решение 6: пользователь перезагружает
ноутбук, подключает питание, останавливает посторонние контейнеры;
перезагрузка завершает сессию, продолжение — `/opsx:apply`. Проверка:
статус `complete`, 54 измеряемых прогона, `host_warnings` пусто,
пометок `generator`, `oom` и `app_down` нет. Если они есть — выяснить причину по правилу
`AGENTS.md` об упавших тестах и спросить, прежде чем менять профиль
или лимиты.
## 5. Документация
- [x] 5.1 `REPORT.md`, «Эксперименты и отказы» (design, решение 8):
таблица гипотез H1–H4 из раздела design «Гипотезы» без изменений
плюс столбец «Результат» с числами; стенд и лимиты, профиль, таблицы
из `evidence/bench/baseline/summary.md`, включая кривую наполнения
1M; ограничения. Строки «Выбранный трек 5» в таблице доказательств и
«TODO: эксперименты трека 5» в таблице отказов — базовый замер со
ссылкой на каталог. Проверка: в этих местах нет TODO; формулировки и
критерии опровержения гипотез совпадают с design; каждое число
совпадает со сводкой.
- [x] 5.2 `AGENTS.md`: команды `make bench` и `make bench_quick`, карта
кода `bench/` и `evidence/bench/`. Проверка: `openspec validate
load-bench-harness --strict` проходит.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-09-30
@@ -0,0 +1,430 @@
# Design
## Context
Мотивация — `proposal.md`. Здесь то, на что опираются решения.
**Что дал базовый замер** (`evidence/bench/baseline/`, commit
`60c098c`). При 10 и 50 клиентах приложение занимает 1,00 ядра. На
запрос уходит около 375 мкс CPU при чтении страницы из 50 сообщений и
около 255 мкс при записи. От 10k к 1M сообщений чтение теряет 6–9% RPS.
Вывод: потолок задаёт цена одного запроса в CPU, а не структура
данных. Значит, узкое место надо искать внутри обработки запроса.
**Предварительное разложение.** 2026-09-30 разовым скриптом (в
репозитории его нет) приложение вызывалось напрямую как ASGI на хосте
(macOS, Python 3.12.12), без uvicorn и сети, на коде commit `3cbdb74`.
Код приложения в нём тот же, что в `60c098c`: `git diff 60c098c
3cbdb74 -- src Dockerfile pyproject.toml uv.lock` пуст.
| Часть запроса | Чтение, мкс | Запись, мкс |
|---|---|---|
| Всего внутри приложения | 292 | 168 |
| JSON ответа | 97 | — |
| из него форматирование времени | 64 | — |
| DTO → модель ответа | 27 | — |
| Логи (INFO против WARNING) | 27 | 52 |
| Остальное: маршрутизация, зависимости FastAPI, сервис | ~140 | ~116 |
Разница между стендом и этим замером — 83 мкс на чтении и 87 мкс на
записи. Она одинакова для двух сценариев, как и должна быть у части
«сервер и сокет», которая от сценария не зависит. Это косвенная
проверка разложения, а не доказательство: хост и контейнер — разные
системы.
Числа предварительные. Этот change повторяет разложение
воспроизводимой командой в образе стенда (решение 2) и опирается уже
на её вывод.
**Пробное разложение в образе стенда.** 2026-09-30, `make bench_inproc`
с пробной меткой, инструмент ещё не закоммичен, хост не подготовлен
(шумно: разброс запусков до 8%). Картина отличается от замера на хосте:
| Часть запроса | Чтение, мкс | Запись, мкс |
|---|---|---|
| Всего внутри приложения | 338 | 216 |
| логи: запись в stdout контейнера | 43 | 35 |
| логи: сборка записи (structlog, JSON) | 26 | 55 |
| форматирование времени в ответе | 55 | — |
| JSON ответа без форматирования времени | 31 | — |
| DTO → модель ответа | 28 | — |
| Остальное: маршрутизация, зависимости FastAPI, сервис | 155 | 126 |
- Логи в контейнере стоят 69 мкс на чтение и 90 мкс на запись, а не 27
и 52. Разницу даёт запись в stdout контейнера: около 40 мкс на
запрос независимо от числа строк. На хосте вывод шёл в `/dev/null`,
и этой части не было видно.
- Форматирование времени стоит те же 55 мкс, но `isoformat` экономит
из них 27, а не 34 (разовый замер в образе: JSON страницы 88 → 61
мкс, три запуска).
- Стенд минус приложение: 37 мкс на чтении, 39 на записи.
По решению 3 такая картина — повод пересмотреть выбор до правки кода.
Пользователь пересмотрел и оставил форматирование времени
(2026-09-30): логирование — базовая функциональность, менять его ради
замера он не хочет. Решения ниже пересчитаны от чисел из образа стенда.
**Почему время форматируется через `strftime`.** Решение 3 design
архива `2026-09-29-messenger-core-api`: время сериализуется явно, в
формат `YYYY-MM-DDTHH:MM:SS.ffffffZ`, через сериализатор полей в
моделях ответа, потому что pydantic сам пишет `...Z`, но при нулевых
микросекундах опускает дробную часть (проверено тогда). Фиксированная
ширина делает формат предсказуемым и одинаковым в ответе и в курсоре.
Это решение о том, *какую* строку отдавать. *Чем* её строить, в design
не обсуждалось: `strftime` записывает формат одной константой
`RFC3339_FORMAT`, и та же константа разбирает курсор через `strptime`.
Цена форматирования тогда не измерялась. Для логгера такой замер есть
(`.claude/rules/logging.md`, поиск места вызова), для времени в ответе
его не делали.
## Goals / Non-Goals
**Goals:**
- Найти узкое место измерением, которое можно повторить командой из
репозитория, и сохранить вывод.
- Внести одно изменение, не меняющее наблюдаемого поведения API.
- Измерить дельту так, чтобы её нельзя было спутать с шумом между
прогонами, и записать предсказание до замера.
- Объяснить в отчёте прежнее решение, механизм улучшения и его границы.
**Non-Goals:**
- Убрать все найденные затраты. Логи, маршрутизация и зависимости
FastAPI, промежуточная модель ответа остаются как есть и попадают в
отчёт как следующие кандидаты.
- Менять стенд: `bench/run.py`, сценарии k6, профиль `full` и лимиты.
- Профилировать процесс внутри работающего стенда (py-spy).
- Open-loop нагрузка с заданным темпом. В design `load-bench-harness`
она значилась кандидатом для этого change; решено не добавлять
(пользователь, 2026-09-30): правка меняет цену запроса, а её меряет
пропускная способность при насыщении. Заниженные хвосты остаются
названным ограничением замера.
- Лечить паузы сборки мусора: на RPS они не влияют (H4 базового
замера).
## Decisions
### 1. Как ищем узкое место: три приёма и сверка
Один профилировщик не даёт ответа в микросекундах, поэтому приёмов три.
- **Выключение.** Один и тот же запрос меряется в трёх режимах логов:
INFO, как на стенде; INFO с stdout процесса в `/dev/null`; WARNING.
Запись ниже уровня отбрасывается первым же процессором structlog,
поэтому INFO минус WARNING — полная цена логов. Режим с `/dev/null`
делит её на сборку записи и запись в stdout контейнера.
- **Изоляция и подмена.** Построение ответа страницы меряется отдельно
от запроса: DTO → модель, модель → JSON. JSON меряется в трёх
вариантах: с текущим сериализатором времени, с эталонным `strftime`
и вообще без Python-сериализатора. Разницы между вариантами — цена
форматирования и цена самого вызова Python-функции из pydantic.
- **Профиль вызовов (cProfile).** Даёт число вызовов на запрос (51
вызов `to_rfc3339` на чтение: 50 сообщений и курсор) и порядок
функций по суммарному времени. Доли времени из него не берутся:
cProfile завышает цену кода, где много мелких Python-вызовов.
- **Сверка.** Стоимость запроса на стенде минус стоимость внутри
приложения должна быть примерно одинаковой для чтения и записи.
Каждое измерение — медиана нескольких повторов с разбросом min–max.
*Альтернативы.* py-spy в соседнем контейнере (`--pid=container:...`,
`SYS_PTRACE`) видит настоящий сервер под настоящей нагрузкой, но даёт
доли выборок, а не микросекунды, не умеет подмену и требует ещё одного
образа и привилегии. Отложен: пригодится, если разложение внутри
процесса и результат стенда разойдутся. Один cProfile отклонён по
причине выше.
### 2. Диагностика запускается в образе стенда
`bench/inproc.py` работает в двух режимах.
- **На хосте** (только stdlib, приложение не импортируется): проверяет,
что метка свободна, собирает образ `mtusi-messenger:bench` тем же
`docker build`, что и стенд, запускает контейнер с `--cpus=1` и
скриптом, смонтированным только для чтения, собирает результаты и
пишет `evidence/profile/<метка>.txt` с датой, commit, признаком
незакоммиченных изменений, id образа и версиями.
- **В контейнере** (`--child`): импортирует приложение, наполняет
хранилище синтетикой (20 000 сообщений по 64 символа, фиксированное
зерно), меряет и отдаёт результаты отдельным каналом. Логи приложения
идут в stdout контейнера, как на стенде.
Контейнер запускается по три раза в каждом из трёх режимов логов,
режимы чередуются. Уровень читается при импорте настроек, поэтому
переключить его внутри одного процесса нельзя. Несколько запусков
нужны, потому что время запроса гуляет от запуска процесса к запуску
на 1–3%, а цена логов — разность между разными запусками. Варианты
форматтера сравниваются внутри одного процесса, и на них этот шум не
ложится.
Контейнер отсоединён (`docker run -d`), результат забирается из
`docker logs`: так же запущен контейнер стенда. С подключённым клиентом
docker логи обходились процессу заметно дороже (97 и 145 мкс на запрос
против 69 и 90).
Почему в образе, а не на хосте: у предварительного замера другой
Python (3.12.12 против 3.12.14) и другая libc, а `strftime` — как раз
вызов libc. Цена форматирования на Linux может отличаться, и от неё
зависит предсказание.
Команда: `make bench_inproc BENCH_LABEL=<метка>`, около двух минут. В
этой же команде — сверка форматтера с эталоном (решение 5).
### 3. Узкое место — форматирование времени в ответе чтения
Критерии выбора: доля в запросе; можно ли убрать одним локальным
изменением; не меняет ли оно поведение, контракт и рубрику.
Доли — от пробного разложения в образе стенда (Context).
| Кандидат | Цена | Одно локальное изменение | Что мешает |
|---|---|---|---|
| Форматирование `created_at` в странице истории | 55 мкс чтения; `isoformat` снимает 27 | да, одна функция | ничего |
| Логи: запись в stdout контейнера | 43 мкс чтения, 35 записи | да: писать порциями, а не на каждую запись | меняет поведение журнала: строки появляются с задержкой, при SIGKILL и OOM теряется последняя порция. **Отклонён пользователем:** логирование — базовая функциональность |
| Логи: сборка записи | 26 мкс чтения, 55 записи | нет: перестройка конвейера structlog | рубрика уровня 4 требует логов, состав записей закреплён спеком `service-logging` |
| DTO → модель ответа | 28 мкс чтения | да | меняет устройство слоя API (`api-layer.md`) |
| Маршрутизация и зависимости FastAPI, сервис | 155 мкс чтения, 126 записи | нет: размазано по фреймворку | отказ от цепочки `Depends` |
| Паузы сборки мусора | 0% RPS, только max | — | не про пропускную способность |
Форматирование времени — самая крупная затрата, сосредоточенная в
одной функции, которую можно убрать, не меняя поведения сервиса.
Запись логов в stdout сопоставима по цене и задевает оба сценария, но
её удешевление меняет поведение журнала; в отчёт она идёт как
найденный, измеренный и не применённый кандидат. Её цена измерена
только в Docker Desktop: на обычном Linux она может быть другой.
### 4. Изменение: `isoformat` вместо `strftime`
```python
def to_rfc3339(value: datetime) -> str:
text = value.astimezone(UTC).isoformat(timespec="microseconds")
# после astimezone(UTC) смещение всегда «+00:00»
return text[:-6] + "Z"
```
`timespec="microseconds"` даёт шесть знаков и при нулевых
микросекундах. `astimezone(UTC)` остаётся: значение в другом часовом
поясе по-прежнему приводится к UTC. `RFC3339_FORMAT` и `from_rfc3339`
не меняются.
JSON страницы из 50 сообщений в образе стенда (разовый замер, три
запуска процесса; одно значение — 1,22 против 0,72 мкс):
| Вариант | JSON страницы, мкс | Память | Почему да или нет |
|---|---|---|---|
| `strftime` (сейчас) | 88 | — | — |
| **`isoformat`** | 61 | без изменений | выбран: одна функция, ничего больше не трогает |
| Готовая строка в DTO, сделанная при записи | 31 | +76 байт на сообщение (+16%) | отклонён: строка представления в DTO (`dto.md`), два поля одного значения, предел по памяти падает с ~4,4 до ~3,8 млн сообщений, в лабе 2 записи приходят из Postgres и приём не переносится |
| Встроенная сериализация pydantic | 31 | без изменений | отклонён: опускает дробную часть при нулевых микросекундах — из-за этого прежнее решение и было принято |
После изменения остаётся около 30 мкс из 61: pydantic по-прежнему
вызывает Python-функцию на каждое сообщение. Убрать этот вызов можно
только вариантами, отклонёнными выше.
### 5. На что влияет изменение
| Место | Влияние |
|---|---|
| Ответы с `Message`, `Chat`, `User` (сериализатор `UtcDatetime`) | та же строка, дешевле: 50 вызовов на страницу истории, до 100 на страницу списка чатов, один на одиночный объект |
| `encode_cursor` (курсоры истории и списка чатов) | та же строка; выданные курсоры побайтно те же |
| `from_rfc3339`, разбор курсора | не затронут |
| Порядок `(created_at, id)`, `bisect`, хранилище, память | не затронуты: `datetime` в DTO остаётся |
| Логи | не затронуты: время в логах ставит structlog |
| Контракт, `/openapi.json`, схемы ответов | не затронуты |
| Запись сообщения | один вызов на ответ, экономия меньше микросекунды |
| Лаба 2 | функция переносится как есть: она не зависит от хранилища |
Инварианты (`api-contract.md`: UTC, суффикс `Z`, одна точность при
хранении и выдаче) проверяются тремя способами:
- сверка в `make bench_inproc`: `to_rfc3339` против эталонной записи
`astimezone(UTC).strftime(RFC3339_FORMAT)` на случайных значениях
1970–2100 годов с фиксированным зерном и на граничных (микросекунды
0, 1, 999999; смещения +03:00 и −08:00; последняя секунда года),
плюс обратный разбор `from_rfc3339`;
- `make student_test`: регулярное выражение на шесть знаков и `Z` в
каждом теле с `created_at`, порядок и постраничный обход;
- `make test`: публичный smoke.
Вне проверки — годы до 1000: там `strftime` зависит от платформы.
Время назначает только `utcnow()`, такие значения недостижимы.
### 6. Предсказание, записанное до замера (H5)
Продолжает нумерацию гипотез `REPORT.md`. В отчёт переносится до
прогона «после».
- **Гипотеза.** Чтение страницы дешевеет на цену форматирования,
запись не меняется, память не меняется.
- **Предсказание.** CPU на запрос чтения падает на 20–30 мкс во всех
ячейках `read`. RPS чтения растёт на 5–8%: при 10 и 50 клиентах
около 7% (2663 → около 2870 на 10k), при одном клиенте около 6%,
потому что часть цикла запроса проводит клиент. Ячейки `write` —
изменение в пределах шума. Байты на сообщение — в пределах ±1%.
Зависимость от размера истории не меняется.
- **Что опровергнет.** Изменение RPS чтения в пределах шума; либо
ячейки `write` меняются сопоставимо с `read` — тогда разницу дали
условия прогона, а не изменение.
Диапазон получен от цены в образе стенда: `isoformat` снимает 27 мкс
с запроса чтения, который на стенде стоит 373–444 мкс в разных
ячейках (`baseline`, CPU приложения на запрос). Первая оценка,
по замеру на хосте, была выше: 34 мкс и RPS +7–12%. Она записана здесь
же, чтобы было видно, что предсказание пересчитано до замера, а не
после.
Известный риск: ожидаемый эффект близок к уровню шума. Пробные метки
одного кода из разных сессий расходились на 2–4% по медиане ячеек.
Если правило из решения 7 отнесёт часть ячеек к шуму, отчёт так и
скажет.
### 7. Методика измерения дельты
**Метки.**
| Метка | Код приложения | Сессия хоста |
|---|---|---|
| `baseline` | до изменения (`60c098c`) | первая, 2026-09-30 |
| `baseline-rerun` | до изменения | вторая |
| `ts-isoformat` | после изменения | вторая, сразу за `baseline-rerun` |
Все три — `make bench`, профиль `full`, те же лимиты и генератор.
Фактически перезагрузки перед второй парой не было: хост оставался в
том же состоянии, что при `baseline` (swap 0, питание от сети,
контейнеров нет), и пользователь решил её не делать. Все три метки
сняты в одной загрузке системы; `baseline` и `baseline-rerun` разделяют
2 часа 22 минуты. Ниже «сессии разные» читать как «прогоны разнесены
во времени».
- **Дельта (A/B):** `baseline-rerun` против `ts-isoformat`. Одна
сессия после перезагрузки, один и тот же код стенда, код приложения
отличается одной функцией.
- **Уровень шума (A/A):** `baseline` против `baseline-rerun`. Код
приложения одинаков, сессии разные, между ними есть правки стенда из
`3cbdb74` (проверка `tail.js`, зерно прогрева в профиле, окончания
строк CSV). Уровень шума сценария — наибольшее по девяти ячейкам
изменение медианы RPS. Это оценка сверху: шум между сессиями не
меньше шума внутри сессии, в которой снята дельта.
- **Статистика.** В ячейке три повтора: медиана и разброс min–max.
Дельта — отношение медиан минус единица.
- **Правило.** Изменение в ячейке — эффект, если разбросы повторов
двух меток не пересекаются и изменение медианы больше уровня шума её
сценария. Правило записано до замера и применяется командой, а не
вручную.
- **Контроль.** Ячейки `write`: изменение их почти не касается. Если
они сдвинулись так же, как `read`, дельта не засчитывается.
- **CPU на запрос** = `app_cpu_cores / rps`. При 10 и 50 клиентах ядро
занято полностью, поэтому RPS — обратная величина этой цены, и
именно она сравнивается с предсказанием в микросекундах.
*Альтернатива:* сравнить `ts-isoformat` прямо с существующим
`baseline`, контроль — только ячейки записи. На 18 минут дешевле.
Отклонена: `baseline` снят в другой сессии и до правок стенда, а
уровень шума пришлось бы предполагать. При ожидаемом эффекте около 10%
это слишком слабое основание.
**Порядок внутри сессии.** Сначала `baseline-rerun`, сразу за ним
`ts-isoformat`, без перезагрузки и без другой работы на хосте между
ними: правка написана, проверена и закоммичена заранее (решение 9).
Порядок «сначала до, потом после» один, без чередования: возможный
дрейф внутри сессии видят ячейки `write`.
### 8. Сравнение меток — командой
`bench/compare.py` (только stdlib, читает `runs.csv` и `meta.json`
двух меток): `make bench_compare BEFORE=... AFTER=... [AA=...]`,
результат — `evidence/compare/<до>__<после>.md` и тот же текст в
терминал. Что в таблице и когда команда отказывается — спек
`load-benchmark`, требование «Сравнение двух меток».
Почему скрипт, а не подсчёт в отчёте: в разделе базового замера
ручной счёт уже дал три неточности, найденные при проверке. Таблица
сравнения выводится из неизменяемых каталогов меток, поэтому файл
можно пересоздавать.
Известная особенность: в паспорте `baseline` нет параметра
`warmup_seed_shift`, он появился в профиле позже. В коде `60c098c` это
константа с тем же значением 1 000 003. Команда перечислит параметр
как непроверенный, отчёт сошлётся на константу.
### 9. Порядок работ и паузы
Полная матрица идёт около 18 минут, а одна команда агента ограничена
10 минутами, поэтому оба прогона запускает пользователь.
1. Инструменты, правила, пробный запуск диагностики, commit.
2. До перезагрузки: H5 в отчёт, commit; правка, commit; тесты и
пробное разложение на этом commit; откат правки отдельным commit
(`git revert`). Рабочее дерево снова содержит код «до».
3. Пауза: пользователь готовит хост и запускает одну команду. Между
прогонами нет ни работы агента, ни тестов, ни сборок, кроме сборки
образа стендом:
```sh
make bench_ab BEFORE=baseline-rerun AFTER=ts-isoformat REAPPLY=184ed27
```
`bench/ab.py` выполняет по шагам: `make bench` и `make bench_inproc`
для `baseline-rerun`, commit их результатов, `git revert 184ed27`,
затем `make bench` и `make bench_inproc` для `ts-isoformat`. Шаг
завершился с ошибкой — следующие не выполняются. На нечистом
рабочем дереве и с занятыми метками команда не стартует.
Стенд идёт первым в каждой паре: его признак `dirty` считается по
всему дереву, и файл разложения, появившийся раньше, поднял бы его.
`git revert` commit отката возвращает правку новым commit.
Состояния кода: правка — `6fed684` (на нём прошли smoke и 79
собственных тестов, `evidence/tests/ts-isoformat.txt`), откат —
`184ed27` (код приложения снова совпадает с `60c098c`).
4. Сравнения A/A и A/B, сравнение двух разложений, отчёт.
**Каждое измеренное состояние кода — commit** (указание пользователя,
2026-09-30). Перед любым замером или тестом, результат которого идёт в
отчёт, состояние кода коммитится, и хеш попадает в шапку файла
доказательства и в `REPORT.md`. То же для пробных изменений, которые
потом откатываются: изменение — отдельный commit, откат — новый commit
поверх (`git revert`), без переписывания истории. Так любое число в
отчёте можно воспроизвести из названного commit. Эти коммиты делает
агент; push и остальные операции git — по-прежнему только по просьбе.
Следствия: в паспортах меток стенда `dirty: false`, а commit меток «до»
и «после» различаются ровно правкой приложения и её доказательствами.
В `inproc.py` признак незакоммиченных изменений считается только по
файлам приложения, образа и самому скрипту: иначе его поднимал бы ещё
не закоммиченный каталог только что снятой метки.
### 10. Граница чёрного ящика в `bench/`
Правило `bench.md` «`bench/` не импортирует `src`» сужается: оно
действует на стенд (`run.py`, `k6/`) и на `compare.py`. Единственное
исключение — режим `--child` в `inproc.py`: разложить время внутри
процесса снаружи нельзя. В правило добавляется, что числа диагностики
не попадают в таблицы результатов стенда.
## Risks / Trade-offs
- **Эффект окажется меньше предсказанного или в пределах шума** →
отчёт говорит об этом прямо (спек, сценарий «Предсказание не
подтвердилось»). Второе изменение поверх не вносится без решения
пользователя.
- **Цена `strftime` в Linux отличается от замера на macOS** →
разложение повторяется в образе стенда до правки кода, предсказание
пересчитывается.
- **Шум между сессиями окажется сопоставим с эффектом** → правило
отметит ячейки как «в пределах шума»; тогда опора — CPU на запрос и
разложение «до/после» внутри процесса, и в отчёте это названо
ограничением.
- **Два прогона по 18 минут подряд** → время пользователя; хост в это
время не нагружать.
- **Диагностика внутри процесса не видит сервер и сокет** → она
объясняет, а меряет стенд; в её выводе это написано.
- **`inproc.py` зависит от устройства приложения** (создание хранилища
в lifespan, пути API) → в лабе 2 его придётся править вместе с
приложением.
- **Срез `[:-6]` полагается на смещение `+00:00`** → его гарантирует
`astimezone(UTC)` в той же строке; сверка с эталоном включает
значения с другим смещением.
- **Откат** — вернуть одну функцию; данных и миграций нет.
@@ -0,0 +1,92 @@
# Proposal
## Why
Базовый замер трека 1 (`evidence/bench/baseline/`) показал, что потолок
сервиса — CPU одного ядра: около 375 мкс на чтение страницы из 50
сообщений и около 255 мкс на запись, и от размера истории эта цена
почти не зависит. Трек 1 (`README.md`) требует вторую половину: найти
узкое место, внести одно изменение, сравнить «до/после» при тех же
лимитах и объяснить, почему улучшение работает. Она не сделана.
Предварительное разложение стоимости запроса (2026-09-30, разовый
скрипт вне репозитория) показало конкретную точку: `created_at` в
ответе форматирует Python-функция `to_rfc3339` через `strftime`, и
pydantic вызывает её на каждое сообщение страницы. Это около 64 мкс из
292 мкс, которые чтение тратит внутри приложения.
## What Changes
- **Одно изменение кода:** `to_rfc3339` (`src/utils/utc.py`) строит
строку через `isoformat(timespec="microseconds")` вместо `strftime`.
Вывод побайтно тот же: RFC 3339, UTC, шесть знаков микросекунд, `Z`.
Контракт, схема ответа, курсоры и объём памяти не меняются.
- **Как нашли узкое место — в репозитории.** Разовый скрипт
превращается в диагностическую команду `make bench_inproc`: она
раскладывает время запроса на части и сохраняет вывод в `evidence/`.
Этой же командой проверяется, что новый форматтер выдаёт те же строки,
что и прежний.
- **Как меряем дельту — в репозитории.** Команда `make bench_compare`
сравнивает две метки стенда по ячейкам матрицы, отказывается
сравнивать метки с разной методикой и отделяет эффект от шума.
- **Два прогона полной матрицы в одной сессии хоста:** повтор базового
замера на коде до изменения (`baseline-rerun`) и замер после
(`ts-isoformat`). Сравнение `baseline` с `baseline-rerun` (один и тот
же код приложения, прогоны разнесены во времени) даёт измеренный
уровень шума. Оба прогона запускает одна команда `make bench_ab`:
изменение заранее закоммичено и откачено, команда снимает «до»,
возвращает изменение и снимает «после».
- **Каждое измеренное состояние кода — commit**, хеш идёт в
доказательства и отчёт (указание пользователя при реализации).
- **Отчёт.** В разделе трека 1 `REPORT.md` появляются: как искали узкое
место и что нашли; почему прежнее решение было выбрано; что именно
изменено и на что это влияет; предсказание, записанное до замера;
методика измерения дельты; результаты «до/после»; почему улучшение
работает и что осталось. Заполняется раздел «Ограничения и следующие
шаги».
- **Правила:** `.claude/rules/bench.md` и `AGENTS.md` дополняются
новыми командами и границей между чёрным ящиком стенда и
диагностикой, которая импортирует приложение.
Не входит в изменение: удешевление логов, цена маршрутизации и
зависимостей FastAPI, паузы сборки мусора, хранение готовой строки
времени в DTO. Это остаётся в отчёте как следующие кандидаты.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `load-benchmark`: добавляются требования к диагностике стоимости
запроса, к сравнению двух меток, к прогонам «до» и «после» подряд и
к описанию сравнения «до/после» в отчёте. Существующие требования
стенда и базового замера не меняются.
Спек `api-conventions` не меняется: требование к представлению времени
остаётся прежним, меняется только способ получить ту же строку.
## Impact
- **Код приложения:** одна функция `to_rfc3339` в `src/utils/utc.py`.
Её вызывают сериализатор `UtcDatetime` (ответы с `User`, `Chat`,
`Message`) и `encode_cursor` (курсоры истории и списка чатов).
`from_rfc3339`, порядок `(created_at, id)`, хранилище и логи не
затронуты.
- **Поведение API:** не меняется. Проверяют `make test`,
`make student_test` (формат `created_at` сверяется в каждом теле) и
сверка нового форматтера с прежним.
- **Стенд:** новые файлы `bench/inproc.py`, `bench/compare.py` и
`bench/ab.py`, цели `bench_inproc`, `bench_compare` и `bench_ab` в
`Makefile`. `bench/run.py`, сценарии k6, лимиты и профиль `full` не
меняются.
- **Зависимости:** новых нет.
- **Доказательства:** `evidence/bench/baseline-rerun/`,
`evidence/bench/ts-isoformat/`, `evidence/profile/`,
`evidence/compare/`, `evidence/tests/ts-isoformat.txt`.
- **Git:** `make bench_ab` сам создаёт два commit в текущей ветке
(доказательства прогона «до» и возврат изменения); push не делает.
- **Время пользователя:** около 40 минут работы `make bench_ab` на
подготовленном хосте. Запускает его пользователь в своём терминале.
@@ -0,0 +1,212 @@
# Spec Delta
## ADDED Requirements
### Requirement: Разложение стоимости запроса
Команда `make bench_inproc` SHALL раскладывать время обработки одного
запроса внутри приложения на части, чтобы узкое место находилось
измерением, а не догадкой. Приложение SHALL вызываться в том же
процессе, без сервера и сети, на синтетических данных с фиксированным
зерном. Вывод SHALL содержать:
- время на запрос сценариев `read` и `write` при обычном уровне логов
и при выключенных записях уровня INFO; разница — цена логов, отдельно
сборка записи и запись в stdout контейнера;
- время частей построения ответа страницы истории, в том числе вариант
без форматирования времени в Python; разница — цена форматирования;
- функции с наибольшим собственным временем и числом вызовов на запрос;
- медиану и разброс min–max каждого измерения: по запускам процесса
для времени на запрос, по повторам для частей ответа;
- дату, commit, признак незакоммиченных изменений, версии Python и
библиотек, машину хоста.
Результат SHALL сохраняться в `evidence/profile/<метка>.txt`. Команда
MUST NOT перезаписывать файл существующей метки. Числа этой команды
MUST NOT выдаваться за результат стенда: она объясняет, куда уходит
время, а пропускную способность и задержки меряет только `make bench`.
Команда SHALL также сверять текущее форматирование времени с эталонной
записью формата `ГГГГ-ММ-ДДTЧЧ:ММ:СС.ffffffZ` на наборе значений,
включающем нулевые микросекунды и время в другом часовом поясе, и
проверять, что строка разбирается обратно в то же значение. При
расхождении команда SHALL завершаться с ненулевым кодом и называть
значение.
#### Scenario: Разложение чтения
- **WHEN** выполняется `make bench_inproc BENCH_LABEL=<метка>`
- **THEN** в `evidence/profile/<метка>.txt` есть время на запрос `read`
и `write`, цена логов, цена построения ответа и цена форматирования
времени, у каждого числа — медиана и разброс
#### Scenario: До и после изменения
- **WHEN** команда выполнена на коде до изменения и на коде после него
под разными метками
- **THEN** по двум файлам видно, какая часть запроса подешевела и на
сколько, а какие части не изменились
#### Scenario: Метка уже занята
- **WHEN** файл `evidence/profile/<метка>.txt` уже существует
- **THEN** команда завершается с ненулевым кодом и называет файл
#### Scenario: Формат времени изменился
- **WHEN** форматирование времени даёт строку, отличную от эталонной,
хотя бы для одного значения набора
- **THEN** команда завершается с ненулевым кодом и печатает значение,
ожидаемую и полученную строки
### Requirement: Сравнение двух меток
Команда `make bench_compare BEFORE=<метка> AFTER=<метка>` SHALL
сравнивать результаты двух меток полной матрицы и сохранять таблицу в
`evidence/compare/<до>__<после>.md`. Для каждой ячейки матрицы таблица
SHALL содержать медиану и разброс min–max повторов RPS в обеих метках,
изменение медианы в процентах, медианы p50, p95 и p99 и CPU приложения
на один запрос. Для каждого размера истории — байты RSS на сообщение в
обеих метках.
Команда SHALL отказываться сравнивать метки, снятые разной методикой:
если различаются параметры профиля, лимиты контейнера приложения или
образ генератора, она завершается с ненулевым кодом, называет
различие и не создаёт таблицу. Параметр, записанный в паспорте только
одной из меток, SHALL перечисляться в таблице как непроверенный, без
отказа. Незавершённая метка, незакоммиченные изменения, предупреждения
о хосте и помеченные прогоны SHALL перечисляться в начале таблицы.
С необязательным параметром `AA=<метка>` команда SHALL оценивать
уровень шума: наибольшее по ячейкам сценария изменение медианы RPS
между метками `AA` и `BEFORE`, снятыми на одном и том же коде
приложения. Изменение в ячейке SHALL называться эффектом, только если
разбросы повторов двух меток не пересекаются и изменение медианы
больше уровня шума её сценария; иначе — изменением в пределах шума.
#### Scenario: Сравнимые метки
- **WHEN** сравниваются две завершённые метки одного профиля с
одинаковыми лимитами и генератором
- **THEN** в таблице 18 ячеек (2 сценария × 3 размера × 3 уровня
конкуренции) с медианами, разбросом и изменением в процентах, а в
начале — commit и условия хоста каждой метки
#### Scenario: Разная методика
- **WHEN** у меток различается параметр профиля, лимит контейнера или
образ генератора
- **THEN** команда завершается с ненулевым кодом, называет параметр и
оба значения, таблица не создаётся
#### Scenario: Параметр только в одной метке
- **WHEN** параметр профиля записан в паспорте одной метки и отсутствует
в паспорте другой
- **THEN** сравнение выполняется, а параметр назван в таблице как
непроверенный
#### Scenario: Уровень шума
- **WHEN** задан `AA` — метка того же кода приложения, что и `BEFORE`
- **THEN** таблица содержит уровень шума по каждому сценарию и для
каждой ячейки вывод: эффект или изменение в пределах шума
#### Scenario: Метка сама с собой
- **WHEN** `BEFORE` и `AFTER` — одна и та же метка
- **THEN** изменение во всех ячейках равно нулю
### Requirement: Прогоны «до» и «после» подряд
Команда `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=<commit>`
SHALL снимать метки «до» и «после» одного изменения подряд, без
работы на хосте между ними. В рабочем дереве лежит код «до», а
изменение закоммичено и откачено отдельным commit; `REAPPLY` — commit
отката. Команда SHALL по порядку выполнить: полную матрицу и
разложение стоимости запроса для `BEFORE`, commit их результатов,
возврат изменения новым commit, полную матрицу и разложение для
`AFTER`. Матрица SHALL идти раньше разложения, чтобы в паспорте метки
не было признака незакоммиченных изменений.
Команда SHALL отказываться стартовать, ничего не запустив, если
рабочее дерево не чистое, файлы одной из меток уже существуют, метки
совпадают или commit `REAPPLY` не найден в текущей ветке. Если шаг
завершился с ошибкой, следующие шаги MUST NOT выполняться, а команда
SHALL назвать этот шаг. Команда создаёт commit в текущей ветке и MUST
NOT отправлять его в удалённый репозиторий.
#### Scenario: Оба прогона без участия человека
- **WHEN** на чистом рабочем дереве выполняется `make bench_ab` со
свободными метками и commit отката
- **THEN** обе метки сняты полностью, у обеих в паспорте нет признака
незакоммиченных изменений, а код приложения между их commit
отличается возвращённым изменением
#### Scenario: Нечистое рабочее дерево
- **WHEN** в рабочем дереве есть незакоммиченные изменения
- **THEN** команда завершается с ненулевым кодом до первого шага и
называет причину
#### Scenario: Метка занята
- **WHEN** каталог метки стенда или файл разложения одной из меток уже
существует
- **THEN** команда завершается с ненулевым кодом до первого шага и
называет путь
#### Scenario: Шаг завершился с ошибкой
- **WHEN** один из шагов вернул ненулевой код
- **THEN** следующие шаги не выполняются, команда называет номер шага
и завершается с ненулевым кодом
### Requirement: Сравнение «до/после» в отчёте
Результаты полной матрицы на коде до изменения и после него SHALL
быть сохранены под разными метками, снятыми в одной сессии хоста при
одинаковых лимитах и одном профиле. Между этими метками код приложения
SHALL отличаться одним изменением. `REPORT.md` SHALL описывать в
разделе экспериментов:
- как искали узкое место: метод, числа и путь к сохранённому выводу;
- почему прежнее решение было выбрано и что при этом не измерялось;
- что именно изменено, какие части сервиса это затрагивает и какие
свойства ответа сохраняются;
- предсказание результата, записанное до замера «после», и условие,
при котором оно считается опровергнутым;
- методику измерения дельты: какие метки сравниваются, как оценён
уровень шума и по какому правилу изменение считается эффектом;
- результаты по ячейкам со ссылкой на таблицу сравнения и каталоги
меток, включая ячейки, где эффекта нет;
- почему изменение дало такой результат и что осталось узким местом;
- ограничения сравнения.
Результат SHALL записываться таким, каким получился: если предсказание
не подтвердилось, отчёт SHALL это говорить.
#### Scenario: Проверяющий читает сравнение
- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md`
- **THEN** он находит метод поиска узкого места, причину прежнего
решения, описание изменения и его влияния, предсказание, методику
измерения дельты, таблицу «до/после» и пути к сырым данным
#### Scenario: Одно изменение
- **WHEN** проверяющий сравнивает commit меток «до» и «после»
- **THEN** код приложения между ними отличается только описанным в
отчёте изменением
#### Scenario: Контрольные ячейки
- **WHEN** изменение затрагивает только один сценарий нагрузки
- **THEN** отчёт показывает и ячейки другого сценария, чтобы было
видно, что разница не вызвана условиями прогона
#### Scenario: Предсказание не подтвердилось
- **WHEN** изменение в ячейках оказалось в пределах шума или
противоположного знака
- **THEN** отчёт называет предсказание опровергнутым и приводит
фактические числа
@@ -0,0 +1,184 @@
# Tasks
Правила: `.claude/rules/bench.md` (стенд), `.claude/rules/api-contract.md`
(формат времени), `AGENTS.md` (упавший тест — сначала разбор). Решения —
`design.md`, требования — дельта спека `load-benchmark`.
Git: каждое измеренное или протестированное состояние кода коммитит
агент, хеш идёт в доказательства и отчёт; пробное изменение и его откат
— отдельные коммиты (design, решение 9). Push — только по просьбе.
## 1. Диагностика стоимости запроса (`bench/inproc.py`)
- [x] 1.1 Режим в контейнере (`--child`): создать хранилище, наполнить
20 000 сообщений по 64 символа, собрать пул курсоров с
фиксированным зерном; измерить время на запрос `read` и `write`,
части построения ответа (DTO → модель; JSON с текущим
сериализатором, с эталонным `strftime` и без Python-сериализатора),
профиль вызовов; каждое число — медиана и min–max повторов
(design, решения 1 и 2). Проверка: запуск в образе печатает все
перечисленные числа, у `to_rfc3339` 51 вызов на запрос чтения
- [x] 1.2 Сверка форматтера с эталоном и обратный разбор на наборе из
design, решение 5; отладочный флаг подмены эталонного формата.
Проверка: на текущем коде код выхода 0; с подменённым эталоном —
ненулевой код и строка со значением, ожидаемой и полученной
строками
- [x] 1.3 Режим на хосте (только stdlib): проверка свободной метки,
commit и признак незакоммиченных изменений, сборка образа
`mtusi-messenger:bench`, по три запуска отсоединённого контейнера
в каждом режиме логов (`--cpus=1`, скрипт смонтирован только для
чтения; INFO, INFO с stdout в `/dev/null`, WARNING), запись
`evidence/profile/<метка>.txt` с шапкой по спеку. Признак незакоммиченных изменений считается по файлам
приложения, образа и самому `bench/inproc.py`: новые каталоги в
`evidence/` его не поднимают. Проверка: файл создан, в шапке
дата, commit, id образа и версии; повторный запуск с той же
меткой — отказ с именем файла
- [x] 1.4 Цель `bench_inproc` в секции `Load benchmark` `Makefile`;
`evidence/profile/quick-*.txt` и `evidence/compare/*quick-*` — в
`.gitignore`. Проверка: `make bench_inproc BENCH_LABEL=quick-<время>`
проходит примерно за две минуты, файл в `git status` не виден
- [x] 1.5 Пробный запуск и сверка с предварительными числами design:
цена логов, цена форматирования времени, остаток «стенд минус
приложение» для чтения и записи. Проверка: числа выписаны в ответ
пользователю; если форматирование времени не самая крупная
затрата, сосредоточенная в одной функции, — остановиться и
спросить (design, решение 3)
## 2. Сравнение меток (`bench/compare.py`)
- [x] 2.1 Загрузка `runs.csv` и `meta.json` двух меток, проверка
сравнимости (профиль, лимиты, образ генератора — отказ; параметр
только в одной метке, незавершённая метка, `dirty`,
предупреждения хоста, помеченные прогоны — перечислить). Проверка:
`baseline` против `quick-*` — ненулевой код, назван параметр и
оба значения, файл не создан
- [x] 2.2 Таблица по ячейкам: медиана и min–max RPS обеих меток,
изменение в процентах, медианы p50/p95/p99, CPU на запрос; байты
на сообщение по размерам; шапка с commit и условиями хоста.
Проверка: `baseline` против `baseline` — 18 ячеек, изменение 0 во
всех; три значения таблицы сверены вручную с
`evidence/bench/baseline/summary.md`
- [x] 2.3 Параметр `AA`: уровень шума по сценариям и вывод по каждой
ячейке (эффект или в пределах шума) по правилу design, решение 7.
Проверка: на двух `quick-*` метках с третьей в роли `AA` таблица
содержит уровень шума и вывод в каждой строке
- [x] 2.4 Цель `bench_compare` в `Makefile` (`BEFORE`, `AFTER`,
необязательный `AA`), результат в
`evidence/compare/<до>__<после>.md`. Проверка: без `BEFORE` или
`AFTER` — понятная ошибка; с ними файл создан и тот же текст в
терминале
## 3. Правила и документация
- [x] 3.1 `.claude/rules/bench.md`: граница чёрного ящика (design,
решение 10), порядок сравнения меток (одна сессия, A/A, правило
эффекта), каталоги `evidence/profile/` и `evidence/compare/`.
Проверка: правило не противоречит новым файлам `bench/`
- [x] 3.2 `AGENTS.md`: команды `make bench_inproc` и
`make bench_compare`, карта кода (`bench/inproc.py`,
`bench/compare.py`, `evidence/profile/`, `evidence/compare/`).
Проверка: каждая новая цель `Makefile` есть в таблице команд
- [x] 3.3 `make lint` и `make check`. Проверка: оба без ошибок
## 4. Правка и её проверка, до перезагрузки
- [x] 4.1 Записать H5 в `REPORT.md` до правки: гипотеза, предсказание
в числах от пробного разложения в образе стенда, чем проверяем,
что опровергнет; результат пустой. Закоммитить. Проверка: строка
H5 есть, числа совпадают с design; commit с H5 старше commit правки
- [x] 4.2 Заменить тело `to_rfc3339` в `src/utils/utc.py` (design,
решение 4), `make lint`, закоммитить правку отдельным commit, в
котором из кода приложения меняется только этот файл. Проверка:
`git show --stat HEAD -- src` показывает один файл
- [x] 4.3 На commit правки: `make run_docker`, `make test`,
`make student_test`, затем `make down`; вывод с хешем commit — в
`evidence/tests/ts-isoformat.txt`. Проверка: smoke `PASS`,
79 passed; упавший тест сначала разбирается, тест не правится
- [x] 4.4 Пробное разложение на commit правки:
`make bench_inproc BENCH_LABEL=quick-<время>`. Проверка: код
выхода 0 — сверка с эталоном и обратный разбор прошли; JSON
страницы текущим форматтером дешевле, чем эталонным `strftime`, в
том же процессе; числа сообщены пользователю. Если не дешевле —
остановиться и разобраться
- [x] 4.5 Откатить правку отдельным commit (`git revert`) и
закоммитить доказательство тестов и задачи. Проверка:
`git diff --stat 60c098c HEAD -- src Dockerfile pyproject.toml
uv.lock .dockerignore .python-version` пуст, рабочее дерево чистое
## 5. Два прогона подряд в новой сессии хоста
- [x] 5.1 Остановиться и попросить пользователя: перезагрузить ноутбук,
подключить питание, остановить посторонние контейнеры и выполнить
`make bench_ab BEFORE=baseline-rerun AFTER=ts-isoformat
REAPPLY=184ed27` (design, решение 9): прогон и разложение «до»,
commit доказательств, возврат правки (`git revert` commit
отката), прогон и разложение «после». Проверка: у меток
`baseline-rerun` и `ts-isoformat` в `meta.json` `status: complete`,
`dirty: false`, `host_warnings` пуст; по 54 прогона без пометок;
оба файла `evidence/profile/` созданы без незакоммиченных
изменений приложения
- [x] 5.2 Проверить состояния кода по git: приложение в `baseline-rerun`
то же, что в `baseline` (`git diff --stat 60c098c <commit метки>
-- src Dockerfile pyproject.toml uv.lock .dockerignore
.python-version` пуст); между метками «до» и «после» в `src`
меняется только `src/utils/utc.py`; commit в шапках файлов
разложения совпадает с commit меток стенда. Проверка: три вывода
сверены, хеши выписаны для отчёта
## 6. Сравнения
- [x] 6.1 A/A: `make bench_compare BEFORE=baseline AFTER=baseline-rerun`.
Проверка: `evidence/compare/baseline__baseline-rerun.md` создан,
`warmup_seed_shift` назван непроверенным; уровень шума по
сценариям сообщён пользователю
- [x] 6.2 A/B: `make bench_compare BEFORE=baseline-rerun
AFTER=ts-isoformat AA=baseline`. Проверка:
`evidence/compare/baseline-rerun__ts-isoformat.md` создан, у
каждой ячейки вывод «эффект» или «в пределах шума»
- [x] 6.3 Сравнить два файла разложения: какие части подешевели и на
сколько, какие остались в пределах разброса. Проверка: цена JSON
страницы и время запроса `read` упали, `write` и цена логов — в
пределах разброса; числа сообщены пользователю
- [x] 6.4 Закоммитить доказательства прогона «после» и сравнений.
Проверка: рабочее дерево чистое
## 7. Отчёт
- [x] 7.1 Новый подраздел `REPORT.md` «Трек 1. Узкое место и сравнение
„до/после“» по требованию спека «Сравнение „до/после“ в отчёте»:
как искали узкое место (три приёма, числа, пути к
`evidence/profile/`), включая кандидата «логи» — найден, измерен,
не применён по решению пользователя; почему прежнее решение было
выбрано и что
не измерялось (design архива `messenger-core-api`, решение 3);
изменение, на что оно влияет, какие свойства сохраняются и чем
это проверено; H5 с результатом; методика измерения дельты
(метки, сессии, уровень шума, правило, контрольные ячейки);
таблицы «до/после» по чтению и записи; почему сработало и что
осталось; ограничения сравнения; хеш commit каждого измеренного
состояния кода, включая пробные и откаченные. Проверка: все
пункты требования найдены в тексте; результат записан как
получился, в том числе ячейки без эффекта; каждый хеш существует
в `git log`
- [x] 7.2 Обновить остальной отчёт: вводный абзац и пункты «Чтение
дороже записи» и «Кандидаты на узкое место» раздела базового
замера; вторая строка трека 5 в таблице доказательств; убрать
шаблонный TODO под таблицей. Проверка: в отчёте нет утверждений,
что сравнение «ещё не сделано»
- [x] 7.3 Раздел «Ограничения и следующие шаги»: какие отказы
выдерживаются и какие нет; что не реализовано; учебные упрощения;
что подтверждено замером, а что осталось гипотезой (логи,
зависимости FastAPI, сборка мусора, кэш процессора). Проверка:
TODO раздела снят, каждое утверждение опирается на раздел отчёта
или файл в `evidence/`
- [x] 7.4 Сверить каждое число новых разделов с
`evidence/compare/*.md`, `evidence/profile/*.txt` и `meta.json`
меток. Проверка: расхождений нет; найденные исправлены и названы
пользователю
## 8. Завершение
- [x] 8.1 `make lint`, `make check`,
`openspec validate perf-bottleneck-fix --strict`. Проверка: все
три без ошибок
- [x] 8.2 `graphify update .`. Проверка: команда завершилась без ошибок
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-09-30
@@ -0,0 +1,286 @@
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — спек
`student-tests` в этом change. Правила написания — `.claude/rules/student-tests.md`.
Что уже есть:
- **Публичный smoke** (`tests/smoke.py`) проходит один счастливый путь
и несколько ошибок: 409 дубликата, 401 без заголовка, 404 чужого
чата, пустое сообщение, `limit=0`. Собственные тесты его дополняют, а
не повторяют.
- **Основные спеки** `api-conventions`, `identification`, `users`,
`chats`, `messages`, `pagination`, `data-storage` и `health` содержат
сценарии в форме WHEN/THEN. Большая часть воспроизводится по HTTP.
- **Контракт.** В `contracts/openapi.json` (OpenAPI 3.1) все схемы
закрыты `additionalProperties: false`, а поля и `required` заданы
явно.
- **Зависимости.** В dev-группе uv уже есть `openapi-spec-validator`,
а через него `jsonschema` 4.26.0. `httpx` 0.28.1 есть в `uv.lock` как
зависимость `fastapi[all]`. pytest ещё нет, актуальная версия —
9.1.1.
- **Makefile.** Переменная skeleton `BASE_URL ?= http://localhost:8080`
уже есть, её использует `make test`.
- **Промежуточная проверка.** Параллельные записи для уровня «3» уже
проверены shell-скриптом (`evidence/api/parallel-writes.txt`).
## Goals / Non-Goals
**Goals:**
- Каждый тест можно сопоставить со сценарием спека, а список
непроверяемых сценариев с причинами хранится в коде и сверяется
автоматически.
- Переход лабы 2 на Bearer-сессии затрагивает одну функцию получения
заголовков идентификации.
- Полный прогон на локальном стенде укладывается в десятки секунд.
**Non-Goals:**
- Нагрузочные замеры и производительность (change `load-bench-harness`).
- Проверки, для которых нужен доступ к процессу: рестарт, ответ 500,
неготовое хранилище.
- Запуск тестов в CI: `CONTRIBUTING.md` его не требует, стенд
поднимается локально.
## Decisions
### 1. Раскладка `student-tests/`
```
student-tests/
conftest.py # BASE_URL, проверка доступности, фикстуры
api_client.py # Api поверх httpx, Actor, регистрация, чаты, сообщения, обход страниц
contract.py # проверка тел по contracts/openapi.json, assert_error
spec_coverage.py # исключения: сценарии, которые не проверить по HTTP, с причиной
test_rubric.py # пять обязательных сценариев уровня «4»
test_race.py # гонки: 100 сообщений от 10 клиентов, гонка за username
test_coverage.py # сверка: у каждого сценария спеков есть тест или исключение
test_contract.py # самопроверка contract.py: неверная форма ответа роняет тест
test_api_conventions.py
test_identification.py
test_users.py
test_chats.py
test_messages.py
test_pagination.py
test_data_storage.py
test_health.py
```
- **Модули тестов — по capability.** Файлы `test_<capability>.py`
повторяют имена спеков, так проще сверять. Отдельные
`test_rubric.py` и `test_race.py` — чтобы проверяющий сразу нашёл
тесты уровня «4».
- **Хелперы — обычные модули.** `pyproject.toml` указывает
`pythonpath = ["student-tests"]`, поэтому тесты импортируют
`api_client` и `contract` напрямую. Пакетом каталог не сделать: в
имени дефис.
- **Имя `spec_coverage.py`, а не `coverage.py`.** Каталог набора стоит
первым в `sys.path`, и модуль `coverage` затенил бы одноимённый пакет
(pytest-cov, coverage-runner IDE).
- **`test_contract.py`** проверяет сам `contract.py` на поддельных
ответах: тело `{"detail": ...}`, чужой `request_id`, `code` не по
статусу, лишнее поле, утечка пути к файлу. Это сценарий «Ошибка не в
формате контракта» спека `student-tests`.
*Альтернатива:* всё в фикстурах `conftest.py`. Но тогда клиентский код
смешивается с настройкой pytest, а на лабе 2 менять придётся конфтест
целиком.
### 2. Клиент и идентификация в одном месте
- **Клиент.** `Api` — тонкая обёртка над `httpx.Client(base_url=...,
timeout=5)`:
- `register()`, `create_chat()`, `send_message()` — создание
объектов, тело ответа сразу проверяется по схеме;
- `messages_page()`, `chats_page()` — одна страница как
`httpx.Response`, чтобы тест мог проверить и ошибку;
- `message_pages()`, `chat_pages()` — обход по `next_cursor` до
конца, `limit` может меняться от страницы к странице;
`all_messages()` — все сообщения чата одним списком.
- **Идентификация.** `register()` возвращает `Actor`: данные
пользователя и функцию `headers()`. На лабе 1 это
`{"X-User-Id": id}`, на лабе 2 будет вход с паролем и
`Authorization: Bearer ...`. Тесты передают `actor=`, а не заголовок.
- **Исключение — тесты `identification`.** Они собирают заголовки
вручную: в этом их смысл. На лабе 2 этот модуль переписывается вместе
со спеком.
- **Уникальные имена.** `username` генерируется как
`t_<uuid4().hex[:12]>`, это укладывается в `^[a-z0-9_]{3,32}$`. У
каждого теста свои пользователи и чаты.
*Альтернатива:* клиент `tests/client.py` из skeleton. Он заточен под
smoke, использует urllib и профиль `lab.json`, а `tests/` менять
нельзя.
### 3. Проверка формы по контракту
- **Схемы.** `contract.py` один раз читает `contracts/openapi.json` и
проверяет тела через `jsonschema.Draft202012Validator` со ссылкой
`#/components/schemas/<Name>` внутри этого же документа. Закрытые
схемы сразу ловят лишние поля, отсутствующие поля и неверные типы.
Когда в следующей лабе придёт новый контракт, тесты подхватят его без
правок.
- **Форматы — отдельно:** `id` проверяется регуляркой UUID в нижнем
регистре, `created_at` — окончанием `Z`, разбором
`datetime.fromisoformat` и 6 знаками долей секунды (спек
`api-conventions`).
- **Ошибки.** `assert_error(resp, status)` проверяет:
- статус и `Content-Type: application/json`;
- тело по схеме `Error`;
- `code` — по таблице статусов `ERROR_CODES` спека
`api-conventions` (405 → `invalid_request`), поэтому тест
передаёт только статус;
- непустой `message` без признаков внутренностей (traceback, путь к
файлу);
- `request_id` равен заголовку `X-Request-Id`.
- **Успех.** `assert_ok(resp, status, schema)` проверяет статус,
`Content-Type`, непустой `X-Request-Id` и тело по схеме с форматами.
Все ожидаемые ошибки в наборе проверяются этой функцией, так что
требование «Проверка формы ответов» выполняется без повторов.
*Альтернатива:* вручную сравнивать множества ключей. Но тогда дублируем
контракт, и с новой лабой набор начнёт расходиться с ним.
### 4. Недоступный сервер
Сессионная autouse-фикстура в `conftest.py` делает `GET /health/live`
с таймаутом 2 с. При ошибке соединения или таймауте она вызывает
`pytest.exit("server is not reachable at <BASE_URL>: ...",
returncode=2)`. Прогон останавливается одной понятной строкой, а не
пачкой ошибок в каждом тесте. Если `/health/live` отвечает, но не 200,
выход такой же, с подсказкой про чужой сервис на порту: на 8080 часто
висит другой проект (`AGENTS.md`, `make test`).
### 5. Тест гонок: потоки, барьер, отдельные соединения
- **Сообщения.** `ThreadPoolExecutor(max_workers=10)`, у каждого потока
свой `httpx.Client`, то есть своё соединение. `threading.Barrier(10)`
отпускает всех одновременно. Каждый клиент — отдельный участник чата
и последовательно шлёт 10 сообщений с уникальным текстом
`race-<client>-<n>`, поэтому в полёте одновременно до 10 запросов.
- **Что проверяется после:**
- 100 ответов 201;
- обход истории по `limit=30` (4 страницы) даёт 100 сообщений;
- множество `id` совпадает с id из ответов;
- множество текстов совпадает с отправленными;
- порядок `(created_at, id)` соблюдён.
- **Доказательство параллельности.** По меткам начала и конца запросов
считается, сколько запросов максимум было в полёте одновременно.
Тест требует ≥ 2, иначе он не доказывает гонку.
- **Гонка за username.** 10 потоков за барьером регистрируют один
`username`. Ожидается `Counter` статусов `{201: 1, 409: 9}`, у всех
409 — формат ошибки `conflict`.
- **Вывод.** Оба теста печатают короткую сводку: статусы, число
сообщений и страниц, максимум одновременных запросов. Её показывает
`-rP` (решение 7).
*Альтернатива:* `asyncio.gather` с `httpx.AsyncClient`. Нужен
pytest-плагин (anyio или pytest-asyncio), а выигрыша для 10 клиентов
нет. Потоки проще, и соединения у них точно разные.
### 6. Сверка покрытия сценариев
- **Маркер.** Тест помечается `@pytest.mark.spec("<capability>",
"<Сценарий>")`, у одного теста может быть несколько маркеров. Маркер
объявляется в `pyproject.toml`, `--strict-markers` ловит опечатки в
имени маркера.
- **Исключения.** `spec_coverage.py` хранит словарь исключений
`(capability, сценарий) → причина и способ проверки`. Сейчас это:
- «Ответ 500» и «Исключение внутри обработки» — без внедрения сбоя в
сервис их не вызвать;
- «Прежний пользователь после рестарта» — нужен рестарт процесса,
доказательство в `evidence/container/lifecycle.txt`;
- «Хранилище не готово» — после старта хранилище готово всегда;
- «Кнопка Authorize в Swagger» — это интерфейс, схему проверяет тест
«Схема в openapi.json».
- **Сверка.** `test_coverage.py` читает заголовки `#### Scenario:` из
`openspec/specs/<capability>/spec.md` для восьми capability и собирает
маркеры всех тестов через хук `pytest_collection_modifyitems`
(результат сохраняется в `config.stash`). Тест падает, если у
сценария нет ни теста, ни исключения, а также если маркер или
исключение ссылаются на несуществующий сценарий. Так набор не отстаёт
от спеков: новый сценарий без теста сразу виден.
- **Неполный сбор.** Хук стоит с `tryfirst`, поэтому видит тесты до
отбора по `-k` / `-m`. Если же pytest собрал не все модули (запущен
один файл), сверка пропускается с пояснением: маркеров других
модулей она не видит. В `make student_test` набор собирается
целиком.
*Альтернатива:* таблица соответствия в `README.md`. Её никто не
сверяет, она устаревает при первой правке спека.
### 7. Запуск: `make student_test` и настройки pytest
```toml
[dependency-groups]
dev = [..., "pytest>=9.1.1,<10", "httpx>=0.28.1,<1", "jsonschema>=4.26.0,<5"]
[tool.ruff]
src = [".", "student-tests"]
[tool.pytest.ini_options]
testpaths = ["student-tests"]
pythonpath = ["student-tests"]
addopts = "-v -rP --strict-markers"
markers = ["spec(capability, scenario): сценарий основного спека, который проверяет тест"]
```
```make
# собственные black-box тесты против запущенного сервера (BASE_URL)
.PHONY: student_test
student_test:
BASE_URL=$(BASE_URL) uv run pytest
```
- **Цель — в секции `Common targets`.** Переменная `BASE_URL` и её
дефолт взяты из skeleton, как у `make test`. Префикс окружения
`BASE_URL=... make ...` здесь работает, потому что `.env` не содержит
`BASE_URL`, но в документации — по-прежнему аргумент make.
- **Флаги.** `-v` печатает имя каждого теста: это и есть список
проверок в evidence. `-rP` показывает сводки тестов гонок.
- **httpx и jsonschema объявляются явно.** Тесты не должны зависеть от
того, что httpx тянет `fastapi[all]`, а jsonschema —
`openapi-spec-validator`.
- **`src` для ruff.** С `student-tests` в `src` isort считает
`api_client`, `contract` и `spec_coverage` модулями проекта и
отделяет их от сторонних импортов.
### 8. Доказательства и отчёт
- **`evidence/tests/student-tests.txt`:**
- шапка — дата, commit, окружение, стенд;
- вывод `make student_test` против `make run_docker`;
- сразу второй прогон на том же сервере (требование независимости);
- краткий итог прогона против `make run_dev`.
- **`REPORT.md`:**
- строка «4: собственные тесты» — команда, число тестов, путь;
- строка «4: 100 сообщений от 10 клиентов» — тест гонок и его
сводка;
- строка «3: параллельные запросы» дополняется ссылкой на тест
гонок, промежуточный скрипт остаётся как первое доказательство.
## Risks / Trade-offs
- [Параллельность не случится: запросы обработаются строго по одному,
и тест ничего не докажет] → Барьер и отдельные соединения, плюс
проверка «максимум одновременно в полёте ≥ 2». Если условие не
выполняется, тест падает, а не проходит вхолостую.
- [Проверка покрытия ломает прогон при правке спека] → Это намеренно.
Новый сценарий требует теста или записи в исключениях с причиной.
- [`uv run` синхронизирует окружение, и extra `dev` с ruff может
пропасть] → ruff глобальный (`AGENTS.md`), `make lint` от этого не
зависит. При необходимости `uv sync --all-extras`.
- [Тесты `identification` и часть `health` привязаны к лабе 1] → На
лабе 2 спек `identification` меняется, модуль переписывается вместе с
ним. Остальные тесты идут через `Actor.headers()`.
- [Данные тестов копятся в памяти стенда: API ничего не удаляет] → Для
лабы 1 это килобайты за прогон. Рестарт стенда очищает всё.
## Migration Plan
Не применимо: новые файлы и dev-зависимости, код приложения и образ не
меняются. Откат — удалить `student-tests/` и `evidence/tests/`, вернуть
`pyproject.toml`, `uv.lock`, `Makefile` и `REPORT.md` из git.
@@ -0,0 +1,86 @@
# Proposal
## Why
Уровень «4» требует собственных тестов, которые запускаются одной
командой:
- неверный JSON, чужой чат, пустое сообщение, дубликат `username`,
обход нескольких страниц;
- тест гонок «100 сообщений от 10 клиентов → ровно 100 уникальных» с
сохранённой командой и результатом (`README.md`).
Сейчас поведение API проверяют только публичный smoke — один
счастливый путь и несколько ошибок — и ручные прогоны. Сценарии
основных спеков автоматически не проверяются. Тесты нужны и дальше:
они переезжают в каждую следующую лабу вместе с кодом и ловят регрессии
при переходах API.
## What Changes
- **Каталог `student-tests/`**: black-box тесты по HTTP против уже
запущенного сервера (console или контейнер), pytest + httpx. Тесты не
импортируют `src` и не поднимают приложение сами.
- **Обязательные сценарии рубрики «4»:**
- неверный JSON;
- чужой чат;
- пустое сообщение;
- дубликат `username`;
- обход нескольких страниц истории;
- гонки: 10 клиентов параллельно отправляют по 10 сообщений, затем
полный обход истории даёт ровно 100 уникальных; плюс гонка за
`username`.
- **Сценарии основных спеков, которые проверяются по HTTP:**
- `identification` — 401 и порядок проверок;
- `api-conventions` — формат ошибок, `X-Request-Id`, 400 вместо 422,
Unicode, длины в code points, формат `id` и `created_at`;
- `users`, `chats`, `messages` — валидация и доступ;
- `pagination` — `limit`, `next_cursor`, курсоры;
- `health`.
Сценарии, которые по HTTP не воспроизвести (ответ 500, рестарт
процесса, неготовое хранилище, кнопка в Swagger), остаются за ручными
проверками и `evidence/`.
- **`make student_test [BASE_URL=...]`**: одна команда запуска.
pytest и httpx — в dev-группе uv.
- **Идентификация в одном месте тестового кода**, чтобы переход лабы 2
на Bearer-сессии менял одну функцию, а не каждый тест.
- **Доказательства:** вывод прогона против контейнера в `evidence/`,
строки уровня «4» в `REPORT.md` — собственные тесты и 100 сообщений
от 10 клиентов. Строка уровня «3» про параллельные запросы получает
ссылку на тест гонок.
- **Не входит:** нагрузочные замеры и методика трека 1 (change
`load-bench-harness`); изменения кода приложения. Если тест найдёт
дефект, он записывается в `KNOWN_ISSUES.md` и чинится отдельно по
просьбе.
## Capabilities
### New Capabilities
- `student-tests`: собственный набор black-box тестов API — запуск
одной командой против любого `BASE_URL`, независимость прогонов друг
от друга, обязательные сценарии рубрики, тест гонок, покрытие
сценариев основных спеков и сохранение результата.
### Modified Capabilities
Нет. Тесты проверяют уже описанное поведение (`api-conventions`,
`identification`, `users`, `chats`, `messages`, `pagination`,
`data-storage`, `health`) и не меняют его требований.
## Impact
- **Новые файлы:** `student-tests/` (тесты, `conftest.py`, клиентские
хелперы), `evidence/tests/`.
- **Изменяемые файлы:**
- `pyproject.toml` и `uv.lock` — pytest и httpx в dev-группе,
настройки pytest;
- `Makefile` — цель `student_test`;
- `REPORT.md` — строки критериев;
- `AGENTS.md` — `make student_test` без пометки «появится»;
- `.claude/rules/student-tests.md` — уточнения из реализации.
- **Код приложения** не меняется.
- **Образ** не меняется: `student-tests` уже в `.dockerignore`, а
dev-группа в образ не ставится (`uv sync --no-dev`).
- **Окружение:** для запуска нужен uv на хосте. Сервер — любой из трёх
способов запуска.
@@ -0,0 +1,162 @@
# Spec Delta
## Purpose
Собственный набор black-box тестов API мессенджера: одной командой
проверяет по HTTP любой запущенный стенд. Покрывает обязательные
сценарии рубрики, гонки и сценарии основных спеков, а результат прогона
сохраняется как доказательство.
## ADDED Requirements
### Requirement: Запуск одной командой
Весь набор SHALL запускаться одной командой `make student_test` против
сервера по адресу `BASE_URL`, по умолчанию `http://localhost:8080`.
Команда SHALL завершаться с кодом 0, только если прошли все тесты. Если
сервер по `BASE_URL` не отвечает, набор MUST завершаться с ненулевым
кодом и сообщением о недоступности адреса, а не множеством ошибок
отдельных тестов.
#### Scenario: Все тесты прошли
- **WHEN** сервер запущен и `make student_test` выполняется без
аргументов
- **THEN** все тесты проходят, команда завершается с кодом 0
#### Scenario: Другой адрес
- **WHEN** выполняется `make student_test BASE_URL=http://localhost:8090`
- **THEN** тесты обращаются к `http://localhost:8090`
#### Scenario: Сервер не запущен
- **WHEN** по `BASE_URL` никто не слушает
- **THEN** команда завершается с ненулевым кодом, а вывод называет
недоступный адрес
### Requirement: Только по HTTP
Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать
код приложения, запускать или останавливать сервер. Один и тот же набор
SHALL проходить против сервера, запущенного на хосте, и против
контейнера.
#### Scenario: Консоль и контейнер
- **WHEN** набор запускается сначала против `make run_dev`, затем против
`make run_docker`
- **THEN** оба прогона проходят одинаково
### Requirement: Независимость прогонов
Каждый тест SHALL создавать собственных пользователей с уникальным
`username` и собственные чаты. Результат MUST NOT зависеть от порядка
тестов, от данных, уже лежащих на сервере, и от предыдущих прогонов.
#### Scenario: Два прогона подряд
- **WHEN** набор запускается дважды подряд против одного сервера без
рестарта
- **THEN** оба прогона проходят
### Requirement: Обязательные сценарии рубрики
Набор SHALL содержать отдельные тесты для сценариев уровня «4»:
неверный JSON, чужой чат, пустое сообщение, дубликат `username` и обход
нескольких страниц истории.
#### Scenario: Неверный JSON
- **WHEN** тест отправляет тело `{bad` в эндпоинт, ожидающий JSON
- **THEN** проверяется ответ 400 с `code` `invalid_request`
#### Scenario: Чужой чат
- **WHEN** пользователь, не состоящий в чате, читает чат, читает
историю и пишет в чат
- **THEN** проверяется, что все три запроса получают 404 `not_found`
#### Scenario: Пустое сообщение
- **WHEN** участник отправляет сообщение с `text` пустым и из пробелов
- **THEN** проверяется ответ 400 `invalid_request`, и сообщение не
появляется в истории
#### Scenario: Дубликат username
- **WHEN** регистрируется `username`, который уже занят
- **THEN** проверяется ответ 409 `conflict`
#### Scenario: Обход нескольких страниц
- **WHEN** история содержит больше сообщений, чем помещается на одну
страницу, и тест обходит её по `next_cursor`, в том числе меняя
`limit` между страницами
- **THEN** проверяется, что каждое сообщение встречается ровно один раз
в порядке `(created_at, id)`, а последняя страница имеет
`next_cursor` null
### Requirement: Тест гонок
Набор SHALL содержать тест гонок с реальной параллельностью: запросы
находятся в обработке одновременно, по отдельным соединениям. 10
клиентов SHALL одновременно отправлять по 10 сообщений в один чат, после
чего полный обход истории SHALL давать ровно 100 сообщений с
уникальными `id`. Отдельный тест SHALL одновременно регистрировать
одинаковый `username` несколькими клиентами.
#### Scenario: 100 сообщений от 10 клиентов
- **WHEN** 10 клиентов одновременно отправляют по 10 сообщений
- **THEN** получено 100 ответов 201, полный обход истории возвращает
100 сообщений с уникальными `id`, и каждое отправленное сообщение
найдено ровно один раз
#### Scenario: Гонка за username
- **WHEN** 10 клиентов одновременно регистрируют одинаковый `username`
- **THEN** ровно один ответ 201, остальные 409 `conflict`
### Requirement: Покрытие сценариев основных спеков
Для каждого сценария основных спеков `api-conventions`,
`identification`, `users`, `chats`, `messages`, `pagination`,
`data-storage` и `health`, который воспроизводится по HTTP против
работающего сервера, SHALL быть тест. Из имени или описания теста SHALL
быть понятно, какой capability и сценарий он проверяет. Сценарии,
которые по HTTP не воспроизвести, SHALL быть перечислены с причиной и
способом проверки.
#### Scenario: Сверка покрытия
- **WHEN** проверяющий берёт любой сценарий перечисленных спеков
- **THEN** находится проверяющий его тест либо запись в списке
исключений с причиной
### Requirement: Проверка формы ответов
Тесты SHALL проверять не только статус.
- У ошибок: тело — ровно `{"error": {"code", "message",
"request_id"}}`, `code` соответствует статусу, `request_id` равен
заголовку `X-Request-Id`.
- У успешных ответов: поля совпадают со схемой контракта, лишних нет,
`id` — UUID в нижнем регистре, `created_at` — RFC 3339 UTC с `Z`.
#### Scenario: Ошибка не в формате контракта
- **WHEN** сервер отвечает на ошибку телом `{"detail": ...}`
- **THEN** тест падает, даже если статус верный
### Requirement: Результат прогона сохраняется
Вывод прогона против контейнера SHALL сохраняться в `evidence/` с
командой, датой, commit, адресом стенда и итогом. `REPORT.md` SHALL
ссылаться на него в строках уровня «4»: собственные тесты и 100
сообщений от 10 клиентов.
#### Scenario: Доказательство в отчёте
- **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md`
- **THEN** в ней есть команда, наблюдаемый результат и путь к файлу
вывода в `evidence/`
@@ -0,0 +1,97 @@
# Tasks
Перед первым файлом в `student-tests/` прочитать
`.claude/rules/student-tests.md` и `.claude/rules/api-contract.md`.
Как строить — `design.md`, что должно получиться — спек
`student-tests`, ожидаемое поведение API — основные спеки в
`openspec/specs/`. Для прогонов нужен свободный порт 8080 или другой
`BASE_URL`.
## 1. Зависимости и запуск
- [x] 1.1 pytest и httpx в dev-группу (`uv add --group dev
"pytest>=9.1.1,<10" "httpx>=0.28.1,<1"`), секция
`[tool.pytest.ini_options]` по design, решение 7. Проверка:
`uv run pytest --version` печатает 9.x, `uv lock --check` проходит,
сборка образа не меняет состав `/app/.venv` (dev-группа в образ не
ставится).
- [x] 1.2 Цель `student_test` в секции `Common targets` `Makefile`
(design, решение 7). Проверка: `make -n student_test` печатает
`BASE_URL=http://localhost:8080 uv run pytest`,
`make -n student_test BASE_URL=http://localhost:8090` — с новым
адресом; `make help` и `make check` работают как раньше.
## 2. Общий код набора
- [x] 2.1 `student-tests/api_client.py` (design, решение 2): `Api`,
`Actor` с `headers()`, регистрация с уникальным `username`, чаты,
сообщения, страница и полный обход истории. Проверка: заголовок
`X-User-Id` встречается только в `Actor.headers()` и в
`test_identification.py` (`grep -rn X-User-Id student-tests`).
- [x] 2.2 `student-tests/contract.py` (design, решение 3): проверка тела
по схеме из `contracts/openapi.json`, форматы `id` и `created_at`,
`assert_error`. Проверка: на запущенном сервере тело `User` проходит,
а тот же словарь с лишним ключом, с `id` в верхнем регистре или с
`created_at` без `Z` отвергается.
- [x] 2.3 `student-tests/conftest.py`: `BASE_URL` из окружения,
проверка доступности через `pytest.exit` (design, решение 4),
фикстуры `api` и регистрации пользователей, хук сбора маркеров
`spec`. Проверка: при остановленном сервере `make student_test`
завершается с кодом 2 одной строкой с адресом, без трейсбеков по
тестам.
## 3. Тесты
- [x] 3.1 `test_rubric.py`: неверный JSON, чужой чат (GET чата, GET
истории, POST сообщения), пустое сообщение и из пробелов (и его нет
в истории), дубликат `username`, обход нескольких страниц со сменой
`limit`. Проверка: `uv run pytest student-tests/test_rubric.py`
проходит на запущенном сервере.
- [x] 3.2 `test_race.py` (design, решение 5): 100 сообщений от 10
клиентов и гонка за `username`, со сводкой в выводе и проверкой
«одновременно в полёте ≥ 2». Проверка: тест проходит, сводка видна в
`-rP`.
- [x] 3.3 `test_api_conventions.py` и `test_identification.py`: все
сценарии этих спеков, кроме исключений (design, решение 6). В том
числе порядок проверок: без заголовка чужой чат и `{"text": ""}`
дают 401, а `{bad` — 400. Схема `devUser` в `/openapi.json`, 404 и
405. Проверка: модули проходят.
- [x] 3.4 `test_users.py`, `test_chats.py`, `test_messages.py`: все
сценарии спеков, включая границы длин в code points (100 и 101
emoji, 4000 и 4001 символ), подмену `sender_id`, повтор и неизвестного
участника чата, неизменный состав. Проверка: модули проходят.
- [x] 3.5 `test_pagination.py`, `test_data_storage.py`,
`test_health.py`: `limit` 0/101/`abc`/по умолчанию 50 из 60, последняя
полная страница, обход 7 элементов по 3 и 2, курсор другого чата и
`garbage`, созданное видно сразу, health без идентификации.
Проверка: модули проходят.
- [x] 3.6 `spec_coverage.py` и `test_coverage.py` (design, решение 6).
Проверка:
- тест проходит;
- временно добавленный в копию списка сценарий без теста роняет его
с понятным сообщением;
- маркер с опечаткой в названии сценария тоже роняет его.
## 4. Прогоны
- [x] 4.1 Против `make run_dev`: `make student_test` — все тесты
проходят. Сразу второй прогон на том же сервере — тоже.
- [x] 4.2 Против `make run_docker`: `make student_test` — все тесты
проходят, вывод сохранить для evidence.
- [x] 4.3 `make lint` без правок в `tests/` и `scripts/`; ruff проверяет
`student-tests/` по правилам проекта.
## 5. Документация
- [x] 5.1 `evidence/tests/student-tests.txt` (design, решение 8): шапка
с датой, commit, окружением и стендом, вывод прогонов 4.1–4.2.
Проверка: в файле нет текстов сообщений, кроме синтетических
`race-*`, и нет секретов.
- [x] 5.2 `REPORT.md`: строки «4: собственные тесты», «4: 100 сообщений
от 10 клиентов» и ссылка на тест гонок в строке уровня «3».
Проверка: TODO в этих строках не осталось.
- [x] 5.3 `AGENTS.md`: `make student_test` без пометки «появится», карта
кода `student-tests/`. `.claude/rules/student-tests.md`: маркер
`spec`, исключения в `spec_coverage.py`, `Actor.headers()` как
единственное место идентификации. Проверка: `openspec validate
student-tests --strict` проходит.
+28
View File
@@ -0,0 +1,28 @@
schema: spec-driven
context: |
Language: Russian
All artifacts must be written in Russian.
Keep OpenSpec structural headings and SHALL/MUST keywords in English.
# Per-artifact rules (optional)
# Add custom rules for specific artifacts.
# Example:
# rules:
# proposal:
# - Keep proposals under 500 words
# - Always include a "Non-goals" section
# tasks:
# - Break tasks into chunks of max 2 hours
# Per-operation guidance (optional)
# Add advisory guidance for how apply and archive work should be conducted.
# This is separate from artifact rules above.
# Example:
# operations:
# apply:
# guidance:
# - Keep test summaries concise
# archive:
# guidance:
# - Summarize the archive outcome before finishing
View File
+145
View File
@@ -0,0 +1,145 @@
# api-conventions Specification
## Purpose
Общие правила HTTP API мессенджера: кодировка и формат JSON, единый
формат ошибок, заголовок `X-Request-Id`, представление времени и
идентификаторов. На них опираются все эндпоинты и клиенты, включая
публичный smoke.
## Requirements
### Requirement: JSON в UTF-8 без искажений
Ответы с телом SHALL иметь `Content-Type: application/json` в
кодировке UTF-8. Строки SHALL возвращаться клиенту в том виде, в каком
были приняты, включая кириллицу и emoji. Длины строк SHALL считаться в
Unicode code points.
#### Scenario: Unicode сохраняется
- **WHEN** клиент отправляет строковое поле `"Привет, мир 👋"`
- **THEN** в ответе и при последующем чтении это поле равно
`"Привет, мир 👋"` байт в байт после декодирования UTF-8
#### Scenario: Длина в code points
- **WHEN** клиент отправляет поле с ограничением 100 символов,
состоящее из 100 emoji
- **THEN** запрос принимается, хотя в UTF-8 это больше 100 байт
### Requirement: X-Request-Id на каждом ответе
Каждый ответ API SHALL содержать непустой заголовок `X-Request-Id`,
уникальный для запроса: успешный, с ошибкой, health, ответ на
неизвестный путь и ответ на непредвиденное исключение.
#### Scenario: Успешный ответ
- **WHEN** клиент выполняет любой успешный запрос
- **THEN** ответ содержит непустой `X-Request-Id`
#### Scenario: Ответ 500
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ 500 тоже содержит непустой `X-Request-Id`
#### Scenario: Разные запросы
- **WHEN** клиент выполняет два запроса подряд
- **THEN** значения `X-Request-Id` в ответах различаются
### Requirement: Единый формат ошибки
Любой ответ со статусом ≥ 400 SHALL иметь тело
`{"error": {"code": ..., "message": ..., "request_id": ...}}` без
других полей. `request_id` MUST совпадать с заголовком `X-Request-Id`.
`message` MUST быть непустым и MUST NOT раскрывать stack trace, пути к
файлам, имена внутренних классов, запросы к хранилищу или сам факт
существования недоступного объекта.
#### Scenario: Ошибка содержит request_id заголовка
- **WHEN** клиент получает любой ответ с ошибкой
- **THEN** тело соответствует формату, а `error.request_id` равен
значению заголовка `X-Request-Id`
#### Scenario: Нет тела FastAPI по умолчанию
- **WHEN** клиент получает ошибку валидации или 404
- **THEN** в теле нет ключа `detail`, есть только `error`
### Requirement: Соответствие статусов и кодов ошибок
Сервис SHALL использовать пары статус — `code`: 400 —
`invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 —
`conflict`, 500 — `internal_error`, 503 — `unavailable`. Метод, не
поддерживаемый путём, SHALL давать 405 с `code` `invalid_request`.
#### Scenario: Неизвестный путь
- **WHEN** клиент запрашивает `GET /api/v1/unknown`
- **THEN** ответ 404 с `code` `not_found` в формате ошибки
#### Scenario: Неподдерживаемый метод
- **WHEN** клиент выполняет `DELETE /api/v1/users`
- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки
### Requirement: Невалидный запрос даёт 400
Сервис SHALL отвечать 400 `invalid_request`, а не 422, когда тело не
является корректным JSON; когда JSON не объект там, где ожидается
объект; когда в теле есть поля, не описанные в контракте; когда тип
значения не совпадает с контрактом. Значения MUST NOT приводиться к
нужному типу неявно. Обязательные строковые поля, состоящие только из
пробельных символов, SHALL считаться невалидными.
#### Scenario: Битый JSON
- **WHEN** клиент отправляет тело `{bad` с `Content-Type: application/json`
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Лишнее поле
- **WHEN** тело запроса содержит поле, которого нет в схеме контракта
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Неверный тип без приведения
- **WHEN** строковое поле передано числом `123`
- **THEN** ответ 400, значение не превращается в строку `"123"`
#### Scenario: Строка из пробелов
- **WHEN** обязательное строковое поле равно `" "`
- **THEN** ответ 400 с `code` `invalid_request`
### Requirement: Непредвиденная ошибка без деталей
Непредвиденное исключение SHALL давать ответ 500 с `code`
`internal_error` и общим сообщением. Детали ошибки MUST попадать только
в лог сервиса.
#### Scenario: Исключение внутри обработки
- **WHEN** при обработке запроса возникает непредвиденное исключение
- **THEN** клиент получает 500 `internal_error` без stack trace, а в
логе есть запись уровня `error` с traceback и тем же `request_id`
### Requirement: Представление времени и идентификаторов
Идентификаторы и время SHALL назначаться сервером. Идентификаторы SHALL
быть UUID в виде строки в нижнем регистре. Время SHALL передаваться в
формате RFC 3339 в UTC с суффиксом `Z` и точностью до микросекунд,
одинаковой при хранении и выдаче.
#### Scenario: Формат created_at
- **WHEN** клиент получает любой объект с `created_at`
- **THEN** значение оканчивается на `Z` и разбирается как RFC 3339 UTC
#### Scenario: Формат id
- **WHEN** клиент получает любой объект с `id`
- **THEN** значение — UUID в нижнем регистре
+101
View File
@@ -0,0 +1,101 @@
# chats Specification
## Purpose
Чаты — группы пользователей с фиксированным составом, в которых идёт
переписка. Capability описывает создание, получение и список чатов
текущего пользователя, а также правило «чат видят только участники».
## Requirements
### Requirement: Создание чата
`POST /api/v1/chats` SHALL принимать тело
`{"title": ..., "member_ids": [...]}` и при успехе отвечать 201 с
объектом `Chat`: `id`, `title`, `member_ids`, `created_at`, без других
полей. `member_ids` в ответе SHALL совпадать с переданным списком,
включая порядок. Чат SHALL создаваться атомарно: при любой ошибке
валидации он MUST NOT появиться ни в одном списке.
#### Scenario: Успешное создание
- **WHEN** Алиса создаёт чат с `member_ids` = [Алиса, Боб]
- **THEN** ответ 201, `member_ids` равен [Алиса, Боб], `id` — новый UUID
### Requirement: Валидация чата
`title` SHALL содержать 1–100 Unicode code points и MUST NOT состоять
только из пробельных символов. `member_ids` SHALL содержать от 1 до 100
UUID без повторов; каждый MUST быть идентификатором существующего
пользователя, и текущий пользователь MUST входить в список. Нарушение
любого условия SHALL давать 400 `invalid_request`.
#### Scenario: Вызывающего нет в списке
- **WHEN** Алиса создаёт чат с `member_ids` = [Боб]
- **THEN** ответ 400
#### Scenario: Повтор участника
- **WHEN** `member_ids` = [Алиса, Алиса]
- **THEN** ответ 400
#### Scenario: Неизвестный участник
- **WHEN** `member_ids` содержит UUID, которого нет среди пользователей
- **THEN** ответ 400
#### Scenario: Пустой список
- **WHEN** `member_ids` = []
- **THEN** ответ 400
### Requirement: Получение чата
`GET /api/v1/chats/{chat_id}` SHALL отвечать 200 с объектом `Chat`,
если текущий пользователь — участник. Если чата нет или пользователь
не участник, сервис SHALL отвечать одинаковым 404 `not_found` и MUST
NOT использовать 403. `chat_id`, не являющийся UUID, SHALL давать 400.
#### Scenario: Участник
- **WHEN** Боб запрашивает чат, в котором состоит
- **THEN** ответ 200 с этим чатом
#### Scenario: Посторонний
- **WHEN** Ева запрашивает существующий чат Алисы и Боба
- **THEN** ответ 404 с `code` `not_found`, неотличимый от ответа на
несуществующий чат
#### Scenario: Неверный chat_id
- **WHEN** `chat_id` равен `nope`
- **THEN** ответ 400
### Requirement: Список чатов пользователя
`GET /api/v1/chats` SHALL возвращать только чаты, в которых состоит
текущий пользователь, в порядке `(created_at, id)` по возрастанию, с
постраничным выводом по capability `pagination`.
#### Scenario: Участник видит чат
- **WHEN** Боб запрашивает список чатов после того, как Алиса создала
чат с ним
- **THEN** этот чат есть в списке
#### Scenario: Посторонний не видит чат
- **WHEN** Ева запрашивает список чатов
- **THEN** чата Алисы и Боба в нём нет
### Requirement: Состав чата неизменен
После создания состав участников чата SHALL оставаться неизменным: API
лабы 1 не предоставляет операций добавления и удаления участников.
#### Scenario: Повторное чтение
- **WHEN** участник читает чат в разное время
- **THEN** `member_ids` каждый раз одинаков
+191
View File
@@ -0,0 +1,191 @@
# code-knowledge-graph Specification
## Purpose
Граф знаний репозитория: агент по нему отвечает на вопросы о структуре и
связях кода, а в отчёт из него берётся схема слоёв. Граф ничего не меняет
в работе проекта и в том, как подгружаются правила слоёв.
## Requirements
### Requirement: Состав графа
Граф SHALL строиться без LLM по коду `src/` и по документам, которые
описывают код: `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`,
`openspec/specs/`, `contracts/README.md`, `KNOWN_ISSUES.md`, а также по
`pyproject.toml`. Файлы, которые инструмент графа не разбирает
(`.json`, `.yaml`/`.yml`, `Dockerfile`, `Makefile`, шаблоны конфигов),
в граф не попадают. Это известное ограничение, а не ошибка состава.
В граф MUST NOT попадать:
- публичные проверки, скрипты и заготовки skeleton: `tests/`, `scripts/`,
`examples/`, `Dockerfile.example`, `lab.json`, `requirements-dev.txt`,
`contracts/examples.json`, `contracts/infrastructure.json`;
- инструментарий агента: `.claude/commands/`, `.claude/skills/`,
`.claude/settings.local.json`;
- изменения OpenSpec, текущие и архивные: `openspec/changes/`;
- `REPORT.md`, `evidence/` и документы курса: `README.md`, `COURSE.md`,
`CONTRIBUTING.md`, `MAINTAINERS.md`, `.github/`;
- всё, что исключено в `.gitignore`, в том числе `.env`, `config.toml`,
`.venv`.
Список исключений SHALL храниться в файле репозитория, а не в памяти
агента.
Раздел документа SHALL быть связан с символом кода, если символ упомянут
в тексте раздела. Полнота таких связей MUST NOT считаться
гарантированной: раздел без упоминания символа с кодом не связан. Точная
карта «правило слоя → файлы кода» — поле `paths:` в правилах
`.claude/rules/` и таблица в `AGENTS.md`, а не граф.
#### Scenario: Запрос находит код и документы
- **WHEN** агент спрашивает граф о сервисе чатов по именам символов
(`ChatService`, `ChatNotFound`)
- **THEN** в ответе есть узел из `src/core/services/`, раздел правила из
`.claude/rules/` и раздел спеки из `openspec/specs/`
#### Scenario: Исключённое отсутствует
- **WHEN** в графе ищутся узлы из `tests/`, `scripts/`,
`.claude/commands/`, `.claude/skills/` и `openspec/changes/`
- **THEN** таких узлов нет
#### Scenario: Конфигурация связана с настройками
- **WHEN** агент спрашивает граф, где используется порт приложения
- **THEN** в ответе есть модуль настроек из `src/config/` и раздел
правила или спеки о запуске
#### Scenario: Секреты не попадают в граф
- **WHEN** в корне лежат `.env` и `config.toml`
- **THEN** в артефактах графа нет ни их содержимого, ни узлов для них
### Requirement: Артефакты графа локальные
Каталог с артефактами графа SHALL быть исключён из git и из контекста
сборки образа. Граф MUST NOT попадать в коммиты, PR и образ; в отчёт из
него переносится только схема (требование «Схема кода в отчёте»).
#### Scenario: git не видит граф
- **WHEN** граф собран, и выполняется `git status --ignored`
- **THEN** каталог графа виден только среди игнорируемых, а среди новых
и изменённых файлов его нет
#### Scenario: Образ без графа
- **WHEN** после сборки графа собирается образ сервиса
- **THEN** каталог графа не передаётся в контекст сборки, и состав образа
не меняется
### Requirement: Установка без побочных эффектов
Установка инструмента графа SHALL затрагивать только файлы этого
репозитория, перечисленные в change, и изолированное окружение самого
инструмента. Установка MUST NOT:
- менять глобальные инструкции и настройки Claude Code пользователя;
- добавлять хуки Claude Code, скиллы и инструкции агенту от инструмента
в настройки проекта или пользователя;
- добавлять git-хуки, merge driver и другие правки git-конфигурации;
- менять окружение и lock-файл зависимостей проекта;
- менять результат `make lint`, `make check` и сборки образа.
#### Scenario: Глобальные настройки не тронуты
- **WHEN** до и после установки сравниваются глобальные файл инструкций и
файл настроек Claude Code пользователя
- **THEN** содержимое совпадает
#### Scenario: Нет хуков
- **WHEN** после установки просматриваются настройки Claude Code проекта,
каталог git-хуков и git-конфигурация репозитория
- **THEN** новых хуков, merge driver и записей о графе в них нет
#### Scenario: Проект собирается как раньше
- **WHEN** после установки выполняются `make lint` и `make check`
- **THEN** `make lint` не меняет файлов, `make check` проходит, lock-файл
зависимостей без изменений
### Requirement: Граф не заменяет чтение файла перед правкой
Инструкции агента SHALL разделять роли: граф — для вопросов о структуре и
связях («где используется», «кто вызывает», «какое правило описывает
модуль»), а перед правкой файл MUST читаться целиком, как без графа,
чтобы подгрузилось правило слоя.
#### Scenario: Правило слоя подгружается при правке
- **WHEN** в новой сессии агента просят изменить файл в
`src/core/services/`
- **THEN** агент читает этот файл перед правкой, и правило сервисного
слоя попадает в его контекст
#### Scenario: Вопрос о связях
- **WHEN** агента спрашивают, какие модули зависят от хранилища в памяти
- **THEN** агент может ответить по графу, не открывая файлы по одному
### Requirement: Обновление графа вручную
Граф SHALL собираться и обновляться только по явной команде, без
обращений к LLM, за секунды, в том числе в чистом clone. Коммиты,
переключение веток и изменения файлов MUST NOT запускать пересборку.
#### Scenario: Коммит не пересобирает граф
- **WHEN** в репозитории делается коммит
- **THEN** артефакты графа не меняются
#### Scenario: Новый модуль после обновления
- **WHEN** в `src/` добавлен модуль, и выполнена команда обновления
- **THEN** модуль есть в графе, а команда не обращалась к LLM
#### Scenario: Сборка в чистом clone
- **WHEN** в clone без каталога графа выполняется команда обновления
- **THEN** граф собирается целиком
### Requirement: Схема кода в отчёте
Раздел «Архитектура и решения» в `REPORT.md` SHALL содержать схему
слоёв кода (api → service → repo → хранилище) и поток вызовов одной
операции — отправки сообщения — в виде блока Mermaid, который GitHub
показывает как диаграмму. Каждая связь на схеме MUST существовать в
коде. Описание процессов и хранилища в отчёте SHALL остаться: схема кода
его дополняет, а не заменяет. В отчёте SHALL быть указано, как схема
получена и какую роль в этом сыграл инструмент графа.
#### Scenario: Схема видна в PR
- **WHEN** проверяющий открывает `REPORT.md` на GitHub
- **THEN** схема отображается диаграммой, а не текстом
#### Scenario: Схема соответствует коду
- **WHEN** каждая стрелка схемы сверяется с кодом
- **THEN** для каждой есть реальный импорт или вызов между указанными
модулями
#### Scenario: Использование ИИ указано
- **WHEN** проверяющий читает, какая помощь ИИ использовалась
- **THEN** там названы инструмент графа и то, для чего он применялся
### Requirement: Перенос в следующую лабу
Список исключений графа SHALL переноситься в следующую лабу вместе с
инструкциями агента. Артефакты графа MUST NOT переноситься: в новом
репозитории граф собирается заново.
#### Scenario: Новая лаба
- **WHEN** решение переносится в skeleton следующей лабы по `AGENTS.md`
- **THEN** список исключений перенесён, а граф собирается заново после
переноса
+105
View File
@@ -0,0 +1,105 @@
# container-image Specification
## Purpose
Образ сервиса: как он собирается из исходников и что в нём есть.
Сборка воспроизводима из чистого clone, версии закреплены, процесс
работает без привилегий, конфиги и секреты в образ не попадают.
## Requirements
### Requirement: Сборка из чистого clone
`docker build` в корне свежего clone SHALL собирать образ без
предварительных шагов: без `make env_setup`, без `config.toml` и `.env`.
Зависимости SHALL устанавливаться строго по `uv.lock`. Если lock не
соответствует `pyproject.toml`, сборка MUST завершаться ошибкой, а не
пересчитывать версии.
#### Scenario: Свежий clone
- **WHEN** в новом clone репозитория выполняется
`docker build -t mtusi-messenger:lab1 .`
- **THEN** образ собирается без ошибок
#### Scenario: Устаревший lock
- **WHEN** в `pyproject.toml` добавлена зависимость, а `uv.lock` не
обновлён
- **THEN** сборка завершается ошибкой проверки lock
### Requirement: Закреплённые версии
Базовые образы и инструменты сборки SHALL указываться явной версией и
digest. Плавающие теги (`latest`, `3.12-slim` и подобные) MUST NOT
использоваться.
#### Scenario: Проверка Dockerfile
- **WHEN** проверяющий читает строки `FROM` и `COPY --from` в
`Dockerfile`
- **THEN** каждая ссылка на образ содержит версию с патч-номером и
`@sha256:`
### Requirement: Непривилегированный пользователь
Процесс сервиса SHALL работать не от root. Код приложения и зависимости
MUST NOT быть доступны этому пользователю на запись.
#### Scenario: UID процесса
- **WHEN** в работающем контейнере выполняется `id -u`
- **THEN** результат не равен 0
#### Scenario: Код только на чтение
- **WHEN** пользователь контейнера пытается записать файл в каталог с
кодом приложения
- **THEN** запись отклоняется с ошибкой доступа
### Requirement: Состав образа
Образ SHALL содержать только то, что нужно для работы сервиса:
интерпретатор, зависимости времени выполнения и исходники `src/`. В
образе MUST NOT быть `config.toml`, `.env`, публичных и собственных
тестов, контрактов, файлов `.claude` и `openspec`, а также инструментов
сборки: uv и компиляторов.
#### Scenario: Нет конфигов и лишних каталогов
- **WHEN** в образе просматривается рабочий каталог приложения
- **THEN** в нём есть только исходники и окружение зависимостей, а
`config.toml` и `.env` отсутствуют
#### Scenario: Нет uv в runtime
- **WHEN** в контейнере запрашивается `uv`
- **THEN** команда не найдена
### Requirement: Сервер — основной процесс контейнера
Процессом с PID 1 SHALL быть сам сервер (`python -m src`), без
оболочки и без `uv run` между Docker и сервером. Так сигналы
остановки доходят до сервера напрямую.
#### Scenario: PID 1
- **WHEN** в работающем контейнере читается командная строка процесса 1
- **THEN** это `python -m src`
### Requirement: Healthcheck образа
Образ SHALL объявлять healthcheck, который проверяет
`GET /health/ready` на внутреннем порту сервиса. Healthcheck MUST
работать и без compose, при запуске голым `docker run`.
#### Scenario: Контейнер становится healthy
- **WHEN** контейнер запущен и сервис завершил старт
- **THEN** `docker inspect` показывает состояние здоровья `healthy`
до окончания `start_period`
#### Scenario: Healthcheck не шумит в логах
- **WHEN** healthcheck отрабатывает несколько раз
- **THEN** итоговых записей о запросах к health в журнале сервиса нет
+168
View File
@@ -0,0 +1,168 @@
# container-run Specification
## Purpose
Как контейнер сервиса запускается и настраивается: два способа запуска —
голый `docker run` из README (`make run_no_compose`) и compose
(`make run_docker`), публикация портов, конфигурация на старте и
поведение состояния при рестарте контейнера.
## Requirements
### Requirement: Запуск командами из README
Команды из `README.md` SHALL работать без compose и без `config.toml`:
`docker build -t mtusi-messenger:lab1 .` и
`docker run --rm --name mtusi-messenger-lab1 -p 127.0.0.1:8080:8080 --env-file .env mtusi-messenger:lab1`.
Внутри контейнера сервис SHALL работать в режиме `docker` и слушать
`0.0.0.0:8080`, не требуя дополнительных переменных.
`make run_no_compose` SHALL выполнять эти две команды, подставляя в
`-p` порты из `.env` (требование «Порты из .env»): собирать образ и
запускать контейнер на переднем плане с журналом в терминале. Перед
этим он SHALL создавать недостающие `.env` и `config.toml` из шаблонов
(`make env_setup`) и MUST NOT перезаписывать существующие. С `.env`
из шаблона команда SHALL совпадать с README. Остановка — Ctrl+C в этом
терминале или `docker stop mtusi-messenger-lab1` из другого, после
чего контейнер удаляется (`--rm`).
#### Scenario: Публичный smoke против контейнера
- **WHEN** контейнер запущен командой из README или
`make run_no_compose`, а в другом терминале выполняется `make test`
- **THEN** результат — `PASS: lab1 public API scenario`
#### Scenario: Свежий clone без .env
- **WHEN** в свежем clone без `.env` выполнен `make run_no_compose`
- **THEN** `.env` создаётся из `.env.example`, сервис стартует и
публикуется на `127.0.0.1:8080`
#### Scenario: Остановка по Ctrl+C
- **WHEN** в терминале с `make run_no_compose` нажат Ctrl+C
- **THEN** сервис штатно завершается (в журнале есть «Shutting down» и
«Finished server process»), а контейнера `mtusi-messenger-lab1` после
этого нет в `docker ps -a`
#### Scenario: Без config.toml
- **WHEN** контейнер запущен без смонтированного `config.toml`
- **THEN** сервис стартует на значениях по умолчанию
### Requirement: Запуск через compose
`make run_docker` SHALL собирать образ и поднимать сервис `api` через
`docker compose`. Перед этим он SHALL создавать недостающие `.env` и
`config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать
существующие. `make stop` SHALL останавливать сервис, `make down` —
удалять контейнер, `make logs` — показывать журнал.
#### Scenario: Штатный запуск
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** сервис отвечает на `http://localhost:8080/health/ready`, и
`make test` проходит
### Requirement: Порты из .env
Оба способа запуска, `make run_no_compose` и `make run_docker`, SHALL
брать порты из одного `.env`:
- внутренний — `APP__PORT`: параметр приложения `[app] port` в формате
настроек, приложение читает его само, на нём же работает
healthcheck;
- внешний — `APP_OUT_PORT`: порт на `127.0.0.1` хоста, приложение его
не читает.
Если переменная не задана, SHALL действовать 8080. Параметры
приложения в `.env` SHALL записываться в формате настроек
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
которые приложение не читает.
#### Scenario: Другой внешний порт
- **WHEN** в `.env` задано `APP_OUT_PORT=8090`
- **THEN** при любом из двух способов API доступно на `localhost:8090`,
а внутри контейнера сервис слушает `APP__PORT`
#### Scenario: Другой внутренний порт
- **WHEN** в `.env` задано `APP__PORT=9090`
- **THEN** при любом из двух способов сервис внутри контейнера слушает
9090, контейнер становится `healthy`, а API доступно на
`localhost:$APP_OUT_PORT`
### Requirement: Оба способа запуска описаны в REPORT.md
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать оба
способа: `make run_no_compose` (без compose, команды README) и
`make run_docker` (compose). Для каждого SHALL быть указаны подготовка
(обе цели сами вызывают `make env_setup`), команды, которые выполняет
цель Makefile, ожидание готовности, `make test` и остановка.
#### Scenario: Запуск по отчёту
- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md`
для любого из двух способов
- **THEN** `/health/ready` отвечает 200, а `make test` проходит
### Requirement: Публикация только на localhost
Порт сервиса SHALL публиковаться только на `127.0.0.1` хоста: в
README-команде, в `make run_no_compose` и в compose. Учебный стенд
MUST NOT быть доступен с других машин сети.
#### Scenario: Адрес публикации
- **WHEN** для запущенного контейнера выполняется `docker port`
- **THEN** порт опубликован на `127.0.0.1`, а не на `0.0.0.0`
### Requirement: Конфигурация на старте
`config.toml` SHALL подключаться к контейнеру при запуске, только на
чтение, и MUST NOT копироваться в образ. В compose файл SHALL
монтироваться так, чтобы его отсутствие давало явную ошибку запуска, а
не создавало на хосте каталог `config.toml/`. Секреты, которые нужны и
compose, и приложению, SHALL передаваться через `environment` (см.
`.claude/rules/settings.md`).
#### Scenario: Правка config.toml
- **WHEN** в `config.toml` изменён `[app] log_level` и контейнер
перезапущен без пересборки образа
- **THEN** сервис работает с новым уровнем логирования
#### Scenario: Нет config.toml, запуск через make
- **WHEN** `make run_docker` запускается без `config.toml`
- **THEN** `config.toml` создаётся из `config_example.toml`, и сервис
стартует
#### Scenario: Нет config.toml, compose напрямую
- **WHEN** `docker compose up` запускается без `config.toml`
- **THEN** запуск завершается ошибкой о несуществующем источнике
монтирования, и каталог `config.toml/` на хосте не появляется
### Requirement: Состояние теряется при рестарте контейнера
Перезапуск контейнера SHALL давать пустое состояние: у контейнера нет
volume для данных. Это ожидаемое поведение лабы 1, его показывают на
защите.
#### Scenario: Жизненный цикл на защите
- **WHEN** пользователь создан, отправил сообщение и прочитал его, после
чего контейнер перезапущен тем же образом
- **THEN** запрос с прежним `X-User-Id` получает 401
### Requirement: Журнал контейнера
Журнал сервиса SHALL выводиться в stdout контейнера в формате
capability `service-logging`. Между Docker и журналом MUST NOT быть
посторонних строк лаунчера (например, от `uv`).
#### Scenario: docker logs
- **WHEN** выполняется `make logs` для работающего сервиса
- **THEN** каждая строка — JSON-запись сервиса или uvicorn
+53
View File
@@ -0,0 +1,53 @@
# data-storage Specification
## Purpose
Где живёт состояние мессенджера на лабе 1 и какие гарантии оно даёт:
память одного процесса, потеря при рестарте, защита от гонок при
параллельных запросах.
## Requirements
### Requirement: Состояние только в памяти одного процесса
Пользователи, чаты и сообщения SHALL храниться только в памяти одного
процесса сервиса. Сервис MUST NOT использовать базы данных, Redis,
файлы состояния и внешние сервисы. Все запросы экземпляра SHALL
обслуживаться одним общим состоянием, без нескольких worker-процессов
с независимой памятью.
#### Scenario: Созданное видно сразу
- **WHEN** клиент создал пользователя и следующим запросом использует
его `id` в `X-User-Id`
- **THEN** пользователь найден
### Requirement: Потеря состояния при рестарте
После перезапуска процесса состояние SHALL быть пустым. Это ожидаемое
поведение лабы 1.
#### Scenario: Прежний пользователь после рестарта
- **WHEN** сервис перезапущен и клиент использует `X-User-Id`,
созданный до рестарта
- **THEN** ответ 401
### Requirement: Параллельные запросы не повреждают состояние
Параллельные запросы MUST NOT терять, дублировать или повреждать
записи. Проверки с последующей записью (уникальность `username`)
SHALL выполняться атомарно.
#### Scenario: 100 сообщений от 10 клиентов
- **WHEN** 10 клиентов одновременно отправляют по 10 сообщений в один
чат
- **THEN** получено 100 ответов 201, а полный обход истории возвращает
ровно 100 сообщений с уникальными `id`
#### Scenario: Гонка за username
- **WHEN** несколько клиентов одновременно регистрируют одинаковый
`username`
- **THEN** создан ровно один пользователь
+59
View File
@@ -0,0 +1,59 @@
# graceful-shutdown Specification
## Purpose
Как сервис останавливается по SIGTERM: перестаёт принимать новые
запросы, дорабатывает текущие и завершается за заявленный срок, до
того как Docker применит SIGKILL.
## Requirements
### Requirement: Новые запросы после SIGTERM не принимаются
После получения SIGTERM сервис SHALL прекращать принимать новые
соединения и MUST NOT начинать обработку новых запросов на уже
открытых простаивающих соединениях.
#### Scenario: Нагрузка во время остановки
- **WHEN** во время непрерывной отправки сообщений контейнеру
отправлен SIGTERM
- **THEN** запросы, начатые после сигнала, завершаются ошибкой
соединения, а не ответом сервиса
### Requirement: Текущие запросы дорабатывают
Запросы, начатые до SIGTERM, SHALL получать ответ, если укладываются в
срок `[app] graceful_shutdown_seconds`. Запросы, которые не уложились,
SHALL отменяться, чтобы процесс всё равно завершился.
#### Scenario: Запрос в полёте
- **WHEN** SIGTERM приходит, пока сервис обрабатывает запрос
- **THEN** клиент получает ответ на этот запрос, после чего процесс
завершается
### Requirement: Завершение за заявленный срок
Процесс SHALL завершаться после SIGTERM не дольше чем за
`[app] graceful_shutdown_seconds` плюс время shutdown в lifespan. Это
значение MUST быть не больше 9 с: Docker применяет SIGKILL через 10 с.
Код выхода MUST NOT быть 137 (SIGKILL).
#### Scenario: docker stop
- **WHEN** выполняется `docker stop` для работающего контейнера
- **THEN** команда завершается быстрее 10 с, а код выхода контейнера не
равен 137
### Requirement: Остановка видна в журнале
Этапы остановки SHALL записываться в журнал сервиса JSON-записями с
временем: начало остановки, завершение lifespan, завершение процесса.
По меткам времени SHALL определяться длительность остановки.
#### Scenario: Журнал остановки
- **WHEN** контейнер остановлен по SIGTERM
- **THEN** в журнале по порядку есть «Shutting down», «Stopped API» и
«Finished server process», и разница их `timestamp` меньше 10 с
+49
View File
@@ -0,0 +1,49 @@
# health Specification
## Purpose
Проверки жизни и готовности сервиса для оператора, healthcheck
контейнера и публичного smoke: жив ли процесс и можно ли направлять на
него трафик.
## Requirements
### Requirement: Liveness
`GET /health/live` SHALL отвечать 200 с телом `{"status": "ok"}`, пока
процесс обслуживает HTTP. Проверка MUST NOT требовать идентификации и
MUST NOT зависеть от состояния хранилища.
#### Scenario: Процесс жив
- **WHEN** клиент запрашивает `GET /health/live` без заголовков
- **THEN** ответ 200, тело `{"status": "ok"}`, есть `X-Request-Id`
### Requirement: Readiness
`GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`,
когда сервис может безопасно обслуживать обязательные запросы, и 503 с
`code` `unavailable` в формате ошибки, когда не может. На лабе 1
критичная зависимость одна — хранилище в памяти процесса, готовое после
завершения запуска. Проверка MUST NOT требовать идентификации.
#### Scenario: Сервис запущен
- **WHEN** запуск сервиса завершён и клиент запрашивает `GET /health/ready`
- **THEN** ответ 200, тело `{"status": "ok"}`
#### Scenario: Хранилище не готово
- **WHEN** хранилище ещё не инициализировано
- **THEN** ответ 503 с `code` `unavailable` в формате ошибки
### Requirement: Health вне версии API и без идентификации
Эндпоинты health SHALL находиться вне префикса `/api/v1` и SHALL
игнорировать `X-User-Id`.
#### Scenario: Неизвестный X-User-Id
- **WHEN** клиент запрашивает health с `X-User-Id` несуществующего
пользователя
- **THEN** ответ 200, а не 401
+87
View File
@@ -0,0 +1,87 @@
# identification Specification
## Purpose
Выбор текущего пользователя на лабе 1 через заголовок `X-User-Id` и
порядок проверок «идентификация → доступ к ресурсу». Это учебная
идентификация, а не аутентификация: любой клиент может выдать себя за
другого. С лабы 2 её заменяет Bearer-сессия.
## Requirements
### Requirement: Защищённые эндпоинты требуют X-User-Id
Все эндпоинты, кроме `POST /api/v1/users` и health, SHALL требовать
заголовок `X-User-Id` с UUID существующего пользователя. Этот
пользователь SHALL считаться текущим для запроса.
#### Scenario: Корректный заголовок
- **WHEN** клиент вызывает `GET /api/v1/users/me` с `X-User-Id`
существующего пользователя
- **THEN** ответ 200 с этим пользователем
### Requirement: Отказ в идентификации — 401
Сервис SHALL отвечать 401 с `code` `unauthorized`, когда заголовок
`X-User-Id` отсутствует, не является UUID или указывает на
несуществующего пользователя. Эти три случая MUST давать одинаковый
ответ и MUST NOT давать 400.
#### Scenario: Нет заголовка
- **WHEN** клиент вызывает `GET /api/v1/users/me` без `X-User-Id`
- **THEN** ответ 401 с `code` `unauthorized`
#### Scenario: Не UUID
- **WHEN** `X-User-Id` равен `not-a-uuid`
- **THEN** ответ 401 с `code` `unauthorized`
#### Scenario: Неизвестный пользователь
- **WHEN** `X-User-Id` — корректный UUID, но такого пользователя нет
- **THEN** ответ 401 с `code` `unauthorized`
### Requirement: Идентификация раньше доступа и валидации
Идентификация SHALL проверяться раньше доступа к конкретному ресурсу и
раньше проверки пути, query и полей тела. Исключение, согласованное с
преподавателем 2026-09-26: тело, которое не разбирается как JSON,
отклоняется с 400 до идентификации.
#### Scenario: Чужой чат без заголовка
- **WHEN** клиент без `X-User-Id` запрашивает существующий чат
- **THEN** ответ 401, а не 404
#### Scenario: Невалидное поле без заголовка
- **WHEN** клиент без `X-User-Id` отправляет сообщение с `{"text": ""}`
- **THEN** ответ 401, а не 400
#### Scenario: Битый JSON без заголовка
- **WHEN** клиент без `X-User-Id` отправляет тело `{bad`
- **THEN** ответ 400 с `code` `invalid_request`
### Requirement: Схема идентификации в документации API
Документация, которую отдаёт сервис (`/openapi.json` и `/docs`), SHALL
объявлять схему `devUser` так же, как `contracts/openapi.json`: `apiKey`
в заголовке `X-User-Id`. Защищённые операции SHALL ссылаться на неё,
публичные (`POST /api/v1/users`, health) MUST NOT. Объявление схемы
MUST NOT менять ответы: без заголовка по-прежнему 401, а не 400 или 403.
#### Scenario: Кнопка Authorize в Swagger
- **WHEN** разработчик открывает `/docs`
- **THEN** доступна кнопка Authorize с полем `X-User-Id`, и введённое
значение уходит заголовком в защищённые запросы
#### Scenario: Схема в openapi.json
- **WHEN** клиент запрашивает `/openapi.json`
- **THEN** `components.securitySchemes.devUser` совпадает с контрактом,
у `GET /api/v1/users/me` `security` равно `[{"devUser": []}]`, а у
`POST /api/v1/users` `security` нет
+482
View File
@@ -0,0 +1,482 @@
# load-benchmark Specification
## Purpose
Воспроизводимый нагрузочный эксперимент трека 1: одной командой
поднимает стенд с фиксированными лимитами, прогоняет матрицу размеров
истории и уровней конкуренции для чтения и записи и сохраняет сырые
данные, сводку и паспорт стенда, чтобы сравнивать версии кода при
одинаковых условиях. К стенду прилагаются диагностика стоимости
запроса, сравнение двух меток и прогоны «до» и «после» одного
изменения подряд.
## Requirements
### Requirement: Запуск одной командой
Полная матрица SHALL запускаться командой `make bench` с меткой
результата `BENCH_LABEL` (по умолчанию `baseline`), короткий прогон —
командой `make bench_quick`. Результаты SHALL сохраняться в
`evidence/bench/<метка>/`. Команда MUST NOT перезаписывать результаты
существующей метки и MUST NOT использовать порт 8080 хоста и
контейнеры `make run_dev` / `make run_docker`. После завершения, в том
числе с ошибкой или по Ctrl+C, контейнеры и сеть стенда SHALL
удаляться.
#### Scenario: Полная матрица
- **WHEN** выполняется `make bench BENCH_LABEL=baseline`
- **THEN** прогоняется вся матрица, результаты лежат в
`evidence/bench/baseline/`, код выхода 0
#### Scenario: Метка уже занята
- **WHEN** каталог `evidence/bench/<метка>/` уже существует
- **THEN** команда завершается с ненулевым кодом до запуска стенда и
называет каталог
#### Scenario: Рабочий стенд не затронут
- **WHEN** во время прогона запущен `make run_docker` на 8080
- **THEN** он продолжает отвечать, его контейнер и данные не меняются
#### Scenario: Прерывание
- **WHEN** прогон прерван Ctrl+C
- **THEN** контейнеры и сеть стенда удалены, частичные результаты
помечены как незавершённые
### Requirement: Фиксированный стенд
Приложение SHALL запускаться в контейнере из образа, собранного из
текущего checkout тем же `Dockerfile`, с одинаковыми во всех прогонах
лимитами: 1 CPU, 2 ГБ памяти без swap. Healthcheck образа SHALL быть
отключён, порты на хост MUST NOT публиковаться. Генератор нагрузки
SHALL работать в той же docker-сети и обращаться к приложению по имени
контейнера, минуя проброс портов хоста.
#### Scenario: Лимиты в паспорте
- **WHEN** прогон завершён
- **THEN** паспорт стенда содержит лимиты CPU и памяти контейнера
приложения, прочитанные у запущенного контейнера, и они одинаковы для
всех прогонов
#### Scenario: Нехватка памяти
- **WHEN** процесс приложения превысил лимит памяти и был убит
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
обычный результат
### Requirement: Сценарии нагрузки
Стенд SHALL поддерживать два сценария с синтетическими данными
фиксированной длины:
- `read` — запрос страницы истории (`limit=50`) чата из N сообщений.
Каждый запрос берёт курсор случайно из пула, равномерно покрывающего
всю историю. В пул входят только позиции, после которых есть не
меньше 50 сообщений, поэтому каждый ответ содержит ровно 50
элементов. Данные при этом не меняются;
- `write` — отправка сообщения в отдельный чат, чтобы история чата
сценария `read` оставалась ровно N.
Последовательность случайных выборов SHALL задаваться фиксированным
зерном из профиля, у каждого клиента — своя последовательность: при
том же профиле и том же N прогоны разных меток отправляют одинаковые
запросы, а одновременные клиенты не повторяют друг друга. Каждый ответ
SHALL проверяться на
ожидаемый статус; неожиданные статусы и ошибки соединения SHALL
считаться ошибками прогона.
#### Scenario: Полная страница
- **WHEN** выполняется любой запрос сценария `read`
- **THEN** ответ содержит ровно 50 сообщений
#### Scenario: Одинаковые запросы в разных метках
- **WHEN** один профиль запускается под двумя метками на одинаковом N
- **THEN** каждый клиент выбирает курсоры в той же последовательности,
что и в другой метке, а последовательности разных клиентов различны
#### Scenario: Чтение не меняет данные
- **WHEN** выполнены все прогоны `read` для размера N
- **THEN** в читаемом чате по-прежнему ровно N сообщений
#### Scenario: Ошибки учитываются
- **WHEN** часть ответов не 200 (`read`) или не 201 (`write`)
- **THEN** они входят в долю ошибок прогона и не входят в перцентили
задержки успешных запросов
### Requirement: Матрица и повторы
Полная матрица SHALL включать размеры истории 10 000, 100 000 и
1 000 000 сообщений, уровни конкуренции 1, 10 и 50 одновременных
клиентов и оба сценария, по 3 измеряемых прогона на ячейку. Перед
каждым измеряемым прогоном SHALL идти прогрев с той же нагрузкой, не
входящий в результат. Каждый размер SHALL начинаться с нового процесса
приложения, наполненного через HTTP API до ровно N сообщений в читаемом
чате. Рост хранилища за прогоны `write` SHALL фиксироваться в
результатах.
#### Scenario: Состав матрицы
- **WHEN** полная матрица завершена
- **THEN** в результатах 54 измеряемых прогона: 3 размера × 3 уровня
конкуренции × 2 сценария × 3 повтора
#### Scenario: Свежий процесс на каждый размер
- **WHEN** начинается размер N
- **THEN** контейнер приложения запущен заново и перед первым прогоном
содержит ровно N сообщений в читаемом чате
### Requirement: Метрики прогона
Для каждого измеряемого прогона SHALL сохраняться: сценарий, размер
истории, конкуренция, номер повтора, длительность, число успешных и
неуспешных запросов, успешные RPS, доля ошибок, задержки p50, p95, p99
и max успешных запросов, потреблённое приложением CPU, RSS процесса
приложения в начале, в конце и максимальный за прогон, число сообщений
в хранилище в начале и в конце, загрузка CPU генератора. Для каждого
размера SHALL сохраняться RSS до и после наполнения и оценка байт RSS
на сообщение.
Наполнение SHALL идти порциями, и для каждой порции SHALL сохраняться:
размер, число сообщений в хранилище до и после, успешные RPS, доля
ошибок, задержки p50, p95, p99 и max, CPU приложения и RSS в конце
порции. Так наполнение до 1 000 000 даёт кривую «запись при росте
хранилища» без дополнительного времени прогона.
#### Scenario: Строка прогона
- **WHEN** проверяющий открывает таблицу прогонов
- **THEN** у каждой строки заполнены все перечисленные поля
#### Scenario: Память на сообщение
- **WHEN** наполнение размера N завершено
- **THEN** в результатах есть прирост RSS за наполнение и байты на
сообщение
#### Scenario: Кривая наполнения
- **WHEN** наполнение размера 1 000 000 завершено
- **THEN** в таблице наполнения есть строка на каждую порцию, от
пустого хранилища до 1 000 000 сообщений, с RPS, p95, p99, max и
RSS
### Requirement: Достоверность прогона
Прогон SHALL помечаться в результатах, если его данные нельзя считать
замером сервера: процесс приложения перезапускался или был убит,
генератор нагрузки был загружен настолько, что мог сам ограничивать
throughput, или доля ошибок больше нуля. Сводка SHALL показывать эти
пометки рядом со значениями.
#### Scenario: Генератор упёрся в CPU
- **WHEN** загрузка CPU генератора за прогон выше порога, заданного в
методике
- **THEN** прогон помечен, и в сводке рядом с его ячейкой видна пометка
### Requirement: Ход прогона виден
Во время прогона команда SHALL печатать строку на каждый этап (сборка
образа, запуск стенда, наполнение, сбор курсоров, каждый измеряемый
прогон) с временем от начала. Наполнение SHALL показывать прогресс не
реже раза в минуту: сколько сообщений из N, скорость, оценку
оставшегося времени. После каждого измеряемого прогона SHALL
печататься его номер из общего числа, ячейка матрицы, основные
результаты (RPS, p50, p95, p99, CPU приложения, RSS, доля ошибок),
пометки и оценка времени до конца матрицы. В каталоге метки SHALL
поддерживаться файл текущего состояния, а строка прогона SHALL
дописываться в таблицу прогонов сразу после прогона.
#### Scenario: Где мы сейчас
- **WHEN** идёт наполнение размера 1M
- **THEN** в выводе не реже раза в минуту появляется строка с числом
отправленных сообщений, скоростью и оценкой оставшегося времени
#### Scenario: Результат сразу после прогона
- **WHEN** завершился измеряемый прогон
- **THEN** в выводе появляется строка вида «прогон k из 54, сценарий,
размер, конкуренция, повтор: RPS, p50/p95/p99, CPU, RSS, ошибки,
пометки, осталось ~T», а в таблице прогонов — его строка
#### Scenario: Наблюдение из другого терминала
- **WHEN** прогон запущен, и пользователь открывает файл состояния в
каталоге метки
- **THEN** там текущий этап, число завершённых прогонов из общего,
оценка оставшегося времени и результат последнего прогона
#### Scenario: Частичные результаты
- **WHEN** прогон прерван на середине матрицы
- **THEN** строки уже завершённых прогонов есть в таблице прогонов
### Requirement: Сохранение результатов
В каталоге метки SHALL лежать:
- сырой результат генератора для каждого прогона и каждой порции
наполнения;
- таблица всех прогонов в CSV;
- таблица порций наполнения в CSV;
- сводка по ячейкам матрицы (медиана и разброс min–max по повторам) в
Markdown;
- паспорт стенда: дата, commit и признак незакоммиченных изменений,
digest образа приложения, версии генератора и Python, лимиты, железо
хоста и VM, параметры профиля и команда запуска;
- состояние хоста в начале и в конце прогона: занятый swap, доля
свободной памяти, питание от сети или от батареи.
Если в начале прогона хост работает от батареи или swap занят сверх
порога методики, команда SHALL предупреждать об этом в выводе и в
паспорте, но не прерываться. Данные MUST быть синтетическими;
результаты MUST NOT содержать секретов, `.env` и абсолютных путей
домашнего каталога.
#### Scenario: Повтор на другой машине
- **WHEN** другой человек берёт паспорт и команду из каталога метки
- **THEN** он может запустить тот же профиль на своём checkout и
сравнить таблицы по тем же столбцам
#### Scenario: Условия хоста для сравнения меток
- **WHEN** проверяющий сравнивает две метки
- **THEN** по паспортам видно, одинаковы ли были swap, свободная
память и питание хоста в начале и в конце каждого прогона
#### Scenario: Неподходящий хост
- **WHEN** прогон запускается от батареи или с занятым swap выше порога
- **THEN** вывод команды и паспорт содержат предупреждение, а прогон
продолжается
### Requirement: Базовый замер в отчёте
Результат полной матрицы текущего кода SHALL быть сохранён под меткой
`baseline`. `REPORT.md` SHALL описывать в разделе экспериментов
гипотезы, стенд и лимиты, профиль нагрузки, результаты по ячейкам со
ссылкой на каталог `evidence/bench/baseline/` и ограничения замера.
#### Scenario: Проверяющий читает отчёт
- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md`
- **THEN** в нём есть гипотезы, условия стенда, таблица результатов и
путь к сырым данным
### Requirement: Разложение стоимости запроса
Команда `make bench_inproc` SHALL раскладывать время обработки одного
запроса внутри приложения на части, чтобы узкое место находилось
измерением, а не догадкой. Приложение SHALL вызываться в том же
процессе, без сервера и сети, на синтетических данных с фиксированным
зерном. Вывод SHALL содержать:
- время на запрос сценариев `read` и `write` при обычном уровне логов
и при выключенных записях уровня INFO; разница — цена логов, отдельно
сборка записи и запись в stdout контейнера;
- время частей построения ответа страницы истории, в том числе вариант
без форматирования времени в Python; разница — цена форматирования;
- функции с наибольшим собственным временем и числом вызовов на запрос;
- медиану и разброс min–max каждого измерения: по запускам процесса
для времени на запрос, по повторам для частей ответа;
- дату, commit, признак незакоммиченных изменений, версии Python и
библиотек, машину хоста.
Результат SHALL сохраняться в `evidence/profile/<метка>.txt`. Команда
MUST NOT перезаписывать файл существующей метки. Числа этой команды
MUST NOT выдаваться за результат стенда: она объясняет, куда уходит
время, а пропускную способность и задержки меряет только `make bench`.
Команда SHALL также сверять текущее форматирование времени с эталонной
записью формата `ГГГГ-ММ-ДДTЧЧ:ММ:СС.ffffffZ` на наборе значений,
включающем нулевые микросекунды и время в другом часовом поясе, и
проверять, что строка разбирается обратно в то же значение. При
расхождении команда SHALL завершаться с ненулевым кодом и называть
значение.
#### Scenario: Разложение чтения
- **WHEN** выполняется `make bench_inproc BENCH_LABEL=<метка>`
- **THEN** в `evidence/profile/<метка>.txt` есть время на запрос `read`
и `write`, цена логов, цена построения ответа и цена форматирования
времени, у каждого числа — медиана и разброс
#### Scenario: До и после изменения
- **WHEN** команда выполнена на коде до изменения и на коде после него
под разными метками
- **THEN** по двум файлам видно, какая часть запроса подешевела и на
сколько, а какие части не изменились
#### Scenario: Метка уже занята
- **WHEN** файл `evidence/profile/<метка>.txt` уже существует
- **THEN** команда завершается с ненулевым кодом и называет файл
#### Scenario: Формат времени изменился
- **WHEN** форматирование времени даёт строку, отличную от эталонной,
хотя бы для одного значения набора
- **THEN** команда завершается с ненулевым кодом и печатает значение,
ожидаемую и полученную строки
### Requirement: Сравнение двух меток
Команда `make bench_compare BEFORE=<метка> AFTER=<метка>` SHALL
сравнивать результаты двух меток полной матрицы и сохранять таблицу в
`evidence/compare/<до>__<после>.md`. Для каждой ячейки матрицы таблица
SHALL содержать медиану и разброс min–max повторов RPS в обеих метках,
изменение медианы в процентах, медианы p50, p95 и p99 и CPU приложения
на один запрос. Для каждого размера истории — байты RSS на сообщение в
обеих метках.
Команда SHALL отказываться сравнивать метки, снятые разной методикой:
если различаются параметры профиля, лимиты контейнера приложения или
образ генератора, она завершается с ненулевым кодом, называет
различие и не создаёт таблицу. Параметр, записанный в паспорте только
одной из меток, SHALL перечисляться в таблице как непроверенный, без
отказа. Незавершённая метка, незакоммиченные изменения, предупреждения
о хосте и помеченные прогоны SHALL перечисляться в начале таблицы.
С необязательным параметром `AA=<метка>` команда SHALL оценивать
уровень шума: наибольшее по ячейкам сценария изменение медианы RPS
между метками `AA` и `BEFORE`, снятыми на одном и том же коде
приложения. Изменение в ячейке SHALL называться эффектом, только если
разбросы повторов двух меток не пересекаются и изменение медианы
больше уровня шума её сценария; иначе — изменением в пределах шума.
#### Scenario: Сравнимые метки
- **WHEN** сравниваются две завершённые метки одного профиля с
одинаковыми лимитами и генератором
- **THEN** в таблице 18 ячеек (2 сценария × 3 размера × 3 уровня
конкуренции) с медианами, разбросом и изменением в процентах, а в
начале — commit и условия хоста каждой метки
#### Scenario: Разная методика
- **WHEN** у меток различается параметр профиля, лимит контейнера или
образ генератора
- **THEN** команда завершается с ненулевым кодом, называет параметр и
оба значения, таблица не создаётся
#### Scenario: Параметр только в одной метке
- **WHEN** параметр профиля записан в паспорте одной метки и отсутствует
в паспорте другой
- **THEN** сравнение выполняется, а параметр назван в таблице как
непроверенный
#### Scenario: Уровень шума
- **WHEN** задан `AA` — метка того же кода приложения, что и `BEFORE`
- **THEN** таблица содержит уровень шума по каждому сценарию и для
каждой ячейки вывод: эффект или изменение в пределах шума
#### Scenario: Метка сама с собой
- **WHEN** `BEFORE` и `AFTER` — одна и та же метка
- **THEN** изменение во всех ячейках равно нулю
### Requirement: Прогоны «до» и «после» подряд
Команда `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=<commit>`
SHALL снимать метки «до» и «после» одного изменения подряд, без
работы на хосте между ними. В рабочем дереве лежит код «до», а
изменение закоммичено и откачено отдельным commit; `REAPPLY` — commit
отката. Команда SHALL по порядку выполнить: полную матрицу и
разложение стоимости запроса для `BEFORE`, commit их результатов,
возврат изменения новым commit, полную матрицу и разложение для
`AFTER`. Матрица SHALL идти раньше разложения, чтобы в паспорте метки
не было признака незакоммиченных изменений.
Команда SHALL отказываться стартовать, ничего не запустив, если
рабочее дерево не чистое, файлы одной из меток уже существуют, метки
совпадают или commit `REAPPLY` не найден в текущей ветке. Если шаг
завершился с ошибкой, следующие шаги MUST NOT выполняться, а команда
SHALL назвать этот шаг. Команда создаёт commit в текущей ветке и MUST
NOT отправлять его в удалённый репозиторий.
#### Scenario: Оба прогона без участия человека
- **WHEN** на чистом рабочем дереве выполняется `make bench_ab` со
свободными метками и commit отката
- **THEN** обе метки сняты полностью, у обеих в паспорте нет признака
незакоммиченных изменений, а код приложения между их commit
отличается возвращённым изменением
#### Scenario: Нечистое рабочее дерево
- **WHEN** в рабочем дереве есть незакоммиченные изменения
- **THEN** команда завершается с ненулевым кодом до первого шага и
называет причину
#### Scenario: Метка занята
- **WHEN** каталог метки стенда или файл разложения одной из меток уже
существует
- **THEN** команда завершается с ненулевым кодом до первого шага и
называет путь
#### Scenario: Шаг завершился с ошибкой
- **WHEN** один из шагов вернул ненулевой код
- **THEN** следующие шаги не выполняются, команда называет номер шага
и завершается с ненулевым кодом
### Requirement: Сравнение «до/после» в отчёте
Результаты полной матрицы на коде до изменения и после него SHALL
быть сохранены под разными метками, снятыми в одной сессии хоста при
одинаковых лимитах и одном профиле. Между этими метками код приложения
SHALL отличаться одним изменением. `REPORT.md` SHALL описывать в
разделе экспериментов:
- как искали узкое место: метод, числа и путь к сохранённому выводу;
- почему прежнее решение было выбрано и что при этом не измерялось;
- что именно изменено, какие части сервиса это затрагивает и какие
свойства ответа сохраняются;
- предсказание результата, записанное до замера «после», и условие,
при котором оно считается опровергнутым;
- методику измерения дельты: какие метки сравниваются, как оценён
уровень шума и по какому правилу изменение считается эффектом;
- результаты по ячейкам со ссылкой на таблицу сравнения и каталоги
меток, включая ячейки, где эффекта нет;
- почему изменение дало такой результат и что осталось узким местом;
- ограничения сравнения.
Результат SHALL записываться таким, каким получился: если предсказание
не подтвердилось, отчёт SHALL это говорить.
#### Scenario: Проверяющий читает сравнение
- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md`
- **THEN** он находит метод поиска узкого места, причину прежнего
решения, описание изменения и его влияния, предсказание, методику
измерения дельты, таблицу «до/после» и пути к сырым данным
#### Scenario: Одно изменение
- **WHEN** проверяющий сравнивает commit меток «до» и «после»
- **THEN** код приложения между ними отличается только описанным в
отчёте изменением
#### Scenario: Контрольные ячейки
- **WHEN** изменение затрагивает только один сценарий нагрузки
- **THEN** отчёт показывает и ячейки другого сценария, чтобы было
видно, что разница не вызвана условиями прогона
#### Scenario: Предсказание не подтвердилось
- **WHEN** изменение в ячейках оказалось в пределах шума или
противоположного знака
- **THEN** отчёт называет предсказание опровергнутым и приводит
фактические числа
+84
View File
@@ -0,0 +1,84 @@
# messages Specification
## Purpose
Текстовые сообщения в чате: отправка от имени текущего пользователя и
чтение истории чата его участниками в порядке `(created_at, id)`.
## Requirements
### Requirement: Отправка сообщения
`POST /api/v1/chats/{chat_id}/messages` SHALL принимать тело
`{"text": ...}` и при успехе отвечать 201 с объектом `Message`: `id`,
`chat_id`, `sender_id`, `text`, `created_at`, без других полей.
`sender_id` SHALL быть текущим пользователем, `text` — совпадать с
отправленным.
#### Scenario: Участник отправляет сообщение
- **WHEN** Алиса отправляет `"Привет, мир 👋"` в свой чат
- **THEN** ответ 201, `sender_id` — Алиса, `chat_id` — этот чат, `text`
равен `"Привет, мир 👋"`
### Requirement: Валидация текста
`text` SHALL содержать от 1 до 4000 Unicode code points и MUST NOT
состоять только из пробельных символов. Поле `sender_id` в теле MUST NOT
приниматься. Нарушения SHALL давать 400 `invalid_request`.
#### Scenario: Пустой текст
- **WHEN** участник отправляет `{"text": ""}`
- **THEN** ответ 400
#### Scenario: Граница длины
- **WHEN** текст из 4000 code points, затем из 4001
- **THEN** первый запрос даёт 201, второй — 400
#### Scenario: Попытка подменить отправителя
- **WHEN** тело содержит `sender_id` другого пользователя
- **THEN** ответ 400, сообщение не создаётся
### Requirement: Писать и читать могут только участники
Отправка и чтение истории SHALL быть доступны только участникам чата.
Посторонний и запрос к несуществующему чату SHALL получать одинаковый
404 `not_found`; сообщение при этом MUST NOT создаваться.
#### Scenario: Посторонний пишет
- **WHEN** Ева отправляет сообщение в чат Алисы и Боба
- **THEN** ответ 404, в истории чата новых сообщений нет
#### Scenario: Посторонний читает
- **WHEN** Ева запрашивает историю чата Алисы и Боба
- **THEN** ответ 404
### Requirement: История чата
`GET /api/v1/chats/{chat_id}/messages` SHALL возвращать сообщения чата
в порядке `(created_at, id)` по возрастанию, с постраничным выводом по
capability `pagination`. Любой участник SHALL видеть все сообщения
чата, в том числе чужие.
#### Scenario: Два участника, две страницы
- **WHEN** Алиса и Боб отправили по сообщению, и Боб читает историю с
`limit=1`, а затем продолжает по курсору
- **THEN** первая страница содержит одно сообщение и непустой
`next_cursor`, вторая — второе сообщение и `next_cursor` null, а
порядок совпадает с `(created_at, id)`
### Requirement: Подтверждённое сообщение сразу видно
Сообщение, на которое сервис ответил 201, SHALL присутствовать в
любом следующем чтении истории этого чата.
#### Scenario: Чтение после записи
- **WHEN** участник получил 201 на отправку и сразу читает историю
- **THEN** сообщение есть в истории

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