ЛР 3 — БВТ2301 — Сафронов — на 5, трек 1 #6

Closed
ricoroma wants to merge 127 commits from ricoroma/mtusi2026lab3-safronov:solution/bvt2301-safronov into main
1289 changed files with 181939 additions and 26 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"
+252
View File
@@ -0,0 +1,252 @@
---
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` без `Authorization`, заголовок объявлен `Header()` | 422 | 401 |
| `POST .../messages` с `{"text": ""}` | 422 | 400 |
| `GET .../messages?limit=0` | 422 | 400 |
| любая ошибка | `{"detail": ...}` | формат контракта |
- Один обработчик `RequestValidationError` → 400 `invalid_request` в
формате контракта. Оставлять 422 выборочно сложнее, чем перевести всё,
поэтому 422 не отдаётся вообще.
- `Authorization` не объявлять типизированным `Header()`: пропуск уйдёт
в валидацию и даст 400 вместо 401. Схемы безопасности — те же, что в
контракте (`bearerAuth`, `basicAuth`): тогда они есть в
`/openapi.json`, а в `/docs` работает кнопка Authorize.
- Бизнес-ручки: `HTTPBearer(scheme_name="bearerAuth",
auto_error=False)` в `get_current_user`. Без заголовка или со схемой
не `Bearer` она отдаёт `None`, и 401 бросает сервис.
- Вход: встроенный `HTTPBasic` не годится даже с `auto_error=False`.
Он декодирует credentials как ASCII и на пароле не из ASCII сам
бросает 401, минуя сервис (проверено на FastAPI 0.141.1), а контракт
требует UTF-8. Схема `basicAuth` объявляется, но заголовок
разбирается своим кодом (`auth.md`).
- Порядок проверок не выправлять, это и есть разрешённое расхождение.
Битый JSON FastAPI разбирает до зависимостей, поэтому запрос без
`Authorization` с битым JSON получит 400, а не 401. Остальная валидация
(тело, путь, query) идёт после зависимостей, там 401 приходит первым.
Расхождение перечислить в `REPORT.md` со ссылкой на согласование.
- `StarletteHTTPException` (404 неизвестного пути, 405) и `Exception`
(500) тоже переводятся в формат контракта.
## Формат ответов
- Непустой `X-Request-Id` в **каждом** ответе: успех, ошибка, health,
404 неизвестного пути, 405, 500. С лабы 3 так же — непустой
`X-Instance-Id` (раздел «Балансировка и повторная отправка» ниже):
smoke проверяет его на каждом ответе, начиная с `/health/live`.
- Любая ошибка: `{"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, лишнее поле, неверный тип; с лабы 3 — нет или неверный `Idempotency-Key` у `POST` сообщения |
| 401 | `unauthorized` | вход: неверные username или пароль, битый Basic; остальное: нет Bearer, токен неизвестен, истёк или отозван, пришёл Basic. Всегда с `WWW-Authenticate` (`auth.md`) |
| 404 | `not_found` | объекта нет **или** он чужой; неизвестный путь |
| 409 | `conflict` | `username` занят; с лабы 3 — тот же `Idempotency-Key` с другим телом сообщения |
| 500 | `internal_error` | необработанное исключение, без деталей |
| 503 | `unavailable` | недоступен Postgres или хранилище сессий: ограниченная ошибка вместо 500 (`infra.md`) |
`413`, `415`, `429` в схеме есть, но на лабе 3 обязательной причины для
них нет. Для 429 нужен `Retry-After`. `DELETE /auth/sessions/current`
отвечает 204 без тела.
- Время — 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 в формате ошибки: 200 только если доступен
Postgres и всё, без чего не работает обязательный путь (`infra.md`).
Обе без идентификации.
## Валидация → 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`, `password`) не
могут состоять только из пробельных символов (`str.strip()` пустой →
400). Само значение не обрезать.
- Длины считаются в Unicode code points: `len(str)` в Python как раз они.
`display_name` и `title` — 1–100, `text` — 1–4000, `password` —
12–128.
- `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.
- UUID на входе — только запись 8-4-4-4-12 (`format: uuid`), цифры в
любом регистре (спек `api-conventions`, «UUID на входе»). `UUID`
pydantic шире контракта: принимает запись без дефисов, с `urn:uuid:` и
в `{…}` (проверено на pydantic 2.13). Поэтому всё, что UUID передаёт
клиент, — `chat_id` в пути и элементы `member_ids`, с лабы 4 и
`attachment_ids`, — объявляется типом `UuidIn` из
`src/api/schemas/common.py` (`BeforeValidator` с `UUID_PATTERN` и
`re.fullmatch`), а не голым `UUID`. Модели ответов — обычный `UUID`.
Не-строку `UuidIn` отдаёт валидатору `UUID`, и `[]`, `{}`, `123`,
`false` дают 400 по типу.
## Аутентификация и сессии (лаба 2)
Переход 1 → 2 (`COURSE.md`): регистрация требует `password`,
`X-User-Id` заменён Bearer. Реализация — `auth.md`.
- Без аутентификации — только `POST /api/v1/users` и health.
`POST /api/v1/auth/sessions` принимает только `Authorization: Basic`,
без JSON-тела, и отвечает `201 Session`. Всё остальное, включая
`DELETE /api/v1/auth/sessions/current`, принимает только
`Authorization: Bearer <token>`.
- Basic на бизнес-ручке — 401 с вызовом Bearer: smoke шлёт верный Basic
на `GET /users/me` и ждёт 401.
- `X-User-Id` игнорируется: доступа не даёт и владельца сессии не
меняет. Smoke шлёт Bearer alice вместе с `X-User-Id` eve и ждёт alice.
- Сначала аутентификация, потом доступ: без токена — 401 даже на
чужой чат. Чужой и несуществующий чат дают одинаковый 404, 403 не
используется.
- В `User` нет пароля, его хэша и данных сессии.
- Logout — 204 без тела; тот же токен после него — 401.
## Чаты и сообщения
- Чат создаётся атомарно. `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` между страницами можно
менять.
- Изменённый курсор — 400, а не 500 и не страница (спек `pagination`,
«Изменённый курсор»). `decode_cursor` проверяет поля по отдельности
(change `strict-id-validation`):
- `v` — ровно целое 1 (`type(v) is int`: `True == 1`);
- `t` и `i` — строки до `strptime` и `UUID()`: `UUID()` на не-строке
роняет `AttributeError`, а не `ValueError`;
- `i` — в записи сервера, `str(UUID(i)) == i`.
- Незнакомые поля курсора игнорируются, и курсор не сравнивается с
обратной сборкой (`encode_cursor(...) == cursor`): иначе формат закрыт,
и даже совместимая правка (необязательное поле, порядок ключей,
`to_rfc3339`, общий с ответами) давала бы 400 курсорам реплики другой
версии во время `make rolling_update`. Тесты такое окно не ловят:
курсор в них выдаёт и проверяет один код.
- Формат курсора, который прежний код не прочтёт (переименованное поле,
другая запись времени), — новая `CURSOR_VERSION`. На время замены
реплик новая версия принимает и старую `v`: курсор, выданный старой
репликой, приходит на новую. Старую версию убирать отдельной правкой,
когда старых реплик не осталось.
- Семантику при конкурентных вставках и ограничения часов описать в
`REPORT.md` (например: `created_at` монотонен внутри чата).
- В Postgres порядок и курсор задаёт SQL: сравнение кортежей
`(created_at, id)` по индексу `(chat_id, created_at, id)`, без
`OFFSET` (`repo-layer.md`). `uuid` Postgres сравнивает побайтно, это
тот же порядок, что `UUID.int`.
## Сохранность (с лабы 2)
Пользователи, чаты, участники, сообщения и ещё действующие сессии
переживают рестарт API и всех хранилищ с сохранёнными volumes: тот же
токен после рестарта читает те же данные. TTL из-за рестарта не
продлевается. Проверка — `make test-persistence
ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook —
`docker.md`. Подтверждённое сообщение видно следующему чтению **через
любую реплику**: история не кэшируется, кэш карточки чата не отдаёт
устаревших данных (состав чата неизменен).
## Балансировка и повторная отправка (лаба 3)
Переход 2 → 3 (`COURSE.md`): `Idempotency-Key` обязателен для отправки
сообщения, ответы API содержат `X-Instance-Id`. Семантика —
`contracts/README.md`, раздел «Балансировка и повторная отправка».
Реализация — `api-layer.md` (заголовки), `service-layer.md`
(транзакция), `balancer.md` (стенд).
- `X-Instance-Id` — в каждом ответе, созданном API: успех, ошибки,
health, 404 неизвестного пути, 405, 500. Значение стабильно, пока жив
процесс, и одно на процесс. Ответ, который сгенерировал сам HAProxy
(502/503/504 при недоступных репликах), заголовка может не иметь —
контракт это допускает.
- `Idempotency-Key` — только у `POST /api/v1/chats/{chat_id}/messages`,
ASCII `^[A-Za-z0-9._:-]{1,128}$` на всю строку. Нет ключа или он
неверный — 400 `invalid_request`. Smoke: `POST` без ключа от
участника — 400. Другие `POST` ключ не требуют и не обрабатывают.
- Область уникальности — пользователь + метод + путь чата + ключ.
Ключ принимает одна ручка, поэтому область — `(user_id, chat_id,
key)`. Одинаковый ключ у разных пользователей или в разных чатах —
независимые сообщения.
- Повтор того же тела в течение 24 ч (`IDEMPOTENCY_TTL_SECONDS`, у нас
`[idempotency] ttl_seconds`) — **тот же 201 и то же `Message`**: тот
же `id`, `created_at` до микросекунды, тот же текст. Smoke сравнивает
JSON целиком (`replay == first`). «То же тело» — семантически: порядок
ключей JSON не важен, отсутствующий `attachment_ids` равен `[]` (с
лабы 4). Другое тело с тем же ключом — 409 `conflict`.
- Повтор заново проверяет сессию и доступ: отозванный токен — 401,
посторонний — 404, даже если ключ уже сохранён.
- Конкурентные повторы через разные реплики создают ровно одно
сообщение; все успешные ответы одинаковы. Транзиентная ошибка (5xx,
отказ БД) результатом не фиксируется: ключ и сообщение пишутся в
одной транзакции, откат убирает оба.
- Порядок кодов: ключ объявлен параметром ручки (`Header`), а FastAPI
проверяет параметры и тело после зависимостей (раздел «FastAPI»).
Значит, ожидаемый порядок — 401 (сессия) → 400 (ключ, тело) → 404
(не участник) → 409 (другое тело). Исключение то же, что везде:
битый JSON — 400 раньше 401. Порядок закрепить тестом в
`student-tests/`, а не считать доказанным.
- Прозрачных повторов других `POST` нет ни в API, ни в LB: создание
чата или регистрация при повторе создали бы второй объект
(`balancer.md`, повторы LB только на отказ соединения).
+97
View File
@@ -0,0 +1,97 @@
---
paths:
- "src/api/**"
- "src/main.py"
---
# Слой API (`src/api/`, `src/main.py`)
FastAPI, один процесс на реплику; реплик ≥2 за HAProxy (`balancer.md`).
Что обязан отдавать HTTP — `.claude/rules/api-contract.md`; здесь — как
устроен слой.
- В памяти процесса нет состояния, от которого зависит ответ: любой
запрос может прийти на любую реплику. Сессии, данные и ключи
идемпотентности — в Postgres; глобалы модулей — только клиенты
хранилищ и неизменяемые значения (`instance_id`, фиктивный хэш
пароля).
## Роутинг
| Что | Файл | Путь |
|---|---|---|
| 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. CPU-тяжёлую работу (KDF пароля)
явно выносят в поток (`auth.md`).
- Ручка: зависимости → вызов сервиса именованными аргументами →
DTO в модель ответа (`UserOut.model_validate(dto)`, у модели
`from_attributes=True`). Логики, импортов repo и хранилища здесь нет.
- Текущий пользователь — `Depends(get_current_user)` из
`dependencies.py`, по Bearer-токену (`auth.md`). Сервис —
зависимость-фабрика (`Depends(get_chat_service)`), которая собирает
его из `AsyncSession`. Сессию БД открывает `get_db_session` из
глобального `session_factory` (`src/infra/db/session.py`): одна на
запрос, закрывается после ответа, вся работа с БД ограничена сроком,
отказ БД — 503 (`infra.md`). Commit делает сервис (`service-layer.md`).
- Ошибки — доменные исключения из сервиса. `HTTPException` не бросать.
Статус, `code` и заголовки ответа (`WWW-Authenticate` у 401)
назначает одна таблица в `errors.py`.
- Модели запросов и ответов — `src/api/schemas/<domain>.py`, имена по
схемам контракта (`CreateUser`, `User`, `ChatPage`...). В сервис модели
API не передавать: разбирать в именованные аргументы или
`Create<Entity>DTO`.
- POST создания — `status_code=201` в декораторе; `response_model` —
модель контракта.
- `Idempotency-Key` (лаба 3) — параметр ручки `POST` сообщения:
`Annotated[str, Header(alias="Idempotency-Key", pattern=...,
max_length=128)]`, шаблон — константа в `src/utils/constants.py`. Так
он есть в `/openapi.json`, а отсутствие и неверный формат дают 400
через общий обработчик валидации. В сервис ключ уходит именованным
аргументом вместе с телом; повтор с тем же ключом отвечает тем же 201,
что и первый вызов (`api-contract.md`).
## 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`. Структуру роутеров ради логов не менять.
- `X-Instance-Id` (лаба 3) ставит тот же middleware, что и
`X-Request-Id`, на каждый ответ, включая health, 404 и 405. Значение
— `settings.app.instance_id` (по умолчанию hostname процесса, в
compose — короткий ID контейнера), вычисляется один раз при старте.
Ответ 500 собирает `ServerErrorMiddleware` снаружи пользовательских
middleware, поэтому обработчик `Exception` в `errors.py` ставит и этот
заголовок сам, как `X-Request-Id`.
+118
View File
@@ -0,0 +1,118 @@
---
paths:
- "src/**/session.py"
- "src/core/services/user.py"
- "src/api/dependencies.py"
- "src/api/errors.py"
- "student-tests/api_client.py"
- "student-tests/test_identification.py"
---
# Аутентификация и сессии (с лабы 2)
Что обязан отдавать HTTP — `contracts/README.md`, «Идентификация и
сессии», и `api-contract.md`; здесь — как это реализовать. Домен
называется `session` во всех слоях: `routers/v1/session.py` с префиксом
`/auth/sessions`, `services/session.py`, `repos/session.py`.
## Пароль
- KDF — Argon2id (`argon2-cffi`). Контракт разрешает Argon2id, scrypt и
bcrypt, но bcrypt режет пароль на 72 байтах, а пароль до 128 code
points в UTF-8 занимает до 512 байт. Lab7 требует именно Argon2id, и
выбор сейчас избавляет от перехэширования. SHA-256 и plaintext
запрещены. Параметры KDF — в `REPORT.md`.
- Хэширование и проверка занимают десятки миллисекунд CPU. В event
loop их не вызывать: `await anyio.to_thread.run_sync(...)`, иначе
один вход останавливает все запросы процесса.
- Всё это — `src/infra/password.py`: профиль
`RFC_9106_LOW_MEMORY` (t=3, m=64 MiB, p=4) назван явно, а не взят
умолчанием библиотеки; свой `CapacityLimiter` на
`[auth] kdf_concurrency` (4), а не общий пул anyio на 40 потоков:
40 × 64 MiB = 2,5 GiB (design change `session-auth`, решение 3).
- Регистрация хэширует пароль до обращения к БД. Вход читает хэш и
закрывает транзакцию (`commit()`) до проверки пароля: соединение пула
не ждёт KDF и очередь лимита; сессия вставляется второй транзакцией.
- Пароль хэшируется целиком как UTF-8, без обрезки и нормализации.
Хэш не выходит за пределы repo и сервиса входа: в `UserFullDTO` и в
ответе API его нет (`dto.md`).
- Неизвестный username и неверный пароль — одно исключение и одинаковый
401. Для неизвестного username пароль всё равно проверяется против
фиктивного хэша, чтобы время ответа не выдавало, есть ли пользователь.
Фиктивный хэш считает lifespan при старте (`prepare_dummy_hash`): при
ленивом расчёте первый такой вход шёл бы вдвое дольше.
## Basic на входе
- Разбор свой, `HTTPBasic` FastAPI не годится (`api-contract.md`,
«FastAPI»). Схему `basicAuth` объявляет
`HTTPBase(scheme="basic", scheme_name="basicAuth", auto_error=False)`
(импорт из `fastapi.security.http`: из `fastapi.security` его нет): он
отдаёт схему и credentials как есть. Дальше схема `Basic` без учёта
регистра → base64 строго (`b64decode(..., validate=True)`) → UTF-8 →
`partition(":")` по **первому** двоеточию: в username двоеточия не
бывает, в пароле оно допустимо. Любой сбой разбора — тот же 401, что и
неверный пароль.
- Username не по шаблону и пароль вне 12–128 code points отсекаются при
разборе: тот же 401 без запроса к БД и KDF. Формат публичный, о
пользователях такой отказ ничего не говорит.
- JSON-тело на входе не читается.
- 401 входа — с `WWW-Authenticate: Basic realm="messenger",
charset="UTF-8"`.
## Токен и сессия
- Токен — `secrets.token_urlsafe(32)`: 256 бит энтропии, 43 символа
(контракт требует не меньше 32). Не JWT, не UUID, ничего не кодирует.
- Хранится не токен, а его SHA-256, поиск идёт по нему. Быстрого хэша
здесь достаточно: у токена 256 бит энтропии, перебирать нечего. Пароль
же выбирает человек, поэтому ему нужен медленный KDF — это вопрос
защиты.
- `expires_at = utcnow() + TTL` фиксируется при создании и хранится.
Ни использование, ни рестарт срок не продлевают. На каждом запросе
проверяется: сессия есть, не отозвана, `expires_at` в будущем.
- TTL — `[auth] session_ttl_seconds` в `config.toml`; контрактное имя
`SESSION_TTL_SECONDS` сопоставлено с ним в `REPORT.md`, мостом не
заводится (`settings.md`). Разовая подмена —
`AUTH__SESSION_TTL_SECONDS` в окружении. По умолчанию 3600, в обычном
smoke не меньше 300, в тесте истечения — 2.
- `DELETE /auth/sessions/current` отзывает только текущую сессию, дальше
этот токен получает 401.
- Сессии — в PostgreSQL, без кэша: отзыв мгновенный (design change
`session-auth`). Таблица `sessions`: id, `user_id` (внешний ключ),
SHA-256 токена (`bytea`, уникальный индекс, `CHECK` на 32 байта),
`created_at` и `expires_at` (`timestamptz`). Отзыв — удаление строки.
Проверка токена — один `SELECT` по `token_hash` с `JOIN` на
пользователя; `now` для `expires_at > now` передаёт сервис, срок
сравнивается по часам приложения.
- Valkey сессии не хранит: он — кэш карточек чатов (спек
`chat-cache`, change `membership-cache`). Любое хранилище сессий
обязано пережить рестарт, соблюдать срок и отзыв, при недоступности
отвечать 503 и никогда не пропускать запрос как анонимный или
доверенный.
## Текущий пользователь
- `get_current_session` (`src/api/dependencies.py`):
`HTTPBearer(scheme_name="bearerAuth", bearerFormat="opaque session
token", auto_error=False)` — как в контракте → токен или `None` →
`SessionService.authenticate` → `CurrentSessionDTO` (id сессии и
`UserFullDTO`). Иначе `Unauthenticated` → 401 с `WWW-Authenticate:
Bearer realm="messenger"`. `get_current_user` берёт пользователя из
неё, logout — id сессии.
- `X-User-Id` не читается нигде. Basic на бизнес-ручке для `HTTPBearer`
— чужая схема: он отдаёт `None`, и получается тот же 401 с вызовом
Bearer.
- Заголовок `WWW-Authenticate` ставит таблица `errors.py` по типу
исключения. Исключений два, для входа и для Bearer, а не одно с
параметром.
- `current_user_id` (contextvar логгера) ставится только после успешной
проверки.
## Логи
Никогда не логируются пароль, токен, его хэш и заголовок
`Authorization`. Создание и отзыв сессии — `info` с `user_id` и id
сессии, неудачный вход — `warning` без username и пароля
(`logging.md`). Параметры SQL в журнал не попадают: engine создан с
`hide_parameters=True` (`infra.md`).
+315
View File
@@ -0,0 +1,315 @@
---
paths:
- "docker-compose.yml"
- "infra/haproxy/**"
- "scripts/stop-one.sh"
- "scripts/rolling-update.sh"
---
# Реплики за балансировщиком (с лабы 3)
Задание — `README.md` лабы 3, роли — `contracts/infrastructure.json`,
семантика `X-Instance-Id` и `Idempotency-Key` — `api-contract.md`.
Общие правила compose, пинов и volumes — `docker.md`; здесь то, что
добавляет лаба 3. Почему HAProxy — `REPORT.md`, «Балансировщик и
реплики» (таблица сравнения), и design change `replicas-lb`, решение 1;
числа и их обоснование — тот же design (архив
`openspec/changes/archive/`), спек `load-balancing`.
```
клиент → 127.0.0.1:APP_OUT_PORT → haproxy → api × API_REPLICAS → postgres (данные, сессии, ключи)
→ valkey (кэш карточек)
migrate (один раз на up) ──────→ postgres
```
## Сервисы compose
- **`haproxy`** — единственный сервис с портом наружу:
`127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}` (внутри LB
слушает тот же `APP__PORT`, что реплики). Образ закреплён тегом с
патч-версией и digest индекса (`docker.md`), сейчас 3.4 LTS. Конфиг —
`infra/haproxy/haproxy.cfg`, монтируется read-only длинной записью с
`create_host_path: false`. Окружение — только `API_PORT`, секретов LB
не получает. `depends_on: api` (`service_started`): `make stop` гасит
LB раньше реплик. Healthcheck — `bash` с `/dev/tcp` на
`/lb/ready` (curl в образе нет): `healthy` значит «есть готовая
реплика». Лимиты CPU/RAM.
- **`api`** — `deploy.replicas: ${API_REPLICAS:-2}`, без `ports`,
без `container_name`: оба мешают масштабированию одного сервиса
(рубрика «4»). Разовая подмена — `make replicas API_REPLICAS=N`.
Лимиты CPU/RAM у каждой реплики, `stop_grace_period: 10s`,
`restart: unless-stopped`.
- **`migrate`** — как в лабе 2: один раз до реплик, реплики ждут
`service_completed_successfully` (`migrations.md`).
- Лимиты CPU/RAM у **всех** сервисов, включая postgres, valkey и
migrate (`deploy.resources.limits`). Сумма — в `REPORT.md`, рядом с
расчётом соединений Postgres (`infra.md`).
## HAProxy
- Имена прокси разные: `frontend entry`, `backend api`, `frontend
monitor`. С HAProxy 3.3 frontend и backend с одним именем — ошибка
конфигурации. Проверка конфига — `haproxy -c` в закреплённом образе
с `API_PORT`.
- Реплики находятся через DNS Docker, а не списком адресов:
`resolvers` на `127.0.0.11:53` и `server-template api- <N> api:<порт>
check resolvers docker init-addr none`. Новая и пропавшая реплика
видны без перезагрузки LB (`hold` 1 с). `<N>` — запас слотов не
меньше максимального числа реплик в сериях трека 1 (сейчас 8). Слоты
HAProxy (`api-1`, `api-2`) не совпадают с именами контейнеров
compose: слот получает адрес из DNS.
- `init-state down` у слотов: адрес из DNS появляется при старте
контейнера, раньше, чем uvicorn слушает порт. Без него слот сразу
`UP`, и запросы уходят на неготовую реплику; с ним — только после
`rise` проверок `/health/ready` (старт LB, `make replicas`,
поочерёдная замена).
- Проверка готовности — активная: `option httpchk GET /health/ready`,
`http-check expect status 200`, `inter`/`fall`/`rise` и
`timeout check` явно. `/health/live` для LB не годится: живой
процесс без Postgres не обслуживает запросы.
- `balance roundrobin`, без `cookie` и `stick-table`: sticky session
запрещён (README, п. 3), а разные `X-Instance-Id` у запросов одной
сессии — проверка уровня 3.
- Повтор запроса в LB — только `retry-on conn-failure` с `retries` и
`option redispatch 1` (каждый повтор — на другую реплику). Запрос до
реплики не дошёл, поэтому повтор безопасен для любого метода.
`response-timeout`, `empty-response`, `5xx` не повторяются: `POST
/chats` и `POST /users` не идемпотентны (`api-contract.md`). `POST`
сообщения клиент повторяет сам, с тем же ключом.
- `X-Request-Id` и `X-Instance-Id` ставит API, LB их не переписывает.
Ответы, которые сгенерировал сам HAProxy (502/503/504), отдаются в
формате ошибки контракта через `http-error … lf-string` с `code`
`unavailable` (в перечислении кодов контракта нет отдельных для 502 и
504); `request_id` — `%[unique-id]`, он же в заголовке
`X-Request-Id`. `X-Instance-Id` у них нет — контракт это допускает.
- Статистика — страница `/stats` и `/stats;csv` (`stats show-legends`:
адрес слота) во `frontend monitor` на `:8404`, там же `monitor-uri
/lb/ready` (503, если готовых реплик нет). Только внутри сети
compose, наружу не публикуется; оператору — `make lb_stats` (CSV
читается изнутри контейнера LB).
- Журнал — `log stdout`, `option httplog` + `option dontlog-normal`:
успешные запросы не пишутся, ошибки, повторы (`+N` в поле retries),
перенаправления и смена состояния реплик — пишутся. `nbthread` равен
лимиту CPU контейнера LB.
## Цепочка таймаутов
Числа живут в конфигах и в таблице `REPORT.md`, обоснование каждого
звена — design change `graceful-failover`, решение 1. Правило —
соотношения между ними:
- худшее время обнаружения отказа ≤ 10 с (рубрика «3»: «не позднее
10 секунд»). HAProxy начинает следующую проверку через интервал после
конца предыдущей, а после первой неудачи — через `fastinter`. Поэтому
для зависшей реплики (соединение есть, ответа нет) худшее — `inter +
timeout check + (fall − 1) × (fastinter + timeout check)`: при 1 с /
2,5 с / 0,5 с / `fall 2` — 6,5 с (было 8 с без `fastinter` и с 3 с;
замер `docker pause` change `replicas-lb` — 7,3–7,7 с). Пропавший
адрес (`stop` после выхода, `kill`) проверка ждёт не дольше таймаута
соединения проверки min(`timeout connect`, `inter`) = 0,5 с: худшее
2,5 с, а DNS уводит слот в обслуживание за 1–2 с. Замер по режимам —
профиль `failover` (`bench.md`), в `REPORT.md` — формула и замер;
- `timeout connect` × (`retries` + 1) < 2 с: таймаут клиента в
`tests/resilience.py` — 2 с, и повтор на живую реплику должен успеть
раньше. Поэтому `timeout connect` 500 мс, а не 1 с, и `redispatch 1`;
- `timeout server` > `[database] request_timeout_seconds` + запас на
KDF входа, иначе LB рвал бы ответ, который API ещё отдаст;
- таймаут проверки внутри `/health/ready` (2 с) < `timeout check`
HAProxy (2,5 с, `infra.md`): медленный PostgreSQL даёт 503 от реплики,
а не таймаут проверки. Уменьшать таймаут готовности ради быстрого
обнаружения нельзя: проверка берёт соединение из общего пула, и заминка
PostgreSQL вывела бы из LB все реплики разом;
- простаивающее соединение LB → реплика закрывает LB, а не реплика.
`http-reuse never`: соединение с репликой не уходит в общий пул и
живёт, пока жив сеанс клиента, а простаивающий сеанс LB закрывает по
`timeout http-keep-alive` (10 с). `[app] keep_alive_seconds` (60 с,
`timeout_keep_alive` uvicorn) больше. Иначе LB может отправить запрос
в соединение, которое реплика в этот момент закрывает, и клиент
получит 502 (`empty-response` LB не повторяет). С пулом (`http-reuse
safe`, по умолчанию) LB держал последнее простаивающее соединение,
пока его не закрывала реплика. Проверка — `driver.py idle-conns`;
- `[database] idle_in_transaction_timeout_ms` (10 с) >
`request_timeout_seconds` (6 с): PostgreSQL прерывает только
транзакцию замороженного процесса и снимает её блокировки, в том числе
ключа идемпотентности (`infra.md`). Проверка — `driver.py hang-key`;
- `[app] graceful_shutdown_seconds` < `stop_grace_period` (8 < 10,
`run-modes.md`).
## `scripts/stop-one.sh`
Hook для `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
(`tests/README.md`), по образцу `scripts/stop-one.example.sh`.
- `#!/bin/sh`, `set -eu`, исполняемый бит в git. Возврат 0 не позже
чем через 10 с: `docker stop --timeout 9` (uvicorn сам завершается
за ≤ 8 с). Остановленная реплика остаётся остановленной,
восстановление — отдельной командой `make replicas` (те же
контейнеры, те же ID), её печатает `REPORT.md`.
- `TARGET_INSTANCE_ID` — `X-Instance-Id` реплики, то есть короткий ID
контейнера: только hex, 12–64 символа. Скрипт ищет его префиксом
среди работающих реплик сервиса `api` **этого** проекта (`docker
compose ps -q api`). Иначе — отказ с ненулевым кодом: Postgres,
Valkey, LB и чужие контейнеры он не трогает никогда. Volumes не
удаляет.
- Режим — `STOP_MODE=stop` (по умолчанию, `docker stop`: SIGTERM и
graceful) или `kill` (`docker kill`: отказ процесса без graceful).
`restart: unless-stopped` не поднимает реплику ни после `stop`, ни
после `kill` (проверено на Docker 29.8: `exited`, `RestartCount` 0
через 15 с), поэтому `docker stop -t 0` вместо `kill` не нужен.
- `STOP_ONE_LOG=<файл>` — необязательная строка «время,
`TARGET_INSTANCE_ID`, полный ID контейнера, режим»: тест скрывает
вывод hook, но передаёт ему своё окружение. Так evidence показывает,
какой ID выбрал тест и какой контейнер остановлен.
- Секретов и окружения не печатает: вывод hook тест скрывает, но он
остаётся в терминале при ручном запуске.
- Доказательство на защите и в `evidence/failover/` — какой контейнер
остановлен: `docker compose ps` до и после, ID совпадает с
`TARGET_INSTANCE_ID` (строка `STOP_ONE_LOG`). Одного заголовка мало
(README, «Сценарий защиты», п. 3). Повторить для каждой реплики,
восстанавливая предыдущую (`make replicas`). Тест останавливает
реплику, ответившую на его первую отправку; при round-robin по двум
репликам после `make replicas` это снова та же, поэтому перед прогоном
для другой очередь сдвигают одним запросом через LB.
- Оборванный ответ при `kill` (запрос уже на реплике, LB его не
повторяет) — `driver.py --port 8080 kill-inflight` скилла
`run-mtusi-messenger`: входы по Basic в полёте и kill реплики через
этот hook.
- Отказ каждой реплики под постоянной нагрузкой (рубрика «4»: RPS,
ошибки, время восстановления) — не этот hook, а профиль `failover`
стенда `bench/` (`make bench_failover`, `bench.md`): свой проект
compose, `docker stop` / `kill` / `pause` реплики и возврат, шкала по
секундам в `evidence/failover/<метка>/`.
## Свои цели Makefile
- `make replicas` — `up -d --no-deps --no-recreate --wait --scale
api=$(API_REPLICAS) api`: запускает остановленные реплики с теми же ID
и доводит их число до `API_REPLICAS` (разово — аргументом make).
- `make instances` — `driver.py instances` скилла `run-mtusi-messenger`:
вход одним синтетическим пользователем и серия `GET /users/me` с одним
токеном, `X-Instance-Id` каждого ответа (шаг 1 сценария защиты).
- `make lb_stats` — занятые слоты HAProxy: адрес, состояние проверки
(в том числе `DRAIN` и `MAINT` при замене), запросы, ошибки
соединения, повторы, перенаправления.
- `make rolling_update [COMMIT=…] [MIGRATE=0]` — поочерёдная замена
реплик, раздел ниже.
## Поочерёдная замена: `scripts/rolling-update.sh`
Compose не умеет rolling update сам (это `update_config` Swarm). Цель —
`make rolling_update`, решения — design change `rolling-update`
(решения 1–6), спек `load-balancing`. Порядок:
0. Предусловия, ничего не меняют (код 2):
- работает ровно `API_REPLICAS` реплик;
- остановленных нет: `up --scale` запустил бы остановленную старую
вместо новой;
- все `UP` в LB;
- `API_REPLICAS` + 1 помещается в слоты;
- runtime API LB отвечает;
- нет слотов с ручным состоянием (`drain`, `maint`), которое оставила
прерванная замена: флаги 1 и 8 в `srv_admin_state` (`show servers
state api`). `show stat` и `make lb_stats` их не показывают: у слота
без адреса и ручное, и DNS-обслуживание — `MAINT (resolution)`.
Иначе — `make replicas`; слоты с ручным состоянием — `set server
api/<слот> state ready` (команду печатает сам скрипт).
1. Сборка нового образа: `docker compose build api` или
`COMMIT=<commit>` — `git archive <commit> | docker build -t <тег> -`,
рабочее дерево не трогается.
2. Миграции один раз: `docker compose up --no-deps --no-build
--force-recreate --abort-on-container-exit --exit-code-from migrate
migrate` на **новом** образе — новые ревизии лежат в нём, поэтому
сборка раньше миграций. Пересоздаётся контейнер самого сервиса
`migrate`, а не одноразовый `run --rm`: иначе в стенде остался бы
`migrate` прежнего образа, и `restart.sh` (`start api` запускает его
как зависимость) гонял бы старые миграции на новой схеме — «Can't
locate revision», exit 255, реплики не стартуют (найдено регрессией
`make test-persistence` в apply). Миграция только расширяет схему
(`migrations.md`), старые реплики работают на ней. Ошибка — код 1 до
замены. `MIGRATE=0` — откат на прежний образ: его миграции не знают
новой ревизии, контейнер `migrate` остаётся на новом образе.
3. `up -d --no-deps --no-recreate --no-build --scale api=N+1 api`:
новая реплика (ID, которого не было), старые не тронуты.
4. Новая `healthy` (на `bench/` без healthcheck — `running`) **и** `UP`
в статистике LB по её адресу: слот начинает `DOWN` (`init-state
down`) и включается через ≤ 1,5 с проверок. Срок
`ROLLOUT_READY_TIMEOUT` (60 с).
5. Вывод старой из LB через runtime API (ниже): `drain` → запросов в
полёте (`scur`) 0, не дольше `ROLLOUT_DRAIN_TIMEOUT` 12 с (> `timeout
server`) → `maint` → `docker stop --timeout 10` (в строке скрипта —
время и код выхода: 0 — graceful, 137 — SIGKILL по сроку) → `docker
rm` → адрес ушёл из слота (DNS, ≤ 10 с) → `ready`.
6. Шаги 3–5 для каждой старой. В конце — N реплик на новом образе, все
`UP`, ни одной прежней.
**Имена контейнеров после замены.** Compose нумерует новые контейнеры
сервиса по возрастанию, поэтому после замен реплики называются `api-N`
с растущим номером (`mtusi-lab3-api-3`, `-4`, …). Штатные цели
(`make replicas`, `make test-failover`, `restart.sh`, `stop-one.sh`) с
ними работают: они обращаются к сервису `api` (`docker compose ps -q
api`, `stop` / `start api`), а не к имени контейнера. `make down` + `make run_docker` снова дают `api-1`, `api-2`.
**Runtime API LB** — `stats socket ipv4@127.0.0.1:9999 level admin` в
`global`: только loopback контейнера LB, из сети compose и с хоста не
достать. Команды — `docker compose exec -T haproxy bash -c 'exec
3<>/dev/tcp/127.0.0.1/9999 …'` (socat и curl в образе нет), слот — по
адресу реплики в `show stat`. `stats admin` на `:8404` не годится: порт
открыт всей сети compose.
**Ручное состояние — свойство слота, а не реплики.** `drain` или
`maint`, оставленные на слоте, достанутся следующей реплике, которой DNS
отдаст этот слот: она не получит ни одного запроса. IPAM Docker
переиспользует адрес удалённой реплики сразу (проверено: новая реплика
получила адрес и слот только что удалённой). Поэтому `ready` — после
ухода адреса из слота и до следующего `--scale`.
**Дренаж убирает 502 гонки keep-alive.** Слот выведен, LB не выбирает
его для новых запросов, и простаивающие соединения, которые uvicorn
закрывает по SIGTERM, ему уже не нужны (спек `graceful-shutdown`,
«Плановая остановка реплики без ошибок»). `stop-one.sh` и профиль
`failover` дренаж не делают: они имитируют отказ.
**Сбой на середине** (`trap` на `EXIT`, `INT`, `TERM`): новая не стала
`UP` за срок — её убирает `remove_new` (design change
`fix-known-issues`, решение 7):
- слот есть (DNS уже отдал) → `maint` → `docker stop --timeout 10` →
`docker rm -f` → адрес ушёл → `ready`; строка `removed new <id> (slot
api-N: stop Ns, exit N)`. Стартующая реплика выходит сразу по раннему
обработчику SIGTERM (`run-modes.md`), работающая — дорабатывает
запросы, которые LB успел отправить на слот до `maint`;
- слота нет → сразу `docker rm -f`, строка `removed new <id> (no slot:
docker rm -f)`: запросов на ней не было, а это ещё и страховка на окно
запуска интерпретатора, где SIGTERM некому принять.
Новая уже `UP` — вывод текущей старой доводится до конца.
Прерывание внутри `up --scale`, когда ID новой ещё не известен: уборка
находит её сама — контейнер, которого не было до команды. ID новой
прежнего шага сбрасывается до перехода в это состояние: иначе уборка
удалила бы уже рабочую реплику (найдено в verify, `evidence/rollout/
script-failures.md`). В любом исходе — `API_REPLICAS` готовых реплик и
слоты без ручного состояния, смешанные версии допустимы, повторный
запуск доводит замену. Автоматического отката нет; откат — `make
rolling_update COMMIT=<прежний> MIGRATE=0`.
**После отката тег сервиса указывает на прежний образ**, а схема новее
его миграций. `docker compose up` без сборки пересоздал бы `migrate` на
этом образе, тот упал бы на «Can't locate revision», и `restart.sh`
перестал бы поднимать реплики (как в регрессии apply). Вперёд —
снова `make rolling_update` или `make run_docker` (сборка рабочего
дерева, все реплики разом).
Прогон — под нагрузкой с постоянной интенсивностью: профиль `rollout`
стенда `bench/` (`make bench_rollout`, `bench.md`) вызывает этот же
скрипт со своим проектом (`COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`,
`COMPOSE_ENV_FILES`). Ошибки и их коды по секундам — в
`evidence/rollout/<метка>/`. Сторонние плагины (docker rollout) не
используются: это ещё одна незакреплённая зависимость.
## Что стенд не переживает
Один Docker-host, один HAProxy, одна Postgres, один Valkey. Выдерживается
отказ процесса API (любой одной реплики, при ≥2 живых). Не выдерживается
отказ хоста, LB и Postgres. Отказ Valkey — деградация до Postgres, не
отказ. Это пишется в `REPORT.md` прямо (`COURSE.md`, «Воспроизводимость
и честные измерения»).
+514
View File
@@ -0,0 +1,514 @@
---
paths:
- "bench/**"
---
# Нагрузочный стенд (`bench/`)
Стенд перенесён из лабы 1 (трек 1 «5», нагрузка на in-memory API) и на
лабе 2 переведён на PostgreSQL: матрица размеров истории и уровней
конкуренции для чтения и записи, метрики, планы запроса истории и сырые
данные в `evidence/bench/<метка>/`. Что стенд обязан делать — спек
`load-benchmark`, почему так — archived changes `load-bench-harness`
(стенд), `perf-bottleneck-fix` (сравнение меток) и `bench-postgres`
(стенд на PostgreSQL, план запроса), `track2-query-plans` (чаты
неравномерных размеров, варианты индекса и запроса, стоимость записи) в
`openspec/changes/archive/`.
Результаты и выводы — `REPORT.md`, раздел «Эксперименты и отказы».
На лабе 2 стенд нужен для двух вещей: план запроса истории
`EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях (уровень 4) и
сравнение индексов и запросов со стоимостью записи на чатах разного
размера, а также backup и восстановление со сверкой для трека «5» №2
(`README.md`). Варианты сравниваются внутри
одной метки, на одних данных; «до» и «после» через `make bench_ab` нужны,
только когда меняется код приложения. Метки лабы 1 сюда не
переносились: другое хранилище — другая методика, сравнивать их с
лабой 2 нельзя.
**Лаба 3, трек «5» №1 «Цена масштабирования»** (design change
`scaling-bench` в архиве; результаты — `REPORT.md`, «Цена
масштабирования»). Стенд нужен для трёх вещей:
- серия A — фиксированный суммарный бюджет CPU/RAM на 1/2/4 реплики;
- серия B — рост числа реплик до точки насыщения Postgres, LB или
пула;
- профили уровня 4: `failover` (постоянная интенсивность, поочерёдная
остановка реплик, посекундные RPS и ошибки) и `rollout` (та же
нагрузка во время `scripts/rolling-update.sh`).
Стенд с N репликами и профиль `failover` — change `graceful-failover`;
нагрузка, метрики и графики трека 1 — change `scaling-bench` (раздел
«Серии трека 1» ниже). Это смена методики: метки лабы 2 с метками лабы
3 не сравниваются, базовый замер снимается заново. Профили лабы 2
(`full`, `restore*`) продолжают работать и после перехода на N реплик.
Стенд с LB (design change `graceful-failover`, решение 6):
- override `bench/bench.compose.yml`: у `api` нет `container_name`,
`deploy.replicas: ${BENCH_API_REPLICAS}`, лимиты `BENCH_APP_*` — на
каждую реплику; у `haproxy` — `container_name: mtusi-bench-haproxy`
(он один), лимиты `BENCH_LB_*`, порт сброшен, конфиг — тот же
`infra/haproxy/haproxy.cfg`. Лимиты всех — в форме
`deploy.resources.limits` (`cpus` / `mem_limit` рядом с ними compose не
принимает), `memswap_limit` — на уровне сервиса;
- k6 ходит на `http://haproxy:8080` (имя сервиса в сети `mtusi-bench`,
`lib.js`), не к реплике напрямую — и при N = 1: серии трека 1
сравнивают 1, 2 и 4 реплики на одном пути запроса;
- `run.py` находит реплики через `docker compose ps api`. Стенд готов,
когда LB видит `UP` все N реплик по их адресам (статистика LB изнутри
контейнера LB). CPU, память и RSS приложения в метриках — сумма по
репликам (`VmHWM` — максимум), при N = 1 — числа её процесса;
- healthcheck образа у реплик выключен, но реплику раз в секунду
проверяет LB (`SELECT 1` в квоте API). Вместе с LB в пути запроса это
смена методики относительно лабы 2: метки лабы 3 до этого change (их в
git нет) и метки лабы 2 с новыми не сравниваются. В паспорте метки со
стендом с LB есть `limits.haproxy` и `limits.api_replicas`;
`make bench_compare` отказывает, если `limits.api_replicas` есть только
в одной из меток.
Стенд — свой проект compose `mtusi-bench`: тот же `docker-compose.yml`
с override `bench/bench.compose.yml` (по образцу `make failure_checks`),
подстановки — `bench/bench.env`, а не `.env` рабочего стенда. Пароли
хранилищ `run.py` генерирует на прогон и никуда не пишет. Каждый размер —
свежий стенд: `down -v`, Postgres и Valkey, миграции, API.
Инструменты `bench/`:
| Файл | Команда | Что делает |
|---|---|---|
| `run.py`, `k6/`, `bench.compose.yml`, `bench.env` | `make bench`, `make bench_quick` | стенд: меряет пропускную способность, задержки, CPU API и Postgres, память, снимает планы запроса истории |
| `run.py` (профили `restore`, `restore_quick`), `k6/after_backup.js`, `k6/restore_check.js` | `make bench_restore`, `make bench_restore_quick` | тот же стенд без матрицы прогонов: backup под записью, восстановление в новое хранилище, сверка, RTO и потеря, кэш до и после `FLUSHALL` |
| `run.py` (профили `failover`, `failover_quick`), `failover.py`, `resources.py`, `sampler.sh` (режим `scan`), `k6/failover.js`, `k6/retry.js` | `make bench_failover`, `make bench_failover_quick` | две реплики с лимитами рабочего стенда, постоянная интенсивность записи с ключом и чтения, каждая реплика в каждом режиме (`stop`, `kill`, `pause`) с возвратом: посекундная шкала, время обнаружения и восстановления, сверка записей, CPU и память каждого компонента по окнам фазы; результаты — `evidence/failover/<метка>/` |
| `run.py` (профили `rollout`, `rollout_quick`), `rollout.py`, `resources.py`, `sampler.sh` (режим `scan`), `k6/failover.js`, `k6/retry.js`, `scripts/rolling-update.sh` | `make bench_rollout`, `make bench_rollout_quick` | две реплики с лимитами рабочего стенда на образе прежнего commit, та же постоянная нагрузка, посреди неё — поочерёдная замена на образ текущего checkout: посекундная шкала с ответами старых и новых реплик, шаги по каждой реплике, контейнеры, образы и ревизия схемы до и после, сверка записей, CPU и память каждого компонента по окнам замены; результаты — `evidence/rollout/<метка>/` |
| `run.py` (профили `scaling_*`), `scaling.py`, `sampler.sh`, `k6/mixed.js` | `make bench_scaling SERIES=a\|b\|pool\|ab\|db\|db4`, `make bench_scaling_quick`, `SERIES=db_quick` | серии трека 1: конфигурации реплик и лимитов, на каждую ячейку — свежий стенд, открытая модель, фиксированные уровни и поиск R* по SLO, посекундный сэмплер контейнеров, ВМ, LB и PostgreSQL; результаты — `evidence/bench/<метка>/` |
| `plots.py` | `make bench_plots LABELS="…"` | графики SVG и сводка серий (R* от числа реплик, p95 от интенсивности, CPU по компонентам, точка насыщения) — `evidence/plots/<PLOTS>/` |
| `compare.py` | `make bench_compare` | дельта двух меток стенда (ячейки матрицы или общие конфигурации серий), эффект или шум |
| `ab.py` | `make bench_ab [SERIES=…]` | стенд «до» и «после» одного изменения подряд, в одной сессии хоста; с `SERIES` — серия трека 1 вместо матрицы |
## Что не меняется между метками
Метки сравнимы, только если различается код приложения и больше ничего.
Не меняются:
- **лимиты контейнеров без swap:** API — 1 CPU / 2 ГБ, PostgreSQL —
4 CPU / 3 ГБ, Valkey — 2 CPU / 512 МБ (поля `Profile`, в compose —
переменными `BENCH_*`). Healthcheck API выключен, `restart: "no"`,
порты на хост не публикуются. Сумма лимитов памяти должна
помещаться в VM docker с запасом 1,5 ГиБ, иначе — предупреждение о
хосте;
- **хранилища:** образы PostgreSQL и Valkey — те же пины, что у рабочего
стенда (из `docker-compose.yml`). Valkey — тот же `valkey.conf`.
PostgreSQL — настройки образа плюс `shared_preload_libraries =
auto_explain`, выключенный вне этапа плана. Настройки, от которых
зависят план и запись, пишутся в паспорт (`stand.postgres.settings`);
- **приложение:** настройки по умолчанию из `settings.py` и окружение
из override (`AUTH__SESSION_TTL_SECONDS` из `Profile`), без `.env` и
`config.toml`. Окружение без паролей — в паспорте (`stand.app_env`);
- **данные:** кроме читаемого чата из N сообщений и чата записи —
фоновые чаты уровнями из `Profile.background` (в `full` 10 × 5 000,
100 × 400, 1 000 × 10). Сообщения всех чатов отправляются вперемешку
по детерминированному расписанию (`fill_schedule`), распределение по
чатам проверяется после наполнения;
- **обслуживание после наполнения:** `VACUUM (ANALYZE)` и `CHECKPOINT`
до сбора курсоров и прогонов. Затем этап плана (страницы читаемого
чата и первого чата каждого уровня, варианты страницы сравнения),
затем прогоны с прогревом перед каждым, затем пробы стоимости записи;
- **варианты и пробы:** варианты индекса истории — `Profile.index_variants`,
проба записи — `write_probe_rows` строк, `write_probe_repeats`
повторов со сдвигом порядка конфигураций;
- **восстановление** (профили `restore*`): `pg_dump -Fc` во время
записи `restore_write_load` сообщений `restore_write_vus` клиентами,
`pg_restore -j restore_jobs` в контейнер того же образа и с лимитами
Postgres стенда на новом volume, `ANALYZE`, переключение API через
`POSTGRES_HOST`. Файл backup живёт только в `.work/`: в нём хэши
паролей и токенов;
- **генератор:** `grafana/k6` той же версии и digest, в той же
docker-сети; в профилях лабы 2, `failover` и `rollout` без лимита, в
сериях трека 1 — 2 CPU / 1 ГиБ без swap (`generator_cpus`,
`generator_memory`), сэмплер — 0,25 CPU / 128 МиБ (`sampler_cpus`,
`sampler_memory`). Их лимиты — часть методики серий. У профилей
`failover` и `rollout` (с change `profile-resources`) — тот же сэмплер
0,25 CPU / 128 МиБ в режиме `scan` (`sample_resources`), k6 по-прежнему
без лимита;
- **PostgreSQL `max_connections`:** 100, как у образа (`-c
max_connections` в override); у серий — из конфигурации ячейки,
лимиты конфигурации в паспорте (`limits.<конфигурация>`);
- **профиль `full`:** размеры, конкуренция, повторы, прогрев и
длительности, длина текста, порция наполнения, зерно выбора курсоров
и сдвиг зерна для прогрева, порог пометки `generator`, лимиты и срок
сессии стенда. Все они — поля `Profile` в `run.py` и целиком пишутся в
`meta.json`: новый параметр методики заводится там же, а не константой
в коде.
`make bench_compare` проверяет совпадение всего этого по паспортам
(лимиты, образы, настройки PostgreSQL, `maxmemory*` Valkey, окружение
приложения, профиль).
Изменить что-то из списка — значит сменить методику: старые метки
перестают быть «до», базовый замер переснимается, а в `REPORT.md`
записывается, что и почему поменялось.
## Профиль отказа реплик (`failover`)
Доказательство уровня 4 «поочерёдная остановка каждой реплики: RPS,
ошибки, время восстановления» (design change `graceful-failover`,
решения 5 и 7). Матрицу лабы 2 он не снимает и с её метками не
сравнивается.
- Лимиты — как у рабочего стенда `docker-compose.yml` (API 1 CPU /
512 МБ на реплику, две реплики, PostgreSQL 2 CPU / 1 ГБ, Valkey
0,5 CPU / 128 МБ, HAProxy 1 CPU / 256 МБ): профиль отвечает, что видит
клиент `make run_docker` при отказе реплики. Читаемый чат —
1 000 сообщений, без фоновых.
- Нагрузка — k6 `constant-arrival-rate`: 100 записей с ключом
`<прогон>.<фаза>.<n>` и 100 чтений страницы истории в секунду, около
половины потолка одной реплики. Фаза — режим × реплика: окно до
действия, `docker stop --timeout 9` / `docker kill` / `docker pause`,
окно отказа, `docker start` того же контейнера или `docker unpause`,
окно после возврата. Перед фазой LB видит обе реплики `UP`.
- Все отметки — часы ВМ Docker: действие и возврат — события Docker
(`docker events`), исключение и возврат в LB — строки журнала HAProxy
(`docker logs -t`), запросы — `Date.now()` k6 при отправке. Часы хоста
с ними не сравниваются.
- События цели — **поток** `Stand.container_events` (`docker events
--filter container=<id>` в `work_dir/<фаза>-events.log`), запущенный
после выбора цели и до k6 и остановленный после возврата в LB, а не
`docker events --since … --until …` после фазы: демон хранит только 256
последних событий всех контейнеров, и проверки здоровья, `docker exec`
оркестратора и чужих проектов их вытесняют. Сверка обоих способов на
одном прогоне: без помех моменты совпали до наносекунды, под шумом
`docker exec` буфер потерял события всех четырёх фаз, поток — ни
одного (design change `fix-known-issues`, решения 9–10;
`evidence/tests/fix-known-issues-checks.md`). Нет события действия
или возврата — отказ с фазой и репликой.
- Каждый запрос — строка `fo,…` в файл консоли k6 (`--console-output`),
а не в вывод `docker exec`: там в самопроверке пропали две строки из
4 601. Число строк сверяется с итерациями сценариев из итога k6,
расхождение — отказ.
- VU k6 создаются заранее с запасом под зависшую реплику
(`failover_pre_vus` 600 на сценарий: половина запросов ждёт 504 10 с).
Иначе k6 создаёт их на ходу и пропускает итерации, и интенсивность
перестаёт быть постоянной; пропуски — `dropped_iterations` и пометка
`dropped`.
- После фазы каждая неуспешная запись повторяется с тем же ключом и
телом до 201 (`k6/retry.js`), затем `psql` стенда: сообщений в чате
записи и разных текстов столько, сколько отправлено ключей. Это
доказательство «без потерь и дублей», расхождение — отказ.
- Превышение формулы обнаружения — пометка `over_bound` в
`phases.csv`, а не отказ: это результат, а не сбой стенда.
- **Ресурсы** (design change `profile-resources`): после `prepare_load`
и до первой фазы запускается сэмплер `mtusi-bench-sampler` в режиме
`scan` (`Profile.sample_resources`), удаляется после последней фазы.
Раз в секунду он обходит cgroup всех контейнеров ВМ и читает
`/proc/stat`; без сети, без метки проекта и паролей, к PostgreSQL и LB
не обращается, процессов в контейнерах стенда не запускает. Роли —
у оркестратора (`Stand.container_map()`: метка сервиса compose, k6 и
сэмплер по имени), чужие cgroup отбрасываются (`meta.resources.unmapped`
— их число). Окна фазы: до действия (от первого запроса + 2 с), окно
отказа (действие → возврат), после возврата (до последнего запроса);
`docker start` после `stop` / `kill` — новая cgroup, её счёт идёт с
момента возврата; у `pause` … `unpause` CPU интервалов, задевающих
заморозку, относится к её внешней части. CPU на успешный запрос —
только до действия.
Разбор и агрегаты — `resources.py` (`--selftest`). Сторож: сэмплер
остановился или тиков нет дольше 3 с в нагрузке — отказ с фазой.
Сумма лимитов CPU на пике и сэмплера больше CPU ВМ — код 2 до стенда
(`meta.resources.budget`).
- Результаты — `evidence/failover/<метка>/` (`meta.json`, `phases.csv`,
`timeline.csv`, `resources.csv` — строка на фазу × окно × компонент,
`samples.csv` — посекундно от действия, `summary.md`,
`raw/<фаза>-k6.json`, `raw/<фаза>-lb.log`), пробные
`quick-failover-*` — в `.gitignore`.
Профиль замера для отчёта — `make bench_failover` после проверки хоста
(раздел «Результаты»), рабочий стенд на время замера остановлен.
## Профиль поочерёдной замены (`rollout`)
Доказательство уровня 4 «rolling update под нагрузкой; миграции
однократно и совместимы» (design change `rolling-update`, решение 8).
Матрицу не снимает и с метками `bench` не сравнивается.
- Стенд, лимиты, нагрузка, строки k6, повтор неуспешных записей и
сверка — как у `failover` (`k6/failover.js`, `k6/retry.js`, поля
`failover_*` профиля). Окна — `rollout_before_s` до запуска скрипта,
бюджет замены `rollout_budget_s`, ещё `rollout_after_s`.
- Реплики стартуют на образе `Profile.rollout_from` (сейчас `c50b721`,
последний commit до change): `git archive <commit> | docker build`
под тегом `mtusi-messenger:bench-from`, затем `docker tag` на
`mtusi-messenger:bench`. Рабочее дерево не трогается; тег снимается
при уборке. `--from <commit>` — отладка (`overrides`).
- Замену делает **тот же** `scripts/rolling-update.sh`, что у рабочего
стенда. Правило «`-p mtusi-bench`, оба `-f`, `--env-file`»
выполняется переменными `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`,
`COMPOSE_ENV_FILES` (`Stand.script_env`). Скрипт сам пересобирает тег
из текущего checkout (слои из кэша) и один раз применяет миграции.
- Время — часы ВМ: начало замены — `create` контейнера миграции
(события Docker с меткой проекта), шаги — события `create`/`start`
новой и `kill`/`die`/`destroy` старой, `UP`/`drain`/`maint`/`ready`
слотов из журнала LB, соответствие реплик слотам — строки скрипта.
- «Старые» и «новые» ответы — по `X-Instance-Id` контейнеров до и после.
Ответ старой реплики, отправленный позже 0,2 с после её `drain`, —
пометка `old_after_drain`: дренаж не сработал.
- Отказ команды: скрипт вернул не 0, k6 упал, хранилище падало, сверка
не сошлась, в конце не `API_REPLICAS` работающих реплик, есть прежняя
или реплики на разных образах, LB за 30 с не видит `UP` все реплики.
Ошибки клиента — пометка `errors`, не отказ.
- **Ресурсы** — тот же сэмплер `scan`, что у `failover`: запуск после
`containers_before`, до потока событий и k6. Режим `scan` видит и
третью реплику, и контейнер миграции с первого тика. Роли: `api-old` /
`api-new` по `X-Instance-Id` до и после, `migrate`, остальные — по
сервису; удалённые к концу контейнеры — по `create` из потока событий.
Окна: до (от первого запроса + 2 с до первого `exec_start` скрипта в
контейнер проекта, кроме проверок здоровья — `Stand.healthcheck_actions`),
подготовка (проверки и сборка до `create` миграции), замена (до
`destroy` последней старой), после. CPU на запрос — только до и после.
На пике — `API_REPLICAS` + 1 реплик: бюджет CPU и `vm_warnings` считают
их. Сторож — как у `failover`.
- Результаты — `evidence/rollout/<метка>/`: `meta.json` (с разделом
`rollout`: commit, образы, контейнеры и ревизия до и после, начало
подготовки `script_start_at`; `resources` — режим, бюджет, контейнеры),
`rollout.csv`, `replicas.csv`, `timeline.csv`, `resources.csv`,
`samples.csv` (секунды от начала замены), `summary.md`,
`raw/rollout-k6.json`, `raw/rollout-lb.log`, `raw/rollout-script.log`
(только строки скрипта, без вывода сборки и миграции). Пробные
`quick-rollout-*` — в `.gitignore`. Замер для отчёта — `make
bench_rollout` после проверки хоста, рабочий стенд остановлен.
## Серии трека 1 (`scaling_*`)
Доказательство уровня «5», трек 1 «Цена масштабирования» (design change
`scaling-bench`; гипотезы H1–H3 — его решение 10 и `REPORT.md`).
Матрицу не снимает; метки серий сравниваются только с метками серий.
- **Серии и конфигурации** (реплик × CPU / память, `max_connections`):
`a` — бюджет 4 CPU / 2 ГиБ: 1 × 4, 2 × 2, 4 × 1; `b` — 1…6 × 1 CPU /
512 МиБ; `pool` — 4 × 1 при 100 и 50; `ab` — 1 × 1 и 6 × 1 («до/после»
и A/A, метка `scaling-aa`); `db` — 1, 2, 4 × 1 при PostgreSQL 0,5 CPU
и контроль 4 × 1 при 2 CPU (насыщение БД управляемым опытом; лимит
PostgreSQL — пятый элемент конфигурации, имя `<k>x1-pg<CPU>`); `db4`
— две ячейки серии `db` (4 × 1 при 0,5 и 2 CPU) для «до/после» change
`scaling-improvement`: окончательные метки попытки 2 —
`scaling-db-aa2`, `scaling-db-before2` (пул 10 + 5) и
`scaling-db-nooverflow2` (10 + 0); попытка 1 (`scaling-db-aa`,
`-before`, `-nooverflow`) испорчена помехами хоста и оставлена как
есть; метки `scaling-a`, `-b`, `-pool`, `-aa`, `-db` сняты на
10 + 5); `quick` и `db_quick` —
самопроверки. Общие поля — в
`scaling_profile()` `run.py`, чтобы методика серий не расходилась.
- **Бюджет:** PostgreSQL 2 / 1 ГиБ, HAProxy 1 / 256 МиБ, Valkey 0,5 /
128 МиБ, k6 2 / 1 ГиБ, сэмплер 0,25 / 128 МиБ — 5,75 CPU без реплик.
Сумма CPU конфигурации больше CPU ВМ — отказ до стенда (код 2); поэтому
серия `b` — до 6 реплик (11,75 CPU), граница пула при 10 + 5 того
времени (k = 7) — управляемым опытом `pool`; с 10 + 0 — k = 10. Бюджет — `meta.budget`.
- **Ячейка** — конфигурация × повтор, 3 повтора, каждая на свежем стенде
(`down -v`, миграции, данные: читаемый чат 10 000, 10 чатов записи).
Порядок — круги, перестановка с зерном `order_seed`, повтор одной
конфигурации не стоит подряд; план — `meta.plan` до первой ячейки.
- **Ступень** — один запуск `k6/mixed.js` (смесь 70/20/10, три сценария
`ramping-arrival-rate`): прогрев 15 с с нуля (первая ступень и после
паузы) или 5 с подъёма, окно 20 с. Тег `window` по
`exec.scenario.startTime`; окно на часах ВМ — от `t0` из `setup()`.
Сначала фиксированные 250 и 500/с, затем поиск R*: L0 = ступенька
`100 × 1,25^i` ≥ max(300 × реплик, пройденный фиксированный), подъём
или спуск, два деления по среднему геометрическому (`scaling.Search`).
- **SLO:** p95 успешных ≤ 200 мс и (ошибки + короткие страницы +
недосланные) / запланированные ≤ 1 %. Нарушила — пауза 10 с и
`wait_ready`. Ошибок > 50 % или p95 > 2 с — досрочный выход k6 (код
99), причина `abort`.
- **Генератор с лимитом и брак:** CPU k6 ≥ 1,8 ядра, его троттлинг ≥ 10 %
или недосланные при CPU k6 ≥ 70 % лимита (`vus` k6 — выборка раз в
секунду, «свободные VU» по нему не видны). Брак останавливает поиск,
R* — нижняя граница (`generator_bound`); лечение — поднять лимит
(смена методики) и переснять серию.
- **Сэмплер** `mtusi-bench-sampler` (`bench/sampler.sh` на образе
PostgreSQL стенда, `--cgroupns host`): раз в секунду `cpu.stat`,
`memory.current`, `cpu.pressure` каждого контейнера, `/proc/stat` и
PSI ВМ, CSV статистики HAProxy, а одним постоянным соединением `psql
\watch` — `pg_stat_activity` по адресам реплик и `wait_event`,
`pg_stat_database`, `pg_stat_wal`, `pg_stat_io`. Его соединение
занимает слот: граница пула — `max_connections − 1`. Строки ступени,
признаки узкого места и пороги — `scaling.py` (`THRESHOLDS`). Это режим
`list` (явный список контейнеров, сеть стенда, метка проекта, `psql` и
опрос LB); профили `failover` и `rollout` берут тот же скрипт в режиме
`scan` — без сети, без `psql` и LB (design change `profile-resources`).
- **Файлы метки:** `runs.csv` (строка на ступень, новые столбцы в
конце), `searches.csv` (строка на ячейку), `samples.csv` (посекундно
в окнах), `prefill.csv`, `summary.md`, `p95-by-rate.svg`,
`cpu-by-component.svg`, `raw/<ячейка>-a<попытка>-s<NN>.json`,
`raw/…-errors.log` (5xx и «too many clients»: строки PostgreSQL, API,
LB без секретов), `progress.json`.
- **Продолжение:** `RESUME=1` — тот же профиль и commit, дерево чистое
без каталога своей метки; готовые ячейки (строка в `searches.csv`)
пропускаются, прерванная снимается с попыткой +1. Метку каждой серии
коммитить до запуска следующей: иначе паспорт следующей — `dirty:
true`.
- **Блокировка** `bench/.bench.lock` (`flock`) — для всех профилей:
второй прогон — код 2. Остатки стенда серии удаляет сама (блокировка
взята, значит, прогона нет); прочие профили по-прежнему отказывают.
- **Сравнение и «до/после»:** `make bench_compare` у серий — по общим
конфигурациям (R*, задержки на фиксированных уровнях, CPU на запрос,
CPU PostgreSQL на R*; шум `AA` — наибольшее |Δ медианы R*|), и вторая
таблица «PostgreSQL на R* и первой нарушившей ступени» (уровень, CPU
PostgreSQL на запрос, новые сессии за окно, соединения; поля
`config_stats` `*_r` / `*_f`). Серия против матрицы — отказ. `make
bench_ab … SERIES=ab` снимает серию вместо матрицы.
- **Графики:** `make bench_plots LABELS="scaling-a scaling-b"` —
`evidence/plots/scaling/`; пробные `quick-*` — в `.gitignore`.
## Как писать
- Стенд — чёрный ящик: `run.py`, `k6/` и `compare.py` не импортируют
`src` и не ходят в приложение мимо HTTP. Все запросы к API делает k6
внутри сети стенда, оркестратор управляет только docker CLI.
- Исключение — PostgreSQL стенда: оркестратор обращается к нему
напрямую (`docker exec … psql` от пользователя контейнера, SQL через
stdin, `docker logs`), но только для обслуживания и измерения:
- `VACUUM (ANALYZE)` и `CHECKPOINT`;
- размеры таблиц и число сообщений по чатам;
- включение и выключение `auto_explain` между маркерами;
- журнал Postgres с планами;
- варианты запроса истории (без индекса, с вариантами индекса, с
курсором через `OR`, generic plan) в транзакции, которая
откатывается;
- пробы записи по вариантам индекса в транзакции, которая
откатывается, и `VACUUM messages` после каждой;
- `pg_dump` исходной базы, второе хранилище (`docker run`, имя
`mtusi-bench-postgres-restore`, volume `mtusi-bench_restore`, метка
проекта), `pg_restore` и `ANALYZE` в нём, построчная сверка обеих
баз;
- `FLUSHALL` Valkey стенда и пересоздание API с адресом
восстановленной базы — только на этапе восстановления, в конце
размера. Второе хранилище и его volume `Stand.stop()` удаляет до
`compose down`;
- ревизия `alembic_version` до и после замены (профиль `rollout`).
Схему меняет не оркестратор, а миграция приложения, которую
запускает `scripts/rolling-update.sh`, — как на рабочем стенде.
Данных и схемы, видимых приложению, он не меняет: список индексов и
число строк `messages` до и после этапа сверяются, при различии —
отказ. Между прогонами нагрузки нет. Свою копию SQL приложения стенд
не держит: варианты строятся из текста запроса в журнале Postgres.
- Из журнала Postgres в результаты идут только планы запроса истории
(`messages`). Между маркерами журнал содержит и проверку сессии с
SHA-256 токена в параметрах: она отбрасывается и не пишется никуда.
- Все вызовы `docker compose` — только с `-p mtusi-bench`, обоими `-f` и
`--env-file bench/bench.env`, с окружением, собранным `run.py`:
без `-p` `down -v` удалил бы чужой volume, без `--env-file` compose
прочитал бы рабочий `.env`.
- Скрипты `bench/` на хосте — только stdlib Python, запуск
`uv run python bench/<файл>.py`. Новых зависимостей не добавлять.
`bench/sampler.sh` — bash, работает только внутри контейнера
сэмплера, на хосте не запускается.
- Сценарии k6 — JavaScript без Node.js: только встроенные модули k6.
Заголовок идентификации собирается в одном месте `lib.js`: Bearer,
как `Actor.headers()` в `student-tests/`. Отправка сообщения — только
с `messageHeaders(token)` из `lib.js`: с лабы 3 она добавляет новый
`Idempotency-Key` (`crypto.randomUUID()`) на каждую отправку; без
ключа запись получит 400. Стенд отправки не повторяет, поэтому число
сообщений равно числу подтверждённых 201, а запись ключа входит в
стоимость записи всех меток лабы 3. Пароли пользователей стенда
живут только в памяти `prepare.js`, токены — в `.work/fixture.json`,
который удаляется в конце прогона; в каталог метки не попадает ни то,
ни другое.
- Имена контейнеров и сети — `mtusi-bench-*`. Чужие контейнеры
(`make run_docker`, другие проекты) стенд не трогает и не
останавливает. Уборка своих — в `finally` и по Ctrl+C. Остатки
прерванного прогона `run.py` не удаляет сам: он отказывается
стартовать и печатает команды уборки.
- Случайность только через свой генератор с зерном из профиля
(`seed + номер VU`), не `Math.random`.
## Измеренное состояние — commit
Замер или тест, результат которого идёт в отчёт, снимается с
закоммиченного состояния кода; хеш попадает в шапку файла доказательства
и в `REPORT.md`. Любое число в отчёте должно воспроизводиться из
названного commit (указание пользователя 2026-09-30).
Коммит делает не агент сам: перед замером он показывает изменения
(`git status`, `git diff --stat`), предлагает сообщение коммита и ждёт
подтверждения пользователя (указание пользователя 2026-10-01).
Пробное изменение `src`, которое потом откатывается, — отдельный commit,
откат — новый commit поверх (`git revert`), без переписывания истории;
оба — по тому же порядку. Push и остальные операции git — только по
просьбе.
## Сравнение меток: `make bench_compare`
- «До» и «после» снимаются в одной сессии хоста, подряд, без
перезагрузки между ними. Код приложения между ними отличается одним
изменением.
- Порядок: изменение закоммичено, проверено тестами и откачено
отдельным commit; затем `make bench_ab BEFORE=... AFTER=...
REAPPLY=<commit отката>` снимает «до», коммитит доказательства,
возвращает изменение и снимает «после». Команда сама делает два
коммита и отказывается стартовать на нечистом рабочем дереве: стенд
записал бы в паспорт `dirty: true`. Поэтому `make bench_ab` агент
запускает только с согласия пользователя.
- Уровень шума берётся из сравнения двух меток одного и того же кода
приложения (A/A), параметр `AA`. Что код одинаков, проверяется по git
(`git diff <commit> <commit> -- src Dockerfile pyproject.toml
uv.lock`): команда этого не видит.
- Изменение в ячейке — эффект, только если разбросы повторов не
пересекаются и изменение медианы больше уровня шума сценария. Дельту
в отчёт переносить из таблицы команды, не считать вручную.
- Ячейки сценария, который изменение не затрагивает, — контроль: они
тоже показываются в отчёте.
- У серий трека 1 R* дискретен: шаг сетки поиска после двух делений —
1,25^¼ ≈ 5,7 %, и шум A/A `scaling-aa` (5,4–5,7 %) — одна ступень.
Сдвиг R* на одну ступень при непересекающихся разбросах команда
назовёт эффектом, но он в пределах разрешения. Эффект R*
засчитывается при сдвиге медианы не меньше двух ступеней сетки: R*
после / R* до ≥ √1,25 ≈ 1,118 (+11,8 %; например, 931 → 1 041), иначе
— с явной оговоркой о разрешении (verify change `scaling-bench`, S6;
порог уточнён до замеров change `scaling-improvement`, решение 5).
Шум `scaling-aa` оценён по двум конфигурациям × 3 повтора.
- `CHANGE=<change>` у `make bench_compare` пишет change в шапку
сравнения серий (по умолчанию `scaling-bench`).
- Пул приложения в метке — дефолт `src/config/settings.py`, а не
окружение стенда: окружение приложения пишется в `stand.app_env`, и
сравнение меток с разным пулом из окружения откажет как «разная
методика» (design change `scaling-improvement`, решение 2). Изменение
пула для «до/после» — правка дефолта в коде.
- Метка A/A годится как `AA`, только пока код приложения тот же: после
правки `src` (например, 53300 в `68edc66` после `scaling-aa`) A/A
снимается заново на коде «до».
## Результаты
- Каталог метки не перезаписывается. `evidence/bench/quick-*` — в
`.gitignore`: короткий прогон проверяет стенд, а не даёт результат.
- `evidence/compare/<до>__<после>.md` выводится из неизменяемых
каталогов меток и может пересоздаваться; сравнения пробных меток
`quick-*` — в `.gitignore`.
- Планы запроса истории — `explain-<размер>.txt` в каталоге метки, как
есть из журнала Postgres и psql. В отчёт числа плана переносятся из
этих файлов или из раздела планов `summary.md`, не пересчитываются.
- Столбцы `runs.csv` и `prefill.csv` не переименовываются и не
удаляются: по ним сравниваются метки. Новая метрика — новый столбец
в конце.
- В результатах нет секретов, `.env` и абсолютных путей домашнего
каталога; данные синтетические.
- Перед замером для отчёта (полная матрица, серии трека 1, профили
`failover` и `rollout`) хост должен быть в состоянии, которое можно
проверить: питание от сети, давления на память нет и свободной памяти
хватает на стенд (`memory_pressure`), посторонних контейнеров нет.
Занятый swap сам по себе не помеха (указание пользователя 2026-10-10):
в него уходят неактивные страницы. Помеха — выгрузка во время прогона:
`run.py` пишет счётчик `Swapouts` (`vm_stat`) в начале и в конце
(`host_state.swapouts`), прирост — `host_state.swapouts_delta`
(`swapouts_delta`: пишется и при 0, нет — только без одного из
счётчиков; до change `fix-known-issues` при `Swapouts` 0 в конце поле
пропадало, так у меток `scaling-db-*2`) и предупреждает о приросте; у серий — ещё по
ячейке и ступени (`host_swapouts`, пометка `host_swap`). Давление на
память или батарея — перезагрузить или подключить питание. Состояние
записывается в паспорт (`host_state`), в отчёте оно указывается по
паспорту, а не по плану. Во время прогона ноутбук не нагружать и не
закрывать крышку: цели `bench*` запускаются под `caffeinate -isu`
(`-u` будит из DarkWake полностью, `-i -s` не дают уснуть по простою),
но от сна при закрытой крышке он не спасает. Сон посреди прогона ставит
ВМ Docker на паузу; `run.py` замечает его по разнице реального и
монотонного времени (`host_state.slept_seconds`, предупреждение больше
5 с). Предупреждения о хосте в `meta.json` (`host_warnings`) — повод
переснять, а не игнорировать.
+262
View File
@@ -0,0 +1,262 @@
---
paths:
- "Dockerfile"
- "docker-compose.yml"
- ".dockerignore"
- "scripts/restart.sh"
- "infra/**"
---
# 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 и сервером.
- PID 1 ядро не доставляет сигнал без обработчика — он отбрасывается.
Поэтому `src/__main__.py` ставит ранний обработчик SIGTERM и SIGINT
(`src/infra/early_stop.py`) до импорта приложения: импорт — почти
весь старт (~0,7 с из ~0,8 при 1 CPU), и без него `docker stop`
стартующей реплики ждал 10 с и кончался SIGKILL
(`evidence/failover/stop-at-start.md`). Окна старта — `run-modes.md`.
- `init: true` (tini) у `api` не ставится: сервер перестал бы быть
PID 1. Остаётся окно запуска интерпретатора — десятки миллисекунд до
первых строк точки входа; `rolling-update.sh` убирает реплику без
слота LB `docker rm -f` (`balancer.md`). У PostgreSQL стенда отказов
init есть — по другой причине (`student-tests.md`).
- `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 (стенд `bench/`), а 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.
Это согласовано с преподавателем
2026-09-29 как выполнение README лабы 1, п. 3 и `Dockerfile.example`,
п. 6 (AGENTS.md, «Согласования с преподавателем»). Что где лежит —
`settings.md`.
- Миграции едут вместе с образом: `migrations/` и `alembic.ini`
копируются в runtime, и миграционный сервис compose запускает тот же
образ с другой командой (`migrations.md`). `.dockerignore` их не
исключает.
## `.dockerignore`
Файл из skeleton дополнять, а не заменять: `config.toml`, `.claude`,
`openspec`, `tests`, `student-tests`, `contracts`, `infra`, `*.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:lab3 -
```
`.env`, `config.toml` и `.venv` в него не попадают по `.gitignore`.
Перед PR — ещё и настоящий `git clone`.
## docker-compose.yml
- Имя проекта — `name: mtusi-lab3`, образ — `mtusi-messenger:lab3`. Имя
проекта задаёт имена volume: с прежним `mtusi-lab2` стенд этой лабы
подключился бы к данным второй лабы, а `make wipe_data` их удалил бы.
Имя меняется в каждой новой лабе.
- Сервис `api`: `build: .`; с лабы 3 **без `ports` и без
`container_name`**, реплик `${API_REPLICAS:-2}`, наружу только LB
(`balancer.md`). До лабы 3 порт был
`"127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"`; теперь эта
строка — у сервиса `haproxy`. `environment` собирается из якорей:
`x-db-env` (`APP__RUN_MODE: docker`, `DATABASE__*` из переменных
`POSTGRES_*`) и `x-cache-env` (`CACHE__*` из `VALKEY_*`), у `api`
— оба через `<<: [*db-env, *cache-env]` плюс `APP__PORT`
(`settings.md`, «Консоль и docker»). У `migrate` — только
`x-db-env`: пароль Valkey ему не нужен; `haproxy` получает только
`API_PORT` (секреты только там, где нужны, рубрика «4»).
Healthcheck образа проверяет `APP__PORT`; `stop_grace_period: 10s`;
`restart: unless-stopped`; лимиты CPU/RAM
(`deploy.resources.limits`) у всех сервисов — override стендов
(`bench/`) задаёт лимиты в той же форме: `cpus` / `mem_limit` рядом с
ними compose не принимает. Имена переменных в `.env` — `settings.md`,
«Имена в `.env`».
- Литералов адреса и порта Postgres в compose нет: `POSTGRES_HOST`
становится алиасом сервиса в сети, `POSTGRES_PORT` — портом самого
сервера через `PGPORT` (его же берут `pg_isready` и `psql` в
контейнере). Литерал — только адрес публикации `127.0.0.1`: это
требование безопасности, а не параметр.
- `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`. Сам файл необязателен: без него приложение стартует на
дефолтах.
- Смонтированный файл должен читаться непривилегированным пользователем
контейнера. На Docker Desktop права хоста не мешают, на Linux нужен
режим `644` или совпадающий uid.
- Новая переменная контейнера — строка в `.env.example` и в
`environment` сервиса.
- С лабы 2 compose — основной запуск стенда: API без Postgres запросы
не обслуживает. Проверка и запуск — по README:
`docker compose --env-file .env config --quiet`, затем
`up -d --build`, ожидание `/health/ready`. Роли лабы 3 — load_balancer
(HAProxy), api × ≥2, postgres и valkey (`contracts/infrastructure.json`:
Redis/Valkey необязателен, у нас остаётся кэшем).
`compose.example.yaml` — лишь список ролей, стенд — свой
`docker-compose.yml` (compose находит его сам, как и `compose.yaml`).
- Образы зависимостей закреплены так же, как базовый: тег с патч-версией
и digest индекса (`postgres:18.6-trixie@sha256:...`), не
`postgres:18` и не `latest`. Точка монтирования volume — из
`Config.Volumes` образа: у Postgres 18 это `/var/lib/postgresql`, а не
`/var/lib/postgresql/data`, как у 17.
- У каждой зависимости свой healthcheck, API ждёт `depends_on:
condition: service_healthy`. У Postgres — `pg_isready -h 127.0.0.1`
по TCP: при инициализации образ поднимает временный сервер только на
сокете, и проверка через сокет сказала бы «готов» раньше времени.
Миграции — отдельный одноразовый сервис на образе API
(`pull_policy: never`, образ собирает `api`), API ждёт его
`service_completed_successfully`.
- Данные — именованные volumes. `make down` и скрипты их не удаляют;
удаление учебных данных — отдельная явная команда в `REPORT.md`.
- Postgres наружу — только `127.0.0.1:${POSTGRES_OUT_PORT}`, для
console-режима. Пароль — `POSTGRES_PASSWORD` в `.env`, в приложение
мостом (`settings.md`).
- Valkey (сервис `valkey`, кэш карточек чатов): тот же пин тега с
патч-версией и digest индекса, `restart: unless-stopped`, healthcheck,
`api` ждёт `service_healthy`. Отличия от Postgres:
- volume нет: persistence выключен в `infra/valkey/valkey.conf`
(`save ""`, `appendonly no`), кэш после рестарта пуст, а данные —
в Postgres. Если бы в Valkey жили сессии, persistence был бы
обязателен: без него рестарт стёр бы их, и `make test-persistence`
упал бы;
- пароль — `VALKEY_PASSWORD` в `.env`, в контейнер — переменной
окружения. Сервер получает его в `command` через `sh -c` из
переменной контейнера (`--requirepass "$$VALKEY_PASSWORD"`), в
compose он не литерал. Запуск — `exec docker-entrypoint.sh
valkey-server ...`: с `sh` первым аргументом entrypoint образа не
сбрасывает root, а так сервер работает от пользователя `valkey`;
- healthcheck — `valkey-cli ping` с паролем из `VALKEYCLI_AUTH`
(без `-a` в команде): `PONG` только после AUTH, и проверка
ловит неверный пароль;
- порт сервера — `VALKEY_PORT` (`--port`), алиас в сети —
`VALKEY_HOST`, публикация — `127.0.0.1:${VALKEY_OUT_PORT}`, как у
Postgres.
- Конфигурации сервисов (`valkey.conf`, при необходимости
`postgresql.conf`) — в `infra/<сервис>/`, монтируются read-only
длинной записью с `create_host_path: false` (`infra/README.md`). В
`REPORT.md` — таблица роль → сервис → версия/digest → healthcheck →
volume → порт → способ передачи credentials.
## Обновление кода на стенде
- `make run_docker` после пересборки пересоздаёт реплики, образ которых
изменился, — все разом, с простоем. Compose сравнивает метку
контейнера `com.docker.compose.image` (манифест платформы) с
манифестом тега. Пересборка без изменений кода реплики не трогает,
хотя digest тега новый: индекс образа содержит отметки времени
сборки (`evidence/rollout/compatibility.md`).
- Хранилище образов Docker Desktop — containerd. У образа три digest:
- индекс — `docker image inspect <тег>`;
- манифест платформы — метка контейнера и `docker image inspect
--platform`;
- конфигурация — поле `.Image` контейнера.
`docker ps` показывает у реплик digest конфигурации, а не имя тега.
Это не признак «старого образа»: прежний пункт `KNOWN_ISSUES.md` о
том, что `run_docker` не пересоздаёт реплики, на этом и ошибся. Образы
сравниваются между контейнерами, по `.Image`.
- Без простоя новый код доходит до реплик через `make rolling_update`
(`balancer.md`): по одной, с выводом из LB и одной миграцией.
## `scripts/restart.sh`
Hook для `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
(`tests/README.md`), по образцу `scripts/restart.example.sh`.
- Перезапускает **все** реплики API, LB и **все** используемые
хранилища: Postgres и Valkey. Volumes, схему и данные сохраняет: без
`down -v`, `FLUSHALL`, повторного seed и изменения тестовых данных.
Кэш Valkey после рестарта пуст сам: persistence у него выключен.
- Порядок: `stop haproxy api` → `restart postgres valkey` → `up -d
--wait postgres valkey` (те же контейнеры, ожидание healthcheck) →
`start api haproxy`. `start api` запускает и зависимость `migrate`:
повторный прогон миграций — no-op. Число реплик не меняется: `start`
поднимает те же контейнеры, а не масштабирует (реплику, остановленную
`stop-one.sh`, тоже).
- `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`,
`git update-index --chmod=+x`). Возвращает 0 только после действия,
укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает.
- Успех теста не доказывает, что БД действительно перезапускалась. В
`evidence/` — состояние контейнеров до и после (`docker compose ps`,
`StartedAt` из `docker inspect`).
## Дальше
Реплики, HAProxy, `scripts/stop-one.sh`, поочерёдная замена, лимиты и
пулы — `balancer.md`.
+40
View File
@@ -0,0 +1,40 @@
---
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 выбирает часть колонок |
| Страница | `<Entity>PageDTO` | `items` и `next_cursor: str \| None` |
- Каждый класс — `@dataclass(frozen=True, slots=True)`, суффикс `DTO`.
Repo отдаёт снимок строки, а не ORM-объект: изменение DTO в БД не
попадёт, и frozen не даёт сделать вид, что попадёт. pydantic читает
DTO через `from_attributes`.
- Обязательные поля первыми, поля со значением по умолчанию — последними;
для `list` / `dict` — `field(default_factory=...)`. В frozen-DTO
коллекции — `tuple` / `frozenset`.
- Типы доменные: `UUID`, а не `str`; `datetime` (aware UTC), а не строки;
`enums.*`; `X | None` для nullable.
- Имена полей `<Entity>FullDTO` совпадают с колонками модели, иначе
`FullDTO(**row.to_dict())` сломается. Исключение — секреты: хэш
пароля и хэш токена в `UserFullDTO` и в DTO, уходящие в API, не
попадают. Для входа — отдельный DTO из выбранных колонок
(`auth.md`).
- Каждый новый класс добавляется в `__init__.py` пакета (импорт и
`__all__`) в алфавитном порядке.
- Короткий docstring на русском, если назначение не очевидно из имени.
- Enum-ы — `StrEnum`. Значение хранится в БД, поэтому переименование
значения = миграция (`migrations.md`).
+135
View File
@@ -0,0 +1,135 @@
---
paths:
- "src/infra/**"
---
# Инфраструктура (`src/infra/`)
Всё, что не содержит бизнес-логики и может смениться от лабы к лабе:
логгер, PostgreSQL (`db/`), кэш Valkey (`cache/`), дальше — S3, брокер,
телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет:
они в сервисах, атомарные операции — в repo.
- Клиент хранилища (engine Postgres, кэш Valkey) — глобал своего модуля
(`db/session.py`, `cache/instance.py`): создаётся при импорте по
`settings` (настройки читаются один раз на процесс), соединения
открывает лениво, при первом запросе. Пакет `src/infra/<клиент>/` этот
модуль не импортирует, модели тоже, поэтому alembic и скрипты клиента
не создают. Закрытие (`engine.dispose()`, `cache.aclose()`) — в
lifespan `src/main.py`. Почему не `app.state` — design change
`postgres-storage`, решение 5.
- Глобал импортируют только `src/main.py` (закрытие) и
`src/api/dependencies.py`; сервисы получают сессию или клиент через
конструктор из зависимости и сами глобал не импортируют. Процессу со
своим пулом (worker с лабы 5) — свой вызов фабрики `create_engine`.
- `db/`: `engine.py` — фабрики engine и сессий, `BoundedCloseConnection`,
`ping`; `session.py` — глобалы `engine` и `session_factory`;
`errors.py` — `is_db_unavailable`; модели — `models/`
(`migrations.md`). Драйвер — asyncpg.
- `cache/`: `client.py` — фабрика `create_cache` и обёртка `Cache`;
`instance.py` — глобал `cache`. Ключи и формат значений — в repo
(`src/core/repos/chat_cache.py`), не здесь.
- `early_stop.py` — ранний обработчик SIGTERM и SIGINT процесса
(`install()`, `disarm()`): только stdlib, ни настроек, ни логгера, ни
других модулей `src`; клиентом хранилища не является, глобала клиента
нет, `dependencies.py` его не импортирует. Импортируется в
`src/__main__.py` до приложения; `disarm()` — первая строка lifespan
`src/main.py` (а не `main()` перед `uvicorn.run`: до
`capture_signals` сигнал снова терялся бы). Окна старта —
`run-modes.md`, запись — `logging.md`.
- Источник истины — PostgreSQL. SQLite, файлы и память процесса его не
заменяют (`README.md`, п. 2). Кэш не хранит ничего, чего нет в
Postgres: сессии в Valkey не лежат (`auth.md`).
- Пул ограничен (`pool_size`, `max_overflow`, `pool_timeout`), у
подключения и запроса есть таймауты (`connect_timeout_seconds`,
серверный `statement_timeout`, срок запроса `request_timeout_seconds`).
Это требование уровня 4; значения — поля секции `[database]`
(`settings.md`). Пул — на один процесс, а процессов `API_REPLICAS`:
`API_REPLICAS × (pool_size + max_overflow)` + migrate + запас
(psql, стенд `bench/`) не больше `max_connections` Postgres (по
умолчанию 100). Расчёт для заявленного числа реплик — в `REPORT.md`;
граница пула — гипотеза H3 трека 1 (`REPORT.md`, «Цена
масштабирования»).
- Пул — постоянный набор: `pool_size` 10, `max_overflow` 0 по умолчанию
(change `scaling-improvement`). Соединение переполнения `QueuePool`
закрывает при возврате, если в очереди уже `pool_size` простаивающих,
и под нагрузкой открывает заново: новый процесс PostgreSQL (~2,7 мс
CPU) и SCRAM-SHA-256 asyncpg в потоке event loop (~11 мс CPU реплики)
на каждое (`evidence/storage/connection-cost.md`). Поэтому
переполнение не включать; больше соединений — больше `pool_size`, и
тогда соединений стенда `API_REPLICAS × pool_size` + 1. Свойство
проверяет `test_pool_keeps_connections` (`make failure_checks`).
`/health/ready` берёт соединение из той же очереди пула (ждёт не
дольше 2 с): на перегрузке проверка готовности стоит в очереди вместе
с запросами.
- `idle_in_transaction_session_timeout` — серверная настройка соединений
приложения (`server_settings`, рядом с `statement_timeout`) из
`[database] idle_in_transaction_timeout_ms` (10 с; 0 — не задаётся).
Замороженный процесс (`docker pause`, зависание) держит открытую
транзакцию бесконечно: его TCP-соединение живо, keepalive ничего не
замечает. Без этой настройки строка ключа идемпотентности, которую он
вставил, оставалась бы заблокированной до разморозки, и повтор того же
ключа через другую реплику получал бы 503 снова и снова. Значение
больше `request_timeout_seconds` (валидатор `Database`): транзакция
живого запроса дольше не живёт, `get_db_session` закрывает соединение
по сроку (design change `graceful-failover`, решение 4).
- `command_timeout` asyncpg не использовать: на таймауте он отменяет
запрос через новое соединение и ждёт сервер без срока, и замёрзший
Postgres держит запрос до разморозки. Срок запроса ставит
`asyncio.timeout` в `get_db_session`, а мягкое закрытие соединения
ограничивает `BoundedCloseConnection` (`connection_class` asyncpg).
- Engine — с `hide_parameters=True`. `str()` у `DBAPIError` включает
`[SQL: ...]` и `[parameters: ...]`, и эта строка уходит в журнал: в
`warning` из `get_db_session` и в traceback ошибки 500. Без флага там
оказались бы текст сообщений, а с `session-auth` — хэши паролей и
токенов (`logging.md`, «Чего в логах быть не должно»).
- `/health/ready` проверяет критичные зависимости через infra:
`SELECT 1` в Postgres с коротким таймаутом. Valkey не проверяется: это
кэш, без него обязательный путь идёт в Postgres. Недоступность
критичной зависимости — 503. Какие зависимости критичны, фиксируется
в `REPORT.md`. С лабы 3 по `/health/ready` HAProxy решает, слать ли
реплике запросы (`balancer.md`): таймаут проверки внутри ручки
меньше `timeout check` HAProxy, иначе медленный Postgres выглядел бы
как мёртвая реплика. `/health/live` для LB не используется.
- Потеря соединения и таймауты драйвера на бизнес-запросе — 503
`unavailable` без деталей (`api-contract.md`), не 500 и не обход
аутентификации. Перевод — в `get_db_session`: `is_db_unavailable`
решает, отказ ли это, сессия закрывается через `invalidate()`, в
журнал — `warning`. Остальные `DBAPIError` (ограничения, синтаксис) —
дефект, им положен 500.
- Valkey (не Redis) — кэш карточки чата (спек `chat-cache`, design
change `membership-cache`). Роль, источник истины, срок, вытеснение и
отсутствие инвалидации — в `REPORT.md`. С лабы 3 Valkey один на все
реплики; инвалидация между ними не нужна, потому что карточка
неизменна (состав чата не меняется). Пропуск кэша после отказа
(`retry_after_seconds`) — состояние своей реплики, на корректность
не влияет. Клиент — redis-py
(`redis.asyncio`):
- **один повтор, только на обрыв**: `retry=Retry(NoBackoff(), 1,
supported_errors=(ConnectionError,))`. По умолчанию redis-py
повторяет команду с backoff, и замороженный Valkey держал запрос
6 с вместо 0,2 с. Таймаут не повторяется, а обрыв повторяется один
раз: после рестарта Valkey старое соединение пула иначе давало бы
отказ на первой команде;
- `Retry` — **из `redis.asyncio.retry`**. Синхронный `redis.retry.Retry`
асинхронное соединение принимает молча, но повтор с ним не
выполняется никогда (первая реализация так и ошиблась);
- `BlockingConnectionPool` на `[cache] max_connections` с ожиданием не
дольше `timeout_seconds`: обычный пул при всплеске запросов сразу
бросает `MaxConnectionsError`, и здоровый Valkey считался бы
отказавшим;
- `socket_timeout` и `socket_connect_timeout` — `[cache]
timeout_seconds`, а всю команду (пул, соединение, повтор, ответ)
ограничивает `asyncio.timeout` того же срока в `Cache`.
- Отказ Valkey — промах, а не 503 и не 500: `Cache.get` / `Cache.set`
ловят `RedisError` и `OSError` (в том числе `TimeoutError` от
`asyncio.timeout`), отдают `None` / `False`, и запрос идёт в
Postgres. После отказа кэш пропускается на `[cache]
retry_after_seconds` без обращений к Valkey. В журнал — один
`warning` «Cache is unavailable» на отказ и `info` «Cache is
available again» при первом успехе. Пароль в журнал не попадает: он
есть только в настройках пула.
- Клиенты внешних сервисов: адреса и секреты из `settings`
(`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки
переводятся в доменные исключения. Логи — по `logging.md`, без
секретов.
+172
View File
@@ -0,0 +1,172 @@
---
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.
С лабы 3 — ещё `instance_id` (то же значение, что `X-Instance-Id`) в
каждой записи, включая строки старта и shutdown: логи реплик
сливаются в один поток `docker compose logs`, и только по нему видно,
какая реплика остановилась и когда.
## Устройство `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` — выключен;
- шумные библиотеки (`sqlalchemy.engine`, драйвер Postgres, `httpx`,
`httpcore`) — `WARNING`: SQL с параметрами в лог не попадает.
### Отличия от 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 лабы 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`).
### Исключение: запись ранней остановки
`src/infra/early_stop.py` пишет одну запись мимо structlog: сигнал
пришёл во время импорта приложения, а логгер настраивается при первом
`get_logger()` — как раз во время импорта настроек, и обработчик застал
бы модули полуинициализированными. Запись — одна строка JSON через
`os.write` в stdout, затем `os._exit(0)`; ошибка записи выходу не мешает.
Поля — как у записей structlog: `event` «Stopped API before startup» и
`instance_id` первыми, `module` `startup`, `signal` (`SIGTERM` /
`SIGINT`), `level` `info`, `timestamp` ISO 8601 UTC с микросекундами и
`Z`. `instance_id` — `APP__INSTANCE_ID` или hostname, то же значение по
умолчанию, что `[app] instance_id`. Уровень `info`: остановку запросил
оператор, и она выполнена верно (design change `fix-known-issues`,
решение 5).
## Чего в логах быть не должно
Рубрика уровня 4: логи полезные, но **без содержимого сообщений**.
- Текст сообщений, `display_name`, `title` чата, тела запросов и ответов
целиком. Вместо текста — идентификаторы и размеры
(`text_length=len(text)`).
- Пароли, токены сессий и их хэши, заголовок `Authorization` (`auth.md`);
с лабы 3 — `Idempotency-Key` (ни целиком, ни частью: ключ выбирает
клиент, в нём может оказаться что угодно; повтор виден по
`replayed=true` и `message_id`); с лабы 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` | подключение, закрытие, ошибки; запросы к внешним API (`debug`) | `module="<client>"` |
| `main.py` | старт (host, port, режим), начало и конец shutdown | `module="startup"` |
| `infra/early_stop.py` | только остановка до старта сервера, одна запись без structlog (раздел выше) | нет, поле `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` не используется.
+104
View File
@@ -0,0 +1,104 @@
---
paths:
- "migrations/**"
- "alembic.ini"
- "src/infra/db/models/**"
---
# Миграции alembic и модели
Основа — правила bp_proxies; отличия продиктованы контрактом и
рубрикой лаб 2–3.
- Схема — до запросов: таблицы, ограничения, индексы и транзакционные
границы описываются в design change раньше, чем пишутся repo
(`README.md`, «Что сделать», п. 1).
- `alembic upgrade head` поднимает схему на пустом volume и повторно
отрабатывает без ошибок и без дублей. Данные миграции не сеют:
тестовых пользователей создают тесты через API.
- Обязательно для «3»: первичные и внешние ключи (участник → чат и
пользователь, сообщение → чат и отправитель), уникальный `username`,
уникальная пара чат–участник. Таблица сессий, если сессии в
Postgres, — `auth.md`.
- Лаба 3 — таблица `idempotency_keys` (модель `IdempotencyKey`,
ревизия `7652184b7016`): первичный ключ `(user_id, chat_id, key)`;
составной внешний ключ `(chat_id, user_id) → chat_members` (ключ есть
только у участника — этим же выполнены ссылки на пользователя и чат);
`message_id → messages` `DEFERRABLE INITIALLY DEFERRED` — ключ
вставляется раньше сообщения в той же транзакции; SHA-256 тела
(`CHECK` на 32 байта); `created_at` и индекс по нему (ручная очистка
просроченных). Длину ключа (1–128) и формат держит ещё и `CHECK`.
- С лабы 3 миграция совместима с работающей версией API: при rolling
update старые реплики работают на новой схеме, пока их не заменят
(`balancer.md`, спек `db-migrations`). Поэтому только расширение —
новые таблицы, колонки с `server_default` или `NULL`, индексы
`CONCURRENTLY` вне транзакции. Удаление и переименование — отдельной
миграцией после того, как старой версии не осталось (expand/contract);
если так нельзя — ограничение в `REPORT.md`. Откат кода к прежнему
образу не требует отката схемы (`make rolling_update COMMIT=<прежний>
MIGRATE=0`): прежний код на расширенной схеме работает.
- Пример — ревизия `e656d6bbe1a4`: колонка `messages.instance_id`
(`text NULL`, реплика, которая записала сообщение). Новый код её
пишет и без неё упал бы, старый не знает: вставка перечисляет свои
колонки, чтение выбирает свои (design change `rolling-update`,
решение 7).
- Первой строкой ревизии, которая берёт `ACCESS EXCLUSIVE` на
рабочую таблицу (`ADD COLUMN`, `ALTER`), — `op.execute("SET LOCAL
lock_timeout = '2s'")`: в очереди за ожидающей блокировкой стоят
все новые запросы к таблице, и чужая долгая транзакция остановила
бы запись всех реплик. По сроку миграция падает без изменений,
замена не начинается, повтор проходит.
- `lock_timeout` миграции меньше `[database] statement_timeout_ms`
приложения (5 с) с запасом. Запросы в очереди за миграцией ждут
её отказа, и при равных сроках все они получали 503 вместе с ним:
6 из 6 запросов в полёте (verify change `rolling-update`,
`evidence/rollout/script-failures.md`). С 2 с они дожидаются отказа
миграции и выполняются, цена — задержка до 2 с.
- Модели — `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`, участник → чаты. Индекс
истории обосновывается запросом и `EXPLAIN (ANALYZE, BUFFERS)` на
≥10 000 сообщениях (уровень 4), вывод — в `evidence/`.
- Колонки типизированы `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 (`docker.md`), API ждёт
`service_completed_successfully`; в консоли — `make run_dev` через
`make upgrade`. Не `sh -c "alembic upgrade head && python -m src"`
(сервер перестаёт быть PID 1) и не из lifespan: реплик несколько, и
каждая гонялась бы с остальными за одну схему. Сервис `migrate`
выполняется один раз на `up`, реплики ждут его завершения; повторный
запуск — no-op. При поочерёдной замене — один запуск на новом образе до
первой новой реплики (`scripts/rolling-update.sh`): пересоздаётся
контейнер самого сервиса (`up --no-deps --force-recreate
--exit-code-from migrate migrate`), а не одноразовый `run --rm`. Иначе
в стенде остался бы `migrate` прежнего образа, и `restart.sh` (`start
api` запускает его как зависимость) падал бы на «Can't locate
revision» (`balancer.md`).
- `migrations/env.py` — асинхронный шаблон alembic: URL из
`settings.database.url`, мимо ConfigParser (`%` в пароле ничего не
ломает), журнал — JSON через `src/infra/logger.py`. Синхронный
`env.py` с asyncpg, как в bp_proxies, на SQLAlchemy 2.1 не работает:
флаг `async_fallback` удалён. Ревизии — обычный синхронный `op.*`.
- В ревизиях — литералы, а не константы `src`: применённая ревизия не
меняется вместе с кодом. Autogenerate для новой таблицы рендерит и
`CHECK`; для существующей таблицы новые `CHECK` дописываются руками.
+55
View File
@@ -0,0 +1,55 @@
---
paths:
- "src/core/repos/**"
---
# Слой repo (`src/core/repos/<domain>.py`)
Только доступ к данным. Ни бизнес-логики (проверок доступа, валидации),
ни логов, ни внешних вызовов.
- Модульные `async def`, без классов. Первый параметр —
`db_session: AsyncSession`. Остальные параметры вызывающий передаёт по
имени.
- **Одна атомарная операция на функцию:** максимум один
`db_session.execute(...)`. Нужна вторая выборка — вторая функция,
CTE, подзапрос или `.returning(...)`.
- Запросы — только через SQLAlchemy (Core или ORM) с параметрами; SQL
из f-строк и конкатенации запрещён (уровень 4). `text()` — только с
bind-параметрами.
- Уникальность проверяется в той же функции, что и вставка:
`pg_insert(...).on_conflict_do_nothing(...).returning(...)`. При
конфликте функция возвращает `None`, исключение бросает сервис.
- Наружу отдаются DTO (`.claude/rules/dto.md`), а не ORM-объекты:
`expunge` и `<Entity>FullDTO(**row.to_dict())` либо DTO из выбранных
колонок, а не `select(Model)`.
- Никаких `commit()` / `rollback()`: транзакцией управляет сервис.
- Мутации возвращают осмысленный результат: созданный DTO, `bool`,
`None` при конфликте.
- Keyset-страница: параметры `after: tuple[datetime, UUID] | None` и
`limit`, выборка `limit + 1` элементов, чтобы сервис узнал о следующей
странице. Условие — `tuple_(Model.created_at, Model.id) > tuple_(...)`,
`ORDER BY created_at, id`, `LIMIT`, по индексу
`(chat_id, created_at, id)`. Без `OFFSET` и `count(*)`: уровень 4
запрещает полный scan истории на каждую страницу, план подтверждается
`EXPLAIN (ANALYZE, BUFFERS)` (`migrations.md`).
- Опциональные фильтры и лимиты — условное дополнение выборки
(`if limit is not None: ...`).
- Логов в репозиториях нет: ни `get_logger`, ни `print`.
- Repo ключей идемпотентности (`idempotency.py`, лаба 3) — две функции
(design change `instance-id-idempotency`, решение 3):
- `claim_key` — одно выражение `pg_insert(...).on_conflict_do_update(
set_=..., where=created_at < expired_before).returning(...)`.
`True` — ключ свободен: новый или просроченный, который заменён тем
же выражением; `False` — занят и действует. `DO UPDATE`, а не
`DO NOTHING`: иначе замене просроченного ключа нужны были бы ещё
`DELETE` и повторная вставка, то есть ещё одна гонка. Занятая строка
блокируется до конца транзакции даже при ложном `WHERE`;
- `get_key_result` — хэш тела и сообщение (`JOIN messages`).
Порог `expired_before`, решение «повтор или 409» и commit — в
сервисе. Ключ в исключения и логи не попадает.
- Repo кэша (`chat_cache.py`) — то же правило над Valkey: первый
параметр `cache: Cache`, одна команда на функцию, ключ и формат
значения (JSON ↔ DTO) живут здесь. Ключ включает
`CACHE_KEY_PREFIX` (версию формата) и `cache.namespace` (имя базы).
+166
View File
@@ -0,0 +1,166 @@
---
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 и проверки HAProxy); с лабы 3 `APP_OUT_PORT` публикует только HAProxy |
| Хранилища | Postgres и Valkey — контейнеры compose, приложение ходит на `127.0.0.1:<*_OUT_PORT>` (`settings.md`, «Консоль и docker»); `make run_dev` сам поднимает Postgres, накатывает миграции и поднимает Valkey | всё в compose, зависимости по имени сервиса; миграции — отдельный сервис до старта API (`migrations.md`) |
| Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные и сессии не теряет (`make test-persistence`); кэш Valkey после рестарта пуст |
## Точка входа
`python -m src` → `src/__main__.py` → `early_stop.install()`
(`src/infra/early_stop.py`, до импорта приложения) → `src.main:main()` →
`uvicorn.run("src.main:app", host=..., port=..., reload=...,
timeout_graceful_shutdown=..., timeout_keep_alive=..., log_config=None,
access_log=False)`. Импорты в `src/__main__.py` — внутри `if __name__ ==
"__main__"`: простой импорт модуля обработчики не ставит.
Хост выбирается по режиму, как в bp_proxies. `log_config=None` нужен,
чтобы uvicorn не перетёр JSON-логирование (`logging.md`).
- Worker в процессе всегда один. Масштабирование — числом контейнеров
`api` за HAProxy (`API_REPLICAS`, `balancer.md`), а не `workers=N`:
у каждого процесса свой пул соединений (`infra.md`), и LB должен
видеть каждый процесс отдельной репликой со своим `X-Instance-Id`.
- SIGTERM: uvicorn перестаёт принимать новые соединения и ждёт текущие
запросы до `timeout_graceful_shutdown` (настройка
`[app] graceful_shutdown_seconds`, не больше 8 с). Docker шлёт SIGKILL
через 10 с, в compose — `stop_grace_period`. Shutdown в lifespan
только логирует и закрывает клиенты (`engine.dispose()`,
`cache.aclose()`), долгих операций в нём нет.
Рубрика уровня 4 требует завершения не дольше 10 с.
Сигнал на старте (спек `graceful-shutdown`, «Остановка во время
старта»; design change `fix-known-issues`, решения 3–6):
- **окно 0** — запуск интерпретатора до `install()`, десятки мс:
обработчика нет, PID 1 сигнал теряет. Это ограничение;
- **A** — импорт приложения, `Config`, `Server`, цикл событий (~0,7 с
в контейнере с 1 CPU): ранний обработчик пишет одну запись `info`
«Stopped API before startup» и делает `os._exit(0)` — запросов и
соединений ещё нет;
- **B** — от `capture_signals` uvicorn до «Uvicorn running on»:
uvicorn доводит старт и сразу штатно останавливается («Shutting
down», «Stopped API», «Finished server process»), код 0;
- **C** — работа: как описано выше;
- **D** — после выхода из `capture_signals` uvicorn возвращает ранний
обработчик и повторяет пойманный сигнал; `early_stop.disarm()`
(первая строка lifespan) его уже снял, и процесс выходит с кодом 0.
В консоли с reload ранний обработчик есть только у родителя-reloader
(до `BaseReload.startup()`): Ctrl+C на старте — код 0 и та же запись
вместо traceback. Воркер `src/__main__.py` не выполняет (spawn), его
сигналы — от uvicorn. Проверка — `driver.py stop-at-start`.
С лабы 3 закрытый сокет остановленной реплики HAProxy видит как отказ соединения и
перенаправляет запрос на живую; новые запросы на неё перестают идти
после проваленных проверок (`balancer.md`, цепочка таймаутов). Под
нагрузкой `docker stop` реплики ошибок от её недоступности не даёт —
замер профиля `failover` (`bench.md`).
- Keep-alive: uvicorn держит простаивающее соединение
`[app] keep_alive_seconds` (60 с, `timeout_keep_alive`), а не 5 с по
умолчанию. Тогда простаивающее соединение LB → реплика закрывает LB
раньше реплики (`balancer.md`, цепочка таймаутов). При SIGTERM uvicorn
закрывает простаивающие соединения сразу. Запрос, который LB отправил
в такое соединение в тот же миг, получает 502: под нагрузкой
200 запросов в секунду — одиночный 502 в части фаз `stop` профиля
`failover` (1 из 4 на `459f84c`). Клиенты с новым соединением на
запрос (`tests/resilience.py`) его не встречают. Плановая остановка
(`scripts/rolling-update.sh`) сначала выводит реплику из LB через его
runtime API (`drain`, затем `maint`) и только потом шлёт SIGTERM:
слот выведен, и гонки нет (`balancer.md`, design change
`rolling-update`, решение 3). Остановка без дренажа (`stop-one.sh`,
`docker stop`, профиль `failover`) имитирует отказ, исключение для
одиночного 502 к ней по-прежнему относится.
- Console-режим — один процесс на `127.0.0.1` без LB, для разработки и
скилла `run-mtusi-messenger`. Проверки лабы 3 (≥2 реплики, failover,
гонка через разные реплики) — только на стенде compose через LB.
## Makefile
- Цели skeleton `help`, `check`, `validate`, `test`, `load`,
`test-persistence`, `test-failover` (с лабы 3) не менять:
в следующей лабе `Makefile` придёт новый, и свои цели в него
переносятся слиянием (AGENTS.md, «Переход в следующую лабу»).
- Свои цели — отдельными секциями ниже целей skeleton, в стиле
bp_proxies: переменные наверху (`DC=docker compose`), заголовки
`# -------------------------`, свой `.PHONY` у каждой цели, имена в
snake_case. Apple Container не делать.
- Запуск и общие цели:
- `run_dev: upgrade start_cache` — Postgres из compose и миграции,
Valkey из compose, затем `APP__RUN_MODE=console uv run python -m
src`;
- `run_docker: env_setup` (недостающие `.env` и `config.toml` из
шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`:
хранилища → migrate → `api` × `API_REPLICAS` → haproxy),
к нему `stop`, `down` (volume остаётся), `logs`
(`$(DC) logs -f --no-log-prefix api`: без префикса `api-1 |`
каждая строка — JSON, реплику называет поле `instance_id`);
- `lint` (`ruff format .` + `ruff check --fix .`, дважды),
`env_setup` (шаблоны `.env` и `config.toml`, в новый `.env` —
случайные `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`; существующий
`.env` не меняется, новые строки переносятся руками),
`student_test`.
Оба способа запуска — `run_docker` и `run_dev` — описываются в
`REPORT.md`. Запуска одного контейнера без compose нет: API без
Postgres не обслуживает запросы.
- PostgreSQL и миграции: `start_db` (`$(DC) up -d --wait postgres`),
`stop_db`, `upgrade: start_db` (`uv run alembic upgrade head`),
`revision: upgrade` (autogenerate, сообщение — `read -p`),
`wipe_data` (`$(DC) down -v --remove-orphans` только после ввода
`yes`). Volume — именованный `postgres_data` в compose; `wipe_data`
пересоздаёт и Valkey, то есть чистит кэш.
- Valkey: `start_cache` (`$(DC) up -d --wait valkey`), `stop_cache`.
- Реплики за HAProxy (с лабы 3, `balancer.md`): `replicas` (вернуть
остановленные и выставить число, `API_REPLICAS ?= 2` после `-include
.env`), `instances` (распределение одной сессии по `X-Instance-Id`),
`lb_stats` (слоты HAProxy), `rolling_update` (поочерёдная замена на
новый образ без простоя, `COMMIT`, `MIGRATE`).
- `student_test` передаёт pytest `EXPECT_REPLICAS` (по умолчанию
`API_REPLICAS`): сколько реплик за `BASE_URL` ждут тесты реплик.
Против одного процесса — `EXPECT_REPLICAS=1` (`student-tests.md`).
- `test_isolated: env_setup start_db start_cache` — образ на временной
базе (`student-tests.md`); Valkey общий с рабочим стендом, ключи кэша
разделены именем базы. Один контейнер API без LB: скрипт зовёт `make
student_test EXPECT_REPLICAS=1`. Скрипт запускается `$(PYTHON)`, а не
`uv run`: uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку.
- `failure_checks: env_setup` — проверки отказов на отдельном стенде,
проект compose `<рабочий>-failures` (`student-tests.md`). От
`start_db` не зависит: стенд свой и удаляется вместе с volume.
`FAULT_ARGS` — аргументы pytest (`make failure_checks FAULT_ARGS='-k
valkey'`). Скрипт тоже запускается `$(PYTHON)`. Все команды docker
проекта отказов — только с `-p <рабочий>-failures`: `down -v` без
него удалил бы рабочий 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`: его читают и compose, и приложение в
console, а аргумент make поменял бы одну переменную make. Префикс
`APP_OUT_PORT=8090 make ...` не сработает: `-include .env` перекроет
его, и в recipe (в том числе в `docker compose`) уйдёт значение из
`.env`.
- Поменял `config.toml` и не видишь эффекта: значение перекрыто
окружением или `.env` (приоритет env > .env > toml).
+83
View File
@@ -0,0 +1,83 @@
---
paths:
- "src/core/services/**"
---
# Слой service (`src/core/services/<domain>.py`)
Бизнес-логика, проверки доступа, серверные значения (id, время),
транзакции, вызовы внешних клиентов, логи.
- Класс `<Domain>Service`. `__init__` принимает
`db_session: AsyncSession` и хранит его в `self`; кэш Valkey
(`cache: Cache`), если он нужен домену, — вторым параметром
(`ChatService`, `MessageService`). Методы принимают keyword-only
параметры (`*,`) и вызываются только именованными аргументами.
- Кэш карточки чата (`chat_cache_repo`, спек `chat-cache`):
cache-aside — сначала кэш, при промахе БД и запись в кэш; новый чат
пишется в кэш **после** `commit()`, чтобы откат не оставил в кэше
чата, которого нет в БД. Отсутствующий чат не кэшируется. Кэшировать
можно только неизменяемое: историю, списки и сессии — нет. Отказ
Valkey сервис не обрабатывает: `Cache` уже вернул промах.
- Repo: `from src.core.repos import chat as chat_repo`. Вызов —
`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`.
- Атомарность — транзакция Postgres. Составная операция (чат вместе с
участниками) — все вызовы repo на одном `db_session` и один
`await self.db_session.commit()` в конце. Ошибка до commit —
`rollback()`, и в БД не остаётся ничего. Откат составной операции —
проверка уровня 4.
- Коммитит только сервис, repo не коммитит. Другой сервис создаётся с
тем же `db_session` (и тем же кэшем), чтобы остаться в одной
транзакции.
- Уникальность (`username`) держит ограничение БД, а не проверка
перед вставкой: repo делает `ON CONFLICT DO NOTHING RETURNING`,
`None` сервис превращает в доменное исключение (→ 409). Схема «сначала
SELECT, потом INSERT» ломается на гонке регистрации даже внутри
транзакции (READ COMMITTED), а эта гонка — проверка уровня 4.
- Идемпотентность отправки сообщения (лаба 3, `api-contract.md`) —
в `MessageService.send_message`, в одной транзакции с сообщением:
- порядок: сессия уже проверена зависимостью → членство в чате
(`ChatNotFound` → 404) → ключ. Повтор проходит обе проверки заново;
- ключ вставляется **раньше** сообщения, с `message_id` ещё не
вставленного сообщения: внешний ключ на `messages` отложен до
commit. Так повтор не пишет и не откатывает сообщение (design
change `instance-id-idempotency`, решение 2);
- захват — `idempotency_repo.claim_key` по `(user_id, chat_id, key)`
с порогом `expired_before = now - [idempotency] ttl_seconds`
(часы приложения, как у сессий). Захватили (новый или просроченный
ключ) — вставка сообщения и один `commit()`. Не захватили — ключ
уже есть, в том числе у конкурентного запроса другой реплики:
захват ждёт его commit;
- существующий ключ: `get_key_result`, затем `commit()` — снять
блокировку строки до ответа. Хэш тела совпал — вернуть сохранённое
сообщение (тот же DTO из БД, не новый `uuid4()`/`utcnow()`); не
совпал — доменное `IdempotencyConflict` (→ 409);
- хэш — SHA-256 канонического JSON тела, собранного из аргументов
сервиса (сортированные ключи, значения по умолчанию подставлены):
модульная функция `message_request_hash`;
- ошибка до `commit()` — откат: ни ключа, ни сообщения. Результат
транзиентной ошибки не сохраняется;
- лог: `Created message` или `Replayed message` с `message_id` и
`replayed`, без ключа и текста (`logging.md`).
- Недоступность Postgres (там же хранятся сессии) — доменное
`ServiceUnavailable` (→ 503), не 500 и никогда не пропуск запроса без
аутентификации (`infra.md`). Недоступность Valkey — не ошибка, а
промах кэша.
- KDF пароля — в потоке, не в event loop (`auth.md`).
- Курсор кодирует и разбирает сервис через `src/utils/cursor.py`:
проверяет область (этот чат или этот пользователь) и возвращает
`<Entity>PageDTO` с готовым `next_cursor`. Неверный курсор — доменное
исключение (→ 400).
- Чистые вычисления — модульные функции над классом, без обращения к
хранилищу.
- Read-only методы, которые лишь делегируют в repo, не логируют.
Остальное — по `.claude/rules/logging.md`.
- Константы (лимиты, размер страницы) — `src/utils/constants.py`.
+198
View File
@@ -0,0 +1,198 @@
---
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`, `Database`, `Auth`, `Cache` — Valkey). Экземпляр один —
`settings` на уровне модуля. Импорт везде `from src.config import
settings`. Второй `Settings()` не создавать, поля в рантайме не менять.
- Приоритет (`settings_customise_sources`): окружение процесса → `.env`
→ `config.toml` → дефолты. Отсутствующий файл пропускается. Без
`.env` и `config.toml` `Settings` обязан загрузиться на дефолтах: так
работают импорт `src`, alembic и чистый clone. Стенд (с лабы 2)
запускается через compose и получает значения из `.env`; без Postgres
приложение стартует, но `/health/ready` отвечает 503.
- Все поля живут в секциях, откуда бы ни пришло значение: секцию задаёт
класс `Settings`, а не файл. Вложенные поля в env — через `__`,
регистр не важен: `DATABASE__PASSWORD` попадает в
`settings.database.password` так же, как `[database] password` из
TOML. Переменную без префикса секции (`APP_PORT`, `POSTGRES_PASSWORD`)
приложение не видит: она для compose.
- Имена из контракта и skeleton (`SESSION_TTL_SECONDS`, `APP_HOST`)
буквально не заводятся, если значение читает только приложение. Поле
живёт в секции (`[auth] session_ttl_seconds` в `config.toml`), а
соответствие имени описано в `REPORT.md`. Мост — только для значения,
которое читает ещё контейнер зависимости (раздел «Мосты» ниже).
- `extra="ignore"`: опечатка в ключе молча оставит дефолт. После правки
проверить конкретное поле: `uv run python -c "from src.config import
settings; print(settings.app.port)"`. Полный дамп настроек не печатать:
в нём пароли.
- Подмена через окружение ставится до первого импорта `src`: потом
`settings` уже прочитан.
## Что где хранится
Критерий — кто читает значение, а не секретное ли оно.
| Где | Что | В git |
|---|---|---|
| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL сессии, таймауты, пул и срок записей `[cache]`, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` |
| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*` и `VALKEY_*` (адрес, порты, учётные данные), пароли MinIO / брокера с лаб 4–5; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольные адреса Postgres и Valkey | нет; шаблон `.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, Valkey, MinIO, брокера — нужны ещё и контейнеру зависимости,
а его настраивает только compose из `.env`. Поэтому такой секрет живёт
в `.env` и попадает в приложение мостом. Если продублировать его в
`config.toml`, как `postgres_password` в bp_proxies, получатся два
источника, которые рано или поздно разойдутся.
## Имена в `.env`: параметр приложения — в формате настроек
Если переменная касается самого приложения, в `.env` она пишется в
формате настроек (`SECTION__FIELD`), даже когда её читают ещё compose и
Makefile. Пример — внутренний порт `APP__PORT`: на нём слушает
приложение, его публикует compose, на нём работает healthcheck. Compose
читает `${APP__PORT}` напрямую и передаёт в `environment` под тем же
именем.
Имя без секции — только у того, что приложение не читает:
`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` раскрывать `${...}` не умеет и передаст
строку буквально, поэтому стенд запускается только через compose.
Окружение не перекрывает мост по исходному имени. python-dotenv
подставляет `${VAR}` сначала из самого `.env` и лишь потом из окружения,
поэтому `POSTGRES_OUT_PORT=5545 uv run ...` оставит в `DATABASE__PORT`
значение из файла (проверено на таком же мосте срока сессии, change
`session-auth`). Разовая подмена —
только по имени поля: `DATABASE__PORT=5545`.
## Консоль и docker из одного `.env`
Переключение консоль ↔ docker не требует правки файлов и
комментирования блоков, как в bp_proxies (design change
`postgres-storage`, решение 7):
- консоль: приложение на хосте читает `.env`, мосты
`DATABASE__HOST=127.0.0.1`, `DATABASE__PORT=${POSTGRES_OUT_PORT}` и
учётные данные из `POSTGRES_*`; для Valkey —
`CACHE__HOST=127.0.0.1`, `CACHE__PORT=${VALKEY_OUT_PORT}`,
`CACHE__PASSWORD=${VALKEY_PASSWORD}`;
- docker: `.env` в контейнер не попадает, адрес и порт приходят из
`environment` compose — `DATABASE__HOST: ${POSTGRES_HOST}`,
`DATABASE__PORT: ${POSTGRES_PORT}`, `CACHE__HOST: ${VALKEY_HOST}`,
`CACHE__PORT: ${VALKEY_PORT}` в общем якоре `x-app-env`.
Адреса и порты Postgres и Valkey в compose — только переменные `.env`,
литерал — лишь адрес публикации `127.0.0.1` (`docker.md`).
Существующий `.env` `make env_setup` не меняет. Новая переменная из
`.env.example` (с `membership-cache` — строки `VALKEY_*` и `CACHE__*`)
переносится в рабочий `.env` руками; без `VALKEY_PASSWORD` compose
останавливается с сообщением об этом.
`.env.example` skeleton lab2 предлагает «логические» имена: `APP_HOST`,
`APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`,
`SESSION_STORE`, `CACHE_URL_FILE`; шапка шаблона просит сопоставить их
с реальными в `REPORT.md`. `SESSION_TTL_SECONDS` называют ещё контракт и
рубрика, но ни одна публичная проверка его не читает. Срок сессии читает
только приложение, поэтому это `[auth] session_ttl_seconds` в
`config.toml`, а короткий срок для проверки истечения —
`AUTH__SESSION_TTL_SECONDS=2` в окружении. Мост с контрактным именем
ничего бы не дал: по абзацу выше окружение его не перекрывает. Пароли
Postgres и Valkey приходят мостами из `POSTGRES_PASSWORD` и
`VALKEY_PASSWORD`, а не строкой подключения в файле (`DATABASE_URL_FILE`,
`CACHE_URL_FILE`). `SESSION_STORE` — PostgreSQL, отдельной настройки
нет. Соответствие переменных реальной конфигурации описать в
`REPORT.md` (раздел «Архитектура и решения»).
Skeleton lab3 добавил ещё два имени:
- `API_REPLICAS` читают compose (`deploy.replicas` сервиса `api`) и
Makefile (`make replicas`, `EXPECT_REPLICAS` тестов), приложение —
нет. Поэтому имя остаётся как есть, без секции: строка в
`.env.example`, `${API_REPLICAS:-2}` в compose и `API_REPLICAS ?= 2`
в Makefile — без строки в `.env` действует 2. Разовая подмена —
`make replicas API_REPLICAS=N`;
- `IDEMPOTENCY_TTL_SECONDS` читает только приложение. Это
`[idempotency] ttl_seconds` в `config.toml` (по умолчанию 86400 —
24 ч по контракту), соответствие — в `REPORT.md`, как
`SESSION_TTL_SECONDS`.
`X-Instance-Id` берётся из `[app] instance_id`: по умолчанию пусто, и
тогда валидатор поля подставляет hostname процесса (один раз, при
загрузке `settings`); значение проверяется по `INSTANCE_ID_PATTERN`.
Его не задают ни в `config.toml` (он смонтирован во все реплики; в
`config_example.toml` вместо поля — комментарий), ни в `.env`, ни в
compose (`environment` и `hostname:` сервиса `api`): у реплик одного
сервиса эти источники общие, а значение должно различаться. Разовая
подмена в консоли — `APP__INSTANCE_ID=...`.
В настройки идёт только то, что отличается между установками, либо
секрет. Остальное — константа.
## Новое поле или секция
1. Поле с типом и безопасным дефолтом: `Settings` загружается без
файлов.
Секрет — `""` и проверка при старте там, где он нужен. Единицы —
коротким комментарием (`# секунды`).
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`.
+227
View File
@@ -0,0 +1,227 @@
---
paths:
- "student-tests/**"
---
# Собственные тесты (`student-tests/`)
В bp_proxies тесты запрещены. Здесь они обязательны для уровня 4
(`README.md`), и каждый должен запускаться одной командой. Лаба 2
требует автоматических проверок:
- истечения сессии при коротком `SESSION_TTL_SECONDS`, logout, неверного
пароля;
- недоступности Postgres и Redis/Valkey: ограниченная ошибка или
корректный обход кэша, и никогда запрос как от анонимного;
- гонки регистрации одного `username` (ровно один 201, остальные 409) и
отката составной операции.
Проверки лабы 1 остаются: возможности прежних лаб сохраняются
(`README.md`, «Что должно быть в PR»). Это неверный JSON, чужой чат,
пустое сообщение, дубликат `username`, обход нескольких страниц истории
и гонка: 10 клиентов параллельно отправляют 100 сообщений, и в истории
ровно 100 уникальных. Команду и результат сохранить.
Лаба 3 добавляет (`api-contract.md`, «Балансировка и повторная
отправка»):
- `X-Instance-Id` на успехе, ошибке, health, 404 неизвестного пути и
405 (`test_api_conventions.py`; 500 по HTTP не вызвать — исключение
в `spec_coverage.py`). `contract.py` проверяет заголовок у каждого
ответа, прошедшего `assert_ok` / `assert_error`;
- идемпотентность (`test_idempotency.py`, спек `idempotency`):
- повтор того же тела — тот же 201 и тот же JSON, в истории одно
сообщение;
- другое тело — 409;
- нет ключа, пустой, длиннее 128, недопустимый символ — 400;
- тот же ключ у другого пользователя или в другом чате — новое
сообщение;
- другая запись того же JSON (пробелы, `\u`-экранирование; с лабы 4
— порядок полей и `attachment_ids` по умолчанию) — повтор;
- отозванный токен — 401, новая сессия того же пользователя — повтор;
- посторонний — 404;
- порядок кодов 401 → 400 → 404 → 409;
- невалидный запрос не занимает ключ; сбой записи сообщения, отказ БД
и срок ключа — проверки отказов (`test_failures.py`);
- гонка одного ключа (уровень 4, `test_race.py`): N потоков за
`threading.Barrier` шлют одно тело с одним ключом. Все ответы 201 с
одним `id`, в истории ровно одно сообщение (`test_same_key_at_once`,
любой стенд). Через LB `test_same_key_through_replicas` ещё требует
пару пересекающихся по времени запросов с разными `X-Instance-Id`:
иначе «одновременно через разные реплики» не доказано;
- тесты реплик (нужны ≥ 2 реплики за `BASE_URL`, фикстура
`replicas`):
- `test_load_balancing.py` — одна сессия на разных репликах, запись
видна через другую реплику (спек `load-balancing` вне сверки
покрытия: сценарий — в докстринге);
- `test_idempotency.py::test_replay_on_other_replica` — повтор с
ключом через другую реплику, 409 от разных реплик;
- `test_race.py::test_same_key_through_replicas`.
Сколько реплик за `BASE_URL`, набор узнаёт из `EXPECT_REPLICAS`, а не
угадывает по ответам: иначе сломанный LB давал бы пропуск вместо
падения. `make student_test` берёт его из `API_REPLICAS` (2), `make
test_isolated` и `driver.py student` против своего процесса передают
1. При 1 тесты реплик пропускаются с причиной «one API process» (её
печатает `-rsP` в `addopts`), при ≥ 2 и одном увиденном значении —
падают с числом увиденных (`assert_replicas` в `contract.py`);
- «Одно значение на процесс» (`test_api_conventions.py`) — две
одинаковые серии по 18 запросов: против одного процесса одно
значение, через LB каждое значение повторяется, и вторая серия не
приносит новых. Опирается на round-robin LB.
Проверки отказов реплик (остановка, kill, зависание, rolling update) —
не pytest, а `make test-failover`, профиль `failover` стенда `bench/`
(`make bench_failover`, `bench.md`), команды драйвера `kill-inflight`,
`hang-key` и сценарии `balancer.md`: им нужен стенд с LB и действие над
контейнерами.
## Как писать
- 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`, а также
отсутствие потерь при обходе всех страниц.
- Обычный прогон — `make test_isolated` (`student-tests/run_isolated.py`):
образ из рабочего дерева на временной базе `test_<db>` с Valkey
стенда (ключи кэша разделены именем базы), публичный smoke и весь
набор против отдельного контейнера, затем уборка при любом исходе.
Его вывод — evidence набора против контейнера. Это один контейнер
API без LB (`EXPECT_REPLICAS=1`): тесты, которым нужны ≥2 реплики,
здесь пропускаются. `make student_test` — против любого запущенного
стенда (`BASE_URL`), он оставляет данные в рабочей базе. Против
стенда compose лабы 3 (`BASE_URL` = HAProxy) выполняются и тесты
реплик; их вывод — второй файл evidence
(`evidence/tests/student-test-lb.md`).
- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные или
замороженные Postgres и Valkey, сбой БД посреди транзакции), обычный
прогон не подходит. Это **проверки отказов**: маркер `fault`, модуль
`test_failures.py`, команда `make failure_checks` (change
`failure-checks`). Попадание в кэш по HTTP не отличить от чтения из
БД: такие сценарии `chat-cache` — исключения с evidence.
- Как устроен `make failure_checks` (`student-tests/run_failures.py`):
- тот же `docker-compose.yml` под проектом `<рабочий>-failures` с
override `failures.compose.yml`: свои Postgres и Valkey со своим
volume, их порты не публикуются, healthcheck PostgreSQL проверяет
служебную базу `postgres` (иначе каждая проверка — сессия в базе
приложения и шум счётчика `db-sessions`);
- два API на свободных портах `127.0.0.1`: обычный (`BASE_URL`) и
«тесный» (`FAULT_TIGHT_BASE_URL`: сроки сессии и ключа
идемпотентности 2 с, пул 1, короткие таймауты);
- `pytest -m fault`, затем журнал PostgreSQL стенда: сводка `postgres
log: N lines, crash markers M; "too many clients" X, "administrator
command" Y` после каждого прогона и ненулевой код при признаках
аварийного перезапуска («untracked child process», «terminating any
other active server processes», «reinitializing», «automatic
recovery in progress») — найденные строки печатаются;
- у `postgres` в override — `init: true`: `fill-connections` держит
`psql` в фоне `sh` из `docker compose exec`, после
`clear-connections` они сироты пространства PID. Без init их
наследовал postmaster (PID 1), считал выход с кодом 2 аварией и
перезапускал PostgreSQL посреди набора (design change
`fix-known-issues`, решения 11–12). Правило `docker.md` «сервер —
PID 1» — про образ API;
- затем удаление стенда с volume при любом исходе. Рабочий стенд не
трогается;
- **два прогона одновременно не запускать** (терминал, IDE, агент):
уборка хвоста в начале второго делает `down -v` стенда первого, и
оба падают с конфликтом имён контейнеров. Блокировки нет намеренно.
- Тесты `fault` сами docker не трогают. На стенд они действуют только
через фикстуру `stand` — hook `student-tests/fault_hook.py`, как
`make test-persistence` вызывает `ACTION_SCRIPT`. Маркер `fault`
выбирает тесты, фикстура `stand` действует на стенд: имена разные
намеренно. Действия: `stop` / `start` /
`pause` / `unpause`, `flush-cache`, `cache-hits`, `cache-has-chat`,
`fail-members` (триггер, который роняет вставку участников),
`fail-messages` (триггер, который роняет вставку сообщения с данным
текстом — уже после вставки ключа идемпотентности) и
`clear-fail-*`, `count-chats`, `fill-connections <секунд>` (все слоты
`max_connections` заняты сессиями `psql`, соединения API по TCP
оборваны — пул получает «too many clients», 53300),
`clear-connections` и `db-sessions` (счётчик
`pg_stat_database.sessions`: сколько сессий PostgreSQL приняла, с
сессией самого вызова; тест «Соединения пула не переоткрываются»).
Hook работает только с проектом из
`FAULT_PROJECT` и
отказывается работать с проектом рабочего стенда.
- Тест `fault`, который останавливает или замораживает хранилище,
делает это в `with outage(...)`: в `finally` хранилище возвращается,
и упавшая проверка не ломает следующие. Границы времени — с запасом
0,3–0,5 с, но на порядок ниже «плохого» поведения (6 с повторов
redis-py, 8 с зависшего запроса).
- `addopts` содержит `-m 'not fault'`: `make student_test` и
`make test_isolated` тесты `fault` собирают (их сценарии видит сверка
покрытия), но не выполняют. Запуск `pytest -m fault` без
`make failure_checks` останавливается до первого теста с кодом 2.
- Пароли и токены тестов синтетические, не печатаются и не попадают в
`evidence/` (`evidence/README.md`).
- `tests/` — публичные проверки skeleton: не править, не ослаблять,
свои тесты туда не класть.
- Вывод прогона (команда, дата, commit, результат) — в `evidence/` и
строкой в таблицу доказательств `REPORT.md`.
## Как устроен набор
- **Идентификация — только `Actor.headers()`** (`api_client.py`):
`Authorization: Bearer <token>`. Токен `Actor` получает при входе:
регистрация с паролем, затем `POST /auth/sessions` по Basic. Тесты
передают `actor=`; заголовок руками собирает только
`test_identification.py` (Basic, битый и чужой Bearer, `X-User-Id`).
`Actor.unregistered()` — токен, которого нет на сервере.
- **Отправка сообщения — только `Api.post_message` / `send_message`**:
по умолчанию новый `Idempotency-Key`, `key=None` — без заголовка,
строка — этот ключ. Прямой `api.request("POST", …/messages)` без
ключа получил бы 400 раньше проверки, которую тест хочет увидеть
(404 постороннему, 401 после выхода). Общие циклы по нескольким
путям добавляют заголовок `key_headers()`.
- **Сценарий спека вне `CAPABILITIES`** (`student-tests`) — в
докстринге теста, не маркером: маркер на такой capability сверка
считает ссылкой на неизвестный сценарий.
- **Форма ответа — через `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`) с причиной и способом проверки.
- **Доказательство исключения — в репозитории этой лабы.** Файл
`evidence/….md`, на который ссылается `check` исключения, должен
существовать: `test_exclusion_evidence_exists` (`missing_evidence`)
падает и называет сценарий и путь. `evidence/` в следующую лабу не
переносится, поэтому там сверка красная, пока файлы не сняты заново
на её стенде. Сверка проверяет только наличие файла, а не то, на
каком стенде он снят: скопированные из прошлой лабы файлы `evidence/`
сделают её зелёной без пересъёмки. Поэтому evidence прошлой лабы не
копировать ни целиком, ни по одному файлу — только снимать заново.
Способ проверки называет команду, которая снимает
доказательство: `driver.py --port <LB> cache-check
--require-test-keys` (после `make test_isolated`; без ключей тестовой
базы — код 1, «Временная база» не доказана) →
`evidence/cache/hits.md`,
`driver.py --port <LB> auth-storage` →
`evidence/auth/passwords-and-tokens.md`; `make test-persistence` →
`evidence/replicas/test-persistence.md`; повтор после `docker compose
up -d --force-recreate api` → `evidence/idempotency/replay-after-restart.md`.
В доказательстве — только факты, счётчики и префиксы, без токенов,
паролей и полных хэшей.
Сценарии тестов `fault` сверка считает покрытыми и печатает их число.
- Модуль сверки называется `spec_coverage.py`, а не `coverage.py`:
каталог набора стоит в `pythonpath`, и `coverage.py` затенил бы
пакет `coverage` (pytest-cov, coverage-runner IDE).
- Новые пользователи и чаты — фикстуры `alice`, `bob`, `eve`, `chat` из
`conftest.py`: у каждого теста свои. `eve` не состоит ни в одном чате
фикстур.
+350
View File
@@ -0,0 +1,350 @@
---
name: run-mtusi-messenger
description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API) — на хосте или в Docker. Use when asked to run / start / stop the server or the stand, run the smoke test, `make test`, `make student_test`, `make test_isolated`, `make test-persistence` or `make test-failover`, stop or restore an API replica, show X-Instance-Id distribution, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the containers, or call services directly without HTTP.
---
REST API мессенджера (пользователи, чаты, сообщения) — сервер на
FastAPI/uvicorn, данные в PostgreSQL из compose, карточки чатов
кэшируются в Valkey из compose. Агент управляет им через
`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres,
накатывает миграции и поднимает Valkey (`make upgrade start_cache`),
запускает свой экземпляр сервера в фоне, гоняет сценарий по HTTP,
публичный smoke и собственные тесты, шлёт одиночные запросы и
останавливает сервер. Против стенда compose (`make run_docker`:
HAProxy на `APP_OUT_PORT` перед репликами API) работают те же команды
драйвера, кроме `start`/`stop`, плюс `instances` — распределение одной
сессии по репликам, `kill-inflight` — kill реплики с запросами в
полёте, `idle-conns` — кто закрывает простаивающие соединения LB →
реплика, `hang-key` — повтор ключа после зависшей реплики,
`cache-check` и `auth-storage` — доказательства исключений сверки
покрытия (кэш, хранение паролей и токенов). `stop-at-start` — остановка
контейнеров образа во время старта, без стенда. Только
стандартная библиотека Python 3.9+: `make instances` запускает драйвер
системным `python3` (на macOS — 3.9), поэтому без `datetime.UTC`,
`match` и прочего синтаксиса 3.10+.
Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12,
Python 3.12 из `.python-version`, Docker Desktop 29.8.
**Лаба 3.** Каждый ответ API несёт `X-Instance-Id` (hostname процесса,
в compose — короткий ID контейнера), `POST` сообщения требует
`Idempotency-Key`: повтор с тем же ключом и телом — тот же 201 и то же
сообщение, другое тело — 409, без ключа — 400. Проект compose —
`mtusi-lab3`, своя база. Стенд: HAProxy — единственная точка входа на
`127.0.0.1:APP_OUT_PORT`, за ним `API_REPLICAS` (по умолчанию 2) реплик
`api` без портов на хосте. Консольный `driver.py start` — один процесс
без балансировщика: тесты реплик против него пропускаются.
Аутентификация лабы 2: регистрация с `password`, вход
`POST /api/v1/auth/sessions` по `Authorization: Basic`, дальше —
`Authorization: Bearer <token>`. `X-User-Id` доступа не даёт. Пароль —
Argon2id, около 30 мс на регистрацию и вход в консоли и около 120 мс в
контейнере с лимитом 1 CPU, поэтому `flow` и `student-tests` идут
дольше, чем на лабе 1, а `make test_isolated` — около минуты.
## Setup
```bash
uv sync --all-extras # venv с ruff и dev-группой (pytest, httpx, валидатор)
make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml, существующие не трогает
```
Нужен запущенный Docker: Postgres и Valkey живут в compose. Без
Postgres сервер стартует, но `/health/ready` отвечает 503; без Valkey
всё работает, но мимо кэша (`warning` «Cache is unavailable» в логе).
`driver.py start` сам делает `make upgrade start_cache`. В `.env`,
созданном до `membership-cache`, нет строк Valkey: их переносят из
`.env.example` руками, иначе compose падает с `VALKEY_PASSWORD is
empty`.
## Run (agent path)
```bash
D=.claude/skills/run-mtusi-messenger/driver.py
python3 $D all # start → flow → tests/smoke.py → student-tests → stop
```
По шагам, когда между ними нужно что-то сделать (поправить код,
посмотреть лог, послать свой запрос):
```bash
python3 $D start # make upgrade start_cache, затем фон; ждёт /health/ready до 30 с
python3 $D status # listeners: [pid reloader, pid worker], ready: True
python3 $D flow # ~60 проверок: регистрация с паролем, вход, 409, неверный пароль,
# 401 с WWW-Authenticate, X-User-Id игнорируется, чат, 5 сообщений,
# пагинация limit=2 по курсору, чужой → 404, 400-е, повтор с ключом,
# 409 на другое тело, без ключа → 400, logout; X-Instance-Id везде
python3 $D req POST /api/v1/users --data '{"username":"zoe_demo","display_name":"Зоя","password":"Zoe-password-1"}'
python3 $D req POST /api/v1/auth/sessions --basic zoe_demo:Zoe-password-1
python3 $D req GET /api/v1/users/me --token <token из ответа выше>
python3 $D req POST /api/v1/chats/<chat>/messages --token <token> --data '{"text":"hi"}'
# печатает idempotency-key; повтор той же отправки — тот же запрос с --key <ключ>
python3 $D smoke # публичный tests/smoke.py против этого порта
python3 $D student # make student_test BASE_URL=http://localhost:<port> — ~20 с
python3 $D --port 8080 instances # стенд через LB: X-Instance-Id 12 запросов одной сессии
python3 $D stop
```
| команда | что делает |
|---|---|
| `start` | `make upgrade start_cache`, затем `APP__RUN_MODE=console APP__PORT=<port> uv run python -m src` в своей группе процессов |
| `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого |
| `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat и синтетический токен alice |
| `req METHOD PATH [--token T \| --basic USER:PASS] [--data JSON] [--key K \| --no-key]` | один запрос: статус, `x-request-id`, `x-instance-id`, `www-authenticate` у 401, тело; код 2 при статусе ≥ 400. `POST …/messages` без `--key` получает новый `Idempotency-Key` (он печатается), `--no-key` — без заголовка |
| `smoke` | `tests/smoke.py --base-url http://localhost:<port>` |
| `student` | `make student_test BASE_URL=http://localhost:<port>` (pytest по `student-tests/`); против своего процесса (есть pid-файл) — с `EXPECT_REPLICAS=1`, тесты реплик пропускаются с причиной; код 1, если каталога нет |
| `instances [--count N]` | вход одним синтетическим пользователем, N (12) × `GET /api/v1/users/me` с одним токеном: `X-Instance-Id` каждого ответа и число ответов каждой реплики; токен не печатается. Его зовёт `make instances` |
| `kill-inflight [--threads 8] [--seconds 4] [--after 1.5]` | только стенд с LB (`--port 8080`): потоки входят по Basic, через `--after` с `scripts/stop-one.sh` в режиме kill убивает реплику пробного запроса. Печатает статусы по репликам и ответы LB: оборванные входы — 502 в формате контракта без повтора, начатые после kill — 201 от другой реплики. Код 1, если оборванных нет. Реплика остаётся остановленной — `make replicas` |
| `idle-conns [--threads 20] [--requests 50] [--keep-alive 60] [--lb C]` | только стенд с LB: всплеск `GET /health/live` через LB с keep-alive соединениями, клиенты остаются подключены и молчат; раз в секунду — установленные соединения на порт API внутри каждой реплики (`/proc/net/tcp`) и пул LB (`idle_conn_cur` + `safe_conn_cur`). Код 0, если реплики остались без соединений раньше `--keep-alive` (`[app] keep_alive_seconds`): закрыл LB по своему `timeout http-keep-alive`, а не реплика; иначе код 1 и «closed by the replica». `--lb C` — контейнер LB, если `--port` ведёт на временный LB с другим вариантом конфигурации перед теми же репликами (`evidence/failover/keep-alive.md`) |
| `hang-key` | только стенд с LB: временный триггер `hang_probe_<метка>` задерживает вставку пробного сообщения на 2 с, реплика с этой транзакцией замораживается `docker pause`, повторы того же `Idempotency-Key` через LB до 201 (сначала 504 от LB или 503 по ожиданию блокировки), разморозка; печатает `idle_in_transaction_session_timeout` соединения приложения и строку журнала PostgreSQL о прерывании. Код 0 — повтор получил 201, в чате одно сообщение, обе реплики снова `UP`. Триггер удаляется и реплика размораживается при любом исходе, в том числе по Ctrl+C, SIGTERM и SIGHUP; если удалить не удалось — печатается SQL удаления и код 1 (от SIGKILL уборки нет) |
| `cache-check [--require-test-keys]` | только стенд с LB (`--port 8080`): сценарии `chat-cache` «Чтение из кэша», «Срок записи», «Временная база». Два синтетических пользователя и чат; ключ `messenger:v1:<база>:chat:<id>` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_<db>`) базы. Код 0 — чтений `chats` ≤ 1, hits ≥ +49, промахов ≤ 1, ответы равны ответу на создание, TTL не продлевается, ≥ 2 `X-Instance-Id`. Для «Временной базы» перед ней — `make test_isolated`: без ключей тестовой базы строка `PASS` заканчивается «temporary database: not checked», с `--require-test-keys` — код 1 (доказательство сценария снимается с флагом). На стенде в это время ничего другого не должно идти. Вывод — `evidence/cache/hits.md` |
| `auth-storage` | только стенд с LB: сценарии `users` «Хэш в БД» и `sessions` «Токена нет в хранилище». Пароль P (с `:` и кириллицей) и токен T — только в памяти; через psql — префикс `$argon2id$…` до соли и длина у двух пользователей с одним P, неравенство хэшей, строка `sessions` с `token_hash` = SHA-256(T) (32 байта); `pg_dump --data-only` в память — нет ли T (текстом и в hex) и P. Код 0 — всё так. Вывод — `evidence/auth/passwords-and-tokens.md` |
| `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab3`) с лимитами реплики (1 CPU / 512 МиБ без swap), без сети и `config.toml`; `docker stop --timeout 10` через паузу после `docker run` и сразу по строке «Started server process». По потоку `docker events` и журналу: «сигнал через», время `docker stop`, «выход после сигнала», код выхода, этап (`import` / `server-start` / `running`), кто остановил (`early` / `uvicorn`). Код 0 — каждая попытка с кодом 0 и `docker stop` ≤ 1 с, есть `import`, остановленный ранним обработчиком, и `running`. Проекты compose не трогает, свои контейнеры удаляет по метке `mtusi.stop-at-start`. Вывод — `evidence/failover/stop-at-start.md` |
| `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 (HAProxy + реплики)
Проект `mtusi-lab3`, образ `mtusi-messenger:lab3`, compose-сервисы
`postgres`, `valkey`, `migrate` (одноразовые миграции), `api` ×
`API_REPLICAS` (по умолчанию 2, без портов на хосте) и `haproxy` —
единственный порт API на хосте, `127.0.0.1:APP_OUT_PORT` (8080).
Конфиг LB — `infra/haproxy/haproxy.cfg`, правила — `balancer.md`.
```bash
make run_docker # build + up -d: postgres, valkey → migrate → api × 2 → haproxy
docker compose ps -a --format '{{.Name}} {{.ID}} {{.Ports}} {{.Status}}'
make instances # ≥2 X-Instance-Id одной сессии через LB (шаг 1 защиты)
make lb_stats # слоты HAProxy: адрес, UP/DOWN, запросы, повторы, перенаправления
python3 $D --port 8080 flow # те же проверки через LB
make test && make student_test # smoke и весь набор через LB, тесты реплик выполняются
docker compose logs --no-log-prefix api | tail -5 # JSON всех реплик, реплика — поле instance_id; без -f
docker compose logs --no-log-prefix haproxy | tail # LB: ошибки, повторы (+N), смена состояния реплик
docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern "messenger:*" | head'
# ключи кэша; пароль — из VALKEYCLI_AUTH контейнера
scripts/restart.sh # рестарт LB, всех реплик, Postgres и Valkey: данные и токены остаются, кэш пуст
make test-persistence ACTION_SCRIPT=scripts/restart.sh # то же публичной проверкой
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики, обслужившей тест; ~20 с
STOP_MODE=kill STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# kill вместо graceful; журнал: какой TARGET_INSTANCE_ID и контейнер
TARGET_INSTANCE_ID=<x-instance-id> scripts/stop-one.sh # остановить одну реплику руками
python3 $D --port 8080 kill-inflight # kill реплики во время входов: 502 от LB без повтора
python3 $D --port 8080 idle-conns # простаивающие соединения с репликами закрывает LB (~10 с), а не реплика (60 с)
python3 $D --port 8080 hang-key # зависшая реплика держит ключ: повтор получает 201 после прерывания транзакции
make test_isolated && python3 $D --port 8080 cache-check --require-test-keys # кэш карточки: одно чтение chats на 50, TTL, ключи двух баз
python3 $D --port 8080 auth-storage # Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump
python3 $D stop-at-start # docker stop стартующей реплики: ~0,06 с и код 0 (раньше 10 с и 137)
make bench_failover_quick # отказ каждой реплики под нагрузкой на своём стенде mtusi-bench, ~2 мин
make rolling_update # новый код на реплики без простоя: сборка, миграции один раз, по одной: новая UP → старая drain → stop → rm
make rolling_update COMMIT=<commit> MIGRATE=0 # откат на образ прежнего commit (git archive), схема остаётся новой
make bench_rollout_quick # замена под нагрузкой на своём стенде mtusi-bench с образа прежнего commit, ~2 мин
make bench_scaling_quick # самопроверка серий трека 1: две ячейки, открытая модель, поиск R*, сэмплер, ~5 мин
make replicas # вернуть остановленные реплики (те же ID), ждать healthy
make replicas API_REPLICAS=3 # разово 3 реплики; LB видит новую за 1–3 с без правки конфига
make down # удалить контейнеры, volume с данными остаётся
make wipe_data # удалить и данные: только после ввода yes
```
`make run_docker` сам создаёт недостающие `.env` и `config.toml`
(`env_setup`) и монтирует `config.toml` только для чтения. Готовность —
`healthy` у `haproxy` (`docker compose ps haproxy`): LB отвечает на
`/lb/ready` 200, пока есть хотя бы одна готовая реплика. Между прогонами
`make test-failover` — `make replicas`: иначе следующий прогон увидит
одну реплику и упадёт на `less than two API instances observed`.
Новый код — `make rolling_update`, а не `make down` + `make run_docker`:
скрипт меняет реплики по одной без простоя (`balancer.md`). Он требует
штатного стенда (ровно `API_REPLICAS` реплик, все `UP`, ни одной
остановленной — иначе код 2 и подсказка `make replicas`; слот в ручном
`drain` / `maint` от прерванной замены — код 2 и команда `set server …
state ready`) и runtime API LB: после правки `haproxy.cfg` LB
пересоздают `docker compose up -d --force-recreate --no-deps haproxy`.
Прерванная замена оставляет `API_REPLICAS` готовых реплик, повторный
запуск доводит её. После отката (`COMMIT=… MIGRATE=0`) не запускать
`docker compose up` без сборки: `migrate` прежнего образа упадёт на
новой ревизии; вперёд — `make rolling_update`.
Тест останавливает реплику, ответившую на его первую отправку, а число
запросов до неё постоянно. При round-robin по двум репликам после `make
replicas` он снова выберет ту же. Чтобы остановить другую, очередь LB
сдвигают одним запросом перед тестом: `curl -s -o /dev/null
http://127.0.0.1:8080/health/live`.
## Direct invocation (без HTTP)
Для правок в `src/core/` сервисы вызываются поверх сессии БД, сервер не
нужен, но Postgres с миграциями нужен (`make upgrade`).
`APP__LOG_LEVEL=WARNING` убирает JSON-логи сервисов из вывода:
```bash
make upgrade
APP__LOG_LEVEL=WARNING uv run python - <<'EOF'
import asyncio
import uuid
from src.core.services import SessionService, UserService
from src.infra.db.session import engine, session_factory
async def main():
async with session_factory() as db_session:
username = f"alice_{uuid.uuid4().hex[:6]}"
await UserService(db_session=db_session).register(
username=username,
display_name="Alice",
password="Alice-password-1",
)
sessions = SessionService(db_session=db_session)
issued = await sessions.login(username=username, password="Alice-password-1")
print(await sessions.authenticate(token=issued.token))
await engine.dispose()
asyncio.run(main())
EOF
```
`ChatService` и `MessageService` создаются с кэшем вторым параметром:
`ChatService(db_session=db_session, cache=cache)`, где `cache` — из
`src.infra.cache.instance` (`await cache.aclose()` в конце, нужен
`make start_cache`). Все методы keyword-only, commit делает сам сервис. Ошибки — доменные
исключения из `src.core.exceptions` (базовый `DomainError`), не
HTTP-коды: `authenticate(token="x")` бросает `Unauthenticated`, неверный
пароль в `login` — `InvalidCredentials`. Созданное так остаётся в рабочей
базе.
## Run (human path)
```bash
make run_dev # Postgres + миграции, Valkey, затем 127.0.0.1:8080, reload по src/; Ctrl-C
```
Блокирует терминал — агенту не подходит, используй `driver.py start`.
## Test
```bash
make check # офлайн-структура skeleton
make test_isolated # образ на временной базе: smoke + student-tests, уборка
make failure_checks # проверки отказов (~45 с) на отдельном стенде <рабочий>-failures
make failure_checks FAULT_ARGS='-k valkey' # только часть проверок отказов
python3 $D all # живой сервер + flow + smoke + student-tests
make lint # ruff; затрагивает и driver.py
```
Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none` у
`flow`, smoke — `PASS: lab3 public API scenario...`, student — все
прошли (тесты `fault` — `deselected`), `All checks passed!`; `all`,
`test_isolated` и `failure_checks` — код 0.
Проверки отказов (`student-tests/test_failures.py`, маркер `fault`)
останавливают и замораживают Postgres и Valkey, поэтому идут только на
своём стенде: `make failure_checks` поднимает проект compose
`<рабочий>-failures` со своими хранилищами и volume и удаляет его после
прогона. Рабочий стенд на 8080 при этом не трогается. `pytest -m fault`
напрямую останавливается с кодом 2: нет hook стенда.
## Gotchas
- **На 8080 обычно уже работает стенд `make run_docker` (HAProxy) или
`make run_dev` пользователя.** Поэтому драйвер по умолчанию на 18080.
`driver.py --port 8080 stop` чужой сервер не убьёт (нет pid-файла →
`left running`, код 1) — и не надо: это процесс пользователя.
- **`make student_test` против одного процесса без `EXPECT_REPLICAS=1`
падает на тестах реплик** (`saw 1 X-Instance-Id ... EXPECT_REPLICAS=2`):
по умолчанию набор ждёт `API_REPLICAS` реплик за `BASE_URL`. Против
`make run_dev` — `make student_test EXPECT_REPLICAS=1`; `driver.py
student` и `make test_isolated` передают его сами.
- **Порт отдельной реплики на хосте не опубликован.** Запрос мимо LB —
только изнутри сети: `docker compose exec --index 2 api python -c
"import urllib.request as u; print(u.urlopen('http://127.0.0.1:8080/health/ready').headers['X-Instance-Id'])"`.
`docker compose exec api` без `--index` берёт первую реплику; если она
остановлена `stop-one.sh`, команда падает.
- **Номера слотов HAProxy (`api-1`, `api-2` в `make lb_stats`) не
совпадают с именами контейнеров** (`mtusi-lab3-api-1`): слот получает
адрес из DNS. Связь — по адресу: `docker inspect -f '{{range
.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <id>`.
- **Экземпляр драйвера пишет в ту же рабочую базу**, что `make run_dev` и
`make run_docker`: тестовые пользователи и чаты там остаются. Чистый
прогон — `make test_isolated` (временная база `test_<db>`), чистый
стенд — `make wipe_data`.
- **Правка файла в `src/` перезапускает worker** (`WatchFiles detected
changes ... Reloading...`), задевает и `make run_dev` на 8080. Данные
и сессии в Postgres остаются, прежние токены работают.
- **`lsof` на порт показывает два PID** — reloader и worker делят один
сокет. Убивать по `lsof -t | xargs kill` бессмысленно: reloader
поднимет worker снова. Драйвер шлёт SIGTERM группе процессов; SIGTERM
на обёртку `uv run` тоже гасит всё дерево.
- **`uv run` и `uv sync` без `--all-extras` удаляют ruff из `.venv`**
(`Would uninstall ruff`): ruff в extra `dev`. `make lint` берёт
глобальный ruff, PyCharm — из `.venv`: после `make upgrade` или
`driver.py start` при необходимости `uv sync --all-extras`.
- **`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, а не HAProxy.
- **`make logs` висит** (`logs -f`) — агенту нужен
`docker compose logs --no-log-prefix api` без `-f`. Строки всех
реплик перемешаны, реплику называет поле `instance_id`.
- **`req` без `--token` на защищённом пути даёт 401 `unauthorized`** с
`www-authenticate: Bearer realm="messenger"` — это не сломанный
сервер, а контракт: аутентификация раньше доступа. Токен — из ответа
`req POST /api/v1/auth/sessions --basic USER:PASS` или последняя строка
`flow`.
- **Короткий срок сессии для проверки истечения** — окружением
`AUTH__SESSION_TTL_SECONDS=2 python3 $D start`: окружение важнее
`.env` и `config.toml`. Так же короткий срок ключа идемпотентности —
`IDEMPOTENCY__TTL_SECONDS=2`.
- **`POST` сообщения без ключа — 400 раньше проверки доступа**: посторонний
без `Idempotency-Key` получит 400, а не 404. Порядок 401 → 400 → 404 →
409 — штатный для FastAPI (`api-contract.md`). Ключ в журнал сервера не
пишется: повтор виден по `"replayed": true` и `message_id`.
- **`X-Instance-Id` в консоли — hostname машины**, в контейнере —
короткий ID контейнера (начало `docker compose ps -q api`, по нему
`scripts/stop-one.sh` находит реплику). Другое значение —
`APP__INSTANCE_ID=... python3 $D start`; в `config.toml`, `.env` и
compose его не задавать: у реплик значение должно различаться.
## 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>`.
- **`make upgrade failed` в `start`** — не запущен Docker или занят порт
Postgres `POSTGRES_OUT_PORT` (5433): `docker ps`, `lsof -nP
-iTCP:5433 -sTCP:LISTEN`.
- **Через LB 503 `No API replica is available` без `X-Instance-Id`** —
ответ самого HAProxy: готовых реплик нет (все остановлены или ещё не
прошли 2 проверки `/health/ready`). `make lb_stats`, затем `make
replicas`. Ответ 502/504 от LB — реплика оборвала ответ или не уложилась
в 10 с.
- **`/health/ready` отвечает 503, `/health/live` — 200** — Postgres
недоступен: `docker compose ps postgres`, `make start_db`. Запросы к
API в это время получают 503 `unavailable`, после возврата Postgres
проходят без рестарта сервера. Так отвечает один процесс (консоль).
Через LB реплики без Postgres не проходят проверку `/health/ready`, и
через 2–3 с на всё, включая `/health/live`, отвечает сам HAProxy: 503
`No API replica is available`. После возврата Postgres реплики
возвращаются через 2 проверки.
- **В логе `warning` «Cache is unavailable»** — Valkey остановлен или
завис (рестарт Valkey отказом не считается: клиент один раз
переоткрывает соединение): `docker compose ps valkey`, `make
start_cache`. Ответы при этом те же (из Postgres), `/health/ready` —
200; через `[cache] retry_after_seconds` (5 с) после возврата Valkey —
`info` «Cache is available again».
- **`VALKEY_PASSWORD is empty, copy Valkey lines from .env.example`** у
любой команды compose — `.env` создан до `membership-cache`: перенести
строки `VALKEY_*` и `CACHE__*` из `.env.example`, пароль — `openssl
rand -hex 16`.
File diff suppressed because it is too large Load Diff
+23
View File
@@ -18,3 +18,26 @@ __pycache__
node_modules
evidence
.DS_Store
# свои: Dockerfile копирует только pyproject.toml, uv.lock, src/,
# alembic.ini и migrations/
# паттерн без **/ действует только в корне контекста
**/__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
+63 -12
View File
@@ -1,13 +1,64 @@
# 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, не перезаписывая
# существующий файл, и подставляет случайные POSTGRES_PASSWORD и
# VALKEY_PASSWORD. В существующий .env новые строки переносятся руками.
# .env не коммитить. .env читают compose, Makefile и приложение
# (pydantic-settings); в контейнеры он не попадает.
# Параметры приложения — в формате настроек SECTION__FIELD, без секции —
# только то, что приложение не читает. Комментарии — только отдельными
# строками: make оставляет хвостовой комментарий частью значения.
# Соответствие переменным skeleton (APP_HOST, APP_PORT, APP_ENV,
# SESSION_TTL_SECONDS, DATABASE_URL_FILE, SESSION_STORE, CACHE_URL_FILE,
# с lab3 — API_REPLICAS, IDEMPOTENCY_TTL_SECONDS) — в REPORT.md,
# «Архитектура и решения».
# порт сервиса ([app] port): на нём слушает приложение, его же
# публикует compose, на нём же healthcheck
APP__PORT=8080
# порт на 127.0.0.1 хоста, куда публикуется балансировщик HAProxy —
# единственная точка входа; приложение его не читает
APP_OUT_PORT=8080
# число реплик сервиса api за балансировщиком (имя skeleton); читают
# compose (deploy.replicas) и Makefile, приложение — нет. Разовая
# подмена — make replicas API_REPLICAS=N
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
# PostgreSQL. POSTGRES_USER, POSTGRES_PASSWORD и POSTGRES_DB читает и
# образ postgres; пароль задаётся только при первом создании volume.
# Пустой пароль образ postgres не принимает: make env_setup подставляет
# случайный
POSTGRES_USER=messenger
POSTGRES_PASSWORD=
POSTGRES_DB=messenger
# адрес и порт Postgres внутри сети compose: по ним ходят API и миграции
# в docker, порт слушает сам сервер (PGPORT)
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
# порт на 127.0.0.1 хоста, куда публикуется Postgres: к нему подключается
# приложение в console
POSTGRES_OUT_PORT=5433
# мосты для console: приложение на хосте берёт значения отсюда, в docker
# их задаёт environment compose
DATABASE__HOST=127.0.0.1
DATABASE__PORT=${POSTGRES_OUT_PORT}
DATABASE__USER=${POSTGRES_USER}
DATABASE__PASSWORD=${POSTGRES_PASSWORD}
DATABASE__NAME=${POSTGRES_DB}
# Valkey — кэш карточек чатов. Пароль читают и сервер (--requirepass), и
# приложение; пустой make env_setup заменяет случайным
VALKEY_PASSWORD=
# адрес и порт Valkey внутри сети compose: по ним ходит API в docker,
# порт слушает сам сервер
VALKEY_HOST=valkey
VALKEY_PORT=6379
# порт на 127.0.0.1 хоста, куда публикуется Valkey: к нему подключается
# приложение в console
VALKEY_OUT_PORT=6380
# мосты для console: в docker их задаёт environment compose
CACHE__HOST=127.0.0.1
CACHE__PORT=${VALKEY_OUT_PORT}
CACHE__PASSWORD=${VALKEY_PASSWORD}
# make test_isolated: порт на 127.0.0.1, куда публикуется тестовый
# контейнер API
TEST_APP_PORT=18088
+17
View File
@@ -2,6 +2,7 @@
.env
.env.*
!.env.example
config.toml
secrets/
certs/private/
*.key
@@ -28,5 +29,21 @@ coverage/
.DS_Store
.idea/
.vscode/
graphify-out/
# make bench_quick: самопроверка стенда, не результат
evidence/bench/quick-*/
# make bench_failover_quick: то же для профиля отказа реплик
evidence/failover/quick-*/
# make bench_rollout_quick: то же для профиля поочерёдной замены
evidence/rollout/quick-*/
# сравнения пробных меток
evidence/compare/*quick-*
# make bench_plots на пробных метках
evidence/plots/quick-*/
# блокировка стенда bench/ (один прогон любого профиля)
bench/.bench.lock
# журналы меток (LB, скрипт замены, 5xx серий): небольшие, без секретов,
# на них ссылается REPORT.md; у пробных quick-* каталог исключён выше
!evidence/**/raw/*.log
# 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
+528
View File
@@ -0,0 +1,528 @@
# MTUSI Messenger
REST API мессенджера (пользователи, чаты, история сообщений). Этот код
переносится через все семь лабораторных курса и на каждой обрастает
инфраструктурой. Текущая работа — **лаба 3** (`lab.json`): балансировщик,
≥2 взаимозаменяемые API-реплики, общие сессии, обязательный
`Idempotency-Key` на отправке сообщения и `X-Instance-Id` в ответах
(`README.md`, `COURSE.md`, переход 2 → 3). Код перенесён из лабы 2
(репозиторий `mtusi2026lab2-safronov`, ветка `solution/bvt2301-safronov`,
commit `c6ad34d`): PostgreSQL как источник истины, вход по Basic →
Bearer-сессия, Valkey — кэш карточек чатов, трек 2 лабы 2 (план запроса
и восстановление) в `bench/`. Change `instance-id-idempotency` добавил
`X-Instance-Id` и `Idempotency-Key`, `replicas-lb` — HAProxy перед
двумя репликами API, лимиты, `scripts/stop-one.sh`,
`graceful-failover` — обоснованная и замеренная цепочка таймаутов,
стенд `bench/` на HAProxy + N реплик и профиль `failover`,
`rolling-update` — поочерёдная замена реплик с дренажём через runtime
API HAProxy (`make rolling_update`), expand-миграция и профиль
`rollout`, `scaling-bench` — серии трека 1 «Цена масштабирования»
(`make bench_scaling`: открытая модель, поиск R*, сэмплер, графики,
насыщение пула и PostgreSQL управляемыми опытами) и ответ 503 на отказ
PostgreSQL «too many clients», `scaling-improvement` — пул PostgreSQL
10 + 0 без переполнения (улучшение трека 1: профиль `SERIES=db4`,
«до/после» с A/A, засчитано с оговоркой), `profile-resources` — CPU и
память каждого компонента по окнам профилей `failover` и `rollout`
(сэмплер `scan`, `bench/resources.py`, метки `resources`; добавлен после
закрытия лабы, код приложения не трогает), `fix-known-issues` —
исправление пяти записей `KNOWN_ISSUES.md` перед переносом: ранний
обработчик SIGTERM до импорта приложения (`src/infra/early_stop.py`,
`docker stop` стартующей реплики — 0,06 с вместо 10 с и SIGKILL),
поток событий Docker в профиле `failover`, `init: true` у PostgreSQL
стенда отказов и проверка его журнала, `swapouts_delta` при нуле,
доказательства исключений сверки покрытия на стенде лабы 3 (команды
драйвера `cache-check`, `auth-storage`; сверка падает на ссылке на
отсутствующий файл), `strict-id-validation` — по рецензии PR:
изменённый клиентом курсор — 400 вместо 500 (поля курсора проверяются
по отдельности, незнакомые игнорируются — формат открыт для совместимых
правок при поочерёдной замене), UUID на входе (`chat_id`, `member_ids`)
— только запись 8-4-4-4-12 (`UuidIn`). Лаба 3 закрыта: все девять
changes лабы 3 (девятый — `strict-id-validation`), как и changes
перехода на lab2, — в `openspec/changes/archive/`, спеки
синхронизированы, активных changes нет; `KNOWN_ISSUES.md` без открытых
записей, `REPORT.md` заполнен, чистый clone проверен на итоговом коде
`ebf080a` (`evidence/tests/clean-clone-final.md`). Дальше —
перенос в лабу 4 (раздел «Переход в следующую лабу»). Рабочий план лабы
(`PLAN.md`) удалён, его решения — в `REPORT.md` и design архивных
changes; последняя версия — `git show 063eedb:PLAN.md`. Стек:
Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
(JSON в stdout), redis-py (клиент Valkey).
Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные
проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные
тесты и `REPORT.md` пишем мы.
## Обязательные правила
- Контракт и skeleton не менять: `contracts/`, `tests/`, `scripts/`
(кроме своих `scripts/restart.sh` и `scripts/stop-one.sh` по образцам
`restart.example.sh` и `stop-one.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` / `test-failover` в `Makefile`. Если публичный тест упал, чиним
приложение, а не тест. Если в контракте противоречие — сказать
пользователю (это вопрос преподавателю), не выбирать трактовку самому.
Ответ преподавателя записать в «Согласования с преподавателем».
- Git не трогать без явной просьбы: никаких commit, push, checkout,
reset, stash. Смотреть можно (`git status`, `git diff`, `git log`).
Замер или evidence для отчёта снимается с закоммиченного кода, но
коммит — только после подтверждения пользователя: показать изменения,
предложить сообщение, ждать ок (`.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. Basic — только
на `POST /auth/sessions`, остальное — Bearer; `X-User-Id` доступа не
даёт; пароли — только через password KDF (`auth.md`). Valkey — на
«4», кэш карточки чата: источник истины — PostgreSQL, отказ Valkey —
обход кэша, а не ошибка (`infra.md`). Всё это сохраняется в лабе 3.
- Лаба 3: ≥2 взаимозаменяемые реплики `api` за HAProxy — единственной
публичной точкой входа; порты реплик наружу не публикуются, sticky
session нет. В памяти процесса нет ничего, от чего зависит
корректность: сессии, данные и ключи идемпотентности — в Postgres,
Valkey — общий кэш неизменяемых карточек. В каждом ответе API —
`X-Instance-Id`. `POST` сообщения требует `Idempotency-Key`; ключ и
сообщение пишутся в одной транзакции (`api-contract.md`,
`service-layer.md`). Миграции — однократно, отдельным сервисом, не
репликами, и только расширяют схему: старые реплики работают на новой
(`migrations.md`). Новый код доходит до реплик без простоя через `make
rolling_update`. Стенд и отказы — `balancer.md`. В каждом процессе
uvicorn по-прежнему один worker: масштабирование — числом реплик.
- `.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 лабы 1, п. 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 — `Idempotency-Key` и `X-Instance-Id`; разделы lab4+ — на будущее |
| `contracts/examples.json`, `infrastructure.json` | примеры тел (проверяет `make validate`); роли инфраструктуры лабы: api ×2+ без локального состояния, postgres, load_balancer; Redis/Valkey — необязательно; внутренние порты реплик в обход LB не публикуются |
| `lab.json` | номер лабы (3); по нему `tests/client.py` выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность) |
| `tests/smoke.py`, `tests/client.py` | публичный сквозной сценарий `make test`; что он проверяет и чего нет — `tests/README.md` |
| `tests/resilience.py` | `make test-persistence`: данные и прежний токен после restart hook; `make test-failover`: ≥2 реплики, запись во время остановки одной, повтор с тем же ключом, без дублей |
| `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 |
| `scripts/stop-one.example.sh` | образец failover hook; свой — `scripts/stop-one.sh`: остановить одну API-реплику по `TARGET_INSTANCE_ID` и оставить её остановленной |
| `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`; «логические» имена skeleton (lab2 и новые lab3 `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS`) перечислены в шапке, их соответствие — в `REPORT.md` (`settings.md`) |
| `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/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе) и другие клиенты |
| `auth.md` | `src/**/session.py`, сервис пользователей, `dependencies.py`, `errors.py`, идентификация в `student-tests/`: пароль и KDF, разбор Basic, токен, срок и отзыв сессии |
| `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`, `scripts/restart.sh`, `infra/**`: мультистейдж, non-root, пины, healthcheck, стенд compose, volumes, restart hook |
| `balancer.md` | `docker-compose.yml`, `infra/haproxy/**`, `scripts/stop-one.sh`, `scripts/rolling-update.sh`: реплики за HAProxy, проверки и цепочка таймаутов, повторы LB, failover hook, поочерёдная замена, лимиты и пулы (с лабы 3) |
| `student-tests.md` | `student-tests/**`: обязательные проверки уровня 4, black-box по HTTP, особый стенд |
| `bench.md` | `bench/**`: нагрузочный стенд на Postgres (проект compose `mtusi-bench`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний |
| `migrations.md` | `migrations/**`, `alembic.ini`, `src/infra/db/models/**`: схема до запросов, ограничения, индексы, повторный запуск миграций |
- **`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`.
- Стенд — проект compose `mtusi-lab3` со своей базой. После `make
rolling_update` реплики называются `api-N` с растущим номером
(compose нумерует новые контейнеры сервиса по возрастанию): штатные
цели с ними работают, `make down` + `make run_docker` снова дают
`api-1`, `api-2` (`balancer.md`).
- `make instances` и публичные проверки skeleton запускаются системным
`python3` (3.9+ на macOS), без uv: драйвер скилла — только stdlib и
синтаксис 3.9.
- 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 test-failover ACTION_SCRIPT=scripts/stop-one.sh` | отказ одной API-реплики через LB: 15 с записи параллельно hook, восстановление записи ≤10 с, без дублей (`tests/README.md`). `STOP_MODE=kill` — без graceful, `STOP_ONE_LOG=<файл>` — какой `TARGET_INSTANCE_ID` и контейнер остановлен. Между прогонами — `make replicas` |
| `make run_dev` | `make upgrade` (Postgres из compose и миграции) и `make start_cache`, затем `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` со случайными `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает (новые строки шаблона переносятся руками) |
| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres, valkey → migrate → api × `API_REPLICAS` (2) → haproxy на `127.0.0.1:APP_OUT_PORT`; `config.toml`, `infra/valkey/valkey.conf` и `infra/haproxy/haproxy.cfg` монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — `make rolling_update` |
| `make stop` / `make down` | остановить / удалить контейнеры compose; volume с данными остаётся |
| `make logs` | журнал всех реплик API, каждая строка — JSON (`--no-log-prefix`), реплика — поле `instance_id` |
| `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число, ждать `healthy` (`balancer.md`) |
| `make instances` | вход одним синтетическим пользователем, 12 × `GET /users/me` через LB: `X-Instance-Id` каждого ответа и итог по репликам |
| `make lb_stats` | слоты HAProxy: адрес, состояние проверки (`DRAIN`, `MAINT` при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) |
| `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`) без слотов LB в ручном `drain` / `maint` (иначе код 2 и команда `set server … state ready`); сбой и Ctrl+C — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ (после него `docker compose up` без сборки не запускать: `migrate` прежнего образа упадёт на новой ревизии) |
| `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` |
| `make start_cache` / `make stop_cache` | Valkey стенда: `up -d --wait valkey` / `stop valkey`; volume нет, кэш после рестарта пуст |
| `make upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) |
| `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` |
| `make wipe_data` | `down -v` — удалить данные стенда (и кэш); только после ввода `yes` |
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе (`student-tests.md`) |
| `make student_test [BASE_URL=...] [EXPECT_REPLICAS=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`) — сколько реплик за `BASE_URL`, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом |
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~60 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (HAProxy и одна реплика API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда; k6 ходит через LB); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) |
| `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт |
| `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` |
| `make bench_restore_quick` | то же на 1k / 5k / 10k (~1,5 мин), метка `quick-restore-<время>`, в git не идёт; сценарий защиты трека 2 |
| `make bench_failover [FAILOVER_LABEL=...]` | уровень 4, отказ реплик под нагрузкой (~6 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` с HAProxy и двумя репликами с лимитами рабочего стенда, k6 — 100 записей с ключом и 100 чтений в секунду; каждая реплика в режимах `stop`, `kill`, `pause` с возвратом. Посекундная шкала, время исключения из LB и восстановления, сверка записей после повтора с тем же ключом, CPU и память каждого компонента по окнам фазы (сэмплер `scan`, `resources.csv`, `samples.csv`; CPU на запрос — только до действия) — `evidence/failover/<метка>/`. Перед запуском — проверка хоста (`bench.md`): питание, давление памяти, `Swapouts` без роста; сумма лимитов на пике больше CPU ВМ — код 2 |
| `make bench_failover_quick` | то же короче, режимы `stop` и `kill` (~2 мин), с ресурсами, метка `quick-failover-<время>`, в git не идёт |
| `make bench_rollout [ROLLOUT_LABEL=...]` | уровень 4, поочерёдная замена под нагрузкой (~3 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` как у `bench_failover`, реплики на образе прежнего commit (`Profile.rollout_from`, `git archive`), та же нагрузка; посреди неё `scripts/rolling-update.sh` меняет их на образ текущего checkout. Посекундная шкала с ответами старых и новых реплик, шаги по репликам, контейнеры, образы и ревизия до и после, сверка записей, CPU и память каждой старой и новой реплики, миграции и остальных компонентов по окнам до / подготовка / замена / после (CPU на запрос — до и после) — `evidence/rollout/<метка>/`. Перед запуском — проверка хоста (`bench.md`) |
| `make bench_rollout_quick` | то же с короткими окнами (~2 мин), с ресурсами, метка `quick-rollout-<время>`, в git не идёт |
| `make bench_scaling SERIES=a\|b\|pool\|ab\|db\|db4 [SCALING_LABEL=...] [RESUME=1]` | уровень 5, трек 1: серия на стенде `mtusi-bench` (метка `scaling-<серия>` по умолчанию). `a` — бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1 (~50 мин); `b` — 1…6 реплик по 1 CPU (~100 мин); `pool` — 4 реплики при `max_connections` 100 и 50 (~35 мин); `ab` — 1 × 1 и 6 × 1 для «до/после» и A/A (~35 мин); `db` — 1, 2, 4 реплики при PostgreSQL 0,5 CPU и контроль 4 × 1 при 2 CPU (~50 мин); `db4` — только 4 × 1 при 0,5 и 2 CPU (~25 мин, «до/после» `scaling-improvement`); `db_quick` — самопроверка серии `db` (~4 мин, метка `quick-*`). Ячейка — конфигурация × повтор (3), свежий стенд; открытая модель 70/20/10, фиксированные 250 и 500/с и поиск R* по SLO; сэмплер контейнеров, ВМ, LB и PostgreSQL. `RESUME=1` — продолжить прерванную метку на том же commit. Перед запуском — проверка хоста, рабочий стенд — `make stop`; метку коммитить до следующей серии (`bench.md`) |
| `make bench_scaling_quick` | самопроверка серий: 1 × 1 и 2 × 1 при `max_connections` 50, короткие окна (~4 мин), метка `quick-scaling-<время>`, в git не идёт |
| `make bench_plots LABELS="..." [PLOTS=scaling]` | графики SVG и сводка серий трека 1 из меток: R* от числа реплик, p95 от интенсивности, CPU по компонентам, эффективность и точка насыщения — `evidence/plots/<PLOTS>/` |
| `make bench_ab BEFORE=... AFTER=... REAPPLY=<commit> [SERIES=...]` | «до» и «после» одного изменения подряд (два прогона `bench`): `bench` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, `bench` для `AFTER`; с `SERIES` — серия трека 1 вместо матрицы (`make bench_scaling`). Нужно чистое рабочее дерево; сама делает два коммита |
| `make bench_compare BEFORE=... AFTER=... [AA=...] [CHANGE=...]` | дельта двух меток `make bench` по ячейкам матрицы, у серий трека 1 — по общим конфигурациям (R*, задержки на фиксированных уровнях, CPU на запрос) и таблица PostgreSQL на R* и первой нарушившей ступени (CPU на запрос, новые сессии, соединения); `CHANGE` — change в шапке сравнения серий (по умолчанию `scaling-bench`); метки с разной методикой не сравнивает (в том числе метку без LB с меткой стенда на LB и серию с матрицей); с `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`, `session`, `idempotency` и т.д.).
```
src/
__main__.py # python -m src: early_stop.install() до импорта приложения → main.main()
main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run
config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [idempotency] ttl_seconds
api/
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py)
schemas/<domain>.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12
dependencies.py # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация
errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; у 500 — X-Request-Id и X-Instance-Id
middlewares/ # X-Request-Id, X-Instance-Id и access-лог
core/
repos/<domain>.py # атомарный доступ к хранилищу, модульные функции
repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py
infra/
early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped API before startup» и выход 0; disarm() — первая строка lifespan
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи
password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username
db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping
db/session.py # глобалы engine и session_factory процесса API
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit
cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
cache/instance.py # глобал cache процесса API
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-курсор: кодирование и разбор; поля проверяются по отдельности, незнакомые игнорируются, смена формата — новая CURSOR_VERSION
student-tests/ # black-box тесты по HTTP (уровень 4): make student_test
conftest.py # BASE_URL, EXPECT_REPLICAS и фикстура replicas (пропуск против одного процесса), проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook
api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message — с Idempotency-Key
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, X-Instance-Id, assert_error, assert_errors (статусы всех вариантов запроса разом), assert_replicas
test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py)
test_load_balancing.py # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия; missing_evidence — файл evidence по ссылке исключения должен быть в репозитории
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db> (stdlib)
run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), уборка (stdlib)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггеры сбоя участников и сообщений, заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions (stdlib)
failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, LB), healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster)
bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling
run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json
scaling.py # серии трека 1 без docker: лестница и автомат поиска R*, разбор итога k6 и строк сэмплера, агрегаты окна, вердикт SLO и брака генератора, признаки узкого места (THRESHOLDS), предельный CPU на запрос, сводка серии; --selftest
plots.py # make bench_plots: SVG на stdlib (R* от числа реплик, p95 от интенсивности, CPU по компонентам) и сводка с точкой насыщения; render_series — графики в каталоге метки
sampler.sh # сэмплер (только в контейнере mtusi-bench-sampler на образе PostgreSQL, --cgroupns host): режим list (серии) — cpu.stat, память и PSI заданных контейнеров, /proc/stat и PSI ВМ, статистика HAProxy, psql \watch по pg_stat_activity / database / wal / io; режим scan (failover, rollout) — обход cgroup всех контейнеров и /proc/stat, без сети, psql и LB
resources.py # ресурсы профилей failover и rollout без docker: интервалы контейнеров (сброс при новой cgroup, заморозка, новые контейнеры с момента запуска), окна, CPU / троттлинг / память по компонентам и ВМ, CPU на запрос в установившихся окнах, resources.csv / samples.csv, разделы summary.md; --selftest
failover.py # профиль failover без docker: строки k6 о запросах, статистика и журнал HAProxy, события Docker, посекундная шкала, величины фазы, summary.md
rollout.py # профиль rollout без docker: строки скрипта замены, события контейнеров проекта, состояния слотов LB (UP, drain, maint, ready), шаги по репликам, шкала со старыми и новыми ответами, окна до / во время / после, summary.md
bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain
bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей)
k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы
compare.py # make bench_compare: дельта двух меток (ячейки матрицы или общие конфигурации серий), уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB и серии против матрицы
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд, с --series — серии трека 1
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose
infra/ # конфигурации сервисов стенда; README.md — skeleton
valkey/valkey.conf # лимит памяти и LRU, persistence выключен
haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене)
scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey
scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG
scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/
Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck
docker-compose.yml # проект mtusi-lab3: postgres, valkey, migrate, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volume postgres_data, лимиты у всех, окружение по сервисам
.dockerignore
config_example.toml, .env.example
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
evidence/auth/ # passwords-and-tokens.md — driver.py auth-storage на стенде лабы 3: Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump (исключения сверки покрытия)
evidence/cache/ # hits.md — make test_isolated + driver.py cache-check на стенде лабы 3: одно чтение chats на 50 через LB, TTL, ключи двух баз (исключения сверки покрытия)
evidence/tests/ # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md; profile-resources-checks.md — проверки сэмплера, быстрые профили, сторож, хост и сравнение меток resources с baseline; fix-known-issues-checks.md — сверка событий поток/буфер, красный и зелёный failure_checks, консоль, сверка ссылок исключений, регрессия; strict-id-validation-checks.md — красный и зелёный прогоны курсора и UUID на входе, пересмотр проверки курсора, замена реплик, клон во временном проекте
evidence/idempotency/ # повтор, 409, гонка, таблица ключей, X-Instance-Id
evidence/replicas/ # стенд с LB: порты, лимиты и их цена для Argon2id, окружение, распределение, ответы LB (нет реплик, зависшая, без PostgreSQL), test-persistence, чистый clone на нестандартных портах
evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh; замер обнаружения, keep-alive, зависшая реплика и ключ; stop-at-start.md — docker stop стартующей реплики «до/после» раннего обработчика и ветка сбоя rolling-update.sh
evidence/failover/<метка>/ # результаты make bench_failover: паспорт, phases.csv, посекундная timeline.csv, summary.md, итоги k6 и журнал LB по фазам; с change profile-resources (метка resources и новые) — resources.csv (фаза × окно × компонент) и samples.csv (посекундно от действия)
evidence/rollout/ # совместимость старого образа с новой схемой, make rolling_update и жизненный цикл стенда после замены, отказы скрипта (Ctrl+C, слоты, lock_timeout миграции)
evidence/rollout/<метка>/ # результаты make bench_rollout: паспорт с контейнерами, образами и ревизией до и после, rollout.csv, replicas.csv, timeline.csv, summary.md, строки скрипта, журнал LB; с change profile-resources (метка resources и новые) — resources.csv (окно × компонент) и samples.csv (посекундно от начала замены)
evidence/bench/<метка>/ # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6
evidence/bench/scaling-*/ # серии трека 1 (a, b, pool, A/A scaling-aa, db — насыщение PostgreSQL; db4 — «до/после» пула без переполнения: scaling-db-aa*, -before*, -nooverflow*, окончательные — с суффиксом 2): паспорт с планом, бюджетом и лимитами по конфигурациям, runs.csv (строка на ступень), searches.csv (строка на ячейку), samples.csv (посекундно в окнах), summary.md, p95-by-rate.svg, cpu-by-component.svg, итоги k6 ступеней и журналы 5xx
evidence/plots/scaling/ # make bench_plots по сериям a и b: графики SVG и summary.md (R*, эффективность, точка насыщения, цена запроса, память)
evidence/plots/scaling-db/ # make bench_plots по серии db: R* по лимитам PostgreSQL и раздел «Насыщение PostgreSQL»
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
```
`evidence/` перенесён без содержимого лабы 2 (оно осталось в
репозитории `mtusi2026lab2-safronov`). Каталоги выше появляются заново
по мере changes.
## Архитектура в двух словах
- Поток однонаправленный. Роутер (зависимости, модели API) → сервис
(логика, проверки доступа, id и время, логи) → repo (одна атомарная
операция над хранилищем, отдаёт DTO) → PostgreSQL через
`AsyncSession` (`src/infra/db/`). Подробности — в правилах слоёв.
- Отличия от 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` в сервисах и ручках
не используется.
- Конкурентность: все ручки и зависимости — `async def`, один event
loop, один worker в процессе, процессов — `API_REPLICAS` за HAProxy.
Атомарность и защиту от гонок, в том числе между репликами, дают
транзакции и ограничения Postgres (уникальность, `ON CONFLICT`),
транзакцией управляет сервис. Повтор `POST` сообщения через другую
реплику находит тот же ключ идемпотентности в Postgres. На лабе 1 ту же роль играло отсутствие `await`
внутри repo-функции над `MemoryStore`. KDF пароля — в потоке, чтобы
не останавливать event loop.
- 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-сессия; Valkey на «4» | `infra/db/`, `migrations/`, repo на `AsyncSession`; `password` при регистрации (KDF); `get_current_user` на Bearer; `SESSION_TTL_SECONDS`; кэш карточки чата — `infra/cache/`, `repos/chat_cache.py` |
| 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/`, `alembic.ini`,
`Dockerfile`, `docker-compose.yml`, `infra/valkey/`,
`infra/haproxy/` (без `infra/README.md` skeleton), свои
`scripts/restart.sh`, `scripts/stop-one.sh` и
`scripts/rolling-update.sh` (без примеров и проверок skeleton в
`scripts/`), `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/` (граф собирается заново).
- Доказательства исключений сверки покрытия снять заново на стенде новой
лабы, иначе `make student_test` красный (`test_exclusion_evidence_exists`
называет сценарий и путь): `make test_isolated`, затем `driver.py
--port <LB> cache-check --require-test-keys` →
`evidence/cache/hits.md`; `driver.py --port
<LB> auth-storage` → `evidence/auth/passwords-and-tokens.md`; `make
test-persistence ACTION_SCRIPT=scripts/restart.sh` →
`evidence/replicas/test-persistence.md` (или путь, который назовёт
исключение); повтор отправки с ключом после `docker compose up -d
--force-recreate api` → `evidence/idempotency/replay-after-restart.md`
(`student-tests.md`). Файлы `evidence/` лабы 3 в новую лабу не
копировать, даже эти четыре: сверка проверяет только наличие файла и
с копией останется зелёной без пересъёмки.
- Сначала прочитать переходы 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).
+56
View File
@@ -0,0 +1,56 @@
# Образ API мессенджера (лаба 2): сервер и миграции. Правила —
# .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
# сервис migrate compose запускает этот же образ: alembic upgrade head
COPY alembic.ini ./
COPY migrations ./migrations
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.
Открытых записей нет: записи лабы 3 исправлены change `fix-known-issues`.
+340
View File
@@ -28,3 +28,343 @@ test-persistence:
test-failover:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2)
$(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
# -------------------------
# Приложение на хосте (свои цели; цели skeleton выше не менять)
# -------------------------
# Postgres из compose и миграции, Valkey из compose, затем сервис на
# хосте: 127.0.0.1:APP__PORT, reload по src/
.PHONY: run_dev
run_dev: upgrade start_cache
APP__RUN_MODE=console uv run python -m src
# шаблоны копируются только если файла ещё нет: локальные значения
# не затираются. В новый .env подставляются случайные пароли Postgres и
# Valkey: в шаблоне они пустые, общего пароля стенда в git нет
.PHONY: env_setup
env_setup:
@test -f .env || sed \
-e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \
-e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \
.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
# число реплик api за HAProxy — то же, что deploy.replicas в compose
API_REPLICAS ?= 2
# сколько реплик за BASE_URL ждут тесты реплик student-tests: против
# стенда с LB — API_REPLICAS, против одного процесса — 1 (их пропуск)
EXPECT_REPLICAS ?= $(API_REPLICAS)
DC=docker compose
# стенд: postgres, valkey -> migrate -> api × API_REPLICAS -> haproxy
# (единственный порт API на хосте — у haproxy). env_setup создаёт
# недостающие .env и config.toml из шаблонов: без config.toml compose не
# запустится (bind с create_host_path: false), без паролей — тоже.
# Реплики, чей образ изменился, пересоздаются все разом (простой); новый
# код без простоя — make rolling_update
.PHONY: run_docker
run_docker: env_setup
DOCKER_BUILDKIT=1 $(DC) build
$(DC) up -d
.PHONY: stop
stop:
$(DC) stop
# контейнеры удаляются, volume с данными остаётся (удаление — wipe_data)
.PHONY: down
down:
$(DC) down
# журнал всех реплик api без префикса "api-1 |": каждая строка — JSON,
# реплику называет поле instance_id
.PHONY: logs
logs:
$(DC) logs -f --no-log-prefix api
# -------------------------
# PostgreSQL и миграции
# -------------------------
# Postgres стенда; --wait ждёт его healthcheck
.PHONY: start_db
start_db: env_setup
$(DC) up -d --wait postgres
.PHONY: stop_db
stop_db:
$(DC) stop postgres
# миграции с хоста: 127.0.0.1:POSTGRES_OUT_PORT из .env
.PHONY: upgrade
upgrade: start_db
uv run alembic upgrade head
# новая ревизия autogenerate; база сначала доводится до head, иначе
# autogenerate сравнит модели не с той схемой
.PHONY: revision
revision: upgrade
@read -p "Сообщение миграции (англ., прошедшее время): " msg; \
uv run alembic revision --autogenerate -m "$$msg"
# удалить контейнеры стенда и volume с данными: только после ввода yes
.PHONY: wipe_data
wipe_data:
@read -p "Удалить все данные стенда (volume Postgres)? Введите yes: " answer; \
if [ "$$answer" = "yes" ]; then \
$(DC) down -v --remove-orphans; \
else \
echo "cancelled, nothing removed"; exit 1; \
fi
# -------------------------
# Valkey (кэш карточек чатов)
# -------------------------
# Valkey стенда; --wait ждёт его healthcheck. Volume нет: кэш после
# рестарта пуст, данные — в PostgreSQL
.PHONY: start_cache
start_cache: env_setup
$(DC) up -d --wait valkey
.PHONY: stop_cache
stop_cache:
$(DC) stop valkey
# -------------------------
# Реплики за балансировщиком (HAProxy)
# -------------------------
# вернуть остановленные реплики (scripts/stop-one.sh) и выставить их
# число: остановленные контейнеры запускаются с теми же ID, недостающие
# создаются, лишние удаляются; ждёт healthcheck реплик. Разовая подмена —
# make replicas API_REPLICAS=3, следующий make run_docker вернёт число
# из .env
.PHONY: replicas
replicas:
$(DC) up -d --no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api
# поочерёдная замена реплик на новый образ без простоя
# (scripts/rolling-update.sh): сборка, миграции один раз, затем по одной —
# новая реплика UP в LB, старая выводится из LB (drain), дорабатывает
# запросы, останавливается и удаляется. COMMIT=<commit> — образ из файлов
# commit (git archive, рабочее дерево не трогается), MIGRATE=0 — без
# миграций (откат на прежний образ: схема только расширялась). Нужен
# штатный стенд: API_REPLICAS реплик, все UP (make replicas)
COMMIT ?=
MIGRATE ?= 1
.PHONY: rolling_update
rolling_update:
API_REPLICAS=$(API_REPLICAS) ROLLOUT_COMMIT="$(COMMIT)" ROLLOUT_MIGRATE=$(MIGRATE) scripts/rolling-update.sh
# распределение запросов одной сессии через LB: вход одним синтетическим
# пользователем, серия GET /users/me с одним токеном, X-Instance-Id каждого
# ответа и число ответов каждой реплики
.PHONY: instances
instances:
$(PYTHON) .claude/skills/run-mtusi-messenger/driver.py --port $(APP_OUT_PORT) instances
# состояние реплик глазами HAProxy: занятые слоты, адрес, статус проверки,
# соединения, запросы, ошибки соединения, повторы и перенаправления. CSV
# статистики читается изнутри контейнера LB: порт 8404 наружу не
# опубликован, curl в образе нет, bash есть
LB_STATS_FIELDS = svname addr status check_status scur stot econ wretr wredis hrsp_5xx
.PHONY: lb_stats
lb_stats:
@$(DC) exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/8404 && printf "GET /stats;csv HTTP/1.0\r\n\r\n" >&3 && cat <&3' \
| awk -F, -v fields="$(LB_STATS_FIELDS)" ' \
/^# pxname/ { sub(/^# /, ""); for (i = 1; i <= NF; i++) col[$$i] = i; \
n = split(fields, f, " "); for (j = 1; j <= n; j++) printf "%s\t", f[j]; print ""; next } \
$$1 != "api" { next } \
$$2 != "BACKEND" && $$(col["addr"]) == "" && $$(col["status"]) == "MAINT (resolution)" { free++; next } \
{ for (j = 1; j <= n; j++) { v = $$(col[f[j]]); printf "%s\t", (v == "" ? "-" : v) }; print "" } \
END { printf "free slots: %d\n", free }' \
| column -t -s "$$(printf '\t')"
# -------------------------
# Load benchmark
# -------------------------
BENCH_LABEL ?= baseline
# macOS не засыпает на время замера (сон ставит ВМ Docker на паузу посреди
# прогона): -u будит из DarkWake полностью, -i и -s не дают уснуть до
# конца; на других ОС caffeinate нет, и префикс пустой
KEEP_AWAKE := $(shell command -v caffeinate >/dev/null 2>&1 && echo caffeinate -isu)
# полная матрица на своём проекте compose mtusi-bench (API, PostgreSQL,
# Valkey, без портов хоста), с фоновыми чатами разного размера, вариантами
# плана и пробами записи, ~35 мин; метка не должна существовать;
# результаты и планы запроса истории — evidence/bench/$(BENCH_LABEL)/,
# ход — строки в терминале и progress.json
.PHONY: bench
bench:
$(KEEP_AWAKE) uv run python bench/run.py --profile full --label $(BENCH_LABEL)
# самопроверка стенда на малых размерах, ~3 мин; результат в git не идёт
.PHONY: bench_quick
bench_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile quick --label quick-$(shell date -u +%Y%m%dT%H%M%SZ)
RESTORE_LABEL ?= restore
# трек 2: backup под записью, восстановление в новое хранилище, сверка БД и
# через HTTP, кэш до и после FLUSHALL — на 10k / 100k / 500k с фоновыми
# чатами, без матрицы прогонов, ~20 мин; результат —
# evidence/bench/$(RESTORE_LABEL)/
.PHONY: bench_restore
bench_restore:
$(KEEP_AWAKE) uv run python bench/run.py --profile restore --label $(RESTORE_LABEL)
# то же на малых размерах (самопроверка, сценарий защиты), ~1,5 мин; в git
# не идёт
.PHONY: bench_restore_quick
bench_restore_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile restore_quick --label quick-restore-$(shell date -u +%Y%m%dT%H%M%SZ)
FAILOVER_LABEL ?= baseline
# уровень 4: отказ реплик под нагрузкой на стенде mtusi-bench (HAProxy, две
# реплики с лимитами рабочего стенда): 100 записей с ключом и 100 чтений в
# секунду, каждая реплика в режимах stop, kill и pause с возвратом,
# посекундная шкала, время обнаружения и восстановления, сверка записей,
# CPU и память по компонентам и окнам (сэмплер); ~6 мин; результат —
# evidence/failover/$(FAILOVER_LABEL)/
.PHONY: bench_failover
bench_failover:
$(KEEP_AWAKE) uv run python bench/run.py --profile failover --label $(FAILOVER_LABEL)
# то же короче, режимы stop и kill (самопроверка), с CPU и памятью по
# компонентам и окнам (сэмплер), ~2 мин; в git не идёт
.PHONY: bench_failover_quick
bench_failover_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile failover_quick --label quick-failover-$(shell date -u +%Y%m%dT%H%M%SZ)
ROLLOUT_LABEL ?= baseline
# уровень 4: поочерёдная замена реплик под нагрузкой на стенде mtusi-bench
# (HAProxy, две реплики с лимитами рабочего стенда): реплики стартуют на
# образе прежнего commit (Profile.rollout_from), посреди 100 записей с
# ключом и 100 чтений в секунду scripts/rolling-update.sh меняет их на
# образ текущего checkout; посекундная шкала, шаги по репликам, сверка
# записей, CPU и память по компонентам и окнам (сэмплер); ~3 мин;
# результат — evidence/rollout/$(ROLLOUT_LABEL)/
.PHONY: bench_rollout
bench_rollout:
$(KEEP_AWAKE) uv run python bench/run.py --profile rollout --label $(ROLLOUT_LABEL)
# то же с короткими окнами (самопроверка), с CPU и памятью по компонентам и
# окнам (сэмплер), ~2 мин; в git не идёт
.PHONY: bench_rollout_quick
bench_rollout_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile rollout_quick --label quick-rollout-$(shell date -u +%Y%m%dT%H%M%SZ)
SCALING_LABEL ?= scaling-$(SERIES)
# уровень 5, трек 1 «Цена масштабирования»: серия на стенде mtusi-bench —
# SERIES=a (бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1, ~50 мин), b (1…6 реплик по
# 1 CPU, ~100 мин), pool (4 реплики при max_connections 100 и 50, ~35 мин),
# ab (1 × 1 и 6 × 1 для «до/после» и A/A, ~35 мин), db (1, 2, 4 реплики при
# узком лимите CPU PostgreSQL и контроль 4 × 1 при 2 CPU, ~50 мин), db4
# (из серии db только 4 × 1 при 0,5 и 2 CPU, ~25 мин), db_quick
# (самопроверка серии db, ~5 мин, метка quick-*); каждая ячейка — свежий
# стенд, открытая модель, поиск R* по SLO; результат —
# evidence/bench/$(SCALING_LABEL)/. RESUME=1 — продолжить прерванную метку
# на том же commit
.PHONY: bench_scaling
bench_scaling:
@if [ -z "$(SERIES)" ]; then \
echo "SERIES is required: make bench_scaling SERIES=a|b|pool|ab|db|db4|quick|db_quick [SCALING_LABEL=...] [RESUME=1]"; \
exit 2; \
fi
$(KEEP_AWAKE) uv run python bench/run.py --profile scaling_$(SERIES) --label $(SCALING_LABEL) $(if $(RESUME),--resume)
# самопроверка серий: две ячейки (1 × 1 и 2 × 1 при max_connections 50),
# короткие окна, ~5 мин; в git не идёт
.PHONY: bench_scaling_quick
bench_scaling_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile scaling_quick --label quick-scaling-$(shell date -u +%Y%m%dT%H%M%SZ)
PLOTS ?= scaling
# графики и сводка серий трека 1 из меток LABELS (через пробел):
# R* от числа реплик, p95 от интенсивности, CPU по компонентам, точка
# насыщения; результат — evidence/plots/$(PLOTS)/, пересоздаётся
.PHONY: bench_plots
bench_plots:
uv run python bench/plots.py --labels "$(LABELS)" --out "$(PLOTS)"
# дельта двух меток по ячейкам матрицы или, у серий трека 1, по общим
# конфигурациям: BEFORE и AFTER обязательны, AA — метка того же кода, что
# BEFORE, для уровня шума; CHANGE — change, к которому относится сравнение
# серий (шапка таблицы, по умолчанию scaling-bench);
# результат — evidence/compare/$(BEFORE)__$(AFTER).md
.PHONY: bench_compare
bench_compare:
uv run python bench/compare.py --before "$(BEFORE)" --after "$(AFTER)" --aa "$(AA)" $(if $(CHANGE),--change "$(CHANGE)")
# «до» и «после» подряд в одной сессии, два прогона bench: bench для
# BEFORE, commit доказательств, git revert commit REAPPLY (возврат
# откаченного изменения), затем bench для AFTER. С SERIES=<серия> вместо
# полной матрицы — серия трека 1 (make bench_scaling). Сам делает два
# коммита; рабочее дерево должно быть чистым
.PHONY: bench_ab
bench_ab:
$(KEEP_AWAKE) uv run python bench/ab.py --before "$(BEFORE)" --after "$(AFTER)" --reapply "$(REAPPLY)" $(if $(SERIES),--series "$(SERIES)")
# -------------------------
# Common targets
# -------------------------
# собственные black-box тесты против запущенного сервера (BASE_URL).
# EXPECT_REPLICAS — сколько реплик за BASE_URL: по умолчанию API_REPLICAS
# (стенд с LB); против одного процесса — EXPECT_REPLICAS=1, и тесты
# реплик пропускаются с причиной
.PHONY: student_test
student_test:
BASE_URL=$(BASE_URL) EXPECT_REPLICAS=$(EXPECT_REPLICAS) uv run pytest
# образ на временной базе test_<POSTGRES_DB>: сборка, миграции, отдельный
# контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test,
# затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу для разбора.
# Valkey общий с рабочим стендом: ключи кэша разделены именем базы.
# $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку
.PHONY: test_isolated
test_isolated: env_setup start_db start_cache
$(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,)
# проверки отказов (pytest -m fault) на отдельном стенде: свой проект
# compose <рабочий>-failures со своими Postgres и Valkey, обычный и
# «тесный» API, hook student-tests/fault_hook.py; стенд и его volume
# удаляются при любом исходе, рабочий стенд не затрагивается.
# FAULT_ARGS — дополнительные аргументы pytest, например -k "Valkey"
.PHONY: failure_checks
failure_checks: env_setup
$(PYTHON) student-tests/run_failures.py $(FAULT_ARGS)
.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"
+2554 -14
View File
File diff suppressed because it is too large Load Diff
+13
View File
@@ -0,0 +1,13 @@
# Миграции alembic, правила — .claude/rules/migrations.md.
# URL подключения migrations/env.py берёт из настроек приложения (секция
# [database]), поэтому sqlalchemy.url здесь нет. Секций logging тоже нет:
# журнал идёт через src/infra/logger.py в JSON, как у сервиса.
[alembic]
script_location = %(here)s/migrations
# имя ревизии: YYYY_MM_DD_HHMM-<rev>_<slug>.py
file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
truncate_slug_length = 40
# импорт src из корня репозитория и из /app в образе
prepend_sys_path = .
path_separator = os
+125
View File
@@ -0,0 +1,125 @@
"""Два прогона подряд: «до» и «после» одного изменения, в одной сессии.
Запуск — `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=<commit>
[SERIES=<серия>]`; с `SERIES` вместо полной матрицы снимается серия трека 1
(`make bench_scaling`).
В рабочем дереве должен лежать код «до», а изменение — быть
закоммиченным и откаченным отдельным commit; `REAPPLY` — commit отката.
Скрипт снимает стенд «до», коммитит его результаты, возвращает изменение
(`git revert` commit отката) и снимает «после». Между прогонами на хосте
нет другой работы. Только stdlib. Методика — design change
`perf-bottleneck-fix`, решения 7 и 9; без разложения внутри процесса —
design change `bench-postgres`, решение 8.
"""
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
path = ROOT / "evidence" / "bench" / name
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 run_step(args: argparse.Namespace, label: str) -> list[str]:
"""Прогон стенда: полная матрица или серия трека 1 (`--series`,
решение 11 design change `scaling-bench`)."""
if args.series:
return [
"make",
"bench_scaling",
f"SERIES={args.series}",
f"SCALING_LABEL={label}",
]
return ["make", "bench", f"BENCH_LABEL={label}"]
def steps(args: argparse.Namespace) -> list[list[str]]:
return [
run_step(args, args.before),
["git", "add", f"evidence/bench/{args.before}"],
["git", "commit", "-m", f"docs: add {args.before} bench evidence"],
["git", "revert", "--no-edit", args.reapply],
run_step(args, 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")
# серия трека 1 вместо полной матрицы: a, b, pool, ab, quick
parser.add_argument("--series", default="")
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:]))
+90
View File
@@ -0,0 +1,90 @@
# Override стенда make bench (bench/run.py): тот же docker-compose.yml под
# проектом mtusi-bench, со своими volume, сетью и лимитами. Пины, healthcheck
# хранилищ, valkey.conf, haproxy.cfg и миграции — из основного файла.
# Подстановки — из bench/bench.env, а не из .env рабочего стенда; пароли и
# BENCH_* передаёт run.py (поля Profile), без них стенд не поднимается.
# Решения 1, 2, 5 design change bench-postgres и 6 design change
# graceful-failover; что не меняется между метками — .claude/rules/bench.md.
# Стенд — HAProxy перед BENCH_API_REPLICAS репликами api, как рабочий; k6
# ходит через LB по имени сервиса haproxy. Лимиты — в форме
# deploy.resources.limits, как в основном файле: compose не принимает
# cpus/mem_limit рядом с deploy-лимитами.
services:
postgres:
container_name: mtusi-bench-postgres
# упавший контейнер не поднимается сам: прогон помечается stand_down
restart: "no"
# auto_explain загружен, но выключен (log_min_duration = -1): run.py
# включает его только на этапе плана, между прогонами. max_connections
# — конфигурация серии трека 1 (граница пула), у прочих профилей 100,
# как у образа (решение 1 design change scaling-bench)
command:
- postgres
- -c
- shared_preload_libraries=auto_explain
- -c
- max_connections=${BENCH_DB_MAX_CONNECTIONS:?run make bench}
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_DB_CPUS:?run make bench}
memory: ${BENCH_DB_MEMORY:?run make bench}
memswap_limit: ${BENCH_DB_MEMORY:?run make bench}
valkey:
container_name: mtusi-bench-valkey
restart: "no"
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_CACHE_CPUS:?run make bench}
memory: ${BENCH_CACHE_MEMORY:?run make bench}
memswap_limit: ${BENCH_CACHE_MEMORY:?run make bench}
migrate:
image: mtusi-messenger:bench
# без config.toml рабочего стенда: настройки — окружение и дефолты
volumes: !reset []
api:
# реплики без постоянного имени (оно мешало бы масштабированию):
# оркестратор находит их через docker compose ps, k6 ходит через LB
image: mtusi-messenger:bench
restart: "no"
volumes: !reset []
# healthcheck образа — лишний CPU внутри лимита API; готовность реплик
# проверяет HAProxy (раз в секунду /health/ready)
healthcheck:
disable: true
environment:
# размер 500k с наполнением идёт ~25 мин; на медленном хосте срок
# 3600 с по умолчанию мог бы истечь посреди прогона и дать 401
AUTH__SESSION_TTL_SECONDS: ${BENCH_SESSION_TTL_SECONDS:?run make bench}
deploy:
replicas: ${BENCH_API_REPLICAS:?run make bench}
resources:
limits:
# на каждую реплику
cpus: ${BENCH_APP_CPUS:?run make bench}
memory: ${BENCH_APP_MEMORY:?run make bench}
memswap_limit: ${BENCH_APP_MEMORY:?run make bench}
haproxy:
# один экземпляр: имя нужно оркестратору (статистика, журнал)
container_name: mtusi-bench-haproxy
restart: "no"
# порт рабочего стенда не занимает: k6 в сети стенда
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_LB_CPUS:?run make bench}
memory: ${BENCH_LB_MEMORY:?run make bench}
memswap_limit: ${BENCH_LB_MEMORY:?run make bench}
networks:
default:
# k6 подключается к сети стенда по имени (docker run --network)
name: mtusi-bench
+11
View File
@@ -0,0 +1,11 @@
# Подстановки compose для стенда make bench вместо .env рабочего стенда
# (docker compose --env-file bench/bench.env). Только несекретные имена и
# порты внутри сети стенда: пароли генерирует bench/run.py на каждый
# прогон, лимиты и срок сессии приходят из Profile (BENCH_*).
POSTGRES_USER=bench
POSTGRES_DB=bench
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
VALKEY_HOST=valkey
VALKEY_PORT=6379
APP__PORT=8080
+792
View File
@@ -0,0 +1,792 @@
"""Сравнение двух меток стенда: дельта по ячейкам матрицы.
Запуск — `make bench_compare BEFORE=<метка> AFTER=<метка> [AA=<метка>]`.
Читает `runs.csv` и `meta.json` из `evidence/bench/<метка>/`, пишет
`evidence/compare/<до>__<после>.md`. Только stdlib, docker и приложение
не нужны. Метки с разной методикой не сравниваются (с лабы 2 методика
включает и хранилища: design change `bench-postgres`, решение 8). Правило
«эффект или шум» — 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
import scaling
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 flatten(prefix: str, value: Any, into: dict[str, Any]) -> None:
"""Вложенные словари паспорта → плоские ключи `a.b.c`."""
if isinstance(value, dict):
for key, inner in value.items():
flatten(f"{prefix}.{key}", inner, into)
else:
into[prefix] = value
def is_series(label: Label) -> bool:
"""Метка серии трека 1 (design change `scaling-bench`, решение 11)."""
return bool(label.meta.get("profile", {}).get("series"))
def methodology(
label: Label,
configs: set[str] | None = None,
) -> dict[str, Any]:
"""Параметры, которые у сравнимых меток обязаны совпадать.
Профиль, лимиты всех контейнеров стенда, образ генератора, образы и
настройки PostgreSQL и Valkey, окружение приложения (решение 8 design
change `bench-postgres`). У Valkey настройки — `maxmemory*` из
`valkey.conf`: правку конфигурации образ не покажет. У серий трека 1
имя, серия и состав конфигураций к методике не относятся, лимиты — по
общим конфигурациям `configs` (решение 11 design change
`scaling-bench`).
"""
meta = label.meta
stand = meta.get("stand", {})
flat: dict[str, Any] = {}
profile = dict(meta.get("profile", {}))
limits = meta.get("limits", {})
if configs is not None:
for key in ("name", "series", "configs"):
profile.pop(key, None)
limits = {key: limits[key] for key in configs if key in limits}
flatten("profile", profile, flat)
flatten("limits", limits, flat)
for name, value in (
("generator.image", meta.get("generator", {}).get("image")),
("stand.postgres.image", stand.get("postgres", {}).get("image")),
("stand.valkey.image", stand.get("valkey", {}).get("image")),
):
if value is not None:
flat[name] = value
flatten(
"stand.postgres.settings",
stand.get("postgres", {}).get("settings", {}),
flat,
)
for key, value in stand.get("valkey", {}).items():
if key.startswith("maxmemory"):
flat[f"stand.valkey.{key}"] = value
flatten("stand.app_env", stand.get("app_env", {}), flat)
return flat
def check_methodology(
first: Label,
second: Label,
configs: set[str] | None = None,
) -> list[str]:
"""Отказ при различии; возвращает параметры, записанные в одной метке.
`configs` — общие конфигурации серий трека 1; None — матрица."""
if is_series(first) != is_series(second):
series = first if is_series(first) else second
raise CompareError(
"different methodology: track 1 series "
f"{series.name} and matrix "
f"{(second if series is first else first).name}",
)
a, b = methodology(first, configs), methodology(second, configs)
# с change graceful-failover в пути запроса стоит HAProxy, и паспорт
# пишет число реплик; метка без него снята мимо LB — другая методика
# (решение 6 design change graceful-failover), а не «параметр
# записан только в одной метке»
without_lb = [
label.name
for label, flat in ((first, a), (second, b))
if configs is None and "limits.api_replicas" not in flat
]
if len(without_lb) == 1:
raise CompareError(
f"label {without_lb[0]} was measured without the load balancer "
"(before change graceful-failover): different methodology",
)
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:
# занятый swap — не помеха; помеха — выгрузка за прогон (решение 12
# design change scaling-bench)
state = meta.get("host_state", {})
start = state.get("start", {})
before = start.get("swapouts")
after = state.get("end", {}).get("swapouts")
swapped = (
f"выгрузок в swap за прогон {after - before}"
if before is not None and after is not None
else f"swap {start.get('swap_used_mib')} МиБ"
)
return f"{swapped}, {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())
def machine(meta: dict[str, Any]) -> str:
found, docker = meta.get("host", {}), meta.get("docker", {})
cores = (
f" ({found['performance_cores']} P + "
f"{found['efficiency_cores']} E)"
if found.get("performance_cores") is not None
else ""
)
return (
f"{found.get('machine')}{cores}, ВМ {docker.get('vm_cpus')} vCPU "
f"/ {docker.get('vm_memory_gib')} GiB, Docker "
f"{docker.get('server')}"
)
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("Машина", machine),
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 на сообщение до | после | "
"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')} | {a.get('db_bytes_per_message')} | "
f"{b.get('db_bytes_per_message')} |",
)
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"
@dataclass(frozen=True)
class SeriesRow:
"""Общая конфигурация двух меток серий: R* повторов и числа сводки."""
config: str
before: dict[str, Any]
after: dict[str, Any]
@property
def delta(self) -> float:
return (self.after["r_star"] / self.before["r_star"] - 1) * 100
@property
def overlap(self) -> bool:
a, b = self.before["r_stars"], self.after["r_stars"]
return min(a) <= max(b) and min(b) <= max(a)
def series_stats(label: Label) -> dict[str, dict[str, Any]]:
"""Сводка конфигураций серии (`scaling.config_stats`) с R* полных
ячеек; ячейки с браком генератора в сравнение не входят."""
directory = BENCH_DIR / label.name
searches = scaling.read_csv(directory / "searches.csv")
return {
c["config"]: c
for c in scaling.config_stats(label.meta, label.runs, searches)
}
def series_notes(label: Label, stats: dict[str, dict[str, Any]]) -> list[str]:
"""Что мешает считать метку серии чистым замером: прочее — как у
матрицы, но нарушения SLO на ступенях поиска — норма, а не пометка."""
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", [])]
bound = [cell for c in stats.values() for cell in c["generator_bound"]]
if bound:
found.append(
"брак генератора, ячейки не сравниваются: " + ", ".join(bound),
)
marked = sorted(
{
run["cell"]
for run in label.runs
if {"oom", "app_down", "stand_down", "host_swap"}
& set((run.get("flags") or "").split())
},
)
if marked:
found.append(
"ячейки с отказом стенда или выгрузкой: " + ", ".join(marked),
)
return [f"`{label.name}`: {text}" for text in found]
def series_noise(aa: Label, before: Label) -> tuple[float, str]:
"""Шум A/A серий: наибольшее по общим конфигурациям |Δ медианы R*|."""
first, second = series_stats(aa), series_stats(before)
common = [
SeriesRow(config=key, before=first[key], after=second[key])
for key in first
if key in second
and first[key]["r_stars"]
and second[key]["r_stars"]
and first[key]["r_star"]
]
if not common:
raise CompareError(
f"labels {aa.name} and {before.name} have no common configs",
)
worst = max(common, key=lambda row: abs(row.delta))
return abs(worst.delta), worst.config
def render_series(
before: Label,
after: Label,
aa: Label | None,
command: str,
change: str = "scaling-bench",
) -> str:
"""Сравнение меток серий трека 1 по общим конфигурациям (решение 11
design change `scaling-bench`); раздел PostgreSQL на R* и первой
нарушившей ступени — решение 7 change `scaling-improvement`."""
first, second = series_stats(before), series_stats(after)
common = [key for key in first if key in second]
if not common:
raise CompareError("labels have no common track 1 configs")
unverified = check_methodology(before, after, set(common))
labels = [before, after]
floor = None
if aa is not None:
aa_stats = series_stats(aa)
unverified += check_methodology(
aa,
before,
{key for key in aa_stats if key in first},
)
floor = series_noise(aa, before)
labels.append(aa)
remarks = list(unverified)
remarks += series_notes(before, first) + series_notes(after, second)
if aa is not None:
remarks += series_notes(aa, series_stats(aa))
remarks += [
f"конфигурация {key} есть только в `{label.name}`: не сравнивается"
for key, label in [
*((k, before) for k in first if k not in second),
*((k, after) for k in second if k not in first),
]
]
rows = [
SeriesRow(config=key, before=first[key], after=second[key])
for key in common
if first[key]["r_stars"]
and second[key]["r_stars"]
and first[key]["r_star"]
]
lines = [
f"# Сравнение серий: `{before.name}` → `{after.name}`",
"",
f"- Команда: `{command}`",
f"- Спек: `load-benchmark` (сравнение меток), change `{change}`; "
"даты, commit и хост — таблица «Метки»",
"- Метки серий трека 1 сравниваются по общим конфигурациям. R* — "
"медиана повторов, в скобках min–max; Δ R* — отношение медиан "
"минус единица. Ячейки с браком генератора не входят.",
"- Задержки — медианы по повторам на фиксированных уровнях, «до → "
"после»; CPU на запрос — CPU реплик на успешный запрос на втором "
"фиксированном уровне; CPU PostgreSQL — на ступени R*.",
]
if floor is None:
lines.append(
"- Уровень шума не задан (`AA`): вывод говорит только, "
"пересекаются ли разбросы повторов.",
)
else:
lines += [
f"- Уровень шума — наибольшее по общим конфигурациям изменение "
f"медианы R* между `{aa.name if aa else ''}` и `{before.name}`: "
f"{floor[0]:.1f}% ({floor[1]}). Он имеет смысл, только если код "
"приложения в этих метках одинаков; это проверяется по git.",
"- «Эффект» — разбросы повторов не пересекаются и изменение "
"медианы больше уровня шума; иначе «в пределах шума».",
]
lines += [
"",
"## Метки",
"",
*passport_rows(labels),
"",
"## Замечания",
"",
]
lines += [f"- {text}" for text in dict.fromkeys(remarks)] or ["Нет."]
fixed = before.meta["profile"].get("fixed_rps") or []
second_level = (
fixed[1] if len(fixed) > 1 else (fixed[0] if fixed else None)
)
lines += [
"",
"## R* по общим конфигурациям",
"",
"| Конфигурация | R* до | R* после | Δ R* | Вывод | "
+ " | ".join(f"p95 / p99 на {lvl}, мс" for lvl in fixed)
+ f" | CPU на запрос на {second_level}, мкс | CPU PostgreSQL на R*, "
"ядер |",
"|---|---|---|---|---|" + "---|" * len(fixed) + "---|---|",
]
for row in rows:
a, b = row.before, row.after
if floor is None:
verdict = (
"разбросы пересекаются"
if row.overlap
else "разбросы не пересекаются"
)
elif not row.overlap and abs(row.delta) > floor[0]:
verdict = "эффект"
else:
verdict = "в пределах шума"
latency = []
for lvl in fixed:
fa, fb = a["fixed"].get(lvl) or {}, b["fixed"].get(lvl) or {}
latency.append(
f"{scaling.fmt(fa.get('p95'), 1)} → "
f"{scaling.fmt(fb.get('p95'), 1)} / "
f"{scaling.fmt(fa.get('p99'), 1)} → "
f"{scaling.fmt(fb.get('p99'), 1)}",
)
us_a = (a["fixed"].get(second_level) or {}).get("app_us")
us_b = (b["fixed"].get(second_level) or {}).get("app_us")
lines.append(
f"| {row.config} | {scaling.spread(a['r_stars'])} | "
f"{scaling.spread(b['r_stars'])} | {row.delta:+.1f}% | "
f"{verdict} | "
+ " | ".join(latency)
+ f" | {scaling.fmt(us_a, 0)} → {scaling.fmt(us_b, 0)} | "
f"{scaling.fmt(a['db_cpu_r'], 2)} → {scaling.fmt(b['db_cpu_r'], 2)} |",
)
if rows:
deltas = [row.delta for row in rows]
lines += [
"",
f"Δ R* по конфигурациям: от {min(deltas):+.1f}% до "
f"{max(deltas):+.1f}%.",
]
lines += pg_section(first, second, common)
return "\n".join(lines) + "\n"
def pg_section(
first: dict[str, dict[str, Any]],
second: dict[str, dict[str, Any]],
common: list[str],
) -> list[str]:
"""PostgreSQL на ступени R* и первой нарушившей выше неё: медианы по
повторам, «до → после»."""
def pair(a: Any, b: Any) -> str:
return f"{scaling.fmt(a)} → {scaling.fmt(b)}"
lines = [
"",
"## PostgreSQL на R* и первой нарушившей ступени",
"",
"Медианы по завершённым ячейкам, «до → после». Уровень R* — медиана "
"R*; первая нарушившая — ближайшая ступень выше R* ячейки, "
"нарушившая SLO. CPU PostgreSQL — на успешный запрос; новые сессии "
"— прирост `pg_stat_database.sessions` за окно; соединения — "
"наибольшее число соединений с PostgreSQL в окне. Нет значения — "
"«—».",
"",
"| Конфигурация | Ступень | Уровень, запросов/с | CPU PostgreSQL "
"на запрос, мкс | Новых сессий за окно | Соединений PostgreSQL |",
"|---|---|---|---|---|---|",
]
for key in common:
a, b = first[key], second[key]
lines += [
f"| {key} | R* | {pair(a['r_star'], b['r_star'])} | "
f"{pair(a['db_us_r'], b['db_us_r'])} | "
f"{pair(a['sessions_r'], b['sessions_r'])} | "
f"{pair(a['conn_r'], b['conn_r'])} |",
f"| {key} | первая нарушившая | "
f"{pair(a['level_f'], b['level_f'])} | "
f"{pair(a['db_us_f'], b['db_us_f'])} | "
f"{pair(a['sessions_f'], b['sessions_f'])} | "
f"{pair(a['conn_f'], b['conn_f'])} |",
]
return lines
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="")
# change, к которому относится сравнение серий (строка шапки)
parser.add_argument("--change", default="scaling-bench")
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}"
if args.change != parser.get_default("change"):
command += f" CHANGE={args.change}"
try:
before, after = load(args.before), load(args.after)
aa = load(args.aa) if args.aa else None
if any(is_series(x) for x in (before, after, aa) if x is not None):
for other in (after, aa):
if other is not None:
check_methodology(before, other, set())
text = render_series(before, after, aa, command, args.change)
else:
text = render(before, after, aa, 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:]))
+606
View File
@@ -0,0 +1,606 @@
"""Профиль отказа реплик: разбор и расчёт без docker.
Оркестрирует фазы `run.py` (профили `failover`, `failover_quick`), здесь —
чистые функции на stdlib: строки k6 о каждом запросе, статистика и
журнал HAProxy, события Docker, посекундная шкала, величины фазы и
`summary.md`. Определения величин — решение 5 design change
`graceful-failover`. Все отметки времени — часы ВМ Docker: `Date.now()` в
k6, отметки `docker logs -t` и `TimeNano` событий Docker.
"""
import csv
import io
import math
import re
from dataclasses import dataclass
from datetime import UTC, datetime
from typing import Any
import resources as res
# худшее время обнаружения по проверкам LB, с (infra/haproxy/haproxy.cfg:
# inter 1s, fastinter 500ms, fall 2, timeout check 2500ms, timeout connect
# 500ms): адрес пропал — inter + 0,5 + fastinter + 0,5; зависшая —
# inter + timeout check + fastinter + timeout check
BOUNDS = {"stop": 2.5, "kill": 2.5, "pause": 6.5}
# действие и возврат фазы — события Docker
ACTIONS = {"stop": "kill", "kill": "kill", "pause": "pause"}
RESTORES = {"stop": "start", "kill": "start", "pause": "unpause"}
PHASE_FIELDS = [
"phase",
"mode",
"replica",
"instance",
"slot",
"action_at",
"signal",
"lb_out_s",
"lb_out_state",
"lb_out_reason",
"bound_s",
"first_write_ok_s",
"first_read_ok_s",
"last_error_s",
"requests",
"errors_before",
"errors_down",
"codes_down",
"errors_after",
"codes_after",
"min_success",
"recovery_s",
"ok_rps_before",
"ok_rps_down_min",
"p95_before_ms",
"p95_down_max_ms",
"restore_at",
"lb_up_s",
"slot_back",
"instance_back_s",
"writes",
"writes_failed",
"retried_ok",
"write_chat_messages",
"distinct_texts",
"pg_idle_tx_terminated",
"dropped_iterations",
"flags",
]
TIMELINE_FIELDS = [
"phase",
"mode",
"replica",
"second",
"writes_ok",
"writes_failed",
"reads_ok",
"reads_failed",
"codes",
"success",
"p50_ms",
"p95_ms",
"instances",
]
# без привязки к началу и концу строки: две строки, склеенные без перевода
# строки, всё равно разбираются; число строк run.py сверяет с итогом k6
LINE_RE = re.compile(
r"fo,(?P<kind>[wr]),(?P<n>\d+),(?P<start>\d{13}),(?P<dur>-?\d+),"
r"(?P<status>-?\d+),(?P<instance>[A-Za-z0-9._-]*),(?P<ok>[01])",
)
def unparsed(text: str) -> list[str]:
"""Строки с `fo,`, которые разбор не взял: в сообщение об отказе."""
return [
line
for line in text.splitlines()
if "fo," in line and not LINE_RE.search(line)
]
LB_RE = re.compile(
r"^(?P<stamp>\S+) .*?Server api/(?P<slot>api-\d+) (?P<rest>.*)$",
)
IDLE_TX = "terminating connection due to idle-in-transaction timeout"
@dataclass(frozen=True)
class Request:
"""Один запрос фазы: строка `fo,…` вывода k6."""
kind: str
n: int
start: float
duration_ms: int
status: int
instance: str
ok: bool
@dataclass(frozen=True)
class LbEvent:
"""Смена состояния слота в журнале HAProxy."""
time: float
slot: str
state: str
reason: str
@dataclass(frozen=True)
class DockerEvent:
time: float
action: str
signal: str
def parse_requests(text: str) -> list[Request]:
return [
Request(
kind=match["kind"],
n=int(match["n"]),
start=int(match["start"]) / 1000,
duration_ms=max(0, int(match["dur"])),
status=int(match["status"]),
instance=match["instance"],
ok=match["ok"] == "1",
)
for match in LINE_RE.finditer(text)
]
def parse_stamp(stamp: str) -> float:
"""Отметка `docker logs -t` (RFC 3339, наносекунды) → секунды эпохи."""
head, _, frac = stamp.rstrip("Z").partition(".")
seconds = datetime.fromisoformat(head).replace(tzinfo=UTC).timestamp()
return seconds + (float(f"0.{frac}") if frac else 0.0)
def iso(seconds: float) -> str:
return datetime.fromtimestamp(seconds, UTC).isoformat(
timespec="milliseconds",
)
def parse_lb_stats(text: str) -> list[dict[str, str]]:
"""CSV статистики HAProxy → занятые слоты backend `api`."""
lines = [
line for line in text.splitlines() if line.startswith(("# ", "api,"))
]
if not lines:
return []
reader = csv.DictReader(io.StringIO("\n".join(lines).removeprefix("# ")))
return [
{
"slot": row["svname"],
"addr": row.get("addr") or "",
"status": row["status"],
"check_status": row.get("check_status") or "",
}
for row in reader
if row["pxname"] == "api"
and row["svname"] not in ("BACKEND", "FRONTEND")
and row.get("addr")
]
def parse_lb_log(text: str) -> list[LbEvent]:
"""Строки смены состояния слотов из журнала LB (`docker logs -t`).
HAProxy пишет каждое событие дважды (в журнал и предупреждением):
повтор с тем же слотом и состоянием в пределах миллисекунды
отбрасывается.
"""
events: list[LbEvent] = []
for line in text.splitlines():
match = LB_RE.match(line)
if not match:
continue
rest = match["rest"]
if "maintenance" in rest:
state = "MAINT"
elif rest.startswith("is DOWN,") or rest == "is DOWN.":
state = "DOWN"
elif rest.startswith("is UP"):
state = "UP"
else:
continue
reason = re.search(r"reason: ([^,]+)", rest)
info = re.search(r"maintenance \(([^)]*)\)", rest)
event = LbEvent(
time=parse_stamp(match["stamp"]),
slot=match["slot"],
state=state,
reason=(
reason.group(1)
if reason
else (info.group(1).strip() if info else "")
),
)
if any(
e.slot == event.slot
and e.state == event.state
and abs(e.time - event.time) < 0.001
for e in events
):
continue
events.append(event)
return sorted(events, key=lambda e: e.time)
def lb_lines(text: str) -> str:
"""Строки журнала LB о состоянии слотов — для `raw/<фаза>-lb.log`."""
return "\n".join(
line
for line in text.splitlines()
if "Server api/" in line and "[WARNING]" not in line
)
def parse_events(text: str) -> list[DockerEvent]:
events = []
for line in text.splitlines():
parts = line.split()
if len(parts) < 2 or not parts[0].isdigit():
continue
signal = parts[2] if len(parts) > 2 and parts[2].isdigit() else ""
events.append(DockerEvent(int(parts[0]) / 1e9, parts[1], signal))
return sorted(events, key=lambda e: e.time)
def count_idle_terminations(text: str) -> int:
"""Сколько соединений PostgreSQL прервал по простою в транзакции."""
return text.count(IDLE_TX)
def percentile(values: list[int], share: float) -> int | None:
"""Ближайший ранг: p95 из 100 значений — 95-е по возрастанию."""
if not values:
return None
ordered = sorted(values)
return ordered[max(0, math.ceil(share * len(ordered)) - 1)]
def code(request: Request) -> str:
"""Код ошибки: статус, 0 — ошибка соединения или таймаут клиента,
`200-short` — чтение без полной страницы."""
if request.status == 200 and not request.ok:
return "200-short"
return str(request.status)
def codes(requests: list[Request]) -> str:
counts: dict[str, int] = {}
for request in requests:
if not request.ok:
counts[code(request)] = counts.get(code(request), 0) + 1
return " ".join(f"{key}:{value}" for key, value in sorted(counts.items()))
def build_timeline(
requests: list[Request],
t0: float,
*,
phase: str,
mode: str,
replica: int,
) -> list[dict[str, Any]]:
"""Посекундная шкала от действия: секунда запроса — по отправке."""
buckets: dict[int, list[Request]] = {}
for request in requests:
buckets.setdefault(math.floor(request.start - t0), []).append(request)
rows = []
for second in range(min(buckets, default=0), max(buckets, default=-1) + 1):
group = buckets.get(second, [])
ok = [r for r in group if r.ok]
instances: dict[str, int] = {}
for request in ok:
instances[request.instance] = (
instances.get(request.instance, 0) + 1
)
durations = [r.duration_ms for r in ok]
rows.append(
{
"phase": phase,
"mode": mode,
"replica": replica,
"second": second,
"writes_ok": sum(1 for r in ok if r.kind == "w"),
"writes_failed": sum(
1 for r in group if r.kind == "w" and not r.ok
),
"reads_ok": sum(1 for r in ok if r.kind == "r"),
"reads_failed": sum(
1 for r in group if r.kind == "r" and not r.ok
),
"codes": codes(group),
"success": round(len(ok) / len(group), 4) if group else None,
"p50_ms": percentile(durations, 0.5),
"p95_ms": percentile(durations, 0.95),
"instances": " ".join(
f"{key}:{value}"
for key, value in sorted(instances.items())
),
},
)
return rows
def first_after(
events: list[LbEvent],
slot: str | None,
states: tuple[str, ...],
since: float,
) -> LbEvent | None:
return next(
(
e
for e in events
if e.slot == slot and e.state in states and e.time >= since
),
None,
)
def rounded(value: float | None, digits: int = 2) -> float | None:
return None if value is None else round(value, digits)
def analyze(
requests: list[Request],
timeline: list[dict[str, Any]],
lb_events: list[LbEvent],
*,
mode: str,
instance: str,
t0: float,
restore: float,
slot: str | None,
slot_back: str | None,
threshold: float,
) -> dict[str, Any]:
"""Величины фазы (решение 5): секунды от действия и от возврата.
До действия — запросы, завершённые до него. Запрос в полёте в момент
действия (на замороженной или убитой реплике) относится к окну
отказа, хотя в шкале он — в секунде отправки.
"""
def ended(request: Request) -> float:
return request.start + request.duration_ms / 1000
before = [r for r in requests if ended(r) < t0]
down = [r for r in requests if ended(r) >= t0 and r.start < restore]
after = [r for r in requests if r.start >= restore]
window = math.ceil(restore - t0)
down_rows = [row for row in timeline if 0 <= row["second"] < window]
before_rows = [row for row in timeline if row["second"] < 0][2:]
bad = [
row["second"]
for row in down_rows
if row["success"] is not None and row["success"] < threshold
]
out = first_after(lb_events, slot, ("DOWN", "MAINT"), t0)
up = first_after(lb_events, slot_back, ("UP",), restore)
back = next(
(
r
for r in sorted(after, key=lambda r: r.start)
if r.ok and r.instance == instance
),
None,
)
def first_ok(kind: str) -> float | None:
starts = [
r.start for r in down if r.kind == kind and r.ok and r.start >= t0
]
return rounded(min(starts) - t0) if starts else None
failed_down = [r for r in down if not r.ok]
p95_down = [
row["p95_ms"] for row in down_rows if row["p95_ms"] is not None
]
lb_out_s = rounded(out.time - t0) if out else None
flags = []
if out is None:
flags.append("no_lb_out")
elif lb_out_s is not None and lb_out_s > BOUNDS[mode]:
flags.append("over_bound")
if up is None:
flags.append("no_lb_up")
if [r for r in before if not r.ok]:
flags.append("errors_before")
return {
"lb_out_s": lb_out_s,
"lb_out_state": out.state if out else None,
"lb_out_reason": out.reason if out else None,
"bound_s": BOUNDS[mode],
"first_write_ok_s": first_ok("w"),
"first_read_ok_s": first_ok("r"),
"last_error_s": (
rounded(max(r.start for r in failed_down) - t0)
if failed_down
else None
),
"requests": len(requests),
"errors_before": sum(1 for r in before if not r.ok),
"errors_down": len(failed_down),
"codes_down": codes(down),
"errors_after": sum(1 for r in after if not r.ok),
"codes_after": codes(after),
"min_success": min(
(
row["success"]
for row in down_rows
if row["success"] is not None
),
default=None,
),
"recovery_s": max(bad) + 1 if bad else 0,
"ok_rps_before": (
round(
sum(row["writes_ok"] + row["reads_ok"] for row in before_rows)
/ len(before_rows),
1,
)
if before_rows
else None
),
"ok_rps_down_min": min(
(row["writes_ok"] + row["reads_ok"] for row in down_rows),
default=None,
),
"p95_before_ms": percentile(
[r.duration_ms for r in before if r.ok],
0.95,
),
"p95_down_max_ms": max(p95_down, default=None),
"lb_up_s": rounded(up.time - restore) if up else None,
"instance_back_s": rounded(back.start - restore) if back else None,
"writes": sum(1 for r in requests if r.kind == "w"),
"writes_failed": sum(
1 for r in requests if r.kind == "w" and not r.ok
),
"flags": " ".join(flags),
}
def fmt(value: Any) -> str:
if value is None or value == "":
return "—"
if isinstance(value, float):
return f"{value:g}"
return str(value)
def limits_line(profile: dict[str, Any]) -> str:
"""Строка лимитов шапки сводки; с сэмплером — и его лимит, и k6 без
лимита (design change `profile-resources`, решение 7)."""
line = (
f"- Лимиты без swap: API {profile['cpus']} CPU / "
f"{profile['memory']} на реплику, HAProxy {profile['lb_cpus']} CPU / "
f"{profile['lb_memory']}, PostgreSQL {profile['db_cpus']} CPU / "
f"{profile['db_memory']}, Valkey {profile['cache_cpus']} CPU / "
f"{profile['cache_memory']}"
)
if profile.get("sample_resources"):
line += (
f", сэмплер {profile['sampler_cpus']} CPU / "
f"{profile['sampler_memory']}, k6 без лимита"
)
return line
def render_summary(
meta: dict[str, Any],
phases: list[dict[str, Any]],
timeline: list[dict[str, Any]],
resources: list[dict[str, Any]] | None = None,
) -> str:
"""`summary.md` профиля отказа: условия, таблица фаз, шкалы вокруг
действия и возврата; с `resources` (строки `resources.csv`) — ещё
ресурсы по фазам и окнам."""
profile = meta["profile"]
lines = [
f"# Отказ реплик под нагрузкой: метка `{meta['label']}`",
"",
f"- Статус: **{meta['status']}**"
+ (f" ({meta['reason']})" if meta.get("reason") else ""),
f"- Commit: `{meta['git']['commit']}`"
+ (" + незакоммиченные изменения" if meta["git"]["dirty"] else ""),
f"- Профиль `{profile['name']}`: {profile['replicas']} реплики за "
f"HAProxy; {profile['failover_write_rate']} записей с ключом и "
f"{profile['failover_read_rate']} чтений страницы истории в "
"секунду (k6, постоянная интенсивность); режимы "
f"{', '.join(profile['failover_modes'])}; окна фазы: "
f"{profile['failover_before_s']} с до действия, "
f"{profile['failover_down_s']} с до возврата, "
f"{profile['failover_after_s']} с после; порог восстановления "
f"{profile['failover_success']:.0%}",
limits_line(profile),
"- Посторонние контейнеры в VM во время замера: "
+ (", ".join(meta.get("other_containers") or []) or "нет"),
"",
"Время — секунды на часах ВМ Docker. Действие — событие Docker "
"(`kill` с сигналом 15 у `docker stop`, 9 у `docker kill`, "
"`pause`), исключение и возврат — строки журнала HAProxy, ответы — "
"отметки k6 при отправке. Граница — худший случай формулы проверок "
"LB для режима. Восстановление — конец последней секунды окна "
"отказа с долей успешных ниже порога (0 — таких секунд нет). "
"Сверка — после повтора неуспешных записей с тем же ключом: "
"сообщений в чате записи и разных текстов столько, сколько "
"отправлено разных ключей.",
"",
"| Фаза | Реплика | Исключение LB, с (граница) | Причина | "
"Первая запись / чтение, с | Ошибки в окне отказа | Мин. доля "
"успешных | Восстановление, с | Возврат в LB, с | Ошибки после "
"возврата | Повтор записей | Сообщений = ключей | PG: прервано "
"простоев | Пометки |",
"|---|---|---|---|---|---|---|---|---|---|---|---|---|---|",
]
for row in phases:
lines.append(
f"| {row['phase']} | {row['instance']} ({row['slot']}) | "
f"{fmt(row['lb_out_s'])} ({fmt(row['bound_s'])}) | "
f"{fmt(row['lb_out_state'])}: {fmt(row['lb_out_reason'])} | "
f"{fmt(row['first_write_ok_s'])} / {fmt(row['first_read_ok_s'])} "
f"| {row['errors_down']} {fmt(row['codes_down'])} | "
f"{fmt(row['min_success'])} | {row['recovery_s']} | "
f"{fmt(row['lb_up_s'])} | {row['errors_after']} | "
f"{row['writes_failed']} → {fmt(row['retried_ok'])} | "
f"{fmt(row['write_chat_messages'])} = "
f"{fmt(row['distinct_texts'])} | "
f"{fmt(row['pg_idle_tx_terminated'])} | {fmt(row['flags'])} |",
)
lines.append("")
if resources:
order = list(dict.fromkeys(r["phase"] for r in resources))
lines += res.render_failover(resources, order)
for row in phases:
rows = [r for r in timeline if r["phase"] == row["phase"]]
reach = max(
row["recovery_s"] or 0,
math.ceil(row["lb_out_s"] or 0),
)
down_s = profile["failover_down_s"]
shown = [
r
for r in rows
if -2 <= r["second"] <= reach + 2
or down_s - 1 <= r["second"] <= down_s + 3
]
lines += [
f"## Фаза {row['phase']}",
"",
f"Действие {row['action_at']} над `{row['instance']}` (слот "
f"{row['slot']}), возврат {row['restore_at']}; ответов "
f"{row['requests']}, до действия {fmt(row['ok_rps_before'])} "
f"успешных/с, p95 {fmt(row['p95_before_ms'])} мс. Полная шкала "
"— `timeline.csv`.",
"",
"| с от действия | Записи ok / ош | Чтения ok / ош | Коды ошибок "
"| Доля успешных | p50 / p95, мс | Ответы реплик |",
"|---|---|---|---|---|---|---|",
]
previous = None
for r in shown:
if previous is not None and r["second"] != previous + 1:
lines.append("| … | | | | | | |")
previous = r["second"]
lines.append(
f"| {r['second']} | {r['writes_ok']} / {r['writes_failed']} | "
f"{r['reads_ok']} / {r['reads_failed']} | {fmt(r['codes'])} | "
f"{fmt(r['success'])} | {fmt(r['p50_ms'])} / "
f"{fmt(r['p95_ms'])} | {fmt(r['instances'])} |",
)
lines.append("")
if resources:
lines += res.render_failover_phase(resources, row["phase"])
if meta.get("host_warnings"):
lines += ["## Предупреждения о хосте", ""]
lines += [f"- {w}" for w in meta["host_warnings"]]
lines.append("")
return "\n".join(lines)
+42
View File
@@ -0,0 +1,42 @@
// Активность после backup (трек 2, восстановление): новый пользователь
// с паролем входит по Basic, создаёт чат с читателем и пишет в него одно
// сообщение. После восстановления из backup всего этого в базе быть не
// должно, а карточка чата остаётся в кэше. Итог — after.json в рабочем
// каталоге (токен только там, оркестратор удаляет его в конце прогона).
import http from "k6/http";
import { fail } from "k6";
import { API, WORK_DIR, createChat, messageHeaders, register } from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "60s",
};
export function setup() {
const stamp = Date.now().toString(36);
const late = register(`b${stamp}_late`, "Bench after backup");
const chatId = createChat(
late.token,
"bench after backup",
[late.id, fixture.readerId],
);
const res = http.post(
`${API}/chats/${chatId}/messages`,
JSON.stringify({ text: "written after backup" }),
{ headers: messageHeaders(late.token) },
);
if (res.status !== 201) {
fail(`message after backup: ${res.status} ${res.body}`);
}
return { userId: late.id, token: late.token, chatId };
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/after.json`]: JSON.stringify(data.setup_data) };
}
+63
View File
@@ -0,0 +1,63 @@
// Пул курсоров сценария 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.tokens[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,
// позиции курсоров пула: сколько сообщений до каждого (для плана)
afters: pool.map((p) => p.after),
cursors: pool.map((p) => p.cursor),
};
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/cursors.json`]: JSON.stringify(data.setup_data) };
}
+41
View File
@@ -0,0 +1,41 @@
// Этап плана: страницы истории из plan_pages.json подряд, пока в Postgres
// стенда включён auto_explain. Для читаемого чата и первого чата каждого
// фонового уровня — первая, средняя и последняя полная страница (у
// короткого чата — первая). Порядок запросов = порядок планов в журнале:
// оркестратор сопоставляет их по нему.
import http from "k6/http";
import { check, fail } from "k6";
import { API, PAGE_LIMIT, WORK_DIR, authHeaders } from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const pages = JSON.parse(open(`${WORK_DIR}/plan_pages.json`));
export const options = {
vus: 1,
iterations: 1,
};
export default function () {
const params = { headers: authHeaders(fixture.tokens[fixture.readerId]) };
for (const page of pages) {
const name = `${page.chat} ${page.page}`;
const query = page.cursor === null
? `?limit=${PAGE_LIMIT}`
: `?limit=${PAGE_LIMIT}&cursor=${encodeURIComponent(page.cursor)}`;
const res = http.get(`${API}/chats/${page.chat_id}/messages${query}`, params);
const ok = check(res, {
[`${name} 200`]: (r) => r.status === 200,
[`${name} ${page.items} items`]: (r) =>
r.status === 200 && r.json("items.#") === page.items,
});
if (!ok) {
fail(`explain page ${name}: ${res.status}`);
}
}
}
// итог не нужен: планы оркестратор берёт из журнала Postgres
export function handleSummary() {
return {};
}
+130
View File
@@ -0,0 +1,130 @@
// Профили отказа и замены реплик: постоянная интенсивность записи с ключом
// и чтения страницы истории через LB, пока оркестратор останавливает и
// возвращает реплику (решение 7 design change graceful-failover) или
// заменяет реплики scripts/rolling-update.sh (решение 8 design change
// rolling-update). Каждый запрос —
// строка «fo,<w|r>,<n>,<отправка мс>,<длительность мс>,<статус>,
// <X-Instance-Id>,<успех>» в вывод k6: из них run.py строит посекундную
// шкалу. Время — Date.now() часов ВМ Docker, те же часы, что у журнала LB и
// событий Docker.
import exec from "k6/execution";
import http from "k6/http";
import { SharedArray } from "k6/data";
import {
API,
PAGE_LIMIT,
SUMMARY_THRESHOLDS,
SUMMARY_TREND_STATS,
WORK_DIR,
authHeaders,
messageHeaders,
mulberry32,
summaryFiles,
syntheticText,
} 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,
);
// ключ записи — <RUN>.<PHASE>.<n>: повтор (retry.js) строит тот же
const RUN = __ENV.RUN;
const PHASE = Number(__ENV.PHASE);
const SEED = Number(__ENV.SEED || 0);
// VU сценария: заранее созданные и предел (Profile.failover_pre_vus,
// failover_max_vus). Создание VU на ходу пропускает итерации
const PRE_VUS = Number(__ENV.PRE_VUS || 600);
const MAX_VUS = Number(__ENV.MAX_VUS || 1500);
// больше timeout server LB (10 с): клиент видит ответ LB, а не свой таймаут
const TIMEOUT = __ENV.TIMEOUT || "15s";
const WRITE_URL = `${API}/chats/${fixture.writeChatId}/messages`;
const READ_URL = `${API}/chats/${fixture.readChatId}/messages`;
const READ_HEADERS = authHeaders(fixture.tokens[fixture.readerId]);
function scenario(fn, rate) {
return {
executor: "constant-arrival-rate",
exec: fn,
rate,
timeUnit: "1s",
duration: __ENV.DURATION,
// зависшая реплика держит запрос до timeout server: VU с запасом
preAllocatedVUs: PRE_VUS,
maxVUs: MAX_VUS,
gracefulStop: "20s",
};
}
export const options = {
scenarios: {
write: scenario("write", Number(__ENV.WRITE_RATE)),
read: scenario("read", Number(__ENV.READ_RATE)),
},
summaryTrendStats: SUMMARY_TREND_STATS,
// пороги всегда выполняются: подметрики итераций по сценариям попадают
// в итог, и run.py сверяет с ними число строк о запросах
thresholds: {
...SUMMARY_THRESHOLDS,
"iterations{scenario:write}": ["count>=0"],
"iterations{scenario:read}": ["count>=0"],
},
};
// длительность — по монотонным таймингам k6, а не разность Date.now():
// часы ВМ подводятся, и при шаге назад разность выходила отрицательной.
// Ответа нет (status 0) — тайминги пусты, тогда разность часов
function report(kind, n, start, res, ok) {
const instance = res.headers["X-Instance-Id"] || "-";
const t = res.timings;
const measured = t.blocked + t.connecting + t.tls_handshaking + t.duration;
const duration = Math.max(
0,
Math.round(res.status === 0 ? Date.now() - start : measured),
);
console.log(
`fo,${kind},${n},${start},${duration},${res.status},${instance},${ok ? 1 : 0}`,
);
}
export function write() {
const n = exec.scenario.iterationInTest;
const sender = fixture.memberIds[n % fixture.memberIds.length];
const start = Date.now();
const res = http.post(
WRITE_URL,
JSON.stringify({ text: syntheticText(`f${PHASE}`, n) }),
{
headers: messageHeaders(fixture.tokens[sender], `${RUN}.${PHASE}.${n}`),
responseType: "none",
timeout: TIMEOUT,
responseCallback: http.expectedStatuses(201),
},
);
report("w", n, start, res, res.status === 201);
}
let random = null;
export function read() {
if (random === null) {
random = mulberry32(SEED + exec.vu.idInTest);
}
const n = exec.scenario.iterationInTest;
const cursor = encodeURIComponent(
cursors[Math.floor(random() * cursors.length)],
);
const start = Date.now();
const res = http.get(`${READ_URL}?limit=${PAGE_LIMIT}&cursor=${cursor}`, {
headers: READ_HEADERS,
timeout: TIMEOUT,
responseCallback: http.expectedStatuses(200),
});
const full = res.status === 200 && res.json("items.#") === PAGE_LIMIT;
report("r", n, start, res, full);
}
export function handleSummary(data) {
return summaryFiles(data);
}
+122
View File
@@ -0,0 +1,122 @@
// Общие хелперы сценариев стенда: адрес, идентификация, текст, генератор
// случайных чисел, запись итога. Не Node.js: только встроенные модули k6.
import encoding from "k6/encoding";
import http from "k6/http";
import { check, fail } from "k6";
// через балансировщик стенда: имя сервиса haproxy — алиас в сети
// mtusi-bench, за ним Profile.replicas реплик (решение 6 design change
// graceful-failover)
export const BASE_URL = __ENV.BASE_URL || "http://haproxy: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"] };
// идентификация, как Actor.headers() в student-tests: Bearer-токен сессии
export function authHeaders(token) {
return {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
};
}
// заголовки отправки сообщения: с лабы 3 обязателен Idempotency-Key. Новый
// ключ на каждую отправку (UUID v4 WebCrypto — допустимый алфавит
// контракта); стенд отправку не повторяет. Профиль отказа задаёт ключ сам:
// повтор неподтверждённой записи строит тот же ключ по номеру
export function messageHeaders(token, key = crypto.randomUUID()) {
return {
...authHeaders(token),
"Idempotency-Key": key,
};
}
// синтетический пароль из двух UUID v4 WebCrypto (73 символа, контракт —
// 12–128): только в памяти prepare.js, в фикстуру и результаты не попадает
function syntheticPassword() {
return `${crypto.randomUUID()}-${crypto.randomUUID()}`;
}
// синтетический текст ровно 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;
};
}
// регистрация с паролем и вход по Basic: { id, token } пользователя
export function register(username, displayName) {
const password = syntheticPassword();
const res = http.post(
`${API}/users`,
JSON.stringify({ username, display_name: displayName, password }),
{ headers: { "Content-Type": "application/json" } },
);
if (!check(res, { "register 201": (r) => r.status === 201 })) {
fail(`register ${username}: ${res.status} ${res.body}`);
}
const basic = encoding.b64encode(`${username}:${password}`);
const login = http.post(`${API}/auth/sessions`, null, {
headers: { Authorization: `Basic ${basic}` },
});
if (!check(login, { "login 201": (r) => r.status === 201 })) {
fail(`login ${username}: ${login.status} ${login.body}`);
}
return { id: res.json("id"), token: login.json("token") };
}
export function createChat(ownerToken, title, memberIds) {
const res = http.post(
`${API}/chats`,
JSON.stringify({ title, member_ids: memberIds }),
{ headers: authHeaders(ownerToken) },
);
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, senderToken, text, key = undefined) {
const res = http.post(
`${API}/chats/${chatId}/messages`,
JSON.stringify({ text }),
{
headers: messageHeaders(senderToken, key),
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) };
}
+217
View File
@@ -0,0 +1,217 @@
// Ступень серии трека 1 (решения 2–3 design change scaling-bench):
// открытая модель, три сценария ramping-arrival-rate с долями смеси —
// страница истории читаемого чата, отправка с новым Idempotency-Key в один
// из чатов записи, GET /users/me. Ступень — подъём от START до LEVEL за
// WARMUP_S (в замер не входит) и окно MEASURE_S с постоянной
// интенсивностью. Каждый запрос получает тег window (warm / hold) по
// времени отправки от начала сценария; итог содержит подметрики окна.
// Время setup (t0) — часы ВМ Docker: по нему run.py режет отсчёты
// сэмплера. Вход по Basic — в prepare.js, до ступеней.
import exec from "k6/execution";
import http from "k6/http";
import { check } from "k6";
import { SharedArray } from "k6/data";
import { Counter } from "k6/metrics";
import {
API,
PAGE_LIMIT,
SUMMARY_TREND_STATS,
WORK_DIR,
authHeaders,
messageHeaders,
mulberry32,
summaryFiles,
syntheticText,
} 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 LEVEL = Number(__ENV.LEVEL);
const START = Number(__ENV.START || 0);
// «read:0.7,write:0.2,me:0.1» — Profile.mix
const MIX = (__ENV.MIX || "read:0.7,write:0.2,me:0.1")
.split(",")
.map((item) => item.split(":"))
.map(([name, share]) => [name, Number(share)]);
const WARMUP_S = Number(__ENV.WARMUP_S);
const MEASURE_S = Number(__ENV.MEASURE_S);
const WARMUP_MS = WARMUP_S * 1000;
// больше timeout server LB (10 с): клиент видит ответ LB, а не свой таймаут
const TIMEOUT_S = Number(__ENV.TIMEOUT || 15);
const PRE_VUS_PER_RPS = Number(__ENV.PRE_VUS_PER_RPS || 0.05);
const MAX_VUS_PER_RPS = Number(__ENV.MAX_VUS_PER_RPS || 0.2);
const SEED = Number(__ENV.SEED || 0);
const STEP = Number(__ENV.STEP || 0);
// короткие ID реплик: подметрики распределения по X-Instance-Id
const INSTANCES = (__ENV.INSTANCES || "").split(",").filter((x) => x);
const ABORT_ERRORS = Number(__ENV.ABORT_ERRORS || 0.5);
const ABORT_P95_MS = Number(__ENV.ABORT_P95_MS || 2000);
// коды неуспешных ответов окна (bench/scaling.py, ERROR_STATUSES)
const ERROR_STATUSES = [0, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504];
const READ_URL = `${API}/chats/${fixture.readChatId}/messages`;
const READ_HEADERS = authHeaders(fixture.tokens[fixture.readerId]);
const USERS = [fixture.readerId, ...fixture.memberIds];
const WRITE_CHATS = fixture.writeChatIds || [fixture.writeChatId];
const shortPages = new Counter("short_pages");
const instanceOk = new Counter("instance_ok");
function scenario(name, share) {
const target = Math.round(LEVEL * share);
const start = Math.round(START * share);
return {
executor: "ramping-arrival-rate",
exec: name,
startRate: start,
timeUnit: "1s",
preAllocatedVUs: Math.ceil(target * PRE_VUS_PER_RPS) + 10,
maxVUs: Math.ceil(target * MAX_VUS_PER_RPS) + 20,
stages: [
{ target, duration: `${WARMUP_S}s` },
{ target, duration: `${MEASURE_S}s` },
],
// запрос, начатый в конце окна, успевает дождаться ответа или таймаута
gracefulStop: `${TIMEOUT_S + 1}s`,
};
}
const HOLD = "window:hold";
const thresholds = {
// досрочный выход по подметрикам окна (код k6 99): перегрузка не тянется
// до конца ступени
[`http_req_duration{${HOLD},expected_response:true}`]: [
"max>=0",
{
threshold: `p(95)<${ABORT_P95_MS}`,
abortOnFail: true,
delayAbortEval: `${WARMUP_S + 5}s`,
},
],
[`http_req_failed{${HOLD}}`]: [
"rate>=0",
{
threshold: `rate<=${ABORT_ERRORS}`,
abortOnFail: true,
delayAbortEval: `${WARMUP_S + 5}s`,
},
],
[`short_pages{${HOLD}}`]: ["count>=0"],
[`checks{${HOLD}}`]: ["rate>=0"],
};
// остальные пороги всегда выполняются: они нужны, чтобы подметрики попали
// в итог
for (const [name] of MIX) {
thresholds[`http_reqs{${HOLD},scenario:${name}}`] = ["count>=0"];
thresholds[`http_req_failed{${HOLD},scenario:${name}}`] = ["rate>=0"];
thresholds[
`http_req_duration{${HOLD},expected_response:true,scenario:${name}}`
] = ["max>=0"];
thresholds[`http_reqs{scenario:${name}}`] = ["count>=0"];
thresholds[`http_req_failed{scenario:${name}}`] = ["rate>=0"];
}
for (const id of [...INSTANCES, "-"]) {
thresholds[`instance_ok{${HOLD},instance:${id}}`] = ["count>=0"];
}
for (const status of ERROR_STATUSES) {
thresholds[`http_reqs{${HOLD},status:${status}}`] = ["count>=0"];
}
export const options = {
scenarios: Object.fromEntries(
MIX.map(([name, share]) => [name, scenario(name, share)]),
),
summaryTrendStats: SUMMARY_TREND_STATS,
thresholds,
};
export function setup() {
return { t0: Date.now() };
}
// тег окна по времени отправки от начала сценария
function windowTag() {
return Date.now() - exec.scenario.startTime < WARMUP_MS ? "warm" : "hold";
}
function counted(res, ok, window) {
if (ok) {
instanceOk.add(1, {
window,
instance: res.headers["X-Instance-Id"] || "-",
});
}
}
let random = null;
export function read() {
if (random === null) {
random = mulberry32(SEED + exec.vu.idInTest);
}
const window = windowTag();
const cursor = encodeURIComponent(
cursors[Math.floor(random() * cursors.length)],
);
const res = http.get(`${READ_URL}?limit=${PAGE_LIMIT}&cursor=${cursor}`, {
headers: READ_HEADERS,
timeout: `${TIMEOUT_S}s`,
tags: { window },
responseCallback: http.expectedStatuses(200),
});
const full = res.status === 200 && res.json("items.#") === PAGE_LIMIT;
if (res.status === 200 && !full) {
// неполная страница при 200: отдельный счётчик, без двойного учёта
shortPages.add(1, { window });
}
check(res, { "read 200 full page": () => full }, { window });
counted(res, full, window);
}
export function write() {
const n = exec.scenario.iterationInTest;
const sender = fixture.memberIds[n % fixture.memberIds.length];
const chat = WRITE_CHATS[
Math.floor(n / fixture.memberIds.length) % WRITE_CHATS.length
];
const window = windowTag();
const res = http.post(
`${API}/chats/${chat}/messages`,
JSON.stringify({ text: syntheticText(`s${STEP}`, n) }),
{
// ключ — новый на каждую отправку (lib.js); стенд не повторяет
headers: messageHeaders(fixture.tokens[sender]),
responseType: "none",
timeout: `${TIMEOUT_S}s`,
tags: { window },
responseCallback: http.expectedStatuses(201),
},
);
const ok = res.status === 201;
check(res, { "write 201": () => ok }, { window });
counted(res, ok, window);
}
export function me() {
const n = exec.scenario.iterationInTest;
const user = USERS[n % USERS.length];
const window = windowTag();
const res = http.get(`${API}/users/me`, {
headers: authHeaders(fixture.tokens[user]),
responseType: "none",
timeout: `${TIMEOUT_S}s`,
tags: { window },
responseCallback: http.expectedStatuses(200),
});
const ok = res.status === 200;
check(res, { "me 200": () => ok }, { window });
counted(res, ok, window);
}
export function handleSummary(data) {
return summaryFiles(data);
}
+51
View File
@@ -0,0 +1,51 @@
// Курсоры страниц плана фоновых чатов (трек 2): проход истории каждого чата
// из plan_chats.json страницами по WALK_LIMIT, позиция и курсор после каждой
// страницы. Идёт до включения auto_explain, поэтому в журнал не попадает;
// заодно прогревает страницы этих чатов, как cursors.js — читаемого.
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 chats = JSON.parse(open(`${WORK_DIR}/plan_chats.json`));
const WALK_LIMIT = Number(__ENV.WALK_LIMIT || 100);
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "10m",
};
export function setup() {
const params = { headers: authHeaders(fixture.tokens[fixture.readerId]) };
return chats.map((chat) => {
const url = `${API}/chats/${chat.id}/messages`;
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(`chat ${chat.id} 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;
}
return { id: chat.id, walked, positions };
});
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/plan_walks.json`]: JSON.stringify(data.setup_data) };
}
+51
View File
@@ -0,0 +1,51 @@
// Одна порция наполнения: COUNT сообщений от участников по кругу. Чат
// сообщения n берётся из расписания оркестратора (schedule.json: 0 —
// читаемый чат, дальше фоновые в порядке фикстуры), так что сообщения всех
// чатов идут вперемешку. OFFSET — сколько сообщений уже отправлено.
import exec from "k6/execution";
import { SharedArray } from "k6/data";
import {
SUMMARY_THRESHOLDS,
SUMMARY_TREND_STATS,
WORK_DIR,
sendMessage,
summaryFiles,
syntheticText,
} from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const schedule = new SharedArray(
"schedule",
() => JSON.parse(open(`${WORK_DIR}/schedule.json`)),
);
const chats = [fixture.readChatId, ...fixture.bgChats.map((c) => c.id)];
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(
chats[schedule[n]],
fixture.tokens[sender],
syntheticText("p", n),
);
}
export function handleSummary(data) {
return summaryFiles(data);
}
+69
View File
@@ -0,0 +1,69 @@
// Пользователи и чаты стенда: читаемый (сценарий read), чат записи
// (сценарий write) и фоновые чаты неравномерных размеров (трек 2). Каждый
// пользователь регистрируется с паролем и входит по Basic; в фикстуру идут
// id и Bearer-токены, пароли — нет. Итог — fixture.json в рабочем каталоге:
// оркестратор удаляет его в конце прогона.
import { WORK_DIR, createChat, register } from "./lib.js";
const MEMBERS = Number(__ENV.MEMBERS || 10);
// чатов записи (Profile.write_chats): у прежних профилей один
const WRITE_CHATS = Math.max(1, Number(__ENV.WRITE_CHATS || 1));
// уровни фоновых чатов: «10x5000,100x400» — число чатов x сообщений в чате
const BACKGROUND = (__ENV.BACKGROUND || "")
.split(",")
.filter((tier) => tier !== "")
.map((tier) => tier.split("x").map(Number));
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "5m",
};
export function setup() {
// размер начинается с пустой базы, поэтому имени хватает времени
const stamp = Date.now().toString(36);
const tokens = {};
const reader = register(`b${stamp}_reader`, "Bench reader");
tokens[reader.id] = reader.token;
const memberIds = [];
for (let i = 0; i < MEMBERS; i++) {
const member = register(`b${stamp}_m${i}`, `Bench member ${i}`);
tokens[member.id] = member.token;
memberIds.push(member.id);
}
const everyone = [reader.id, ...memberIds];
// фоновые чаты в порядке уровней: номер чата в расписании наполнения —
// 1 + индекс в этом списке (0 — читаемый чат)
const bgChats = [];
for (const [count, size] of BACKGROUND) {
for (let i = 0; i < count; i++) {
const title = `bench bg ${size} #${i}`;
bgChats.push({ id: createChat(reader.token, title, everyone), size });
}
}
const readChatId = createChat(reader.token, "bench read", everyone);
// чаты записи со всеми пользователями: серии трека 1 делят вставки на
// WRITE_CHATS правых краёв индекса истории (решение 2 design change
// scaling-bench); прежние сценарии пишут в первый — writeChatId
const writeChatIds = [];
for (let i = 0; i < WRITE_CHATS; i++) {
const title = i === 0 ? "bench write" : `bench write #${i}`;
writeChatIds.push(createChat(reader.token, title, everyone));
}
return {
readerId: reader.id,
memberIds,
tokens,
readChatId,
writeChatId: writeChatIds[0],
writeChatIds,
bgChats,
};
}
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.tokens[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);
}
+87
View File
@@ -0,0 +1,87 @@
// Проверки восстановления через HTTP (трек 2), фаза — PHASE:
// - source: исходная база до восстановления;
// - stale: API на восстановленной базе, кэш ещё не очищен;
// - restored: после FLUSHALL.
// Во всех фазах — страницы этапа плана (plan_pages.json) и /users/me
// читателя; в stale и restored — ещё чат и пользователь «после backup».
// Ответы не проверяются здесь: статусы и элементы страниц пишутся в
// check-<фаза>.json, сверяет оркестратор. Токенов в итоге нет.
import http from "k6/http";
import {
API,
PAGE_LIMIT,
WORK_DIR,
authHeaders,
messageHeaders,
} from "./lib.js";
const PHASE = __ENV.PHASE;
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const pages = JSON.parse(open(`${WORK_DIR}/plan_pages.json`));
// after.json появляется только после активности «после backup»
const after = PHASE === "source"
? null
: JSON.parse(open(`${WORK_DIR}/after.json`));
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "5m",
};
function status(res) {
return res.status;
}
export function setup() {
const reader = { headers: authHeaders(fixture.tokens[fixture.readerId]) };
const result = {
phase: PHASE,
reader_me: status(http.get(`${API}/users/me`, reader)),
pages: pages.map((page) => {
const query = page.cursor === null
? `?limit=${PAGE_LIMIT}`
: `?limit=${PAGE_LIMIT}&cursor=${encodeURIComponent(page.cursor)}`;
const res = http.get(
`${API}/chats/${page.chat_id}/messages${query}`,
reader,
);
return {
chat: page.chat,
page: page.page,
status: res.status,
items: res.status === 200 ? res.json("items") : null,
};
}),
};
if (after !== null) {
const late = { headers: authHeaders(after.token) };
result.late_me = status(http.get(`${API}/users/me`, late));
result.after_chat_get = status(
http.get(`${API}/chats/${after.chatId}`, reader),
);
}
if (PHASE === "stale") {
// запись в чат, которого нет в восстановленной базе, а карточка — в
// кэше; с ключом, иначе 400 пришёл бы раньше проверки членства
result.after_chat_post = status(
http.post(
`${API}/chats/${after.chatId}/messages`,
JSON.stringify({ text: "written to a stale chat" }),
{
headers: messageHeaders(fixture.tokens[fixture.readerId]),
},
),
);
}
return result;
}
export default function () {}
export function handleSummary(data) {
return {
[`${WORK_DIR}/check-${PHASE}.json`]: JSON.stringify(data.setup_data),
};
}
+55
View File
@@ -0,0 +1,55 @@
// Повтор неподтверждённых записей фазы отказа с тем же ключом и тем же
// телом до 201 (решение 7 design change graceful-failover). Номера — в
// retry.json рабочего каталога; итог — retry-result.json: сколько
// получили 201 и какие нет. Ключ и текст строятся так же, как в
// failover.js, поэтому повтор после неопределённого исхода (kill, 504)
// возвращает сохранённое сообщение или пишет его впервые — без дубля.
import { sleep } from "k6";
import { WORK_DIR, sendMessage, syntheticText } from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const items = JSON.parse(open(`${WORK_DIR}/retry.json`)).items;
const RUN = __ENV.RUN;
const PHASE = Number(__ENV.PHASE);
const ATTEMPTS = 5;
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "5m",
};
export function setup() {
let ok = 0;
const failed = [];
for (const n of items) {
const sender = fixture.memberIds[n % fixture.memberIds.length];
let status = 0;
for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
const res = sendMessage(
fixture.writeChatId,
fixture.tokens[sender],
syntheticText(`f${PHASE}`, n),
`${RUN}.${PHASE}.${n}`,
);
status = res.status;
if (status === 201) {
break;
}
sleep(1);
}
if (status === 201) {
ok += 1;
} else {
failed.push({ n, status });
}
}
return { ok, failed };
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/retry-result.json`]: JSON.stringify(data.setup_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.tokens[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) };
}
+43
View File
@@ -0,0 +1,43 @@
// Сценарий 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,
fixture.tokens[sender],
syntheticText("w", n),
);
}
export function handleSummary(data) {
return summaryFiles(data);
}
+1341
View File
File diff suppressed because it is too large Load Diff
+1246
View File
File diff suppressed because it is too large Load Diff
+676
View File
@@ -0,0 +1,676 @@
"""Профиль поочерёдной замены реплик: разбор и расчёт без docker.
Оркестрирует прогон `run.py` (профили `rollout`, `rollout_quick`), здесь —
чистые функции на stdlib: строки `scripts/rolling-update.sh`, события
Docker проекта, журнал HAProxy, посекундная шкала с ответами старых и
новых реплик, шаги по каждой заменённой реплике и `summary.md`. Строки
k6 о запросах, отметки времени и перцентили — из `failover.py`. Все
отметки — часы ВМ Docker. Решение 8 design change `rolling-update`.
"""
import math
import re
from dataclasses import dataclass
from typing import Any
import failover
import resources as res
ROLLOUT_FIELDS = [
"label",
"from_commit",
"replicas",
"revision_before",
"revision_after",
"build_s",
"migrate_s",
"rollout_s",
"script_exit",
"requests",
"errors_before",
"codes_before",
"errors_during",
"codes_during",
"errors_after",
"codes_after",
"min_success",
"seconds_below",
"ok_rps_before",
"ok_rps_during_min",
"p95_before_ms",
"p95_during_max_ms",
"first_new_s",
"last_old_s",
"old_after_drain",
"writes",
"writes_failed",
"retried_ok",
"write_chat_messages",
"distinct_texts",
"dropped_iterations",
"flags",
]
REPLICA_FIELDS = [
"step",
"new_instance",
"new_slot",
"old_instance",
"old_slot",
"new_created_s",
"new_up_s",
"ready_s",
"drain_s",
"drain_timeout",
"stop_s",
"old_removed_s",
"slot_ready_s",
"replace_s",
"errors",
"after_drain",
]
TIMELINE_FIELDS = [
"second",
"writes_ok",
"writes_failed",
"reads_ok",
"reads_failed",
"codes",
"success",
"p50_ms",
"p95_ms",
"old_ok",
"new_ok",
"instances",
]
SCRIPT_TAG = "rolling-update:"
NEW_UP_RE = re.compile(
r"replica (?P<n>\d+)/\d+: new (?P<id>[0-9a-f]{12}) addr (?P<addr>\S+) "
r"slot (?P<slot>api-\d+) UP",
)
DRAIN_RE = re.compile(
r"replica (?P<n>\d+)/\d+: drain old (?P<id>[0-9a-f]{12}) addr "
r"(?P<addr>\S+) slot (?P<slot>api-\d+)",
)
DRAIN_TIMEOUT_RE = re.compile(r"replica (?P<n>\d+)/\d+: drain timeout")
# запас на отметку отправки k6 против момента drain в журнале LB, с
DRAIN_MARGIN_S = 0.2
BUILD_RE = re.compile(r"build done in (\d+)s")
MIGRATE_RE = re.compile(r"migrate done in (\d+)s")
# состояния слота в журнале HAProxy: ручные (drain, maint, возврат из
# maint) и по проверкам и DNS
LB_STATES = (
("enters drain state", "DRAIN"),
("is going DOWN for maintenance (No IP", "DNS_MAINT"),
("is going DOWN for maintenance", "MAINT"),
("leaving forced maintenance", "READY"),
("is UP", "UP"),
("is DOWN", "DOWN"),
)
@dataclass(frozen=True)
class ContainerEvent:
"""Событие Docker контейнера проекта: время, действие, полный ID."""
time: float
action: str
id: str
name: str
signal: str
@dataclass(frozen=True)
class SlotEvent:
time: float
slot: str
state: str
def script_lines(text: str) -> str:
"""Строки самого скрипта, без вывода сборки и миграции."""
return "\n".join(line for line in text.splitlines() if SCRIPT_TAG in line)
def script_error(text: str) -> str:
"""Последняя строка ошибки скрипта — в сообщение об отказе."""
errors = [
line
for line in text.splitlines()
if SCRIPT_TAG in line and "error:" in line
]
return errors[-1].split(SCRIPT_TAG, 1)[1].strip() if errors else ""
def parse_steps(text: str) -> list[dict[str, Any]]:
"""Шаги замены из строк скрипта: новая и старая реплика, их слоты."""
steps: dict[int, dict[str, Any]] = {}
for line in text.splitlines():
if match := NEW_UP_RE.search(line):
step = steps.setdefault(int(match["n"]), {})
step.update(
new_id=match["id"],
new_addr=match["addr"],
new_slot=match["slot"],
)
elif match := DRAIN_RE.search(line):
step = steps.setdefault(int(match["n"]), {})
step.update(
old_id=match["id"],
old_addr=match["addr"],
old_slot=match["slot"],
)
elif match := DRAIN_TIMEOUT_RE.search(line):
steps.setdefault(int(match["n"]), {})["drain_timeout"] = True
return [{"step": n, **steps[n]} for n in sorted(steps)]
def seconds(pattern: re.Pattern[str], text: str) -> int | None:
match = pattern.search(text)
return int(match.group(1)) if match else None
def parse_container_events(text: str) -> list[ContainerEvent]:
"""`docker events` в формате `время|действие|ID|имя|сигнал`.
Действие exec содержит команду, поэтому поля берутся с краёв.
"""
events = []
for line in text.splitlines():
parts = line.split("|")
if len(parts) < 5 or not parts[0].isdigit():
continue
events.append(
ContainerEvent(
time=int(parts[0]) / 1e9,
action="|".join(parts[1:-3]),
id=parts[-3],
name=parts[-2],
signal=parts[-1],
),
)
return sorted(events, key=lambda e: e.time)
def parse_slot_events(text: str) -> list[SlotEvent]:
"""Смена состояния слотов из журнала LB (`docker logs -t`); повтор
одной строки предупреждением в пределах миллисекунды отбрасывается."""
events: list[SlotEvent] = []
for line in text.splitlines():
match = failover.LB_RE.match(line)
if not match:
continue
state = next(
(name for marker, name in LB_STATES if marker in match["rest"]),
None,
)
if state is None:
continue
event = SlotEvent(
failover.parse_stamp(match["stamp"]),
match["slot"],
state,
)
if any(
e.slot == event.slot
and e.state == event.state
and abs(e.time - event.time) < 0.001
for e in events
):
continue
events.append(event)
return sorted(events, key=lambda e: e.time)
def container_event(
events: list[ContainerEvent],
short_id: str | None,
action: str,
since: float = 0.0,
) -> ContainerEvent | None:
if not short_id:
return None
return next(
(
e
for e in events
if e.id.startswith(short_id)
and e.action == action
and e.time >= since
),
None,
)
def slot_event(
events: list[SlotEvent],
slot: str | None,
state: str,
since: float | None,
) -> SlotEvent | None:
if slot is None or since is None:
return None
return next(
(
e
for e in events
if e.slot == slot and e.state == state and e.time >= since
),
None,
)
def start_time(events: list[ContainerEvent]) -> float | None:
"""Начало изменения стенда: создание контейнера миграции, без него —
первой новой реплики (миграции пропущены)."""
# контейнер сервиса migrate (scripts/rolling-update.sh пересоздаёт его
# на новом образе) или одноразовый migrate-run
migrate = next(
(e for e in events if e.action == "create" and "-migrate-" in e.name),
None,
)
if migrate is not None:
return migrate.time
create = next((e for e in events if e.action == "create"), None)
return create.time if create else None
def script_start(
events: list[ContainerEvent],
since: float,
ignore: frozenset[str] | set[str] = frozenset(),
) -> float | None:
"""Начало подготовки замены (решение 4 design change
`profile-resources`): первое `exec_start` в контейнер проекта не
раньше `since` (первого запроса) — первое обращение скрипта к LB.
Оркестратор во время нагрузки `docker exec` не делает, k6 — вне
проекта; `exec_start` проверок здоровья (`ignore` — их действия)
отбрасываются (найдено в apply: они тоже приходят каждые 5 с)."""
return next(
(
e.time
for e in events
if e.action.startswith("exec_start")
and e.action not in ignore
and e.time >= since
),
None,
)
def diff(later: Any, earlier: Any) -> float | None:
if later is None or earlier is None:
return None
return round(later.time - earlier.time, 2)
def since_t0(event: Any, t0: float) -> float | None:
return None if event is None else round(event.time - t0, 2)
def replica_rows(
steps: list[dict[str, Any]],
containers: list[ContainerEvent],
slots: list[SlotEvent],
requests: list[failover.Request],
t0: float,
) -> list[dict[str, Any]]:
"""Шаги каждой замены: от создания новой до возврата слота старой."""
rows = []
for step in steps:
created = container_event(containers, step.get("new_id"), "create")
started = container_event(containers, step.get("new_id"), "start")
up = slot_event(
slots,
step.get("new_slot"),
"UP",
started.time if started else None,
)
drain = slot_event(
slots,
step.get("old_slot"),
"DRAIN",
up.time if up else None,
)
maint = slot_event(
slots,
step.get("old_slot"),
"MAINT",
drain.time if drain else None,
)
kill = container_event(
containers,
step.get("old_id"),
"kill",
maint.time if maint else 0.0,
)
die = container_event(
containers,
step.get("old_id"),
"die",
kill.time if kill else 0.0,
)
destroy = container_event(containers, step.get("old_id"), "destroy")
ready = slot_event(
slots,
step.get("old_slot"),
"READY",
destroy.time if destroy else None,
)
window = [
r
for r in requests
if created is not None
and destroy is not None
and created.time <= r.start < destroy.time
]
# ответы старой реплики, отправленные после её вывода из LB: запрос
# мог уйти до команды drain на доли миллисекунды раньше отметки k6,
# поэтому запас DRAIN_MARGIN_S
after_drain = [
r
for r in requests
if drain is not None
and r.instance == step.get("old_id")
and r.start > drain.time + DRAIN_MARGIN_S
]
rows.append(
{
"step": step["step"],
"new_instance": step.get("new_id"),
"new_slot": step.get("new_slot"),
"old_instance": step.get("old_id"),
"old_slot": step.get("old_slot"),
"new_created_s": since_t0(created, t0),
"new_up_s": since_t0(up, t0),
"ready_s": diff(up, started),
"drain_s": diff(maint, drain),
"drain_timeout": bool(step.get("drain_timeout")),
"stop_s": diff(die, kill),
"old_removed_s": since_t0(destroy, t0),
"slot_ready_s": since_t0(ready, t0),
"replace_s": diff(destroy, created),
"errors": sum(1 for r in window if not r.ok),
"after_drain": len(after_drain),
},
)
return rows
def build_timeline(
requests: list[failover.Request],
t0: float,
old: set[str],
new: set[str],
) -> list[dict[str, Any]]:
"""Посекундная шкала от начала замены; секунда — по отправке.
`old` и `new` — `X-Instance-Id` (12 символов) реплик до и после.
"""
buckets: dict[int, list[failover.Request]] = {}
for request in requests:
buckets.setdefault(math.floor(request.start - t0), []).append(request)
rows = []
for second in range(min(buckets, default=0), max(buckets, default=-1) + 1):
group = buckets.get(second, [])
ok = [r for r in group if r.ok]
instances: dict[str, int] = {}
for request in ok:
instances[request.instance] = (
instances.get(request.instance, 0) + 1
)
durations = [r.duration_ms for r in ok]
rows.append(
{
"second": second,
"writes_ok": sum(1 for r in ok if r.kind == "w"),
"writes_failed": sum(
1 for r in group if r.kind == "w" and not r.ok
),
"reads_ok": sum(1 for r in ok if r.kind == "r"),
"reads_failed": sum(
1 for r in group if r.kind == "r" and not r.ok
),
"codes": failover.codes(group),
"success": round(len(ok) / len(group), 4) if group else None,
"p50_ms": failover.percentile(durations, 0.5),
"p95_ms": failover.percentile(durations, 0.95),
"old_ok": sum(1 for r in ok if r.instance in old),
"new_ok": sum(1 for r in ok if r.instance in new),
"instances": " ".join(
f"{key}:{value}"
for key, value in sorted(instances.items())
),
},
)
return rows
def analyze(
requests: list[failover.Request],
timeline: list[dict[str, Any]],
replicas: list[dict[str, Any]],
*,
t0: float,
end: float,
old: set[str],
new: set[str],
threshold: float,
) -> dict[str, Any]:
"""Величины прогона: окна до, во время и после замены (решение 8)."""
def ended(request: failover.Request) -> float:
return request.start + request.duration_ms / 1000
before = [r for r in requests if ended(r) < t0]
during = [r for r in requests if ended(r) >= t0 and r.start < end]
after = [r for r in requests if r.start >= end]
window = math.ceil(end - t0)
during_rows = [row for row in timeline if 0 <= row["second"] < window]
before_rows = [row for row in timeline if row["second"] < 0][2:]
# после вывода из LB старая реплика запросов получать не должна
old_after_drain = sum(r["after_drain"] for r in replicas)
new_ok = [r.start for r in requests if r.ok and r.instance in new]
old_ok = [r.start for r in requests if r.ok and r.instance in old]
p95_during = [
row["p95_ms"] for row in during_rows if row["p95_ms"] is not None
]
flags = []
if any(not r.ok for r in requests):
flags.append("errors")
if old_after_drain:
flags.append("old_after_drain")
return {
"rollout_s": round(end - t0, 2),
"requests": len(requests),
"errors_before": sum(1 for r in before if not r.ok),
"codes_before": failover.codes(before),
"errors_during": sum(1 for r in during if not r.ok),
"codes_during": failover.codes(during),
"errors_after": sum(1 for r in after if not r.ok),
"codes_after": failover.codes(after),
"min_success": min(
(
row["success"]
for row in during_rows
if row["success"] is not None
),
default=None,
),
"seconds_below": sum(
1
for row in during_rows
if row["success"] is not None and row["success"] < threshold
),
"ok_rps_before": (
round(
sum(row["writes_ok"] + row["reads_ok"] for row in before_rows)
/ len(before_rows),
1,
)
if before_rows
else None
),
"ok_rps_during_min": min(
(row["writes_ok"] + row["reads_ok"] for row in during_rows),
default=None,
),
"p95_before_ms": failover.percentile(
[r.duration_ms for r in before if r.ok],
0.95,
),
"p95_during_max_ms": max(p95_during, default=None),
"first_new_s": round(min(new_ok) - t0, 2) if new_ok else None,
"last_old_s": round(max(old_ok) - t0, 2) if old_ok else None,
"old_after_drain": old_after_drain,
"writes": sum(1 for r in requests if r.kind == "w"),
"writes_failed": sum(
1 for r in requests if r.kind == "w" and not r.ok
),
"flags": " ".join(flags),
}
fmt = failover.fmt
def render_summary(
meta: dict[str, Any],
row: dict[str, Any] | None,
replicas: list[dict[str, Any]],
timeline: list[dict[str, Any]],
resources: list[dict[str, Any]] | None = None,
) -> str:
"""`summary.md` профиля замены: условия, итог, шаги по репликам,
контейнеры до и после, шкала вокруг замены; с `resources` (строки
`resources.csv`) — ещё ресурсы по окнам замены."""
profile = meta["profile"]
info = meta.get("rollout", {})
lines = [
f"# Поочерёдная замена реплик под нагрузкой: метка `{meta['label']}`",
"",
f"- Статус: **{meta['status']}**"
+ (f" ({meta['reason']})" if meta.get("reason") else ""),
f"- Commit: `{meta['git']['commit']}`"
+ (" + незакоммиченные изменения" if meta["git"]["dirty"] else ""),
f"- Профиль `{profile['name']}`: {profile['replicas']} реплики за "
f"HAProxy; замена с образа commit `{info.get('from_commit')}` на "
"образ текущего checkout (`scripts/rolling-update.sh`); "
f"{profile['failover_write_rate']} записей с ключом и "
f"{profile['failover_read_rate']} чтений страницы истории в "
"секунду (k6, постоянная интенсивность); окна: "
f"{profile['rollout_before_s']} с до запуска скрипта, бюджет "
f"замены {profile['rollout_budget_s']} с, ещё "
f"{profile['rollout_after_s']} с; порог доли успешных "
f"{profile['failover_success']:.0%}",
failover.limits_line(profile),
"- Посторонние контейнеры в VM во время замера: "
+ (", ".join(meta.get("other_containers") or []) or "нет"),
"",
"Время — секунды на часах ВМ Docker от начала замены (создание "
"контейнера миграции). Шаги — события Docker (создание и старт "
"новой реплики, SIGTERM, выход и удаление старой) и журнал HAProxy "
"(`UP` новой, `drain` и `maint` старой, возврат слота в `ready`). "
"Ответы — отметки k6 при отправке; «старые» и «новые» — по "
"`X-Instance-Id` контейнеров до и после замены. Окно замены — от "
"начала до удаления последней старой реплики. Сверка — после "
"повтора неуспешных записей с тем же ключом: сообщений в чате "
"записи и разных текстов столько, сколько отправлено ключей.",
"",
]
if row:
lines += [
"| Замена, с | Сборка / миграция, с | Ревизия до → после | "
"Ошибки до / во время / после | Мин. доля успешных | Секунд ниже "
"порога | Успешных в секунду: до / мин. во время | p95: до / "
"макс. во время, мс | Первый ответ новой / последний старой, с | "
"Ответов старых после дренажа | Повтор записей | "
"Сообщений = ключей | Пометки |",
"|---|---|---|---|---|---|---|---|---|---|---|---|---|",
f"| {fmt(row['rollout_s'])} | {fmt(row['build_s'])} / "
f"{fmt(row['migrate_s'])} | `{fmt(row['revision_before'])}` → "
f"`{fmt(row['revision_after'])}` | {row['errors_before']} / "
f"{row['errors_during']}"
+ (f" ({row['codes_during']})" if row["codes_during"] else "")
+ f" / {row['errors_after']} | {fmt(row['min_success'])} | "
f"{row['seconds_below']} | {fmt(row['ok_rps_before'])} / "
f"{fmt(row['ok_rps_during_min'])} | {fmt(row['p95_before_ms'])} / "
f"{fmt(row['p95_during_max_ms'])} | {fmt(row['first_new_s'])} / "
f"{fmt(row['last_old_s'])} | {row['old_after_drain']} | "
f"{row['writes_failed']} → {fmt(row['retried_ok'])} | "
f"{fmt(row['write_chat_messages'])} = "
f"{fmt(row['distinct_texts'])} | {fmt(row['flags'])} |",
"",
]
if replicas:
lines += [
"## Шаги по репликам",
"",
"| Шаг | Новая (слот) | Старая (слот) | Новая создана, с | Новая "
"`UP`, с | Старт → `UP`, с | Дренаж, с | Остановка, с | Старая "
"удалена, с | Слот `ready`, с | Замена целиком, с | Ошибок за "
"шаг | Ответов старой после дренажа |",
"|---|---|---|---|---|---|---|---|---|---|---|---|---|",
]
for r in replicas:
drain = fmt(r["drain_s"]) + (
" (срок)" if r["drain_timeout"] else ""
)
lines.append(
f"| {r['step']} | `{fmt(r['new_instance'])}` "
f"({fmt(r['new_slot'])}) | `{fmt(r['old_instance'])}` "
f"({fmt(r['old_slot'])}) | {fmt(r['new_created_s'])} | "
f"{fmt(r['new_up_s'])} | {fmt(r['ready_s'])} | {drain} | "
f"{fmt(r['stop_s'])} | {fmt(r['old_removed_s'])} | "
f"{fmt(r['slot_ready_s'])} | {fmt(r['replace_s'])} | "
f"{r['errors']} | {r['after_drain']} |",
)
lines.append("")
if resources:
lines += res.render_rollout(resources)
for title, key in (
("до", "containers_before"),
("после", "containers_after"),
):
items = info.get(key) or []
if not items:
continue
lines += [
f"## Контейнеры `api` {title} замены",
"",
"| Контейнер | `X-Instance-Id` | Образ (тег) | Конфигурация образа |",
"|---|---|---|---|",
]
lines += [
f"| {c['name']} | `{c['instance']}` | `{c['tag']}` | "
f"`{c['image'][:19]}…` |"
for c in items
]
lines.append("")
if timeline:
end = math.ceil(row["rollout_s"]) if row else 0
shown = [r for r in timeline if -3 <= r["second"] <= end + 3]
lines += [
"## Шкала вокруг замены",
"",
"Полная шкала — `timeline.csv`.",
"",
"| с от начала | Записи ok / ош | Чтения ok / ош | Коды ошибок | "
"Доля успешных | p50 / p95, мс | Старые / новые ok | Ответы "
"реплик |",
"|---|---|---|---|---|---|---|---|",
]
for r in shown:
lines.append(
f"| {r['second']} | {r['writes_ok']} / {r['writes_failed']} | "
f"{r['reads_ok']} / {r['reads_failed']} | {fmt(r['codes'])} | "
f"{fmt(r['success'])} | {fmt(r['p50_ms'])} / "
f"{fmt(r['p95_ms'])} | {r['old_ok']} / {r['new_ok']} | "
f"{fmt(r['instances'])} |",
)
lines.append("")
if meta.get("host_warnings"):
lines += ["## Предупреждения о хосте", ""]
lines += [f"- {w}" for w in meta["host_warnings"]]
lines.append("")
return "\n".join(lines)
+5891
View File
File diff suppressed because it is too large Load Diff
+147
View File
@@ -0,0 +1,147 @@
#!/usr/bin/env bash
# Сэмплер стенда (решение 7 design change scaling-bench, решение 1 design
# change profile-resources). Работает только внутри контейнера
# mtusi-bench-sampler (образ PostgreSQL стенда, --cgroupns host), не на
# хосте: его запускает bench/run.py (Stand.start_sampler). Раз в интервал
# пишет в /work/samples.log строки с отметкой часов ВМ в наносекундах
# (одна отметка на весь тик):
# cg <нс> <роль> <id12> <usage_usec> <nr_periods> <nr_throttled>
# <throttled_usec> <memory.current> <cpu.pressure some total>
# cg <нс> <роль> <id12> missing — нет каталога cgroup
# vm <нс> <занято jiffies> <всего jiffies> <PSI CPU some total, мкс>
# lb <нс> # <заголовок CSV статистики HAProxy> / lb <нс> api,<строка>
# lb <нс> missing — статистика недоступна
# Режимы — по второму аргументу:
# list (серии трека 1): <интервал, с> <роль>=<полный id контейнера>…
# Сеть mtusi-bench. Строки cg заданных контейнеров, vm и lb; в фоне
# psql с \watch пишет /work/pg-samples.log (одно соединение на всю
# ячейку): act, db, wal, io — разбор в bench/scaling.py
# (parse_samples).
# scan (профили failover и rollout): <интервал, с> scan
# Контейнер без сети. На каждом тике — обход /sys/fs/cgroup/docker/*/
# (только каталоги с именем из 64 hex — контейнеры), строка
# `cg <нс> - <id12> …` на каждый; роли назначает оркестратор. Строки
# vm — как в list. Ни psql, ни опроса LB: наблюдатель не обращается к
# стенду.
set -u
interval=$1
shift
mode=list
if [[ ${1:-} == scan ]]; then
mode=scan
shift
fi
roles=()
ids=()
for arg in "$@"; do
roles+=("${arg%%=*}")
ids+=("${arg#*=}")
done
if [[ $mode == list ]]; then
export PGPASSWORD="$POSTGRES_PASSWORD"
psql "host=postgres user=$POSTGRES_USER dbname=$POSTGRES_DB \
application_name=bench-sampler" -XAtq -F '|' >/work/pg-samples.log 2>&1 <<SQL &
WITH t AS (
SELECT (extract(epoch FROM clock_timestamp()) * 1000)::bigint AS ts
)
SELECT 'act', (SELECT ts FROM t), coalesce(host(client_addr), '-'),
coalesce(state, '-'), coalesce(wait_event_type, 'CPU'),
coalesce(wait_event, '-'), count(*)
FROM pg_stat_activity
WHERE backend_type = 'client backend' AND pid <> pg_backend_pid()
GROUP BY 3, 4, 5, 6
UNION ALL
SELECT 'db', (SELECT ts FROM t), xact_commit::text, xact_rollback::text,
sessions::text, sessions_fatal::text, numbackends::bigint
FROM pg_stat_database WHERE datname = current_database()
UNION ALL
SELECT 'wal', (SELECT ts FROM t), wal_records::text, wal_fpi::text,
wal_bytes::text, NULL, NULL
FROM pg_stat_wal
UNION ALL
SELECT 'io', (SELECT ts FROM t), coalesce(sum(writes), 0)::text,
coalesce(sum(fsyncs), 0)::text, NULL, NULL, NULL
FROM pg_stat_io WHERE object = 'wal'
\watch $interval
SQL
fi
exec 4>>/work/samples.log
cg_line() {
local role=$1 id=$2 dir=/sys/fs/cgroup/docker/$2
local key val usage= periods=0 throttled=0 thr_usec=0 mem= psi=0 rest=
if [[ ! -r $dir/cpu.stat ]]; then
printf 'cg %s %s %s missing\n' "$ns" "$role" "${id:0:12}" >&4
return
fi
# каталог может пропасть между проверкой и чтением (контейнер
# остановлен посреди тика): тогда тоже missing, а не строка нулей
{
while read -r key val; do
case $key in
usage_usec) usage=$val ;;
nr_periods) periods=$val ;;
nr_throttled) throttled=$val ;;
throttled_usec) thr_usec=$val ;;
esac
done <"$dir/cpu.stat"
read -r mem <"$dir/memory.current"
read -r _ _ _ _ rest <"$dir/cpu.pressure"
} 2>/dev/null
if [[ -z $usage || -z $mem ]]; then
printf 'cg %s %s %s missing\n' "$ns" "$role" "${id:0:12}" >&4
return
fi
psi=${rest#total=}
printf 'cg %s %s %s %s %s %s %s %s %s\n' "$ns" "$role" "${id:0:12}" \
"$usage" "$periods" "$throttled" "$thr_usec" "$mem" "$psi" >&4
}
vm_line() {
local _cpu user nice system idle iowait irq softirq steal rest total
read -r _cpu user nice system idle iowait irq softirq steal rest </proc/stat
total=$((user + nice + system + idle + iowait + irq + softirq + steal))
read -r _ _ _ _ rest </proc/pressure/cpu
printf 'vm %s %s %s %s\n' "$ns" "$((total - idle - iowait))" "$total" \
"${rest#total=}" >&4
}
lb_lines() {
local line
if ! exec 3<>/dev/tcp/haproxy/8404 2>/dev/null; then
printf 'lb %s missing\n' "$ns" >&4
return
fi
printf 'GET /stats;csv HTTP/1.0\r\n\r\n' >&3
while IFS= read -r line; do
line=${line%$'\r'}
case $line in
"# "* | api,*) printf 'lb %s %s\n' "$ns" "$line" >&4 ;;
esac
done <&3
exec 3<&-
}
hex64='^[0-9a-f]{64}$'
while :; do
# EPOCHREALTIME bash 5 — часы ВМ без запуска date
ns=${EPOCHREALTIME/./}000
if [[ $mode == scan ]]; then
for dir in /sys/fs/cgroup/docker/*/; do
dir=${dir%/}
id=${dir##*/}
[[ $id =~ $hex64 ]] && cg_line - "$id"
done
else
for i in "${!ids[@]}"; do
cg_line "${roles[$i]}" "${ids[$i]}"
done
fi
vm_line
[[ $mode == list ]] && lb_lines
sleep "$interval"
done
+1776
View File
File diff suppressed because it is too large Load Diff
+67
View File
@@ -0,0 +1,67 @@
# Шаблон 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
# сколько секунд uvicorn держит простаивающее keep-alive соединение;
# больше, чем HAProxy держит простаивающее соединение с репликой (timeout
# http-keep-alive 10 с, http-reuse never в infra/haproxy/haproxy.cfg):
# простаивающее соединение закрывает LB
keep_alive_seconds = 60
# instance_id (X-Instance-Id) здесь не задавать: config.toml общий у всех
# реплик, а значение должно различаться. Без него берётся hostname
# процесса (в compose — короткий ID контейнера); в консоли его можно
# заменить окружением APP__INSTANCE_ID.
[database]
# Адрес, порт, пользователь, пароль и имя базы приходят из .env (мосты к
# POSTGRES_*) и из environment compose; здесь их не указывать.
pool_size = 10
# 0 — без переполнения: соединения сверх pool_size переоткрывались бы
max_overflow = 0
# секунды ожидания свободного соединения пула
pool_timeout_seconds = 5
# секунды на установку соединения
connect_timeout_seconds = 3
# миллисекунды, серверный statement_timeout; 0 — без ограничения
statement_timeout_ms = 5000
# секунды на всю работу запроса с БД: зависший сервер, обрыв сети
request_timeout_seconds = 6
# миллисекунды, серверный idle_in_transaction_session_timeout: транзакцию
# замороженной реплики PostgreSQL прерывает и снимает её блокировки.
# 0 — без ограничения, иначе больше request_timeout_seconds
idle_in_transaction_timeout_ms = 10000
[auth]
# секунды жизни сессии с момента входа (контрактное имя
# SESSION_TTL_SECONDS); короткий срок для проверки истечения — окружением
# AUTH__SESSION_TTL_SECONDS=2
session_ttl_seconds = 3600
# сколько хэшей пароля Argon2id считается одновременно: 64 MiB на каждый
kdf_concurrency = 4
[cache]
# Адрес, порт и пароль Valkey приходят из .env (мосты к VALKEY_*) и из
# environment compose; здесь их не указывать.
# секунды на всю команду Valkey (ожидание пула, соединение, ответ);
# дольше — запрос идёт в PostgreSQL
timeout_seconds = 0.2
# секунды, на которые кэш пропускается после отказа Valkey
retry_after_seconds = 5
# секунды жизни карточки чата в кэше
chat_ttl_seconds = 3600
# соединений в пуле клиента Valkey
max_connections = 10
[idempotency]
# секунды, в течение которых повтор POST сообщения с тем же
# Idempotency-Key возвращает исходный результат (имя skeleton
# IDEMPOTENCY_TTL_SECONDS); контракт требует не меньше 86400 — 24 ч.
# Короткий срок для проверки — окружением IDEMPOTENCY__TTL_SECONDS=2
ttl_seconds = 86400
+214
View File
@@ -0,0 +1,214 @@
# Стенд лабы 3: HAProxy — единственная точка входа, за ним API ×
# API_REPLICAS; PostgreSQL, Valkey (кэш) и одноразовые миграции.
# Правила — .claude/rules/docker.md и balancer.md. Значения — из .env
# (шаблон .env.example); литералы только у адреса публикации 127.0.0.1 и
# у режима docker. Имя проекта меняется в каждой лабе: от него зависят
# имена volumes, и стенд не должен подключаться к данным прошлой лабы.
name: mtusi-lab3
# окружение по сервисам: секреты получают только те, кому они нужны.
# PostgreSQL — api и migrate
x-db-env: &db-env
APP__RUN_MODE: docker
DATABASE__HOST: ${POSTGRES_HOST:-postgres}
DATABASE__PORT: ${POSTGRES_PORT:-5432}
DATABASE__USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env_setup}
DATABASE__PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env_setup}
DATABASE__NAME: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env_setup}
# Valkey — только api
x-cache-env: &cache-env
CACHE__HOST: ${VALKEY_HOST:-valkey}
CACHE__PORT: ${VALKEY_PORT:-6379}
CACHE__PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example}
# config.toml только на чтение, длинной записью: без файла запуск падает,
# а не создаёт на хосте каталог config.toml/
x-config-toml: &config-toml
type: bind
source: ./config.toml
target: /app/config.toml
read_only: true
bind:
create_host_path: false
services:
postgres:
image: postgres:18.6-trixie@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env_setup}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env_setup}
POSTGRES_DB: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env_setup}
# порт самого сервера; его же берут pg_isready и psql в контейнере
PGPORT: ${POSTGRES_PORT:-5432}
ports:
# только localhost: к нему подключается приложение в console
- "127.0.0.1:${POSTGRES_OUT_PORT:-5433}:${POSTGRES_PORT:-5432}"
volumes:
# с 18.x данные в /var/lib/postgresql/18/docker, volume образа —
# весь /var/lib/postgresql (Config.Volumes)
- postgres_data:/var/lib/postgresql
networks:
default:
# любое значение POSTGRES_HOST указывает на этот сервис
aliases:
- ${POSTGRES_HOST:-postgres}
healthcheck:
# по TCP, а не через сокет: при инициализации образ поднимает
# временный сервер только на сокете, и проверка через сокет
# сказала бы «готов» раньше времени. $$ — переменная контейнера
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
interval: 5s
timeout: 3s
retries: 10
start_period: 30s
start_interval: 1s
deploy:
resources:
limits:
# соединения реплик: API_REPLICAS × pool_size (переполнения нет,
# max_overflow 0) + migrate ≤ max_connections (100): 2 × 10 + 1,
# при поочерёдной замене 3 × 10 + 1; расчёт — REPORT.md
cpus: "2.0"
memory: 1G
# кэш карточек чатов: без volume, persistence выключен в valkey.conf —
# после рестарта кэш пуст, данные остаются в PostgreSQL
valkey:
image: valkey/valkey:9.1.2-trixie@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd
restart: unless-stopped
# $$ — переменные контейнера: пароль не попадает в command литералом.
# Через docker-entrypoint.sh образа: он запускает сервер не от root
command:
- sh
- -c
- exec docker-entrypoint.sh valkey-server /usr/local/etc/valkey/valkey.conf --port "$$VALKEY_PORT" --requirepass "$$VALKEY_PASSWORD"
environment:
VALKEY_PORT: ${VALKEY_PORT:-6379}
VALKEY_PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example}
# пароль для valkey-cli в контейнере (healthcheck), без -a в команде
VALKEYCLI_AUTH: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example}
ports:
# только localhost: к нему подключается приложение в console
- "127.0.0.1:${VALKEY_OUT_PORT:-6380}:${VALKEY_PORT:-6379}"
volumes:
- type: bind
source: ./infra/valkey/valkey.conf
target: /usr/local/etc/valkey/valkey.conf
read_only: true
bind:
create_host_path: false
networks:
default:
# любое значение VALKEY_HOST указывает на этот сервис
aliases:
- ${VALKEY_HOST:-valkey}
healthcheck:
# PONG только после AUTH: проверяет и запуск, и пароль
test: ["CMD-SHELL", 'test "$$(valkey-cli -p "$$VALKEY_PORT" ping)" = PONG']
interval: 5s
timeout: 3s
retries: 10
start_period: 10s
start_interval: 1s
deploy:
resources:
limits:
# maxmemory 64mb в valkey.conf плюс накладные
cpus: "0.5"
memory: 128M
# миграции — один раз до реплик, сами реплики их не запускают
migrate:
# образ собирает сервис api (make run_docker, make test_isolated)
image: mtusi-messenger:lab3
pull_policy: never
command: ["alembic", "upgrade", "head"]
restart: "no"
# только PostgreSQL: пароль Valkey миграциям не нужен
environment: *db-env
volumes:
- *config-toml
depends_on:
postgres:
condition: service_healthy
deploy:
resources:
limits:
cpus: "0.5"
memory: 256M
# реплики API: порты не публикуются, фиксированного имени контейнера
# нет (мешало бы масштабированию) — запросы идут только через haproxy; X-Instance-Id — hostname, то есть
# короткий ID контейнера. Разовая подмена числа — make replicas
# API_REPLICAS=N
api:
build: .
image: mtusi-messenger:lab3
restart: unless-stopped
environment:
<<: [*db-env, *cache-env]
APP__PORT: ${APP__PORT:-8080}
volumes:
- *config-toml
depends_on:
postgres:
condition: service_healthy
# без кэша API работает, но в штатном стенде он есть с первого запроса
valkey:
condition: service_healthy
migrate:
condition: service_completed_successfully
# healthcheck — из образа; SIGKILL не раньше, чем через 10 с
stop_grace_period: 10s
deploy:
replicas: ${API_REPLICAS:-2}
resources:
limits:
# один event loop занимает не больше 1 CPU. Argon2id (p=4, до
# kdf_concurrency хэшей сразу) взял бы больше: под лимитом вход
# медленнее в 4–5 раз, осознанно (REPORT.md, «Ограничения»).
# Память: Argon2id 4 × 64 MiB + интерпретатор ≈ 350 МБ
cpus: "1.0"
memory: 512M
# единственная точка входа: реплики находит через DNS Docker, проверяет
# /health/ready; конфиг — infra/haproxy/haproxy.cfg. Секретов не получает
haproxy:
image: haproxy:3.4.6-trixie@sha256:e273915691a8eab3f105bf3e39fd4c29a4ecf334e33421903b5589d25e14db26
restart: unless-stopped
environment:
# порт реплик и самого LB внутри сети: тот же APP__PORT
API_PORT: ${APP__PORT:-8080}
ports:
# только localhost: стенд учебный; API на хосте доступно только так
- "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"
volumes:
- type: bind
source: ./infra/haproxy/haproxy.cfg
target: /usr/local/etc/haproxy/haproxy.cfg
read_only: true
bind:
create_host_path: false
# make stop гасит LB раньше реплик, make run_docker поднимает после них
depends_on:
- api
healthcheck:
# healthy — через LB можно обслужить запрос: /lb/ready отвечает 200,
# пока есть хотя бы одна готовая реплика. curl в образе нет, bash есть
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8404 && printf 'GET /lb/ready HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"]
interval: 5s
timeout: 3s
retries: 3
start_period: 10s
start_interval: 1s
deploy:
resources:
limits:
# nbthread 1 в haproxy.cfg
cpus: "1.0"
memory: 256M
volumes:
postgres_data:
+47
View File
@@ -0,0 +1,47 @@
# Пароли и токены в PostgreSQL на стенде лабы 3
| | |
|---|---|
| Спеки | `users` «Хэш в БД», `sessions` «Токена нет в хранилище» (исключения в `student-tests/spec_coverage.py`: нужен доступ к таблицам PostgreSQL, а тесты ходят по HTTP) |
| Change | `fix-known-issues`, задача 6.3 |
| Дата | 2026-10-13, ~14:37 UTC |
| Commit | команда драйвера — `5372d20`; код приложения на стенде — `edad1fd` (после `make rolling_update`) |
| Стенд | `make run_docker`: проект `mtusi-lab3`, HAProxy на `127.0.0.1:8080` перед двумя репликами `api` (1 CPU / 512 МиБ каждая), PostgreSQL 2 CPU / 1 ГиБ, Valkey 0,5 CPU / 128 МиБ |
| Хост | Docker Desktop 29.8.2, macOS arm64; ВМ Docker: 12 CPU, 7,7 GiB RAM |
| Команда | `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 auth-storage` |
Как устроена `auth-storage` (design change `fix-known-issues`, решение
1): синтетический пароль P (случайный, 36 символов, с `:` и кириллицей)
и токен T живут только в памяти процесса команды. Два пользователя
регистрируются с одним P через LB, первый входит по Basic и получает T.
Затем `psql` в контейнере PostgreSQL: префикс строки `password_hash` до
соли (31 символ — алгоритм, версия и параметры) и длина у обоих,
неравенство хэшей, строки `sessions` с `token_hash = SHA-256(T)`. И
`pg_dump --data-only` рабочей базы — в память команды: ищутся T (текстом
и в hex) и P. Дамп никуда не пишется, хэши целиком, T и P не
печатаются.
```text
$ python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 auth-storage
users auth_… and auth_…: same password P (36 characters with ':' and Cyrillic)
password_hash $argon2id$v=19$m=65536,t=3,p=4$… (97 chars)
password_hash $argon2id$v=19$m=65536,t=3,p=4$… (97 chars)
hashes differ: t
session of the first user: token T (43 characters); rows of sessions with token_hash = SHA-256(T): 1, octet_length 32
pg_dump --data-only: 7 COPY blocks; T as text: no, T in hex: no, P as text: no
PASS: only Argon2id strings and SHA-256 of the token are stored
```
Код выхода 0.
## Вывод
- **Хэш в БД.** В строке пользователя — строка Argon2id
(`$argon2id$v=19$m=65536,t=3,p=4$`, дальше соль и хэш, всего 97
символов), а не пароль. У двух пользователей с одинаковым паролем
хранимые значения разные: соль своя у каждого. P нет ни в одной
строке ни одной таблицы (дамп всех 7 таблиц с данными).
- **Токена нет в хранилище.** Сессия найдена по `token_hash` — 32 байта
SHA-256 от T, ровно одна строка. Самого T нет ни в одной строке ни
текстом, ни в hex.
- Пересъёмка в следующей лабе — та же команда на её стенде.
@@ -0,0 +1,54 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 560" width="720" height="560" font-family='system-ui, -apple-system, "Segoe UI", sans-serif'>
<rect x="0" y="0" width="720" height="560" fill="#fcfcfb"/>
<text x="24.0" y="30.0" font-size="16" font-weight="600" fill="#52514e" text-anchor="start">Серия a: CPU по компонентам на R*</text>
<text x="24.0" y="52.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">Медиана занятых ядер по ячейкам на ступени R*;</text>
<text x="24.0" y="70.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">«остальное в ВМ» — загрузка ВМ сверх контейнеров стенда</text>
<line x1="64.0" y1="476.0" x2="696.0" y2="476.0" stroke="#e1e0d9" stroke-width="1"/>
<text x="56.0" y="480.0" font-size="12" font-weight="400" fill="#898781" text-anchor="end">0</text>
<line x1="64.0" y1="360.7" x2="696.0" y2="360.7" stroke="#e1e0d9" stroke-width="1"/>
<text x="56.0" y="364.7" font-size="12" font-weight="400" fill="#898781" text-anchor="end">5</text>
<line x1="64.0" y1="245.3" x2="696.0" y2="245.3" stroke="#e1e0d9" stroke-width="1"/>
<text x="56.0" y="249.3" font-size="12" font-weight="400" fill="#898781" text-anchor="end">10</text>
<line x1="64.0" y1="130.0" x2="696.0" y2="130.0" stroke="#e1e0d9" stroke-width="1"/>
<text x="56.0" y="134.0" font-size="12" font-weight="400" fill="#898781" text-anchor="end">15</text>
<line x1="64.0" y1="476.0" x2="696.0" y2="476.0" stroke="#c3c2b7" stroke-width="1"/>
<line x1="64.0" y1="199.2" x2="696.0" y2="199.2" stroke="#52514e" stroke-width="1.5" stroke-dasharray="6 4"/>
<text x="692.0" y="193.2" font-size="12" font-weight="400" fill="#52514e" text-anchor="end">12 vCPU ВМ</text>
<line x1="64.0" y1="337.6" x2="696.0" y2="337.6" stroke="#898781" stroke-width="1.5" stroke-dasharray="2 4"/>
<text x="692.0" y="331.6" font-size="12" font-weight="400" fill="#52514e" text-anchor="end">6 производительных ядер хоста</text>
<g><title>1x4: реплики API 0.95 ядра (R* 630 запросов/с)</title><rect x="157.3" y="454.1" width="24.0" height="21.9" fill="#2a78d6"/></g>
<g><title>1x4: PostgreSQL 0.18 ядра (R* 630 запросов/с)</title><rect x="157.3" y="449.9" width="24.0" height="2.2" fill="#eb6834"/></g>
<g><title>1x4: k6 0.15 ядра (R* 630 запросов/с)</title><rect x="157.3" y="445.3" width="24.0" height="1.4" fill="#e87ba4"/></g>
<g><title>1x4: остальное в ВМ 0.49 ядра (R* 630 запросов/с)</title><path d="M157.3,443.3 L157.3,438.1 Q157.3,434.1 161.3,434.1 L177.3,434.1 Q181.3,434.1 181.3,438.1 L181.3,443.3 Z" fill="#008300"/></g>
<text x="169.3" y="428.1" font-size="12" font-weight="400" fill="#0b0b0b" text-anchor="middle">1.8</text>
<text x="169.3" y="494.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">1x4</text>
<text x="169.3" y="510.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">R* 630</text>
<g><title>2x2: реплики API 1.94 ядра (R* 1101 запросов/с)</title><rect x="368.0" y="431.4" width="24.0" height="44.6" fill="#2a78d6"/></g>
<g><title>2x2: PostgreSQL 0.38 ядра (R* 1101 запросов/с)</title><rect x="368.0" y="422.6" width="24.0" height="6.7" fill="#eb6834"/></g>
<g><title>2x2: k6 0.26 ядра (R* 1101 запросов/с)</title><rect x="368.0" y="414.4" width="24.0" height="4.0" fill="#e87ba4"/></g>
<g><title>2x2: остальное в ВМ 0.55 ядра (R* 1101 запросов/с)</title><path d="M368.0,412.4 L368.0,405.7 Q368.0,401.7 372.0,401.7 L388.0,401.7 Q392.0,401.7 392.0,405.7 L392.0,412.4 Z" fill="#008300"/></g>
<text x="380.0" y="395.7" font-size="12" font-weight="400" fill="#0b0b0b" text-anchor="middle">3.2</text>
<text x="380.0" y="494.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">2x2</text>
<text x="380.0" y="510.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">R* 1101</text>
<g><title>4x1: реплики API 3.82 ядра (R* 1819 запросов/с)</title><rect x="578.7" y="387.8" width="24.0" height="88.2" fill="#2a78d6"/></g>
<g><title>4x1: PostgreSQL 0.78 ядра (R* 1819 запросов/с)</title><rect x="578.7" y="369.9" width="24.0" height="15.9" fill="#eb6834"/></g>
<g><title>4x1: HAProxy 0.15 ядра (R* 1819 запросов/с)</title><rect x="578.7" y="366.5" width="24.0" height="1.4" fill="#1baf7a"/></g>
<g><title>4x1: k6 0.49 ядра (R* 1819 запросов/с)</title><rect x="578.7" y="354.1" width="24.0" height="9.3" fill="#e87ba4"/></g>
<g><title>4x1: остальное в ВМ 0.52 ядра (R* 1819 запросов/с)</title><path d="M578.7,352.1 L578.7,346.1 Q578.7,342.1 582.7,342.1 L598.7,342.1 Q602.7,342.1 602.7,346.1 L602.7,352.1 Z" fill="#008300"/></g>
<text x="590.7" y="336.1" font-size="12" font-weight="400" fill="#0b0b0b" text-anchor="middle">5.8</text>
<text x="590.7" y="494.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">4x1</text>
<text x="590.7" y="510.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">R* 1819</text>
<text x="16.0" y="303.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="middle" transform="rotate(-90 16.0 303.0)">Занятые ядра</text>
<rect x="64.0" y="89.0" width="12" height="12" rx="2" fill="#2a78d6"/>
<text x="86.0" y="99.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">реплики API</text>
<rect x="175.0" y="89.0" width="12" height="12" rx="2" fill="#eb6834"/>
<text x="197.0" y="99.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">PostgreSQL</text>
<rect x="279.0" y="89.0" width="12" height="12" rx="2" fill="#1baf7a"/>
<text x="301.0" y="99.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">HAProxy</text>
<rect x="362.0" y="89.0" width="12" height="12" rx="2" fill="#eda100"/>
<text x="384.0" y="99.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">Valkey</text>
<rect x="438.0" y="89.0" width="12" height="12" rx="2" fill="#e87ba4"/>
<text x="460.0" y="99.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">k6</text>
<rect x="486.0" y="89.0" width="12" height="12" rx="2" fill="#008300"/>
<text x="508.0" y="99.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">остальное в ВМ</text>
</svg>

After

Width:  |  Height:  |  Size: 6.3 KiB

+754
View File
@@ -0,0 +1,754 @@
{
"label": "scaling-a",
"status": "complete",
"started_at": "2026-10-11T01:10:13+00:00",
"command": "uv run python bench/run.py --profile scaling_a --label scaling-a",
"git": {
"commit": "cbe3b4a",
"dirty": false
},
"overrides": {},
"host_state": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 49,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 54,
"power": "AC Power",
"battery_percent": 80
},
"swapouts_delta": 0,
"slept_seconds": 0
},
"host_warnings": [],
"other_containers": [],
"budget": {
"1x4": {
"cpus": 9.75,
"memory_gib": 4.5,
"vm_cpus": 12,
"vm_memory_gib": 7.75
},
"2x2": {
"cpus": 9.75,
"memory_gib": 4.5,
"vm_cpus": 12,
"vm_memory_gib": 7.75
},
"4x1": {
"cpus": 9.75,
"memory_gib": 4.5,
"vm_cpus": 12,
"vm_memory_gib": 7.75
}
},
"app_image": {
"tag": "mtusi-messenger:bench",
"id": "sha256:dbead735420cbfd43051e3e3919929e288ab36815afd86aa3ef58ee110eb1924",
"versions": {
"python": "3.12.14",
"fastapi": "0.141.1",
"starlette": "1.7.0",
"pydantic": "2.13.5",
"uvicorn": "0.54.0",
"sqlalchemy": "2.1.1",
"asyncpg": "0.31.0",
"redis": "8.1.0"
}
},
"generator": {
"image": "grafana/k6:2.3.0@sha256:9c2dee7f8ed74d317e4027c06a10f169b625638189de8d4555d0b3486a5aeb34",
"version": "k6 v2.3.0 (commit/e088784614, go1.27.1, linux/arm64)"
},
"docker": {
"server": "29.8.2",
"vm_os": "Docker Desktop",
"vm_cpus": 12,
"vm_memory_gib": 7.7,
"cgroup": "2",
"logging_driver": "local"
},
"host": {
"os": "macOS 26.6.2",
"machine": "Apple M3 Pro",
"memory_gib": 18.0,
"performance_cores": 6,
"efficiency_cores": 6
},
"profile": {
"name": "scaling_a",
"sizes": [
10000
],
"concurrency": [],
"repeats": 3,
"read_warmup_s": 0,
"read_measure_s": 0,
"write_warmup": 0,
"write_measure": 0,
"prefill_chunk": 25000,
"prefill_vus": 32,
"text_length": 64,
"page_limit": 50,
"walk_limit": 100,
"cursor_pool": 1000,
"members": 10,
"seed": 20260930,
"warmup_seed_shift": 1000003,
"generator_cpu_limit": 1.8,
"cpus": "1",
"memory": "512m",
"db_cpus": "2",
"db_memory": "1g",
"cache_cpus": "0.5",
"cache_memory": "128m",
"session_ttl_seconds": 21600,
"background": [],
"index_variants": [
[
"chat_only",
"(chat_id)"
],
[
"covering",
"(chat_id, created_at, id) INCLUDE (sender_id, text)"
]
],
"write_probe_rows": 20000,
"write_probe_repeats": 3,
"restore": false,
"restore_jobs": 4,
"restore_write_load": 5000,
"restore_write_vus": 10,
"replicas": 1,
"lb_cpus": "1",
"lb_memory": "256m",
"failover_modes": [],
"failover_write_rate": 0,
"failover_read_rate": 0,
"failover_before_s": 0,
"failover_down_s": 0,
"failover_after_s": 0,
"failover_success": 0.99,
"failover_pre_vus": 600,
"failover_max_vus": 1500,
"rollout_from": "",
"rollout_before_s": 0,
"rollout_budget_s": 0,
"rollout_after_s": 0,
"db_max_connections": 100,
"series": "a",
"configs": [
[
1,
"4",
"2g",
100
],
[
2,
"2",
"1g",
100
],
[
4,
"1",
"512m",
100
]
],
"write_chats": 10,
"mix": [
[
"read",
0.7
],
[
"write",
0.2
],
[
"me",
0.1
]
],
"fixed_rps": [
250,
500
],
"ladder_base": 100,
"step_factor": 1.25,
"start_rps_per_replica": 300,
"bisect_steps": 2,
"max_steps": 12,
"first_warmup_s": 15,
"step_warmup_s": 5,
"step_measure_s": 20,
"cooldown_s": 10,
"slo_p95_ms": 200,
"slo_error_ratio": 0.01,
"abort_error_ratio": 0.5,
"abort_p95_ms": 2000,
"request_timeout_s": 15,
"prevus_per_rps": 0.2,
"vus_per_rps": 0.2,
"generator_cpus": "2",
"generator_memory": "1g",
"sampler_cpus": "0.25",
"sampler_memory": "128m",
"sample_interval_s": 1.0,
"order_seed": 20261011
},
"sizes": [],
"plan": [
{
"cell": "4x1-r1",
"config": "4x1",
"replicas": 4,
"replica_cpus": "1",
"replica_memory": "512m",
"db_max_connections": 100,
"repeat": 1,
"round": 1,
"order": 1
},
{
"cell": "1x4-r1",
"config": "1x4",
"replicas": 1,
"replica_cpus": "4",
"replica_memory": "2g",
"db_max_connections": 100,
"repeat": 1,
"round": 1,
"order": 2
},
{
"cell": "2x2-r1",
"config": "2x2",
"replicas": 2,
"replica_cpus": "2",
"replica_memory": "1g",
"db_max_connections": 100,
"repeat": 1,
"round": 1,
"order": 3
},
{
"cell": "1x4-r2",
"config": "1x4",
"replicas": 1,
"replica_cpus": "4",
"replica_memory": "2g",
"db_max_connections": 100,
"repeat": 2,
"round": 2,
"order": 4
},
{
"cell": "2x2-r2",
"config": "2x2",
"replicas": 2,
"replica_cpus": "2",
"replica_memory": "1g",
"db_max_connections": 100,
"repeat": 2,
"round": 2,
"order": 5
},
{
"cell": "4x1-r2",
"config": "4x1",
"replicas": 4,
"replica_cpus": "1",
"replica_memory": "512m",
"db_max_connections": 100,
"repeat": 2,
"round": 2,
"order": 6
},
{
"cell": "2x2-r3",
"config": "2x2",
"replicas": 2,
"replica_cpus": "2",
"replica_memory": "1g",
"db_max_connections": 100,
"repeat": 3,
"round": 3,
"order": 7
},
{
"cell": "1x4-r3",
"config": "1x4",
"replicas": 1,
"replica_cpus": "4",
"replica_memory": "2g",
"db_max_connections": 100,
"repeat": 3,
"round": 3,
"order": 8
},
{
"cell": "4x1-r3",
"config": "4x1",
"replicas": 4,
"replica_cpus": "1",
"replica_memory": "512m",
"db_max_connections": 100,
"repeat": 3,
"round": 3,
"order": 9
}
],
"limits": {
"4x1": {
"api": {
"nano_cpus": 1000000000,
"memory": 536870912,
"memory_swap": 536870912,
"published_ports": {},
"healthcheck": [
"NONE"
],
"log_driver": "local"
},
"postgres": {
"nano_cpus": 2000000000,
"memory": 1073741824,
"memory_swap": 1073741824,
"published_ports": {},
"healthcheck": [
"CMD-SHELL",
"pg_isready -h 127.0.0.1 -U \"$POSTGRES_USER\" -d \"$POSTGRES_DB\""
],
"log_driver": "local"
},
"valkey": {
"nano_cpus": 500000000,
"memory": 134217728,
"memory_swap": 134217728,
"published_ports": {},
"healthcheck": [
"CMD-SHELL",
"test \"$(valkey-cli -p \"$VALKEY_PORT\" ping)\" = PONG"
],
"log_driver": "local"
},
"haproxy": {
"nano_cpus": 1000000000,
"memory": 268435456,
"memory_swap": 268435456,
"published_ports": {},
"healthcheck": [
"CMD",
"bash",
"-c",
"exec 3<>/dev/tcp/127.0.0.1/8404 && printf 'GET /lb/ready HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"
],
"log_driver": "local"
},
"k6": {
"nano_cpus": 2000000000,
"memory": 1073741824,
"memory_swap": 1073741824,
"published_ports": {},
"healthcheck": null,
"log_driver": "local"
},
"api_replicas": 4,
"max_connections": 100
},
"1x4": {
"api": {
"nano_cpus": 4000000000,
"memory": 2147483648,
"memory_swap": 2147483648,
"published_ports": {},
"healthcheck": [
"NONE"
],
"log_driver": "local"
},
"postgres": {
"nano_cpus": 2000000000,
"memory": 1073741824,
"memory_swap": 1073741824,
"published_ports": {},
"healthcheck": [
"CMD-SHELL",
"pg_isready -h 127.0.0.1 -U \"$POSTGRES_USER\" -d \"$POSTGRES_DB\""
],
"log_driver": "local"
},
"valkey": {
"nano_cpus": 500000000,
"memory": 134217728,
"memory_swap": 134217728,
"published_ports": {},
"healthcheck": [
"CMD-SHELL",
"test \"$(valkey-cli -p \"$VALKEY_PORT\" ping)\" = PONG"
],
"log_driver": "local"
},
"haproxy": {
"nano_cpus": 1000000000,
"memory": 268435456,
"memory_swap": 268435456,
"published_ports": {},
"healthcheck": [
"CMD",
"bash",
"-c",
"exec 3<>/dev/tcp/127.0.0.1/8404 && printf 'GET /lb/ready HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"
],
"log_driver": "local"
},
"k6": {
"nano_cpus": 2000000000,
"memory": 1073741824,
"memory_swap": 1073741824,
"published_ports": {},
"healthcheck": null,
"log_driver": "local"
},
"api_replicas": 1,
"max_connections": 100
},
"2x2": {
"api": {
"nano_cpus": 2000000000,
"memory": 1073741824,
"memory_swap": 1073741824,
"published_ports": {},
"healthcheck": [
"NONE"
],
"log_driver": "local"
},
"postgres": {
"nano_cpus": 2000000000,
"memory": 1073741824,
"memory_swap": 1073741824,
"published_ports": {},
"healthcheck": [
"CMD-SHELL",
"pg_isready -h 127.0.0.1 -U \"$POSTGRES_USER\" -d \"$POSTGRES_DB\""
],
"log_driver": "local"
},
"valkey": {
"nano_cpus": 500000000,
"memory": 134217728,
"memory_swap": 134217728,
"published_ports": {},
"healthcheck": [
"CMD-SHELL",
"test \"$(valkey-cli -p \"$VALKEY_PORT\" ping)\" = PONG"
],
"log_driver": "local"
},
"haproxy": {
"nano_cpus": 1000000000,
"memory": 268435456,
"memory_swap": 268435456,
"published_ports": {},
"healthcheck": [
"CMD",
"bash",
"-c",
"exec 3<>/dev/tcp/127.0.0.1/8404 && printf 'GET /lb/ready HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"
],
"log_driver": "local"
},
"k6": {
"nano_cpus": 2000000000,
"memory": 1073741824,
"memory_swap": 1073741824,
"published_ports": {},
"healthcheck": null,
"log_driver": "local"
},
"api_replicas": 2,
"max_connections": 100
}
},
"stand": {
"postgres": {
"image": "postgres:18.6-trixie@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722",
"id": "sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722",
"version": "18.6 (Debian 18.6-1.pgdg13+2)",
"settings": {
"autovacuum": "on",
"checkpoint_timeout": "5min",
"effective_cache_size": "4GB",
"fsync": "on",
"jit": "on",
"maintenance_work_mem": "64MB",
"max_wal_size": "1GB",
"plan_cache_mode": "auto",
"random_page_cost": "4",
"shared_buffers": "128MB",
"shared_preload_libraries": "auto_explain",
"synchronous_commit": "on",
"wal_level": "replica",
"work_mem": "4MB"
}
},
"valkey": {
"image": "valkey/valkey:9.1.2-trixie@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd",
"id": "sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd",
"version": "9.1.2",
"maxmemory": "67108864",
"maxmemory-clients": "0",
"maxmemory-eviction-tenacity": "10",
"maxmemory-policy": "allkeys-lru",
"maxmemory-samples": "5"
},
"haproxy": {
"image": "haproxy:3.4.6-trixie@sha256:e273915691a8eab3f105bf3e39fd4c29a4ecf334e33421903b5589d25e14db26",
"id": "sha256:e273915691a8eab3f105bf3e39fd4c29a4ecf334e33421903b5589d25e14db26",
"version": "HAProxy version 3.4.6-56332c5 2026/09/28 - https://haproxy.org/"
},
"app_env": {
"APP__PORT": "8080",
"APP__RUN_MODE": "docker",
"AUTH__SESSION_TTL_SECONDS": "21600",
"CACHE__HOST": "valkey",
"CACHE__PORT": "6379",
"DATABASE__HOST": "postgres",
"DATABASE__NAME": "bench",
"DATABASE__PORT": "5432",
"DATABASE__USER": "bench"
}
},
"cells": {
"4x1-r1": {
"attempt": 1,
"status": "complete",
"r_star_rps": 1539,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 49,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 50,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
},
"1x4-r1": {
"attempt": 1,
"status": "complete",
"r_star_rps": 630,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 50,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 48,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
},
"2x2-r1": {
"attempt": 1,
"status": "complete",
"r_star_rps": 1041,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 48,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 45,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
},
"1x4-r2": {
"attempt": 1,
"status": "complete",
"r_star_rps": 630,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 44,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 46,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
},
"2x2-r2": {
"attempt": 1,
"status": "complete",
"r_star_rps": 1101,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 46,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 52,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
},
"4x1-r2": {
"attempt": 1,
"status": "complete",
"r_star_rps": 1819,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 53,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 54,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
},
"2x2-r3": {
"attempt": 1,
"status": "complete",
"r_star_rps": 1164,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 54,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 53,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
},
"1x4-r3": {
"attempt": 1,
"status": "complete",
"r_star_rps": 704,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 54,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 53,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
},
"4x1-r3": {
"attempt": 1,
"status": "complete",
"r_star_rps": 1819,
"host": {
"start": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 53,
"power": "AC Power",
"battery_percent": 80
},
"end": {
"swap_used_mib": 864.31,
"swap_total_mib": 2048.0,
"swapouts": 6697411,
"memory_free_percent": 54,
"power": "AC Power",
"battery_percent": 80
}
},
"other_containers": []
}
},
"finished_at": "2026-10-11T01:46:48+00:00"
}
+77
View File
@@ -0,0 +1,77 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 860 520" width="860" height="520" font-family='system-ui, -apple-system, "Segoe UI", sans-serif'>
<rect x="0" y="0" width="860" height="520" fill="#fcfcfb"/>
<text x="24.0" y="30.0" font-size="16" font-weight="600" fill="#52514e" text-anchor="start">Серия a: p95 от интенсивности</text>
<text x="24.0" y="52.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">Метка scaling-a: медиана p95 успешных запросов по повторам на каждом уровне; полые точки — ступени деления</text>
<line x1="76.0" y1="456.0" x2="836.0" y2="456.0" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="460.0" font-size="12" font-weight="400" fill="#898781" text-anchor="end">1</text>
<line x1="76.0" y1="428.9" x2="836.0" y2="428.9" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="432.9" font-size="12" font-weight="400" fill="#898781" text-anchor="end">2</text>
<line x1="76.0" y1="393.1" x2="836.0" y2="393.1" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="397.1" font-size="12" font-weight="400" fill="#898781" text-anchor="end">5</text>
<line x1="76.0" y1="366.0" x2="836.0" y2="366.0" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="370.0" font-size="12" font-weight="400" fill="#898781" text-anchor="end">10</text>
<line x1="76.0" y1="338.9" x2="836.0" y2="338.9" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="342.9" font-size="12" font-weight="400" fill="#898781" text-anchor="end">20</text>
<line x1="76.0" y1="303.1" x2="836.0" y2="303.1" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="307.1" font-size="12" font-weight="400" fill="#898781" text-anchor="end">50</text>
<line x1="76.0" y1="276.0" x2="836.0" y2="276.0" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="280.0" font-size="12" font-weight="400" fill="#898781" text-anchor="end">100</text>
<line x1="76.0" y1="248.9" x2="836.0" y2="248.9" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="252.9" font-size="12" font-weight="400" fill="#898781" text-anchor="end">200</text>
<line x1="76.0" y1="213.1" x2="836.0" y2="213.1" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="217.1" font-size="12" font-weight="400" fill="#898781" text-anchor="end">500</text>
<line x1="76.0" y1="186.0" x2="836.0" y2="186.0" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="190.0" font-size="12" font-weight="400" fill="#898781" text-anchor="end">1K</text>
<line x1="76.0" y1="158.9" x2="836.0" y2="158.9" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="162.9" font-size="12" font-weight="400" fill="#898781" text-anchor="end">2K</text>
<line x1="76.0" y1="123.1" x2="836.0" y2="123.1" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="127.1" font-size="12" font-weight="400" fill="#898781" text-anchor="end">5K</text>
<line x1="76.0" y1="96.0" x2="836.0" y2="96.0" stroke="#e1e0d9" stroke-width="1"/>
<text x="68.0" y="100.0" font-size="12" font-weight="400" fill="#898781" text-anchor="end">10K</text>
<text x="76.0" y="474.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">0</text>
<text x="228.0" y="474.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">500</text>
<text x="380.0" y="474.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">1K</text>
<text x="532.0" y="474.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">1.5K</text>
<text x="684.0" y="474.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">2K</text>
<text x="836.0" y="474.0" font-size="12" font-weight="400" fill="#898781" text-anchor="middle">2.5K</text>
<line x1="76.0" y1="456.0" x2="836.0" y2="456.0" stroke="#c3c2b7" stroke-width="1"/>
<line x1="76.0" y1="248.9" x2="836.0" y2="248.9" stroke="#52514e" stroke-width="1.5" stroke-dasharray="6 4"/>
<text x="832.0" y="242.9" font-size="12" font-weight="400" fill="#52514e" text-anchor="end">SLO p95 200 мс</text>
<text x="456.0" y="502.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="middle">Интенсивность, запросов/с</text>
<text x="20.0" y="276.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="middle" transform="rotate(-90 20.0 276.0)">p95, мс (логарифмическая шкала)</text>
<polyline points="152.0,400.1 228.0,294.7 257.2,278.1 302.5,206.6" fill="none" stroke="#2a78d6" stroke-width="2" stroke-linejoin="round" stroke-linecap="round"/>
<g><title>1x4: 250 запросов/с, p95 4.2 мс (повторов 3)</title><circle cx="152.0" cy="400.1" r="7" fill="transparent"/><circle cx="152.0" cy="400.1" r="4.5" fill="#2a78d6" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>1x4: 500 запросов/с, p95 62.0 мс (повторов 3)</title><circle cx="228.0" cy="294.7" r="7" fill="transparent"/><circle cx="228.0" cy="294.7" r="4.5" fill="#2a78d6" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>1x4: 596 запросов/с, p95 94.7 мс (повторов 3)</title><circle cx="257.2" cy="278.1" r="7" fill="transparent"/><circle cx="257.2" cy="278.1" r="4.5" fill="#2a78d6" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>1x4: 745 запросов/с, p95 590.7 мс (повторов 3)</title><circle cx="302.5" cy="206.6" r="7" fill="transparent"/><circle cx="302.5" cy="206.6" r="4.5" fill="#2a78d6" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>1x4: деление 630 запросов/с, p95 132.1 мс (повторов 2)</title><circle cx="267.5" cy="265.1" r="7" fill="transparent"/><circle cx="267.5" cy="265.1" r="4.5" fill="#fcfcfb" stroke="#2a78d6" stroke-width="2"/></g>
<g><title>1x4: деление 666 запросов/с, p95 327.6 мс (повторов 3)</title><circle cx="278.5" cy="229.6" r="7" fill="transparent"/><circle cx="278.5" cy="229.6" r="4.5" fill="#fcfcfb" stroke="#2a78d6" stroke-width="2"/></g>
<g><title>1x4: деление 704 запросов/с, p95 148.0 мс (повторов 1)</title><circle cx="290.0" cy="260.7" r="7" fill="transparent"/><circle cx="290.0" cy="260.7" r="4.5" fill="#fcfcfb" stroke="#2a78d6" stroke-width="2"/></g>
<polyline points="152.0,404.8 228.0,409.9 302.5,321.2 359.0,280.5 429.9,199.6 518.3,184.2" fill="none" stroke="#eb6834" stroke-width="2" stroke-linejoin="round" stroke-linecap="round"/>
<g><title>2x2: 250 запросов/с, p95 3.7 мс (повторов 3)</title><circle cx="152.0" cy="404.8" r="7" fill="transparent"/><circle cx="152.0" cy="404.8" r="4.5" fill="#eb6834" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>2x2: 500 запросов/с, p95 3.2 мс (повторов 3)</title><circle cx="228.0" cy="409.9" r="7" fill="transparent"/><circle cx="228.0" cy="409.9" r="4.5" fill="#eb6834" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>2x2: 745 запросов/с, p95 31.5 мс (повторов 3)</title><circle cx="302.5" cy="321.2" r="7" fill="transparent"/><circle cx="302.5" cy="321.2" r="4.5" fill="#eb6834" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>2x2: 931 запросов/с, p95 89.0 мс (повторов 3)</title><circle cx="359.0" cy="280.5" r="7" fill="transparent"/><circle cx="359.0" cy="280.5" r="4.5" fill="#eb6834" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>2x2: 1164 запросов/с, p95 707.0 мс (повторов 3)</title><circle cx="429.9" cy="199.6" r="7" fill="transparent"/><circle cx="429.9" cy="199.6" r="4.5" fill="#eb6834" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>2x2: 1455 запросов/с, p95 1046.1 мс (повторов 1)</title><circle cx="518.3" cy="184.2" r="7" fill="transparent"/><circle cx="518.3" cy="184.2" r="4.5" fill="#eb6834" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>2x2: деление 1041 запросов/с, p95 123.5 мс (повторов 2)</title><circle cx="392.5" cy="267.8" r="7" fill="transparent"/><circle cx="392.5" cy="267.8" r="4.5" fill="#fcfcfb" stroke="#eb6834" stroke-width="2"/></g>
<g><title>2x2: деление 1101 запросов/с, p95 445.3 мс (повторов 2)</title><circle cx="410.7" cy="217.6" r="7" fill="transparent"/><circle cx="410.7" cy="217.6" r="4.5" fill="#fcfcfb" stroke="#eb6834" stroke-width="2"/></g>
<g><title>2x2: деление 1231 запросов/с, p95 866.0 мс (повторов 1)</title><circle cx="450.2" cy="191.6" r="7" fill="transparent"/><circle cx="450.2" cy="191.6" r="4.5" fill="#fcfcfb" stroke="#eb6834" stroke-width="2"/></g>
<g><title>2x2: деление 1301 запросов/с, p95 760.9 мс (повторов 1)</title><circle cx="471.5" cy="196.7" r="7" fill="transparent"/><circle cx="471.5" cy="196.7" r="4.5" fill="#fcfcfb" stroke="#eb6834" stroke-width="2"/></g>
<polyline points="152.0,409.7 228.0,414.4 518.3,295.0 629.0,259.8 767.3,188.9" fill="none" stroke="#1baf7a" stroke-width="2" stroke-linejoin="round" stroke-linecap="round"/>
<g><title>4x1: 250 запросов/с, p95 3.3 мс (повторов 3)</title><circle cx="152.0" cy="409.7" r="7" fill="transparent"/><circle cx="152.0" cy="409.7" r="4.5" fill="#1baf7a" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>4x1: 500 запросов/с, p95 2.9 мс (повторов 3)</title><circle cx="228.0" cy="414.4" r="7" fill="transparent"/><circle cx="228.0" cy="414.4" r="4.5" fill="#1baf7a" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>4x1: 1455 запросов/с, p95 61.5 мс (повторов 3)</title><circle cx="518.3" cy="295.0" r="7" fill="transparent"/><circle cx="518.3" cy="295.0" r="4.5" fill="#1baf7a" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>4x1: 1819 запросов/с, p95 151.3 мс (повторов 3)</title><circle cx="629.0" cy="259.8" r="7" fill="transparent"/><circle cx="629.0" cy="259.8" r="4.5" fill="#1baf7a" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>4x1: 2274 запросов/с, p95 927.4 мс (повторов 2)</title><circle cx="767.3" cy="188.9" r="7" fill="transparent"/><circle cx="767.3" cy="188.9" r="4.5" fill="#1baf7a" stroke="#fcfcfb" stroke-width="2"/></g>
<g><title>4x1: деление 1539 запросов/с, p95 128.0 мс (повторов 1)</title><circle cx="543.9" cy="266.4" r="7" fill="transparent"/><circle cx="543.9" cy="266.4" r="4.5" fill="#fcfcfb" stroke="#1baf7a" stroke-width="2"/></g>
<g><title>4x1: деление 1627 запросов/с, p95 238.3 мс (повторов 1)</title><circle cx="570.6" cy="242.1" r="7" fill="transparent"/><circle cx="570.6" cy="242.1" r="4.5" fill="#fcfcfb" stroke="#1baf7a" stroke-width="2"/></g>
<g><title>4x1: деление 1923 запросов/с, p95 741.1 мс (повторов 2)</title><circle cx="660.6" cy="197.7" r="7" fill="transparent"/><circle cx="660.6" cy="197.7" r="4.5" fill="#fcfcfb" stroke="#1baf7a" stroke-width="2"/></g>
<g><title>4x1: деление 2034 запросов/с, p95 959.6 мс (повторов 2)</title><circle cx="694.3" cy="187.6" r="7" fill="transparent"/><circle cx="694.3" cy="187.6" r="4.5" fill="#fcfcfb" stroke="#1baf7a" stroke-width="2"/></g>
<line x1="76.0" y1="73.0" x2="92.0" y2="73.0" stroke="#2a78d6" stroke-width="2"/>
<text x="98.0" y="77.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">1x4</text>
<line x1="131.0" y1="73.0" x2="147.0" y2="73.0" stroke="#eb6834" stroke-width="2"/>
<text x="153.0" y="77.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">2x2</text>
<line x1="186.0" y1="73.0" x2="202.0" y2="73.0" stroke="#1baf7a" stroke-width="2"/>
<text x="208.0" y="77.0" font-size="12" font-weight="400" fill="#52514e" text-anchor="start">4x1</text>
</svg>

After

Width:  |  Height:  |  Size: 11 KiB

+10
View File
@@ -0,0 +1,10 @@
size,chunk,messages_before,messages_after,duration_s,requests_ok,requests_failed,rps,error_ratio,p50_ms,p95_ms,p99_ms,max_ms,app_cpu_cores,rss_end_mib,mem_cgroup_end_mib,generator_cpu_cores,flags,db_cpu_cores,cell,attempt
10000,1,0,10000,7.558,10000,0,1323.2,0.0,7.104,96.383,137.067,241.748,3.733,370.6,329.8,0.309,,0.737,4x1-r1,1
10000,1,0,10000,16.211,10000,0,616.9,0.0,49.641,94.954,131.16,258.537,1.007,92.6,83.2,0.094,,0.204,1x4-r1,1
10000,1,0,10000,10.38,10000,0,963.4,0.0,25.127,91.725,133.052,208.511,1.96,186.5,167.9,0.173,,0.412,2x2-r1,1
10000,1,0,10000,16.233,10000,0,616.0,0.0,50.489,89.017,120.492,239.705,1.008,92.6,80.8,0.096,,0.206,1x4-r2,1
10000,1,0,10000,10.404,10000,0,961.1,0.0,23.642,97.894,142.31,222.056,1.95,186.4,165.1,0.168,,0.404,2x2-r2,1
10000,1,0,10000,6.949,10000,0,1439.1,0.0,7.015,89.328,124.098,284.221,3.681,370.8,327.2,0.309,,0.743,4x1-r2,1
10000,1,0,10000,9.717,10000,0,1029.2,0.0,23.181,88.473,127.153,237.322,1.956,186.2,170.6,0.169,,0.403,2x2-r3,1
10000,1,0,10000,15.567,10000,0,642.4,0.0,48.138,88.675,118.465,237.522,1.007,92.6,82.4,0.097,,0.196,1x4-r3,1
10000,1,0,10000,6.967,10000,0,1435.2,0.0,7.145,88.941,128.167,240.71,3.683,369.8,331.1,0.303,,0.745,4x1-r3,1
1 size chunk messages_before messages_after duration_s requests_ok requests_failed rps error_ratio p50_ms p95_ms p99_ms max_ms app_cpu_cores rss_end_mib mem_cgroup_end_mib generator_cpu_cores flags db_cpu_cores cell attempt
2 10000 1 0 10000 7.558 10000 0 1323.2 0.0 7.104 96.383 137.067 241.748 3.733 370.6 329.8 0.309 0.737 4x1-r1 1
3 10000 1 0 10000 16.211 10000 0 616.9 0.0 49.641 94.954 131.16 258.537 1.007 92.6 83.2 0.094 0.204 1x4-r1 1
4 10000 1 0 10000 10.38 10000 0 963.4 0.0 25.127 91.725 133.052 208.511 1.96 186.5 167.9 0.173 0.412 2x2-r1 1
5 10000 1 0 10000 16.233 10000 0 616.0 0.0 50.489 89.017 120.492 239.705 1.008 92.6 80.8 0.096 0.206 1x4-r2 1
6 10000 1 0 10000 10.404 10000 0 961.1 0.0 23.642 97.894 142.31 222.056 1.95 186.4 165.1 0.168 0.404 2x2-r2 1
7 10000 1 0 10000 6.949 10000 0 1439.1 0.0 7.015 89.328 124.098 284.221 3.681 370.8 327.2 0.309 0.743 4x1-r2 1
8 10000 1 0 10000 9.717 10000 0 1029.2 0.0 23.181 88.473 127.153 237.322 1.956 186.2 170.6 0.169 0.403 2x2-r3 1
9 10000 1 0 10000 15.567 10000 0 642.4 0.0 48.138 88.675 118.465 237.522 1.007 92.6 82.4 0.097 0.196 1x4-r3 1
10 10000 1 0 10000 6.967 10000 0 1435.2 0.0 7.145 88.941 128.167 240.71 3.683 369.8 331.1 0.303 0.745 4x1-r3 1
+16
View File
@@ -0,0 +1,16 @@
{
"label": "scaling-a",
"profile": "scaling_a",
"stage": "done",
"size": 10000,
"runs_done": 9,
"runs_total": 9,
"elapsed_s": 2195,
"eta_s": 0,
"warnings": [],
"cell": null,
"attempt": 1,
"cells_done": 9,
"cells_total": 9,
"updated_at": "2026-10-11T01:46:48+00:00"
}
@@ -0,0 +1 @@
{"state":{"isStdErrTTY":false,"testRunDurationMs":16210.766591,"isStdOutTTY":false},"metrics":{"http_req_duration":{"type":"trend","contains":"time","values":{"avg":51.76013685850013,"min":16.406375,"med":49.640521,"p(50)":49.640521,"p(95)":94.95414759999998,"p(99)":131.16030782999994,"max":258.537416}},"http_req_connecting":{"contains":"time","values":{"max":0.467833,"avg":0.0006603583,"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0},"type":"trend"},"http_req_waiting":{"type":"trend","contains":"time","values":{"med":49.6261875,"p(50)":49.6261875,"p(95)":94.94111904999998,"p(99)":131.15158433999994,"max":258.311167,"avg":51.7403214161001,"min":16.391375}},"http_req_blocked":{"type":"trend","contains":"time","values":{"avg":0.003684756199999864,"min":0.000416,"med":0.000875,"p(50)":0.000875,"p(95)":0.001833,"p(99)":0.007125,"max":1.254167}},"vus_max":{"type":"gauge","contains":"default","values":{"value":32,"min":32,"max":32}},"iteration_duration":{"type":"trend","contains":"time","values":{"avg":51.821075050900056,"min":16.454625,"med":49.69758349999999,"p(50)":49.69758349999999,"p(95)":95.01154614999999,"p(99)":131.19856624999994,"max":259.211541}},"http_req_duration{expected_response:true}":{"thresholds":{"max>=0":{"ok":true}},"type":"trend","contains":"time","values":{"p(50)":49.640521,"p(95)":94.95414759999998,"p(99)":131.16030782999994,"max":258.537416,"avg":51.76013685850013,"min":16.406375,"med":49.640521}},"http_req_receiving":{"type":"trend","contains":"time","values":{"avg":0.014428195899999968,"min":0.004125,"med":0.012292,"p(50)":0.012292,"p(95)":0.029833049999999996,"p(99)":0.054585509999999976,"max":0.301458}},"http_req_failed":{"type":"rate","contains":"default","values":{"rate":0,"passes":0,"fails":10000}},"data_sent":{"type":"counter","contains":"data","values":{"count":3760000,"rate":231944.61402507033}},"http_reqs":{"type":"counter","contains":"default","values":{"count":10000,"rate":616.8739734709318}},"vus":{"type":"gauge","contains":"default","values":{"min":32,"max":32,"value":32}},"http_req_sending":{"contains":"time","values":{"max":0.245625,"avg":0.005387246499999947,"min":0.00175,"med":0.003583,"p(50)":0.003583,"p(95)":0.010167,"p(99)":0.025917829999999992},"type":"trend"},"http_req_tls_handshaking":{"type":"trend","contains":"time","values":{"max":0,"avg":0,"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0}},"data_received":{"type":"counter","contains":"data","values":{"count":4700000,"rate":289930.7675313379}},"checks":{"type":"rate","contains":"default","values":{"rate":1,"passes":10000,"fails":0}},"iterations":{"type":"counter","contains":"default","values":{"count":10000,"rate":616.8739734709318}}},"root_group":{"path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"fails":0,"name":"message 201","path":"::message 201","id":"6445aff337e1ade0bc10402fbac79882","passes":10000}],"name":""},"options":{"noColor":true,"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":""}}
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1 @@
{"root_group":{"path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"passes":10000,"fails":0,"name":"message 201","path":"::message 201","id":"6445aff337e1ade0bc10402fbac79882"}],"name":""},"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"isStdOutTTY":false,"isStdErrTTY":false,"testRunDurationMs":16233.351716},"metrics":{"http_req_waiting":{"values":{"p(50)":50.474542,"p(95)":88.99110239999997,"p(99)":120.48283849999999,"max":239.574542,"avg":51.81044076180005,"min":16.057375,"med":50.474542},"type":"trend","contains":"time"},"data_sent":{"type":"counter","contains":"data","values":{"count":3760000,"rate":231621.91430214926}},"iteration_duration":{"contains":"time","values":{"med":50.537833500000005,"p(50)":50.537833500000005,"p(95)":89.07724794999999,"p(99)":120.54012083999999,"max":241.057875,"avg":51.894887439600055,"min":16.135875},"type":"trend"},"http_req_receiving":{"values":{"p(99)":0.054293509999999975,"max":0.447,"avg":0.014754876200000053,"min":0.004125,"med":0.012458,"p(50)":0.012458,"p(95)":0.030708},"type":"trend","contains":"time"},"http_req_failed":{"type":"rate","contains":"default","values":{"rate":0,"passes":0,"fails":10000}},"data_received":{"type":"counter","contains":"data","values":{"count":4700000,"rate":289527.3928776866}},"vus_max":{"contains":"default","values":{"value":32,"min":32,"max":32},"type":"gauge"},"http_req_blocked":{"type":"trend","contains":"time","values":{"p(50)":0.000916,"p(95)":0.001958,"p(99)":0.0051660099999999995,"max":1.586875,"avg":0.004550053899999775,"min":0.000416,"med":0.000916}},"http_req_duration{expected_response:true}":{"thresholds":{"max>=0":{"ok":true}},"type":"trend","contains":"time","values":{"med":50.489125,"p(50)":50.489125,"p(95)":89.01723569999999,"p(99)":120.49150383999998,"max":239.705334,"avg":51.830670079500024,"min":16.073458}},"http_req_tls_handshaking":{"values":{"p(50)":0,"p(95)":0,"p(99)":0,"max":0,"avg":0,"min":0,"med":0},"type":"trend","contains":"time"},"checks":{"type":"rate","contains":"default","values":{"rate":1,"passes":10000,"fails":0}},"http_req_duration":{"type":"trend","contains":"time","values":{"med":50.489125,"p(50)":50.489125,"p(95)":89.01723569999999,"p(99)":120.49150383999998,"max":239.705334,"avg":51.830670079500024,"min":16.073458}},"http_reqs":{"type":"counter","contains":"default","values":{"rate":616.0157295269927,"count":10000}},"vus":{"type":"gauge","contains":"default","values":{"max":32,"value":32,"min":32}},"http_req_sending":{"contains":"time","values":{"p(50)":0.003667,"p(95)":0.010042,"p(99)":0.03014040999999986,"max":0.184625,"avg":0.005474441499999937,"min":0.00175,"med":0.003667},"type":"trend"},"iterations":{"type":"counter","contains":"default","values":{"count":10000,"rate":616.0157295269927}},"http_req_connecting":{"type":"trend","contains":"time","values":{"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0.672708,"avg":0.0009841377000000002,"min":0}}}}
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1 @@
{"metrics":{"http_req_duration":{"type":"trend","contains":"time","values":{"p(95)":88.67549614999997,"p(99)":118.46454834,"max":237.522167,"avg":49.69941644029998,"min":15.864542,"med":48.137645500000005,"p(50)":48.137645500000005}},"data_received":{"type":"counter","contains":"data","values":{"count":4700000,"rate":301921.6390242359}},"http_req_duration{expected_response:true}":{"type":"trend","contains":"time","values":{"p(99)":118.46454834,"max":237.522167,"avg":49.69941644029998,"min":15.864542,"med":48.137645500000005,"p(50)":48.137645500000005,"p(95)":88.67549614999997},"thresholds":{"max>=0":{"ok":true}}},"iteration_duration":{"type":"trend","contains":"time","values":{"p(99)":118.58631125,"max":239.990709,"avg":49.76121841569988,"min":15.908417,"med":48.1959375,"p(50)":48.1959375,"p(95)":88.73248959999998}},"vus_max":{"type":"gauge","contains":"default","values":{"value":32,"min":32,"max":32}},"checks":{"contains":"default","values":{"fails":0,"rate":1,"passes":10000},"type":"rate"},"http_req_blocked":{"contains":"time","values":{"p(50)":0.000792,"p(95)":0.001667,"p(99)":0.005001669999999985,"max":2.864583,"avg":0.007770112600000289,"min":0.000416,"med":0.000792},"type":"trend"},"vus":{"type":"gauge","contains":"default","values":{"value":32,"min":32,"max":32}},"http_req_connecting":{"type":"trend","contains":"time","values":{"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0.786084,"avg":0.0008384709000000001,"min":0}},"http_req_failed":{"type":"rate","contains":"default","values":{"rate":0,"passes":0,"fails":10000}},"http_req_waiting":{"type":"trend","contains":"time","values":{"p(95)":88.65650829999997,"p(99)":118.43883717,"max":237.397001,"avg":49.67969904029991,"min":15.851166,"med":48.1186875,"p(50)":48.1186875}},"http_req_receiving":{"type":"trend","contains":"time","values":{"med":0.011583,"p(50)":0.011583,"p(95)":0.029,"p(99)":0.06745941,"max":0.835125,"avg":0.01405589730000008,"min":0.00425}},"http_reqs":{"type":"counter","contains":"default","values":{"rate":642.3864660090126,"count":10000}},"http_req_sending":{"contains":"time","values":{"p(95)":0.009458,"p(99)":0.03137624999999999,"max":0.64,"avg":0.005661502699999917,"min":0.001667,"med":0.003209,"p(50)":0.003209},"type":"trend"},"http_req_tls_handshaking":{"type":"trend","contains":"time","values":{"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0,"avg":0}},"data_sent":{"values":{"count":3760000,"rate":241537.31121938874},"type":"counter","contains":"data"},"iterations":{"type":"counter","contains":"default","values":{"count":10000,"rate":642.3864660090126}}},"root_group":{"name":"","path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"fails":0,"name":"message 201","path":"::message 201","id":"6445aff337e1ade0bc10402fbac79882","passes":10000}]},"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"isStdOutTTY":false,"isStdErrTTY":false,"testRunDurationMs":15566.953118}}
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1 @@
{"metrics":{"checks":{"type":"rate","contains":"default","values":{"rate":1,"passes":10000,"fails":0}},"http_req_connecting":{"type":"trend","contains":"time","values":{"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":1.135,"avg":0.0012002374999999998}},"http_req_blocked":{"type":"trend","contains":"time","values":{"med":0.001042,"p(50)":0.001042,"p(95)":0.002125,"p(99)":0.004250419999999997,"max":3.152208,"avg":0.004773698199999706,"min":0.000417}},"http_req_failed":{"type":"rate","contains":"default","values":{"rate":0,"passes":0,"fails":10000}},"http_req_duration{expected_response:true}":{"values":{"p(99)":133.05195967,"max":208.510791,"avg":33.09427992769995,"min":1.965333,"med":25.1268335,"p(50)":25.1268335,"p(95)":91.7250923},"thresholds":{"max>=0":{"ok":true}},"type":"trend","contains":"time"},"vus":{"type":"gauge","contains":"default","values":{"value":32,"min":32,"max":32}},"http_req_waiting":{"type":"trend","contains":"time","values":{"med":25.1099375,"p(50)":25.1099375,"p(95)":91.6923,"p(99)":133.02306324999998,"max":207.328333,"avg":33.06765294049998,"min":1.947875}},"http_req_receiving":{"values":{"min":0.004458,"med":0.015,"p(50)":0.015,"p(95)":0.039417,"p(99)":0.07075082999999999,"max":0.527625,"avg":0.018135855499999947},"type":"trend","contains":"time"},"iterations":{"type":"counter","contains":"default","values":{"count":10000,"rate":963.3642525350293}},"http_req_sending":{"values":{"min":0.001834,"med":0.004375,"p(50)":0.004375,"p(95)":0.01125,"p(99)":0.03796632999999992,"max":1.614167,"avg":0.00849113169999989},"type":"trend","contains":"time"},"data_received":{"contains":"data","values":{"count":4700000,"rate":452781.19869146374},"type":"counter"},"vus_max":{"contains":"default","values":{"min":32,"max":32,"value":32},"type":"gauge"},"http_req_duration":{"contains":"time","values":{"p(95)":91.7250923,"p(99)":133.05195967,"max":208.510791,"avg":33.09427992769995,"min":1.965333,"med":25.1268335,"p(50)":25.1268335},"type":"trend"},"http_reqs":{"values":{"count":10000,"rate":963.3642525350293},"type":"counter","contains":"default"},"http_req_tls_handshaking":{"type":"trend","contains":"time","values":{"avg":0,"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0}},"iteration_duration":{"type":"trend","contains":"time","values":{"avg":33.16643324620005,"min":2.012708,"med":25.197542,"p(50)":25.197542,"p(95)":91.77513335,"p(99)":133.11713375,"max":210.281666}},"data_sent":{"type":"counter","contains":"data","values":{"count":3760000,"rate":362224.95895317104}}},"root_group":{"checks":[{"name":"message 201","path":"::message 201","id":"6445aff337e1ade0bc10402fbac79882","passes":10000,"fails":0}],"name":"","path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[]},"options":{"noColor":true,"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":""},"state":{"testRunDurationMs":10380.289671,"isStdOutTTY":false,"isStdErrTTY":false}}
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1 @@
{"root_group":{"name":"","path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"name":"message 201","path":"::message 201","id":"6445aff337e1ade0bc10402fbac79882","passes":10000,"fails":0}]},"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"isStdOutTTY":false,"isStdErrTTY":false,"testRunDurationMs":10404.206658},"metrics":{"http_req_failed":{"type":"rate","contains":"default","values":{"fails":10000,"rate":0,"passes":0}},"data_received":{"type":"counter","contains":"data","values":{"count":4700000,"rate":451740.3541178296}},"http_req_connecting":{"type":"trend","contains":"time","values":{"p(95)":0,"p(99)":0,"max":0.595292,"avg":0.0010674001,"min":0,"med":0,"p(50)":0}},"http_req_receiving":{"type":"trend","contains":"time","values":{"med":0.014542,"p(50)":0.014542,"p(95)":0.03829404999999998,"p(99)":0.08209091999999993,"max":0.438875,"avg":0.017955777200000043,"min":0.004209}},"http_req_blocked":{"type":"trend","contains":"time","values":{"avg":0.0049112708999997055,"min":0.000458,"med":0.001042,"p(50)":0.001042,"p(95)":0.002167,"p(99)":0.005085239999999989,"max":3.029334}},"http_req_duration{expected_response:true}":{"type":"trend","contains":"time","values":{"avg":33.167545960899936,"min":1.825208,"med":23.6423265,"p(50)":23.6423265,"p(95)":97.89436939999999,"p(99)":142.30957157999998,"max":222.055583},"thresholds":{"max>=0":{"ok":true}}},"http_req_duration":{"contains":"time","values":{"avg":33.167545960899936,"min":1.825208,"med":23.6423265,"p(50)":23.6423265,"p(95)":97.89436939999999,"p(99)":142.30957157999998,"max":222.055583},"type":"trend"},"vus_max":{"contains":"default","values":{"max":32,"value":32,"min":32},"type":"gauge"},"iterations":{"values":{"count":10000,"rate":961.1496896124033},"type":"counter","contains":"default"},"iteration_duration":{"type":"trend","contains":"time","values":{"p(99)":142.36247283,"max":222.117209,"avg":33.23894307780009,"min":1.868083,"med":23.708042,"p(50)":23.708042,"p(95)":97.95207705}},"vus":{"values":{"value":32,"min":32,"max":32},"type":"gauge","contains":"default"},"data_sent":{"type":"counter","contains":"data","values":{"count":3760000,"rate":361392.28329426365}},"http_req_tls_handshaking":{"type":"trend","contains":"time","values":{"avg":0,"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0}},"http_req_sending":{"type":"trend","contains":"time","values":{"max":0.426708,"avg":0.006164955199999962,"min":0.001792,"med":0.004292,"p(50)":0.004292,"p(95)":0.011584,"p(99)":0.03733841999999995}},"http_req_waiting":{"type":"trend","contains":"time","values":{"p(95)":97.88245205,"p(99)":142.29766333999999,"max":222.037708,"avg":33.14342522850018,"min":1.811167,"med":23.617479,"p(50)":23.617479}},"checks":{"type":"rate","contains":"default","values":{"rate":1,"passes":10000,"fails":0}},"http_reqs":{"type":"counter","contains":"default","values":{"rate":961.1496896124033,"count":10000}}}}
File diff suppressed because one or more lines are too long

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