ЛР 5 — БВТ2301 — Сафронов — на 5 #19
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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).
|
||||
@@ -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"
|
||||
@@ -0,0 +1,364 @@
|
||||
---
|
||||
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` с другим телом сообщения |
|
||||
| 413 | `payload_too_large` | с лабы 4: тело загрузки больше 10 MiB (по `Content-Length` или счётчику) или изображение больше 40 млн пикселей (`PayloadTooLarge`) |
|
||||
| 415 | `unsupported_media_type` | с лабы 4: `Content-Type` не PNG/JPEG, содержимое не PNG/JPEG, подмена MIME, повреждённое изображение (`UnsupportedMediaType`) |
|
||||
| 429 | `rate_limited` | с change `upload-memory`: места загрузки процесса заняты — очередь ожидания полна или место не освободилось за срок (`UploadsBusy`); всегда с `Retry-After: 1` (`UPLOAD_RETRY_AFTER_SECONDS`, таблица `RETRY_AFTER` в `errors.py`) |
|
||||
| 500 | `internal_error` | необработанное исключение, без деталей; с лабы 4 ещё у готового вложения нет объекта в S3 или он другого размера, а сверка этого ещё не подтвердила (`AttachmentContentMissing`, причина — `error` в журнале); после пометки сверкой — 404 (раздел «Вложения») |
|
||||
| 503 | `unavailable` | недоступен Postgres или хранилище сессий: ограниченная ошибка вместо 500 (`infra.md`); с лабы 4 — недоступен S3 на путях байтов вложений |
|
||||
|
||||
С change `track1-queue-overload` 429 у загрузки ещё при пределе незавершённых заданий
|
||||
(`UploadBacklogFull`, `Retry-After: 5` — `UPLOAD_BACKLOG_RETRY_AFTER_SECONDS`); 5 с:
|
||||
повтор через секунду почти всегда получил бы тот же отказ (вопрос 10 в `REPORT.md`).
|
||||
|
||||
`429` контракт описывает как ограничение частоты запросов и требует
|
||||
`Retry-After` — положительное целое. У нас 429 — только у загрузки, когда
|
||||
заняты места процесса (design change `upload-memory`, решение 2). Места
|
||||
ограничивают одновременность, а не частоту: трактовка — вопрос 1
|
||||
преподавателю (`REPORT.md`, «Открытые вопросы преподавателю»). До ответа — 429, ответ
|
||||
«503» меняет строку `DOMAIN_ERRORS`, сценарии и тесты, но не подход.
|
||||
`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`, `password`) не
|
||||
могут состоять только из пробельных символов (`str.strip()` пустой →
|
||||
400). Само значение не обрезать. `text` сообщения с лабы 4 — особый
|
||||
случай (раздел «Вложения» ниже).
|
||||
- Длины считаются в Unicode code points: `len(str)` в Python как раз они.
|
||||
`display_name` и `title` — 1–100, `text` — до 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 только на отказ соединения). Загрузка
|
||||
вложения тоже не идемпотентна: повтор — второе вложение.
|
||||
|
||||
## Вложения (лаба 4)
|
||||
|
||||
Семантика — `contracts/README.md`, «Вложения (с lab4)», и спек
|
||||
`attachments`; устройство — design change `attachments`.
|
||||
|
||||
- Ручки: `POST /api/v1/chats/{chat_id}/attachments?filename=…` — сырые
|
||||
байты одного PNG/JPEG (не multipart, не JSON), с лабы 5 — `202 Attachment`
|
||||
со снимком `status=queued`, `variants=[]`, `error_code=null` только после
|
||||
записи объекта в staging и `queued` с заданием в PostgreSQL; брокера в пути
|
||||
запроса нет: его отказ не меняет ни кода, ни срока ответа (design change
|
||||
`pipeline-reliability`, решение 1); `GET /api/v1/attachments/{id}` — метаданные: `queued`,
|
||||
`processing`, `ready`, `failed` — 200, у `ready` есть `variants`, у `failed`
|
||||
— `error_code` (`invalid_image`, `processing_failed`, `retry_exhausted`);
|
||||
`GET …/{id}/content` — байты оригинала или варианта потоком, `Content-Type`
|
||||
без параметров, `Content-Length`, `X-Content-Type-Options: nosniff`, без
|
||||
redirect. `variant` — `original`, `thumbnail`, `crop`, `optimized` (иное —
|
||||
400): у вложений этого уровня есть все три, у `ready` прежней версии — только
|
||||
thumbnail. Не `ready` — 409 `conflict` на любой `variant`; варианта нет — 404.
|
||||
Ключ объекта, адрес и ключи S3 в ответ не попадают.
|
||||
- Доступ — любой участник чата вложения. Посторонний, неизвестный id и
|
||||
вложение в статусе `pending` — одинаковый 404 «Not found».
|
||||
- Порядок проверок загрузки: 401 → 400 (`chat_id`, `filename`, их
|
||||
проверяет FastAPI после зависимостей) → 404 (членство) → 415
|
||||
(`Content-Type`: тип до `;`, без регистра) → 413 (`Content-Length`) →
|
||||
429 (предел незавершённых заданий, с change `track1-queue-overload`) →
|
||||
429 (место загрузки, с change `upload-memory`) → тело: 413 (счётчик
|
||||
прочитанного), 400 (тело не пришло за `[uploads]
|
||||
body_timeout_seconds` — `UploadTimedOut`, или обрыв —
|
||||
`UploadInterrupted`) → 415/413 (содержимое: сигнатура и подмена MIME,
|
||||
целостность, пиксели). Тело не читается до пройденных 1–7; отказ на
|
||||
1–6 места не ждёт и не занимает (посторонний и заведомо большое тело не
|
||||
вытесняют живые загрузки). Пустое тело — 415.
|
||||
- Места загрузки (спек `attachments`, «Одновременные загрузки реплики»;
|
||||
`service-layer.md`): `[uploads] max_concurrent` (4) на процесс, очередь
|
||||
до `max_waiting` (16) по порядку прихода, ожидание не дольше
|
||||
`wait_timeout_seconds` (5 с); очередь полна — 429 сразу, срок вышел —
|
||||
429 по сроку. Место держится до ответа. LB 429 не повторяет, повтор —
|
||||
клиент после `Retry-After`. Ни строки, ни объекта у 429 и у 400 по
|
||||
сроку тела нет.
|
||||
- Лимиты — константы `ATTACHMENT_MAX_BYTES` (10 485 760) и
|
||||
`ATTACHMENT_MAX_PIXELS` (40 млн), не настройки (`settings.md`). Ровно
|
||||
лимит проходит.
|
||||
- Целостность — структурная проверка без декодирования пикселей
|
||||
(`src/utils/image.py`): у PNG CRC чанков, поток IDAT ровно в объём по
|
||||
размерам, типы фильтров строк, IEND; у JPEG маркеры, таблицы DQT и
|
||||
DHT, один SOF, скан, EOI. Для скана — его компоненты есть в кадре,
|
||||
полоса прогрессивного скана допустима, нужные таблицы определены,
|
||||
есть данные у скана с кодами Хаффмана. Таблицы Хаффмана 0 и 1
|
||||
непрогрессивного кадра необязательны: декодер берёт стандартные (Motion
|
||||
JPEG). Условия — те, на которых `djpeg` падает
|
||||
(`evidence/attachments/jpeg-structure.md`). Новое условие сверять с
|
||||
libjpeg-turbo, иначе декодируемый файл получит 415. Хвост после
|
||||
IEND/EOI — часть оригинала. Байт внутри данных скана JPEG не ловится —
|
||||
граница, она названа в спеке и `REPORT.md`.
|
||||
- `filename` — 1–255 code points; 400 только по списку контракта: `/`,
|
||||
`\`, управляющие символы категории Unicode Cc (U+0000–U+001F,
|
||||
U+007F–U+009F) и строка из одних пробелов. Символы форматирования и
|
||||
направления текста (Cf, U+202E, U+2066), U+2028/U+2029 принимаются и
|
||||
возвращаются без изменений (решение пользователя 2026-10-20). Имя
|
||||
только отображается: ни в ключ, ни в путь, ни в журнал. Процент-коды
|
||||
`filename` — строгий UTF-8: Starlette меняет неверные байты на U+FFFD
|
||||
(`a%FFb.png` прошёл бы с 201), поэтому ручка сама разбирает
|
||||
`scope["query_string"]` (`_check_filename_encoding`): неверный UTF-8 и
|
||||
байт вне ASCII — `InvalidFilename` (400) до проверки членства.
|
||||
- `attachment_id` в пути и элементы `attachment_ids` в теле — `UuidIn`
|
||||
(раздел «Валидация → 400»). `attachment_ids`: 0–10, без повторов (и в
|
||||
другом регистре), иначе 400; каждое — принятое вложение этого чата
|
||||
(`queued`, `processing`, `ready`), иначе 404 до захвата ключа
|
||||
идемпотентности; `failed` — 409 после захвата, с откатом, а повтор уже
|
||||
отправленного сообщения с тем же ключом — тот же 201 (вопрос преподавателю,
|
||||
`QUESTIONS.md`). Ответы — id в нижнем регистре, в порядке отправки.
|
||||
- Текст сообщения: до 4000 code points; пустой текст — `""` или строка
|
||||
из одних пробельных символов — допустим только с хотя бы одним
|
||||
вложением, без вложений 400. Сохраняется как прислан, без обрезки
|
||||
(согласовано с преподавателем 2026-10-20, AGENTS.md). Правило держит
|
||||
валидатор `CreateMessage`; CHECK в БД — только верхняя граница.
|
||||
- Ранний ответ: 404, 413 и 415 отдаются, не дочитав тело. httpx и `curl`
|
||||
получают его и напрямую, через LB — любой клиент (HAProxy дочитывает
|
||||
тело сам). `urllib` напрямую к одной реплике ранний ответ на большом
|
||||
теле теряет (`BrokenPipe`) — ограничение, оно в `REPORT.md`; тесты на
|
||||
httpx.
|
||||
- Потерянный оригинал (design change `track2-reconciler`, решение 5):
|
||||
если сверка подтвердила, что объекта готового вложения нет или размер
|
||||
другой, и пометила его (`lost_at`), скачивание — 404 `not_found` без
|
||||
обращения к S3, как «отсутствующий вариант ready-объекта»
|
||||
(`contracts/README.md`); метаданные — 200 тем же `Attachment`
|
||||
(`status=ready`, `error_code=null`: другого статуса контракт лабы 4 не
|
||||
знает), ссылка в новом сообщении — 201. До пометки — 500, как выше.
|
||||
Контракт неоднозначен («404 — объекта нет», «неожиданное исключение —
|
||||
500», `status` только `ready`): это вопрос преподавателю (`REPORT.md`,
|
||||
«Открытые вопросы преподавателю», п. 2), сделан вариант по
|
||||
умолчанию. Ответ «иначе» меняет ветку `open_content`, сценарий
|
||||
`attachments` «Потерянный оригинал» и тест
|
||||
`test_reconcile_finds_and_fixes`.
|
||||
- Отказ S3 — 503 только на загрузке и скачивании байтов. Метаданные,
|
||||
сообщения (в том числе со ссылкой на готовое вложение), история и
|
||||
`/health/ready` работают без S3. Отказ брокера, relay и worker API не видит:
|
||||
загрузка — 202, готовность — 200.
|
||||
@@ -0,0 +1,134 @@
|
||||
---
|
||||
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"`.
|
||||
- Исключение — `attachment.py` (лаба 4): один роутер домена с двумя
|
||||
префиксами путей, `APIRouter(tags=["attachments"])` и полные пути
|
||||
`/chats/{chat_id}/attachments`, `/attachments/{attachment_id}` и
|
||||
`/attachments/{attachment_id}/content` в декораторах.
|
||||
- Версию задаёт `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)`), которая собирает
|
||||
его из `UowDep`: `get_uow` создаёт `SqlAlchemyUnitOfWork` на запрос поверх
|
||||
глобального `session_factory` (`src/infra/db/session.py`), кэш зависимостей
|
||||
отдаёт входу и сервису один экземпляр, а их блоки идут по очереди. Соединение
|
||||
занято только на шаг: на хэш пароля, между шагами и на передачу ответа оно в
|
||||
пуле (`infra.md`, change `unit-of-work`, решение 5). Фиксирует сервис
|
||||
(`service-layer.md`).
|
||||
- Общий срок JSON-запроса — `request_deadline`: зависимость с `yield` вокруг
|
||||
`deadline_scope` (`src/infra/db/scope.py`), подключена в
|
||||
`routers/v1/__init__.py` на роутерах пользователей, сессий, чатов и сообщений
|
||||
(`json_deadline`), та же настройка `[database] request_timeout_seconds`.
|
||||
Срок блока один не даёт ни ответа раньше `timeout server` LB (два шага — до
|
||||
12 с), ни срока очереди хэшей (решение 6). Истёк — та же запись «Database is
|
||||
unavailable» и 503. Новый JSON-роутер получает срок одной строкой там же.
|
||||
- Длинная передача байтов (вложения, лаба 4; design change
|
||||
`attachments`, решение 5). Роутер вложений общего срока не имеет: передача
|
||||
дольше срока одного блока, у него срок только на шаг. Вход — тот же
|
||||
`CurrentUser`, соединение вернулось в пул до тела запроса. Поэтому ручки
|
||||
вложений:
|
||||
- загрузка объявляет `request: Request` и не объявляет параметр тела —
|
||||
FastAPI тело не читает; схема тела (`image/png`, `image/jpeg`,
|
||||
`format: binary`) — в `openapi_extra`. Тело уходит в сервис
|
||||
асинхронным итератором поверх `request.stream()`, обёртка переводит
|
||||
`ClientDisconnect` в доменное `UploadInterrupted` (400): в итоговой
|
||||
записи 400, а не 500 с traceback. `Content-Type` — тип до `;`, без
|
||||
пробелов, в нижнем регистре; `Content-Length` — `int` или `None`.
|
||||
До сервиса ручка проверяет кодировку `filename` по сырой строке
|
||||
запроса (`_check_filename_encoding` → `InvalidFilename`, 400):
|
||||
Starlette заменил бы неверный UTF-8 на U+FFFD (`api-contract.md`);
|
||||
- скачивание — `StreamingResponse` над генератором блоков объекта S3:
|
||||
`media_type` вложения (у `image/*` Starlette `charset` не добавляет),
|
||||
`Content-Length`, `X-Content-Type-Options: nosniff`; генератор сам
|
||||
закрывает объект в `finally`, тот же закрыватель — фоновой задачей
|
||||
ответа на случай, если генератор не начался;
|
||||
- `variant` — `Literal` четырёх значений контракта, по умолчанию
|
||||
`original`; в сервис — `AttachmentVariantName` или `None` (оригинал);
|
||||
- загрузка — `status_code=202`, а не 201: приём, а не создание готового
|
||||
объекта.
|
||||
- Ошибки — доменные исключения из сервиса. `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`.
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
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).
|
||||
- Регистрация хэширует пароль до блока единицы работы. Вход читает хэш в
|
||||
блоке и выходит из него до проверки пароля (писать нечего, откат): соединение
|
||||
пула не ждёт KDF и очередь лимита; сессия вставляется вторым блоком. Срок
|
||||
очереди KDF — общий срок JSON-запроса (`request_deadline`, `api-layer.md`).
|
||||
- Пароль хэшируется целиком как 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`).
|
||||
@@ -0,0 +1,452 @@
|
||||
---
|
||||
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 (кэш карточек)
|
||||
→ s3 (байты вложений, с лабы 4)
|
||||
migrate (один раз на up) ──────→ postgres
|
||||
s3-bootstrap (один раз на up) ─→ s3 (bucket, пользователи API и уборщика)
|
||||
cleaner (долгоживущий, с лабы 4) → postgres, s3 (незавершённые загрузки)
|
||||
```
|
||||
|
||||
Реплики ждут обоих одноразовых сервисов (`service_completed_successfully`).
|
||||
|
||||
## Сервисы 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`).
|
||||
- **`s3`, `s3-bootstrap`** (с лабы 4) — сервер S3 и его bootstrap
|
||||
(`docker.md`, раздел S3). Реплики ждут bootstrap, как миграций.
|
||||
- Лимиты 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` у них нет — контракт это допускает.
|
||||
С change `upload-memory` так же `http-error status 400` с `code`
|
||||
`invalid_request`: неверный запрос и клиент, замолчавший посреди тела
|
||||
дольше `timeout client` (30 с; до change — HTML). 408 на медленные
|
||||
заголовки (`timeout http-request`) HAProxy строит до потока запроса,
|
||||
`http-error` его не меняет — остаётся HTML (`KNOWN_ISSUES.md`,
|
||||
`REPORT.md`).
|
||||
- `tune.sndbuf.server 262144` в `global` (change `upload-memory`,
|
||||
решение 6): буфер отправки LB к реплике фиксирован, тело загрузки,
|
||||
которое реплика не читает (ожидание места, отказ до тела), не копится
|
||||
в памяти LB целиком. Рядом — `tune.rcvbuf.client 131072` (apply,
|
||||
design «Уточнения apply», п. 11): буфер приёма от клиента фиксирован,
|
||||
иначе ядро растит его до `tcp_rmem` ВМ (32 MiB), и тело, которое LB не
|
||||
может отдать реплике, копится там — до 9 MiB на сокет клиента, `sock`
|
||||
LB до 112 MiB при 40 загрузках по 10 MiB. С ним `make
|
||||
bench_uploads_quick` («с лимитом», 10 MiB): пик LB 35,6 / 41,4 /
|
||||
57,3 MiB при C = 1 / 10 / 40 — 0,56 MiB на клиента (было ~2,6 в
|
||||
метке, отброшенной до правки), очередь приёма сокета клиента ≤
|
||||
0,24 MiB; скорость одного клиента прежняя (11,25 загрузки/с, p50
|
||||
84 мс). Окно 128 KiB даёт ~20 Мбит/с при RTT 50 мс: 10 MiB — за ~4 с
|
||||
при сроке тела 30 с; клиенту с RTT больше ~370 мс 30 с на 10 MiB не
|
||||
хватит — ограничение в `REPORT.md`. Буфер приёма LB от реплики
|
||||
(ответы, скачивание) не меняется. `maxconn` на слот не ставится —
|
||||
менял бы поведение всех путей лабы 3.
|
||||
- Статистика — страница `/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 ещё отдаст. С change
|
||||
`unit-of-work` срок настройки — на блок, а соединение занято на шаг, поэтому
|
||||
звено держит общий срок JSON-запроса `request_deadline` на роутерах
|
||||
пользователей, сессий, чатов и сообщений (`api-layer.md`): без него два шага
|
||||
дали бы до 12 с и 504 от LB вместо 503 реплики. При замороженном PostgreSQL к
|
||||
общему сроку добавляется закрытие соединения (`DB_CLOSE_TIMEOUT_SECONDS`): 6 + 2
|
||||
= 8 с < 10 с; при сроке 8 с ответ стал бы 504. Ручки вложений его не имеют:
|
||||
вход и блок метаданных и скачивания — до 12 с при `timeout server` 10 с
|
||||
(`KNOWN_ISSUES.md`, дефект прежний);
|
||||
- путь загрузки вложения (change `upload-memory`, решение 7) — свой
|
||||
`timeout server` 30 с: `http-request set-timeout server 30s if
|
||||
METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ }` в `backend
|
||||
api`. Больше самого долгого молчания живой загрузки: до тела `2 ×
|
||||
request_timeout_seconds + [uploads] wait_timeout_seconds` = 17 с
|
||||
(вход, членство, ожидание места), а с закрытием соединения на зависшем сервере
|
||||
(`DB_CLOSE_TIMEOUT_SECONDS`, вне срока блока) до 2 × (6 + 2) + 5 = 21 с; после тела — проверка (до ~4 с) +
|
||||
tx1 6 + PUT 5 + tx2 6 = 21 с, а ветка компенсации после неудачной tx2 — ещё
|
||||
DELETE 5, 26 с: брокера в пути нет (change `pipeline-reliability`, решение 11).
|
||||
Тело ограничивают
|
||||
`[uploads] body_timeout_seconds` (30 с) и `timeout client` (30 с).
|
||||
Остальные пути — прежние 10 с: общий 30 с держал бы любой запрос к
|
||||
зависшей реплике 30 с до 504, а замеры `failover` рассчитаны на 10.
|
||||
Выражение повторяет путь ручки в `src/api/routers/v1/attachment.py`:
|
||||
при смене префикса API менять вместе. Наибольшая длительность загрузки
|
||||
U = 21 + 30 + 26 ≈ 77 с < `ROLLOUT_DRAIN_TIMEOUT` 90 с;
|
||||
`graceful_shutdown_seconds` прежний (8 с): `stop-one.sh` и `docker
|
||||
stop` — отказ, загрузка дольше 8 с обрывается, строку `pending`
|
||||
убирает уборщик. Проверка поведения — `driver.py lb-upload-timeouts`:
|
||||
временная сеть, HAProxy закреплённого образа с конфигурацией проекта
|
||||
(`--config`) и заглушка реплики под именем `api` на образе API, пять
|
||||
случаев параллельно (~35 с) — молчание 12 с до и после тела загрузки —
|
||||
201, 12 с на другом пути — 504 через ~10 с, 32 с на пути загрузки —
|
||||
504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта,
|
||||
`request_id` = `X-Request-Id`; код 1 при расхождении (на
|
||||
конфигурации `f894040` — 502 и 504 через 10 с и 400 HTML). Evidence —
|
||||
`evidence/uploads/lb-timeouts.md`;
|
||||
- таймаут проверки внутри `/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` 90 с (с change
|
||||
`upload-memory`; больше `timeout server` пути загрузки 30 с и
|
||||
наибольшей длительности загрузки ≈ 73 с, иначе замена обрывала бы
|
||||
живую загрузку; обычно дренаж — 0–2 с) → `maint` → `docker stop
|
||||
--timeout 10` (в строке скрипта —
|
||||
время и код выхода: 0 — graceful, 137 — SIGKILL по сроку) → `docker
|
||||
rm` → адрес ушёл из слота (DNS, ≤ 10 с) → `ready`.
|
||||
6. Шаги 3–5 для каждой старой. В конце — N реплик на новом образе, все
|
||||
`UP`, ни одной прежней.
|
||||
|
||||
**Имена контейнеров после замены.** Compose нумерует новые контейнеры
|
||||
сервиса по возрастанию, поэтому после замен реплики называются `api-N`
|
||||
с растущим номером (`mtusi-lab5-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` (сборка рабочего
|
||||
дерева, все реплики разом).
|
||||
|
||||
**Уборщика скрипт не пересоздаёт** (design change `upload-consistency`,
|
||||
решение 9): как bootstrap, он не реплика за LB. После `make
|
||||
rolling_update` уборщик работает на прежнем образе — корректно, схема
|
||||
только расширяется (индекс). Новый код уборщика — `docker compose up -d
|
||||
--no-deps cleaner` или `make run_docker`; его SIGTERM доводит текущий
|
||||
шаг строки и выходит за ≤ 6 с. Пометка строки к уборке (verify W1,
|
||||
design `upload-consistency`, «Уточнения apply», п. 16 и 21) полностью
|
||||
защищает от `ready` без объекта, только когда новые и реплики, и
|
||||
уборщик. Смеси версий не хуже, чем до правки:
|
||||
- новый уборщик + реплики до `87c48b9` (пометку не проверяют): объект и
|
||||
строка удаляются одной транзакцией под блокировкой, поэтому прежний
|
||||
`mark_ready` либо делает строку `ready` с целым объектом (уборщик её
|
||||
пропускает), либо ждёт commit и находит 0 строк;
|
||||
- прежний уборщик (пометку не ставит) + новые реплики — как до правки.
|
||||
|
||||
В обеих остаётся прежний риск: загрузка, пережившая grace, при откате
|
||||
транзакции уборки после удачного DELETE объекта; это ограничение в
|
||||
`REPORT.md`. Порядок сокращает окно смеси: вперёд — сначала реплики
|
||||
(`make rolling_update`), потом `docker compose up -d --no-deps cleaner`;
|
||||
откат реплик на версию раньше `87c48b9` (`make rolling_update
|
||||
COMMIT=<прежний> MIGRATE=0`) — сначала уборщик (его откат или `docker
|
||||
compose stop cleaner`), потом реплики. Обратная совместимость есть:
|
||||
новый `mark_ready` на строках, вставленных прежним кодом, работает
|
||||
(вставка всегда писала `created_at` = `updated_at`).
|
||||
|
||||
**Порядок обновления со сверкой** (design change `track2-reconciler`,
|
||||
решение 6): вперёд — `docker compose up -d s3-bootstrap` (политика
|
||||
уборщика со списком по префиксу), затем `make rolling_update` (миграция
|
||||
`lost_at`, затем реплики), затем `docker compose up -d --no-deps cleaner`.
|
||||
Откат — сначала уборщик (`docker compose stop cleaner` или прежний
|
||||
образ), потом `make rolling_update COMMIT=<прежний> MIGRATE=0`; колонка и
|
||||
пометки остаются и прежнему коду не мешают. Смеси не хуже, чем до
|
||||
change: прежние реплики колонку не читают (у помеченного без объекта —
|
||||
500, как раньше); новый уборщик на прежней политике получает
|
||||
`AccessDenied` на списке — проход сверки прерван, уборка работает; новый
|
||||
уборщик на прежней схеме — «Reconcile pass failed», процесс живёт.
|
||||
|
||||
**Порядок обновления с брокером** (design change `async-attachments`, решение
|
||||
14): вперёд — `docker compose up -d --wait rabbitmq`, `docker compose up -d
|
||||
s3-bootstrap`, `make rolling_update`, `docker compose up -d --no-deps cleaner
|
||||
worker`. Смесь версий: прежняя реплика загружает по-старому (201, `ready`,
|
||||
конечный ключ) и даёт 500 на чтении строки нового статуса, новая читает её строку
|
||||
как `ready` без вариантов; переход 201 → 202 всё равно несовместим для клиента на
|
||||
время замены — названо в `REPORT.md`. Откат — `make rolling_update COMMIT=<прежний>
|
||||
MIGRATE=0`, `docker compose stop worker`, прежний образ уборщика.
|
||||
|
||||
**Порядок обновления с relay** (design change `pipeline-reliability`, Migration Plan):
|
||||
вперёд — `docker compose up -d s3-bootstrap`, `make rolling_update` (две ревизии, затем
|
||||
реплики), `docker compose up -d --no-deps worker cleaner`, затем `docker compose up -d
|
||||
--no-deps relay`: worker раньше relay, иначе прежний worker сделает `ready` только с
|
||||
thumbnail. До запуска relay новые загрузки отвечают 202 и ждут. Откат — `make
|
||||
rolling_update COMMIT=<прежний> MIGRATE=0
|
||||
COMPOSE_FILE=docker-compose.yml:infra/rollback/broker.compose.yml` (прежние реплики
|
||||
публикуют сами, и без адреса и пароля брокера их загрузка — 503), прежние
|
||||
worker и уборщик, relay останавливается, когда нет заданий `queued` без отметки. Схема
|
||||
остаётся. Новая реплика прежнего образа, созданная после отката без этого override
|
||||
(`make replicas`, `docker compose up`), тоже получит 503 на загрузке: `COMPOSE_FILE` с
|
||||
override нужен, пока стенд на прежнем образе.
|
||||
|
||||
**Bootstrap S3 скрипт не запускает** (design change `s3-storage`,
|
||||
решение 9): новая реплика поднимается с `--no-deps`. Bootstrap, как
|
||||
миграции, только расширяет: новые пользователи и политики не отбирают
|
||||
прав у старых реплик. Его изменения (новая строка `infra/s3/bootstrap.sh`,
|
||||
новый секрет API в `.env`) применяет `docker compose up -d s3-bootstrap`
|
||||
или `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, одна нода S3
|
||||
без репликации. Выдерживается отказ процесса API (любой одной реплики,
|
||||
при ≥2 живых). Не выдерживается отказ хоста, LB и Postgres. Отказ
|
||||
Valkey — деградация до Postgres, не отказ. Отказ S3 — 503 на путях
|
||||
вложений, текст работает, `/health/ready` 200. SIGKILL процесса S3
|
||||
подтверждённых объектов не теряет, отказ диска или ВМ — теряет (нет
|
||||
реплик и fsync). Это пишется в `REPORT.md` прямо (`COURSE.md`,
|
||||
«Воспроизводимость и честные измерения»).
|
||||
@@ -0,0 +1,826 @@
|
||||
---
|
||||
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.
|
||||
|
||||
**S3 (лаба 4) описан, но профили лаб 2–3 его не запускают** (design
|
||||
change `s3-storage`, решение 9): старт стенда перечисляет сервисы, а
|
||||
реплики поднимает с `--no-deps`, поэтому ни `s3`, ни `s3-bootstrap` не
|
||||
стартуют, и методика прежних профилей не меняется. Compose всё равно
|
||||
требует секреты S3 при разборе файла (`:?`), их `compose_env` тоже
|
||||
генерирует на прогон (пять значений). Override `s3` —
|
||||
`container_name: mtusi-bench-s3`, `restart: "no"`, порты сброшены;
|
||||
`bench.env` — `S3_HOST`, `S3_PORT`, `S3__BUCKET=bench`. Реплики получают
|
||||
`S3__*` в окружении, и `S3__HOST`, `S3__PORT`, `S3__BUCKET` попадают в
|
||||
паспорт (`stand.app_env`); меток лабы 3 в этом репозитории нет, поэтому
|
||||
сравнивать их не с чем. Лимиты `BENCH_S3_*` и S3 в паспорте появятся с
|
||||
профилем, который его запускает (`upload-memory`, трек 2).
|
||||
|
||||
Фильтр окружения паспорта (`SECRET_ENV_MARKS` в `run.py`) убирает имена с
|
||||
`PASSWORD`, `SECRET` и `ACCESS_KEY`: иначе секрет и ключ доступа S3
|
||||
попали бы в `meta.json`.
|
||||
|
||||
Инструменты `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` (профили `uploads`, `uploads_quick`), `uploads.py`, `sampler.sh` (режим `peak`), `k6/uploads.js`, `k6/prepare.js` | `make bench_uploads [UPLOADS_LABEL=…]`, `make bench_uploads_quick` | память реплики при одновременных загрузках вложений (change `upload-memory`): одна реплика 1 CPU / 512 МБ без swap, S3 рабочего стенда, варианты «до» / «без лимита» / «с лимитом», тела PNG ~1 и ~10 MiB, 1 / 10 / 20 / 40 клиентов; пик `memory.peak` окна, OOM, ответы по кодам, загрузок/с и p50/p95/p99; результаты — `evidence/uploads/<метка>/` |
|
||||
| `run.py` (профили `reconcile`, `reconcile_quick`), `reconcile.py`, `fill_objects.py`, `sampler.sh` (режим `scan`), `k6/background.js`, `k6/prepare.js` | `make bench_reconcile [RECONCILE_LABEL=…]`, `make bench_reconcile_quick` | стоимость сверки bucket и БД (change `track2-reconcile-cost`): наполнение мимо API (`\copy` и PUT в S3), разовые проходы уборщика — стратегии `batch` и `head`, глубокая, CPU уборщика, предел скорости, фоновая нагрузка, отказ по пределу «до» и «после»; счёт сверки против метрик шлюза S3, CPU и память за окно прохода; результаты — `evidence/reconcile/<метка>/` |
|
||||
| `run.py` (профили `queue`, `queue_quick`), `overload.py`, `make_images.py`, `queue.compose.yml`, `rabbitmq/`, `sampler.sh` (режим `queue`), `k6/queue.js`, `k6/queue_sweep.js`, `k6/background.js`, `k6/prepare.js` | `make bench_queue [QUEUE_LABEL=…] [RESUME=1]`, `make bench_queue_quick` | очередь под перегрузкой (change `track1-queue-overload`): стенд с S3, брокером, relay, worker и уборщиком, настройки конкуренции и prefetch × классы изображений, блоки предела, приёма, второго worker и рестартов; результаты — `evidence/queue/<метка>/` |
|
||||
| `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 по-прежнему
|
||||
без лимита;
|
||||
- **буфер приёма сокетов реплики** (с change `upload-memory`): `sysctls`
|
||||
сервиса `api` из основного `docker-compose.yml` (`net.ipv4.tcp_rmem`
|
||||
`4096 131072 524288`) действует и на `bench/`; значение — в паспорте
|
||||
всех профилей (`stand.api_tcp_rmem`), ядро ВМ — `docker.kernel`.
|
||||
Для прежних профилей это смена стенда, но запросы и ответы JSON меньше
|
||||
начального буфера (128 KiB) — результаты не меняются; метки до change
|
||||
поля в паспорте не имеют. Там же исправлено: контейнер сэмплера (образ
|
||||
PostgreSQL) удаляется с `-v`, иначе каждый запуск оставлял анонимный
|
||||
volume `/var/lib/postgresql`;
|
||||
- **S3** — запускают только профили `uploads`, `reconcile` и `queue`: образ,
|
||||
аргументы и лимиты рабочего стенда (`BENCH_S3_*`, 1 CPU / 512 МБ, swap =
|
||||
память; у `reconcile` — ещё порт метрик шлюза на loopback), bucket
|
||||
`bench` (`bench.env`) и пользователи — тот же `s3-bootstrap`; override
|
||||
`s3` нужен compose и в остальных профилях;
|
||||
- **уборщик** — запускает только профиль `reconcile` разовыми проходами:
|
||||
лимиты `BENCH_CLEANER_*` (`cleaner_cpus` 0,25, `cleaner_memory` 256m —
|
||||
рабочего стенда, без swap) compose требует при разборе у всех профилей;
|
||||
окружение реплик (`stand.app_env`) они не меняют;
|
||||
- **брокер, relay и worker** — запускает только профиль очереди, лимиты
|
||||
`BENCH_BROKER_*`, `BENCH_RELAY_*`, `BENCH_WORKER_*` рабочего стенда; плагин метрик
|
||||
брокера и политика перезапуска worker — только его `queue.compose.yml`; остальные
|
||||
профили меряют реплику;
|
||||
- **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`: `git archive
|
||||
<commit> | docker build` под тегом `mtusi-messenger:bench-from`, затем
|
||||
`docker tag` на `mtusi-messenger:bench`. Рабочее дерево не трогается;
|
||||
тег снимается при уборке. `--from <commit>` — отладка (`overrides`).
|
||||
- **Какой commit** (спек `load-benchmark`, «Прежний commit профиля
|
||||
замены»; design change `attachments`, решение 14): commit текущей лабы
|
||||
до изменения, которое показывает замена. Сейчас — `7f38948`, последний
|
||||
перед change `pipeline-reliability`: замена показывает его две ревизии.
|
||||
Прежний образ брокера от реплики не требует: настройки `BROKER__*` у него
|
||||
необязательны, соединяется он первой публикацией, а `k6/failover.js`
|
||||
вложений не загружает. Commit меняется:
|
||||
- при переходе в следующую лабу — commit прошлой лабы в её истории нет
|
||||
(AGENTS.md, «Переход в следующую лабу»);
|
||||
- когда замена должна показать новое изменение схемы.
|
||||
|
||||
`run.py` проверяет commit до стенда (`git rev-parse --verify
|
||||
<commit>^{commit}`): нет в истории — код 2, сообщение называет commit
|
||||
и `--from`. Commit — в паспорте метки (`rollout.from_commit`).
|
||||
- Замену делает **тот же** `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, соответствие реплик слотам — строки скрипта.
|
||||
- Образы реплик в паспорте и сравнении «все на одном, отличном от прежнего» —
|
||||
метка `com.docker.compose.image`, у контейнера без неё — `.Image`
|
||||
(`CONTAINER_IMAGE` в `run.py`, `docker.md`, «Обновление кода на стенде»). Так
|
||||
же поле `id` образов `stand.*`: имя поля прежнее.
|
||||
- «Старые» и «новые» ответы — по `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` после проверки хоста, рабочий стенд остановлен.
|
||||
|
||||
## Профиль загрузок (`uploads`)
|
||||
|
||||
Спек `load-benchmark`, «Профиль загрузок»; design change `upload-memory`,
|
||||
решение 10. Методика — поля `Profile` (`uploads_*`) в `run.py`, разбор без
|
||||
docker — `bench/uploads.py` (`--selftest`). С change `pipeline-reliability`
|
||||
(решение 16) брокер, relay и worker описаны в `bench.compose.yml` (лимиты
|
||||
`BENCH_BROKER_*`, `BENCH_RELAY_*`, `BENCH_WORKER_*`, compose требует их при разборе
|
||||
у всех профилей) и здесь не запускаются: реплика к брокеру не обращается,
|
||||
задания ждут в PostgreSQL. Поэтому у всех вариантов `UPLOADS__MAX_UNFINISHED_JOBS=0`
|
||||
(change `track1-queue-overload`, решение 13): иначе профиль мерил бы предел, а не
|
||||
память приёма; `app_env` вариантов — в паспорте. Метка `baseline`, снятая на
|
||||
`ff1a83b` с брокером, с новыми
|
||||
не сравнивается. Успех — 202, у варианта «до» —
|
||||
201: столбец `s201` не переименован, код называет `success_code` в конце `runs.csv` и
|
||||
раздел `uploads` паспорта.
|
||||
|
||||
- **Стенд:** LB, одна реплика API 1 CPU / 512 МБ без swap (OOM-kill
|
||||
виден, а не прячется в swap), PostgreSQL, Valkey, S3 и `s3-bootstrap`
|
||||
(раздел выше); k6 без лимита.
|
||||
- **Варианты:** «до» — образ `Profile.uploads_before` (`04f8592`, commit
|
||||
переноса лабы 4: код лабы 4 с местами загрузок, успех 201; прежнего кода
|
||||
`f894040` в истории лабы 5 нет, поэтому H2 про «до» старой метки здесь не
|
||||
воспроизводится; `git archive` → тег `bench-from`,
|
||||
проверка commit до стенда — код 2, как у `rollout_from`); «без лимита» — образ checkout с
|
||||
`UPLOADS__MAX_CONCURRENT=1000`, `UPLOADS__MAX_WAITING=0`; «с лимитом» —
|
||||
образ checkout со значениями по умолчанию. Окружение варианта задаёт
|
||||
override `.work/variant.compose.yml`, а не `BENCH_*`: иначе изменился
|
||||
бы `stand.app_env` прежних профилей, и `bench_compare` отказал бы со
|
||||
старыми метками. В паспорте — `app_env` по вариантам.
|
||||
- **Тела:** PNG из шума RGB шириной 1024 (`random.Random(seed + высота)`,
|
||||
stdlib): ~1 MiB (1 048 276 байт) и ~10 MiB (10 479 107 байт), не больше
|
||||
10 485 760; размеры и SHA-256 — в паспорте. Тело 10 MiB у `uploads` и
|
||||
`uploads_quick` побайтно одно.
|
||||
- **Прогон:** вариант × размер × C ∈ {1, 10, 20, 40} × повтор (3), круги
|
||||
с перестановкой по зерну. Перед каждым — новый volume S3 с bootstrap
|
||||
(`kill`), новая реплика с окружением варианта, ожидание процесса и `UP` в LB,
|
||||
одна разогревающая загрузка. PostgreSQL, пользователь и чат — один раз
|
||||
на метку. Окно — `constant-vus` k6 (`k6/uploads.js`): C VU, 3 с
|
||||
разгона и 20 с окна без пауз; на 429 — пауза `Retry-After`, на прочие
|
||||
ошибки — 1 с; строка на запрос — в файл консоли.
|
||||
- **Память:** сэмплер `peak` сбрасывает `memory.peak` реплики, S3 и LB
|
||||
перед нагрузкой (после разогрева) и читает пик в конце; окно памяти —
|
||||
весь прогон k6. Раз в 0,2 с — `memory.current`, `anon`, `sock`,
|
||||
`oom_kill`. Ядро без сброса (< 6.12) — наибольшая выборка и
|
||||
`peak_sampled`. Загрузок/с и перцентили — по загрузкам окна `[t0 + 3,
|
||||
t0 + 23)`, ответы по кодам — за весь прогон, в том числе после OOM.
|
||||
- **Пометки:** `oom` (реплика завершена ядром — результат варианта, не
|
||||
сбой команды; следующий прогон на новой реплике), `host_swap`,
|
||||
`peak_sampled`, `s3_down`. Блокировка `bench/.bench.lock`, отказ
|
||||
занятой метки и остатков стенда — как у остальных профилей.
|
||||
- **Результаты:** `evidence/uploads/<метка>/` — `meta.json` (раздел
|
||||
`uploads`: commit «до», образы, тела, план, `app_env`), `runs.csv`
|
||||
(строка на прогон: вариант, размер, C, повтор, память до окна, пик
|
||||
окна, пик старта, наибольшие `anon` и `sock`, `oom_kill`, код выхода и
|
||||
`OOMKilled`, ответы по кодам, успешных загрузок/с, p50/p95/p99, пики S3
|
||||
и LB, пометки, код успеха; прочий 201 или 202 — `s_other`), `summary.md` (медиана и min–max по ячейкам, сценарии
|
||||
спеков — с ростом на клиента и итогом «Буферы соединений ограничены»
|
||||
по сумме роста LB и `sock` реплики от C = 1 до 40, H1–H4 с итогом
|
||||
только по ячейкам гипотез; у метки `baseline` этих строк ещё нет —
|
||||
design, «Уточнения apply», пп. 12–13), `raw/<прогон>-k6.json`,
|
||||
`raw/<прогон>-peak.log`.
|
||||
`quick-uploads-*` — в `.gitignore`.
|
||||
- **Время:** полный профиль — 72 прогона, ~50 мин; `uploads_quick` —
|
||||
«без лимита» и «с лимитом», 10 MiB, C ∈ {1, 10, 40}, один повтор,
|
||||
~4,5 мин. Замер для отчёта — `make bench_uploads` после проверки хоста,
|
||||
рабочий стенд остановлен (`make stop`), гипотезы H1–H4 закоммичены
|
||||
раньше метки.
|
||||
|
||||
## Профиль сверки (`reconcile`)
|
||||
|
||||
Спек `load-benchmark`, «Профиль сверки» и «Стоимость сверки в отчёте»;
|
||||
design change `track2-reconcile-cost`, решения 1–3, 7–13. Методика — поля
|
||||
`Profile` (`reconcile_*`, `cleaner_*`) в `run.py`, модель набора, план,
|
||||
разбор, вердикты и сводка без docker — `bench/reconcile.py`
|
||||
(`--selftest`), загрузчик объектов — `bench/fill_objects.py`, фоновая
|
||||
нагрузка — `bench/k6/background.js`.
|
||||
|
||||
- **Стенд:** LB, две реплики 1 CPU / 512 МБ, PostgreSQL 2 / 1 ГБ, Valkey
|
||||
0,5 / 128 МБ, S3 и `s3-bootstrap` рабочего стенда; к аргументам S3
|
||||
добавлен `-metricsPort=9327` (override `.work/s3-metrics.compose.yml`
|
||||
из `command` сервиса `s3` по `docker compose config` того же стенда —
|
||||
списка аргументов в двух местах нет). Порт слушает loopback контейнера
|
||||
S3, из сети стенда недоступен; **у прочих профилей и рабочего стенда его
|
||||
нет**. Сэмплер `scan` с интервалом 0,5 с (`reconcile_sample_interval_s`)
|
||||
на этап, k6 без лимита.
|
||||
- **Проход** — разовый уборщик `docker compose run -d --name
|
||||
mtusi-bench-reconcile-<n> --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30
|
||||
cleaner reconcile …` (лимиты `BENCH_CLEANER_*` в `bench.compose.yml` —
|
||||
0,25 CPU / 256 МБ без swap, в управляемом опыте `BENCH_CLEANER_CPUS=1`
|
||||
на вызов), затем `docker wait`, журнал, `docker inspect` и `docker rm`
|
||||
при любом исходе. Вариант «до» — тот же вызов с override
|
||||
`.work/cleaner-before.compose.yml` (`image: mtusi-messenger:bench-from`,
|
||||
`Profile.reconcile_before` — `04f8592`, commit переноса лабы 4: прежнего
|
||||
`7f4e626` в истории нет, ранний отказ по пределу в «до» уже есть, поэтому
|
||||
S4 ждёт у обеих ячеек одно число находок, а вердикт S4 «до и после»
|
||||
ничего не показывает — метка лабы 4 осталась в её отчёте;
|
||||
`git archive` → тег `bench-from`, проверка commit до стенда — код 2, как
|
||||
у `rollout_from`). Тег стенда не меняется.
|
||||
- **Этапы полной метки:** A — свежий стенд, 1 000 × 1 MiB, `batch`,
|
||||
`deep`, `deep-fast`; B — свежий, 10 000 × 4 KiB, `batch`, `head`,
|
||||
`deep`; C — тот же, +20 000, `batch`, `head`; D — тот же, +70 000,
|
||||
`batch` и блок под нагрузкой `stand`, `stand-unlimited`,
|
||||
`fast-unlimited`, `fast-limited`; S4 — свежий, 10 000 согласованных и
|
||||
1 000, затем 10 000 строк `ready` без объектов, `before` и `after`
|
||||
(`--apply --max-changes 100`, у `after` — без предела скорости). Три
|
||||
повтора кругами внутри группы (`reconcile.plan_passes`), план — в
|
||||
`meta.json` до первого прохода. У группы из одной ячейки (D без
|
||||
нагрузки — только `batch`) повторы идут подряд: остальные проходы
|
||||
набора — блок под нагрузкой (спек `load-benchmark`, verify S8). Ячейки без нагрузки — dry-run без
|
||||
предела скорости. `reconcile_quick` — один стенд 2 000 × 4 KiB, все
|
||||
виды по одному проходу, окна 5 с, S4 с 300 кандидатами на своём свежем
|
||||
стенде.
|
||||
- **Набор** (решение 2): объект `i` — `id` UUID v4 из SHA-256
|
||||
`<зерно>:<i>`, содержимое — повторённый SHA-256 `<зерно>:<i>:c`, класс —
|
||||
`i mod 400` (0 — объект без строки, 1 — строка без объекта, 2 — размер
|
||||
в строке на байт больше, 3 — зависшая загрузка `pending` с объектом);
|
||||
строки — читаемый чат и его владелец из `prepare.js`, `created_at` =
|
||||
`updated_at` = сутки назад. Проходы этапа — через grace + 2 с после
|
||||
последнего PUT. Каждый проход сверяет `found` по классам,
|
||||
`listed_objects` и `checked_rows` с моделью (`reconcile.model`):
|
||||
расхождение — отказ команды с проходом, классом и обоими числами.
|
||||
- **Граница чёрного ящика** — новые исключения, только у этого профиля и
|
||||
только на свежем стенде `mtusi-bench`:
|
||||
- метаданные набора — `\copy attachments (…) FROM STDIN` через `docker
|
||||
exec -i … psql` (данные стенда, схему не трогает; файла CSV нет —
|
||||
строки генерирует `reconcile.rows_csv`);
|
||||
- объекты — `bench/fill_objects.py` в контейнере `mtusi-bench-fill` на
|
||||
образе стенда (botocore образа, `src` не импортируется, `bench/` на
|
||||
чтение, ключи API — `docker run -e <имя>` без значения в argv, три
|
||||
процесса × 24 потока);
|
||||
- метрики шлюза S3 — `docker exec mtusi-bench-s3 wget` на loopback до
|
||||
и после прохода; `pg_stat_database` — psql до и после;
|
||||
- проход — процесс уборщика из образа, результат — его записи
|
||||
«Started cleaner», «Finished reconcile pass», «Reconcile changes
|
||||
exceed limit» (`raw/<проход>-cleaner.json`; записи о расхождениях —
|
||||
числом).
|
||||
`mtusi-bench-fill` и `mtusi-bench-reconcile-*` — в остатках стенда и в
|
||||
уборке `Stand.stop()`.
|
||||
- **Счёт S3:** шлюз считает HEAD типом GET, поэтому `LIST = list`,
|
||||
`GET = head + get`, `DELETE = delete`; в ячейках без нагрузки неравенство
|
||||
— пометка `count_mismatch` (строка остаётся). С change `pipeline-reliability`
|
||||
(решение 16) сверка на один LIST больше: страница списка staging, пустая, —
|
||||
в счёте обоих источников и в модели H1 (`reconcile.STAGING_PAGES`);
|
||||
`listed_objects` её не считает. Строки набора идут `\copy` без `staging_key` —
|
||||
строки прежней версии с объектом по `object_key`: так сверка их и читает.
|
||||
Новые `attempt_base` и `attachment_job_replays` принадлежат заданиям, набор их не
|
||||
пишет. Вариант `before` (`04f8592`) staging не знает, H1 его не считает.
|
||||
- **Ресурсы:** окно прохода — `[t − duration_ms, t]`, `t` — время записи
|
||||
«Finished reconcile pass» (часы ВМ); CPU уборщика (по `id` контейнера
|
||||
прохода), S3, PostgreSQL, реплик и LB — по отсчётам сэмплера; память
|
||||
уборщика — выборка у начала окна и наибольшая за жизнь контейнера.
|
||||
- **Фоновая нагрузка (H4):** один k6 `background.js` на блок — 300
|
||||
скачиваний (5 000 согласованных вложений от зерна, `.work/downloads.json`),
|
||||
50 записей и 50 чтений истории в секунду; тихие окна 30 с перед первым
|
||||
проходом и после каждого; окна «до» и «после» — по старту и выходу
|
||||
контейнера, окно прохода — по итогу. k6 останавливается `pkill -INT -f
|
||||
background.js` в контейнере k6 (итог он пишет и тогда). Полнота строк
|
||||
(`reconcile.line_problems`): строк `bg,…` сценария не меньше итераций
|
||||
сценария и не меньше счётчика k6 `bg_lines_<сценарий>` (его
|
||||
увеличивает тот же код перед строкой; меньше — «lines lost», отказ), а
|
||||
лишних против каждого — не больше VU сценария (`reconcile_bg_max_vus`)
|
||||
и не больше VU, созданных k6 за прогон (`vus_max` итога, verify S4).
|
||||
Лишние — итерации, прерванные SIGINT уже после строки: k6 их в
|
||||
`iterations` не считает, а их отсчёт счётчика может не принять (метка
|
||||
`aaf3fa3` упала на 264 071 строке download против 264 070 итераций,
|
||||
`a42dd27` — на 43 997 строках write против 43 996 и итераций, и
|
||||
отсчётов). Число прерванных — в `meta.reconcile.bg_interrupted`.
|
||||
Точного равенства нет ни с одним счётом. `r` = p95 прохода
|
||||
/ p95 тихих, `a` = p95 до / p95 после; 5xx окон прохода — пометка
|
||||
`bg_5xx`, неуспешные запросы (`http_req_failed`) и недосланные итерации
|
||||
(`dropped_iterations`) по всему итогу k6 — пометки `bg_failed` и
|
||||
`bg_dropped` всех проходов блока (`meta.reconcile.bg_errors`, verify
|
||||
S9); с любой из трёх H4 не подтверждается.
|
||||
- **Сравнение:** все варианты — внутри одной метки; второй метки A/A нет
|
||||
(шум — разброс повторов и `a`). `make bench_compare` метки сверки не
|
||||
сравнивает: он читает `evidence/bench/`, у сверки другая методика.
|
||||
- **Результаты:** `evidence/reconcile/<метка>/` — `meta.json` (раздел
|
||||
`reconcile`: план, этапы и модели, commit и образы «до», аргументы S3,
|
||||
CPU уборщика, фоновая нагрузка; `limits.cleaner` по CPU), `passes.csv`
|
||||
(строка на проход, новые столбцы — в конец; с verify S6 —
|
||||
`fixed_total` и `fixed_records`, неизменность данных S4; у метки
|
||||
`baseline` их нет), `windows.csv`, `summary.md`
|
||||
(таблицы, S4, вердикты H1–H4 и S4), `cost-by-n.svg`, `requests-by-n.svg`,
|
||||
`background-p95.svg`, `raw/`. `quick-reconcile-*` — в `.gitignore`.
|
||||
- **Время:** полная метка ~50 мин (45 мин у `baseline`), быстрая ~4 мин
|
||||
(3,7 мин на шумном хосте). Замер для отчёта —
|
||||
`make bench_reconcile` на тихом хосте, рабочий стенд остановлен (`make
|
||||
stop`), гипотезы H1–H4 закоммичены раньше метки.
|
||||
|
||||
## Профиль очереди (`queue`, `queue_quick`)
|
||||
|
||||
Спек `load-benchmark`, «Профиль очереди»; design change `track1-queue-overload`, решения
|
||||
5–11, 14. Методика — поля `Profile` (`queue_*`), `QUEUE_RATES`, конфигурации
|
||||
`queue_matrix` и `queue_blocks` в `run.py`; разбор без docker — `bench/overload.py`
|
||||
(`--selftest`), не `queue.py`: каталог скрипта первый в `sys.path`.
|
||||
|
||||
- **Стенд:** LB, две реплики 1 CPU / 512 МБ, PostgreSQL, Valkey, S3, брокер, relay, worker
|
||||
и уборщик с лимитами рабочего стенда без swap; третий `-f` — `queue.compose.yml`
|
||||
(плагин `rabbitmq_prometheus`, статистика в секунду, порт 15692 только в сети стенда;
|
||||
`restart: unless-stopped` у worker), окружение ячейки — `.work/variant.compose.yml`.
|
||||
У S3 остаётся `restart: "no"`: его гибель — пометка `storage_down`.
|
||||
- **Ячейка** — свежий стенд, `prepare.js`, разогрев 12 файлов `s` до `ready` (готовые байты
|
||||
контрольного потока), сэмплер `queue`, `background.js`, `queue.js`: окна `before` и `over`
|
||||
одним запуском, затем ожидание нуля незавершённых, окно `after` отдельным запуском,
|
||||
ожидание нуля, `queue_sweep.js`, чтение SQL и журналов. VU — заранее и без прибавления:
|
||||
тело — `open` на VU. Ответ не повторяется.
|
||||
- **Истина о готовности — `GET /attachments/{id}` после разбора:** `updated_at` у `ready`
|
||||
не меняется, живого опроса нет. Новые исключения границы чёрного ящика, только этот
|
||||
профиль и только чтение: `psql \watch` сэмплера и чтение SQL в конце ячейки, метрики
|
||||
брокера по HTTP в сети стенда, журналы контейнеров (разбор без копирования в метку).
|
||||
- **Сэмплер `queue`:** строки `cg`, `vm`, `lb` как в `scan` и `list`, `mp` (`memory.peak`,
|
||||
`anon`, `oom_kill`), `mq` (метрики брокера, `missing`), `jobs.log` — `psql \watch`.
|
||||
`rabbitmqctl` стоит 0,5 с CPU брокера на вызов: им не опрашивать. Перезапуск сбрасывает
|
||||
cgroup того же контейнера: `overload.split_lives` — наибольшее и сумма по жизням.
|
||||
- **Причины завершения** (verify S5): поток `Stand.death_events` (`docker events`: `oom`,
|
||||
`kill`, `die` с кодом выхода), разбор — `overload.die_causes`. Проба Docker 29.9: ядро —
|
||||
`oom` и `die` 137 в десятки мс; `docker kill` — `kill` с сигналом и `die`; процесс
|
||||
обработки — `oom` без `die`. Столбцы `worker_die_oom`, `worker_die_command`,
|
||||
`worker_die_other`, `worker_exit_codes`, `worker_oom_events`, `relay_restarts`, `relay_die`.
|
||||
`oom_kill` — счётчик cgroup плюс подтверждённые завершения процесса 1, а не каждый
|
||||
перезапуск. Перезапусков больше, чем `die` в потоке, — отказ: поток потерян.
|
||||
- **Реплики в LB** считает `overload.lb_up_count`: только слоты-серверы, не `BACKEND`, `UP
|
||||
1/2` — ещё в балансировке; наименьшее — столбец `lb_up_min`. В метке `baseline` `lb_down`
|
||||
не срабатывал: считал `BACKEND` третьей репликой.
|
||||
- **Сверка принятых — в обе стороны** (verify S4): вложение стенда не из 202 и не из разогрева
|
||||
— `unexpected_rows`; больше, чем 5xx и обрывов, — пометка `unexpected`.
|
||||
- **Пометки:** `oom`, `worker_restart`, `worker_crash`, `failed` — результат настройки; `lost`, `stuck`,
|
||||
`duplicate`, `sha_mismatch`, `unexpected` — ненулевой код команды в конце метки, ячейки сняты;
|
||||
`not_recovered`, `dropped`, `lb_down`, `host_swap`, `storage_down`. Запись «Started
|
||||
worker» не совпала с ячейкой — отказ. Тиков сэмплера нет 3 с в нагрузке — отказ.
|
||||
- **`RESUME=1`** — как у серий: тот же commit, готовая строка `cells.csv` — признак ячейки.
|
||||
- **Результаты:** `evidence/queue/<метка>/` — `meta.json`, `cells.csv` (новые столбцы —
|
||||
только в конец), `timeline.csv`, `summary.md`, четыре SVG, `raw/` — только итоги k6;
|
||||
журналы не копируются, `.work/` удаляется. `quick-queue-*` — в `.gitignore`. Метка
|
||||
`baseline` (`7999002`) снята раньше правок verify и не перезаписывается, столбцы правок —
|
||||
с `baseline2`. `baseline2` и `baseline3` сняты с выгрузкой хоста, остаются записью;
|
||||
основная для отчёта — `baseline4` (`QUESTIONS.md`, правило выбора). Образы S3 и брокера в
|
||||
паспорте (`stand.s3`, `stand.rabbitmq`) — только у меток после `baseline4`; её образы — в `REPORT.md`.
|
||||
- **Время:** полный профиль — 57 ячеек, ~2 ч 10 мин; `queue_quick` — `s` (2, 2), `lp` (4, 4),
|
||||
предел 40 и без него, `kill-worker`, `w2-p256`, ~11 мин. Рабочий стенд — `make stop`.
|
||||
|
||||
## Серии трека 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 с адресом
|
||||
восстановленной базы — только на этапе восстановления, в конце
|
||||
размера. После пересоздания `switch_api` сначала ждёт, что процесс
|
||||
каждой новой реплики сам отвечает на `/health/ready` (`docker exec`
|
||||
команды HEALTHCHECK образа, `wait_processes_ready`), и только потом
|
||||
`UP` в LB: новый контейнер получает тот же IP, и LB ещё держит слот
|
||||
`UP` от прежнего — без этого шага первые запросы k6 получали 503
|
||||
`<NOSRV>` (design change `attachments`, «Уточнения apply», п. 9). Второе хранилище и его volume `Stand.stop()` удаляет до
|
||||
`compose down`;
|
||||
- ревизия `alembic_version` до и после замены (профиль `rollout`).
|
||||
- Исключение для S3 стенда (профиль `uploads`, change `upload-memory`):
|
||||
перед каждым прогоном оркестратор удаляет S3 (`kill`: volume всё равно
|
||||
уходит), его volume `mtusi-bench_s3_data`, поднимает S3 и `s3-bootstrap`
|
||||
заново. К bucket и объектам он не обращается. Счётчики памяти cgroup
|
||||
реплики, S3 и LB читает сэмплер `peak` (`--user 0`, cgroupfs на
|
||||
запись, `--network none`): сброс `memory.peak` через свой дескриптор —
|
||||
управление счётчиком, а не приложением.
|
||||
Схему меняет не оркестратор, а миграция приложения, которую
|
||||
запускает `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`) — повод
|
||||
переснять, а не игнорировать.
|
||||
@@ -0,0 +1,450 @@
|
||||
---
|
||||
paths:
|
||||
- "Dockerfile"
|
||||
- "docker-compose.yml"
|
||||
- ".dockerignore"
|
||||
- "scripts/restart.sh"
|
||||
- "infra/**"
|
||||
- ".github/ci/**"
|
||||
- ".github/workflows/application.yml"
|
||||
---
|
||||
|
||||
# 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`.
|
||||
- С лабы 4 ещё `MALLOC_MMAP_THRESHOLD_=131072`: блоки glibc от 128 KiB
|
||||
всегда в mmap, и буфер тела загрузки растёт через `mremap`, без копии.
|
||||
Без него порог динамический: после первой загрузки glibc поднимает его
|
||||
до ~10 MiB, следующие буферы растут в куче, и `realloc` на миг держит
|
||||
два тела (замер — design change `attachments`, «Уточнения apply»,
|
||||
п. 10). Не убирать без нового замера.
|
||||
- `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/`, `service-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`, `service-tests`, `contracts`, `infra`,
|
||||
`*.md`, `Makefile`. `Dockerfile` копирует только `src/` и миграции, но контекст
|
||||
сборки быстрых тестов тоже не тащит (спек `unit-of-work`, «Быстрых тестов нет в
|
||||
образе»).
|
||||
`.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:lab5 -
|
||||
```
|
||||
|
||||
`.env`, `config.toml` и `.venv` в него не попадают по `.gitignore`.
|
||||
Перед PR — ещё и настоящий `git clone`.
|
||||
|
||||
## docker-compose.yml
|
||||
|
||||
- Имя проекта — `name: mtusi-lab5`, образ — `mtusi-messenger:lab5`. Имя
|
||||
проекта задаёт имена volume: с прежним `mtusi-lab4` стенд этой лабы
|
||||
подключился бы к данным третьей лабы, а `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_*`) и с лабы 4
|
||||
`x-s3-env` (адрес: `S3__HOST`, `S3__PORT`, `S3__BUCKET`) и
|
||||
`x-s3-api-keys-env` (ключи API мостами из `S3_API_*`), у `api` —
|
||||
`<<: [*db-env, *cache-env, *s3-env, *s3-api-keys-env]` плюс
|
||||
`APP__PORT` (`settings.md`, «Консоль и docker»). У `migrate` — только
|
||||
`x-db-env`: пароль Valkey и секреты S3 ему не нужны; `haproxy`
|
||||
получает только `API_PORT` (секреты только там, где нужны, рубрика
|
||||
«4»). Секреты S3 по сервисам — раздел S3 ниже, уборщик — раздел
|
||||
«Уборщик» ниже.
|
||||
Healthcheck образа проверяет `APP__PORT`; `stop_grace_period: 10s`;
|
||||
с change `upload-memory` — `sysctls: net.ipv4.tcp_rmem: "4096 131072
|
||||
524288"`: буфер приёма сокетов реплики до 512 KiB, а не до 32 MiB ВМ
|
||||
Docker Desktop. Ядро копит недочитанное тело (ожидание места загрузки,
|
||||
отказ до тела) в буфере сокета, и он считается памятью контейнера
|
||||
(`sock` в `memory.stat`): при 40 загрузках по 10 MiB `sock` реплики
|
||||
17 MiB вместо 134. Параметр сетевого пространства контейнера — его
|
||||
получают все контейнеры сервиса `api`, в том числе `docker compose
|
||||
run` (`make test_isolated`, стенд отказов) и `bench/`; новые реплики —
|
||||
после `make rolling_update`. Скорость не страдает: RTT в сети Docker —
|
||||
доли миллисекунды. В консоли sysctl нет (`run-modes.md`);
|
||||
`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`. Роли лабы 4 — load_balancer
|
||||
(HAProxy), api × ≥2, postgres, s3 (SeaweedFS) и 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.
|
||||
- S3 (с лабы 4, design change `s3-storage`, решения 1–4) — сервис `s3`
|
||||
на SeaweedFS (`chrislusf/seaweedfs:4.48@sha256:…`, якорь
|
||||
`x-s3-image`) и одноразовый `s3-bootstrap` на том же образе:
|
||||
- `s3` — `weed server` одним процессом: master, volume и filer только
|
||||
на `127.0.0.1` контейнера (`-ip`, `-ip.bind`), в сеть выходят порт
|
||||
API S3 (`S3_PORT`) и gRPC шлюза (`S3_PORT` + 10000); телеметрия,
|
||||
Iceberg, Lance и IAM API выключены. Volume `s3_data:/data`
|
||||
(`Config.Volumes`), алиас `${S3_HOST}`, публикация только
|
||||
`127.0.0.1:${S3_OUT_PORT}:${S3_PORT}`. Healthcheck — `wget` на
|
||||
`/cluster/healthz` master, непустой `DataNodes` в `/dir/status`
|
||||
master (том зарегистрирован), `/healthz` filer и шлюза, всё на
|
||||
loopback. Без проверки тома `healthy` наступал на ~4 с раньше
|
||||
регистрации, и первая запись ждала её почти весь срок вызова клиента
|
||||
(5 с). Та же команда — проба `fault_hook.py`.
|
||||
Лимиты 1 CPU / 512 МБ, `GOMEMLIMIT=400MiB` и
|
||||
`-s3.concurrentUploadLimitMB=64` (решение 2);
|
||||
- **`stop_grace_period: 20s`**, а не 10: плавная остановка SeaweedFS
|
||||
~15 с (срок ожидания подписок filer зашит в код), при 10 с —
|
||||
SIGKILL и код 137. Цена — `make stop` и `restart.sh` дольше на
|
||||
~15 с. На стенде отказов — 2 с (`student-tests.md`);
|
||||
- секреты по сервисам: административная пара `S3_ROOT_*` — только
|
||||
`s3` (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`: без учётной
|
||||
записи сервер открыт анониму); ключ подписи `S3_JWT_SIGNING_KEY`
|
||||
(`WEED_JWT_FILER_SIGNING_KEY`) — `s3` и `s3-bootstrap`: без него
|
||||
gRPC шлюза принимает администратора от любого контейнера сети; ключи
|
||||
API `S3_API_*` — `s3-bootstrap` и `api`; ключи уборщика
|
||||
`S3_CLEANER_*` — `s3-bootstrap` и `cleaner` (с `:?` «run make
|
||||
env_setup»: он допишет их в существующий `.env`). Остальные — с `:?`
|
||||
«copy S3 lines from .env.example»;
|
||||
- `s3-bootstrap` — `network_mode: service:s3` (master и filer сервера
|
||||
на его `127.0.0.1`), `user: seaweed`, `restart: "no"`, `tmpfs:
|
||||
[/tmp, /data]` и `HOME=/tmp` (`/data` — volume образа: без tmpfs
|
||||
каждый новый контейнер bootstrap оставлял анонимный volume, а
|
||||
пересоздание его переносит — `up -d --renew-anon-volumes
|
||||
s3-bootstrap` отвязывает старый), скрипт `infra/s3/bootstrap.sh` read-only
|
||||
длинной записью, `depends_on: s3: service_healthy`, лимиты 0,5 CPU /
|
||||
128 МБ. Режим `apply` (по умолчанию) идемпотентно сводит состояние
|
||||
к `.env` (bucket, анонимный доступ `none`, политики `api-objects` и
|
||||
`cleaner-objects`, пользователи `api` и `cleaner` с их ключами;
|
||||
шаги пользователя общие — `apply_user <имя> <политика>`) и проверяет
|
||||
приватность: ключ API пишет и читает проверочный объект, ключ
|
||||
уборщика читает его, получает 403 на запись и список всего bucket,
|
||||
200 на список своего префикса и удаляет его, после этого GET ключом
|
||||
API — 404. Политика `cleaner-objects` с change `track2-reconciler`
|
||||
(решение 2) — два оператора: `s3:GetObject` и `s3:DeleteObject` на
|
||||
`<bucket>/*` и `s3:ListBucket` на `<bucket>` с условием `StringLike
|
||||
s3:prefix <база>/attachments/*` (SeaweedFS 4.48 условие соблюдает:
|
||||
весь bucket, `test_<db>/`, `.s3-check/` и HEAD bucket — 403). Префикс
|
||||
bootstrap получает в `S3_CLEANER_LIST_PREFIX:
|
||||
${POSTGRES_DB:?…}/attachments/` (окружение `s3-bootstrap`, не секрет)
|
||||
и проверяет по `^[a-z0-9_]+/attachments/$` до любого шага (иначе
|
||||
«FAILED: cleaner list prefix» и код 1); уборщику его не передают —
|
||||
свой префикс он строит из имени базы. Новая политика доходит до шлюза
|
||||
подпиской, как ключ: проверка списка — с ожиданием. `check` печатает
|
||||
строки «cleaner key list attachments prefix» (200), «… objects»,
|
||||
«… other prefix», «… other bucket» (403). Ожидание, пока ключ дойдёт до шлюза: у
|
||||
API — PUT проверочного объекта, у уборщика — DELETE несуществующего
|
||||
ключа (204; PUT ему запрещён); `SignatureDoesNotMatch` — новый
|
||||
секрет, ключ пересоздаётся. `check` (свой проверочный объект для
|
||||
удаления ключом уборщика) и `cleanup` — для `make s3_check`. `api` ждёт его
|
||||
`service_completed_successfully`, как `migrate`. Секреты — в
|
||||
`weed shell` через stdin, в `curl` файлом `-K` на tmpfs, не в argv;
|
||||
- `up -d --wait` одноразовый сервис без healthcheck считает готовым
|
||||
уже запущенным: код bootstrap отдельно — `up --no-deps
|
||||
--exit-code-from s3-bootstrap s3-bootstrap` (`make start_s3`).
|
||||
- **Уборщик** (с лабы 4, сервис `cleaner`, design change
|
||||
`upload-consistency`, решения 2 и 9): образ API (`image:
|
||||
mtusi-messenger:lab5`, `pull_policy: never`), `entrypoint: ["python",
|
||||
"-m", "src.cleaner"]`, а не `command`: аргументы после имени сервиса
|
||||
(`docker compose run --rm --no-deps cleaner --once`) — флаги
|
||||
уборщика, а с `command` они заменили бы саму команду («executable file
|
||||
not found», design change `upload-consistency`, «Уточнения apply»,
|
||||
п. 6). `restart: unless-stopped`, без портов.
|
||||
Окружение — `<<: [*db-env, *s3-env]`, `DATABASE__POOL_SIZE: "1"` и
|
||||
ключи уборщика `S3_CLEANER_*` в `S3__ACCESS_KEY_ID` /
|
||||
`S3__SECRET_ACCESS_KEY`: ни пароля Valkey, ни ключей API, ни
|
||||
административных ключей S3 и ключа подписи. `config.toml` read-only,
|
||||
`depends_on`: `postgres` healthy, `migrate` и `s3-bootstrap`
|
||||
completed successfully; реплики его не ждут. Healthcheck образа (HTTP)
|
||||
выключен (`healthcheck: disable: true`): уборщик HTTP не слушает и
|
||||
стал бы `unhealthy`, живость — журнал. `stop_grace_period: 10s`,
|
||||
лимиты 0,25 CPU / 256 МБ (простой ~90 MiB). В консоли (`make run_dev`)
|
||||
уборщика нет; разовый проход — `docker compose run --rm --no-deps
|
||||
cleaner --once`. Стенд отказов запускает его с grace 20 с, интервалом
|
||||
1 с и без плановой сверки (`RECONCILER__INTERVAL_SECONDS: "0"`,
|
||||
`student-tests.md`), `bench/` описывает (тоже с 0) и запускает только
|
||||
разовыми проходами профиля сверки (`bench.md`, «Профиль сверки»). Выход
|
||||
процесса — `os._exit` после `main()` (`src/cleaner/__main__.py`):
|
||||
финализация интерпретатора при 0,25 CPU — до 1,5 с (design change
|
||||
`track2-reconcile-cost`, «Уточнения apply», п. 14).
|
||||
С change `track2-reconciler` сервис ещё и сверяет bucket с БД — при
|
||||
старте и раз в `[reconciler] interval_seconds` (3600 с); разовая
|
||||
сверка — `make reconcile [APPLY=1] [MAX_CHANGES=N]` (`docker compose
|
||||
run --rm --no-deps cleaner reconcile …`). **На время восстановления
|
||||
базы уборщик останавливают** (`docker compose stop cleaner`): база из
|
||||
старой копии или пустая при живом bucket сделала бы объекты новых
|
||||
вложений «объектами без метаданных», и сверка удалила бы их в пределах
|
||||
`max_changes`. После восстановления — сначала `make reconcile`
|
||||
(dry-run), потом `docker compose start cleaner` (design change
|
||||
`track2-reconciler`, Risks).
|
||||
- Конфигурации сервисов (`valkey.conf`, при необходимости
|
||||
`postgresql.conf`, скрипт `infra/s3/bootstrap.sh`) — в
|
||||
`infra/<сервис>/`, монтируются read-only
|
||||
длинной записью с `create_host_path: false` (`infra/README.md`). В
|
||||
`REPORT.md` — таблица роль → сервис → версия/digest → healthcheck →
|
||||
volume → порт → способ передачи credentials.
|
||||
- **Стенд в CI** — тот же `docker-compose.yml` плюс override
|
||||
`.github/ci/compose.yml` (job `.github/workflows/application.yml`,
|
||||
AGENTS.md, карта кода). Job раннера Gitea — контейнер на том же Docker,
|
||||
что стенд: bind mount файла из рабочего каталога там не работает (пути
|
||||
нет на хосте раннера), порты хоста job не видит. Override заменяет
|
||||
каждый bind mount на `configs` из переменной окружения
|
||||
(`.github/ci/stand-env.sh`), убирает `ports` (`!reset []`) и даёт образу
|
||||
API тег прогона. Поэтому новый bind mount, новый порт или новый сервис
|
||||
на образе API в `docker-compose.yml` — строка и в override, иначе job
|
||||
упадёт на `bind source path does not exist` или возьмёт чужой образ.
|
||||
|
||||
## Брокер и worker (с лабы 5)
|
||||
|
||||
Design change `async-attachments`, решения 4, 6, 12, 14.
|
||||
|
||||
- **`rabbitmq`** — `rabbitmq:4.3.7@sha256:bd88…` (индекс), `hostname: rabbitmq`:
|
||||
имя узла задаёт каталог данных, без него `up --force-recreate` теряет очередь.
|
||||
Volume `rabbitmq_data:/var/lib/rabbitmq`, `RABBITMQ_NODE_PORT`, порт только AMQP
|
||||
на `127.0.0.1:${RABBITMQ_OUT_PORT}`, алиас, healthcheck
|
||||
`check_port_connectivity`, `stop_grace_period: 20s` (на деле ~2 с), лимиты 1 CPU /
|
||||
512 МБ. **`vm_memory_high_watermark.absolute = 400MiB`** в
|
||||
`infra/rabbitmq/rabbitmq.conf` (`conf.d`, read-only): лимит cgroup брокер не видит
|
||||
(проба: 4760 МиБ), и его убило бы ядро. Неверная настройка этого файла — отказ
|
||||
старта, проверять запуском. Без management-плагина: состояние — `rabbitmqctl`.
|
||||
- **`worker`** — образ API, `entrypoint: ["python", "-m", "src.worker"]`,
|
||||
`restart: unless-stopped`, без портов, `healthcheck: disable: true`, окружение
|
||||
`<<: [*db-env, *s3-env, *broker-env]`, `DATABASE__POOL_SIZE: "2"`, ключи
|
||||
`S3_WORKER_*`; `depends_on` PostgreSQL и брокер healthy, `migrate` и
|
||||
`s3-bootstrap` completed; `stop_grace_period: 10s`, лимиты 1 CPU / 1 ГБ.
|
||||
- **`relay`** (design change `pipeline-reliability`, решения 1, 2, 13) — образ API,
|
||||
`entrypoint: ["python", "-m", "src.relay"]` (аргументы после имени сервиса —
|
||||
подкоманда `replay`), `restart: unless-stopped`, без портов, `healthcheck: disable:
|
||||
true`, окружение `<<: [*db-env, *broker-env]`, `DATABASE__POOL_SIZE: "1"`; `depends_on`
|
||||
PostgreSQL и брокер healthy, `migrate` completed; `stop_grace_period: 10s`, лимиты
|
||||
0,25 CPU / 256 МБ. Реплики его не ждут. У `api` нет `*broker-env` и зависимости от
|
||||
брокера.
|
||||
- **Секреты:** пароль брокера — только `rabbitmq`, `relay`, `worker`; ключи worker —
|
||||
только `s3-bootstrap` и `worker`. Пользователь S3 `worker`, политика
|
||||
`worker-objects`: `s3:GetObject`, `s3:PutObject` на `<bucket>/*` — без удаления и
|
||||
списка; `check` печатает строки «worker key …». Политика уборщика — список с условием
|
||||
на два префикса, `<база>/attachments/*` и `<база>/staging/*`; `check` — ещё строки
|
||||
«cleaner key list staging prefix» и «cleaner key list database prefix».
|
||||
- **`restart.sh`** перезапускает и брокер; relay, worker и уборщика не трогает: защита
|
||||
вызывает hook при остановленном worker, и он останется остановленным.
|
||||
- **Суммы:** постоянные 9,0 CPU, 4992 МБ, с разовыми 10,0 CPU, 5376 МБ; соединений
|
||||
PostgreSQL `API_REPLICAS × 10 + migrate 1 + cleaner 1 + worker 2 + relay 1` = 25, при
|
||||
замене 35.
|
||||
|
||||
## Обновление кода на стенде
|
||||
|
||||
- `make run_docker` после пересборки пересоздаёт реплики, образ которых
|
||||
изменился, — все разом, с простоем. Compose сравнивает метку
|
||||
контейнера `com.docker.compose.image` (манифест платформы) с
|
||||
манифестом тега. Пересборка без изменений кода реплики не трогает,
|
||||
хотя digest тега новый: индекс образа содержит отметки времени
|
||||
сборки (`evidence/rollout/compatibility.md`).
|
||||
- Хранилище образов Docker Desktop — containerd. Что чем называется:
|
||||
- индекс — ID тега, `docker image inspect <тег>`; у каждой пересборки
|
||||
свой;
|
||||
- манифест платформы — метка контейнера `com.docker.compose.image` и
|
||||
`docker image inspect --platform`;
|
||||
- поле `.Image` контейнера — не digest конфигурации: на пробе оно
|
||||
совпадало с ID тега на момент создания контейнера, а при том же
|
||||
манифесте отличалось.
|
||||
|
||||
`docker ps` показывает у реплик ID, а не имя тега, когда тег уже указывает
|
||||
на другой индекс. Это не признак «старого образа»: прежний пункт
|
||||
`KNOWN_ISSUES.md` о том, что `run_docker` не пересоздаёт реплики, на этом
|
||||
и ошибся. Образы сравниваются по метке, а не по `.Image`: `docker inspect
|
||||
-f '{{index .Config.Labels "com.docker.compose.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 и с лабы 4 S3. Volumes, схему и данные
|
||||
сохраняет: без `down -v`, `FLUSHALL`, повторного seed и изменения
|
||||
тестовых данных. Кэш Valkey после рестарта пуст сам: persistence у
|
||||
него выключен. Bucket, учётные записи и объекты S3 — в его volume.
|
||||
- Порядок: `stop haproxy api` → `restart postgres valkey s3` → `up -d
|
||||
--wait --no-recreate postgres valkey s3` (те же контейнеры, ожидание
|
||||
healthcheck) → `start api haproxy`. `--no-recreate` обязателен:
|
||||
Compose 5.4 пересоздаёт контейнер, если его образ скачивался при первом
|
||||
`up` (метка — digest индекса, сверка — digest манифеста платформы), и
|
||||
`s3-bootstrap` (`network_mode: service:s3`) после пересоздания `s3` не
|
||||
стартует — код 128, `start api` падает. Нашёл CI на раннере Gitea
|
||||
(`evidence/tests/ci-application.md`); локально образы были в кэше, и
|
||||
Compose 5.6 так не делает. `start api` запускает и зависимости `migrate` и
|
||||
`s3-bootstrap`: повторные миграции и bootstrap — no-op («exists»).
|
||||
Число реплик не меняется: `start` поднимает те же контейнеры, а не
|
||||
масштабирует (реплику, остановленную `stop-one.sh`, тоже). Уборщика
|
||||
hook не трогает: он не хранилище и не реплика API, рестарт PostgreSQL
|
||||
и S3 переживает сам (`warning` отказа в журнале, проход — через
|
||||
интервал).
|
||||
- `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`,
|
||||
`git update-index --chmod=+x`). Возвращает 0 только после действия,
|
||||
укладывается в 90 с (с S3 — ~25 с, из них ~15 с — остановка S3).
|
||||
Готовность ждёт сам тест. Секреты не печатает.
|
||||
- Успех теста не доказывает, что БД действительно перезапускалась. В
|
||||
`evidence/` — состояние контейнеров до и после (`docker compose ps`,
|
||||
`StartedAt` из `docker inspect`).
|
||||
|
||||
## Дальше
|
||||
|
||||
Реплики, HAProxy, `scripts/stop-one.sh`, поочерёдная замена, лимиты и
|
||||
пулы — `balancer.md`.
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
paths:
|
||||
- "src/schemas/**"
|
||||
---
|
||||
|
||||
# DTO и enum-ы (`src/schemas/`)
|
||||
|
||||
Обработка вложений (design change `async-attachments`, решения 1–3):
|
||||
`AttachmentFullDTO` — ещё `staging_key`, `error_code` и `variants` кортежем
|
||||
(не колонка: подставляет сервис); `AttachmentInListDTO.staging_key`;
|
||||
`AttachmentJobDTO`, `AttachmentVariantDTO`; enum `AttachmentJobState`,
|
||||
`AttachmentVariantName`, `AttachmentErrorCode`, `AttachmentJobReason`,
|
||||
`JobOutcome`. Сообщение брокера — pydantic-модель
|
||||
`src/schemas/jobs/attachment.py`, а не DTO: оно приходит извне и разбирается по
|
||||
`contracts/jobs.schema.json`.
|
||||
|
||||
С change `pipeline-reliability`: `AttachmentJobDTO.attempt_base`,
|
||||
`AttachmentInListDTO.status`, `updated_at`, `ReconcilePassDTO.listed_staging`, новые
|
||||
`AttachmentJobReplayDTO`, `FailedJobDTO`, `RelayPassDTO`, `StagingCleanupPassDTO`,
|
||||
`ReplayResultDTO`, `ReplayPassDTO`, `RenderedVariantDTO`, `RenderedVariantsDTO`;
|
||||
`AttachmentJobReason` — ещё лимиты, `render_killed`, `render_crashed`,
|
||||
`lease_expired`; `ReconcileFinding.ORPHAN_STAGING`.
|
||||
|
||||
`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`).
|
||||
- Вложения (лаба 4): `AttachmentStatus` (`pending`, `ready`; новое
|
||||
значение — замена CHECK) и `ImageType` (`image/png`, `image/jpeg`) в
|
||||
`enums/attachment.py`. `AttachmentFullDTO` — все колонки строки, в
|
||||
том числе `object_key` и `sha256` байтами: ключ в API не уходит, hex
|
||||
собирает модель ответа. `AttachmentContentDTO` — не снимок строки, а
|
||||
поток на отдачу: тип, размер, асинхронный итератор блоков и `close`.
|
||||
`MessageFullDTO.attachment_ids: tuple[UUID, ...] = ()` — значение по
|
||||
умолчанию последним полем.
|
||||
- Сверка bucket и БД (design change `track2-reconciler`, решение 8):
|
||||
`AttachmentFullDTO.lost_at: datetime | None = None` — последним полем
|
||||
(колонка `lost_at`, в API не уходит); `ReconcileFinding` (классы
|
||||
`orphan_object`, `missing_object`, `size_mismatch`, `stale_pending`,
|
||||
`restored_object`, `unknown_object`) и `ReconcileAction`
|
||||
(`deleted_object`, `marked_lost`, `cleared_lost`, `removed_pending`) —
|
||||
`StrEnum` в `enums/attachment.py`, в БД не хранятся;
|
||||
`ReconcileFindingDTO` (класс, ключ, `id`, возраст, размеры) и
|
||||
`ReconcilePassDTO` (итог прохода; `found` и `fixed` — неизменяемые
|
||||
отображения `MappingProxyType`, а не `dict`: DTO frozen).
|
||||
- Стоимость сверки (design change `track2-reconcile-cost`, решения 8 и
|
||||
15): `ReconcileFinding.CHECKSUM_MISMATCH` (`checksum_mismatch`) и
|
||||
`ReconcileStrategy` (`batch`, `head`) в `enums/attachment.py`;
|
||||
`ReconcilePassDTO` — новые поля в конце со значениями по умолчанию:
|
||||
`strategy`, `deep`, `max_objects_per_second`, `storage_objects`,
|
||||
`s3_requests` и `phase_ms` (`MappingProxyType`, по умолчанию пустой —
|
||||
`field(default_factory=…)`), `read_bytes`, `db_sessions`, `unchecked`;
|
||||
`ReconcileFindingDTO.sha256: bytes | None = None` — SHA-256 строки для
|
||||
перепроверки прочитанного объекта, в журнал не попадает. Снимок
|
||||
счётчиков клиента S3 `StorageStats` — тип `src/infra/s3`, не DTO
|
||||
слоёв.
|
||||
@@ -0,0 +1,298 @@
|
||||
---
|
||||
paths:
|
||||
- "src/infra/**"
|
||||
---
|
||||
|
||||
# Инфраструктура (`src/infra/`)
|
||||
|
||||
Брокер (`broker/`, с лабы 5, design change `async-attachments`, решение 5):
|
||||
`client.py` — `JobPublisher` (только relay), `JobConsumer` (только worker),
|
||||
`JobDelivery`, `queue_name`; у реплик API клиента брокера нет (design change
|
||||
`pipeline-reliability`, решение 1). aio-pika без `connect_robust`: фоновый reconnect
|
||||
скрыл бы, что исход публикации неизвестен. Издатель открывает соединение первым
|
||||
вызовом, `publisher_confirms=True`, `mandatory`, `on_return_raises=True`, очередь
|
||||
объявляется при каждом соединении. `publish_many(items) -> set[UUID]` — задача на
|
||||
сообщение и `asyncio.wait` с общим сроком `[broker] publish_timeout_seconds`:
|
||||
подтверждённые до срока считаются, остальные отменяются; подмножество — ошибка уже
|
||||
записана, соединение сброшено. `ready_messages()` — активное объявление, считает
|
||||
только готовые; отказ — `BrokerUnavailable`.
|
||||
Любая ошибка — сброс соединения (`is_closed` соединения не верить: канал закрыт при
|
||||
«живом» соединении), закрытие в фоне (при заморозке оно само зависло бы),
|
||||
`warning` «Broker is unavailable»; повторов нет. Закрытый канал (`is_closed` канала)
|
||||
перед публикацией — брокер перезапускался, пока заданий не было: в него ничего не
|
||||
ушло, поэтому это новое соединение, а не повтор. Процесс обработки (`render/`):
|
||||
`ImageRenderer`, см. `worker.md`.
|
||||
Потребитель
|
||||
— своё соединение: блокировка публикации не должна останавливать ack. Строка URL
|
||||
с паролем не собирается, `aio_pika` и `aiormq` на `WARNING`.
|
||||
|
||||
Всё, что не содержит бизнес-логики и может смениться от лабы к лабе:
|
||||
логгер, PostgreSQL (`db/`), кэш Valkey (`cache/`), S3 (`s3/`), дальше —
|
||||
брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет:
|
||||
они в сервисах, атомарные операции — в repo.
|
||||
|
||||
- Клиент хранилища (engine Postgres, кэш Valkey, S3) — глобал своего
|
||||
модуля (`db/session.py`, `cache/instance.py`, `s3/instance.py`):
|
||||
создаётся при импорте по
|
||||
`settings` (настройки читаются один раз на процесс), соединения
|
||||
открывает лениво, при первом запросе. Пакет `src/infra/<клиент>/` этот
|
||||
модуль не импортирует, модели тоже, поэтому alembic и скрипты клиента
|
||||
не создают. Закрытие (`engine.dispose()`, `cache.aclose()`) — в
|
||||
lifespan `src/main.py` (S3 — ещё и `start()` там же). Почему не
|
||||
`app.state` — design change
|
||||
`postgres-storage`, решение 5.
|
||||
- Глобал импортируют только `src/main.py` (закрытие) и
|
||||
`src/api/dependencies.py`; сервисы получают единицу работы или клиент через
|
||||
конструктор из зависимости и сами глобал не импортируют. Процессу со
|
||||
своим пулом (уборщик с лабы 4, worker с лабы 5) — свой вызов фабрик
|
||||
`create_engine` и `create_object_storage`.
|
||||
- Уборщик (`src/cleaner/main.py`, design change `upload-consistency`,
|
||||
решения 2 и 7): свой engine — пул из `DATABASE__POOL_SIZE` (на стенде
|
||||
1: проход последовательный), свой клиент S3 с namespace — имя базы и
|
||||
ключами пользователя уборщика; глобалы `db/session.py` и
|
||||
`s3/instance.py` он не импортирует. Закрывает их сам при выходе.
|
||||
- `db/`: `engine.py` — фабрики engine и сессий, `BoundedCloseConnection`,
|
||||
`ping`; `session.py` — глобалы `engine` и `session_factory`;
|
||||
`scope.py` — `session_scope(session_factory, *, timeout_seconds)`:
|
||||
сессия на блок, блок вместе с откатом при выходе — под сроком (change
|
||||
`unit-of-work`, решение 4: блок заканчивается до ответа, и замороженный
|
||||
PostgreSQL иначе повесил бы готовый ответ), `is_db_unavailable` →
|
||||
`invalidate()`, `warning` «Database is unavailable» (модуль `database`) и
|
||||
`ServiceUnavailable`; отмена задачи тоже сбрасывает соединение (`close()`
|
||||
послал бы ROLLBACK); и `deadline_scope(*, timeout_seconds)` — общий срок JSON-запроса
|
||||
без сессии (`api-layer.md`). Внутри общего срока таймер блока не взводится
|
||||
(`_deadline_task`, только в той же задаче): оба истекали бы почти разом, и вторая
|
||||
отмена прерывала бы закрытие соединения в пуле. Срок отката на JSON-ручке — общий
|
||||
срок, вне их — срок блока. `uow.py` — `SqlAlchemyUnitOfWork(session_factory,
|
||||
*, timeout_seconds)` поверх `session_scope`, repo создаются на блок, соединение
|
||||
выдаётся лениво. Импортируют `uow.py` только точки входа процессов;
|
||||
`db/__init__.py` не импортирует ни его, ни `scope.py` (логгер не настраивается
|
||||
в alembic). `errors.py` — `is_db_unavailable`; модели — `models/`
|
||||
(`migrations.md`). Драйвер — asyncpg.
|
||||
- Проверка соединения при выдаче — одним обменом `;` (`_ping_once`,
|
||||
`engine.dialect.do_ping`; change `unit-of-work`, решение 7): проверка
|
||||
диалекта — `BEGIN`, `;`, `ROLLBACK` ради pgbouncer, которого на стенде нет, а
|
||||
соединение на шаг выдаётся двухшаговой ручке дважды. Разбор обрыва прежний:
|
||||
`_do_ping_w_event` получает ту же ошибку адаптера. Опирается на внутренние
|
||||
`_connection` и `_handle_exception` адаптера, SQLAlchemy закреплён `<2.2`;
|
||||
смену имён ловит `make service_test_db` (`test_ping_*`).
|
||||
- `cache/`: `client.py` — фабрика `create_cache` и обёртка `Cache`;
|
||||
`instance.py` — глобал `cache`. Ключи и формат значений — в repo
|
||||
(`src/core/repos/chat_cache.py`), не здесь.
|
||||
- `s3/` (с лабы 4, design change `s3-storage`, решения 6–7): `client.py`
|
||||
— фабрика `create_object_storage`, обёртка `ObjectStorage` и типы
|
||||
`StoredObjectInfo`, `StoredObject`; `instance.py` — глобал
|
||||
`object_storage` с `namespace` = имя базы. Ключ объекта строит repo
|
||||
(`attachments`): `f"{namespace}{S3_KEY_SEPARATOR}…"`, как ключи кэша, —
|
||||
объекты `make test_isolated` лежат под `test_<db>/`. Клиент
|
||||
aiobotocore создаёт `start()` в lifespan (модели botocore — при
|
||||
старте, сети нет), закрывает `aclose()` рядом с `cache.aclose()`.
|
||||
Ниже — правила клиента.
|
||||
- `upload_slots.py` (change `upload-memory`, design, решение 1) — класс
|
||||
`UploadSlots` и глобал `upload_slots` из `settings.uploads` (при
|
||||
импорте, как `_limiter` в `password.py`): места загрузок процесса на
|
||||
`asyncio.Semaphore` (ожидающие — по порядку прихода), счётчик
|
||||
ожидающих и срок ожидания. Контекст `slot()`: места нет и ожидающих
|
||||
уже `max_waiting` — сразу `UploadsBusy`; иначе ожидание не дольше
|
||||
`wait_timeout_seconds` (`asyncio.timeout`), не вышло — `UploadsBusy`;
|
||||
отдаёт ожидание в мс, место освобождает в `finally`. Отмену во время
|
||||
ожидания `Semaphore` обрабатывает сам: место, отданное отменённому
|
||||
ожидающему, переходит следующему. Это допуск к обработке, а не данные:
|
||||
места считает каждая реплика, корректность ответов от них не зависит
|
||||
(`api-layer.md`). Глобал импортирует только `dependencies.py`,
|
||||
уборщик его не создаёт. Отвергнуты — очередь в LB, `--limit-concurrency`
|
||||
uvicorn, места по байтам, счётчик в Valkey или PostgreSQL (design).
|
||||
- `early_stop.py` — ранний обработчик SIGTERM и SIGINT процесса
|
||||
(`install(process_name)`, `disarm()`, `write_record`): только stdlib,
|
||||
ни настроек, ни логгера, ни других модулей `src`; клиентом хранилища
|
||||
не является, глобала клиента нет, `dependencies.py` его не
|
||||
импортирует. Импортируется в `src/__main__.py` до приложения;
|
||||
`disarm()` — первая строка lifespan `src/main.py` (а не `main()`
|
||||
перед `uvicorn.run`: до `capture_signals` сигнал снова терялся бы).
|
||||
У уборщика — `install("cleaner")` в `src/cleaner/__main__.py`,
|
||||
`disarm()` — после обработчиков сигналов asyncio; `write_record` пишет
|
||||
ещё и запись о неверных настройках уборщика (логгер их тоже читает).
|
||||
Окна старта — `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); с лабы 4 ещё уборщик (пул 1). Расчёт для заявленного
|
||||
числа реплик — в `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`): транзакция
|
||||
живого блока дольше не живёт, `session_scope` сбрасывает соединение
|
||||
по сроку (design change `graceful-failover`, решение 4).
|
||||
- `command_timeout` asyncpg не использовать: на таймауте он отменяет
|
||||
запрос через новое соединение и ждёт сервер без срока, и замёрзший
|
||||
Postgres держит запрос до разморозки. Срок блока ставит
|
||||
`asyncio.timeout` в `session_scope`, а мягкое закрытие соединения
|
||||
ограничивает `BoundedCloseConnection` (`connection_class` asyncpg). Он же обрывает
|
||||
транспорт после закрытия: `abort()` asyncpg на прерванном `close()` выходит сразу и
|
||||
сокет не трогает, а сессия без транзакции (проверка `;`) жила бы сверх пула без
|
||||
срока. Опирается на внутренний `_transport`, смену ловит
|
||||
`test_no_sessions_over_pool_after_freeze`.
|
||||
- Engine — с `hide_parameters=True`. `str()` у `DBAPIError` включает
|
||||
`[SQL: ...]` и `[parameters: ...]`, и эта строка уходит в журнал: в
|
||||
`warning` из `session_scope` и в 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 и не обход
|
||||
аутентификации. Перевод — в `session_scope` (`db/scope.py`, под единицей
|
||||
работы): `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» при первом успехе. Пароль в журнал не попадает: он
|
||||
есть только в настройках пула.
|
||||
- S3 (SeaweedFS) — байты вложений; источник истины метаданных —
|
||||
PostgreSQL. Клиент — aiobotocore (botocore закреплён им узко,
|
||||
обновлять вместе через `uv lock`):
|
||||
- **повторов нет** (`retries={"total_max_attempts": 1}`): рестарт S3
|
||||
повтора не требует (старый клиент проходит первым же вызовом), таймаут
|
||||
не повторяется, загрузку повторяет клиент контракта;
|
||||
- **срок на вызов** — `asyncio.timeout([s3] timeout_seconds)` (5 с,
|
||||
меньше `timeout server` HAProxy), у `open` — ещё и на каждый блок
|
||||
чтения тела. Кроме срока установки соединения
|
||||
(`connect_timeout_seconds` из `[s3]`), это единственный срок вызова:
|
||||
`read_timeout` botocore **выключен (`None`)**; пул aiohttp — `[s3]
|
||||
max_connections`;
|
||||
- **почему без `read_timeout`** (design change `fix-upload-put-flake`,
|
||||
решение 1): aiobotocore превращает его в `sock_read` aiohttp, а
|
||||
aiohttp 3.14.5 (версия `uv.lock`, проверено пробой) после потокового
|
||||
ответа с паузой чтения перевзводит этот срок в `resume_reading()` уже
|
||||
у соединения, которое вернулось в пул. Пауза — когда буфер ответа
|
||||
больше 512 KiB (`read_bufsize` по умолчанию 256 KiB, верхний порог —
|
||||
вдвое больше: `aiohttp/helpers.py:65`, `streams.py:117–118`, `300`;
|
||||
замер: 64–200 KiB — 0 взведённых из 90, 1 MiB — до 2 из 10). Пробой
|
||||
другие версии aiohttp не проверялись, их исходники — в
|
||||
`evidence/s3/idle-connection.md`, раздел 1. Через срок он
|
||||
срабатывает на простаивающем соединении, пул отдаёт его следующему
|
||||
вызову (проверяет только
|
||||
`is_connected()` и keep-alive), и вызов падает за 1 мс —
|
||||
`ReadTimeoutError`, 503 на исправном S3. Включать `read_timeout`
|
||||
снова — только с новой пробой (`driver.py s3-idle`, тест
|
||||
`test_upload_after_idle_s3`). Отсюда правило: всякое новое чтение из
|
||||
S3 — внутри `_call` или `_read_chunk` под `asyncio.timeout`, а не
|
||||
голым `await` на ответе aiohttp, иначе оно останется без срока;
|
||||
- правило «повторов нет» (пункт выше) прежнее: причина 503 убрана, а не
|
||||
скрыта повтором (решение 2 того же design). Отдельного срока PUT
|
||||
по размеру нет: места API ограничивают одновременные PUT (4 на
|
||||
реплику, 12 при замене), p95 при 12 — 1,6–1,9 с (design change
|
||||
`upload-memory`, решение 8), а больший срок удлинил бы границу B
|
||||
уборщика;
|
||||
- `put(key, body, *, size, content_type)` — тело потоком с `read`,
|
||||
`seek`, `tell` (сервис передаёт свой `BytesIO`), `size` — в журнал
|
||||
вызова. Не `bytes`: botocore обернул бы его в `BytesIO` с общим
|
||||
буфером, и aiohttp скопировал бы тело при `getbuffer()`;
|
||||
- `list_page(prefix, *, token, max_keys)` (design change
|
||||
`track2-reconciler`, решение 3) — страница ListObjectsV2:
|
||||
`StoredObjectPage` (объекты с размером и `last_modified`, токен
|
||||
продолжения или `None`). Срок — на страницу, как у любого вызова; у
|
||||
`_call` ключ необязателен (`None` — вызов без `Key`, в журнал —
|
||||
префикс). Нет bucket — `ObjectStorageUnavailable` («bucket is
|
||||
missing»), а не пустая страница: у списка и 404 без тела считается
|
||||
отсутствующим bucket; отказ в списке — «denied access».
|
||||
`StoredObjectInfo.last_modified` — из списка, HEAD и GET (часы S3,
|
||||
точность — секунда). Порядок списка SeaweedFS —
|
||||
обход каталогов, а не порядок байтов: сверка не сливает
|
||||
отсортированные потоки, а собирает множество ключей. Префикс —
|
||||
только `<namespace>/attachments/` (repo): политика уборщика другие
|
||||
префиксы запрещает;
|
||||
- счётчики клиента (design change `track2-reconcile-cost`, решение 8):
|
||||
попытки вызовов по операциям — в `_call` до вызова, в том числе
|
||||
неудачные (`OPERATION_NAMES`: `list`, `head`, `get`, `delete`, `put`),
|
||||
ключи страниц — в `list_page`, прочитанные байты — в `_read_chunk`.
|
||||
`stats()` — неизменяемый снимок `StorageStats` (`calls` —
|
||||
`MappingProxyType`); стоимость прохода сверка считает разностью
|
||||
снимков. На поведение, сроки и перевод ошибок счётчики не влияют.
|
||||
`open` отдаёт и `last_modified` (GET), чтобы глубокая сверка `head`
|
||||
проверяла свежесть без HEAD;
|
||||
- адресация `path`: `bucket.s3` Docker DNS не разрешает;
|
||||
простаивающее соединение aiohttp закрывает через
|
||||
`S3_KEEPALIVE_TIMEOUT_SECONDS` (15 с), раньше шлюза (120 с);
|
||||
- ключи передаются в botocore всегда, даже пустые: с `None` он искал
|
||||
бы учётные данные в окружении и `~/.aws` хоста. Пустые ключи —
|
||||
`warning` при старте;
|
||||
- ошибки: отказ соединения, обрыв, таймаут, 5xx, отказ в учётных
|
||||
данных (`InvalidAccessKeyId`, `SignatureDoesNotMatch`), отказ в
|
||||
доступе (`AccessDenied`, 403 без тела у HEAD) и отсутствующий bucket
|
||||
(`NoSuchBucket`) — `ObjectStorageUnavailable` (наследник
|
||||
`ServiceUnavailable`, 503 `unavailable`); отсутствующий ключ
|
||||
(`NoSuchKey`, 404 без тела у HEAD) — `StoredObjectMissing` (`head` —
|
||||
`None`, `delete` глушит только его). Удалённый bucket не выдаётся за
|
||||
отсутствующий объект; исключение — HEAD: SeaweedFS отвечает тем же
|
||||
404 без тела. Прочие ошибки S3 и botocore не перехватываются — 500,
|
||||
дефект;
|
||||
- обхода и пропуска после отказа, как у Valkey, нет: без S3 путь
|
||||
вложений всё равно 503. `/health/ready` S3 не проверяет (спек
|
||||
`health`, design change `s3-storage`): текст работает без него.
|
||||
- Клиенты внешних сервисов: адреса и секреты из `settings`
|
||||
(`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки
|
||||
переводятся в доменные исключения. Логи — по `logging.md`, без
|
||||
секретов.
|
||||
@@ -0,0 +1,308 @@
|
||||
---
|
||||
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 с параметрами в лог не попадает;
|
||||
- клиент S3 (с лабы 4): `botocore`, `aiobotocore`, `aiohttp` — явно
|
||||
`WARNING`, даже если кто-то опустит уровень root: на `DEBUG`
|
||||
botocore пишет заголовки запроса с подписью (`Authorization`).
|
||||
|
||||
### Отличия от 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»
|
||||
(у уборщика — «Stopped cleaner 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).
|
||||
|
||||
## Журнал worker и брокера (с лабы 5)
|
||||
|
||||
Спек `service-logging`, «Журнал worker»; design change `async-attachments`,
|
||||
решение 18. Модуль `attachment_processing_service`, `request_id` — `job_id`:
|
||||
`info` «Started job attempt», «Attachment became ready» (`variant_width`,
|
||||
`variant_height`, `variant_size_bytes`, `duration_ms`), «Skipped job message»
|
||||
(`reason`: `finished`, `unknown`, `busy`); `warning` «Retrying job» (`reason`,
|
||||
`delay_seconds`), «Attachment failed» (`error_code`, `reason`), «Job waits for
|
||||
database»; `error` «Dropped malformed job message» — без содержимого, «Job attempt
|
||||
failed» с traceback. Модуль `worker`: «Started worker» со всеми значениями,
|
||||
«Stopped worker» с `exit_code`, «Invalid worker settings» мимо structlog, «Stopped
|
||||
worker before startup». Модуль `broker`: `warning` «Broker is unavailable»,
|
||||
`info` «Broker is available again», `debug` на публикацию; API: «Uploaded attachment»
|
||||
— ещё `job_id`, `content_type` значением. Пароля брокера и тел сообщений в записях нет.
|
||||
|
||||
С change `pipeline-reliability` (решение 18): «Started job attempt» — ещё `queue_wait_ms`
|
||||
(от подтверждения брокером до взятия), `message_attempt`, `redelivered`; «Attachment
|
||||
became ready» — вместо `variant_*` — `variants` (имя, ширина, высота, размер), `render_ms`,
|
||||
`render_peak_kib`, `render_memory_limit_applied`, `duration_ms`; «Retrying job» — ещё
|
||||
`next_attempt_at`; «Skipped job message» — ещё `not_due`, `superseded`. Модуль
|
||||
`image_renderer`: `warning` «Render process failed» (`exit_code`), «Render process output
|
||||
is damaged». Модуль `relay`: «Started relay» со всеми значениями, «Stopped relay»,
|
||||
«Invalid relay settings», «Stopped relay before startup», `warning` «Relay pass was
|
||||
interrupted», `error` «Relay pass failed». Модуль `attachment_relay_service`: «Relay
|
||||
pass» (`published`, `unconfirmed`, `recovered`, `republished`, `published_backlog`,
|
||||
`duration_ms`; `info`, пустой — `debug`), `warning` «Recovered expired lease», `info`
|
||||
«Relay backlog is full» / «Relay backlog has room» на смену состояния. Модуль
|
||||
`attachment_replay_service`: «Found failed job», «Replayed job» (`operator`, прежние
|
||||
`error_code`, `reason`), `warning` «Refused job replay» (`refusal`), «Finished replay
|
||||
pass». Модуль `attachment_cleanup_service`: «Finished staging cleanup pass»
|
||||
(`removed_ready`, `removed_failed`, `skipped`, `interrupted_by`, `duration_ms`), `warning`
|
||||
«Staging key is not own». Итог сверки — ещё `listed_staging`.
|
||||
|
||||
## Чего в логах быть не должно
|
||||
|
||||
Рубрика уровня 4: логи полезные, но **без содержимого сообщений**.
|
||||
|
||||
- Текст сообщений, `display_name`, `title` чата, тела запросов и ответов
|
||||
целиком. Вместо текста — идентификаторы и размеры
|
||||
(`text_length=len(text)`).
|
||||
- Пароли, токены сессий и их хэши, заголовок `Authorization` (`auth.md`);
|
||||
с лабы 3 — `Idempotency-Key` (ни целиком, ни частью: ключ выбирает
|
||||
клиент, в нём может оказаться что угодно; повтор виден по
|
||||
`replayed=true` и `message_id`); с лабы 4 — ключи доступа и секреты
|
||||
S3, ключ подписи служебных вызовов, подписи запросов к S3 (заголовок
|
||||
`Authorization`, параметры подписанного URL) и байты объектов. Для
|
||||
обращений к S3 допустимы адрес S3, bucket, ключ объекта, размер,
|
||||
длительность и класс ошибки (спек `service-logging`). Клиент
|
||||
(`src/infra/s3/client.py`, модуль `object_storage`) пишет `warning`
|
||||
«Object storage is unavailable» на отказ и таймаут, `error` с кодом
|
||||
ошибки S3 — «Object storage rejected credentials» (неверный ключ или
|
||||
подпись), «Object storage denied access» (`AccessDenied`) и «Object
|
||||
storage bucket is missing» (`NoSuchBucket`), `debug` на успешный
|
||||
вызов; текста исключения botocore в записи нет. Запись «Started API» —
|
||||
с `s3_host`, `s3_port`, `s3_bucket`; пустые ключи — `warning`. С change
|
||||
`upload-memory` в ней же `uploads_max_concurrent`,
|
||||
`uploads_max_waiting`, `uploads_wait_timeout_seconds`,
|
||||
`uploads_body_timeout_seconds`, с change `track1-queue-overload` —
|
||||
`uploads_max_unfinished_jobs` (спек `service-configuration`,
|
||||
«Параметры загрузок»).
|
||||
- С лабы 4 — `filename` вложений (его выбирает пользователь) и байты
|
||||
изображений. Модуль `attachment_service` пишет `info` «Uploaded
|
||||
attachment» (`attachment_id`, `chat_id`, `size_bytes`,
|
||||
`content_type`, `width`, `height`, `waited_ms`, `duration_ms`), `info`
|
||||
«Rejected attachment» с `reason` (`type`, `declared_size`, `size`,
|
||||
`content`, `content_mismatch`, `damaged`, `pixels`, `interrupted`; с
|
||||
change `upload-memory` — `busy` с `waited_ms`: места заняты, 429, и
|
||||
`body_timeout` с `size` прочитанного: тело не пришло за срок, 400; с
|
||||
change `track1-queue-overload` — `backlog` с `unfinished` и `limit`: предел
|
||||
заданий, 429; профиль очереди сверяет эти записи с числом 429),
|
||||
`chat_id` и `filename_length`, `error` «Attachment content is missing» / «…size
|
||||
differs» с `attachment_id` и `object_key`. С change
|
||||
`upload-consistency`: `warning` «Attachment upload left pending» с
|
||||
`attachment_id` и `step` (`put`, `ready`, `commit`), `info` «Deleted
|
||||
attachment object» или `warning` «Attachment object kept for cleaner»
|
||||
(`object_key`, `error_type`) о компенсации, `error` «Pending
|
||||
attachment was removed before ready». `MessageService` пишет
|
||||
`attachments_count` в «Created message» и «Rejected message
|
||||
attachments». Поле `filename` у записей — место вызова в коде
|
||||
(`CallsiteParameterAdder`), а не имя файла вложения.
|
||||
- Stack trace — только в лог, никогда в ответ.
|
||||
|
||||
## Журнал уборщика (с лабы 4)
|
||||
|
||||
Спек `service-logging`, «Журнал уборщика»; design change
|
||||
`upload-consistency`. Тот же `get_logger()`, `instance_id` — hostname
|
||||
контейнера уборщика.
|
||||
|
||||
- `cleaner` (`src/cleaner/main.py`): `info` «Started cleaner»
|
||||
(`interval_seconds`, `pending_grace_seconds`, `batch_size`,
|
||||
`live_upload_bound_seconds`, `once`, адрес и имя базы, размер пула,
|
||||
`s3_host`, `s3_port`, `s3_bucket`), `info` «Stopped cleaner»
|
||||
(`exit_code`), `error` «Cleaner grace period is not longer than live
|
||||
upload bound» (grace, оба срока, граница), `error` «Cleanup pass
|
||||
failed» с traceback. Неверные настройки — запись «Invalid cleaner
|
||||
settings» мимо structlog (`early_stop.write_record`: `loc` и `msg`
|
||||
ошибок, без значений полей), «Stopped cleaner before startup» — как у
|
||||
API.
|
||||
- `attachment_cleanup_service`: `info` «Removed stale attachment»
|
||||
(`attachment_id`, `object_key`, `age_seconds`) — после commit
|
||||
транзакции уборки (второй шаг строки: объект и строка под
|
||||
блокировкой); пометка (первый шаг) и пропуск занятой строки своих
|
||||
записей не пишут, пропуски видны в `skipped`; итог прохода
|
||||
«Finished cleanup pass» / «Interrupted cleanup pass» (`removed`,
|
||||
`skipped`, `interrupted_by`, `duration_ms`): `warning` при отказе S3
|
||||
или БД, `info`, если что-то убрано или проход остановлен сигналом,
|
||||
иначе `debug` — пустой проход раз в минуту журнал не засоряет.
|
||||
- Причину отказа пишет нижний слой: клиент S3 (`object_storage`) и
|
||||
`session_scope` под единицей работы (`database`, `warning` «Database is
|
||||
unavailable»; та же запись у общего срока JSON-запроса — `deadline_scope`);
|
||||
сервис только называет `interrupted_by`.
|
||||
- Сверка bucket и БД (спек `service-logging`, «Журнал сверки»; design
|
||||
change `track2-reconciler`, решение 8), модуль
|
||||
`attachment_reconcile_service`, `method=reconcile`, `apply`:
|
||||
- находка, которая осталась, — `warning` «Found storage discrepancy»;
|
||||
исправленная — `info` «Fixed storage discrepancy» с `action`
|
||||
(`deleted_object`, `marked_lost`, `cleared_lost`, `removed_pending`).
|
||||
Поля: `kind`, `object_key`, `attachment_id`, `age_seconds`, а
|
||||
`size_bytes` и `stored_size` — только если размеры разные. Отдельных
|
||||
записей — не больше `RECONCILE_FINDINGS_LOGGED_MAX` (1000) за проход,
|
||||
остальные — `unlogged` в итоге;
|
||||
- итог — «Finished reconcile pass» (`listed_objects`, `checked_rows`,
|
||||
`found` и `fixed` по классам, `remaining`, `fresh_objects`,
|
||||
`fresh_rows`, `lost_known`, `refused`, `unlogged`, `interrupted_by`,
|
||||
`duration_ms`): `info`, если ничего не осталось, иначе `warning`;
|
||||
- предел — `error` «Reconcile changes exceed limit» (`changes`,
|
||||
`max_changes`, с change `track2-reconcile-cost` — `unchecked`;
|
||||
`changes` после раннего отказа — `max_changes + 1`, нижняя граница);
|
||||
- стоимость прохода (change `track2-reconcile-cost`, решения 8 и 15):
|
||||
записи прохода связаны полями `strategy` и `deep`; итог ещё называет
|
||||
`max_objects_per_second`, `storage_objects`, `s3_requests` (`list`,
|
||||
`head`, `get`, `delete`), `read_bytes`, `db_sessions`, `unchecked`,
|
||||
`phase_ms` (`list`, `rows`, `stale`, `recheck`, `act`) — ключи
|
||||
постоянные, значения числа; «Started cleaner» — ещё
|
||||
`reconcile_max_objects_per_second`, а у разового прохода
|
||||
`reconcile_strategy` и `reconcile_deep` (у сервиса — `null`). SHA-256
|
||||
объектов и строк в записях нет;
|
||||
- непредвиденная ошибка — `error` «Reconcile pass failed» с traceback
|
||||
(`cleaner`); «Started cleaner» с change называет ещё `mode`,
|
||||
`reconcile_interval_seconds`, `reconcile_page_size`,
|
||||
`reconcile_max_changes`, `reconcile_apply`;
|
||||
- зависшую загрузку сверка убирает шагом уборщика: «Removed stale
|
||||
attachment» пишет `attachment_cleanup_service`;
|
||||
- реплика API на скачивание помеченного оригинала — `info` «Attachment
|
||||
content is lost» (`attachment_id`, `object_key`), а не `error`.
|
||||
- `filename`, ключей и секретов S3, подписей в записях уборщика нет.
|
||||
|
||||
## Где логировать
|
||||
|
||||
| Слой | Логи | Логгер модуля |
|
||||
|---|---|---|
|
||||
| `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>"` (S3 — `object_storage`) |
|
||||
| `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` не используется.
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
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'")`: в очереди за ожидающей блокировкой стоят
|
||||
все новые запросы к таблице, и чужая долгая транзакция остановила
|
||||
бы запись всех реплик. По сроку миграция падает без изменений,
|
||||
замена не начинается, повтор проходит.
|
||||
- Ревизия `ef25d50b01a8` (лаба 4, design change `attachments`,
|
||||
решение 3): таблицы `attachments` (составной FK `(chat_id,
|
||||
owner_id) → chat_members`, CHECK размера, SHA-256 32 байта, типа,
|
||||
статуса, длины и символов `filename` — `!~ '[/\\\u0001-\u001f\u007f-\u009f]'`,
|
||||
уникальный `object_key`) и `message_attachments` (PK `(message_id,
|
||||
position)`, `position` 0–9, уникальная пара `(message_id,
|
||||
attachment_id)`, индекс по `attachment_id`, FK без `ON DELETE`).
|
||||
Плюс **ослабление** `ck_messages_text_length` с `1–4000` до
|
||||
`<= 4000`: `DROP CONSTRAINT` и `ADD CONSTRAINT … NOT VALID` в той же
|
||||
транзакции. Прежние строки строже нового условия, проверять их
|
||||
нечего, а `VALIDATE` держал бы `ACCESS EXCLUSIVE` на время полного
|
||||
просмотра `messages`. Не `autocommit_block`: он зафиксировал бы DDL
|
||||
раньше `alembic_version`, и сбой оставил бы неповторяемую миграцию.
|
||||
Отметка «не проверено» в каталоге — цена, она в `REPORT.md`.
|
||||
`downgrade` — зеркально, строгое ограничение тоже `NOT VALID`.
|
||||
Autogenerate изменение CHECK не видит; имя ограничения — через
|
||||
`op.f(...)`, иначе шаблон имён даст `ck_messages_ck_messages_…`.
|
||||
- Ревизия `739b8f04d5fb` (лаба 4, design change `upload-consistency`,
|
||||
решение 6): частичный индекс `ix_attachments_pending_created_at` на
|
||||
`attachments (created_at, id) WHERE status = 'pending'` — кандидаты
|
||||
уборщика keyset. Индекс на рабочей таблице — только `CONCURRENTLY`:
|
||||
обычный `CREATE INDEX` берёт `SHARE` и останавливает запись загрузок
|
||||
на время сборки. `CONCURRENTLY` не работает в транзакции, поэтому
|
||||
`with op.get_context().autocommit_block()`; в нём `SET LOCAL` не
|
||||
действует — `SET lock_timeout = '2s'` на уровне сессии и `RESET
|
||||
lock_timeout` в конце. `create_index(..., postgresql_concurrently=True,
|
||||
if_not_exists=True)`: повтор после сбоя проходит. `downgrade` —
|
||||
`drop_index(..., postgresql_concurrently=True, if_exists=True)` так
|
||||
же. Модель — `Index(..., postgresql_where=text(...))` в `Attachment`;
|
||||
autogenerate условие не видит, ревизия руками. Проверено: с нуля,
|
||||
повтор, откат и снова `upgrade` на асинхронном `env.py`,
|
||||
`indisvalid` — true.
|
||||
- Ревизия `5c3e1f0a9b7d` (лаба 4, design change `track2-reconciler`,
|
||||
решение 6): колонка `attachments.lost_at timestamptz NULL` без
|
||||
значения по умолчанию — время, когда сверка подтвердила потерю
|
||||
оригинала. Первой строкой `SET LOCAL lock_timeout = '2s'` (`ADD
|
||||
COLUMN` берёт `ACCESS EXCLUSIVE`, но меняет только каталог — 0,36 мс
|
||||
на пробе), `downgrade` — `drop_column` с тем же сроком. Индекса нет:
|
||||
сверка просматривает все `ready`, API читает по `id`; CHECK «помечено
|
||||
только `ready`» не добавлен (на существующей таблице — `NOT VALID` или
|
||||
скан под блокировкой), пометку ставит только условный `UPDATE`.
|
||||
Прежние реплики колонку не читают и не пишут. Проверено на временной
|
||||
базе: с нуля, повтор, `downgrade -1`, снова `upgrade`, `--sql`;
|
||||
- Ревизия `a1d4c7e90b23` (лаба 5, design change `async-attachments`, решение
|
||||
1): `attachments.staging_key`, `error_code` (NULL), таблицы `attachment_jobs`
|
||||
(FK без каскада, UNIQUE вложение + версия, CHECK состояния и попыток) и
|
||||
`attachment_variants` (PK — ключ эффекта, UNIQUE `object_key`, CHECK).
|
||||
Статус — ослабление: `DROP` и `ADD CHECK … NOT VALID` в той же транзакции, как
|
||||
`ck_messages_text_length`; новый `ck_attachments_error_code_failed` тоже `NOT
|
||||
VALID`: прежние строки условию отвечают. Первой строкой `SET LOCAL lock_timeout
|
||||
= '2s'`; `downgrade` — зеркально. Прежний образ на новой схеме работает, но
|
||||
падает 500 на чтении строки нового статуса: ограничение в `REPORT.md`.
|
||||
- Ревизии `c7e2f1a04b56` и `d3f9a6b2c1e7` (лаба 5, design change
|
||||
`pipeline-reliability`, решение 10). Первая, атомарная, первой строкой `SET LOCAL
|
||||
lock_timeout = '2s'`: `attachment_jobs.attempt_base` (`NOT NULL DEFAULT 0`), CHECK
|
||||
`attempt_base BETWEEN 0 AND attempt NOT VALID`, таблица `attachment_job_replays`
|
||||
(FK на задание без каскада). Вторая — `autocommit_block`, `SET lock_timeout`,
|
||||
`CONCURRENTLY`, `if_not_exists`: `ix_attachment_jobs_outbox` по выражению
|
||||
`COALESCE(next_attempt_at, created_at), id`, `ix_attachment_jobs_published`,
|
||||
`ix_attachment_jobs_lease`, `ix_attachments_staging_cleanup`. Autogenerate условие и
|
||||
выражение не видит. У `ix_attachment_jobs_published` условие `published_at IS NOT
|
||||
NULL` запрос называет явно: без него общий план на пробе — Seq Scan. Прежний образ
|
||||
на новой схеме работает: новых статусов и `error_code` нет.
|
||||
- **INVALID-индекс.** Прерванная `CREATE INDEX CONCURRENTLY` (сбой,
|
||||
`lock_timeout`, Ctrl+C) оставляет индекс с `pg_index.indisvalid =
|
||||
false`, и `IF NOT EXISTS` его не пересоздаст: повтор миграции
|
||||
«пройдёт», а индекс останется негодным. Проверка — `SELECT
|
||||
indisvalid FROM pg_index WHERE indexrelid =
|
||||
'ix_attachments_pending_created_at'::regclass`; починка — `DROP INDEX
|
||||
CONCURRENTLY ix_attachments_pending_created_at;`, затем `alembic
|
||||
downgrade` на ревизию раньше (или правка `alembic_version`) и снова
|
||||
`upgrade`. Запросы к частичному индексу пишут статус константой, а
|
||||
не параметром (`repo-layer.md`).
|
||||
- `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` дописываются руками.
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
paths:
|
||||
- "src/core/repos/**"
|
||||
- "src/core/ports/**"
|
||||
---
|
||||
|
||||
# Слой repo (`src/core/ports/<domain>.py`, `src/core/repos/<domain>.py`)
|
||||
|
||||
Только доступ к данным. Ни бизнес-логики (проверок доступа, валидации),
|
||||
ни логов, ни внешних вызовов.
|
||||
|
||||
- Порт — `Abstract<Domain>Repository(abc.ABC)` в `src/core/ports/<domain>.py`:
|
||||
абстрактный метод и докстринг-контракт (что значат `None` и `False`, какие
|
||||
условия у перехода). Импорты порта — только DTO, enum и `src.utils`: без
|
||||
SQLAlchemy. Реализация — `SqlAlchemy<Domain>Repository(порт)` в
|
||||
`src/core/repos/<domain>.py` с `self._session`; подробности SQL (почему
|
||||
константа, какой индекс) — у неё. Модульные помощники (`_to_dto`,
|
||||
`MESSAGE_COLUMNS`) остаются модульными (change `unit-of-work`, решения 1 и
|
||||
9).
|
||||
- **Новый метод — порт, SQL, фейк `service-tests/fakes/repos.py` и проверка
|
||||
в `service-tests/repo_contract.py`,** если по результату ветвится сервис.
|
||||
Иначе `make service_test` падает и называет класс и метод.
|
||||
- Методы — только keyword-only (`*,`); вызывающий передаёт параметры по имени.
|
||||
- **Одна атомарная операция на метод:** максимум один
|
||||
`self._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 вложений (лаба 4, design change `attachments`, решения 3, 4, 8):
|
||||
- `attachment.py`: `insert_attachment` (`created_at` и `updated_at`
|
||||
одним значением), `mark_queued` (`UPDATE … WHERE status = 'pending'
|
||||
AND updated_at = created_at RETURNING`, `None` — строки `pending` нет
|
||||
или уборщик пометил её к уборке), с лабы 5 (design change
|
||||
`async-attachments`, решения 1–3) `mark_processing`,
|
||||
`return_to_queued`, `commit_ready`, `commit_failed` — условные `UPDATE`,
|
||||
`updated_at` через `greatest`: часы процессов расходятся, а CHECK
|
||||
`updated_at >= created_at` падал бы; с change `pipeline-reliability`
|
||||
`return_group_to_queued`, `replay_failed`, `lock_attachment` (`FOR NO KEY
|
||||
UPDATE`), `get_staging_candidates`, `lock_staging_candidate` (`FOR NO KEY
|
||||
UPDATE SKIP LOCKED`), `clear_staging_key` (`updated_at` не меняется);
|
||||
`attachment_job.py` (`insert_job`, `lock_job` — `FOR UPDATE`, `get_job`,
|
||||
`get_attachment_job`, `start_attempt`, `return_to_queued` с условием своей
|
||||
попытки, `finish_job`; relay — `lock_due_jobs` (`FOR UPDATE SKIP LOCKED`,
|
||||
порядок по выражению индекса), `count_published`, `count_unfinished` (сумма трёх
|
||||
`count(*)` с `LIMIT` на группу по условиям частичных индексов outbox, опубликованных
|
||||
и аренды: цена не растёт с превышением, число выше предела неточно, design change
|
||||
`track1-queue-overload`, решение 3), `mark_published` пакета,
|
||||
`recover_expired_leases`, `has_published_before`, `reset_published_before`;
|
||||
`replay_job`, `list_failed` — состояние в выборках relay константой
|
||||
`literal_execute`), `attachment_job_replay.py` (`insert_replay`,
|
||||
`get_job_replays`) и
|
||||
`attachment_variant.py` (`insert_variant` — `ON CONFLICT DO NOTHING`,
|
||||
`get_variants`, `get_variant`);
|
||||
`get_attachment`, `get_attachments` (до 10 строк по первичному
|
||||
ключу). Значения `content_type` и `status` — `.value` enum на
|
||||
записи и enum в DTO на чтении. Для уборщика (design change
|
||||
`upload-consistency`, решение 3): `get_stale_pending` (keyset по
|
||||
`(created_at, id)`, `status = 'pending'`, `created_at <
|
||||
older_than`, `LIMIT`), `lock_stale_pending` (те же условия по `id`,
|
||||
`FOR UPDATE SKIP LOCKED`; `None` — строки нет, она `ready` или её
|
||||
держат), `mark_removing` (пометка к уборке: `updated_at` = время
|
||||
уборщика, позже `created_at`; без миграции, CHECK
|
||||
`updated_after_created` выполняется), `delete_attachment`
|
||||
(`RETURNING id`, `bool`); DTO — `AttachmentInListDTO`. Порядок
|
||||
вызовов — в сервисе (`service-layer.md`), два шага: транзакция
|
||||
`lock_stale_pending` → `mark_removing`, затем транзакция
|
||||
`lock_stale_pending` → `delete_original` → `delete_attachment`.
|
||||
Статус в этих выражениях — константа
|
||||
(`literal(..., literal_execute=True)`), а не параметр: условие
|
||||
частичного индекса `ix_attachments_pending_created_at` планировщик
|
||||
доказывает только по константе, и общий план подготовленного
|
||||
выражения asyncpg иначе индекс не взял бы. Для сверки bucket и БД
|
||||
(design change `track2-reconciler`, решения 3–5):
|
||||
`get_attachments_for_objects` (`id = ANY(:ids) OR object_key =
|
||||
ANY(:keys)`, параметры-массивы, план — Bitmap OR `pk_attachments` и
|
||||
`uq_attachments_object_key`, при пустом `keys` — по сути только pk),
|
||||
`get_ready_page` (keyset `ready` по `id`, Index Scan
|
||||
`pk_attachments`), `find_attachment_reference` (строка этого `id` или
|
||||
любая с этим ключом, до двух), `mark_lost` (`UPDATE … SET lost_at
|
||||
WHERE id AND status = 'ready' AND lost_at IS NULL AND object_key
|
||||
RETURNING id`) и `clear_lost` (`lost_at IS NOT NULL` и тот же ключ);
|
||||
`_ATTACHMENT_COLUMNS` выбирает и `lost_at`;
|
||||
- `attachment_object.py` — repo над S3, как `chat_cache.py` над
|
||||
Valkey: модульные функции, первый параметр `storage: ObjectStorage`, один
|
||||
вызов на функцию; порта у этих двух нет (change `unit-of-work`, решение 8). `original_key` собирает `<namespace>/attachments/<id>/
|
||||
original` (namespace — имя базы, `filename` не входит),
|
||||
`put_original`, `open_original` (контекст объекта),
|
||||
`delete_original` (отсутствие объекта — не ошибка; компенсация
|
||||
загрузки и уборщик). Ключ хранится в
|
||||
строке и при чтении берётся из неё, не вычисляется заново. Для сверки:
|
||||
`originals_prefix` (`<namespace>/attachments/`), `is_own_key` (ключ
|
||||
под этим префиксом, без вызова S3), `parse_original_key`
|
||||
(`UUID` ключа `<id>/original` в записи сервера, иначе `None`),
|
||||
`list_originals` (страница списка), `probe_originals` (список с
|
||||
`MaxKeys=1`: bucket на месте и список разрешён), `head_original`; с change
|
||||
`pipeline-reliability` — `staging_prefix`, `is_own_staging_key`,
|
||||
`parse_staging_key`, `list_staging`, `variant_keys` (ключи вариантов всех имён);
|
||||
- `message.py`: `MESSAGE_COLUMNS` с коррелированным подзапросом
|
||||
`ARRAY(SELECT attachment_id … ORDER BY position)` — одно выражение на
|
||||
страницу и на сохранённый результат ключа; план — `SubPlan` по
|
||||
`pk_message_attachments` на строку страницы, индекс истории прежний.
|
||||
DTO — `to_message_dto` (массив → кортеж). Вставка сообщения
|
||||
перечисляет свои колонки, связи — `insert_message_attachments` одной
|
||||
многострочной вставкой с `position`.
|
||||
- Repo кэша (`chat_cache.py`) — то же правило над Valkey: первый
|
||||
параметр `cache: Cache`, одна команда на функцию, ключ и формат
|
||||
значения (JSON ↔ DTO) живут здесь. Ключ включает
|
||||
`CACHE_KEY_PREFIX` (версию формата) и `cache.namespace` (имя базы).
|
||||
@@ -0,0 +1,274 @@
|
||||
---
|
||||
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 и S3 — контейнеры compose, приложение ходит на `127.0.0.1:<*_OUT_PORT>` (`settings.md`, «Консоль и docker»); `make run_dev` сам поднимает Postgres, накатывает миграции, поднимает Valkey и S3 с bootstrap | всё в compose, зависимости по имени сервиса; миграции и bootstrap S3 — отдельные сервисы до старта API (`migrations.md`, `docker.md`) |
|
||||
| Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные, сессии и объекты S3 не теряет (`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()`, `object_storage.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`. Места загрузок (`[uploads]`) и срок тела
|
||||
в консоли работают, а ограничения буфера приёма сокетов (`sysctls` у
|
||||
`api` в compose, `docker.md`) нет: процесс на macOS, ожидающая
|
||||
загрузка держит в буфере ядра больше 512 KiB — ограничение в
|
||||
`REPORT.md` (design change `upload-memory`, решение 6). Проверки лабы 3 (≥2 реплики, failover,
|
||||
гонка через разные реплики) — только на стенде compose через LB.
|
||||
|
||||
## Уборщик (с лабы 4)
|
||||
|
||||
`python -m src.cleaner [--once]` → `src/cleaner/__main__.py` →
|
||||
`early_stop.install("cleaner")` до импорта приложения → `main()`
|
||||
(`src/cleaner/main.py`; design change `upload-consistency`, решение 2).
|
||||
В compose — сервис `cleaner` на образе API (`docker.md`), PID 1
|
||||
контейнера, как сервер.
|
||||
|
||||
- Старт: неверные настройки — запись «Invalid cleaner settings» и код
|
||||
2; grace не больше границы живой загрузки — `error` и код 2, до
|
||||
engine и клиента S3; затем обработчики SIGTERM и SIGINT asyncio,
|
||||
`early_stop.disarm()`, «Started cleaner».
|
||||
- Цикл: проход, затем ожидание `[cleaner] interval_seconds` или
|
||||
сигнала. SIGTERM / SIGINT ставят флаг: доводится до commit или отката
|
||||
текущий шаг строки — пометка или уборка (объект и строка одной
|
||||
транзакцией; не дольше срока шага с БД, 6 с, DELETE в S3 внутри него
|
||||
≤ 5 с; флаг проверяется и между шагами), новые не берутся, клиенты
|
||||
закрываются,
|
||||
«Stopped cleaner» и код 0 — раньше `stop_grace_period` 10 с. Сигнал
|
||||
до обработчиков asyncio — ранний обработчик: «Stopped cleaner before
|
||||
startup», код 0.
|
||||
- `--once` — один проход и выход: 0 — дошёл до конца, 1 — прерван
|
||||
отказом хранилища или ошибкой, 2 — неверная конфигурация.
|
||||
- С change `track2-reconciler` (решения 1, 8, 9):
|
||||
- `python -m src.cleaner reconcile [--apply] [--max-changes N]` —
|
||||
разовая сверка bucket и БД, по умолчанию dry-run; в compose —
|
||||
`docker compose run --rm --no-deps cleaner reconcile …`, цель `make
|
||||
reconcile [APPLY=1] [MAX_CHANGES=N]`. Коды: 0 — расхождений нет, 3 —
|
||||
остались (в том числе чужие объекты и отказ по пределу), 1 — прервана
|
||||
отказом, ошибкой или сигналом, 2 — конфигурация (в том числе
|
||||
`--max-changes 0` — ошибка аргумента argparse). Подготовка общая с
|
||||
сервисом: проверка grace, сигналы, `early_stop.disarm()`, engine,
|
||||
клиент S3;
|
||||
- плановая сверка в цикле сервиса: после прохода уборки, если подошёл
|
||||
срок, — `reconcile(apply=True)` с пределом из настроек; первая — при
|
||||
старте, следующая — через `[reconciler] interval_seconds` после
|
||||
конца предыдущей (0 — нет); пауза цикла — меньшее из интервала
|
||||
уборки и времени до сверки. Пока идёт сверка, уборка ждёт;
|
||||
- SIGTERM во время сверки: текущий вызов S3 или шаг с БД доводится,
|
||||
новые страницы и действия не начинаются, итог — `interrupted_by:
|
||||
stop`; сервис выходит с кодом 0, разовый проход — с 1. Паузу предела
|
||||
скорости сигнал прерывает сразу (куски по 0,2 с): остановка — не
|
||||
позже секунды (`driver.py reconcile-signal --pace`). Для этого
|
||||
`src/cleaner/__main__.py` после `main()` выходит `os._exit(code)`
|
||||
(stdout и stderr сброшены, клиенты закрыты): финализация
|
||||
интерпретатора при 0,25 CPU — 0,8–1,5 с (design change
|
||||
`track2-reconcile-cost`, «Уточнения apply», п. 14);
|
||||
- с change `track2-reconcile-cost` (решения 4–6) у разового прохода ещё
|
||||
`--strategy {batch,head}` (по умолчанию `batch`), `--deep` и
|
||||
`--max-objects-per-second R` (≥ 0, иначе ошибка argparse, код 2; без
|
||||
аргумента — `[reconciler] max_objects_per_second`); `make reconcile
|
||||
STRATEGY=head DEEP=1 RATE=R`. Плановая сверка — всегда `batch`, без
|
||||
глубокой, предел из настроек.
|
||||
- Непредвиденная ошибка прохода — `error` с traceback, процесс живёт
|
||||
до следующего прохода; отказ S3 или PostgreSQL — `warning`, без
|
||||
перезапуска (решение 5).
|
||||
- В консоли (`make run_dev`) уборщика нет: зависшие загрузки
|
||||
консольного API убирает уборщик стенда (та же база) или разовый
|
||||
`docker compose run --rm --no-deps cleaner --once`. Цели Makefile
|
||||
нет: образ для него собирает `make run_docker`.
|
||||
|
||||
## Worker (с лабы 5)
|
||||
|
||||
`python -m src.worker` → `src/worker/__main__.py` → `early_stop.install("worker")`
|
||||
→ `main()` (`worker.md`), в compose — сервис `worker`, PID 1. SIGTERM: новые
|
||||
сообщения не берутся, начатые ждут ≤ `[worker] graceful_shutdown_seconds`,
|
||||
остальные отменяются (их процессы обработки убиты), «Stopped worker», код 0,
|
||||
`os._exit`. Сигнал на старте — «Stopped worker before startup». Неверные настройки —
|
||||
код 2. Отказ брокера, S3, PostgreSQL процесс не роняет. Консоль — `make run_dev`
|
||||
(поднимает и брокер) плюс `make run_worker` и `make run_relay` в других терминалах:
|
||||
тот же `.env`, ключи worker в окружении процесса. Без relay консольный API принимает
|
||||
файлы, а задания ждут в PostgreSQL. Лимит памяти процесса обработки на macOS не
|
||||
действует (`worker.md`).
|
||||
|
||||
## Relay (с лабы 5)
|
||||
|
||||
`python -m src.relay` → `src/relay/__main__.py` → `early_stop.install("relay")` →
|
||||
`main()`, в compose — сервис `relay`, PID 1. SIGTERM: текущий шаг доводится (≤ 6 с),
|
||||
новые не начинаются, паузу сигнал прерывает сразу, «Stopped relay», код 0, `os._exit`.
|
||||
Сигнал на старте — «Stopped relay before startup». Неверные настройки — код 2. Отказ
|
||||
брокера и PostgreSQL процесс не роняет. `python -m src.relay replay …` — разовая
|
||||
команда реестра `failed`, коды 0 / 3 / 1 / 2 (`make replay`).
|
||||
|
||||
## 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 start_s3` — Postgres из compose и
|
||||
миграции, Valkey и S3 с bootstrap из 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 и s3-bootstrap → `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` и шесть секретов
|
||||
S3; в существующий `.env` дописываются переменные шаблона, которых
|
||||
в нём нет, секреты — случайными, прежние строки не меняются;
|
||||
печатаются только имена — `settings.md`),
|
||||
`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`; запрос называет удаляемые volumes Postgres и S3 —
|
||||
`<проект>_postgres_data`, `<проект>_s3_data`). Volumes — именованные
|
||||
`postgres_data` и `s3_data` в compose; `wipe_data` пересоздаёт и
|
||||
Valkey, то есть чистит кэш.
|
||||
- Valkey: `start_cache` (`$(DC) up -d --wait valkey`), `stop_cache`.
|
||||
- S3 (с лабы 4): `start_s3` — `$(DC) up -d --wait s3`, затем `$(DC) up
|
||||
--no-deps --exit-code-from s3-bootstrap s3-bootstrap`: `--wait`
|
||||
одноразовый сервис считает готовым уже запущенным, а код bootstrap
|
||||
нужен цели (design change `s3-storage`, «Уточнения apply», п. 1);
|
||||
`stop_s3` (плавно ~15 с); `s3_check` — `driver.py s3-check`:
|
||||
проверка приватности bucket вне API на запущенном стенде (права ключа
|
||||
API, чужой bucket, административные запросы, аноним с хоста и из
|
||||
сети, порты контейнера S3), таблица «проверка → ожидаемо → получено»,
|
||||
код 1 при нарушении.
|
||||
- Реплики за 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`).
|
||||
- Быстрые тесты (`service-tests.md`): `service_test` — `uv run pytest -c
|
||||
service-tests/pytest.ini service-tests/unit`, без хранилищ и docker;
|
||||
`service_test_db: start_db` — `service-tests/db` на временной базе в PostgreSQL
|
||||
стенда.
|
||||
- `test_isolated: env_setup start_db start_cache start_s3` — образ на
|
||||
временной базе (`student-tests.md`); Valkey и S3 общие с рабочим
|
||||
стендом, ключи кэша и объектов разделены именем базы, префикс
|
||||
`test_<db>/` bucket удаляется при уборке. Один контейнер 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` не зависит: стенд свой (Postgres, Valkey, S3) и удаляется
|
||||
вместе с volumes.
|
||||
`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).
|
||||
@@ -0,0 +1,316 @@
|
||||
---
|
||||
paths:
|
||||
- "src/core/services/**"
|
||||
---
|
||||
|
||||
# Слой service (`src/core/services/<domain>.py`)
|
||||
|
||||
Бизнес-логика, проверки доступа, серверные значения (id, время),
|
||||
транзакции, вызовы внешних клиентов, логи.
|
||||
|
||||
- Класс `<Domain>Service`. `__init__` принимает
|
||||
`uow: AbstractUnitOfWork` (`src/core/ports/uow.py`) и хранит её в
|
||||
`self`; кэш Valkey (`cache: Cache`), если он нужен домену, — вторым
|
||||
параметром (`ChatService`, `MessageService`). Методы принимают
|
||||
keyword-only параметры (`*,`) и вызываются только именованными
|
||||
аргументами.
|
||||
- **Граница транзакции — блок единицы работы** (change `unit-of-work`,
|
||||
спек `unit-of-work`, Cosmic Python, глава 6). Один блок — одна
|
||||
транзакция:
|
||||
|
||||
```python
|
||||
async with self.uow:
|
||||
job = await self.uow.jobs.lock_job(job_id=job_id)
|
||||
if job is None:
|
||||
return JobOutcome.ACK # выход без commit — откат
|
||||
await self.uow.jobs.finish_job(...)
|
||||
await self.uow.commit()
|
||||
```
|
||||
|
||||
Выход без `commit()`, в том числе по исключению, откатывает. После
|
||||
`commit()` блок закончен: repo и вторая фиксация — `UnitOfWorkError`,
|
||||
следующая транзакция — следующим блоком. Вложенный блок и repo вне блока
|
||||
— та же ошибка, в том числе на фейке. В сервисах нет `AsyncSession`,
|
||||
SQLAlchemy, реализаций repo на SQL и глобалов хранилищ: это проверяет
|
||||
`service-tests/unit/test_architecture.py`, реализации выбирают точки
|
||||
входа процессов. Экземпляр единицы работы — одна задача: в API на
|
||||
запрос, в worker сервис на доставку, в relay, уборщике, сверке и replay —
|
||||
на сервис. Кэш и S3 в единицу работы не входят: фиксация и откат на них
|
||||
не действуют.
|
||||
- Кэш карточки чата (`chat_cache_repo`, спек `chat-cache`):
|
||||
cache-aside — сначала кэш, при промахе БД и запись в кэш; новый чат
|
||||
пишется в кэш **после** `commit()`, чтобы откат не оставил в кэше
|
||||
чата, которого нет в БД. Отсутствующий чат не кэшируется. Кэшировать
|
||||
можно только неизменяемое: историю, списки и сессии — нет. Отказ
|
||||
Valkey сервис не обрабатывает: `Cache` уже вернул промах.
|
||||
- Repo — через единицу работы: `self.uow.chats.get_chat(chat_id=…)`,
|
||||
только именованные аргументы. `chat_cache` и `attachment_object` остаются
|
||||
модулями: `from src.core.repos import chat_cache as chat_cache_repo`, первый
|
||||
параметр — клиент. Членство внутри чужого блока — `require_member(uow, cache,
|
||||
*, chat_id, user_id)` из `services/chat.py`, требует открытый блок.
|
||||
- Проверка доступа — здесь. Не участник получает то же исключение, что
|
||||
«не найден» (`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 внутри одного блока и один
|
||||
`await self.uow.commit()` в конце. Ошибка до commit — откат при выходе
|
||||
из блока, и в БД не остаётся ничего. Откат составной операции —
|
||||
проверка уровня 4.
|
||||
- Фиксирует только сервис, repo не фиксирует и не откатывает.
|
||||
- Уникальность (`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);
|
||||
- захват — `self.uow.idempotency.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`).
|
||||
- Вложения (лаба 4, design change `attachments`, решения 1, 5–9):
|
||||
- `AttachmentService(uow, cache, storage, slots)`: каждый шаг с БД —
|
||||
свой блок: соединение пула не занято передачей тела, на запрос не больше
|
||||
одного соединения. `storage` — глобал
|
||||
`object_storage` из зависимости, `slots` — глобал `upload_slots`
|
||||
(места загрузок процесса, `infra.md`; в сервисе только тип под
|
||||
`TYPE_CHECKING`);
|
||||
- предел принятой работы (design change `track1-queue-overload`, решение 3): в том
|
||||
же первом блоке, что членство, — `Content-Type`, `Content-Length`, затем
|
||||
`self.uow.jobs.count_unfinished(limit=…)`; у предела `info` «Rejected attachment»
|
||||
`reason=backlog`, `unfinished`, `limit` и `UploadBacklogFull`. Значение 0 — запроса
|
||||
нет. Шаг с БД до тела один, поэтому граница молчания реплики и цепочка LB прежние.
|
||||
Предел мягкий: превышение — только загрузки в полёте, жёсткая граница потребовала
|
||||
бы блокировки на фиксацию;
|
||||
- порядок записи загрузки: проверки (членство, `Content-Type`,
|
||||
`Content-Length`, предел заданий) — без места → `async with self.slots.slot()` (429
|
||||
`UploadsBusy`: `info` «Rejected attachment», `reason=busy`,
|
||||
`waited_ms`) → внутри `_store` весь остальной путь до ответа: чтение
|
||||
тела со счётчиком под `asyncio.timeout([uploads]
|
||||
body_timeout_seconds)` (истёк — `UploadTimedOut`, 400) → структура
|
||||
изображения и SHA-256 одним `anyio.to_thread.run_sync` над
|
||||
`buffer.getvalue()` → `size = len(data)`, `del data` → строка
|
||||
`pending` с `object_key` и `staging_key` (commit) → `buffer.seek(0)`,
|
||||
PUT этим же `BytesIO` в staging (`attachment_object_repo.put_original(...,
|
||||
body=buffer, size=size)`), `buffer.close()` → `_mark_queued`: `queued` и
|
||||
задание одной транзакцией → снимок DTO; место освобождается при выходе из
|
||||
контекста, в том числе после компенсации и при отмене. С change
|
||||
`pipeline-reliability` (решение 1) брокера в пути запроса нет: строка
|
||||
`queued` без `published_at` — намерение, его публикует relay. Worker и relay —
|
||||
`worker.md`. Отказ S3 или БД после `pending` — 503, строка остаётся до уборщика.
|
||||
Отклонённая до `pending` загрузка ничего не пишет (design change
|
||||
`upload-memory`, решения 1–5);
|
||||
- одна копия тела: `del data` до PUT обязателен. Пока жива ссылка на
|
||||
`bytes` из `getvalue()`, буфер `BytesIO` общий, и `getbuffer()`
|
||||
aiohttp при PUT копирует тело целиком — два тела на загрузку вместо
|
||||
одного (проба: 2,3 тела против 1,19). `bytes` в `put` не передавать:
|
||||
botocore оборачивает его в `BytesIO` с общим буфером, и копия та же;
|
||||
- ожидание места, тело и проверка — до `created_at` строки `pending`:
|
||||
граница живой загрузки уборщика (B = 17 с по формуле кода, с закрытием соединения
|
||||
до 21 с: `KNOWN_ISSUES.md`) от очереди и медленного клиента не растёт
|
||||
(`settings.md`, «Уборщик»);
|
||||
- компенсация (design change `upload-consistency`, решение 1) — только
|
||||
удаление объекта staging и только при известном исходе, в `_mark_queued`:
|
||||
флаг «COMMIT отправлен» ставится прямо перед `commit()` и только при
|
||||
найденной строке. Сбой до него (сам `UPDATE`, пул, срок) — объект
|
||||
удаляется до ответа (`_compensate`: `delete_original` без повторов,
|
||||
неудача — `warning`, исходная ошибка уходит дальше); сбой на
|
||||
`commit()` — исход неизвестен, объект не трогается. `mark_queued` →
|
||||
`None` (строку убрал или пометил к уборке уборщик) — `error`,
|
||||
удаление объекта, 503 `ServiceUnavailable`. После неудачного PUT
|
||||
компенсации нет, строку
|
||||
компенсация не удаляет никогда — её убирает уборщик. `CancelledError`
|
||||
не ловится (`except Exception`);
|
||||
- уборка — `AttachmentCleanupService(uow, storage)`
|
||||
(`services/attachment_cleanup.py`), сервис процесса уборщика, а не
|
||||
реплик API: `clean_stale_pending(*, older_than, batch_size,
|
||||
stop_requested)`. Кандидаты — блок без блокировки (keyset), затем
|
||||
каждая строка — два блока (verify W1 и повторный verify, design,
|
||||
«Уточнения apply», п. 16 и 21):
|
||||
1. блок пометки: `lock_stale_pending` (`FOR UPDATE SKIP LOCKED`) →
|
||||
`mark_removing` (`updated_at = utcnow()`) → commit;
|
||||
2. блок уборки: снова `lock_stale_pending` →
|
||||
`delete_original` → `delete_attachment` → commit; строки нет или
|
||||
она занята — пропуск.
|
||||
|
||||
Шаг 2 удаляет `staging_key or object_key`: строка прежней версии —
|
||||
конечный объект, новая — staging. Помеченную строку `mark_queued` в
|
||||
`queued` не переводит (`updated_at =
|
||||
created_at`), поэтому сбой после удаления объекта (откат шага 2,
|
||||
DELETE, который S3 выполнил после срока) не даёт `ready` без
|
||||
объекта. Не одна транзакция на строку: её откат после удачного
|
||||
DELETE в S3 вернул бы строку непомеченной, и загрузка, пережившая
|
||||
grace, сделала бы её `ready` без объекта. DELETE в S3 — под
|
||||
блокировкой шага 2, а не между транзакциями: реплика до `87c48b9`
|
||||
пометку не проверяет и иначе сделала бы строку `ready` прямо перед
|
||||
удалением её объекта. Вызов S3 внутри транзакции ≤ `[s3]
|
||||
timeout_seconds` (5 с) < `idle_in_transaction_session_timeout` (10 с).
|
||||
Объект раньше строки: сбой между ними оставляет строку без объекта, а
|
||||
не наоборот. Отказ S3 или
|
||||
БД прерывает проход (`session_scope` уже записал `warning`),
|
||||
помеченная строка ждёт следующего прохода — пометка ставится заново.
|
||||
`stop_requested()` проверяется перед строкой и между шагами. Итог —
|
||||
`CleanupPassDTO`;
|
||||
- очистка staging (`AttachmentCleanupService.clean_staging`, design change
|
||||
`pipeline-reliability`, решение 9): кандидаты keyset сначала `ready`, затем
|
||||
`failed` с `updated_at < retention_before`; строка — одна транзакция: `FOR NO
|
||||
KEY UPDATE SKIP LOCKED` с теми же условиями → DELETE в S3 → `staging_key = NULL`.
|
||||
`NO KEY`, не `FOR UPDATE`: отправка сообщения берёт `FOR KEY SHARE` и не должна
|
||||
ждать DELETE в S3. У `failed` ещё объекты вариантов всех имён и конечный
|
||||
оригинал; ключ вне своего префикса staging — `warning`, строка не меняется;
|
||||
- чтение: `pending`, нет строки, не участник — одно
|
||||
`AttachmentNotFound`; варианты подставляются только у `ready`;
|
||||
скачивание любого `variant` не `ready` вложения — `AttachmentNotReady`
|
||||
(409) без обращения к S3; нет варианта — 404, нет его объекта или другой
|
||||
размер — 500; оригинал — `open_original` вне транзакции,
|
||||
нет объекта или другой размер — `error` в журнале и
|
||||
`AttachmentContentMissing` (500), строка не меняется. Оригинал,
|
||||
который сверка уже пометила потерянным (`lost_at`, design change
|
||||
`track2-reconciler`, решение 5), — `info` «Attachment content is
|
||||
lost» и `AttachmentNotFound` (404) до обращения к S3; метаданные и
|
||||
`MessageService` эту колонку не смотрят (200 и 201, как у любого
|
||||
`ready`). Ответ — вариант по умолчанию до ответа преподавателя
|
||||
(`REPORT.md`, «Открытые вопросы преподавателю», п. 2);
|
||||
- сверка bucket и БД — `AttachmentReconcileService(uow, storage)`
|
||||
(`services/attachment_reconcile.py`, design change
|
||||
`track2-reconciler`, решения 3, 4, 7, 8), сервис процесса уборщика:
|
||||
`reconcile(*, older_than, apply, max_changes, page_size, batch_size,
|
||||
stop_requested)` → `ReconcilePassDTO`. Проход:
|
||||
1. S3 → БД: страницы `list_originals`, на страницу одна выборка
|
||||
`get_attachments_for_objects` (по `id` стандартных ключей, по
|
||||
тексту — нестандартных), ключи — в множество `seen`;
|
||||
2. БД → S3: `get_ready_page` keyset по `id`, ключа нет в `seen` —
|
||||
кандидат «метаданные без объекта»;
|
||||
3. зависшие — `get_stale_pending`;
|
||||
4. перепроверка каждого кандидата в БД (`get_attachment`,
|
||||
`find_attachment_reference`) и HEAD до решения, в обоих режимах;
|
||||
отсутствие объекта — только после `probe_originals` (bucket на
|
||||
месте);
|
||||
5. предел `max_changes` (удаления объектов, пометки и снятия пометок;
|
||||
больше — `error`, ни одного из них, код 3), затем с `apply` по
|
||||
порядку: зависшие (`AttachmentCleanupService.remove_stale_pending` —
|
||||
тот же шаг уборщика) → объекты без строки (ещё раз
|
||||
`find_attachment_reference`, затем `delete_original`) → `mark_lost`
|
||||
→ `clear_lost` (перед каждым — HEAD, условный `UPDATE`, свой
|
||||
commit).
|
||||
|
||||
Удаляется только объект без строки и зависшая загрузка; `ready`,
|
||||
объект строки любого статуса и чужой ключ — никогда. Действия
|
||||
начинаются после классификации: отказ на шагах 1–4 — ни одного
|
||||
изменения. Строка `ready` или зависшая загрузка с ключом вне
|
||||
`<база>/attachments/` (`attachment_object_repo.is_own_key`) — «чужой
|
||||
объект»: без HEAD, без пометки и без уборки; HEAD, пометка, снятие и
|
||||
DELETE ещё раз проверяют префикс (design change `track2-reconciler`,
|
||||
«Уточнения apply», п. 19). Отказ S3 или БД — `interrupted_by`, после
|
||||
сигнала — `stop`; `stop_requested()` (`_Pass.check_stop`) — перед
|
||||
каждым вызовом S3 и шагом с БД: остановка ждёт не больше одного вызова
|
||||
(п. 20);
|
||||
- стоимость сверки (design change `track2-reconcile-cost`, решения
|
||||
4–8): `reconcile(…, strategy, deep, max_objects_per_second, …)`.
|
||||
Параметры, счётчики и находки прохода — `_Pass`, вызовы S3 — свои
|
||||
обёртки сервиса (`_list_page`, `_probe`, `_head`, `_read`, `_delete`):
|
||||
сигнал до вызова, предел скорости после;
|
||||
- `strategy=head` — только разовый проход: шаг S3 → БД — выборка
|
||||
строки на объект (`get_attachments_for_objects` с одним элементом),
|
||||
пара «строка — объект» с тем же ключом пропускается; шаг БД → S3 —
|
||||
HEAD на строку своей базы (с `deep` у непомеченной строки старше
|
||||
grace — сразу GET). Множества `seen` нет. Классификация пары —
|
||||
общая `_row_with_object`, строки без объекта — `_row_without_object`:
|
||||
расхождения те же, что у `batch`. Каждая строка сравнивается с
|
||||
объектом по своему ключу: у `batch` шаг списка сравнивает объект
|
||||
стандартного ключа со строкой своего `id`, нестандартного — с
|
||||
каждой строкой этого ключа, а строку с ключом `<id>/original`
|
||||
другого вложения — шаг строк HEAD (`_key_of_other_id`; verify W2,
|
||||
design, «Правки по verify», п. 2);
|
||||
- `deep` — GET и SHA-256 потоком (`open_original`, блоки клиента,
|
||||
`hashlib`) у строки `ready` без пометки, старше grace, с объектом
|
||||
того же размера, не моложе grace; класс `checksum_mismatch` — в
|
||||
`LIMITED_KINDS` и `ACTION_ORDER` (пометка), не в `NEEDS_BUCKET`.
|
||||
«Оригинал вернулся» и «другой SHA-256» (`NEEDS_READ`) перепроверка и
|
||||
действие подтверждают заново прочитанным объектом: размер и SHA-256
|
||||
строки (`ReconcileFindingDTO.sha256`). Без `deep` вернувшийся объект
|
||||
тоже читается — пометку снимает только тот же SHA-256; другой —
|
||||
`lost_known`. Объект моложе grace — свежий и в перепроверке: «другой
|
||||
SHA-256» читается с `fresh_before` (`_fresh_before`), объект другого
|
||||
размера свежим не подтверждается ни в классификации, ни в
|
||||
перепроверке, ни перед пометкой; вернувшийся читается без порога
|
||||
(verify S1);
|
||||
- предел скорости — после каждого вызова S3 (`_pace`): затронуто
|
||||
(`_touched` — ключи страниц и HEAD/GET/DELETE, разность
|
||||
`storage.stats()` с начала) больше `R × время с начала прохода` —
|
||||
`asyncio.sleep` кусками ≤ `RECONCILE_PACE_STEP_SECONDS` (0,2 с) с
|
||||
проверкой сигнала. Пауза после вызова, а не перед следующим: тогда и
|
||||
последний вызов прохода не обгоняет предел (design, «Уточнения
|
||||
apply»). DELETE шага уборки зависшей — тоже: `_pace` после
|
||||
`remove_stale_pending`. Сигнал прекращает ожидание, но `_pace` не
|
||||
бросает `_Stopped`: итог вызова перед паузой (страница, удаление)
|
||||
доходит до записи «Fixed» и счёта, а проход останавливает
|
||||
`check_stop()` перед следующим вызовом (verify W1);
|
||||
- ранний отказ: с `apply` в `_recheck_all`, как только подтверждённых
|
||||
классов `LIMITED_KINDS` больше `max_changes`, остальные кандидаты
|
||||
этих классов не перепроверяются, а считаются в `unchecked`; `_act`
|
||||
отказывает тем же условием (`changes` = `max_changes + 1`). Dry-run
|
||||
перепроверяет всех;
|
||||
- счёт сеансов — `db_sessions` итога, разность `uow.blocks_opened` с
|
||||
начала прохода; внутренний `AttachmentCleanupService` работает на том
|
||||
же экземпляре единицы работы, его блоки входят в счёт; длительность
|
||||
шагов — `_Pass.phase` (`list`,
|
||||
`rows`, `stale`, `recheck`, `act`). Плановая сверка — `batch`, без
|
||||
`deep`, предел из настроек (`src/cleaner/main.py`);
|
||||
- сверка (с лабы 5, решение 11): объект варианта
|
||||
(`parse_variant_key`) — строка `id` есть, пропуск; нет — объект без
|
||||
метаданных (удаление с `--apply`), свежий — свежий. `processing` и `failed` не
|
||||
находки, зависшая загрузка называет ключ staging. С change
|
||||
`pipeline-reliability` (решение 9) — ещё шаг `_list_staging` (та же обёртка
|
||||
сигнала и скорости): `<id>/original` строки с этим `staging_key` — пропуск; иначе
|
||||
`orphan_staging` старше срока хранения (`staging_older_than`), моложе — свежий;
|
||||
другой ключ под staging — `unknown_object`; итог — `listed_staging`;
|
||||
- `MessageService.send_message(..., attachment_ids)`: членство →
|
||||
`get_attachments` (все найдены, чат этого сообщения, не `pending`; иначе
|
||||
`AttachmentNotFound` до захвата ключа) → хэш → ключ → новый ключ при
|
||||
`failed` среди вложений: откат и `AttachmentFailed` (409), ключ свободен;
|
||||
занятый — прежняя ветка повтора, на состояние вложения не глядя → сообщение
|
||||
→ `insert_message_attachments` (если список непустой) → один commit;
|
||||
- хэш: `message_request_hash(text, attachment_ids)` — `attachment_ids`
|
||||
в каноническом JSON только непустым, id — `str(UUID)` (нижний
|
||||
регистр), порядок значим. Пустой список хэш версии `e1161f7` не
|
||||
меняет: ключ, сохранённый до замены реплик, повторяется.
|
||||
- Недоступность 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`.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
paths:
|
||||
- "service-tests/**"
|
||||
---
|
||||
|
||||
# Быстрые тесты сервисов (`service-tests/`)
|
||||
|
||||
Спек `unit-of-work`, «Быстрые тесты сервисов»; design change `unit-of-work`,
|
||||
решения 11 и 13. Каталог вне `student-tests/`: правило black-box там прежнее, `make
|
||||
student_test` его не собирает. В образ не попадает (`.dockerignore`).
|
||||
|
||||
| Что | Где | Цель |
|
||||
|---|---|---|
|
||||
| ветки сервисов, архитектура, контракт repo на фейке | `unit/` | `make service_test`: без PostgreSQL, Valkey, S3, брокера, docker и сети, секунды |
|
||||
| настоящая единица работы, контракт repo на SQL, общий срок запроса | `db/` | `make service_test_db`: временная база `test_uow_<db>` в PostgreSQL стенда |
|
||||
| блокировки, конкуренция, исход COMMIT, триггеры | `student-tests/test_failures.py` | только `make failure_checks`: фейк их не воспроизводит |
|
||||
|
||||
- **Фейки, а не моки.** Тест проверяет исход и журнал `database.events`, а не набор
|
||||
вызовов. Метод фейка реализует контракт из докстринга порта: условие перехода, keyset
|
||||
по полям, порядок результата. Нет плана запроса, блокировок, индексов, внешних
|
||||
ключей и `greatest` сверх контракта. Занятая строка — `database.held`, отказ —
|
||||
`database.fail_on`, `database.fail_commit`.
|
||||
- **Новый метод — порт, SQL, фейк и строка контракта.** `test_architecture.py` сверяет
|
||||
набор методов и сигнатуры порт — реализация — фейк и фейки клиентов — настоящие
|
||||
клиенты; `repo_contract.py` — условия, по результату которых ветвятся сервисы: один
|
||||
набор на фейке и на SQL. Разошлись — чинится фейк: SQL определяет поведение.
|
||||
- **Кэш и S3 — настоящие модули поверх фейков клиентов:** `chat_cache`,
|
||||
`attachment_object` не дублируются. `UploadSlots` — настоящий.
|
||||
- **Настройки.** `settings` читает `.env` и `config.toml` по абсолютному пути, поэтому
|
||||
поля, от которых зависят ветки, подставляет автоматическая фикстура `unit/conftest.py`:
|
||||
результат не зависит от локальных файлов. Новое поле настроек в ветке сервиса —
|
||||
строка там. В `db/conftest.py` — окружение «тесного» API до импорта `src`.
|
||||
- **Временная база:** имя проверяется `^test_uow_[a-z0-9_]+$` до любых действий, иначе
|
||||
код 2; создаётся и мигрирует в начале, удаляется при любом исходе
|
||||
(`pytest_unconfigure`). Рабочая база не затрагивается, чужие контейнеры — тоже.
|
||||
- **Замороженный сервер** — `TcpProxy` из `db/conftest.py`, а не `docker pause`
|
||||
рабочего PostgreSQL. Смена внутренних имён адаптера в `_ping_once` падает тестами
|
||||
`test_ping_*`.
|
||||
- `async def` тесты запускает плагин `anyio`: `pytestmark = pytest.mark.anyio` в модуле,
|
||||
новых зависимостей нет. Цикл событий на тест: engine закрывается в том же тесте.
|
||||
@@ -0,0 +1,374 @@
|
||||
---
|
||||
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, `S3`, `Idempotency`,
|
||||
`Uploads`, `Cleaner`, `Reconciler`).
|
||||
Экземпляр один —
|
||||
`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]`, регион, сроки и пул `[s3]`, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` |
|
||||
| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*`, `VALKEY_*` и `S3_*` (адрес, порты, учётные данные, секреты S3 с лабы 4), пароль брокера с лабы 5; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольные адреса Postgres, Valkey и S3 | нет; шаблон `.env.example` |
|
||||
| окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — |
|
||||
| `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50; с лабы 4 — 10 MiB и 40 млн пикселей вложения, 10 вложений в сообщении, `filename` 1–255), пути: одинаковы на всех установках | да |
|
||||
|
||||
Схему согласовали с преподавателем 2026-09-29 (AGENTS.md, «Согласования
|
||||
с преподавателем»). Секреты в `config.toml` допустимы. Запрет
|
||||
`Dockerfile.example` касается запекания в образ (`COPY`), а
|
||||
`config.toml` в образ не копируется, его монтируют на старте
|
||||
(`docker.md`). Но почти все секреты курса — пароли
|
||||
Postgres, Valkey, брокера, ключи S3 — нужны ещё и контейнеру зависимости,
|
||||
а его настраивает только 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}`; для S3 —
|
||||
`S3__HOST=127.0.0.1`, `S3__PORT=${S3_OUT_PORT}`,
|
||||
`S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY}`,
|
||||
`S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY}`;
|
||||
- docker: `.env` в контейнер не попадает, адрес и порт приходят из
|
||||
`environment` compose — `DATABASE__HOST: ${POSTGRES_HOST}`,
|
||||
`DATABASE__PORT: ${POSTGRES_PORT}` (якорь `x-db-env`),
|
||||
`CACHE__HOST: ${VALKEY_HOST}`, `CACHE__PORT: ${VALKEY_PORT}`
|
||||
(`x-cache-env`), `S3__HOST: ${S3_HOST}`, `S3__PORT: ${S3_PORT}`
|
||||
(`x-s3-env`).
|
||||
|
||||
Адреса и порты Postgres, Valkey и S3 в compose — только переменные
|
||||
`.env`, литерал — лишь адрес публикации `127.0.0.1` (`docker.md`).
|
||||
|
||||
В новый `.env` `make env_setup` подставляет случайные
|
||||
`POSTGRES_PASSWORD`, `VALKEY_PASSWORD` и шесть секретов S3 и печатает
|
||||
только их имена. Существующий `.env` он не перезаписывает, а дописывает
|
||||
в конец переменные шаблона, которых в нём нет (с change
|
||||
`upload-consistency`, design, «Уточнения apply», п. 1): секреты —
|
||||
случайными значениями той же подстановкой, что для
|
||||
нового `.env` (`ENV_FILLED`), остальные — значениями шаблона, под
|
||||
комментарием `# added by make env_setup from .env.example`. Прежние
|
||||
строки не меняются, в вывод — только имена («added to existing .env:
|
||||
…»), повторный запуск ничего не дописывает. Так приходят и секреты
|
||||
уборщика `S3_CLEANER_*` (без них compose останавливается на `:?` «run
|
||||
make env_setup»). Значение уже существующей переменной (пустой секрет,
|
||||
изменённый шаблоном порт) он не трогает: такое переносится руками,
|
||||
секреты — `openssl rand -hex 32`.
|
||||
|
||||
### S3 (с лабы 4)
|
||||
|
||||
- `[s3]`: `host`, `port` (8333), `bucket` (`messenger`, валидатор по
|
||||
`S3_BUCKET_NAME_PATTERN`: иначе сервис не стартует, в ошибке —
|
||||
`bucket`), `access_key_id` и `secret_access_key` (`SecretStr`, пусто
|
||||
— `warning` при старте), `region` (`us-east-1`), сроки
|
||||
`connect_timeout_seconds` (1) и `timeout_seconds` (5, `gt=0`), пул
|
||||
`max_connections` (10, `ge=1`). URL — свойство `endpoint_url`.
|
||||
- Имя bucket читают и приложение, и bootstrap, поэтому в `.env` оно в
|
||||
формате настроек — `S3__BUCKET`; bootstrap получает его как
|
||||
`S3_BUCKET: ${S3__BUCKET:-messenger}`. Регион, сроки и пул — в
|
||||
`config.toml`, адреса и ключей там нет.
|
||||
- Секреты S3 в `.env` (кто какой получает — `docker.md`):
|
||||
`S3_ROOT_ACCESS_KEY` / `S3_ROOT_SECRET_KEY` — административная пара,
|
||||
только сервер; `S3_JWT_SIGNING_KEY` — ключ подписи служебных вызовов;
|
||||
`S3_API_ACCESS_KEY` / `S3_API_SECRET_KEY` — пользователь API: один
|
||||
источник для bootstrap и приложения (мост). Новый секрет API действует
|
||||
после следующего bootstrap (`make run_docker`), прежний перестаёт.
|
||||
`S3_CLEANER_ACCESS_KEY` / `S3_CLEANER_SECRET_KEY` — пользователь
|
||||
уборщика (чтение и удаление объектов): bootstrap и сервис `cleaner`
|
||||
через `environment` compose (`S3__ACCESS_KEY_ID`,
|
||||
`S3__SECRET_ACCESS_KEY`), моста в консоль нет — консольного уборщика
|
||||
нет, разовый проход идёт в контейнере.
|
||||
|
||||
### Загрузки (с change `upload-memory`)
|
||||
|
||||
`[uploads]` (класс `Uploads`, design change `upload-memory`, решения 1–4
|
||||
и 9) читает процесс API: `max_concurrent` (int, `ge=1`, 4),
|
||||
`max_waiting` (int, `ge=0`, 16; 0 — без очереди, сразу 429),
|
||||
`wait_timeout_seconds` (float, `gt=0`, 5), `body_timeout_seconds`
|
||||
(float, `gt=0`, 30). Значения — в `config.toml`, разовая подмена —
|
||||
`UPLOADS__*` (стенд отказов — 1 / 1 / 1 / 3 у третьего API, профиль
|
||||
`uploads` — 1000 / 0 у варианта «без лимита»). Настройки, а не
|
||||
константы: у установок разный лимит памяти. Неверное значение —
|
||||
ошибка проверки настроек с именем поля, сервис не стартует. «Started
|
||||
API» называет все пять (с `max_unfinished_jobs`).
|
||||
|
||||
- `max_unfinished_jobs` (int, `ge=0`, 250; 0 — без предела; design change
|
||||
`track1-queue-overload`, решения 1–2): при каком числе незавершённых заданий стенда
|
||||
(`queued` и `processing`) загрузка получает 429 `Retry-After: 5`. Выбран по худшему
|
||||
измеренному классу: предел / потолок worker — срок ожидания, ~270 с. Файл на лимите
|
||||
CPU процесса (15 с, scan bomb в пределах контракта) этим не покрыт и не мерился:
|
||||
расчёт 250 × 15 с ≈ 1 ч разбора, при таком ожидании relay шлёт копии. При другом
|
||||
числе worker предел другой. Разовая подмена —
|
||||
`UPLOADS__MAX_UNFINISHED_JOBS` (стенд отказов и профиль `uploads` — 0, пятый API
|
||||
стенда отказов — 3). `Retry-After` — константа `UPLOAD_BACKLOG_RETRY_AFTER_SECONDS`;
|
||||
|
||||
- `max_concurrent` 4 — бюджет реплики 512 МБ: база ~105 MiB + хэши
|
||||
паролей 4 × 64 MiB + места до ~90 MiB при 40 клиентах ≈ 450 MiB; при
|
||||
8 местах — ~530 MiB;
|
||||
- `wait_timeout_seconds` 5 — молчание реплики до тела `2 × [database]
|
||||
request_timeout_seconds + wait_timeout_seconds` = 17 с, а с закрытием соединения
|
||||
на зависшем сервере (`DB_CLOSE_TIMEOUT_SECONDS`, вне срока блока) до 2 × (6 + 2) +
|
||||
5 = 21 с меньше `timeout server` LB пути загрузки (30 с, `balancer.md`); при смене
|
||||
любого из них пересчитать цепочку. **Проверки соотношения при старте нет** (в
|
||||
отличие от grace уборщика): `timeout server` живёт в `haproxy.cfg`, и
|
||||
процесс API его не знает. Поэтому `wait_timeout_seconds` больше `30 −
|
||||
2 × (request_timeout_seconds + закрытие)` = 14 с сервис примет молча, а ожидающая
|
||||
загрузка может получить 504 от LB вместо 429 реплики (design change
|
||||
`upload-memory`, «Уточнения apply», п. 14). То же для молчания после
|
||||
тела (≈ 26 с): бо́льшие `request_timeout_seconds` и `[s3]
|
||||
timeout_seconds` выводят его за 30 с так же молча;
|
||||
- `body_timeout_seconds` 30 — один срок на всё тело с момента, как
|
||||
загрузка заняла место (не срок простоя: клиент по байту раз в 29 с
|
||||
держал бы место вечно). Наибольшая длительность загрузки 21 + 30 + 26
|
||||
≈ 77 с < `ROLLOUT_DRAIN_TIMEOUT` (90 с);
|
||||
- **граница B уборщика прежняя** (17 с по формуле кода, с закрытием соединения до 21
|
||||
с): ожидание места, тело и проверка идут до `created_at` строки `pending`, а сроки
|
||||
tx1, PUT и tx2 не менялись. Поэтому `[uploads]` в проверку grace уборщика не входит.
|
||||
Закрытия формула не учитывает: при grace 900 с это неважно, `KNOWN_ISSUES.md`.
|
||||
|
||||
### Брокер и worker (с лабы 5)
|
||||
|
||||
`[broker]` (класс `Broker`, design change `async-attachments`, решение 13):
|
||||
`host`, `port`, `user`, `password` (`SecretStr`) — мосты из `RABBITMQ_*` в `.env`,
|
||||
в docker — `x-broker-env`; `connect_timeout_seconds` (2),
|
||||
`publish_timeout_seconds` (2; секцию читают relay и worker, в цепочку LB больше не
|
||||
входит). `[worker]` (класс `Worker`, design change `pipeline-reliability`, решение
|
||||
12): `concurrency` (2), `prefetch` (2), `max_attempts` (5), `job_timeout_seconds` (60),
|
||||
`lease_margin_seconds` (10), `retry_base_delay_seconds` (5), `retry_max_delay_seconds`
|
||||
(300, не меньше основы), `render_timeout_seconds` (40, меньше срока попытки),
|
||||
`render_cpu_limit_seconds` (15), `render_memory_limit_mib` (450),
|
||||
`graceful_shutdown_seconds` (8, ≤ 8), `reconnect_seconds` (2). Прежний ключ
|
||||
`retry_delay_seconds` в существующем `config.toml` молча игнорируется. `[relay]` (класс
|
||||
`Relay`): `poll_interval_seconds` (0,25), `batch_size` (100), `max_published_backlog`
|
||||
(1000, 0 — без предела), `republish_after_seconds` (300), `failure_pause_seconds` (2).
|
||||
`[cleaner] staging_retention_seconds` (86400). Подмена — `BROKER__*`, `WORKER__*`,
|
||||
`RELAY__*`. Ключи worker `S3_WORKER_*` — в `.env`, контейнеру — `environment`
|
||||
compose, консоль — `make run_worker` (мост `S3__*` в `.env` — ключи API); `make
|
||||
run_relay` — те же мосты. Имена skeleton: `BROKER_URL_FILE` → мосты `RABBITMQ_*`;
|
||||
`WORKER_CONCURRENCY`, `JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS` → поля `[worker]`;
|
||||
`STAGING_RETENTION_SECONDS` → `[cleaner] staging_retention_seconds`.
|
||||
|
||||
### Уборщик (с лабы 4)
|
||||
|
||||
`[cleaner]` (класс `Cleaner`, design change `upload-consistency`,
|
||||
решение 4) читает только процесс `python -m src.cleaner`:
|
||||
`interval_seconds` (float, `gt=0`, 60), `pending_grace_seconds` (int,
|
||||
`gt=0`, 900), `batch_size` (int, `ge=1`, 100). Значения — в
|
||||
`config.toml`, разовая подмена — `CLEANER__*` в окружении (стенд
|
||||
отказов — 20 и 1 в `failures.compose.yml`, драйвер — grace 30 с).
|
||||
Неверное значение — запись «Invalid cleaner settings» без значений
|
||||
полей и код 2 (`src/cleaner/__main__.py`). Grace сравнивает с границей
|
||||
живой загрузки `2 × [database] request_timeout_seconds + [s3]
|
||||
timeout_seconds` (17 с) сама точка входа уборщика, а не валидатор
|
||||
`Settings`: реплики API от неё не зависят. Сроки берутся из настроек
|
||||
процесса уборщика: `config.toml` общий, а подмена сроков окружением
|
||||
только у API проверку обошла бы — ограничение в `REPORT.md`.
|
||||
- Порт API S3 в сети — `S3_PORT`, на `127.0.0.1` хоста — `S3_OUT_PORT`
|
||||
(8334, как 5433 и 6380).
|
||||
|
||||
### Сверка (с change `track2-reconciler`)
|
||||
|
||||
`[reconciler]` (класс `Reconciler`, design change `track2-reconciler`,
|
||||
решение 10) читает только процесс уборщика: `interval_seconds` (float,
|
||||
`ge=0`, 3600; 0 — без плановой сверки), `page_size` (int, 1–1000, 1000:
|
||||
больше 1000 ключей S3 за страницу не отдаёт), `max_changes` (int,
|
||||
`ge=1`, 100). Значения — в `config.toml`, разовая подмена —
|
||||
`RECONCILER__*`; разовый проход принимает предел ещё и аргументом
|
||||
`--max-changes`. Своего grace у сверки нет — `[cleaner]
|
||||
pending_grace_seconds` и его проверка при старте (одна ручка «свежести»).
|
||||
Неверное значение — «Invalid cleaner settings» с `loc` поля и код 2, как
|
||||
у `[cleaner]`. «Started cleaner» называет `reconcile_interval_seconds`,
|
||||
`reconcile_page_size`, `reconcile_max_changes` и `mode`. Стенд отказов и
|
||||
`bench/` — `RECONCILER__INTERVAL_SECONDS: "0"`.
|
||||
|
||||
С change `track2-reconcile-cost` (решение 6) ещё `max_objects_per_second`
|
||||
(float, `ge=0`, `allow_inf_nan=False`, 2000; 0 — без предела; `inf` —
|
||||
ошибка: «Started cleaner» было бы не JSON, verify S2; у прочих полей
|
||||
`float` тот же дефект — `KNOWN_ISSUES.md`) — предел скорости прохода:
|
||||
объектов S3 в секунду в среднем от начала прохода (ключи страниц списка,
|
||||
HEAD, GET, DELETE). Разовая подмена — `RECONCILER__MAX_OBJECTS_PER_SECOND`,
|
||||
у разового прохода — `--max-objects-per-second R` (`make reconcile
|
||||
RATE=R`); плановая сверка берёт значение из настроек. Почему 2000: CPU
|
||||
шлюза на ключ списка — 0,085–0,11 мс (проба), 2000 ключей в секунду —
|
||||
~0,2 ядра S3 из 1; проход 100k на лимите стенда — с ~30 до ~65 с, на
|
||||
рабочем стенде (2–3 тыс. объектов) — ~1,5 с в час; граница нагрузки на
|
||||
S3 не зависит от CPU уборщика. Проверка выбора — метка профиля сверки
|
||||
(`bench.md`), итог — `REPORT.md`. «Started cleaner» называет
|
||||
`reconcile_max_objects_per_second`.
|
||||
|
||||
`.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`.
|
||||
|
||||
Skeleton lab4 добавил имена `S3_*` (буквально не заводятся,
|
||||
соответствие — в `REPORT.md`, design change `s3-storage`, решение 5):
|
||||
|
||||
- `S3_ENDPOINT` → `S3__HOST` и `S3__PORT` (мосты в консоли,
|
||||
`x-s3-env` в docker);
|
||||
- `S3_REGION` → `[s3] region`;
|
||||
- `S3_BUCKET` → `S3__BUCKET`;
|
||||
- `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` → мосты из
|
||||
`S3_API_*`: значения, а не файлы, как с `DATABASE_URL_FILE`;
|
||||
- `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` — **константы, не настройки**
|
||||
(спек `service-configuration`, «Лимиты вложений — константы
|
||||
контракта»; design change `attachments`, решение 10):
|
||||
`ATTACHMENT_MAX_BYTES` (10 485 760) и `ATTACHMENT_MAX_PIXELS`
|
||||
(40 000 000) в `src/utils/constants.py`. Их задаёт контракт, они
|
||||
одинаковы на всех установках, поэтому ни окружение, ни `.env`, ни
|
||||
`config.toml` их не меняют, и в `.env.example` они не заводятся.
|
||||
Соответствие имён — в `REPORT.md`.
|
||||
|
||||
`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`.
|
||||
@@ -0,0 +1,642 @@
|
||||
---
|
||||
paths:
|
||||
- "student-tests/**"
|
||||
---
|
||||
|
||||
# Собственные тесты (`student-tests/`)
|
||||
|
||||
Быстрые тесты сервисов на фейках и настоящая единица работы — не здесь:
|
||||
`service-tests/` (`service-tests.md`). Здесь только black-box по HTTP.
|
||||
|
||||
В 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.
|
||||
|
||||
Лаба 4 добавляет (спек `attachments`, design change `attachments`,
|
||||
решение 12):
|
||||
|
||||
- `test_attachments.py` — сценарии спека `attachments`, кроме проверок
|
||||
отказов и исключений: загрузка PNG/JPEG и разновидностей, граница
|
||||
размера, 413 по `Content-Length` и частями, пиксели, «бомба», тип по
|
||||
содержимому и подмена MIME, повреждения и хвост, `filename` (400 только
|
||||
по списку контракта, Cf/Zl принимаются как есть), порядок проверок,
|
||||
доступ, метаданные, побайтный оригинал, `variant`, следы хранилища,
|
||||
повторная загрузка; «Скачивание через другую реплику» — с фикстурой
|
||||
`replicas`. Новые сценарии `messages`, `idempotency`,
|
||||
`api-conventions`, `data-storage` — в их модулях; пять сценариев
|
||||
рубрики «4» лабы 4 — в `test_rubric.py` (сценарий `student-tests` — в
|
||||
докстринге, маркеры — на сценарии `attachments` и `messages`);
|
||||
- `images.py` — генераторы: PNG на stdlib (любые IHDR и IDAT, Adam7,
|
||||
точный размер чанком `tEXt`, «бомба», огромные размеры, порча байта
|
||||
IDAT), JPEG через Pillow (разновидности, в том числе baseline без DHT;
|
||||
подмена размеров в SOF; `jpeg_undecodable` — без таблиц, изменённый
|
||||
заголовок скана, пустой скан, 27 байт из замечания ревьюера —
|
||||
`test_undecodable_jpeg`, красный на `e30b649`), обрезка и хвост.
|
||||
Большие файлы и «бомбы» живут в памяти теста, в git
|
||||
не попадают. С лабы 5 Pillow — основная зависимость worker; в тестах он
|
||||
генератор и проверка пикселей;
|
||||
- `api_client.py`: `post_attachment` (байты или итератор — частями,
|
||||
без `Content-Length`; `None` — без заголовка или параметра),
|
||||
`upload` (201 и проверка размера, SHA-256, `owner_id`, `filename`),
|
||||
`attachment_meta`, `attachment_content`, `send_message(...,
|
||||
attachment_ids=…)`. `contract.py`: коды 413 и 415, `owner_id` и
|
||||
элементы `attachment_ids` — UUID в нижнем регистре, `updated_at` —
|
||||
время, `assert_content` (байты, тип, длина, `nosniff`, без `Location`
|
||||
и `x-amz-*`);
|
||||
- проверки отказов (`test_failures.py`): «Запись в S3 не удалась»,
|
||||
«Отклонённая загрузка ничего не оставляет», «S3 остановлен» (с
|
||||
историей `attachment_ids` без S3), «S3 завис»; вне сверки — «Окружение
|
||||
не меняет лимит» спека `service-configuration`. Срок «S3 завис» —
|
||||
`[s3] timeout_seconds` (5 с) плюс запас; клиент теста — со сроком
|
||||
больше этого, иначе httpx оборвёт раньше ответа;
|
||||
- с change `upload-consistency` (design, решение 10) — согласованность
|
||||
БД и S3 и уборщик, тоже проверки отказов:
|
||||
- **списки `id`, а не счётчики**: уборщик стенда отказов убирает
|
||||
строки прежних тестов параллельно, и «`pending` +1» зависел бы от
|
||||
порядка тестов; после DELETE SeaweedFS оставляет пустой каталог
|
||||
`<id>/` ещё ~2 мин, и счёт по каталогам завышен. Тесты сравнивают
|
||||
множества: новые `id` (`after − before`), готовые — те же, объекты
|
||||
без строки — `object-ids − attachment-ids` (сначала строки, потом
|
||||
объекты: уборщик удаляет объект раньше строки);
|
||||
- hook: `attachment-ids` (`<id> <status>` через psql), `last-pending`
|
||||
(замечание S6 verify `attachments`), `object-ids` (файлы `original`
|
||||
из `weed shell fs.tree` под `/buckets/<bucket>/<база>/attachments`;
|
||||
bucket и база — `FAULT_S3_BUCKET`, `FAULT_DATABASE` от
|
||||
`run_failures.py`), `fail-attachments
|
||||
insert|ready|stall|commit|outlive|undeletable <filename>` (триггеры
|
||||
на уникальный `filename` теста, сбой — SQLSTATE 08006, для API отказ
|
||||
БД, 503: вставка или перевод в `ready` падает; `stall` — перевод в
|
||||
`ready` ждёт `pg_sleep(4)`; `commit` — отложенный триггер
|
||||
ограничения роняет COMMIT перевода, исход для API неизвестен;
|
||||
`outlive` — строка вставляется на час старше вместе с `updated_at`,
|
||||
а перевод в `ready` ждёт до 4,5 с в триггере уровня оператора
|
||||
`BEFORE UPDATE OF status`, пока строку не уберёт уборщик: на уровне
|
||||
оператора строка не заблокирована, а пометку уборщика (только
|
||||
`updated_at`) `OF status` не задерживает; `undeletable` — как
|
||||
`outlive`, и удаление строки падает — в той же транзакции уборки,
|
||||
где уборщик уже удалил объект: это откат второго шага после удачного
|
||||
DELETE в S3), `clear-fail-attachments`,
|
||||
`kill-api` / `start-api` (`docker kill` / `docker start`
|
||||
`<FAULT_PROJECT>-api`, ожидание `healthy`);
|
||||
- тесты: `test_upload_with_object_storage_stopped` (+ «Незавершённая
|
||||
загрузка не видна»: метаданные, байты и ссылка — 404 с `message`
|
||||
неизвестного `id`), `test_rejected_uploads_leave_nothing`,
|
||||
`test_metadata_insert_failure`, `test_interrupted_body` (итератор
|
||||
тела бросает исключение после 1 MiB), `test_ready_failure_compensated`
|
||||
(объекта нет сразу после 503, на G/2 строка ещё `pending`, после
|
||||
G + I + 5 с ни строки, ни объекта), `test_object_storage_paused`
|
||||
(уборка после `unpause`), `test_killed_between_put_and_ready`
|
||||
(`stall` → строка и объект есть → `kill-api` → нет 201 → `start-api`
|
||||
в `finally` → уборка), `test_cleaner_survives_outages` (S3 и
|
||||
PostgreSQL остановлены, строка на месте после G + 3I, после возврата
|
||||
S3 убрана за I + 5 с, готовое вложение цело); по замечаниям verify —
|
||||
`test_ready_commit_outcome_unknown` (`commit`: 503, строка `pending`
|
||||
и объект есть сразу после ответа, после G + I + 5 с ни того, ни
|
||||
другого), `test_upload_outlives_grace` (`outlive`: 503, а не 201 и
|
||||
не 500, ни строки, ни объекта) и
|
||||
`test_cleaner_failure_after_object_delete` (`undeletable`: 503, а не
|
||||
201, строка `pending`, `ready` без объекта нет; после снятия
|
||||
триггера уборщик доводит уборку). Клиент загрузок с ожиданием в
|
||||
триггере — со сроком 30 с (у `Api` по умолчанию 5 с). G и I —
|
||||
`FAULT_CLEANER_GRACE_S` (20) и `FAULT_CLEANER_INTERVAL_S` (1) от
|
||||
`run_failures.py`; запас поверх G + I — 5 с;
|
||||
- красный прогон до кода (новые тесты против прежней ветки
|
||||
`mark_ready` без компенсации и без уборщика): упали
|
||||
`test_ready_failure_compensated` (объект остался),
|
||||
`test_killed_between_put_and_ready`, `test_cleaner_survives_outages`,
|
||||
`test_object_storage_paused` (строки никто не убрал); остальные
|
||||
сценарии прежний код уже выполнял. Тесты по замечаниям verify:
|
||||
`test_cleaner_failure_after_object_delete` красный на коде до пометки
|
||||
(201: ждавший `mark_ready` перевёл строку в `ready` после отката
|
||||
уборщика, объект уже удалён; на двухшаговой схеме — пометка, затем
|
||||
объект и строка одной транзакцией — тест не менялся и проверяет тот
|
||||
же откат); `test_ready_commit_outcome_unknown` и
|
||||
`test_upload_outlives_grace` на том коде зелёные (ветки были верны) и
|
||||
красные на временных регрессиях — компенсация на любой сбой (объекта
|
||||
нет сразу после 503) и возврат `RuntimeError` (500);
|
||||
- с change `upload-memory` (design, решение 11) — места загрузки и срок
|
||||
тела:
|
||||
- `test_attachments.py::test_concurrent_uploads` («Загрузки в
|
||||
пределах лимита», любой стенд): 10 участников одного чата за
|
||||
`threading.Barrier`, у каждого свой `Api` (срок 30 с) и свой PNG из
|
||||
шума ~1 MiB (`images.png_noise(seed=…)`); все 201, `id` разные,
|
||||
загрузки пересекались по времени, каждое скачивается побайтно;
|
||||
- `contract.py`: код 429 — `rate_limited`, `assert_error(resp, 429)`
|
||||
требует `Retry-After` — положительное целое;
|
||||
- третий API стенда отказов — «узкий по загрузкам»
|
||||
(`<проект>-api-uploads`, `UPLOADS_ENV` в `run_failures.py`: 1 место,
|
||||
1 в очереди, ожидание 1 с, срок тела 3 с), тестам —
|
||||
`FAULT_UPLOADS_BASE_URL` (фикстура `uploads_api`, срок клиента 30 с)
|
||||
и `FAULT_UPLOADS_ENV`; тесты сверяют, что стенд запущен с этим
|
||||
окружением (`assert_uploads_stand`). Место держит загрузка A
|
||||
(`held_slot`): генератор тела отдаёт половину и ждёт
|
||||
`threading.Event`; A отпускается до истечения её срока тела (3 с:
|
||||
в `test_upload_slots_busy` A держит место ~1,3–1,5 с, при 2 с запас
|
||||
был ~0,5 с — verify, S5);
|
||||
- тесты (`fault`): `test_upload_slots_busy` (B ждёт, C сразу 429 < 0,5
|
||||
с, B — 429 не раньше 1 с, `Retry-After` ≥ 1; из трёх загрузок новая
|
||||
строка и объект — только у A), `test_rejections_before_queue` (при
|
||||
полной очереди 404 постороннему, 413 по `Content-Length` 30 MiB и 415
|
||||
по `Content-Type` — быстрее срока ожидания и раньше 429 ожидавшей),
|
||||
`test_upload_waits_for_slot` (B ждёт и получает 201, `B.created_at >
|
||||
A.updated_at` — сценарий `storage-consistency`),
|
||||
`test_slot_released_after_failures` (413 по счётчику, 415 по
|
||||
содержимому, 400 по сроку тела, обрыв, 503 при остановленном S3 —
|
||||
после каждого `sample.png` получает 201 быстрее срока ожидания),
|
||||
`test_slow_body` (тело частями дольше срока — 400 «Upload body was
|
||||
not received in time», ни строки, ни объекта; мелкими частями в
|
||||
срок — 201 с тем же SHA-256);
|
||||
- красный прогон на `f894040`: упали все пять — у прежнего кода нет ни
|
||||
мест, ни срока тела (`evidence/tests/failure-checks.md`);
|
||||
- сценарии памяти «Одна копия тела при записи в S3» и «Память не
|
||||
растёт с числом загрузок» — исключения сверки: `make bench_uploads` →
|
||||
`evidence/uploads/baseline/summary.md` (`bench.md`, профиль
|
||||
`uploads`);
|
||||
- с change `track2-reconciler` (design, решение 11) — сверка bucket и
|
||||
БД, тоже проверки отказов, в конце `test_failures.py` (их тесты
|
||||
оставляют вложения, помеченные потерянными, — `ready` без объекта;
|
||||
прежние тесты таких не ждут, `ready_without_object`):
|
||||
- hook: `put-object <ключ>` (тело — stdin фикстуры `stand(...,
|
||||
stdin=байты)`; `docker exec -i <проект>-api python -c …` — botocore
|
||||
образа ключами API из окружения контейнера, ключи в hook не
|
||||
попадают), `delete-object <ключ>` (`weed shell fs.rm`, ошибка — по
|
||||
выводу), оба — только под `<FAULT_DATABASE>/attachments/` и символы
|
||||
`[A-Za-z0-9._/-]`; `delete-row`, `set-size`, `age-row` (сдвиг
|
||||
`created_at` и `updated_at` вместе — CHECK и непомеченность `pending`
|
||||
сохраняются), `set-key <id> <ключ>` (только `object_key` строки,
|
||||
ключ под `<FAULT_DATABASE>/`, в том числе вне `attachments/`; bucket
|
||||
не трогается), `lost-ids`; `fail-attachments mark <filename>` — свой
|
||||
триггер `BEFORE UPDATE OF lost_at` (08006), `clear-fail-attachments`
|
||||
снимает и его; `reconcile dry-run|apply [<предел>]` — `docker compose
|
||||
run --rm --no-deps -T cleaner reconcile …`, записи процесса и строка
|
||||
`exit_code=<n>`, код hook — 0; `stop|start cleaner` (`start` —
|
||||
`docker start` контейнера: `compose start` проверял бы зависимость
|
||||
`migrate`, а её одноразового контейнера нет); `run-cleaner
|
||||
<секунд>` — `<проект>-cleaner-scheduled` с
|
||||
`RECONCILER__INTERVAL_SECONDS=1`, затем `docker stop`, журнал и `rm`
|
||||
(`run_failures.py` убирает его вместе с API);
|
||||
- уборщик стенда — без плановой сверки (`RECONCILER__INTERVAL_SECONDS:
|
||||
"0"` в `failures.compose.yml`): иначе она исправляла бы внесённое до
|
||||
проверки; `run_failures.py` печатает интервал сверки в строке `start
|
||||
cleaner`;
|
||||
- тесты: `test_reconcile_finds_and_fixes` (уборщик стоит, A в сообщении
|
||||
без объекта, B без строки, C с другим размером, O мимо API, P —
|
||||
`commit`; после G + 1 dry-run — свои классы, код 3, ничего не
|
||||
изменилось, A — 500; apply — O и B удалены, P убрана, A и C помечены,
|
||||
A — 404, метаданные — 200; повтор — своих нет), `…_keeps_fresh_used_
|
||||
and_unknown`, `…_restored_original`, `…_change_limit`,
|
||||
`…_object_storage_stopped`, `…_interrupted_by_database`,
|
||||
`…_under_load` (4 потока ~G + 15 с загрузок PNG ~100 KiB и отправок,
|
||||
apply раз в 3 с; все 201 скачиваются с тем же SHA-256, новые пометки
|
||||
— только внесённые), `test_scheduled_reconcile`; по замечаниям
|
||||
verify — `test_reconcile_keeps_referenced_objects` (X с другим ключом,
|
||||
Y ссылается на `<Z>/original` без строки Z: три объекта — чужие и на
|
||||
месте, X помечено), `test_reconcile_limit_keeps_cleanup` (отказ по
|
||||
пределу, зависшая загрузка всё равно убрана) и
|
||||
`test_reconcile_foreign_key_untouched` (`set-key` на
|
||||
`<база>/elsewhere/<id>` у готовой строки и зависшей загрузки: чужие, ни
|
||||
пометки, ни уборки). Записи
|
||||
фильтруются по своим `id` и ключам, код выхода сверяется с записями
|
||||
того же прохода (`Reconcile.assert_code_matches`). Объекты без строки
|
||||
ждут G + 1 с (`LastModified` ставит S3), строки состаривает
|
||||
`age-row`; у состаренных и с изменённым размером метаданные
|
||||
сравниваются без полей, которые изменил сам hook;
|
||||
- красный прогон на `c13df14` (код до change): упали все восемь —
|
||||
команды `reconcile` нет (argparse, код 2), колонки `lost_at` нет
|
||||
(`lost-ids` — ошибка psql), плановой сверки нет
|
||||
(`evidence/tests/failure-checks.md`). Тесты по замечаниям verify: на
|
||||
`a6071da` `…_foreign_key_untouched` красный (готовая строка —
|
||||
`missing_object` после HEAD чужого префикса, зависшая — `stale_pending`),
|
||||
два теста W1 зелёные (ветки были верны) и красные на временных
|
||||
регрессиях — `_recheck_orphan` без проверки ссылок и уборка зависших
|
||||
под пределом (design, «Уточнения apply», п. 22);
|
||||
- с change `fix-upload-put-flake` (design, решение 3) — простой S3 после
|
||||
скачиваний, тоже проверка отказов:
|
||||
- четвёртый API стенда отказов — «с коротким сроком S3»
|
||||
(`<проект>-api-s3`, `S3_ENV` в `run_failures.py`:
|
||||
`S3__TIMEOUT_SECONDS=1`), тестам — `FAULT_S3_BASE_URL` (фикстура
|
||||
`s3_api`, срок клиента 30 с) и `FAULT_S3_ENV`; тест сверяет стенд
|
||||
(`assert_s3_stand`). Других тестов на нём нет: пул S3 процесса — только
|
||||
от этого теста. Короткий срок нужен, чтобы простой дольше срока вызова
|
||||
длился 1,5 с, а не 6;
|
||||
- `api_client.py`: `attachment_content_slowly` — скачивание потоком с
|
||||
паузой после каждого блока 64 KiB, ответ с байтами в `content` (его
|
||||
проверяет `assert_content`);
|
||||
- `test_upload_after_idle_s3` («Загрузка после простоя S3»): PNG из шума
|
||||
~4 MiB загружен один раз; до 8 раундов — 10 одновременных медленных
|
||||
скачиваний (барьер, своё соединение, 2 мс на блок), простой
|
||||
`S3__TIMEOUT_SECONDS + 0,5` с, 12 загрузок `sample.png` по одной,
|
||||
каждая 201; сообщение падения — раунд, загрузка и ответ. Тест
|
||||
вероятностный внутри раунда: до правки соединение портится с p ≈
|
||||
0,28, промах восьми раундов ≈ 4e-12 (докстринг);
|
||||
- красный прогон на `4cfaab0` (тест без правки клиента): `make
|
||||
failure_checks FAULT_ARGS='-k idle_s3'` три раза — каждый 1 failed в
|
||||
первом раунде (загрузки 4, 8, 3: 503 `unavailable`, в журнале API —
|
||||
`put_object` `ReadTimeoutError` за 1 мс); после правки — 1 passed,
|
||||
~16 с (`evidence/tests/failure-checks.md`);
|
||||
- с change `track2-reconcile-cost` (design, решение 14) — стоимость
|
||||
сверки, тоже проверки отказов, в конце `test_failures.py`:
|
||||
- hook: `reconcile dry-run|apply [<предел>] [--strategy batch|head]
|
||||
[--deep] [--max-objects-per-second R]` — каждый аргумент по списку
|
||||
(`reconcile_options`: стратегия из двух, R — неотрицательное число,
|
||||
повтор флага — отказ), иначе код 2 hook; команде передаются как есть.
|
||||
`run_reconcile(stand, mode, limit, options=…)` в тестах;
|
||||
- тесты: `test_reconcile_head_strategy_same_findings` (расхождения как в
|
||||
`…_finds_and_fixes`, уборщик стоит; dry-run `batch` и `head` — свои
|
||||
классы и ключи, весь отчёт, `found`, `listed_objects`, `checked_rows` и
|
||||
коды равны, у `head` больше HEAD и сеансов; затем apply — стенд без
|
||||
внесённого), `test_reconcile_deep_checksum` (A в сообщении
|
||||
перезаписано другими байтами того же размера, `age-row`, G + 1:
|
||||
поверхностная A не называет, `--deep` — `checksum_mismatch`,
|
||||
`read_bytes`, код 3, ничего не изменилось, SHA-256 обоих тел в журнале
|
||||
нет; `--deep --apply` — пометка, 404 / 200),
|
||||
`test_reconcile_restore_needs_same_bytes` (помечено → другие байты
|
||||
того же размера, G + 1: apply пометку не снимает, 404 → те же байты,
|
||||
G + 1: снята, 200 с тем же SHA-256), `test_reconcile_rate_limit`
|
||||
(восемь загрузок и одна потеря, уборщик стоит; dry-run с пределом 0 и
|
||||
с R = max(5, ⌈объектов / 4⌉): `duration_ms ≥ 1000 × storage_objects /
|
||||
R × 0,95`, без предела короче, находки и коды равны),
|
||||
`test_reconcile_limit_stops_rechecks` (6 потерь, apply с пределом 2:
|
||||
код 3, `changes` = 3, `unchecked` ≥ 3, ни одной пометки; dry-run
|
||||
называет все шесть, `unchecked` 0; apply 100 — помечены). Байты
|
||||
«того же размера» — `same_size_bytes(data, seed=…)` от зерна теста;
|
||||
по замечаниям verify — `test_reconcile_row_with_other_id_key` (W2: Y1
|
||||
и Y2 ссылаются на `<Z1>/original` другого размера и `<Z2>/original`
|
||||
тех же размера с другими байтами; dry-run `--deep` обеими стратегиями
|
||||
— Y1 `size_mismatch`, Y2 `checksum_mismatch`, четыре объекта чужие,
|
||||
без `--deep` — только Y1; `--deep --apply` — обе помечены, объекты на
|
||||
месте; записи сравниваются тройкой «класс, ключ, `id`»,
|
||||
`own_findings`) и `test_reconcile_fresh_overwrite_untouched` (S1:
|
||||
объекты двух состаренных вложений перезаписаны только что — другим
|
||||
размером и другими байтами; `--deep --apply` и `--deep --strategy
|
||||
head` в пределах grace — ни находок, ни пометок, `fresh_objects` ≥ 2;
|
||||
после G + 1 — `size_mismatch` и `checksum_mismatch`; исходные байты
|
||||
возвращаются в `finally`);
|
||||
- красный прогон на `7f4e626` (тесты и hook из рабочего дерева): упали
|
||||
все пять — новые аргументы — ошибка argparse (код 2; у `head` пустой
|
||||
отчёт, у предела скорости нет итога), у глубокой нет поля `deep`,
|
||||
пометку снимал другой объект того же размера, `changes` 7 вместо 3
|
||||
(`evidence/tests/failure-checks.md`). Тесты verify — на `16f2cde`:
|
||||
`…_row_with_other_id_key` красный (`batch` не назвал Y1 и Y2),
|
||||
`…_fresh_overwrite_untouched` красный (объект другого размера,
|
||||
перезаписанный только что, помечен); W1 тестом отказов не
|
||||
проверяется — hook не шлёт сигнал посреди прохода, это `driver.py
|
||||
reconcile-signal --pace --apply`;
|
||||
- исключения сверки: «Принявшая реплика остановлена» — `driver.py
|
||||
attachment-failover` → `evidence/attachments/failover.md`; «Байты не в
|
||||
БД и не на диске API» — `driver.py attachment-storage` →
|
||||
`evidence/attachments/storage.md`; «Рестарт стенда» — `make
|
||||
test-persistence` (с `LAB=4` публичная проверка скачивает оригинал
|
||||
после hook) → `evidence/replicas/test-persistence.md`.
|
||||
|
||||
Лаба 5 добавляет (design change `async-attachments`, решение 15):
|
||||
|
||||
- `api_client.py`: `upload` — 202 и снимок `queued` (`assert_accepted`),
|
||||
`wait_attachment(actor, id, status=…, timeout=60)` — опрос раз в 0,2 с,
|
||||
падение с последним состоянием, `upload_ready` — загрузка и ожидание.
|
||||
Тест, которому нужны байты, ждёт `ready`, а не считает его готовым после 202;
|
||||
форма ответа 202 проверяется до ожидания. `contract.py`:
|
||||
`assert_variant_content` (заголовки, размер и SHA-256 варианта). `images.py`:
|
||||
`jpeg_precision_12`, `jpeg_halves(orientation)`, `png_half_transparent`,
|
||||
`png_palette_transparent`, `png_rgba_large`;
|
||||
- `test_attachment_processing.py` — thumbnail, варианты, `failed` по HTTP на
|
||||
любом стенде с worker;
|
||||
- hook — ещё действия брокера и worker, `worker-state`, `queue-state`,
|
||||
`peek-job`, `publish-job`, `delete-queue`, `job`, `staging-ids`,
|
||||
`variant-object-count`, режимы `fail-attachments` на `queued`, а `ready-fail`,
|
||||
`ready-stall` — на фиксацию worker; ключи и пароль брокера hook не получает:
|
||||
`peek-job` и `publish-job` — Python в контейнере API его настройками;
|
||||
- стенд отказов: `rabbitmq` без порта, worker с `restart: "no"`, 4 попытки,
|
||||
пауза 5 с, срок 10 с, graceful 2 с (`FAULT_WORKER_*`), журнал worker при
|
||||
падении; `make test_isolated` — ещё контейнер `<проект>-test-worker` и уборка
|
||||
очереди `test_<db>.attachment.process.v1`. Полный прогон — 99 проверок, pytest
|
||||
~1300 с, вся команда ~22 мин. Описание лабы 4 выше — история: `upload` там
|
||||
отвечал 201, режим hook `ready` стал `queued`, тесты `test_ready_*` — `test_queued_*`.
|
||||
|
||||
С change `pipeline-reliability` (design, решения 14–15):
|
||||
|
||||
- `contract.py`: `assert_variant_image` (настоящий JPEG или WebP того размера);
|
||||
`images.py`: `png_stripes`, `png_solid`, `jpeg_with_metadata`, `jpeg_scan_bomb`
|
||||
(прогрессивный 8000 × 5000, самый маленький AC-скан повторён до 10 MiB);
|
||||
`test_failures.py`: `assert_variants` вместо `assert_one_thumbnail`;
|
||||
- hook: `stop|start|kill|pause|unpause relay`, `freeze worker` (`docker kill -s STOP`:
|
||||
контейнер `running`, поэтому KILL проходит), `pause|unpause worker`, `run-worker K=V…`,
|
||||
`run-relay K=V…`, `stop-extra`, `extra-log`, `kill-extra`, `pause-extra`,
|
||||
`unpause-extra`, `relay-log`, `relay-state`, `cleaner-log`, `kill-render`, `render-env`,
|
||||
`render-count`, `wait-commit-stall`, `object-sha256`, `broker-memory-limit`, режимы
|
||||
`ready-commit-stall`, `relay-stall`, `set-sha256`, `set-staging-key`,
|
||||
`set-next-attempt`, `expire-lease`, `attachment-row`, `attachment-free` (`FOR SHARE
|
||||
SKIP LOCKED`: держит ли строку чужая транзакция), `delete-variant`,
|
||||
`cancel-to-pending`, `replay`, `replays`, `reconcile … --staging-retention S --grace
|
||||
S`; `run-cleaner` ждёт конец первого прохода, а не весь срок; `peek-job`
|
||||
и `publish-job` — одноразовым контейнером relay; `run-worker-second` — третий
|
||||
worker рядом с замороженным первым (`test_hung_worker_lease_fencing`), `extra-log`,
|
||||
`pause-extra`, `unpause-extra` принимают `worker-second`;
|
||||
- окна сбоя — без точек в коде: после COMMIT до publish — relay убит; после confirm до
|
||||
отметки — `relay-stall`, `kill relay`; после записи S3 до COMMIT — `ready-stall`,
|
||||
`kill worker`; после COMMIT до ack — `ready-commit-stall`, `wait-commit-stall`, `freeze`,
|
||||
`kill`. Зависший worker: worker со сроками больше времени теста, иначе при
|
||||
разморозке его прервал бы таймер, а не fencing; аренду делает истекшей `expire-lease`.
|
||||
Номер попытки решает, только пока вторая жива: `test_hung_worker_lease_fencing`
|
||||
размораживает первую при замороженной второй (та взята и ждёт S3, блокировки строки
|
||||
нет); если вторая уже дала итог (`test_hung_worker_thawed_after_ready`), решает `state`;
|
||||
- `test_pixel_limit_png_modes` — обычный набор: `images.png_at_pixel_limit` даёт 8000 × 5000
|
||||
любого типа PNG; типы, которые переводятся в другой режим, не должны держать исходник на
|
||||
время масштаба;
|
||||
- стенд отказов: `relay` (`restart: "no"`, опрос 0,2 с, порог потерянного 5 с), worker —
|
||||
4 попытки, пауза 4–16 с, срок 10 с, запас аренды 2 с, процесс обработки 8 с / 3 с CPU,
|
||||
остановка 2 с; уборщик — срок хранения 60 с; `FAULT_RELAY_*`, новые `FAULT_WORKER_*`,
|
||||
`FAULT_CLEANER_STAGING_RETENTION_S`, журнал relay при падении, уборка
|
||||
`<проект>-worker-extra`, `<проект>-relay-extra`; `make test_isolated` — ещё контейнер
|
||||
`<проект>-test-relay`. После KILL новая попытка ждёт аренду 12 с. Время полного
|
||||
прогона — design change `pipeline-reliability`, «Уточнения apply».
|
||||
|
||||
С change `track1-queue-overload` (design, решение 13):
|
||||
|
||||
- пятый API стенда отказов — «узкий по заданиям» (`<проект>-api-backlog`, `BACKLOG_ENV`
|
||||
в `run_failures.py`: `UPLOADS__MAX_UNFINISHED_JOBS=3`), тестам — `FAULT_BACKLOG_BASE_URL`
|
||||
(фикстура `backlog_api`, срок клиента 30 с) и `FAULT_BACKLOG_ENV`, сверка —
|
||||
`assert_backlog_stand`; без адреса `pytest -m fault` останавливается до первого теста.
|
||||
У четырёх прежних — `UPLOADS__MAX_UNFINISHED_JOBS=0`: их проверки копят задания при
|
||||
остановленном worker, и предел отклонял бы чужие загрузки;
|
||||
- hook: `unfinished-jobs` (число заданий `queued` и `processing`, полный счёт, без обрыва),
|
||||
`backlog-api-log` (журнал пятого API); помощник `wait_no_unfinished` — перед проверкой
|
||||
предела стенд должен разобрать чужой бэклог, до 120 с;
|
||||
- тесты: `test_backlog_limit` («Предел достигнут», «Порядок проверок у предела»,
|
||||
«Остальной API у предела», «Загрузки снова принимаются», запись «Started API» и «Rejected
|
||||
attachment» по журналу), `test_backlog_ignores_finished`,
|
||||
`test_backlog_counts_waiting_retry` (relay стоит, срок следующей попытки отодвинут
|
||||
`set-next-attempt`), `test_backlog_without_broker`, `test_backlog_overshoot_bounded` (40
|
||||
клиентов за барьером, принято от K до K + 20), `test_backlog_off` (обычный API без
|
||||
предела);
|
||||
- девять сценариев `queue-overload` с открытой нагрузкой и счётчиками — исключения сверки:
|
||||
`make bench_queue QUEUE_LABEL=baseline4` → `evidence/queue/baseline4/summary.md`.
|
||||
|
||||
Проверки отказов реплик (остановка, 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 и S3
|
||||
стенда (ключи кэша и объектов разделены именем базы), публичный smoke
|
||||
и весь набор против отдельного контейнера, затем уборка при любом
|
||||
исходе. С лабы 4 уборка удаляет и объекты под префиксом `test_<db>/`
|
||||
bucket — в начале (хвост прошлого прогона) и в конце: `docker compose
|
||||
exec -T s3` + `weed shell` `fs.rm -r /buckets/<bucket>/test_<db>`
|
||||
(отсутствие префикса — не ошибка). `weed shell` выходит с кодом 0 и
|
||||
при ошибке команды, поэтому успех проверяется отдельно: нет строк
|
||||
`rm:` с ошибкой и `fs.ls` префикса пуст; иначе в начале — код 1 до
|
||||
прогона, в уборке — «cleanup failed» и код 1. Префикс собирается только из
|
||||
имени, прошедшего `^test_[a-z0-9_]+$`, и проверенного имени bucket,
|
||||
иначе код 2 до любых действий: ошибка не может удалить рабочий
|
||||
префикс. `KEEP_TEST_DB=1` оставляет базу и префикс и печатает оба.
|
||||
Его вывод — 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 и с лабы 4
|
||||
S3 со своими volumes, их порты не публикуются; bootstrap S3 —
|
||||
отдельным `up --no-deps --exit-code-from s3-bootstrap` после
|
||||
миграций; у `s3` `stop_grace_period: 2s` — здесь проверяется отказ,
|
||||
а не плавная остановка (~15 с), и `stop` не тянет время набора;
|
||||
healthcheck PostgreSQL проверяет
|
||||
служебную базу `postgres` (иначе каждая проверка — сессия в базе
|
||||
приложения и шум счётчика `db-sessions`);
|
||||
- пять API на свободных портах `127.0.0.1` (пятый — раздел change
|
||||
`track1-queue-overload` выше): обычный (`BASE_URL`; с
|
||||
лабы 4 в окружении `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` —
|
||||
`LIMITS_ENV`, тест получает их в `FAULT_LIMITS_ENV` и грузит
|
||||
`sample.png`: лимиты — константы, спек `service-configuration`),
|
||||
«тесный» (`FAULT_TIGHT_BASE_URL`: сроки сессии и ключа
|
||||
идемпотентности 2 с, пул 1, короткие таймауты), с change
|
||||
`upload-memory` «узкий по загрузкам» (`FAULT_UPLOADS_BASE_URL`,
|
||||
`UPLOADS_ENV` → `FAULT_UPLOADS_ENV`: 1 место, 1 в очереди, ожидание
|
||||
1 с, срок тела 3 с), с change `fix-upload-put-flake` — «с коротким
|
||||
сроком S3» (`FAULT_S3_BASE_URL`, `S3_ENV` → `FAULT_S3_ENV`: срок
|
||||
вызова S3 1 с); без любого из четырёх адресов `pytest -m fault`
|
||||
останавливается до первого теста; при падении печатаются журналы
|
||||
всех четырёх;
|
||||
- уборщик (с лабы 4): после bootstrap — `up -d --no-deps cleaner` с
|
||||
grace 20 с и интервалом 1 с из `failures.compose.yml`
|
||||
(`CLEANER__*`, `restart: "no"`: падение не прячется за
|
||||
перезапуском); значения `run_failures.py` берёт из конфигурации
|
||||
compose и передаёт тестам (`FAULT_CLEANER_GRACE_S`,
|
||||
`FAULT_CLEANER_INTERVAL_S`) и строкой `start cleaner: grace … s,
|
||||
interval … s` в вывод. При падении печатается и журнал уборщика.
|
||||
С change `track2-reconciler` — без плановой сверки
|
||||
(`RECONCILER__INTERVAL_SECONDS: "0"`, строка `start cleaner` называет
|
||||
и её интервал), а `<проект>-cleaner-scheduled` hook `run-cleaner`
|
||||
убирается вместе с API. Прогон — ~15 мин (с правками по verify
|
||||
`track2-reconcile-cost` — 56 проверок, pytest 877 с, вся команда 898 с
|
||||
на шумном хосте: два теста verify ~1,5 мин; до них — 54 проверки,
|
||||
pytest 712 с: пять тестов
|
||||
стоимости сверки ~3,5 мин, из них ожидание grace — 4 × 21 с; с change
|
||||
`fix-upload-put-flake` — 49 проверок, pytest ~550–570 с: тест простоя S3
|
||||
~17 с, остальное — разброс хоста; до него 48 проверок, pytest ~535 с;
|
||||
до правок по verify `track2-reconciler` — 45 и ~460 с;
|
||||
до `track2-reconciler` — 37 и ~255 с, до `upload-memory` — 32 и
|
||||
~220 с, до `upload-consistency` ~70 с);
|
||||
- `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` сервиса `postgres`, `valkey` или `s3` (у `s3`
|
||||
проба после `unpause` — та же команда, что healthcheck: master,
|
||||
зарегистрированный том, filer и шлюз;
|
||||
`test_readiness_without_object_storage[stop|pause]` — спек `health`,
|
||||
«Хранилище объектов недоступно»), `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 приняла, с
|
||||
сессией самого вызова; тест «Соединения пула не переоткрываются»), с
|
||||
лабы 4 — действия вложений и API выше (`attachment-ids`,
|
||||
`last-pending`, `object-ids`, `fail-attachments`,
|
||||
`clear-fail-attachments`, `kill-api`, `start-api`).
|
||||
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` не состоит ни в одном чате
|
||||
фикстур.
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
paths:
|
||||
- "src/worker/**"
|
||||
- "src/relay/**"
|
||||
- "src/infra/render/**"
|
||||
- "src/core/services/attachment_processing.py"
|
||||
- "src/core/services/attachment_relay.py"
|
||||
- "src/core/services/attachment_replay.py"
|
||||
- "src/utils/image_variants.py"
|
||||
---
|
||||
|
||||
# Worker, relay и процесс обработки (с лабы 5)
|
||||
|
||||
Спеки `attachment-processing`, `message-broker`, `job-outbox`; решения — design
|
||||
change `async-attachments` (2, 6–8) и `pipeline-reliability` (1–9, 19). Здесь то,
|
||||
что легко нарушить.
|
||||
|
||||
- **Worker:** `python -m src.worker` → `src/worker/__main__.py`
|
||||
(`early_stop.install("worker")`, «Invalid worker settings» и код 2,
|
||||
`os._exit` в конце) → `src/worker/main.py`. Свои engine, клиент S3 с ключами
|
||||
worker и потребитель брокера; издателя нет, глобалы процесса API не
|
||||
импортируются. Сервис собирается на доставку со своей `SqlAlchemyUnitOfWork`
|
||||
(change `unit-of-work`, решение 3): доставки идут одновременно, а единица работы
|
||||
держит открытую сессию; `storage`, `renderer` и `stop` общие. Сервис compose — на образе API, без портов и healthcheck, не
|
||||
реплика: вне `rolling-update.sh` и `restart.sh`. В консоли — `make run_worker`.
|
||||
- **Relay:** `python -m src.relay` → `src/relay/__main__.py` → `src/relay/main.py`
|
||||
→ `AttachmentRelayService`. Свой engine (пул 1) и `JobPublisher`; S3 и Pillow
|
||||
нет. Не в репликах (издатели и пароль у всех), не в worker (остановка worker на
|
||||
защите остановила бы публикацию), не в уборщике (сверка держала бы цикл). В
|
||||
консоли — `make run_relay`.
|
||||
- **Проход relay** — три шага, сигнал проверяется между ними: истёкшие аренды
|
||||
(`processing` → `queued`, причина `lease_expired`, задание и вложение одной
|
||||
транзакцией); потерянные (есть `queued` с `published_at` старше `[relay]
|
||||
republish_after_seconds` и ноль готовых сообщений — отметка снимается; не ноль —
|
||||
ничего: длинная очередь не обрастает копиями); публикация (`room =
|
||||
max_published_backlog - count_published()`, `FOR UPDATE SKIP LOCKED`, порядок —
|
||||
`COALESCE(next_attempt_at, created_at), id`, `publish_many`, отметка
|
||||
подтверждённых, COMMIT). Публикация внутри транзакции — осознанное исключение:
|
||||
блокировка строки и есть признак «это задание публикует другой relay», срок 2 с
|
||||
< шага 6 с < простоя транзакции 10 с. Worker, получивший сообщение раньше
|
||||
COMMIT, ждёт блокировку и видит отметку. Статусы в выборках — константой
|
||||
(`literal_execute`), иначе общий план — Seq Scan.
|
||||
- **Pillow** импортирует только `src/utils/image_variants.py`, его — только
|
||||
`src/worker/render.py`, отдельный процесс на задание. Ни реплики API, ни процесс
|
||||
worker декодер в память не загружают (проверка — `/proc/1/maps`).
|
||||
- **Процесс обработки** — `ImageRenderer` (`src/infra/render/client.py`):
|
||||
`python -m src.worker.render`, окружение только `PATH`,
|
||||
`PYTHONDONTWRITEBYTECODE`, `PYTHONUNBUFFERED`, `MALLOC_MMAP_THRESHOLD_`: секретов в
|
||||
нём нет. Лимиты — первыми строками, до импорта Pillow: `RLIMIT_AS`,
|
||||
`RLIMIT_CPU` (жёсткий на секунду больше), `RLIMIT_CORE = 0`. Коды 3 / 4 / 5 —
|
||||
не декодируется, память, пиксели; −SIGXCPU — CPU (всё постоянные, `ImageRejected`);
|
||||
срок родителя — `TimeoutError`, −SIGKILL и иное — `RenderInterrupted` (временные).
|
||||
`finally` клиента убивает процесс и ждёт его: отмена попытки процесс не оставит.
|
||||
Пик — `VmHWM`, не `ru_maxrss`: тот наследует пик родителя через fork. На macOS
|
||||
`setrlimit(RLIMIT_AS)` — `ValueError`: процесс продолжает, вывод отмечает это.
|
||||
- **Claim** (`_claim`, таблица решения 3): сообщение — подсказка, истина в строке
|
||||
задания. `succeeded`, `failed`, чужое, `queued` раньше срока, `processing` с живой
|
||||
арендой — ACK без записи и без новой попытки; `redelivered` только в журнал: брокер
|
||||
ставит его и после `nack`, живого от потерянного он не отличает. Истёкшая аренда
|
||||
и `queued` — взять, если бюджет не исчерпан (`attempt - attempt_base >=
|
||||
max_attempts` — `failed` `retry_exhausted`). Взятие: `attempt + 1`,
|
||||
`lease_expires_at = now + job_timeout + lease_margin`.
|
||||
- **Fencing:** `ready`, `failed` и возврат фиксирует только попытка, номер которой
|
||||
равен текущему у задания в `processing` (`_own_attempt`, условие
|
||||
`return_to_queued`), иначе `Skipped job message`, `superseded`, ACK. Поэтому `attempt`
|
||||
монотонен, а бюджет после replay — `attempt_base`.
|
||||
- **Аренда без пульса:** шаги попытки под `asyncio.timeout(job_timeout)`, процесс
|
||||
убивается, поэтому попытка не живёт дольше срока. Цена — после KILL следующая
|
||||
попытка ждёт истечения аренды (до 70 с).
|
||||
- **Ack — только после устойчивого эффекта:** `ready` или `failed` зафиксированы,
|
||||
задание возвращено в `queued` со сроком либо записывать нечего. Подтверждает
|
||||
`main.py` по `JobOutcome`. `REQUEUE` — только отказ PostgreSQL: пауза
|
||||
`reconnect_seconds`, попытка не считается, если не начата.
|
||||
- **Повтор:** временная ошибка — `queued`, `next_attempt_at = now + uniform(d/2, d)`,
|
||||
`d = min(max, base × 2^(N−1))`, `N` от последнего replay (`retry_delay`), ACK.
|
||||
Следующее сообщение публикует relay, пауза места конкуренции не занимает.
|
||||
- **Prefetch и конкуренция:** `set_qos(prefetch)`, каждая доставка — задача,
|
||||
`asyncio.Semaphore(concurrency)` вокруг `service.handle`: сообщение сверх
|
||||
конкуренции ждёт без взятия и аренды, после сигнала попытка не начинается.
|
||||
- **Подбор конкуренции и prefetch** (design change `track1-queue-overload`, решения
|
||||
5, 12): `concurrency ≤ min(CPU + ожидание, (лимит − база) / пик процесса)`,
|
||||
`prefetch = concurrency`. Сверх CPU конкуренция не ускоряет, а удлиняет процесс и
|
||||
умножает память; больше prefetch только прячет очередь от брокера и второго worker.
|
||||
Два ограничения сверху на `prefetch / потолок`: 30 мин (`consumer_timeout`
|
||||
брокера: дольше — закрытие канала) и `[relay] republish_after_seconds` 300 с (иначе
|
||||
копии потерянных). Конкуренция, которая не помещается в лимит памяти контейнера, —
|
||||
не только повторы `render_killed`: ядро может завершить и процесс 1, контейнер
|
||||
перезапускается, задания возвращаются по аренде (до 70 с). Защита — конкуренция, а
|
||||
не `oom_score_adj`. Числа и проверка правила — метка `evidence/queue/baseline4/`.
|
||||
- **Варианты:** одно декодирование, `fit_size` (округление вниз, не
|
||||
`Image.thumbnail`). `draft` у JPEG — под самый большой нужный размер. Основа 1280 —
|
||||
для optimized и thumbnail; crop — из основы, если её короткая сторона ≥ 256, иначе
|
||||
из декодированного (у 5000 × 10 основа 1280 × 2). Transpose на малых изображениях.
|
||||
Thumbnail и crop — JPEG `quality=85`, альфа на белый; optimized — WebP `quality=80`,
|
||||
`method=4`, прозрачность сохраняется. Метаданные в `save` не передаются: EXIF,
|
||||
XMP и ICC не пишутся, ориентация применена к пикселям. `FLIP_LEFT_RIGHT` равен 0:
|
||||
результат `.get` сравнивать с `None`.
|
||||
- **Replay:** `AttachmentReplayService`, `make replay` (`python -m src.relay replay`),
|
||||
только PostgreSQL. Транзакция: `lock_job`, `lock_attachment` (`FOR NO KEY UPDATE`),
|
||||
проверки (`not_found`, `already_ready`, `not_failed`, `source_gone` — отказ без
|
||||
изменений, код 3), `failed → queued`, `attempt_base = attempt`, запись
|
||||
`attachment_job_replays`. Сообщение публикует relay. С `--apply` выбор обязателен
|
||||
(код 2), `--attachment-id` и фильтр по коду вместе нельзя (код 2). HTTP-ручки нет.
|
||||
- **Остановка worker (S5):** `graceful_shutdown_seconds` ≤ 8, отмена задач 0,5,
|
||||
закрытие потребителя 0,5, engine и S3 — одним `gather` под сроком 0,5: 9,5 с < 10 с.
|
||||
Новые клиенты не добавляют срока. Задание, прерванное остановкой, получает
|
||||
следующую попытку по аренде: release на пути отмены ненадёжен.
|
||||
- **Сообщение** — `src/schemas/jobs/attachment.py`, по `contracts/jobs.schema.json`:
|
||||
только id и служебные поля. Ключи, размер, SHA-256 и тип worker берёт из
|
||||
PostgreSQL. Не по схеме — `error` без содержимого, `reject(requeue=False)`.
|
||||
- **Порядок блокировок везде:** задание (`lock_job`), затем вложение; вызовов S3
|
||||
внутри блоков единицы работы у worker нет (тест `put` — `service-tests/unit`).
|
||||
Вложение `ready`, варианты и итог задания — один блок. Вспомогательные методы
|
||||
сервиса работают внутри открытого блока без параметра сессии.
|
||||
- **Ключ эффекта** `(attachment_id, pipeline_version, variant)` — первичный ключ
|
||||
`attachment_variants`; ключ объекта варианта из него следует.
|
||||
- **Журнал:** `request_id` — `job_id` (ставит сервис); `filename`, байтов, тел
|
||||
сообщений и секретов в записях нет (`logging.md`).
|
||||
- **Ограничения** называются в `REPORT.md`: восстановление после KILL по аренде,
|
||||
дубли сообщений, объект, дописанный прежней попыткой теми же байтами, профиль ICC,
|
||||
лимит памяти на macOS, цена процесса на задание, удаление очереди при работающем
|
||||
worker. Изоляция секретов неполная: в окружении процесса обработки их нет, но он
|
||||
идёт под тем же UID, что PID 1 worker, и после эксплойта декодера прочитает
|
||||
`/proc/1/environ` (ключи S3, пароли PostgreSQL и брокера); предложение
|
||||
`PR_SET_DUMPABLE=0` — `QUESTIONS.md`.
|
||||
@@ -0,0 +1,710 @@
|
||||
---
|
||||
name: run-mtusi-messenger
|
||||
description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API; лаба 4 — S3 на SeaweedFS; лаба 5 — RabbitMQ, relay и worker) — на хосте или в 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`, `make s3_check`, check that the S3 bucket is private, run the defense scenario or its failure windows, check the broker, the worker or the relay process, show the pipeline state, 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, с лабы 4 есть S3 (SeaweedFS) для байтов
|
||||
вложений, с лабы 5 — RabbitMQ, relay и worker: загрузка отвечает 202, файл
|
||||
становится `ready` в фоне. Агент управляет им через
|
||||
`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres,
|
||||
накатывает миграции, поднимает Valkey, S3 с bootstrap и брокер (`make
|
||||
upgrade start_cache start_s3 start_broker`),
|
||||
запускает свой экземпляр сервера, worker и relay в фоне, гоняет сценарий по 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` — доказательства исключений сверки
|
||||
покрытия (кэш, хранение паролей и токенов), `s3-check` (`make
|
||||
s3_check`) — приватность bucket вне API, `attachment-failover` и
|
||||
`attachment-storage` — доказательства исключений `attachments`
|
||||
(остановка реплики, принявшей файл; где лежат байты),
|
||||
`upload-consistency` — согласованность БД и S3 (компенсация и уборщик
|
||||
незавершённых загрузок), `reconcile-cycle` и `reconcile-stress` — сверка
|
||||
bucket и БД (расхождения с обеих сторон, dry-run, `--apply`, повтор,
|
||||
возврат оригинала; `--apply` под загрузками), `defense-scenario` и
|
||||
`defense-faults` — сценарий защиты лабы 5 и его шаг 4, `broker-check`,
|
||||
`worker-process`, `relay-process` — брокер и процессы, `pipeline-state` — состояние
|
||||
конвейера, `worker-memory` — память контейнера worker, `freeze-sessions` и `freeze-lb`
|
||||
— заморозка PostgreSQL (раздел «Лаба 5: брокер, relay и worker»). `upload` и
|
||||
`download` — загрузка и скачивание вложения с SHA-256 на любом
|
||||
сервере. `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-lab5`, своя база. Стенд: 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, RABBITMQ_DEFAULT_PASS и секреты S3, печатает только имена) и config.toml, существующие не трогает
|
||||
```
|
||||
|
||||
Нужен запущенный Docker: Postgres, Valkey и S3 живут в compose. Без
|
||||
Postgres сервер стартует, но `/health/ready` отвечает 503; без Valkey
|
||||
всё работает, но мимо кэша (`warning` «Cache is unavailable» в логе);
|
||||
без S3 `/health/ready` — 200, а загрузка и скачивание байтов
|
||||
вложений — 503 (метаданные, сообщения и история работают). S3 нужен
|
||||
только путям вложений. Без брокера, relay и worker `/health/ready` — 200, загрузка —
|
||||
202 (брокера в пути запроса нет, задание ждёт в PostgreSQL), вложение остаётся
|
||||
`queued`, скачивание — 409.
|
||||
`driver.py start` сам делает `make upgrade start_cache
|
||||
start_s3 start_broker`. В `.env`, созданном до `membership-cache` или `s3-storage`,
|
||||
нет строк Valkey или S3: их переносят из `.env.example` руками, иначе
|
||||
compose падает с `… is empty, copy … lines from .env.example`.
|
||||
|
||||
## 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 start_s3 start_broker, затем API, worker и relay в фоне; ждёт /health/ready, брокер и старт relay до 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, вложение: загрузка fixture 202,
|
||||
# сообщение со ссылкой, опрос до ready, оригинал Бобу (SHA-256),
|
||||
# thumbnail (JPEG 256×160), 404 Еве; 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 upload --token <token> --chat <chat> --file tests/fixtures/sample.png
|
||||
# 202, x-instance-id, снимок queued, SHA-256 файла и «sha256 matches: True»,
|
||||
# затем опрос до ready и итоговые метаданные
|
||||
python3 $D download --token <token> --attachment <id> [--out /tmp/x.png] [--variant thumbnail] [--wait]
|
||||
# 200, Content-Type, размер, SHA-256 полученного (99ea7533… у fixture),
|
||||
# у JPEG и WebP — размеры по байтам; не ready — 409, с --wait — сначала опрос
|
||||
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 start_s3 start_broker`, затем `APP__RUN_MODE=console APP__PORT=<port> uv run python -m src`, `make run_worker` (ключи S3 worker) и `make run_relay` в одной группе процессов; готово — `/health/ready` 200, запись worker «Connected to broker» и запись «Started relay». Журналы — `/tmp/mtusi-worker-<port>.log`, `/tmp/mtusi-relay-<port>.log` |
|
||||
| `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` |
|
||||
| `s3-check` | стенд compose (`make s3_check`), без приложения: спек `object-storage` «Проверка приватности вне API». `docker compose run --rm --no-deps s3-bootstrap check` — права ключа API (PUT/GET/HEAD объекта, 404 отсутствующего; 403 на список, создание и удаление bucket, политику и ACL bucket, публичный ACL объекта), права ключа уборщика (GET/HEAD/DELETE своего проверочного объекта, повторный DELETE и DELETE отсутствующего — 204; список с префиксами `<база>/attachments/` и `<база>/staging/` — 200, с change `track2-reconciler` и `pipeline-reliability`; 403 на запись, список всего bucket, префикса базы и с чужим префиксом, bucket, политику, ACL), временный чужой bucket (403 на всё обоим ключам), аноним изнутри сервера (403); анонимные запросы с хоста (`127.0.0.1:S3_OUT_PORT`) и из сети стенда (одноразовый контейнер образа S3), порты контейнера S3: слушающие сокеты из `netstat -tuln` в контейнере — вне loopback ровно API S3 и gRPC шлюза, а остальные слушающие порты из сети закрыты (`nc -z`); затем `s3-bootstrap cleanup` и `weed shell` — проверочных объектов и bucket не осталось. Строки списка уборщика по префиксам вложений, staging и базы обязательны: нет — код 1. Таблица «где → проверка → ожидаемо → получено» без секретов, код 1 при расхождении (печатает нарушенные). Вывод — `evidence/s3/privacy.md` |
|
||||
| `upload --token T --chat C --file F [--type …] [--filename …]` | загрузка файла сырыми байтами (`urllib`): статус (202), `x-instance-id`, снимок `Attachment`, размер и SHA-256 файла, совпал ли `sha256` ответа, затем опрос метаданных раз в 0,2 с до `ready` или `failed` (до 60 с) и итоговое тело. `--type` по умолчанию — по сигнатуре (PNG, JPEG, иначе `application/octet-stream`), `--filename` — имя файла. Код 2 при статусе ≥ 400, `failed` и сроке ожидания |
|
||||
| `download --token T --attachment A [--out F] [--variant …] [--wait]` | скачивание оригинала или варианта (`thumbnail`, `crop`, `optimized`): статус, `x-instance-id`, `Content-Type`, `Content-Length`, размер и SHA-256 полученного, у JPEG — размеры по SOF, у WebP — по заголовку; `--out` сохраняет байты. Код 2 при статусе ≠ 200 (тело ошибки печатается): не `ready` — 409 `conflict`, так его и показывают; `--wait` — сначала опрос до `ready` |
|
||||
| `defense-scenario` | только стенд с LB: сценарий защиты лабы 5, раздел «Лаба 5: брокер, relay и worker» |
|
||||
| `defense-faults` | только стенд с LB: шаг 4 защиты, окна отказа, тот же раздел |
|
||||
| `broker-check [--require-test-queue]` | стенд compose: брокер, тот же раздел |
|
||||
| `worker-process` | только стенд с LB: процесс worker, тот же раздел |
|
||||
| `relay-process` | только стенд с LB: процесс relay, тот же раздел |
|
||||
| `pipeline-state` | стенд compose, только чтение: JSON о конвейере, тот же раздел |
|
||||
| `worker-memory` | только стенд с LB: память контейнера worker на двух файлах разом, тот же раздел |
|
||||
| `freeze-sessions [--rounds 6] [--settle 15]` | стенд compose: сессии PostgreSQL и журнал пула после заморозки через TCP-прокси пробы, сервер не замораживается, тот же раздел |
|
||||
| `freeze-lb [--rounds 3]` | свой временный проект compose, `mtusi-lab5` — код 2: `docker pause` PostgreSQL и цепочка сроков через LB, тот же раздел |
|
||||
| `attachment-failover [--mode stop\|kill]` | только стенд с LB: спек `attachments` «Принявшая реплика остановлена». Синтетические Алиса, Боб, Ева и чат; загрузка `tests/fixtures/sample.png` через LB — 202 и ожидание `ready` (реплика A — `X-Instance-Id` ответа), сообщение со ссылкой, `scripts/stop-one.sh` с `TARGET_INSTANCE_ID=A` и `STOP_MODE`, Боб скачивает через LB (до 30 попыток), пока не ответит другая реплика: SHA-256 совпадает, метаданные равны метаданным `ready`; Ева — 404 на метаданные и байты. В `finally` — `make replicas`, затем ожидание, пока LB снова видит все реплики `UP`. Печатает `docker compose ps` до и после и таблицу «шаг → ожидаемо → получено → реплика» без токенов. Код 1 при расхождении, без LB (порт консольного процесса драйвера) — код 2. Вывод — `evidence/attachments/failover.md` |
|
||||
| `attachment-storage` | только стенд с LB: спек `attachments` «Байты не в БД и не на диске API» и `data-storage` «Ограничения обработки в схеме». Две загрузки fixture через LB, 202 и ожидание `ready`; psql — колонки `attachments`, `message_attachments`, `attachment_jobs`, `attachment_variants` и `attachment_job_replays` (из `bytea` только 32-байтные `sha256` вложения и варианта), `object_key` = `<база>/attachments/<id>/original` без `filename`, `staging_key` = `<база>/staging/<id>/original` или уже пуст: готовое вложение его теряет на проходе уборщика; `weed shell fs.ls -l` — объект и три варианта в bucket, размер; анонимный GET ключа и каждого варианта с `127.0.0.1:S3_OUT_PORT` — 403; скачивание участником — тот же SHA-256; пробы в откатываемой транзакции — второе задание той же версии, второй вариант того же имени, `error_code` у не `failed`, `attachment_job_replays` с неизвестным заданием: каждая вставка отклонена (SQLSTATE и имя ограничения), после проб одна строка задания и три варианта; `docker diff` каждой реплики и worker — ни одного файла оригинала. Код 1 с названной проверкой, без LB — код 2. Вывод — `evidence/attachments/storage.md` |
|
||||
| `upload-consistency` | только стенд с LB: спеки `attachments` «Порядок записи» и `storage-consistency` (design change `upload-consistency`, решение 11; `async-attachments`, решения 3 и 11). Синтетические Алиса, Боб и чат; вложение R — 202 и `ready`. Шаги: (1) `docker compose pause s3` → загрузка через LB — 503 за ~5 с → `unpause` в `finally`; новая строка `pending` по psql (`id`, статус, возраст, ключ); (2) триггер «перевод в `queued` падает» (SQLSTATE 08006) на рабочей базе только для уникального `filename` прогона → загрузка 503 → строка `pending`, объекта staging уже нет (компенсация), триггер снят (`finally`, и остаток прошлого прогона — в начале); (3) метаданные, байты и сообщение со ссылкой на обе строки — 404; (4) после grace прогона 30 с — `docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once`, его JSON-вывод; тот же проход убирает staging R: `staging_key` пуст, объекта нет, метаданные прежние; (5) psql и `weed shell fs.tree` (файлы `original`, а не каталоги, под `attachments/` и `staging/`) — ни строк, ни объектов обеих загрузок, объектов без строки под префиксом вложений рабочей базы нет; R скачивается с тем же SHA-256. Таблица «проверка → ожидаемо → получено» без токенов и секретов; код 1 при расхождении, без LB — код 2. ~45 с. Вывод — `evidence/attachments/consistency.md` |
|
||||
| `reconcile-cycle` | только стенд с LB: спеки `storage-consistency` (сверка bucket и БД) и `attachments` «Потерянный оригинал» (design change `track2-reconciler`, решение 12). (1) исходный dry-run с grace по умолчанию — расхождений нет, иначе код 2; (2) синтетические Алиса, Боб, чат, вложения A (в сообщении), B, C — 202 и `ready`; (3) объект O без строки и чужой ключ X — `docker exec` реплики (botocore образа её ключами), объект A удалён (`weed shell fs.rm`), строка B с заданием и вариантом удалена и размер C изменён (psql), P — триггер COMMIT перевода в `queued` на уникальный `filename` (503, строка `pending` и объект staging; находка называет ключ staging), S — объект staging без строки, Y — объект staging с ключом другого вида; (4) после grace 30 с dry-run со сроком хранения по умолчанию — S и Y свежие, не находки; dry-run со сроком хранения 30 с: таблица «класс → действие → ключ → `id` → возраст», снимки строк, объектов и пометок до и после совпали; ещё находки — три объекта вариантов B без строки, S — `orphan_staging`, Y — `unknown_object`; (5) байты A — 500; (6) свежий F, `--apply`: O, B, варианты B и S удалены, A, C помечены, P убрана, F не тронут, байты A — 404, метаданные A — 200 и равны ответу загрузки, история отдаёт A; (7) повтор — только чужие X и Y, код 3; оператор удаляет их — код 0; после grace F удалён; (8) A возвращён теми же байтами — «оригинал вернулся», байты 200 с тем же SHA-256, итоговый dry-run — код 0. Таблица «проверка → ожидаемо → получено» без токенов; код 1 при расхождении, без LB — код 2. ~2 мин. Вывод — `evidence/reconcile/cycle.md` |
|
||||
| `reconcile-stress [--seconds S] [--clients N]` | только стенд с LB: «Сверка под нагрузкой». Предусловие — dry-run с grace 20 с без расхождений (иначе код 2); два объекта без строки и два вложения без объекта; N клиентов (4) S секунд (40, больше grace) загружают PNG ~100 KiB из шума и отправляют сообщения, поток сверки — `--apply` с grace 20 с раз в ~3 с, затем ещё один проход. Итог: загрузки по кодам, сообщения, коды проходов, исправления по классам; проверки — внесённые исправлены (объекты удалены, новые пометки — ровно внесённые), каждое 202 дошло до `ready` и скачивается с тем же SHA-256, каждое сообщение отдаёт своё вложение, ни одного прерванного прохода, повтор dry-run — код 0. Проверка корректности, не замер. Вывод — `evidence/reconcile/stress.md` |
|
||||
| `reconcile-signal` | только не рабочий проект compose (выбор — окружением `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`; `mtusi-lab5` — отказ, код 2): спек `graceful-shutdown`, разовый проход сверки, прерванный сигналом, — код 1 (design change `track2-reconciler`, «Уточнения apply», п. 23). Нужны запущенные `s3` и образ уборщика, LB и реплики не нужны. `docker compose pause s3` → `run -d --no-deps --name <проект>-reconcile-signal cleaner reconcile --apply` → через секунду после «Started cleaner» `docker stop` → код контейнера и журнал → `rm`, `unpause s3` в `finally`. Записи процесса (событие, уровень, операция, `interrupted_by`, `exit_code`) и таблица: код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, записей «Fixed» 0, остановка быстрее 10 с; код 1 при расхождении. ~10 с. `--pace` (design change `track2-reconcile-cost`, решение 14): вместо `pause s3` — 8 объектов пробы под `<база>/attachments/pace-signal-*` мимо API (`docker compose run --rm --no-deps -T --entrypoint python api -`: botocore образа ключами API из окружения контейнера), `cleaner reconcile --max-objects-per-second 1` (dry-run), `docker stop` через 2 с после «Started cleaner» — во время паузы предела скорости; ожидание — код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, остановка ≤ 1 с, `listed_objects` итога — 8 (ключи страницы перед паузой, verify W1); объекты пробы удаляются в `finally`. `--pace --apply` (verify W1, ~45 с): объекты пробы — `<база>/attachments/<uuid>/original` без строки, через 19 с (grace прохода 18 с, `-e CLEANER__PENDING_GRACE_SECONDS=18`) `reconcile --apply --max-objects-per-second 1`, `docker stop` через 19,5 с после «Started cleaner» — посреди удалений, в паузе после DELETE; перед уборкой — сколько объектов пробы осталось (HEAD); ожидание — то же и «Fixed» = `fixed.orphan_object` = удалённых > 0. Нужен ещё сервис `api` в конфигурации проекта (реплики не нужны). Вывод — раздел `evidence/reconcile/service.md` |
|
||||
| `s3-idle [--rounds 3] [--downloads 10] [--puts 12] [--size-mib 4] [--pause-ms 0.5]` | только стенд с LB: спеки `object-storage` «Вызов после простоя» и `attachments` «Загрузка после простоя S3» (design change `fix-upload-put-flake`, решение 4). Проба клиента S3 в первой работающей реплике `api`: `docker exec -i <реплика> python -` со скриптом из stdin — код, настройки и ключи образа, ключи в драйвер не попадают; uvloop, если есть. Два варианта по очереди, у каждого свой `ObjectStorage` и пул: `image` (как в образе) и `reference` (прежний `read_timeout` aiohttp = `[s3] timeout_seconds`, подменой `AioConfig` при создании клиента). Раунд: `--downloads` одновременных скачиваний объекта `--size-mib` MiB через `open` / `iter_chunks` с паузой `--pause-ms` после блока 64 KiB, простой `[s3] timeout_seconds + 0,5` с, `--puts` PUT по 128 KiB по одному. Таблица по раундам: `read_timeout` клиента, скачивания с тем же SHA-256, соединения пула со взведённым сроком чтения после скачиваний (`armed`) и с сохранённым исключением после простоя (`broken`) — закрытые поля aiohttp `_conns`, `_read_timeout_handle`, `_exception`, нет их — «n/a», тогда судят только по PUT; PUT прошло и упало, у упавших — цепочка исключений и мс; каждый записанный объект читается обратно (размер и SHA-256). Объекты — под `<база>/.s3-idle-probe/<uuid>/` (сверка этот префикс не читает), удаляются в `finally` отдельным клиентом; затем `weed shell fs.tree` — файлов пробы 0. Код 0 — у `image` ни испорченного соединения, ни упавшего PUT, ни расхождения байтов, все раунды пройдены и файлов не осталось; 1 — иначе (эталон может падать: так видно механизм); 2 — нет реплики или консольный процесс драйвера. Пул API не трогает (отдельный процесс), но на время команды берёт ~100 MiB и CPU реплики — без нагрузки на стенд. ~40 с при 3 раундах и `timeout_seconds` 5. Вывод — `evidence/s3/idle-connection.md` |
|
||||
| `lb-upload-timeouts [--config F] [--image ТЕГ]` | без стенда (рабочий стенд и проекты compose не трогает): спек `load-balancing` «Загрузки через балансировщик» и «Ошибки балансировщика в формате контракта» (design change `upload-memory`, решение 7). `haproxy -c` конфигурации F (по умолчанию `infra/haproxy/haproxy.cfg`) в закреплённом образе LB из `docker-compose.yml`, затем временная сеть `mtusi-lbto-<метка>`: заглушка реплики на образе API (по умолчанию `mtusi-messenger:lab5`, asyncio stdlib) под сетевым именем `api` и HAProxy с F и `API_PORT=8080` на свободном `127.0.0.1`; ожидание `UP` заглушки по `/health/ready` через LB. Пять случаев параллельно, у каждого своё соединение и свой `case` в строке запроса: заглушка молчит 12 с до чтения тела загрузки 10 MiB и после него — 202 от заглушки; 12 с на `GET /api/v1/users/me` — 504 LB через ~10 с; 32 с на пути загрузки — 504 LB через ~30 с; клиент отправил половину тела и молчит — 400 LB через ~30 с (`timeout client`). Ошибки LB — `application/json`, ровно `{"error": {"code", "message", "request_id"}}`, `code` по статусу, `request_id` = `X-Request-Id`. Таблица «случай → ожидаемо → получено → время», код 1 при расхождении. Сеть и контейнеры (метка `mtusi.lb-upload-timeouts`) удаляются при любом исходе, в том числе по Ctrl+C, SIGTERM, SIGHUP. ~35 с. На `haproxy.cfg` до change (`git archive f894040 infra/haproxy/haproxy.cfg \| tar -x -C <каталог>`, `--config <каталог>/infra/haproxy/haproxy.cfg`) — код 1: 502 и 504 через 10 с на пути загрузки, 400 в HTML. Вывод — `evidence/uploads/lb-timeouts.md` |
|
||||
| `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab5`) с лимитами реплики (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-lab5`, образ `mtusi-messenger:lab5`, compose-сервисы
|
||||
`postgres`, `valkey`, `s3` (SeaweedFS, API S3 на `127.0.0.1:S3_OUT_PORT`
|
||||
— 8334), `rabbitmq` (AMQP на `127.0.0.1:5673`, volume `rabbitmq_data`),
|
||||
`migrate` (одноразовые миграции), `s3-bootstrap` (одноразовый:
|
||||
приватный bucket, пользователи API, уборщика и worker), `api` × `API_REPLICAS`
|
||||
(по умолчанию 2, без портов на хосте и без настроек брокера), `relay` (`python -m
|
||||
src.relay`, публикует задания из PostgreSQL), `worker` (`python -m src.worker`), оба
|
||||
без портов и healthcheck, `cleaner` (уборщик незавершённых
|
||||
загрузок, без портов и healthcheck) и `haproxy` — единственный порт API
|
||||
на хосте, `127.0.0.1:APP_OUT_PORT` (8080). Конфиг LB —
|
||||
`infra/haproxy/haproxy.cfg`, правила — `balancer.md` и `docker.md`.
|
||||
|
||||
```bash
|
||||
make run_docker # build + up -d: postgres, valkey, s3, rabbitmq → migrate, s3-bootstrap → api × 2, relay, worker, cleaner → haproxy
|
||||
make s3_check # приватность bucket вне API: таблица проверок, код 0
|
||||
docker compose logs s3-bootstrap # bucket/user exists|created, checks passed
|
||||
docker compose run --rm s3-bootstrap # повтор bootstrap: «exists», код 0
|
||||
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, S3 и брокера (~35 с): данные, токены, объекты и очередь остаются, кэш пуст; relay, worker и уборщик не трогает
|
||||
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 --port 8080 attachment-failover --mode kill # реплика, принявшая файл, убита: скачивание через другую, тот же SHA-256
|
||||
python3 $D --port 8080 attachment-storage # байты только в приватном bucket: схема, ключ, объект, аноним 403, docker diff
|
||||
python3 $D --port 8080 upload-consistency # S3 заморожен и сбой ready: 503, pending не видны, компенсация, cleaner --once всё убрал
|
||||
make reconcile # разовая сверка bucket и БД, dry-run: код 0 — расхождений нет, 3 — остались
|
||||
make reconcile APPLY=1 [MAX_CHANGES=N] # то же с исправлением (предел изменений прохода — 100 или N)
|
||||
python3 $D --port 8080 reconcile-cycle # расхождения с обеих сторон: dry-run, --apply, 404/200, повтор = 0, возврат оригинала; ~2 мин
|
||||
python3 $D --port 8080 reconcile-stress # --apply раз в 3 с под загрузками 4 клиентов 40 с: все 202 доходят до ready и скачиваются с тем же SHA-256
|
||||
COMPOSE_PROJECT_NAME=<временный> python3 $D reconcile-signal # pause s3 + docker stop разового --apply: код 1, interrupted_by stop; не на mtusi-lab5
|
||||
COMPOSE_PROJECT_NAME=<временный> python3 $D reconcile-signal --pace # docker stop во время паузы предела скорости: код 1, ≤ 1 с
|
||||
COMPOSE_PROJECT_NAME=<временный> python3 $D reconcile-signal --pace --apply # то же посреди удалений: каждое удалённое — «Fixed»
|
||||
python3 $D --port 8080 s3-idle # клиент S3 после скачиваний и простоя: у образа 0 испорченных соединений и упавших PUT, эталон портит; ~40 с
|
||||
python3 $D lb-upload-timeouts # сроки LB пути загрузки на заглушке: 202 после 12 с молчания, 504 через 10/30 с, 400 в формате контракта; ~35 с
|
||||
python3 $D --port 8080 defense-scenario # защита лабы 5: worker стоит, 202, 201, 409, 201, сообщение в очереди, рестарт, worker, ready, оригинал и три варианта; ~1,5 мин
|
||||
python3 $D --port 8080 defense-faults # шаг 4 защиты: crash до фиксации и до ack, relay убит до публикации и до отметки, replay; ~4 мин
|
||||
make bench_queue_quick # шаг защиты «для 5 — выбранный эксперимент»: очередь под перегрузкой, ~11 мин (рабочий стенд — make stop); разбор — evidence/queue/baseline4/summary.md
|
||||
python3 $D broker-check # брокер: образ, volume, порт, предел памяти, очередь, пароль только у rabbitmq, relay, worker, остановка с кодом 0; ~30 с
|
||||
python3 $D --port 8080 worker-process # процесс worker: PID 1, лимиты, Pillow, журнал, неверные настройки, остановка, рестарт хранилищ, остановка под нагрузкой; ~5 мин
|
||||
python3 $D --port 8080 relay-process # процесс relay: то же, окружение без S3 и Valkey; ~2 мин
|
||||
python3 $D --port 8080 worker-memory # два файла разом на границах контракта: memory.peak контейнера, render_peak, OOM нет; ~35 с
|
||||
python3 $D --port 8080 freeze-sessions # заморозка через TCP-прокси пробы: 503 за срок плюс закрытие, сессий сверх пула нет; сервер не трогается; ~2,5 мин
|
||||
python3 $D freeze-lb # docker pause PostgreSQL на временном проекте со своими данными в tmpfs: 503 через LB за ~8 с, 504 нет; ~1,5 мин
|
||||
python3 $D pipeline-state # JSON: задания по состояниям, due, ждут срока, опубликованы и не взяты, истёкшие аренды, очередь
|
||||
make replay # реестр failed, только показ; APPLY=1 ATTACHMENT=<id> — вернуть в работу, код 3 — есть отказы
|
||||
docker compose logs --no-log-prefix relay | tail -3 # relay: Started relay, Relay pass, Recovered expired lease
|
||||
docker compose logs --no-log-prefix worker | tail -3 # worker: Started worker, Connected to broker, задания
|
||||
docker compose logs --no-log-prefix cleaner | tail -3 # уборщик: Started cleaner (60/900/100), проходы, отказы
|
||||
docker compose run --rm --no-deps cleaner --once # разовый проход уборщика (grace 900 с): код 0 — проход дошёл до конца
|
||||
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`.
|
||||
|
||||
## Лаба 5: брокер, relay и worker
|
||||
|
||||
Design change `async-attachments`, решение 17, и `pipeline-reliability`, решения 8, 14,
|
||||
17. Команды останавливают сервисы рабочего стенда, поэтому идут одни, без параллельных
|
||||
загрузок и тестов на нём (кроме `pipeline-state`: она только читает). Вывод — без
|
||||
токенов и секретов.
|
||||
|
||||
**`defense-scenario`** (`--port <LB>`; спек `student-tests`, «Сценарий защиты
|
||||
автоматизирован»; ~1,5 мин). Синтетические Алиса, Боб, Ева и чат, затем:
|
||||
|
||||
1. `docker compose stop worker`;
|
||||
2. загрузка `tests/fixtures/sample.png` — 202, снимок `queued`, `id` вложения;
|
||||
3. сообщение с вложением — 201, `id` сообщения;
|
||||
4. скачивание Бобом — 409;
|
||||
5. текстовое сообщение — 201;
|
||||
6. опрос (до 20 с): в очереди ≥ 1 сообщение, его публикует relay, он не останавливается;
|
||||
0 потребителей;
|
||||
7. `scripts/restart.sh`, ожидание LB, сообщение всё ещё в очереди, прежний токен
|
||||
читает метаданные: `queued`;
|
||||
8. `docker compose start worker`, опрос до `ready` (до 60 с);
|
||||
9. оригинал — 200 и тот же SHA-256; три варианта — 200, тип, размеры по самим байтам (без
|
||||
Pillow, стандартной библиотекой), SHA-256 равен метаданным: `thumbnail` JPEG 256×160,
|
||||
`crop` JPEG 128×128, `optimized` WebP 320×200;
|
||||
10. история отдаёт оба сообщения; `StartedAt` всех реплик `api` и `rabbitmq` до и
|
||||
после — разный, у relay — тот же.
|
||||
|
||||
Коды: 0 — всё сошлось; 1 — расхождение (таблица «проверка → ожидаемо →
|
||||
получено»); 130 — прерван сигналом; 2 — нет стенда на порту или консольный процесс
|
||||
драйвера. Вывод — `evidence/attachments/defense.md`.
|
||||
|
||||
**`defense-faults`** (`--port <LB>`; спек `student-tests`, «Шаг 4 на рабочем стенде»;
|
||||
~4 мин, из них аренда 70 с). Порядок — тот же, что `test_defense_faults` на стенде
|
||||
отказов. Триггеры `driver_df_*` срабатывают только на уникальный `filename` прогона:
|
||||
|
||||
1. **после записи объектов до COMMIT:** триггер `pg_sleep(4)` на перевод в `ready`,
|
||||
загрузка 202, сессия worker в `PgSleep` на `UPDATE attachments` (объекты записаны),
|
||||
`docker kill worker`; `processing`, `attempt` 1, SHA-256 трёх объектов до сбоя, снятие
|
||||
триггера, запуск; `ready` не раньше истечения аренды (срок попытки 60 с + запас 10 с),
|
||||
те же SHA-256 в S3 и метаданных, `attempt` 2;
|
||||
2. **после COMMIT до ack:** отложенный триггер `pg_sleep(3)` в COMMIT, `docker kill -s
|
||||
STOP worker` (контейнер `running`, не `paused`: KILL проходит), `succeeded` при
|
||||
замороженном клиенте, `docker kill worker`, сообщение вернулось в очередь, запуск —
|
||||
запись «Skipped job message» `finished` по этому заданию, новых попыток 0, тот же
|
||||
`updated_at`, метаданные те же, `attempt` 1, очередь пуста;
|
||||
3. **после COMMIT `queued` до публикации:** `docker kill relay`, контейнер не вернулся,
|
||||
загрузка 202, `published_at` пуст, сообщений 0, запуск relay, `ready`, `attempt` 1;
|
||||
4. **после подтверждения до отметки:** worker остановлен, триггер `pg_sleep(3)` на
|
||||
`published_at`, загрузка 202, сессия relay в `PgSleep` на `UPDATE attachment_jobs`,
|
||||
`docker kill relay`, сообщение в очереди, `published_at` пуст, запуск relay — два
|
||||
сообщения при остановленном worker, запуск worker, `ready`, `attempt` 1, очередь пуста;
|
||||
5. **replay `failed`:** worker остановлен, загрузка 202, объект staging заменён другими
|
||||
байтами того же размера, запуск worker — `failed` `processing_failed`, причина
|
||||
`source_corrupted`; реестр `relay replay --error-code processing_failed` называет
|
||||
задание и ничего не меняет; объект возвращён; `relay replay --attachment-id … --apply
|
||||
--operator driver-defense-faults` — код 0, `ready`, оригинал с тем же SHA-256, то же
|
||||
задание, `attempt` 2, `attempt_base` 1, запись аудита;
|
||||
6. **replay готового:** новое `ready`, `--apply` — код 3, отказ `already_ready`,
|
||||
метаданные и задание те же, аудита нет.
|
||||
|
||||
Каждое вложение проверяется скачиванием трёх вариантов. Вывод — строки по окнам и шагам, в
|
||||
конце таблица «окно → действие → `id` задания → начатых попыток → итог» и таблица «проверка →
|
||||
ожидаемо → получено». В конце `pg_trigger` без `driver_df_*`. Коды: 0; 1 — расхождение; 130 —
|
||||
прерван сигналом; 2 — нет стенда на порту или консольный процесс драйвера. Вывод —
|
||||
`evidence/attachments/defense-faults.md`.
|
||||
|
||||
**`broker-check [--require-test-queue]`** (спек `message-broker`; ~30 с, порт не
|
||||
нужен). Таблица «проверка → ожидаемо → получено»: образ `rabbitmq:X.Y.Z@sha256:…` в
|
||||
`docker compose config`, `healthy`, volume `<проект>_rabbitmq_data` на
|
||||
`/var/lib/rabbitmq`, `docker port` — ровно AMQP на `127.0.0.1`, лимит контейнера 512
|
||||
МиБ и `vm_memory_high_watermark_limit` меньше него (`rabbitmqctl -q status --formatter
|
||||
json`), пароль брокера в `docker compose config` — только у `rabbitmq`, `relay`, `worker`
|
||||
(имена переменных, значения не печатаются), у `api` нет `BROKER__*`, рабочая очередь
|
||||
`<база>.attachment.process.v1` durable (`rabbitmqctl -q list_queues … --formatter json`).
|
||||
С флагом — ещё очередь `test_<база>.attachment.process.v1`, без неё код 1, без флага —
|
||||
строка «not checked». Затем `docker compose stop rabbitmq` — код 0 раньше срока 20 с, код
|
||||
контейнера 0; `up -d --wait --no-recreate rabbitmq` (при любом исходе), очередь на месте,
|
||||
worker снова потребляет (если потреблял), relay пережил отказ (прежний `StartedAt`). Коды: 0,
|
||||
1 — расхождение, 130 — сигнал. Вывод — `evidence/broker/stand.md`.
|
||||
|
||||
**`worker-process`** (`--port <LB>`; спеки `container-run`, `graceful-shutdown`,
|
||||
`service-configuration`; ~2 мин). PID 1 — `python -m src.worker`, healthcheck `NONE`, лимиты
|
||||
1 CPU и 1 ГБ; `_imaging` нет в `/proc/1/maps` ни реплик API, ни процесса 1 worker (декодер —
|
||||
только в процессе обработки); версия Pillow в образе равна `uv.lock`; последняя запись
|
||||
«Started worker» со всеми значениями, значения по умолчанию (конкуренция 2, prefetch 2, 5
|
||||
попыток, срок 60 с, запас аренды 10 с, пауза 5 и 300 с, процесс обработки 40 с, 15 с CPU, 450
|
||||
МиБ, остановка 8 с, соединение 2 с); `WORKER__CONCURRENCY=0`, `WORKER__PREFETCH=0`,
|
||||
`WORKER__MAX_ATTEMPTS=abc`, `WORKER__GRACEFUL_SHUTDOWN_SECONDS=9`,
|
||||
`WORKER__RENDER_MEMORY_LIMIT_MIB=0`, `WORKER__RENDER_TIMEOUT_SECONDS=120` (`docker compose
|
||||
run --rm --no-deps -e … worker`) — код 2, запись называет поле, значения в ней нет; подмена
|
||||
окружением в одноразовом контейнере (`WORKER__CONCURRENCY=3`, `WORKER__RECONNECT_SECONDS=1`);
|
||||
`docker compose stop worker` — код контейнера 0, быстрее 10 с, «Stopped worker» с `exit_code`
|
||||
0, затем `start`; `docker stop` контейнера образа (без сети, лимиты сервиса) через 0,2–0,4 с
|
||||
после `docker run` — код 0, не дольше 1 с, «Stopped worker before startup» хотя бы в одной
|
||||
попытке; `scripts/restart.sh` — у worker прежний `StartedAt`, `RestartCount` 0, новая
|
||||
загрузка `ready`; остановка под нагрузкой: два дорогих JPEG в обработке (генератор
|
||||
`student-tests/images.py` в контейнере образа), `docker stop` быстрее 9,5 с, код 0, без OOM,
|
||||
«Stopped worker» последней записью — сначала при живых хранилищах, затем при замороженных
|
||||
PostgreSQL и брокере; все четыре задания после этого доходят по аренде до `failed`, `limit_cpu`
|
||||
(до 200 с, поэтому вся команда ~5 мин). Коды: 0, 1 — расхождение, 130 — сигнал, 2 — нет стенда.
|
||||
Вывод — `evidence/worker/process.md`.
|
||||
|
||||
**`relay-process`** (`--port <LB>`; те же спеки; ~2 мин). Те же шаги о сервисе `relay`: PID 1 —
|
||||
`python -m src.relay`, healthcheck `NONE`, лимиты 0,25 CPU и 256 МБ; в окружении нет `S3__`,
|
||||
`S3_`, `CACHE__`, `VALKEY` (только имена переменных); `_imaging` нет ни у реплик, ни у relay;
|
||||
«Started relay» со всеми значениями, значения по умолчанию (опрос 0,25 с, пакет 100, предел 1000,
|
||||
порог потерянного 300 с, пауза отказа 2 с); `RELAY__BATCH_SIZE=0`,
|
||||
`RELAY__MAX_PUBLISHED_BACKLOG=-1`, `RELAY__POLL_INTERVAL_SECONDS=abc` — код 2, поле, без
|
||||
значения; подмена окружением (`RELAY__BATCH_SIZE=7`, `RELAY__POLL_INTERVAL_SECONDS=1`);
|
||||
`docker compose stop relay` — код контейнера 0, быстрее 10 с, «Stopped relay» с `exit_code` 0;
|
||||
`docker stop` на старте — «Stopped relay before startup»; `scripts/restart.sh` — прежний
|
||||
`StartedAt`, `RestartCount` 0, новая загрузка `ready`; `docker stop relay` при замороженном брокере
|
||||
с намерением в работе — быстрее 10 с, код 0, «Stopped relay» последней записью, после запуска relay
|
||||
вложение `ready`. Коды те же. Вывод — `evidence/relay/process.md`.
|
||||
|
||||
**`pipeline-state`** (решение 8; порт не нужен, только чтение, идёт и под нагрузкой). JSON:
|
||||
`jobs_by_state` (`queued`, `processing`, `succeeded`, `failed`), `due` (`queued` без отметки, срок
|
||||
прошёл: публикует следующий проход relay), `waiting_for_time` (`queued`, срок впереди),
|
||||
`published_not_taken` (`queued` с отметкой), `expired_leases` (`processing`, аренда истекла:
|
||||
вернёт relay), `oldest_queued_age_seconds` (старейшее `queued`, `null` — таких нет), `queue`:
|
||||
`name`, `available`, `exists`, `durable`, `messages_ready`, `messages_unacknowledged`, `consumers`.
|
||||
Коды: 0, в том числе при недоступном брокере (`available: false`, ожидание до 15 с); 1 — нет
|
||||
PostgreSQL или конфигурации стенда, причина в stderr. `python3 $D pipeline-state | jq .due`.
|
||||
|
||||
**`worker-memory`** (`--port <LB>`; спек `attachment-processing`, «Изображение в лимите
|
||||
пикселей»; design change `pipeline-reliability`, решение 7; ~35 с). Девять случаев: PNG из шума
|
||||
10 MiB, шесть типов PNG на 40 Мпкс, RGBA и серый 16 бит на обеих границах контракта разом (файлы
|
||||
— генераторы `student-tests/images.py` в контейнере образа без сети). На случай: `docker stop`
|
||||
worker, две одинаковые загрузки, `docker start` (новая cgroup: `memory.peak` с нуля), оба `ready`
|
||||
(до 90 с), затем `/proc/1/status`, `memory.peak`, `memory.events`, `docker inspect`, записи журнала
|
||||
«Started job attempt» и «Attachment became ready». Строка таблицы на случай и таблица «проверка →
|
||||
ожидаемо → получено»: все 18 `ready`, задания пересеклись во всех случаях, `oom` и `oom_kill` 0,
|
||||
`OOMKilled` false, рестартов нет, наибольший `render_peak` меньше `render_memory_limit_mib`,
|
||||
`memory.peak` и сумма пиков `VmHWM + 2 × render_peak` меньше лимита контейнера. `memory.peak` одного
|
||||
случая плавает на сотни МиБ: зависит от совпадения пиков двух процессов. Коды: 0; 1 — расхождение;
|
||||
130 — сигнал (worker и relay запускаются при любом исходе); 2 — нет стенда или есть незавершённые
|
||||
задания: они добавили бы свой пик. Вывод — `evidence/worker/memory.md`.
|
||||
|
||||
**`freeze-sessions [--rounds 6] [--settle 15]`** (спек `unit-of-work`; design change `unit-of-work`,
|
||||
уточнения 17 и 18; порт не нужен; ~2,5 мин). Заморозка без заморозки сервера: одноразовый контейнер
|
||||
`api` (`docker compose run --rm --no-deps -T --name <проект>-freeze-sessions --entrypoint python
|
||||
api -`, скрипт через stdin, настройки и код образа, ключи в драйвер не попадают), приложение в его
|
||||
процессе без lifespan, вызовы ASGI напрямую (httpx в образе нет), PostgreSQL только через TCP-прокси
|
||||
пробы, закрытые ворота прокси — и есть заморозка. Срок `[database] request_timeout_seconds` 2 с. Режимы:
|
||||
`second-block` (пул 2, ворота закрываются между блоком входа и `GET /chats`), `before-requests`
|
||||
(пачка из четырёх `GET /users/me`, пул 2 и пул 4). После разморозки на раунд: сессии через прокси,
|
||||
занятые соединения, четыре следующих запроса, записи логгера `sqlalchemy.pool`; в конце — занятые
|
||||
соединения, снимок сессий через `--settle` с. Таблица: 503 в срок 2–4,5 с, сессии в пределах пула
|
||||
сразу и после паузы, следующие запросы 200, записей пула 0, сессий брошенной проверки (запрос `;`) 0.
|
||||
Контейнер удаляется при любом исходе, в базе остаётся по одному синтетическому пользователю на режим.
|
||||
Коды: 0; 1 — расхождение; 130 — сигнал; 2 — PostgreSQL проекта не работает. Вывод —
|
||||
`evidence/storage/freeze-sessions.md`.
|
||||
|
||||
**`freeze-lb [--rounds 3]`** (та же запись verify; порт не нужен; ~1,5 мин). Только временный проект
|
||||
compose: `COMPOSE_PROJECT_NAME` или `mtusi-lab5-freeze`, `mtusi-lab5` — отказ, код 2; перед `docker
|
||||
pause` метка проекта контейнера сверяется ещё раз. Команда сама поднимает стенд и убирает его при любом
|
||||
исходе, нужен только образ `mtusi-messenger:lab5` (`make run_docker`, иначе код 2): во временном каталоге
|
||||
файл окружения из `.env.example` со случайными секретами и override — без портов PostgreSQL, Valkey и S3,
|
||||
данные PostgreSQL, Valkey и S3 в tmpfs (volumes нет), `config_example.toml`, порт LB свободный. `up -d
|
||||
--no-build haproxy`, ожидание двух реплик через LB, прогрев пула, синтетические пользователи и чат. На
|
||||
заморозку: сессии `pg_stat_activity`, `docker pause` PostgreSQL, шесть одновременных запросов (`GET
|
||||
/users/me`, история, `POST` сообщения, `GET /chats`, вход, метаданные вложения), `unpause` в `finally`,
|
||||
время до первого 200, через 11 с — снова сессии. Таблица: все ответы 503 `unavailable`, 504 от LB нет,
|
||||
каждый раньше `timeout server` 10 с, восстановление, сессий не больше пулов (20) и не растёт, сессий `;`
|
||||
нет, контейнеров и volumes проекта после `down` 0. Коды: 0; 1 — расхождение; 130 — сигнал; 2 — рабочий
|
||||
проект или нет образа. Вывод — раздел `evidence/storage/freeze-sessions.md`.
|
||||
|
||||
Gotchas:
|
||||
|
||||
- **Сигнал во время `defense-scenario`, `defense-faults`, `worker-process`, `relay-process`.**
|
||||
SIGINT, SIGTERM, SIGHUP прерывают сценарий с кодом 130. Начатый `restart.sh` (своя сессия)
|
||||
доводится до конца, триггеры снимаются, замороженный worker добивается, worker и relay
|
||||
запускаются, повторные сигналы на это время игнорируются: выход может занять до минуты. От
|
||||
SIGKILL защиты нет: `docker compose start worker relay` руками, триггеры — следующий прогон
|
||||
`defense-faults` или `DROP TRIGGER` по `pg_trigger` с `driver_df_`.
|
||||
- **Прерванный `defense-faults` оставляет работу в строках, а не только в триггерах:** зависшая
|
||||
попытка вернётся по аренде через ≤ 70 с, строка `failed` окна replay остаётся в реестре.
|
||||
- **`docker kill` не перезапускает контейнер** при `restart: unless-stopped`: `docker start` делает
|
||||
сам драйвер (тот же контейнер, те же журнал и `StartedAt` следующего запуска).
|
||||
- **`broker-check --require-test-queue` имеет смысл только во время `make test_isolated`:**
|
||||
после прогона очереди временной базы нет (спек «Очереди разных баз разделены»), поэтому отдельный
|
||||
запуск — код 1, и это верно. Флаг запускают из другого терминала посреди прогона.
|
||||
- **На время `broker-check` загрузки стенда — по-прежнему 202:** брокера в пути запроса нет.
|
||||
Брокер остановлен ~5–10 с, задания ждут в PostgreSQL, relay пишет «Broker is unavailable» и
|
||||
публикует их после возврата.
|
||||
- **Без `--port` у `defense-scenario`, `defense-faults`, `worker-process`, `relay-process` — код 2**
|
||||
(«no stand on port 18080»): стенд на 8080, а порт драйвера по умолчанию 18080.
|
||||
- **Подмена окружением.** Одноразовый контейнер `worker-process` — такой же потребитель рабочей
|
||||
очереди, у `relay-process` — такой же издатель; живёт секунды и убирается `docker rm -f`: задание
|
||||
worker вернётся по аренде, дубль relay — no-op.
|
||||
- **Staging готового вложения исчезает на проходе уборщика (до 60 с, `staging_key` становится
|
||||
`NULL`):** `attachment-storage` принимает оба вида. У `failed` объект живёт сутки: без него
|
||||
replay откажет `source_gone`. Сверка видит staging: объект без строки и ключ другого вида моложе
|
||||
срока хранения — свежие, старше — `orphan_staging` и `unknown_object`. `reconcile-cycle`
|
||||
задаёт срок хранения прогона 30 с. У него строка B удаляется вместе с заданием и вариантами (FK без
|
||||
каскада), три объекта вариантов становятся находками, а её staging драйвер убирает сам.
|
||||
- **Консольный `driver.py start` и стенд делят очередь и строки заданий:** имя очереди — от имени
|
||||
базы, база та же. Если контейнеры `worker` и `relay` стенда запущены, задания консольного API могут
|
||||
взять они (результат тот же). Worker и relay в консоли не перезагружаются при правке `src/`:
|
||||
`driver.py stop`, затем `start`.
|
||||
- **`pipeline-state` считает задания прежнего уровня как есть:** строка с отметкой без сообщения —
|
||||
`published_not_taken`, пока relay не снимет отметку по порогу `republish_after_seconds`.
|
||||
|
||||
## Direct invocation (без HTTP)
|
||||
|
||||
Для правок в `src/core/` сервисы вызываются поверх единицы работы, сервер не
|
||||
нужен, но Postgres с миграциями нужен (`make upgrade`). Ветки сервисов без
|
||||
хранилищ — `make service_test`.
|
||||
`APP__LOG_LEVEL=WARNING` убирает JSON-логи сервисов из вывода:
|
||||
|
||||
```bash
|
||||
make upgrade
|
||||
APP__LOG_LEVEL=WARNING uv run python - <<'EOF'
|
||||
import asyncio
|
||||
import uuid
|
||||
from src.config import settings
|
||||
from src.core.services import SessionService, UserService
|
||||
from src.infra.db.session import engine, session_factory
|
||||
from src.infra.db.uow import SqlAlchemyUnitOfWork
|
||||
|
||||
async def main():
|
||||
uow = SqlAlchemyUnitOfWork(
|
||||
session_factory,
|
||||
timeout_seconds=settings.database.request_timeout_seconds,
|
||||
)
|
||||
username = f"alice_{uuid.uuid4().hex[:6]}"
|
||||
await UserService(uow=uow).register(
|
||||
username=username,
|
||||
display_name="Alice",
|
||||
password="Alice-password-1",
|
||||
)
|
||||
sessions = SessionService(uow=uow)
|
||||
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(uow=uow, 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, S3 + bootstrap, затем 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: lab5 public API scenario...`, student — все
|
||||
прошли (тесты `fault` — `deselected`), `All checks passed!`; `all`,
|
||||
`test_isolated` и `failure_checks` — код 0. Пока файлы `evidence/`, на
|
||||
которые ссылаются исключения сверки покрытия, не сняты на стенде лабы
|
||||
(AGENTS.md, «Переход в следующую лабу»), красный только
|
||||
`test_exclusion_evidence_exists` — он называет сценарий и путь.
|
||||
|
||||
Проверки отказов (`student-tests/test_failures.py`, маркер `fault`)
|
||||
останавливают и замораживают Postgres, Valkey и S3, поэтому идут только на
|
||||
своём стенде: `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` передают его сами.
|
||||
- **Загрузка отвечает 202, а не 201 (с лабы 5):** все команды вложений ждут
|
||||
`ready` опросом метаданных раз в 0,2 с, до 60 с. Сообщение можно отправить и
|
||||
с `queued`, а скачивание до `ready` — 409.
|
||||
- **Порт отдельной реплики на хосте не опубликован.** Запрос мимо 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-lab5-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`.
|
||||
- **Ранний 413 на большой загрузке `urllib` напрямую к процессу
|
||||
теряет.** API отвечает 413 (и 404, 415), не дочитывая тело; uvicorn
|
||||
закрывает соединение, а `urllib` всё ещё пишет тело и получает
|
||||
`BrokenPipe` / `ConnectionReset` вместо ответа. Через LB ответ
|
||||
доходит (HAProxy дочитывает тело сам), httpx и `curl` получают его и
|
||||
напрямую. Поэтому `driver.py upload` большие тела проверять через
|
||||
`--port 8080`, а в консоли — `curl -H 'Content-Type: image/png'
|
||||
--data-binary @big.png`.
|
||||
- **Скачивание через LB может прийти не от той реплики, что загрузку**
|
||||
— это и есть проверка «байты не на диске API»: оригинал отдаёт любая
|
||||
реплика из S3. `X-Instance-Id` ответа загрузки — у `upload`.
|
||||
- **`upload-consistency`: grace разового прохода — не меньше 18 с.**
|
||||
Уборщик не стартует (код 2), если grace не больше границы живой
|
||||
загрузки `2 × request_timeout_seconds + s3 timeout_seconds` = 17 с;
|
||||
драйвер берёт 30 с. Уборщик сервиса (grace 900 с) строки прогона за
|
||||
это время не трогает, а разовый проход и сервис друг другу не мешают
|
||||
(`FOR UPDATE SKIP LOCKED`).
|
||||
- **На время `pause` S3 (~5 с) вложения всего стенда отвечают 503** —
|
||||
загрузка и скачивание, в том числе чужие запросы; текст и метаданные
|
||||
работают. Не запускать `upload-consistency` параллельно с тестами,
|
||||
которые качают вложения.
|
||||
- **Разовый проход уборщика — `docker compose run --rm --no-deps cleaner
|
||||
--once`**: у сервиса `cleaner` точка входа `python -m src.cleaner`, а
|
||||
не `command`, поэтому аргументы после имени сервиса — флаги уборщика.
|
||||
Так же разовая сверка — `… cleaner reconcile [--apply]` (`make
|
||||
reconcile`).
|
||||
- **`reconcile-cycle` и `reconcile-stress` меняют рабочий стенд**
|
||||
(design change `track2-reconciler`, решение 12): синтетические
|
||||
пользователи, чаты и вложения остаются в рабочей базе, в том числе
|
||||
вложения, помеченные потерянными (`lost_at`): у одного изменён размер,
|
||||
у другого удалён объект; их байты — 404, метаданные — 200. Объекты мимо
|
||||
API (без строки, чужой ключ, свежий) драйвер удаляет сам — сверкой или
|
||||
`weed shell fs.rm` в `finally`. Триггер COMMIT — на уникальный
|
||||
`filename` прогона, снимается в `finally` и в начале следующего. Перед
|
||||
прогоном стенд должен быть сведён: исходный dry-run с расхождениями —
|
||||
код 2 и «run make reconcile first». Grace прогона — 30 с (цикл) и 20 с
|
||||
(стресс), больше границы живой загрузки 17 с. Нужен стенд на коде
|
||||
change: новая политика S3 уборщика (`docker compose up -d
|
||||
s3-bootstrap`), колонка `lost_at` (миграция) и образ уборщика с
|
||||
командой `reconcile`; на прежнем — сверка падает (`AccessDenied` на
|
||||
списке или нет колонки). Evidence — `evidence/reconcile/cycle.md`,
|
||||
`evidence/reconcile/stress.md`.
|
||||
- **Строки `s3-check` о списке уборщика** («cleaner key list attachments
|
||||
prefix», «… staging prefix» — 200, «… objects», «… database prefix», «…
|
||||
other prefix», «… other bucket» — 403) печатает сам bootstrap в режиме
|
||||
`check`. Драйвер требует строки трёх префиксов: на прежнем `bootstrap.sh`
|
||||
— код 1 и «no row from s3-bootstrap check».
|
||||
- **Пустой каталог `<id>/` в bucket после удаления объекта** SeaweedFS
|
||||
убирает лишь через ~2 мин: `fs.ls` его показывает, список S3 — нет.
|
||||
Объекты считать по файлам `original` (`fs.tree`), а не по каталогам.
|
||||
- **`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`.
|
||||
- **`S3_… is empty, copy S3 lines from .env.example`** — `.env` создан
|
||||
до `s3-storage`: перенести блок S3 из `.env.example`, пять пустых
|
||||
секретов — `openssl rand -hex 32` каждый; затем `make run_docker`.
|
||||
- **`s3-bootstrap: FAILED: <шаг>`, реплики не стартуют** — bootstrap
|
||||
назвал шаг: `docker compose logs s3-bootstrap`. Недопустимое имя
|
||||
`S3__BUCKET` — «bucket create»; анонимный доступ или права не те —
|
||||
`FAILED: … is not denied`. Повтор — `docker compose up -d
|
||||
s3-bootstrap` (или `make run_docker`).
|
||||
- **`make stop` и `restart.sh` дольше на ~15 с** — SeaweedFS
|
||||
останавливается плавно ~15 с (`stop_grace_period: 20s`), это не
|
||||
зависание.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -18,3 +18,27 @@ __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
|
||||
service-tests
|
||||
bench
|
||||
contracts
|
||||
scripts
|
||||
examples
|
||||
infra
|
||||
*.md
|
||||
Makefile
|
||||
.ruff_cache
|
||||
.idea
|
||||
.python-version
|
||||
|
||||
+133
-24
@@ -1,25 +1,134 @@
|
||||
# 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,
|
||||
# RABBITMQ_DEFAULT_PASS и секреты S3 (S3_ROOT_*, S3_JWT_SIGNING_KEY,
|
||||
# S3_API_*, S3_CLEANER_*, S3_WORKER_*).
|
||||
# Существующий .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, с lab4 — S3_ENDPOINT,
|
||||
# S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE,
|
||||
# MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS) — в REPORT.md, «Архитектура и
|
||||
# решения». Имена skeleton S3_* буквально не заводятся: S3 настраивают
|
||||
# строки блока S3 ниже.
|
||||
# С lab5 — BROKER_URL_FILE: [broker] мостами из RABBITMQ_* ниже (значения, а
|
||||
# не файл); WORKER_CONCURRENCY: [worker] concurrency; JOB_MAX_ATTEMPTS:
|
||||
# [worker] max_attempts; JOB_TIMEOUT_SECONDS: [worker] job_timeout_seconds;
|
||||
# STAGING_RETENTION_SECONDS: [cleaner] staging_retention_seconds.
|
||||
|
||||
# порт сервиса ([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
|
||||
S3_ENDPOINT=http://s3:9000
|
||||
S3_REGION=us-east-1
|
||||
S3_BUCKET=messenger-attachments
|
||||
S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id
|
||||
S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key
|
||||
MAX_UPLOAD_BYTES=10485760
|
||||
MAX_IMAGE_PIXELS=40000000
|
||||
BROKER_URL_FILE=/run/secrets/broker_url
|
||||
WORKER_CONCURRENCY=2
|
||||
JOB_MAX_ATTEMPTS=5
|
||||
JOB_TIMEOUT_SECONDS=60
|
||||
STAGING_RETENTION_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}
|
||||
|
||||
# S3 (SeaweedFS) — байты вложений. Шесть пустых секретов make env_setup
|
||||
# заменяет случайными hex; без них compose не стартует. Кто какой секрет
|
||||
# получает — docker-compose.yml, якоря x-s3-*
|
||||
# имя bucket: читают приложение ([s3] bucket) и bootstrap S3, который его
|
||||
# создаёт; 3–63 символа: строчные буквы, цифры, точка и дефис
|
||||
S3__BUCKET=messenger
|
||||
# административные ключ и секрет S3: только сервер s3 (без учётной
|
||||
# записи он открыт анониму), ни API, ни bootstrap их не получают
|
||||
S3_ROOT_ACCESS_KEY=
|
||||
S3_ROOT_SECRET_KEY=
|
||||
# ключ подписи служебных вызовов SeaweedFS (gRPC шлюза, IAM filer):
|
||||
# сервер s3 и bootstrap
|
||||
S3_JWT_SIGNING_KEY=
|
||||
# ключи пользователя API (только объекты своего bucket): bootstrap
|
||||
# заводит пользователя с ними, реплики API ходят с ними в S3. Новый
|
||||
# секрет вступает в силу при следующем bootstrap (make run_docker)
|
||||
S3_API_ACCESS_KEY=
|
||||
S3_API_SECRET_KEY=
|
||||
# ключи пользователя уборщика незавершённых загрузок (только чтение и
|
||||
# удаление объектов своего bucket): bootstrap заводит пользователя с
|
||||
# ними, сервис cleaner ходит с ними в S3; реплики API их не получают
|
||||
S3_CLEANER_ACCESS_KEY=
|
||||
S3_CLEANER_SECRET_KEY=
|
||||
# ключи пользователя worker (только чтение и запись объектов своего
|
||||
# bucket): bootstrap заводит пользователя с ними, сервис worker и make
|
||||
# run_worker ходят с ними в S3; реплики API их не получают
|
||||
S3_WORKER_ACCESS_KEY=
|
||||
S3_WORKER_SECRET_KEY=
|
||||
# адрес и порт API S3 внутри сети compose: по ним ходит API в docker,
|
||||
# порт слушает сам сервер и проверяет bootstrap
|
||||
S3_HOST=s3
|
||||
S3_PORT=8333
|
||||
# порт на 127.0.0.1 хоста, куда публикуется API S3: к нему подключается
|
||||
# приложение в console (консоль и UI SeaweedFS не публикуются)
|
||||
S3_OUT_PORT=8334
|
||||
# мосты для console: в docker их задаёт environment compose
|
||||
S3__HOST=127.0.0.1
|
||||
S3__PORT=${S3_OUT_PORT}
|
||||
S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY}
|
||||
S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY}
|
||||
|
||||
# RabbitMQ — брокер заданий обработки вложений. Пользователя и пароль читает
|
||||
# и образ брокера: учётная запись создаётся при первом старте на пустом
|
||||
# volume. Пустой пароль make env_setup заменяет случайным
|
||||
RABBITMQ_DEFAULT_USER=messenger
|
||||
RABBITMQ_DEFAULT_PASS=
|
||||
# адрес и порт AMQP внутри сети compose: по ним ходят API и worker в docker,
|
||||
# порт слушает сам брокер
|
||||
RABBITMQ_HOST=rabbitmq
|
||||
RABBITMQ_PORT=5672
|
||||
# порт на 127.0.0.1 хоста, куда публикуется AMQP: к нему подключаются
|
||||
# приложение и worker в console; другие порты брокера не публикуются
|
||||
RABBITMQ_OUT_PORT=5673
|
||||
# мосты для console: в docker их задаёт environment compose
|
||||
BROKER__HOST=127.0.0.1
|
||||
BROKER__PORT=${RABBITMQ_OUT_PORT}
|
||||
BROKER__USER=${RABBITMQ_DEFAULT_USER}
|
||||
BROKER__PASSWORD=${RABBITMQ_DEFAULT_PASS}
|
||||
|
||||
# make test_isolated: порт на 127.0.0.1, куда публикуется тестовый
|
||||
# контейнер API
|
||||
TEST_APP_PORT=18088
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# Стенд в CI: docker-compose.yml + этот файл (COMPOSE_FILE job
|
||||
# application, .github/workflows/application.yml). Раннер Gitea
|
||||
# (act_runner) запускает job в контейнере рядом со стендом, на том же
|
||||
# Docker. Файлы рабочего каталога есть только в контейнере job, а bind
|
||||
# mount ищет их на хосте раннера; порты на 127.0.0.1 хоста из job не
|
||||
# видны и на общем хосте заняли бы чужие. Поэтому отличия от рабочего
|
||||
# стенда только такие:
|
||||
# - конфиги — configs из переменных окружения (их выставляет
|
||||
# .github/ci/stand-env.sh): compose копирует содержимое в контейнер при
|
||||
# создании, пути на хосте не нужно;
|
||||
# - портов на хосте нет: job подключается к сети стенда и ходит на
|
||||
# haproxy по имени;
|
||||
# - образ API — с тегом прогона: тег mtusi-messenger:lab5 на общем хосте
|
||||
# раннера может собрать и чужой job.
|
||||
# Остальное — сервисы, лимиты, volumes, секреты по сервисам — как в
|
||||
# рабочем стенде. Нужен Compose ≥ 2.24 (!reset).
|
||||
|
||||
services:
|
||||
postgres:
|
||||
ports: !reset []
|
||||
|
||||
valkey:
|
||||
ports: !reset []
|
||||
volumes: !reset []
|
||||
configs:
|
||||
- source: valkey_conf
|
||||
target: /usr/local/etc/valkey/valkey.conf
|
||||
|
||||
s3:
|
||||
ports: !reset []
|
||||
|
||||
s3-bootstrap:
|
||||
volumes: !reset []
|
||||
configs:
|
||||
- source: s3_bootstrap
|
||||
target: /opt/s3/bootstrap.sh
|
||||
|
||||
rabbitmq:
|
||||
ports: !reset []
|
||||
# !override: bind mount конфига заменяют configs, volume данных остаётся
|
||||
volumes: !override
|
||||
- rabbitmq_data:/var/lib/rabbitmq
|
||||
configs:
|
||||
- source: rabbitmq_conf
|
||||
target: /etc/rabbitmq/conf.d/90-messenger.conf
|
||||
|
||||
migrate:
|
||||
image: &ci-image mtusi-messenger:${CI_IMAGE_TAG:?CI_IMAGE_TAG is not set}
|
||||
volumes: !reset []
|
||||
configs: &config-toml
|
||||
- source: config_toml
|
||||
target: /app/config.toml
|
||||
|
||||
api:
|
||||
image: *ci-image
|
||||
volumes: !reset []
|
||||
configs: *config-toml
|
||||
|
||||
cleaner:
|
||||
image: *ci-image
|
||||
volumes: !reset []
|
||||
configs: *config-toml
|
||||
|
||||
relay:
|
||||
image: *ci-image
|
||||
volumes: !reset []
|
||||
configs: *config-toml
|
||||
|
||||
worker:
|
||||
image: *ci-image
|
||||
volumes: !reset []
|
||||
configs: *config-toml
|
||||
|
||||
haproxy:
|
||||
ports: !reset []
|
||||
volumes: !reset []
|
||||
configs:
|
||||
- source: haproxy_cfg
|
||||
target: /usr/local/etc/haproxy/haproxy.cfg
|
||||
|
||||
# файлы по умолчанию 0444 и root: непривилегированные пользователи
|
||||
# контейнеров читают, но не меняют — как read_only у bind mount
|
||||
configs:
|
||||
config_toml:
|
||||
environment: CI_CONFIG_TOML
|
||||
valkey_conf:
|
||||
environment: CI_VALKEY_CONF
|
||||
s3_bootstrap:
|
||||
environment: CI_S3_BOOTSTRAP
|
||||
rabbitmq_conf:
|
||||
environment: CI_RABBITMQ_CONF
|
||||
haproxy_cfg:
|
||||
environment: CI_HAPROXY_CFG
|
||||
@@ -0,0 +1,39 @@
|
||||
# Окружение шага job application (.github/workflows/application.yml),
|
||||
# подключается через «.» из корня репозитория после make env_setup.
|
||||
# Содержимое конфигов — в переменные для configs override
|
||||
# .github/ci/compose.yml. $(cat …) срезает перевод строки в конце файла,
|
||||
# поэтому он возвращается: копия побайтно равна файлу, а HAProxy без него
|
||||
# конфиг не принимает («Missing LF on last line»). Значения не печатаются.
|
||||
nl='
|
||||
'
|
||||
CI_CONFIG_TOML="$(cat config.toml)$nl"
|
||||
CI_VALKEY_CONF="$(cat infra/valkey/valkey.conf)$nl"
|
||||
CI_S3_BOOTSTRAP="$(cat infra/s3/bootstrap.sh)$nl"
|
||||
CI_HAPROXY_CFG="$(cat infra/haproxy/haproxy.cfg)$nl"
|
||||
CI_RABBITMQ_CONF="$(cat infra/rabbitmq/rabbitmq.conf)$nl"
|
||||
export CI_CONFIG_TOML CI_VALKEY_CONF CI_S3_BOOTSTRAP CI_HAPROXY_CFG CI_RABBITMQ_CONF
|
||||
|
||||
# готовность стенда через LB: /health/ready отвечает 200 от API_REPLICAS
|
||||
# (из .env, по умолчанию 2) разных реплик — X-Instance-Id. Срок 60 с:
|
||||
# make replicas ждёт healthy контейнеров, а слот LB включается ещё через
|
||||
# rise проверок
|
||||
wait_replicas() {
|
||||
want=$(sed -n 's/^API_REPLICAS=//p' .env)
|
||||
want=${want:-2}
|
||||
seen=""
|
||||
deadline=$(($(date +%s) + 60))
|
||||
while [ "$(date +%s)" -lt "$deadline" ]; do
|
||||
reply=$(curl -s -o /dev/null -w '%{http_code} %header{x-instance-id}' \
|
||||
"$BASE_URL/health/ready" || true)
|
||||
case "$reply" in
|
||||
"200 "?*) seen=$(printf '%s\n%s\n' "$seen" "${reply#200 }" | sort -u | grep .) ;;
|
||||
esac
|
||||
if [ "$(printf '%s\n' "$seen" | grep -c .)" -ge "$want" ]; then
|
||||
echo "LB ready: $(printf '%s ' $seen)"
|
||||
return 0
|
||||
fi
|
||||
sleep 0.5
|
||||
done
|
||||
echo "LB: $(printf '%s\n' "$seen" | grep -c .) of $want replicas ready in 60 s" >&2
|
||||
return 1
|
||||
}
|
||||
@@ -0,0 +1,144 @@
|
||||
# Job приложения (CONTRIBUTING.md, «CI»): сборка образа, стенд и его
|
||||
# готовность через LB, make check и make test, затем проверки, которым
|
||||
# хватает сети стенда: приватность bucket для анонима, make validate,
|
||||
# собственные тесты, сохранность после рестарта и отказ реплики. Workflow
|
||||
# skeleton contracts.yml проверяет только контракт и не меняется.
|
||||
# Раннер Gitea (act_runner) запускает job в контейнере на том же Docker,
|
||||
# что и стенд: конфиги и порты — override .github/ci/compose.yml, к LB job
|
||||
# ходит по сети стенда. Секретов CI не получает: пароли и ключи — случайные
|
||||
# из make env_setup и живут только в прогоне. pull_request_target не
|
||||
# используется (CONTRIBUTING.md). Нет make s3_check, test_isolated и
|
||||
# failure_checks: им нужны порты на хосте; их результат — evidence/.
|
||||
name: Application
|
||||
on: [push, pull_request, workflow_dispatch]
|
||||
permissions:
|
||||
contents: read
|
||||
# прогоны репозитория по очереди и без отмены: отменённый посреди прогона
|
||||
# job оставил бы стенд на общем хосте раннера, а уборка хвостов не должна
|
||||
# задеть стенд соседнего прогона
|
||||
concurrency:
|
||||
group: application-${{ github.repository }}
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
application:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 40
|
||||
env:
|
||||
# свой проект, volumes и образ у каждого прогона
|
||||
COMPOSE_PROJECT_NAME: mtusi-lab5-safronov-ci-${{ github.run_id }}
|
||||
COMPOSE_FILE: docker-compose.yml:.github/ci/compose.yml
|
||||
CI_IMAGE_TAG: safronov-ci-${{ github.run_id }}
|
||||
# LB по имени сервиса в сети стенда, порт — APP__PORT из .env.example
|
||||
BASE_URL: http://haproxy:8080
|
||||
steps:
|
||||
- name: Checkout
|
||||
# ровно commit прогона; репозиторий публичный, токен не нужен.
|
||||
# Адрес Gitea — литералом: github.server_url здесь внутренний
|
||||
# http://gitea:3000, и контейнер job его не резолвит
|
||||
run: |
|
||||
git init -q .
|
||||
git remote add origin "https://gitea.privcloud.tech/${{ github.repository }}.git"
|
||||
git fetch -q --depth=1 origin "${{ github.sha }}"
|
||||
git checkout -q --detach FETCH_HEAD
|
||||
git log --oneline -1
|
||||
|
||||
- name: Runner
|
||||
run: |
|
||||
docker info --format 'docker {{.ServerVersion}}, {{.OSType}}/{{.Architecture}}, {{.NCPU}} CPU, {{.MemTotal}} B'
|
||||
docker compose version
|
||||
python3 -V
|
||||
|
||||
- name: Remove stands of interrupted runs
|
||||
# только проекты этого workflow: прогон, прерванный без уборки
|
||||
# (сбой раннера), оставил бы их на хосте
|
||||
run: |
|
||||
for p in $(docker ps -a --format '{{.Label "com.docker.compose.project"}}' | grep '^mtusi-lab5-safronov-ci-' | sort -u || true); do
|
||||
echo "remove leftover stand $p"
|
||||
docker ps -aq --filter "label=com.docker.compose.project=$p" | xargs -r docker rm -f >/dev/null
|
||||
docker volume ls -q --filter "label=com.docker.compose.project=$p" | xargs -r docker volume rm >/dev/null
|
||||
docker network ls -q --filter "label=com.docker.compose.project=$p" | xargs -r docker network rm >/dev/null || true
|
||||
done
|
||||
|
||||
- name: Build and start the stand
|
||||
run: |
|
||||
make env_setup
|
||||
. .github/ci/stand-env.sh
|
||||
docker compose config --quiet
|
||||
make run_docker
|
||||
make replicas
|
||||
docker network connect "${COMPOSE_PROJECT_NAME}_default" "$HOSTNAME"
|
||||
wait_replicas
|
||||
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'
|
||||
|
||||
- name: make check and make test
|
||||
run: |
|
||||
make check
|
||||
make test
|
||||
|
||||
- name: Bucket is closed to anonymous requests
|
||||
# без подписи: список bucket и объектов — 403. Полная проверка
|
||||
# приватности — make s3_check (evidence/s3/privacy.md)
|
||||
run: |
|
||||
s3="http://s3:$(sed -n 's/^S3_PORT=//p' .env)"
|
||||
bucket=$(sed -n 's/^S3__BUCKET=//p' .env)
|
||||
for url in "$s3/" "$s3/$bucket" "$s3/$bucket?list-type=2"; do
|
||||
code=$(curl -s -o /dev/null -w '%{http_code}' "$url")
|
||||
echo "anonymous GET $url -> $code"
|
||||
test "$code" = 403
|
||||
done
|
||||
|
||||
- name: Install uv
|
||||
# та же версия, что в Dockerfile
|
||||
run: |
|
||||
python3 -m venv "$RUNNER_TEMP/uv"
|
||||
"$RUNNER_TEMP/uv/bin/pip" install -q uv==0.12.17
|
||||
echo "$RUNNER_TEMP/uv/bin" >> "$GITHUB_PATH"
|
||||
|
||||
- name: make validate
|
||||
# полная проверка OpenAPI и примеров, как в contracts.yml skeleton:
|
||||
# на этом раннере он не доходит до проверок — actions/checkout
|
||||
# берёт внутренний адрес Gitea (http://gitea:3000)
|
||||
run: |
|
||||
uv sync -q
|
||||
make validate PYTHON=.venv/bin/python
|
||||
|
||||
- name: make service_test
|
||||
# без хранилищ и docker: фейки; service_test_db нужен порт PostgreSQL
|
||||
# на хосте, в CI его нет (design change unit-of-work, решение 13)
|
||||
run: make service_test
|
||||
|
||||
- name: make student_test
|
||||
# через LB: тесты реплик выполняются, проверки отказов — нет
|
||||
run: make student_test
|
||||
|
||||
- name: make test-persistence
|
||||
run: |
|
||||
. .github/ci/stand-env.sh
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||||
wait_replicas
|
||||
|
||||
- name: make test-failover, stop and kill
|
||||
# остановленную реплику возвращает make replicas (те же ID)
|
||||
run: |
|
||||
. .github/ci/stand-env.sh
|
||||
log="$RUNNER_TEMP/stop-one.log"
|
||||
STOP_ONE_LOG="$log" make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||||
make replicas
|
||||
wait_replicas
|
||||
STOP_ONE_LOG="$log" STOP_MODE=kill make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||||
make replicas
|
||||
wait_replicas
|
||||
cat "$log"
|
||||
|
||||
- name: Stand logs
|
||||
if: failure()
|
||||
run: |
|
||||
if [ -f .env ]; then docker compose ps -a; docker compose logs --no-color --tail=200; fi
|
||||
|
||||
- name: Remove the stand
|
||||
if: always()
|
||||
run: |
|
||||
docker network disconnect "${COMPOSE_PROJECT_NAME}_default" "$HOSTNAME" 2>/dev/null || true
|
||||
if [ -f .env ]; then docker compose down -v --remove-orphans; fi
|
||||
docker image rm "mtusi-messenger:$CI_IMAGE_TAG" >/dev/null 2>&1 || true
|
||||
+23
@@ -2,6 +2,7 @@
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
config.toml
|
||||
secrets/
|
||||
certs/private/
|
||||
*.key
|
||||
@@ -28,5 +29,27 @@ 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-*/
|
||||
# make bench_uploads_quick: то же для профиля загрузок
|
||||
evidence/uploads/quick-*/
|
||||
# make bench_reconcile_quick: то же для профиля сверки
|
||||
evidence/reconcile/quick-reconcile-*/
|
||||
# make bench_queue_quick: то же для профиля очереди
|
||||
evidence/queue/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.
|
||||
|
||||
@@ -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/
|
||||
@@ -0,0 +1 @@
|
||||
3.12
|
||||
@@ -0,0 +1,822 @@
|
||||
# MTUSI Messenger
|
||||
|
||||
REST API мессенджера (пользователи, чаты, история сообщений). Этот код
|
||||
переносится через все семь лабораторных курса и на каждой обрастает
|
||||
инфраструктурой. Текущая работа — **лаба 5** (`lab.json`): брокер
|
||||
RabbitMQ 4 (выбор пользователя), отдельный worker, состояния вложения
|
||||
`queued` / `processing` / `ready` / `failed` и преобразование изображений;
|
||||
загрузка отвечает `202` (`README.md`, `COURSE.md`, переход 4 → 5,
|
||||
`contracts/README.md`, «Фоновая обработка (с lab5)»,
|
||||
`contracts/attachment-states.md`, `contracts/jobs.schema.json`). Цель —
|
||||
оценка 5, трек 1 «Очередь под перегрузкой» (выбор пользователя).
|
||||
Предупреждения о хосте, которые явно не влияют на результат замера, прогон
|
||||
не останавливают (указание пользователя 2026-10-31). Решения, принятые
|
||||
без пользователя, и открытые вопросы — `QUESTIONS.md`. Фоновая обработка
|
||||
(уровень 3) — change `async-attachments` (заархивирован 2026-10-31,
|
||||
`openspec/changes/archive/2026-10-31-async-attachments/`): загрузка — 202
|
||||
после staging, задания в PostgreSQL и подтверждения брокера, worker на
|
||||
образе API, thumbnail, очередь RabbitMQ 4, новые capability
|
||||
`attachment-processing` и `message-broker`. Надёжность конвейера
|
||||
(уровень 4) — change `pipeline-reliability` (заархивирован 2026-10-31,
|
||||
`openspec/changes/archive/2026-10-31-pipeline-reliability/`, новая capability `job-outbox`): outbox и
|
||||
relay вместо публикации в запросе, варианты `crop` и `optimized`, лимиты в процессе
|
||||
обработки на задание, backoff с jitter, реестр `failed` и replay, аренда и fencing,
|
||||
prefetch, очистка staging. Единица работы — change `unit-of-work` (заархивирован 2026-11-01,
|
||||
`openspec/changes/archive/2026-11-01-unit-of-work/`, полный UoW по Cosmic Python, решение
|
||||
пользователя, новая capability `unit-of-work`): сервисы на абстракциях
|
||||
`src/core/ports/`, соединение на шаг, быстрые тесты `service-tests/`. Очередь под
|
||||
перегрузкой (уровень 5) — change `track1-queue-overload` (заархивирован 2026-11-02,
|
||||
`openspec/changes/archive/2026-11-02-track1-queue-overload/`, новая capability
|
||||
`queue-overload`): предел незавершённых заданий на входе API, профиль `make bench_queue`,
|
||||
гипотезы H1–H9 в `REPORT.md`; основная метка `baseline4` — на закоммиченном коде. Код перенесён из
|
||||
лабы 4 (репозиторий `mtusi2026lab4-safronov`, ветка
|
||||
`solution/bvt2301-safronov`, commit `2546deb`) по разделу «Переход в
|
||||
следующую лабу»; отчёт и evidence лабы 4 остались в её репозитории. Дальше
|
||||
— что досталось от лабы 4. S3 в стенде — change `s3-storage` (заархивирован
|
||||
2026-10-20, `openspec/changes/archive/2026-10-20-s3-storage/`):
|
||||
SeaweedFS с приватным bucket, bootstrap и клиент `src/infra/s3/`.
|
||||
Вложения — change `attachments` (заархивирован 2026-10-21,
|
||||
`openspec/changes/archive/2026-10-21-attachments/`): ручки загрузки,
|
||||
метаданных и скачивания, структурная проверка PNG/JPEG,
|
||||
`attachment_ids` в сообщениях, таблицы `attachments` и
|
||||
`message_attachments`. Согласованность БД и S3 — change
|
||||
`upload-consistency` (заархивирован 2026-10-21,
|
||||
`openspec/changes/archive/2026-10-21-upload-consistency/`): компенсация
|
||||
в загрузке (удаление объекта при известном исходе, 503 вместо 500),
|
||||
уборщик незавершённых загрузок — сервис `cleaner` (`python -m
|
||||
src.cleaner`, grace 900 с, свой пользователь S3 «чтение и удаление»),
|
||||
частичный индекс строк `pending`, новая capability
|
||||
`storage-consistency`. Память и сроки загрузки — change
|
||||
`upload-memory` (заархивирован 2026-10-22,
|
||||
`openspec/changes/archive/2026-10-22-upload-memory/`): места загрузки на
|
||||
процесс API (`[uploads]`: 4 места, очередь 16, ожидание 5 с, затем 429
|
||||
`rate_limited` с `Retry-After`), срок тела 30 с (400), одна копия тела
|
||||
при PUT, буферы сокетов реплики 512 KiB и LB 256 / 128 KiB, `timeout server`
|
||||
LB пути загрузки 30 с, дренаж замены 90 с, профиль `uploads` стенда
|
||||
`bench/`. Сверка bucket и БД (трек 2) — change `track2-reconciler`
|
||||
(заархивирован 2026-10-22,
|
||||
`openspec/changes/archive/2026-10-22-track2-reconciler/`): сверка в
|
||||
процессе уборщика (`make reconcile [APPLY=1]` и плановая), классы
|
||||
расхождений, пометка потерянного оригинала `lost_at`, список по
|
||||
префиксу у ключа уборщика. Изредка 503 на загрузке — change
|
||||
`fix-upload-put-flake` (заархивирован 2026-10-23,
|
||||
`openspec/changes/archive/2026-10-23-fix-upload-put-flake/`): у клиента
|
||||
S3 нет срока чтения aiohttp (он переживал ответ и портил соединение в
|
||||
пуле), срок — только `asyncio.timeout` вызова и блока; четвёртый API
|
||||
стенда отказов со сроком S3 1 с (`test_upload_after_idle_s3`), проба
|
||||
`driver.py s3-idle`. Стоимость сверки (трек 2) — change
|
||||
`track2-reconcile-cost` (заархивирован 2026-10-23,
|
||||
`openspec/changes/archive/2026-10-23-track2-reconcile-cost/`): стратегия «HEAD на строку» и
|
||||
глубокая сверка (класс «другой SHA-256», пометку снимает только тот же
|
||||
SHA-256) в разовом проходе, предел скорости `[reconciler]
|
||||
max_objects_per_second` (2000 объектов S3/с), отказ по пределу без
|
||||
лишних перепроверок, стоимость прохода в его итоге, профиль `reconcile`
|
||||
стенда `bench/`. Рабочий план лабы 4 (`PLAN.md`) удалён после закрытия
|
||||
всех changes: итоги — в `REPORT.md` репозитория лабы 4, открытые вопросы
|
||||
преподавателю — в его разделе «Открытые вопросы преподавателю», последняя
|
||||
версия плана — там же, `git show fd03b84:PLAN.md`. Из лабы 2: PostgreSQL
|
||||
как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш
|
||||
карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API
|
||||
(`replicas-lb`), `X-Instance-Id` и обязательный `Idempotency-Key`
|
||||
(`instance-id-idempotency`), замеренная цепочка таймаутов
|
||||
(`graceful-failover`), поочерёдная замена реплик `make rolling_update`
|
||||
(`rolling-update`), ранний обработчик SIGTERM (`fix-known-issues`),
|
||||
строгие курсор и UUID на входе (`strict-id-validation`). Стенд `bench/`
|
||||
— трек 2 лабы 2 (план запроса и восстановление), профили `failover` и
|
||||
`rollout`, серии трека 1 лабы 3 (`scaling-bench`, `scaling-improvement`,
|
||||
`profile-resources`). Changes лаб 2 и 3 и `s3-storage`, `attachments`,
|
||||
`upload-consistency`, `upload-memory`, `track2-reconciler`,
|
||||
`fix-upload-put-flake`, `track2-reconcile-cost` лабы 4, `async-attachments`,
|
||||
`pipeline-reliability`, `unit-of-work` и `track1-queue-overload` лабы 5 — в
|
||||
`openspec/changes/archive/`, активных нет (новые capability: с `s3-storage` —
|
||||
`object-storage`, с `attachments` — `attachments`, с
|
||||
`upload-consistency` — `storage-consistency`, с `async-attachments` —
|
||||
`attachment-processing`, `message-broker`, с `pipeline-reliability` — `job-outbox`,
|
||||
с `unit-of-work` — `unit-of-work`, с `track1-queue-overload` — `queue-overload`);
|
||||
в `KNOWN_ISSUES.md` десять открытых записей (смесь версий при замене реплик на первый
|
||||
релиз с обработкой; bootstrap после удаления
|
||||
bucket; уборщик
|
||||
удаляет объект зависшей загрузки по ключу вне своего префикса; 408 LB на медленные заголовки текстом HAProxy; поля `float` настроек принимают `inf`; 504 LB на метаданных и скачивании вложения при зависшем PostgreSQL; ложный FAIL `driver.py reconcile-cycle` на наполненном стенде; память S3 на долго живущем стенде; граница живой загрузки уборщика без закрытия соединения; остановка API при замороженном PostgreSQL дольше срока контейнера). Отчёт, evidence и рабочий план лабы 3 остались в её
|
||||
репозитории (`REPORT.md`, `evidence/`, `git show 063eedb:PLAN.md`).
|
||||
Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings,
|
||||
structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
|
||||
(клиент S3).
|
||||
|
||||
Репозиторий — 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/` (кроме своего CI job по `CONTRIBUTING.md`,
|
||||
«CI»: `.github/workflows/application.yml` и `.github/ci/`),
|
||||
`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; быстрые тесты сервисов на фейках и настоящая
|
||||
единица работы — только в `service-tests/` вне образа
|
||||
(`.claude/rules/service-tests.md`).
|
||||
- Единица работы (change `unit-of-work`, `service-layer.md`): работа сервиса с
|
||||
PostgreSQL — `async with self.uow:`, один блок — одна транзакция, явный
|
||||
`await self.uow.commit()`, выход без него — откат. Вложенный блок и repo вне
|
||||
блока или после фиксации — ошибка. В сервисах нет `AsyncSession`, SQLAlchemy,
|
||||
реализаций repo и глобалов хранилищ: они зависят от `src/core/ports/`, реализации
|
||||
выбирают точки входа. Экземпляр — на задачу: запрос, доставка worker, сервис в
|
||||
последовательных процессах. Соединение занято на шаг, вход и операция — разные
|
||||
блоки; `[database] request_timeout_seconds` — срок блока с откатом, а на
|
||||
JSON-роутерах ещё и общий срок запроса (`request_deadline`). Новый метод repo —
|
||||
порт, SQL, фейк и строка `service-tests/repo_contract.py`.
|
||||
- Упавший тест — сначала разбор, потом правка. Воспроизвести падение,
|
||||
прочитать вывод и назвать причину: дефект приложения, ошибка в самом
|
||||
тесте или стенд (чужой сервис на порту, старый образ, не тот
|
||||
`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,
|
||||
4 и 5.
|
||||
- Лаба 3: ≥2 взаимозаменяемые реплики `api` за HAProxy — единственной
|
||||
публичной точкой входа; порты реплик наружу не публикуются, sticky
|
||||
session нет. В памяти процесса нет ничего, от чего зависит
|
||||
корректность: сессии, данные и ключи идемпотентности — в Postgres,
|
||||
Valkey — общий кэш неизменяемых карточек, S3 — байты вложений. В
|
||||
каждом ответе API —
|
||||
`X-Instance-Id`. `POST` сообщения требует `Idempotency-Key`; ключ и
|
||||
сообщение пишутся в одной транзакции (`api-contract.md`,
|
||||
`service-layer.md`). Миграции — однократно, отдельным сервисом, не
|
||||
репликами, и только расширяют схему: старые реплики работают на новой
|
||||
(`migrations.md`). Новый код доходит до реплик без простоя через `make
|
||||
rolling_update`. Стенд и отказы — `balancer.md`. В каждом процессе
|
||||
uvicorn по-прежнему один worker: масштабирование — числом реплик.
|
||||
Всё это сохраняется в лабах 4 и 5.
|
||||
- Лаба 4, S3 (change `s3-storage`): SeaweedFS в стенде, образ
|
||||
закреплён тегом и digest, volume `s3_data`. Bucket приватен с первой
|
||||
секунды: административная пара — только у сервера, служебные
|
||||
серверы — на loopback контейнера, gRPC шлюза закрыт ключом подписи.
|
||||
Bucket, политику и пользователя API создаёт одноразовый
|
||||
`s3-bootstrap` (идемпотентно, сам проверяет приватность), реплики ждут
|
||||
его, как миграций. У API — только ключи своего пользователя (чтение,
|
||||
запись, удаление объектов своего bucket). Срок вызова клиента S3 —
|
||||
только `asyncio.timeout` вызова и блока, `read_timeout` aiohttp
|
||||
выключен (change `fix-upload-put-flake`, `infra.md`). `/health/ready`
|
||||
S3 не проверяет. Приватность вне API — `make s3_check` (`docker.md`,
|
||||
`infra.md`, design change `s3-storage`).
|
||||
- Лаба 4, согласованность БД и S3 (change `upload-consistency`): строка
|
||||
`pending` с ключом — до PUT; после записанного объекта сбой до
|
||||
отправки COMMIT `ready` — объект удаляется до ответа 503, исход COMMIT
|
||||
неизвестен — объект не трогается (`service-layer.md`). Незавершённые
|
||||
загрузки убирает только уборщик — отдельный сервис `cleaner` на образе
|
||||
API, а не реплики: строки `pending` старше `[cleaner]
|
||||
pending_grace_seconds` (900 с; больше границы живой загрузки 17 с по
|
||||
формуле, с закрытием соединения до 21 с, иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`, в два шага:
|
||||
пометка строки (`updated_at`) отдельной транзакцией, затем объект и
|
||||
строка одной транзакцией под блокировкой (объект раньше строки);
|
||||
помеченную строку `mark_queued` в `queued` не переводит,
|
||||
`queued`, `processing`, `ready` и `failed` уборщик не трогает, удаляет
|
||||
`staging_key`, а у строки прежней версии `object_key`. У уборщика свой пользователь S3 — только
|
||||
чтение и удаление объектов своего bucket, ключи `S3_CLEANER_*` только
|
||||
у него и bootstrap (`docker.md`, `settings.md`).
|
||||
- Лаба 4, сверка bucket и БД (change `track2-reconciler`, трек 2): её
|
||||
делает процесс уборщика — разовая `make reconcile [APPLY=1]` (по
|
||||
умолчанию dry-run; коды 0 / 3 / 1 / 2) и плановая в сервисе `cleaner`
|
||||
при старте и раз в `[reconciler] interval_seconds` (3600 с) с
|
||||
исправлением. Удаляется только объект без строки старше grace и
|
||||
зависшая загрузка (шагом уборщика); строки `ready`, объект, на который
|
||||
ссылается строка, и чужой ключ — никогда; строку с ключом вне
|
||||
`<база>/attachments/` сверка только называет (чужой объект): её объект
|
||||
не читает, строку не помечает и не убирает. Сигнал — перед каждым
|
||||
вызовом хранилища (остановка ждёт ≤ 5 с S3 или ≤ 6 с шага БД). Grace — тот же `[cleaner]
|
||||
pending_grace_seconds`, по `LastModified` объекта и времени строки;
|
||||
перед каждым действием — перепроверка в БД и HEAD, отсутствие объекта —
|
||||
только при живом bucket; больше `[reconciler] max_changes` (100)
|
||||
изменений — ни одного и код 3. Потерянный оригинал помечается
|
||||
(`attachments.lost_at`): скачивание — 404, метаданные — 200, ссылка —
|
||||
201 (вопрос преподавателю, `REPORT.md`, «Открытые вопросы
|
||||
преподавателю»). Уборщику разрешён список только
|
||||
с префиксом `<база>/attachments/` (`S3_CLEANER_LIST_PREFIX` у
|
||||
bootstrap). На время восстановления базы уборщик останавливают
|
||||
(`docker.md`). С change `track2-reconcile-cost`: проход затрагивает в
|
||||
среднем не больше `[reconciler] max_objects_per_second` (2000; 0 — без
|
||||
предела) объектов S3 в секунду, паузу прерывает сигнал; разовый проход
|
||||
— ещё `--strategy head` (выборка строки на объект, HEAD на строку, без
|
||||
множества ключей) и `--deep` (GET и SHA-256: «другой SHA-256» помечается
|
||||
потерянным), плановая — всегда `batch`, поверхностная; «оригинал
|
||||
вернулся» — только тот же SHA-256; с `--apply`, как только
|
||||
подтверждённых изменений больше предела, остальные кандидаты не
|
||||
перепроверяются (`unchecked`); итог называет стоимость — объекты и
|
||||
запросы S3, байты, сеансы, длительность шагов (`service-layer.md`).
|
||||
- Лаба 4, память загрузок (change `upload-memory`): память загрузок
|
||||
реплики ограничена числом мест, а не числом клиентов. Место берётся
|
||||
после проверок 401/400/404/415/413 и до чтения тела, держится до
|
||||
ответа и освобождается при любом исходе; без места — очередь процесса
|
||||
до `[uploads] max_waiting` не дольше `wait_timeout_seconds`, затем 429
|
||||
с `Retry-After` без строки и объекта. Тело — не дольше
|
||||
`body_timeout_seconds` с момента места (иначе 400), в PUT уходит тот же
|
||||
`BytesIO` без второй копии (`service-layer.md`). Ожидание, тело и
|
||||
проверка — до строки `pending`: граница B уборщика прежняя (17 с по
|
||||
формуле, с закрытием соединения до 21 с: `KNOWN_ISSUES.md`).
|
||||
Буфер приёма сокетов `api` — 512 KiB (`sysctls`), буфер отправки LB к
|
||||
реплике — 256 KiB, буфер приёма LB от клиента — 128 KiB; `timeout server` пути загрузки 30 с, остальных — 10
|
||||
с; `ROLLOUT_DRAIN_TIMEOUT` 90 с (`balancer.md`, `docker.md`).
|
||||
- Лаба 5, фоновая обработка (change `async-attachments`, `worker.md`): ответ 202
|
||||
— только после оригинала в staging (`<база>/staging/<id>/original`) и `queued` с
|
||||
заданием одной транзакцией. Ack — после устойчивого эффекта, повтор — те же
|
||||
ключи, ключ эффекта `(attachment_id, pipeline_version, variant)`. Брокер, relay и
|
||||
worker не входят в `/health/ready`, без них работают загрузка (202), текст,
|
||||
история, метаданные и готовые байты. Очередь — `<база>.attachment.process.v1`,
|
||||
durable, сообщения persistent, в них только id и служебные поля
|
||||
(`contracts/jobs.schema.json`).
|
||||
- Лаба 5, надёжность конвейера (change `pipeline-reliability`, `worker.md`):
|
||||
брокера в пути запроса нет, у реплик API ни клиента, ни пароля; намерения
|
||||
(`attachment_jobs`, `state = 'queued' AND published_at IS NULL`) публикует
|
||||
relay (`python -m src.relay`, отдельный сервис) с подтверждением, отметка — только
|
||||
подтверждённым; доставка at least once, дубль — no-op. Сообщение — подсказка, истина
|
||||
в строке: дубль при живой аренде и сообщение раньше срока подтверждаются без
|
||||
эффекта, номер попытки — fencing. Аренда `job_timeout + lease_margin` без пульса,
|
||||
истёкшую возвращает relay. Следующую попытку публикует relay по `next_attempt_at`
|
||||
(backoff с jitter), пауза места конкуренции не занимает. Декодирует и делает три
|
||||
варианта только отдельный процесс на задание (`src/worker/render.py`, лимиты CPU и
|
||||
адресного пространства, без секретов в окружении): Pillow нет ни в репликах, ни в
|
||||
процессе worker. Постоянная ошибка — `failed` сразу, реестр — строки `failed`, возврат
|
||||
— `make replay` с записью аудита и новым бюджетом (`attempt_base`). Staging убирает
|
||||
только уборщик: у `ready` — следующим проходом, у `failed` — по `[cleaner]
|
||||
staging_retention_seconds` вместе с частично записанными объектами, блокировка `FOR
|
||||
NO KEY UPDATE`; сверка находит `orphan_staging`. Лимиты 0,25 CPU / 256 МБ у relay, пул
|
||||
1. Цепочка LB — 26 с и 73 с (`balancer.md`).
|
||||
- Лаба 5, предел принятой работы (change `track1-queue-overload`, спек `queue-overload`,
|
||||
`service-layer.md`): загрузка при `[uploads] max_unfinished_jobs` (250, 0 — без предела)
|
||||
и больше незавершённых заданий стенда (`queued`, `processing`) получает 429
|
||||
`rate_limited` с `Retry-After: 5`, без тела и места, ни строки, ни объекта. Порядок: 404
|
||||
→ 415 → 413 → 429 предела → 429 мест. Считает все реплики по PostgreSQL одним запросом
|
||||
в первом блоке (три частичных индекса с `LIMIT` на группу, `count_unfinished`), шаг
|
||||
с БД не прибавляется, цепочка LB прежняя. Предел мягкий: превышение — только загрузки в
|
||||
полёте. Текст, история, метаданные, готовые байты и `/health/ready` от него не
|
||||
зависят. Профиль `uploads` и четыре прежних API стенда отказов — с пределом 0.
|
||||
- `.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` |
|
||||
| 2026-10-20 | Лаба 4: «пустой текст» сообщения — это и `""`, и текст только из пробельных символов. Допустимы: вложение + непустой текст, без вложения + непустой текст, вложение + пустой текст. Значит, `" "` с хотя бы одним вложением — 201, без вложений — 400 | спек `messages` (change `attachments`, сценарий «Пробелы с вложением»), design `attachments`, решение 8; `.claude/rules/api-contract.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 — вложения: сырые bytes PNG/JPEG ≤10 MiB и ≤40 млн пикселей, на лабе 4 `201 Attachment` (`ready`), с лабы 5 — `202` (`queued`), `attachment_ids` в сообщении, download только участникам; пустой текст (в том числе из пробелов) — только с вложением (согласование 2026-10-20); разделы lab5+ — на будущее; как это сделано — `api-contract.md`, «Вложения (лаба 4)» |
|
||||
| `contracts/examples.json`, `infrastructure.json` | примеры тел (проверяет `make validate`); роли инфраструктуры лабы: api ×2+ без локального состояния, postgres, load_balancer, s3 (одно из MinIO, SeaweedFS, RustFS; приватный bucket, persistent volume); Redis/Valkey — необязательно; внутренние порты реплик в обход LB не публикуются |
|
||||
| `lab.json` | номер лабы (5); по нему `tests/client.py` выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность; с лабы 4 — вложение, 201 вместо 202 с лабы 5) |
|
||||
| `tests/smoke.py`, `tests/client.py` | публичный сквозной сценарий `make test`; с лабы 4 — загрузка `tests/fixtures/sample.png`, сообщение с `attachment_ids`, SHA-256 скачанного оригинала, 404 постороннему; что он проверяет и чего нет — `tests/README.md` |
|
||||
| `tests/fixtures/`, `tests/image_probe.py` | синтетический PNG 320×200 и его SHA-256 (`tests/fixtures/README.md`); размеры JPEG без внешних библиотек (thumbnail — с лабы 5) |
|
||||
| `tests/resilience.py` | `make test-persistence`: данные, прежний токен и с лабы 4 — тот же оригинал вложения после 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` проверяет только контракт, приложение не запускает; сборку, стенд и `make test` — свой job `workflows/application.yml` (карта кода) |
|
||||
| `Dockerfile.example` | опорные шаги Dockerfile, не рабочий файл |
|
||||
| `.env.example` | шаблон `.env`; «логические» имена skeleton (lab2, lab3 `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` и новые lab4 `S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`) перечислены в шапке, их соответствие — в `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/**`, `src/core/ports/**`: порты и repo-классы |
|
||||
| `dto.md` | `src/schemas/**` |
|
||||
| `infra.md` | `src/infra/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе), клиент S3 (без повторов, срок на вызов, перевод ошибок) и другие клиенты |
|
||||
| `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/**`, `.github/ci/**`, `.github/workflows/application.yml`: мультистейдж, non-root, пины, healthcheck, стенд compose, S3 и bootstrap, секреты по сервисам, 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, особый стенд |
|
||||
| `service-tests.md` | `service-tests/**`: быстрые тесты на фейках, контракт repo на фейке и на SQL, временная база |
|
||||
| `worker.md` | `src/worker/**`, `src/relay/**`, `src/infra/render/**`, `src/core/services/attachment_processing.py`, `attachment_relay.py`, `attachment_replay.py`, `src/utils/image_variants.py`: worker, relay, процесс обработки, claim и fencing, аренда, бюджет, лимиты, варианты, replay |
|
||||
| `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-lab5` со своей базой. После `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` и `make start_s3`, затем `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` и шестью секретами S3, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает, но в существующий `.env` дописывает переменные шаблона, которых в нём нет (секреты — случайными, прежние строки не меняются); печатает только имена |
|
||||
| `make run_docker` | `make env_setup` (недостающие файлы и переменные) + `docker compose build` + `up -d`: postgres, valkey, s3 → migrate, s3-bootstrap → api × `API_REPLICAS` (2) и cleaner → haproxy на `127.0.0.1:APP_OUT_PORT`; `config.toml`, `infra/valkey/valkey.conf`, `infra/haproxy/haproxy.cfg` и `infra/s3/bootstrap.sh` монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — `make rolling_update` |
|
||||
| `make stop` / `make down` | остановить / удалить контейнеры compose; volumes с данными остаются; S3 останавливается плавно ~15 с |
|
||||
| `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` каждого ответа и итог по репликам |
|
||||
| `driver.py upload` / `download` | загрузка файла и скачивание оригинала с SHA-256 на любом сервере (`.claude/skills/run-mtusi-messenger/SKILL.md`) |
|
||||
| `driver.py --port <LB> attachment-failover [--mode stop\|kill]` | вложение через LB, `stop-one.sh` принявшей реплики, скачивание через другую (тот же SHA-256), 404 постороннему, затем `make replicas`; доказательство исключения `attachments` «Принявшая реплика остановлена» |
|
||||
| `driver.py --port <LB> attachment-storage` | схема таблиц вложений, вид `object_key`, объект в bucket, анонимный GET — 403, `docker diff` реплик; доказательство исключения «Байты не в БД и не на диске API» |
|
||||
| `driver.py --port <LB> upload-consistency` | согласованность БД и S3 на рабочем стенде (~45 с): загрузка при `pause` S3 и со сбоем фиксации `ready` (триггер на `filename` прогона) — 503, строки `pending` не видны, компенсация удалила объект; `cleaner --once` с grace 30 с убирает обе, объектов без строки нет, готовое вложение цело; `evidence/attachments/consistency.md` |
|
||||
| `driver.py lb-upload-timeouts [--config F]` | сроки LB пути загрузки без стенда (~35 с): `haproxy -c`, временная сеть, HAProxy закреплённого образа с F (по умолчанию `infra/haproxy/haproxy.cfg`) и заглушка реплики `api` на образе API; молчание 12 с до и после тела загрузки — 201, 12 с на другом пути — 504 через ~10 с, 32 с на пути загрузки — 504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта; уборка при любом исходе, код 1 при расхождении; `evidence/uploads/lb-timeouts.md` |
|
||||
| `driver.py --port <LB> s3-idle [--rounds 3]` | клиент S3 после простоя (~40 с, change `fix-upload-put-flake`): проба в реплике стенда (`docker exec -i … python -`, код и ключи образа), варианты «образ» и «эталон» с прежним `read_timeout` aiohttp; раунд — 10 одновременных медленных скачиваний 4 MiB, простой срока вызова + 0,5 с, 12 PUT; взведённые и испорченные соединения пула, PUT прошло и упало (цепочка ошибки, мс), чтение обратно; объекты под `<база>/.s3-idle-probe/` удаляются в `finally`; код 0 — у образа ни порчи, ни упавших PUT, 1 — иначе, 2 — нет стенда; `evidence/s3/idle-connection.md` |
|
||||
| `make reconcile [APPLY=1] [MAX_CHANGES=N] [STRATEGY=head] [DEEP=1] [RATE=R]` | разовая сверка bucket и БД в контейнере уборщика (`docker compose run --rm --no-deps cleaner reconcile [--apply] [--max-changes N] [--strategy batch\|head] [--deep] [--max-objects-per-second R]`): по умолчанию dry-run — записи «Found storage discrepancy» по классам и итог со стоимостью прохода; `APPLY=1` — исправить; `STRATEGY=head` — HEAD на строку, `DEEP=1` — SHA-256 содержимого, `RATE` — предел скорости (0 — без него); 0 — расхождений нет, 3 — остались (чужие объекты, отказ по пределу), 1 — прервана, 2 — конфигурация |
|
||||
| `driver.py --port <LB> reconcile-cycle` | сверка на рабочем стенде (~2 мин): исходный dry-run без расхождений (иначе код 2), расхождения с обеих сторон, dry-run без изменений, 500 → `--apply` → 404 и 200, повтор, удаление чужого объекта, свежий объект после grace, возврат оригинала; `evidence/reconcile/cycle.md` |
|
||||
| `driver.py --port <LB> reconcile-stress [--seconds S] [--clients N]` | `--apply` раз в ~3 с под загрузками и отправками N клиентов S секунд (4 × 40 с): внесённое исправлено, каждое 201 скачивается с тем же SHA-256, повтор — 0; `evidence/reconcile/stress.md` |
|
||||
| `driver.py reconcile-signal [--pace [--apply]]` | только не рабочий проект compose (`COMPOSE_PROJECT_NAME` и др., `mtusi-lab5` — код 2): `pause s3`, разовый `reconcile --apply` отдельным контейнером, `docker stop` через секунду после «Started cleaner» — код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, быстрее 10 с; `unpause` в `finally`. `--pace` (change `track2-reconcile-cost`) — вместо `pause s3` объекты пробы мимо API и `reconcile --max-objects-per-second 1`, `docker stop` через 2 с во время паузы предела скорости — остановка ≤ 1 с, `listed_objects` — ключи страницы; `--pace --apply` (verify W1) — объекты пробы без строки, grace 18 с, `reconcile --apply`, `docker stop` посреди удалений: записей «Fixed» и `fixed` столько же, сколько удалено; объекты удаляются в `finally`; `evidence/reconcile/service.md` |
|
||||
| `make bench_reconcile [RECONCILE_LABEL=...]` | трек 2, стоимость сверки (~50 мин, метка `baseline`; change `track2-reconcile-cost`): стенд `mtusi-bench` с LB, двумя репликами, PostgreSQL, Valkey и S3 с лимитами рабочего стенда, порт метрик шлюза S3 на loopback; наполнение мимо API (`\copy` метаданных, PUT объектов загрузчиком `bench/fill_objects.py`), 1 000 × 1 MiB и 10k → 30k → 100k × 4 KiB с 0,25 % расхождений каждого класса; разовые проходы уборщика (0,25 CPU / 256 МБ, управляемый опыт — 1 CPU): `batch`, `head`, глубокая, фоновая нагрузка с пределом скорости и без, отказ по пределу на образе `Profile.reconcile_before` (`04f8592`, commit переноса лабы 4: ранний отказ уже есть, `bench.md`) и checkout; 3 повтора, найденное сверяется с моделью (иначе отказ), счёт сверки — с метриками шлюза; `evidence/reconcile/<метка>/` (`passes.csv`, `windows.csv`, `summary.md` с H1–H4 и S4, SVG). Перед запуском — проверка хоста (`bench.md`), рабочий стенд — `make stop` |
|
||||
| `make bench_reconcile_quick` | то же на 2 000 × 4 KiB, по одному проходу каждого вида, окна 5 с, S4 с 300 кандидатами (~4 мин: 3,7 мин на шумном хосте), метка `quick-reconcile-<время>`, в git не идёт |
|
||||
| `docker compose run --rm --no-deps cleaner --once` | разовый проход уборщика незавершённых загрузок (grace — `[cleaner]` или `-e CLEANER__PENDING_GRACE_SECONDS=…`, не меньше 18 с): 0 — проход дошёл до конца, 1 — прерван отказом, 2 — неверная конфигурация; журнал сервиса — `docker compose logs --no-log-prefix cleaner` |
|
||||
| `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 run_worker` | worker в консоли (`python -m src.worker`, тот же `.env`, ключи `S3_WORKER_*` в окружении процесса, рецепт без эха); рядом с `make run_dev` |
|
||||
| `make run_relay` | relay в консоли (`python -m src.relay`, те же мосты `.env`); рядом с `make run_dev`: без него задания ждут в PostgreSQL |
|
||||
| `make replay [ATTACHMENT=…] [ERROR_CODE=…] [REASON=…] [LIMIT=…] [APPLY=1] [OPERATOR=…]` | реестр `failed` и возврат работы (`docker compose run --rm --no-deps relay replay …`): без `APPLY=1` только показ; с ним выбор обязателен, иначе код 2; 0 — выполнено или показано, 3 — есть отказы, 1 — отказ PostgreSQL |
|
||||
| `make start_broker` / `make stop_broker` | брокер стенда: `up -d --wait rabbitmq` / `stop rabbitmq` |
|
||||
| `driver.py --port <LB> defense-scenario` | сценарий защиты на рабочем стенде: worker остановлен → 202 → сообщение 201 → 409 → текст 201 → `scripts/restart.sh` → worker → `ready`, оригинал и thumbnail; `id` и `StartedAt`, worker запускается при любом исходе; `evidence/attachments/defense.md` |
|
||||
| `driver.py --port <LB> broker-check [--require-test-queue]` | образ и digest, volume, порт, предел памяти, очередь, остановка брокера; `evidence/broker/stand.md`, `evidence/broker/isolated.md` |
|
||||
| `driver.py --port <LB> worker-process` | PID 1, лимиты, остановка, неверные `WORKER__*`, рестарт хранилищ, остановка на двух дорогих JPEG (быстрее 9,5 с, в том числе при замороженных PostgreSQL и брокере), ~5 мин; `evidence/worker/process.md` |
|
||||
| `driver.py --port <LB> relay-process` | то же у relay: PID 1, нет healthcheck, лимиты, запись о старте, неверные `RELAY__*`, остановка простаивающего, на старте и при замороженном брокере, рестарт хранилищ; `evidence/relay/process.md` |
|
||||
| `driver.py --port <LB> defense-faults` | шаг 4 защиты на рабочем стенде (~4 мин: аренда 70 с): crash после записи объектов и после фиксации до ack, relay убит до публикации и после подтверждения до отметки, replay неудачного и отказ replay готового; триггеры на `filename` прогона снимаются, worker и relay запускаются при любом исходе; `evidence/attachments/defense-faults.md` |
|
||||
| `driver.py --port <LB> pipeline-state` | только чтение, JSON: задания по состояниям, due, ждущие срока, опубликованные и не взятые, истёкшие аренды, возраст старейшего, очередь |
|
||||
| `driver.py --port <LB> worker-memory` | память контейнера worker (~35 с): на девять случаев в пределах контракта два одинаковых файла разом, новая cgroup на случай; `memory.peak`, `VmHWM`, `render_peak`, OOM, сумма пиков меньше 1 ГБ; worker и relay запускаются при любом исходе; `evidence/worker/memory.md` |
|
||||
| `driver.py freeze-sessions [--rounds 6] [--settle 15]` | сессии PostgreSQL и журнал пула после заморозки (~2,5 мин), работает и на рабочем стенде: приложение в процессе одноразового контейнера `api`, PostgreSQL только через TCP-прокси пробы, заморожен прокси, а не сервер; режимы — между блоками и до запросов при пуле 2 и 4; `evidence/storage/freeze-sessions.md` |
|
||||
| `driver.py freeze-lb [--rounds 3]` | только не рабочий проект compose (`COMPOSE_PROJECT_NAME`, по умолчанию `mtusi-lab5-freeze`; `mtusi-lab5` — код 2): сама поднимает стенд с данными в tmpfs (volumes нет) на образе `mtusi-messenger:lab5` и убирает его при любом исходе; `docker pause` PostgreSQL, шесть запросов через LB — 503 за ~8 с, 504 нет, `unpause` в `finally`, сессий не больше пулов (~1,5 мин); раздел `evidence/storage/freeze-sessions.md` |
|
||||
| `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 start_s3` / `make stop_s3` | S3 стенда: `up -d --wait s3`, затем `up --no-deps --exit-code-from s3-bootstrap s3-bootstrap` (код bootstrap — код цели: `--wait` одноразовый сервис не ждёт) / `stop s3` |
|
||||
| `make s3_check` | приватность bucket вне API на запущенном стенде (`driver.py s3-check`): bootstrap в режиме `check` (права ключей API и уборщика, чужой временный bucket, административные запросы), анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети, затем `cleanup`; таблица «где → проверка → ожидаемо → получено», код 1 при нарушении |
|
||||
| `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` — удалить данные стенда (volumes Postgres и S3 называются в запросе) и кэш; только после ввода `yes` |
|
||||
| `make service_test` | быстрые тесты сервисов на фейках (`service-tests/unit`): ветки всех сервисов, архитектура (импорты, сигнатуры порт — реализация — фейк), контракт repo на фейке; без PostgreSQL, Valkey, S3, брокера, docker и сети, секунды (`service-tests.md`) |
|
||||
| `make service_test_db` | `start_db` и `service-tests/db` на временной базе `test_uow_<db>`: настоящая единица работы, тот же контракт repo на SQL, соединение на шаг и общий срок JSON-запроса в процессе (S3 и кэш — фейки), замороженный сервер — TCP-прокси; база удаляется при любом исходе, имя не по шаблону — код 2 |
|
||||
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом `test_<db>/` (`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`, 147 проверок, ~39 мин) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres, Valkey и S3 (с bootstrap), уборщик (grace 20 с, интервал 1 с), пять API — обычный, «тесный» (срок 2 с, пул 1), «узкий по загрузкам», «с коротким сроком S3» (1 с) и «узкий по заданиям» (предел 3; у прочих предел выключен), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volumes удаляются при любом исходе, рабочий не трогается (`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`; сейчас `7f38948` — commit до change `pipeline-reliability`, правило выбора — `bench.md`; commit вне истории — код 2 до стенда, отладка `--from`), та же нагрузка; посреди неё `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_uploads [UPLOADS_LABEL=...]` | уровень 4, память при одновременных загрузках (~50 мин, метка `baseline` по умолчанию; change `upload-memory`): стенд `mtusi-bench` с LB, одной репликой 1 CPU / 512 МБ без swap, PostgreSQL, Valkey и S3 рабочего стенда; варианты «до» (`Profile.uploads_before` — `04f8592`, commit переноса лабы 4: места загрузки уже есть, `bench.md`; `git archive`; commit вне истории — код 2), «без лимита» (1000 мест, без очереди) и «с лимитом» (по умолчанию) × тела PNG ~1 и ~10 MiB × 1 / 10 / 20 / 40 клиентов × 3 повтора, на прогон — новые реплика и volume S3; пик `memory.peak` окна со сбросом (сэмплер `peak`), `anon`, `sock`, OOM, ответы по кодам, загрузок/с, p50/p95/p99, пики S3 и LB, H1–H4 в сводке — `evidence/uploads/<метка>/`. Перед запуском — проверка хоста (`bench.md`), рабочий стенд — `make stop`, гипотезы закоммичены раньше |
|
||||
| `make bench_uploads_quick` | то же короче (~4,5 мин): «без лимита» и «с лимитом», 10 MiB, 1 / 10 / 40 клиентов, один повтор, метка `quick-uploads-<время>`, в git не идёт |
|
||||
| `make bench_queue [QUEUE_LABEL=...] [RESUME=1]` | уровень 5, трек 1, очередь под перегрузкой (~2 ч 10 мин, метка `baseline` по умолчанию; заняты `baseline`…`baseline4`, основная — `baseline4`, новый прогон — со своей `QUEUE_LABEL`; change `track1-queue-overload`): стенд `mtusi-bench` с S3, брокером, relay, worker и уборщиком, настройки (1, 1), (2, 2), (4, 4), (2, 256) × классы `s`, `m`, `lj`, `lp` × 3 повтора и блоки предела, приёма, второго worker, KILL worker, рестарта брокера; на ячейку — свежий стенд, открытая модель, контрольный поток, разбор очереди, обход метаданных; `evidence/queue/<метка>/` (`meta.json`, `cells.csv`, `timeline.csv`, `summary.md` с H1–H9 и рекомендацией, SVG). Рабочий стенд — `make stop`, гипотезы закоммичены раньше метки |
|
||||
| `make bench_queue_quick` | то же короче (~11 мин): `s` (2, 2), `lp` (4, 4), предел 40 и без него, `kill-worker`, `w2-p256`, один повтор, метка `quick-queue-<время>`, в git не идёт; шаг защиты «для 5» |
|
||||
| `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
|
||||
worker/__main__.py # python -m src.worker: early_stop.install("worker") до импорта → main(); неверные настройки — запись без значений и код 2; os._exit в конце
|
||||
worker/main.py # worker обработки вложений: свои engine, S3 и потребитель; цикл соединений с паузой, задачи доставок (prefetch) под семафором concurrency, сервис и SqlAlchemyUnitOfWork на доставку, ack / requeue / drop по итогу, SIGTERM — начатые ждут в срок, закрытие клиентов одним gather
|
||||
worker/render.py # процесс обработки: python -m src.worker.render, лимиты первыми строками (RLIMIT_AS, RLIMIT_CPU, RLIMIT_CORE), затем Pillow; stdin — байты, stdout — строка JSON и варианты, коды 0/3/4/5
|
||||
relay/__main__.py # python -m src.relay: early_stop.install("relay") до импорта → main(); неверные настройки — запись без значений и код 2; os._exit в конце
|
||||
relay/main.py # relay: свои engine, SqlAlchemyUnitOfWork и издатель, цикл проходов с паузами, отказ брокера и PostgreSQL не роняет, SIGTERM — текущий шаг и выход 0; replay — разовая команда реестра, коды 0/3/1/2
|
||||
cleaner/__main__.py # python -m src.cleaner [--once]: early_stop.install("cleaner") до импорта → main(); неверные настройки — запись без значений и код 2
|
||||
cleaner/main.py # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine, SqlAlchemyUnitOfWork на сервис и клиент S3, цикл с интервалом и плановой сверкой (при старте и раз в [reconciler] interval_seconds), SIGTERM — довести текущий шаг и выйти 0, --once — коды 0/1/2; reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep] [--max-objects-per-second R] — разовая сверка, коды 0/3/1/2; плановая — batch, поверхностная, предел скорости из настроек
|
||||
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, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [uploads] max_concurrent 4, max_waiting 16, wait_timeout_seconds 5, body_timeout_seconds 30 (места загрузок процесса API), max_unfinished_jobs 250 (предел незавершённых заданий стенда; 0 — без него), [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100, [reconciler] interval_seconds 3600, page_size 1000, max_changes 100, max_objects_per_second 2000 (предел скорости сверки; 0 — без него)
|
||||
api/
|
||||
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
|
||||
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra, строгий UTF-8 filename по scope["query_string"]), метаданные, байты StreamingResponse
|
||||
schemas/<domain>.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12; attachment.py — DisplayFilename (отказ на / \ Cc и пробелы) и Attachment; message.py — CreateMessage с attachment_ids и валидатором пустого текста
|
||||
dependencies.py # get_uow (SqlAlchemyUnitOfWork на запрос), request_deadline (общий срок JSON-запроса), фабрики сервисов на UowDep (с кэшем; вложения — ещё S3 и места), разбор Basic, текущая сессия по Bearer, пагинация
|
||||
errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; RETRY_AFTER — Retry-After у 429 занятых мест загрузки и предела заданий (UploadBacklogFull, 5 с); у 500 — X-Request-Id и X-Instance-Id
|
||||
middlewares/ # X-Request-Id, X-Instance-Id и access-лог
|
||||
core/
|
||||
ports/uow.py # AbstractUnitOfWork: блок, commit, rollback, blocks_opened, правила вложенного входа и repo вне блока, UnitOfWorkError; реальные шаги — _open, _close, _commit, _rollback реализации; Repositories
|
||||
ports/<domain>.py # Abstract<Domain>Repository: абстрактные методы, докстринг — контракт (None, False, условие перехода); импорты — только DTO, enum, src.utils
|
||||
repos/<domain>.py # SqlAlchemy<Domain>Repository: одна атомарная операция на метод; chat_cache и attachment_object — модульные функции над клиентом
|
||||
repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
|
||||
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
|
||||
repos/attachment_job.py # задание вложения: вставка, lock_job FOR UPDATE, start_attempt, return_to_queued своей попытки, finish_job; count_unfinished (предел принятой работы: сумма трёх count с LIMIT по частичным индексам); relay — lock_due_jobs (SKIP LOCKED, порядок срока), count_published, mark_published пакета, recover_expired_leases, has_published_before, reset_published_before; replay_job, list_failed
|
||||
repos/attachment_job_replay.py # журнал replay: вставка записи аудита, чтение по заданию
|
||||
repos/attachment_variant.py # варианты: вставка ON CONFLICT DO NOTHING по ключу эффекта, варианты вложения, один по имени
|
||||
repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_queued (pending и непомеченная → queued RETURNING), mark_processing, return_to_queued, return_group_to_queued, replay_failed, lock_attachment (FOR NO KEY UPDATE), commit_ready, commit_failed, чтение одной и до 10; очистке staging — get_staging_candidates, lock_staging_candidate, clear_staging_key; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment; сверке — get_attachments_for_objects (id = ANY OR object_key = ANY), get_ready_page (keyset ready по id), find_attachment_reference, mark_lost / clear_lost (условный UPDATE lost_at)
|
||||
repos/attachment_object.py # объекты в S3: staging_key <база>/staging/<id>/original, variant_key и parse_variant_key <база>/attachments/<id>/v<N>-<имя>, оригинал <база>/attachments/<id>/original, put_original (поток BytesIO и size, без копии тела), open, delete_original; сверке — originals_prefix, is_own_key (ключ под префиксом вложений своей базы), parse_original_key, list_originals, probe_originals (bucket на месте), head_original, staging_prefix, is_own_staging_key, parse_staging_key, list_staging; variant_keys — ключи вариантов всех имён
|
||||
repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой
|
||||
services/<domain>.py # <Domain>Service(uow, …): логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем, require_member внутри чужого блока; отправка — ключ, сообщение и связи с вложениями одним блоком
|
||||
services/attachment.py # AttachmentService(uow, cache, storage, slots): загрузка (проверки в первом блоке и там же предел заданий count_unfinished, 429 UploadBacklogFull → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT в staging тем же BytesIO → queued и задание, ответ 202; сбой до COMMIT или пропавшая строка — удаление объекта и 503; брокера в пути нет; место — до ответа), метаданные с вариантами, отдача потоком
|
||||
services/attachment_processing.py # AttachmentProcessingService(uow, storage, renderer, stop): разбор сообщения, claim с арендой и бюджетом, GET staging и сверка, PUT оригинала, варианты через ImageRenderer, PUT вариантов, фиксация ready с fencing одной транзакцией; временные ошибки — queued со сроком (retry_delay, jitter) и ACK, постоянные — failed; JobOutcome
|
||||
services/attachment_relay.py # AttachmentRelayService(uow, publisher): проход — истёкшие аренды, потерянные сообщения, публикация с подтверждением и отметка пакета внутри транзакции SKIP LOCKED, предел опубликованных; RelayPassDTO
|
||||
services/attachment_replay.py # AttachmentReplayService(uow): реестр failed, replay одной транзакцией с аудитом и новым бюджетом, отказы not_found / already_ready / not_failed / source_gone; ReplayPassDTO
|
||||
services/attachment_cleanup.py # AttachmentCleanupService(uow, storage): проход уборщика — кандидаты keyset, каждая строка в два шага (remove_stale_pending): блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO; clean_staging — очистка staging ready и failed по сроку под FOR NO KEY UPDATE SKIP LOCKED, StagingCleanupPassDTO
|
||||
services/attachment_reconcile.py # AttachmentReconcileService(uow, storage): сверка bucket и БД — S3 → БД (страницы списка, выборка на страницу, множество ключей), БД → S3 (keyset ready; ключ строки вне префикса вложений — чужой объект без HEAD; строка с ключом <id>/original другого вложения — HEAD её объекта, verify W2), зависшие, перепроверка в БД и HEAD (bucket — probe), сигнал — перед каждым вызовом хранилища, предел изменений, действия с apply (зависшие шагом уборщика → объекты без строки → объекты staging без строки → пометки → снятия); журнал Found / Fixed / Finished; ReconcilePassDTO. С change pipeline-reliability: шаг _list_staging, orphan_staging, listed_staging. С change track2-reconcile-cost: strategy head (выборка строки на объект, HEAD на строку, без множества), deep (GET и SHA-256 потоком, checksum_mismatch; «оригинал вернулся» — тот же SHA-256), предел скорости после каждого вызова S3 (_pace, куски 0,2 с; сигнал прекращает паузу, останавливает следующий check_stop — verify W1), ранний отказ по пределу (unchecked), счёт сеансов — uow.blocks_opened, стоимость в итоге (storage_objects, s3_requests, read_bytes, db_sessions, phase_ms)
|
||||
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва и срока тела (UploadTimedOut), 429 занятых мест (UploadsBusy), 429 предела заданий (UploadBacklogFull), 500 пропавшего объекта
|
||||
infra/
|
||||
early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog
|
||||
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи
|
||||
password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username
|
||||
broker/client.py # aio-pika: JobPublisher relay (соединение лениво, publish_many с confirm и общим сроком, ready_messages, сброс после любой ошибки), JobConsumer worker (своё соединение, prefetch), JobDelivery, queue_name <база>.attachment.process.v1
|
||||
render/client.py # ImageRenderer: процесс обработки на задание, окружение без секретов, срок и kill в finally, разбор вывода, коды в ImageRejected / RenderInterrupted
|
||||
upload_slots.py # UploadSlots (asyncio.Semaphore по порядку прихода, счётчик ожидающих, срок ожидания; slot() — UploadsBusy или ожидание в мс, место в finally) и глобал upload_slots из [uploads]; импортирует только dependencies.py
|
||||
db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping; _ping_once — проверка соединения при выдаче одним обменом
|
||||
db/session.py # глобалы engine и session_factory процесса API
|
||||
db/scope.py # session_scope(factory, timeout_seconds): сессия на блок, срок вместе с откатом, отмена и отказ БД → invalidate, warning, ServiceUnavailable; deadline_scope — общий срок JSON-запроса без сессии, внутри него таймер блока той же задачи не взводится
|
||||
db/uow.py # SqlAlchemyUnitOfWork(factory, timeout_seconds) поверх session_scope, repo на блок; импортируют только точки входа
|
||||
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
|
||||
db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment (частичный индекс pending по (created_at, id), lost_at — пометка потерянного оригинала) и MessageAttachment (порядок position, FK без каскада)
|
||||
cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
|
||||
cache/instance.py # глобал cache процесса API
|
||||
s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete / list_page (ListObjectsV2 по префиксу, нет bucket — ошибка), срок на вызов и блок — единственный срок клиента (read_timeout aiohttp выключен: переживал ответ и портил соединение в пуле, change fix-upload-put-flake), ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo (с last_modified, у open — тоже), StoredObject, StoredObjectPage; счётчики попыток по операциям, ключей списка и прочитанных байт — stats() → StorageStats (change track2-reconcile-cost)
|
||||
s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan
|
||||
schemas/
|
||||
jobs/attachment.py # AttachmentJobMessage (pydantic по contracts/jobs.schema.json) и build_job_body
|
||||
dataclasses/<domain>.py # DTO между repo → service → api
|
||||
enums/<domain>.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType, ReconcileFinding, ReconcileAction, ReconcileStrategy (batch, head)
|
||||
utils/
|
||||
image_variants.py # render_variants: thumbnail, crop, optimized из одного декодирования, fit_size вниз своим расчётом, EXIF orientation, alpha на белый у JPEG, InvalidImage; импортирует Pillow, поэтому только src/worker/render.py
|
||||
constants.py # лимиты контракта (с лабы 4 — 10 MiB, 40 млн пикселей, filename, 10 вложений), размер страницы, префиксы путей, имя bucket S3, разделитель и части ключа объекта, keep-alive клиента S3
|
||||
image.py # inspect_image: структурная проверка PNG/JPEG без декодирования пикселей (stdlib), тип, размеры, UnsupportedImage / DamagedImage / TooManyPixels; у JPEG ещё таблицы DQT/DHT, компоненты и полоса скана, определённые к скану таблицы (0 и 1 Хаффмана непрогрессивного кадра — необязательны), данные скана Хаффмана — условия отказа djpeg
|
||||
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/uploads_api/s3_api/backlog_api, сбор маркеров spec, стоп без hook
|
||||
api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message (с attachment_ids) — с Idempotency-Key; post_attachment/upload, attachment_meta, attachment_content, attachment_content_slowly (потоком с паузой после блока)
|
||||
contract.py # тела по схемам contracts/openapi.json, форматы id, attachment_ids и времени, X-Instance-Id, assert_error (с 413, 415 и 429 — Retry-After положительное целое), assert_errors (статусы всех вариантов запроса разом), assert_content (байты, тип, nosniff, без Location и x-amz-*), assert_replicas
|
||||
images.py # изображения для тестов: PNG на stdlib (любые IHDR, Adam7, точный размер, бомба, огромные размеры, порча байта, шум RGB ~1 MiB от зерна — png_noise), JPEG через Pillow (dev): разновидности, подмена размеров, без таблиц, изменённый заголовок скана и пустой скан (jpeg_undecodable); обрезка и хвост
|
||||
test_attachment_processing.py # спек attachment-processing по HTTP: готовность, thumbnail, варианты, failed от недекодируемого JPEG
|
||||
test_attachments.py # спек attachments: загрузка, лимиты, тип и целостность, filename, доступ, метаданные, оригинал, variant, повтор, 10 одновременных загрузок, другая реплика
|
||||
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>, уборка базы и префикса test_<db>/ в S3 (weed shell fs.rm, затем проверка fs.ls: код 0 weed shell успеха не значит; префикс только из проверенного имени) (stdlib)
|
||||
run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap, уборщик с grace 20 с и интервалом 1 с без плановой сверки → FAULT_CLEANER_*, FAULT_RECONCILER_INTERVAL_S; уборщик с плановой сверкой <проект>-cleaner-scheduled убирается вместе с API), пять API (обычный, «тесный», «узкий по загрузкам» с UPLOADS_ENV → FAULT_UPLOADS_BASE_URL / FAULT_UPLOADS_ENV, «с коротким сроком S3» с S3_ENV → FAULT_S3_BASE_URL / FAULT_S3_ENV, «узкий по заданиям» с BACKLOG_ENV → FAULT_BACKLOG_BASE_URL / FAULT_BACKLOG_ENV; у первых четырёх предел заданий выключен, NO_BACKLOG_ENV), pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), журналы API и уборщика при падении, уборка (stdlib)
|
||||
fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall|commit|outlive|undeletable: сбой вставки, перевода в ready до и на COMMIT, задержка, строка «старше grace» с ожиданием уборщика, неудаляемая строка), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api; расхождения и сверка (change track2-reconciler): put-object (тело — stdin, botocore в контейнере API его ключами) / delete-object (weed fs.rm) только под <база>/attachments/, delete-row, set-size, age-row, set-key (object_key строки под <база>/), lost-ids, fail-attachments mark, reconcile dry-run|apply [предел] [--strategy batch|head] [--deep] [--max-objects-per-second R] (аргументы по списку, записи и exit_code=), stop|start cleaner, run-cleaner <с> (stdlib)
|
||||
failures.compose.yml # override стенда отказов: relay (опрос 0,2 с, restart "no"), worker и уборщик с короткими сроками change pipeline-reliability, без публикации портов (Postgres, Valkey, S3, LB), уборщик с CLEANER__* 20 / 1, RECONCILER__INTERVAL_SECONDS 0 и restart "no", stop_grace_period 2 с у S3, healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster)
|
||||
service-tests/ # быстрые тесты сервисов (вне образа и вне student-tests), service-tests.md
|
||||
pytest.ini # настройки pytest этого каталога: pyproject.toml здесь не применяется
|
||||
builders.py # DTO для тестов: явное время, PASSWORD_HASH по виду CHECK
|
||||
repo_contract.py # один набор условий repo: на фейке и на настоящем SQL
|
||||
fakes/ # FakeDatabase (таблицы, снимок, events, held, fail_on), FakeUnitOfWork на базовом классе порта, фейки девяти repo, FakeCache, FakeObjectStorage, FakeJobPublisher, FakeImageRenderer
|
||||
unit/ # make service_test: test_unit_of_work, test_architecture, test_repo_contract, test_<service> на каждый сервис, test_worker_deliveries (одновременные доставки); conftest подставляет поля settings
|
||||
db/ # make service_test_db: conftest (временная база, TcpProxy, «тесный» API окружением до импорта src), test_uow, test_repo_contract_sql, test_request_flow
|
||||
bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling / bench_uploads (с S3)
|
||||
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; профиль uploads (S3 и bootstrap на стенде, на прогон — новый volume S3 и реплика с окружением варианта через .work/variant.compose.yml, образ «до» — тег bench-from, сэмплер peak), в паспорте всех профилей stand.api_tcp_rmem и docker.kernel; профиль reconcile (S3 с портом метрик через .work/s3-metrics.compose.yml, наполнение \copy и загрузчиком, разовые проходы mtusi-bench-reconcile-<n> с лимитом CPU варианта, «до» — .work/cleaner-before.compose.yml, метрики шлюза и pg_stat_database до и после, блок H4 с k6 background.js, отказ по пределу S4)
|
||||
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; режим peak (uploads) — сброс memory.peak реплики, S3 и LB через свой дескриптор (perl), чтение пика в конце окна, выборка current / anon / sock / oom_kill раз в 0,2 с (--user 0, cgroupfs rw, без сети)
|
||||
uploads.py # профиль uploads без docker: тела PNG из шума от зерна, план кругами, разбор строк k6 и сэмплера peak, строка runs.csv, пометки oom / host_swap / peak_sampled / s3_down, summary.md (медиана и min–max по ячейкам, сценарии спеков, H1–H4); --selftest
|
||||
reconcile.py # профиль reconcile без docker (change track2-reconcile-cost): модель набора (id, содержимое и класс по номеру и зерну, строки CSV для \copy, ожидаемое по классам), план кругами, разбор записей уборщика, метрик шлюза S3, строк bg k6 и сэмплера, окна и r / a H4, passes.csv и windows.csv, вердикты H1–H4 и S4, summary.md и SVG (plots.Svg); --selftest
|
||||
overload.py # профиль queue без docker (change track1-queue-overload): план кругами, разбор строк q/qs/qv, jobs, mq, mp и журналов, жизни контейнера, строка cells.csv и timeline.csv, пометки, вердикты H1–H9, правило рекомендации, summary.md и SVG; --selftest
|
||||
make_images.py # файлы классов s, m, lj, lp профиля queue: только в контейнере mtusi-bench-images на образе стенда (Pillow образа, --network none), зерно из аргумента, JSON с размерами и SHA-256, больше лимита контракта — код 1
|
||||
queue.compose.yml # третий -f только профиля queue: плагин метрик брокера и статистика в секунду (bench/rabbitmq/), restart: unless-stopped у worker
|
||||
rabbitmq/ # enabled_plugins и 91-bench.conf профиля queue
|
||||
fill_objects.py # загрузчик объектов профиля reconcile: только в контейнере mtusi-bench-fill на образе стенда (botocore образа, bench/ на чтение, ключи API из окружения), процессы × потоки PUT по модели reconcile.py
|
||||
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; s3 (лимиты BENCH_S3_*, swap = память) запускают профили uploads и reconcile, cleaner (mtusi-bench-cleaner, без порта, лимиты BENCH_CLEANER_* без swap) — только разовыми проходами профиля reconcile; буфер приёма реплики — sysctls основного compose
|
||||
bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей и секретов S3: их генерирует run.py)
|
||||
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, досрочный выход), uploads (constant-vus загрузок тела из /work, пауза Retry-After на 429 и 1 с на прочие ошибки, строка на запрос, WARMUP — одна загрузка), background (профили reconcile и queue: constant-arrival-rate скачиваний, записи и чтения истории, строка bg на запрос, остановка SIGINT), queue (окна constant-arrival-rate загрузок, VU заранее, ответ не повторяется, строка q на загрузку; WARM — разогрев) и queue_sweep (метаданные каждого принятого вложения, SHA-256 выборки, строки qs и qv); 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; 739b8f04d5fb — частичный индекс pending CONCURRENTLY в autocommit_block; 5c3e1f0a9b7d — attachments.lost_at (NULL, SET LOCAL lock_timeout); c7e2f1a04b56 — attempt_base и attachment_job_replays; d3f9a6b2c1e7 — индексы outbox, аренды и очистки staging CONCURRENTLY
|
||||
infra/ # конфигурации сервисов стенда; README.md — skeleton
|
||||
valkey/valkey.conf # лимит памяти и LRU, persistence выключен
|
||||
rabbitmq/rabbitmq.conf # предел памяти брокера 400 МиБ: лимит контейнера он не видит
|
||||
rollback/broker.compose.yml # override отката реплик на образ до pipeline-reliability (прежний код публикует сам): адрес и пароль брокера только на время отката
|
||||
s3/bootstrap.sh # bootstrap S3 (ещё пользователь worker: чтение и запись объектов; сервис s3-bootstrap, network_mode: service:s3): apply — bucket, анонимный доступ none, политики api-objects и cleaner-objects (у уборщика — ещё список только с префиксом S3_CLEANER_LIST_PREFIX = <база>/attachments/), пользователи api и cleaner с ключами из .env, проверки приватности обоих ключей; check (и строки ключа уборщика) и cleanup — для make s3_check; секреты — stdin weed shell и файл curl на tmpfs
|
||||
haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта (400, 502, 503, 504), timeout server 30 с пути загрузки (set-timeout, остальные 10 с), tune.sndbuf.server 256 KiB и tune.rcvbuf.client 128 KiB, мониторинг :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, s3 (~25 с); ожидание хранилищ — up --wait --no-recreate (Compose 5.4 иначе пересоздаёт контейнеры, чьи образы скачивались при первом up, и s3-bootstrap не стартует); start api повторяет migrate и s3-bootstrap (no-op); уборщика не трогает — рестарт хранилищ он переживает сам
|
||||
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 (до 90 с: дольше загрузки) → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/
|
||||
Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck, MALLOC_MMAP_THRESHOLD_ (буфер загрузки растёт без копии)
|
||||
docker-compose.yml # проект mtusi-lab5: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), rabbitmq, migrate, s3-bootstrap, relay и worker (пароль брокера только у них и rabbitmq), api × API_REPLICAS без портов (sysctls: буфер приёма сокетов до 512 KiB), cleaner (уборщик: точка входа python -m src.cleaner, пул 1, ключи S3_CLEANER_*, без healthcheck), haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env, x-s3-api-keys-env)
|
||||
.dockerignore
|
||||
config_example.toml, .env.example
|
||||
evidence/broker/ # change async-attachments: stand.md (driver.py broker-check), isolated.md (очередь временной базы)
|
||||
evidence/worker/ # change async-attachments: process.md (driver.py worker-process), logs.md (журнал задания); memory.md (driver.py worker-memory)
|
||||
evidence/attachments/ # change async-attachments: defense.md (driver.py defense-scenario); change attachments: smoke.md, failover.md (driver.py attachment-failover stop и kill), storage.md (driver.py attachment-storage), slow-transfer.md (10 MiB через LB дольше 6 с); change upload-consistency: consistency.md (driver.py upload-consistency и журналы API и уборщика), cleaner-process.md (старт, отказ конфигурации, остановка, окно 0, рестарт хранилищ, отказ S3 во время прохода); по замечанию ревьюера: jpeg-structure.md (варианты JPEG — прежняя и новая проверка, Pillow, djpeg; регрессия на 301 JPEG; время; красный и зелёный прогоны test_undecodable_jpeg)
|
||||
evidence/s3/ # privacy.md — make s3_check на текущем коде; change s3-storage: bootstrap.md (первый запуск, повтор, смена секрета, ошибка шага, до bootstrap), privacy.md (make s3_check, нарушение и исправление, порты, секреты по сервисам), grpc-admin.md (gRPC шлюза без токена), restart.md (restart.sh и SIGKILL S3), client.md (операции, pause/stop, неверный секрет, журнал), memory.md (20 × 10 MiB PUT); change upload-consistency: cleaner-key.md (пользователь уборщика в bootstrap, смена секрета, make s3_check с ключом уборщика, секреты по сервисам); change track2-reconciler: cleaner-list.md (bootstrap с политикой списка по префиксу, неверный префикс, make s3_check со строками списка уборщика, окружение s3-bootstrap)
|
||||
evidence/reconcile/ # change track2-reconciler: cycle.md (driver.py reconcile-cycle), stress.md (driver.py reconcile-stress), service.md (Started cleaner с параметрами сверки, плановая сверка при старте, docker stop во время сверки при pause s3, код 1 разового прохода по сигналу — driver.py reconcile-signal, отказ старта на RECONCILER__*, коды 3 и 0; с change track2-reconcile-cost — остановка во время паузы предела скорости, driver.py reconcile-signal --pace)
|
||||
evidence/reconcile/<метка>/ # результаты make bench_reconcile (change track2-reconcile-cost): meta.json (раздел reconcile: план, этапы и модели, commit и образы «до», аргументы S3), passes.csv, windows.csv, summary.md (H1–H4 и S4), cost-by-n.svg, requests-by-n.svg, background-p95.svg, raw/ (записи уборщика по проходам, итог k6 блока H4)
|
||||
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга; freeze-sessions.md — change unit-of-work: сессии и журнал пула после заморозки PostgreSQL (driver.py freeze-sessions и freeze-lb)
|
||||
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции; лаба 4: pending-index.md (ревизия 739b8f04d5fb с нуля, повтор, откат, EXPLAIN общего плана кандидатов уборщика на рабочей базе с откатом, rollout_quick), lost-at.md (ревизия 5c3e1f0a9b7d колонки lost_at: с нуля, повтор, откат, --sql с lock_timeout, make rolling_update с ревизией до и после)
|
||||
evidence/auth/ # passwords-and-tokens.md — driver.py auth-storage на стенде текущей лабы: Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump (исключения сверки покрытия)
|
||||
evidence/cache/ # hits.md — make test_isolated + driver.py cache-check на стенде текущей лабы: одно чтение chats на 50 через LB, TTL, ключи двух баз (исключения сверки покрытия)
|
||||
evidence/tests/ # change unit-of-work: service-tests.md (make service_test и service_test_db, таблица регрессий); выводы make test_isolated (test-isolated.md), make student_test через LB (student-test-lb.md) и make failure_checks (failure-checks.md) для REPORT.md, secrets.md; файлы этих проверок лаб 3 и 4 — в их репозиториях
|
||||
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/queue/<метка>/ # результаты make bench_queue (change track1-queue-overload): meta.json (классы, план, окна, app_env по конфигурациям), cells.csv, timeline.csv, summary.md (H1–H9, рекомендация), SVG, raw/ — итоги k6
|
||||
evidence/uploads/ # change upload-memory: <метка>/ — make bench_uploads (meta.json, runs.csv, summary.md, raw/), lb-timeouts.md — driver.py lb-upload-timeouts, rollout-upload.md — медленная загрузка во время make rolling_update
|
||||
evidence/bench/unit-of-work-*/ # change unit-of-work, профиль quick с именной меткой (идёт в git): before и aa на b2fb88f, after на 6ba74b1
|
||||
evidence/rollout/unit-of-work*/ # change unit-of-work: unit-of-work (замена с Profile.rollout_from), unit-of-work-previous (--from b2fb88f: CPU на запрос старых и новых реплик)
|
||||
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md; unit-of-work-before__unit-of-work-after.md и unit-of-work-aa__unit-of-work-after.md — цена шага от двух меток одного кода
|
||||
.github/workflows/application.yml # свой CI job (CONTRIBUTING.md, «CI»; contracts.yml — skeleton): checkout commit прогона (адрес Gitea литералом: github.server_url — внутренний http://gitea:3000, из job не резолвится; по той же причине contracts.yml на этом раннере падает на actions/checkout), сборка и стенд под проектом mtusi-lab5-safronov-ci-<run_id>, job подключается к сети стенда, готовность — обе реплики через LB, make check / test, аноним в S3 — 403, make validate, make student_test, test-persistence, test-failover stop и kill, уборка при любом исходе; без s3_check, test_isolated и failure_checks (порты хоста). Раннер Gitea (act_runner) запускает job в контейнере на том же Docker, что стенд
|
||||
.github/ci/compose.yml # override стенда в CI: конфиги — configs из переменных окружения вместо bind mount (файлов job нет на хосте раннера), без портов на хосте, образ API с тегом прогона
|
||||
.github/ci/stand-env.sh # «.» в шагах job: содержимое конфигов в CI_* для configs (с переводом строки в конце: без него HAProxy конфиг не принимает), wait_replicas — /health/ready 200 от API_REPLICAS разных реплик через LB за 60 с
|
||||
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
|
||||
```
|
||||
|
||||
`evidence/` в лабу 5 не переносился: здесь только снятое на её стенде, а
|
||||
файлы и метки лаб 3 и 4 остались в репозиториях `mtusi2026lab3-safronov`
|
||||
и `mtusi2026lab4-safronov`. Записи карты о changes лаб 3 и 4 говорят, что
|
||||
такой каталог содержит, когда он снят: каталоги появляются заново по мере
|
||||
changes, а файлы исключений сверки покрытия снимаются заново на стенде
|
||||
текущей лабы (раздел «Переход в следующую лабу»).
|
||||
|
||||
## Архитектура в двух словах
|
||||
|
||||
- Поток однонаправленный. Роутер (зависимости, модели API) → сервис
|
||||
(логика, проверки доступа, id и время, логи) → единица работы и repo за портами
|
||||
`src/core/ports/` (одна атомарная операция над хранилищем, отдаёт DTO) →
|
||||
PostgreSQL через `SqlAlchemyUnitOfWork` (`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/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/`, `service-tests/`, `migrations/`, `alembic.ini`,
|
||||
`Dockerfile`, `docker-compose.yml`, `infra/valkey/`,
|
||||
`infra/haproxy/`, `infra/s3/`, `infra/rabbitmq/` (без `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`, свой CI
|
||||
job `.github/workflows/application.yml` и `.github/ci/` (остальное в
|
||||
`.github/` — из нового skeleton). В job поменять номер лабы в префиксе
|
||||
проекта `mtusi-lab5-safronov-ci-` (и в шаге уборки хвостов), в
|
||||
override — новые сервисы и конфиги нового стенда; Actions в новом fork
|
||||
включить в его настройках.
|
||||
- Сливать, а не копировать поверх: `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`;
|
||||
с лабы 4 ещё `driver.py --port <LB> attachment-failover` (оба режима)
|
||||
→ `evidence/attachments/failover.md` и `driver.py --port <LB>
|
||||
attachment-storage` → `evidence/attachments/storage.md`
|
||||
(`student-tests.md`). Файлы `evidence/` этой лабы в новую лабу не
|
||||
копировать, даже эти: сверка проверяет только наличие файла и с
|
||||
копией останется зелёной без пересъёмки.
|
||||
- `Profile.rollout_from` в `bench/run.py` (профили `rollout`,
|
||||
`rollout_quick`) поменять на commit новой лабы до изменения, которое
|
||||
должна показать замена: commit этой лабы в истории новой нет, и
|
||||
команда откажет до стенда (`bench.md`, профиль `rollout`). Так же
|
||||
`Profile.uploads_before` (профиль `uploads`, вариант «до»): commit новой
|
||||
лабы до изменения, которое показывает профиль.
|
||||
- Сначала прочитать переходы 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`, включая использование ИИ.
|
||||
@@ -0,0 +1,5 @@
|
||||
@AGENTS.md
|
||||
|
||||
Правила по слоям лежат в `.claude/rules/` и подгружаются сами только при
|
||||
чтении файла из их `paths:`. Проект пишется с нуля: перед созданием
|
||||
первого файла слоя прочитать его правило руками (таблица в AGENTS.md).
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
# Образ 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
|
||||
|
||||
# MALLOC_MMAP_THRESHOLD_: блоки от 128 KiB всегда в mmap, и буфер тела
|
||||
# загрузки растёт через mremap без копии. Без него glibc после первой
|
||||
# загрузки поднимает порог, буфер растёт в куче, и realloc на миг держит
|
||||
# два тела (design change `attachments`, решение 6)
|
||||
ENV PATH=/app/.venv/bin:$PATH \
|
||||
PYTHONUNBUFFERED=1 \
|
||||
PYTHONDONTWRITEBYTECODE=1 \
|
||||
MALLOC_MMAP_THRESHOLD_=131072 \
|
||||
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"]
|
||||
+196
@@ -0,0 +1,196 @@
|
||||
# Известные дефекты
|
||||
|
||||
Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md).
|
||||
Исправленные удаляются отсюда, история — в git.
|
||||
|
||||
## Смесь версий при замене реплик на первый релиз с обработкой
|
||||
|
||||
- **Где:** `make rolling_update` с прежней версии (design change
|
||||
`async-attachments`, решение 14), `AttachmentStatus` прежнего образа.
|
||||
- **Что:** на время замены прежняя реплика отвечает 201 `ready` и даёт 500 на
|
||||
чтении строки нового статуса (`ValueError` в `_to_dto`), а новая — 202. То же
|
||||
после отката: незавершённые `queued` и `processing` дают 500 на прежней версии.
|
||||
- **Чем грозит:** окно замены ограничено, переход 201 → 202 всё равно несовместим
|
||||
для клиента на это окно; названо в `REPORT.md`.
|
||||
- **Предложение:** не лечить: объявленный переход контракта. Новые статусы в
|
||||
будущих версиях добавлять так, чтобы прежняя версия читала строку.
|
||||
|
||||
## Bootstrap после удаления bucket на маленьком диске: «api key wait (code 500)»
|
||||
|
||||
- **Где:** `infra/s3/bootstrap.sh` (режим `apply`) и сервер `s3`
|
||||
(`docker-compose.yml`: entrypoint образа добавляет `-volume.max=0
|
||||
-master.volumeSizeLimitMB=1024`), SeaweedFS 4.48.
|
||||
- **Что:** после удаления bucket мимо bootstrap (`s3.bucket.delete`)
|
||||
повторный bootstrap пишет «bucket created», затем «FAILED: api key wait
|
||||
(code 500)». Найдено в правках по verify change `s3-storage`
|
||||
(2026-10-20); воспроизведено и объяснено пробой design change
|
||||
`track2-reconciler` (Context, 2026-10-22, проект `rcprobe`).
|
||||
- **Причина:** не повторное имя bucket, а слоты томов. С `-volume.max=0`
|
||||
число слотов считается по свободному месту диска / 1 ГиБ. Удаление
|
||||
bucket удаляет тома его коллекции, но на маленьком диске слоты уже
|
||||
заняты томами коллекции по умолчанию (журналы filer), и новых томов для
|
||||
`messenger` выделить некуда: в журнале S3 — «No writable volumes and no
|
||||
free volumes left for collection:messenger», PUT получает 500.
|
||||
- **Условие:** диск, на котором `-volume.max=0` даёт мало слотов, — tmpfs
|
||||
проб, а не volume стендов проекта. Проба: tmpfs 4 ГБ — 3 слота из 3
|
||||
заняты, ошибка дважды подряд; tmpfs 16 ГБ — 15 слотов, повтор
|
||||
bootstrap прошёл за 2 с. Рабочий стенд (volume на диске ВМ) — 417
|
||||
слотов, 403 свободны (`weed shell volume.list`): удаление bucket и
|
||||
повтор bootstrap этим не падают. Стенды проекта не затронуты.
|
||||
- **Чем грозит:** только временным стендам на маленьком tmpfs: после
|
||||
удаления bucket повтор bootstrap не проходит. Сверка bucket и БД
|
||||
bucket не создаёт и не удаляет: на `NoSuchBucket` она прерывает проход
|
||||
без изменений (design change `track2-reconciler`, решение 14).
|
||||
- **Предложение:** на маленьких дисках — `-master.volumeSizeLimitMB`
|
||||
меньше 1024 (больше слотов на тот же объём) или явный `-volume.max`;
|
||||
для стендов проекта не нужно. Запись остаётся открытой.
|
||||
|
||||
## Уборщик удаляет объект зависшей загрузки по ключу вне своего префикса
|
||||
|
||||
- **Где:** `src/core/services/attachment_cleanup.py`
|
||||
(`remove_stale_pending`: `delete_original` по `object_key` строки) и
|
||||
политика `cleaner-objects` в `infra/s3/bootstrap.sh` (`s3:DeleteObject`
|
||||
на `<bucket>/*`).
|
||||
- **Что:** сервис уборки (`python -m src.cleaner`, `--once`) убирает
|
||||
строку `pending` старше grace вместе с объектом по ключу из этой
|
||||
строки, не проверяя, что ключ под `<база>/attachments/`. Ключ вне
|
||||
префикса API не пишет; он бывает в базе, восстановленной под другим
|
||||
именем (её строки ведут к объектам исходной базы), или после ручной
|
||||
правки. Тогда уборщик удаляет объект чужого префикса — другой базы.
|
||||
Найдено в правках по verify change `track2-reconciler` (замечание W2,
|
||||
2026-10-22): сверка такую строку теперь только называет «чужим
|
||||
объектом» и не убирает (design, «Уточнения apply», п. 19), а сервис
|
||||
уборки — поведение change `upload-consistency` — не менялся.
|
||||
- **Чем грозит:** только при строке с чужим ключом: потерей объекта
|
||||
другой базы того же bucket. Стенды проекта таких строк не содержат.
|
||||
- **Предложение:** в `remove_stale_pending` (или в `lock_stale_pending`)
|
||||
— та же проверка `attachment_object_repo.is_own_key`: строку с чужим
|
||||
ключом убирать без DELETE объекта (или пропускать с `warning`), сценарий
|
||||
в требовании «Уборщик незавершённых загрузок» и тест на стенде отказов
|
||||
(`set-key` hook уже есть); при желании — сузить `s3:DeleteObject`
|
||||
политики до `<bucket>/<база>/attachments/*`, переделав проверки
|
||||
bootstrap, которые удаляют свои объекты ключом уборщика.
|
||||
|
||||
## LB отвечает 408 на медленные заголовки текстом HAProxy
|
||||
|
||||
- **Где:** `infra/haproxy/haproxy.cfg`, `defaults`: `timeout
|
||||
http-request 10s`, HAProxy 3.4.6.
|
||||
- **Что:** клиент, который присылает заголовки запроса дольше 10 с,
|
||||
получает от LB 408 со страницей HAProxy в HTML, а не ошибку в формате
|
||||
контракта (`{"error": {...}}` с `request_id` = `X-Request-Id`).
|
||||
`http-error status 408 … lf-string` его не меняет: такой ответ HAProxy
|
||||
строит до потока запроса, где `http-error` уже не действует. Проба
|
||||
change `upload-memory` (design, Context, п. 4; таблица «HAProxy,
|
||||
сроки»): заголовки за 12 с — 408 HTML и с `http-error status 408`, и
|
||||
без него. 400 посреди тела после change идёт в формате контракта.
|
||||
- **Чем грозит:** клиент с медленной сетью на заголовках получает ответ
|
||||
вне формата контракта. Путь загрузки и остальные пути API не
|
||||
затронуты: заголовки приходят за миллисекунды.
|
||||
- **Предложение:** `errorfile 408` со статичным JSON не годится:
|
||||
`request_id` в нём один на все ответы, а контракт требует тот же id,
|
||||
что в `X-Request-Id`, и уникальный. Варианты для разбора: проверить
|
||||
`http-errors` / `errorloc` и Lua-ответ в новых версиях HAProxy 3.x;
|
||||
либо поднять `timeout http-request` и назвать ограничение в
|
||||
`REPORT.md` (уже названо в спеке `load-balancing`, «Ошибки
|
||||
балансировщика в формате контракта»).
|
||||
|
||||
## Поля `float` настроек принимают `inf`
|
||||
|
||||
- **Где:** `src/config/settings.py` — все поля `float` с `gt=0` или
|
||||
`ge=0`, кроме `[reconciler] max_objects_per_second`: сроки `[database]`,
|
||||
`[cache]`, `[s3]`, `[uploads]`, `[cleaner] interval_seconds`,
|
||||
`[reconciler] interval_seconds`. Найдено verify change
|
||||
`track2-reconcile-cost` (S2) на `max_objects_per_second`; там исправлено
|
||||
(`allow_inf_nan=False`), остальные поля — вне change.
|
||||
- **Что:** pydantic принимает `inf` (`RECONCILER__INTERVAL_SECONDS=inf`,
|
||||
`UPLOADS__WAIT_TIMEOUT_SECONDS=inf`): `inf > 0` верно. `nan` отсекают
|
||||
`gt` и `ge`. Записи старта («Started API», «Started cleaner») выводят
|
||||
значение как `Infinity` — это не JSON, и разбор журнала по строкам
|
||||
ломается.
|
||||
- **Чем грозит:** оператор, ошибившийся в значении, получает срок без
|
||||
конца (ожидание места загрузки, вызов S3 без срока, плановая сверка,
|
||||
которая не наступит) и журнал, который не разбирается как JSON.
|
||||
Значения по умолчанию и `config_example.toml` не затронуты.
|
||||
- **Предложение:** `allow_inf_nan=False` у каждого поля `float` (или
|
||||
`model_config = ConfigDict(allow_inf_nan=False)` у секций), сценарий в
|
||||
требовании «Некорректное значение останавливает запуск» спека
|
||||
`service-configuration` и проверка `uv run python -c` с `inf` по полям.
|
||||
|
||||
## `driver.py reconcile-cycle` на наполненном стенде: свежий F стареет раньше проверки
|
||||
|
||||
- **Где:** `.claude/skills/run-mtusi-messenger/driver.py`, строка «exit code after X
|
||||
and Y are removed» (grace пробы `RC_GRACE_S` 30 с). Найдено прогоном change
|
||||
`unit-of-work` (задача 11.5); от кода не зависит.
|
||||
- **Что:** на стенде с 11 тыс. объектов (накоплены `make student_test`) каждый проход
|
||||
сверки длится ~5,8 с из-за предела скорости 2000 объектов/с, и за шесть проходов
|
||||
объект F становится старше 30 с раньше этой проверки: dry-run находит `orphan_object`
|
||||
и даёт код 3 вместо 0. Остальные проверки цикла совпадают, итог команды — код 1.
|
||||
- **Чем грозит:** ложный FAIL сценария на долго живущем стенде, на чистом стенде его нет.
|
||||
- **Предложение:** в этой проверке считать допустимой находку F или записывать F позже,
|
||||
непосредственно перед ожиданием grace; либо передавать пробам `RATE=0`.
|
||||
|
||||
## Метаданные и скачивание вложения: 504 от LB вместо 503 при зависшем PostgreSQL
|
||||
|
||||
- **Где:** `GET /api/v1/attachments/{id}` и `GET …/content`
|
||||
(`src/api/routers/v1/attachment.py`), `infra/haproxy/haproxy.cfg`. Найдено
|
||||
пробами change `unit-of-work` (design, решение 6).
|
||||
- **Что:** вход и блок сервиса — два блока по сроку `[database]
|
||||
request_timeout_seconds`, то есть до `2T` = 12 с, а `timeout server` этих путей
|
||||
— 10 с; общего срока у роутера вложений нет (передача дольше срока блока).
|
||||
Дефект прежний: `CurrentUserBrief` и `db_scope` тоже были двумя шагами. Путь
|
||||
загрузки не затронут: его `timeout server` 30 с.
|
||||
- **Чем грозит:** при зависшем PostgreSQL клиент получает 504 от LB через 10 с
|
||||
вместо 503 реплики; данные не страдают.
|
||||
- **Предложение:** общий срок `request_deadline` на этих двух ручках на шаг до
|
||||
начала потока (вход и блок метаданных, без передачи байтов): отдельной
|
||||
зависимостью сложно, поток идёт после неё. Проще свой путь в
|
||||
`http-request set-timeout server` LB для `GET /attachments/…`. Не чинится в
|
||||
change `unit-of-work`: ручки вложений там без общего срока (решение 6).
|
||||
|
||||
## S3 на долго живущем стенде: лимит памяти при всплеске загрузок у границы байтов
|
||||
|
||||
- **Где:** сервис `s3` (`docker-compose.yml`: лимит 512 МБ, `GOMEMLIMIT=400MiB`,
|
||||
`-s3.concurrentUploadLimitMB=64`), SeaweedFS 4.48. Найдено пробой change
|
||||
`track1-queue-overload` (design, Context, проект `q1probe`, 2026-11-01).
|
||||
- **Что:** на стенде, который ~80 мин принимал пробы без пересоздания volume (~9 200
|
||||
заданий), `docker stats` показывал у S3 330–415 МиБ; при 12 загрузках 10 MiB в секунду
|
||||
ядро его убило (`exit 137`, `OOMKilled: true`, один случай). На свежем стенде те же 12 и
|
||||
15 загрузок в секунду — 322–399 МиБ и `oom_kill` 0. Зависит ли это от числа объектов,
|
||||
проба не проверяла.
|
||||
- **Чем грозит:** пока S3 лежит, загрузка и скачивание — 503. На рабочем стенде его
|
||||
возвращает `restart: unless-stopped`; в пробе (`restart: "no"`) все 229 незавершённых
|
||||
заданий за ~85 с исчерпали бюджет: `failed`, `retry_exhausted`, возврат — `make replay`.
|
||||
Принятая работа не потеряна, реестр её называет.
|
||||
- **Предложение:** замерить рост памяти S3 с числом объектов (профиль с накоплением, без
|
||||
пересоздания volume); при подтверждении — лимит 768 МБ или меньше `GOMEMLIMIT`. Метка
|
||||
`make bench_queue` этого не покажет: её ячейки идут на свежих volume.
|
||||
|
||||
## Граница живой загрузки уборщика не учитывает закрытие соединения
|
||||
|
||||
- **Где:** `src/cleaner/main.py`, `live_upload_bound_seconds`; `openspec/specs/load-balancing/spec.md`
|
||||
и `openspec/specs/service-configuration/spec.md` («17 с»). Найдено verify change
|
||||
`track1-queue-overload` (S9).
|
||||
- **Что:** формула `2 × request_timeout_seconds + [s3] timeout_seconds` = 17 с не считает закрытие
|
||||
соединения на зависшем сервере (`DB_CLOSE_TIMEOUT_SECONDS`, 2 с: возврат соединения идёт вне срока
|
||||
блока). Оценка сверху — 2 × (6 + 2) + 5 = 21 с. То же у молчания реплики до тела: 21 с вместо 17, но
|
||||
оба меньше `timeout server` 30 с, поэтому цепочка LB верна.
|
||||
- **Чем грозит:** проверка старта пропускает grace от 18 до 21 с. При 900 с по умолчанию разницы нет,
|
||||
запас огромный. На стенде отказов grace 20 с: при зависшем PostgreSQL уборщик может взять строку ещё
|
||||
живой загрузки, но данные не страдают: `mark_queued` помеченную строку не переводит, клиент получает
|
||||
503, объект удаляется.
|
||||
- **Предложение:** прибавить `2 × DB_CLOSE_TIMEOUT_SECONDS` в формулу и поднять grace стенда отказов до
|
||||
22 с и больше, отдельным change; там же поправить «17 с» в спеках. Правка меняет код уборщика и стенд
|
||||
отказов, в `track1-queue-overload` не входит.
|
||||
|
||||
## Остановка API при замороженном PostgreSQL дольше срока контейнера
|
||||
|
||||
- **Где:** `src/main.py`, `await engine.dispose()` в lifespan без общего срока. Найдено
|
||||
повторным verify change `unit-of-work` (S3); дефект прежний, правкой не вызван.
|
||||
- **Что:** простаивающие соединения закрываются по очереди, каждое до
|
||||
`DB_CLOSE_TIMEOUT_SECONDS` (2 с). Замер `dispose` на замороженном сервере: пул 10 —
|
||||
20,05 с; пул 4 — 8,02 с и на `d8fe2e8`, и на `9efab79`. `docker stop` на замороженном
|
||||
PostgreSQL не проверялся: то, что контейнер получит SIGKILL после 10 с, — расчёт.
|
||||
- **Чем грозит:** только при замороженном PostgreSQL во время остановки реплики:
|
||||
журнал без «Stopped API»; данные не страдают, незафиксированное откатит сервер.
|
||||
- **Предложение:** общий срок на закрытие в lifespan, как `_CLOSE_TIMEOUT_SECONDS` у
|
||||
worker и relay, и сценарий в спеке `graceful-shutdown`.
|
||||
@@ -28,3 +28,522 @@ 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 и S3 с bootstrap из compose,
|
||||
# затем сервис на хосте: 127.0.0.1:APP__PORT, reload по src/
|
||||
.PHONY: run_dev
|
||||
run_dev: upgrade start_cache start_s3 start_broker
|
||||
APP__RUN_MODE=console uv run python -m src
|
||||
|
||||
# worker в консоли: тот же .env, адреса на хосте; ключи worker — в окружение
|
||||
# процесса (мост S3__* в .env — ключи API). @: значения в вывод не попадают
|
||||
.PHONY: run_worker
|
||||
run_worker:
|
||||
@S3__ACCESS_KEY_ID="$(S3_WORKER_ACCESS_KEY)" S3__SECRET_ACCESS_KEY="$(S3_WORKER_SECRET_KEY)" APP__RUN_MODE=console uv run python -m src.worker
|
||||
|
||||
# relay публикации заданий в консоли: без него консольный API принимает файлы, а
|
||||
# задания ждут в PostgreSQL. Брокер поднимает make run_dev; те же мосты .env
|
||||
.PHONY: run_relay
|
||||
run_relay:
|
||||
@APP__RUN_MODE=console uv run python -m src.relay
|
||||
|
||||
# реестр failed и replay (design change pipeline-reliability, решение 5): без
|
||||
# APPLY=1 только показ; с APPLY=1 выбор обязателен (ATTACHMENT, ERROR_CODE или
|
||||
# REASON), иначе код 2. Коды: 0 — выполнено или показано, 3 — есть отказы, 1 —
|
||||
# отказ PostgreSQL. ATTACHMENT — id вложения, можно несколько через пробел
|
||||
OPERATOR ?= $(USER)
|
||||
.PHONY: replay
|
||||
replay:
|
||||
@$(DC) run --rm --no-deps relay replay$(foreach id,$(ATTACHMENT), --attachment-id $(id))$(if $(ERROR_CODE), --error-code $(ERROR_CODE))$(if $(REASON), --reason $(REASON))$(if $(LIMIT), --limit $(LIMIT))$(if $(filter 1,$(APPLY)), --apply)$(if $(OPERATOR), --operator $(OPERATOR))
|
||||
|
||||
# шаблоны копируются только если файла ещё нет: локальные значения
|
||||
# не затираются. В .env подставляются случайные пароли Postgres и
|
||||
# Valkey и секреты S3: в шаблоне они пустые, общего секрета стенда в git
|
||||
# нет. В существующий .env дописываются переменные шаблона, которых в нём
|
||||
# нет (секреты — случайными, остальные — значениями шаблона), прежние
|
||||
# строки не меняются (design change upload-consistency). Печатаются
|
||||
# только имена, значения — нет
|
||||
ENV_SECRETS = POSTGRES_PASSWORD VALKEY_PASSWORD RABBITMQ_DEFAULT_PASS S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY S3_WORKER_ACCESS_KEY S3_WORKER_SECRET_KEY
|
||||
# шаблон с подставленными секретами — в поток, не в вывод команды
|
||||
ENV_FILLED = sed \
|
||||
-e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \
|
||||
-e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \
|
||||
-e "s/^S3_ROOT_ACCESS_KEY=$$/S3_ROOT_ACCESS_KEY=$$(openssl rand -hex 10)/" \
|
||||
-e "s/^S3_ROOT_SECRET_KEY=$$/S3_ROOT_SECRET_KEY=$$(openssl rand -hex 20)/" \
|
||||
-e "s/^S3_JWT_SIGNING_KEY=$$/S3_JWT_SIGNING_KEY=$$(openssl rand -hex 32)/" \
|
||||
-e "s/^S3_API_ACCESS_KEY=$$/S3_API_ACCESS_KEY=$$(openssl rand -hex 10)/" \
|
||||
-e "s/^S3_API_SECRET_KEY=$$/S3_API_SECRET_KEY=$$(openssl rand -hex 20)/" \
|
||||
-e "s/^S3_CLEANER_ACCESS_KEY=$$/S3_CLEANER_ACCESS_KEY=$$(openssl rand -hex 10)/" \
|
||||
-e "s/^S3_CLEANER_SECRET_KEY=$$/S3_CLEANER_SECRET_KEY=$$(openssl rand -hex 20)/" \
|
||||
-e "s/^S3_WORKER_ACCESS_KEY=$$/S3_WORKER_ACCESS_KEY=$$(openssl rand -hex 10)/" \
|
||||
-e "s/^S3_WORKER_SECRET_KEY=$$/S3_WORKER_SECRET_KEY=$$(openssl rand -hex 20)/" \
|
||||
-e "s/^RABBITMQ_DEFAULT_PASS=$$/RABBITMQ_DEFAULT_PASS=$$(openssl rand -hex 16)/" \
|
||||
.env.example
|
||||
# строки NAME=… шаблона, имени которых в .env нет, — в конец .env под
|
||||
# комментарием; в вывод — только имена
|
||||
ENV_APPEND_MISSING = awk -F= ' \
|
||||
BEGIN { \
|
||||
while ((getline line < ".env") > 0) \
|
||||
if (line ~ /^[A-Za-z_][A-Za-z0-9_]*=/) { split(line, kv, "="); have[kv[1]] = 1 }; \
|
||||
close(".env"); \
|
||||
} \
|
||||
/^[A-Za-z_][A-Za-z0-9_]*=/ && !($$1 in have) { \
|
||||
if (!added++) printf "\n\# added by make env_setup from .env.example\n" >> ".env"; \
|
||||
print >> ".env"; names = names " " $$1 \
|
||||
} \
|
||||
END { if (added) print "added to existing .env:" names }'
|
||||
.PHONY: env_setup
|
||||
env_setup:
|
||||
@if [ ! -f .env ]; then \
|
||||
$(ENV_FILLED) > .env; \
|
||||
echo "new .env with random $(ENV_SECRETS)"; \
|
||||
else \
|
||||
$(ENV_FILLED) | $(ENV_APPEND_MISSING); \
|
||||
fi
|
||||
@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, s3, rabbitmq -> migrate, s3-bootstrap -> api ×
|
||||
# API_REPLICAS, cleaner, worker -> 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"
|
||||
|
||||
# удалить контейнеры стенда и volumes с данными: только после ввода yes
|
||||
.PHONY: wipe_data
|
||||
wipe_data:
|
||||
@project=$$($(DC) config | sed -n 's/^name: //p'); \
|
||||
volumes=$$($(DC) config --volumes | sed "s/^/$${project}_/" | paste -sd ' ' -); \
|
||||
read -p "Удалить все данные стенда (volumes Postgres, S3 и брокера: $$volumes)? Введите 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
|
||||
|
||||
|
||||
# -------------------------
|
||||
# S3 (SeaweedFS, байты вложений)
|
||||
# -------------------------
|
||||
|
||||
# S3 стенда и его bootstrap: --wait ждёт healthcheck сервера, но
|
||||
# одноразовый сервис считает готовым уже запущенным, поэтому bootstrap —
|
||||
# отдельным up с его кодом выхода (как миграции в rolling-update.sh)
|
||||
.PHONY: start_s3
|
||||
start_s3: env_setup
|
||||
$(DC) up -d --wait s3
|
||||
$(DC) up --no-deps --exit-code-from s3-bootstrap s3-bootstrap
|
||||
|
||||
# плавная остановка ~15 с (stop_grace_period 20 с)
|
||||
.PHONY: stop_s3
|
||||
stop_s3:
|
||||
$(DC) stop s3
|
||||
|
||||
# брокер стенда: --wait ждёт healthcheck; данные — в volume rabbitmq_data
|
||||
.PHONY: start_broker
|
||||
start_broker: env_setup
|
||||
$(DC) up -d --wait rabbitmq
|
||||
|
||||
.PHONY: stop_broker
|
||||
stop_broker:
|
||||
$(DC) stop rabbitmq
|
||||
|
||||
# проверка приватности bucket вне API на запущенном стенде: права ключа
|
||||
# API, чужой bucket и административные запросы (bootstrap в режиме check),
|
||||
# анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети;
|
||||
# таблица «проверка → ожидаемо → получено», проверочные объекты и bucket
|
||||
# удаляются. Код 1 — нарушение
|
||||
.PHONY: s3_check
|
||||
s3_check:
|
||||
$(PYTHON) .claude/skills/run-mtusi-messenger/driver.py s3-check
|
||||
|
||||
# разовая сверка bucket и БД в контейнере уборщика (образ собирает
|
||||
# make run_docker): по умолчанию dry-run — отчёт без изменений; APPLY=1 —
|
||||
# исправить, MAX_CHANGES=N — предел изменений прохода вместо [reconciler]
|
||||
# max_changes; STRATEGY=head — HEAD на строку вместо страниц, DEEP=1 —
|
||||
# глубокая (SHA-256 содержимого), RATE=R — предел скорости, объектов S3 в
|
||||
# секунду (0 — без предела) вместо [reconciler] max_objects_per_second.
|
||||
# Код 0 — расхождений нет, 3 — остались, 1 — прерван, 2 — конфигурация
|
||||
# (design change track2-reconciler, решения 1 и 8; track2-reconcile-cost,
|
||||
# решения 4–6)
|
||||
.PHONY: reconcile
|
||||
reconcile:
|
||||
$(DC) run --rm --no-deps cleaner reconcile$(if $(filter 1,$(APPLY)), --apply)$(if $(MAX_CHANGES), --max-changes $(MAX_CHANGES))$(if $(STRATEGY), --strategy $(STRATEGY))$(if $(filter 1,$(DEEP)), --deep)$(if $(RATE), --max-objects-per-second $(RATE))
|
||||
|
||||
|
||||
# -------------------------
|
||||
# Реплики за балансировщиком (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)
|
||||
|
||||
UPLOADS_LABEL ?= baseline
|
||||
|
||||
# уровень 4 лабы 4: память реплики при одновременных загрузках на стенде
|
||||
# mtusi-bench (HAProxy, одна реплика 1 CPU / 512 МБ без swap, S3 рабочего
|
||||
# стенда): варианты «до» (Profile.uploads_before), «без лимита» и «с
|
||||
# лимитом» × тела 1 и 10 MiB × 1/10/20/40 клиентов × 3 повтора, на каждый
|
||||
# прогон — новые S3 и реплика; пик памяти окна, OOM, ответы по кодам,
|
||||
# загрузок/с; ~50 мин; результат — evidence/uploads/$(UPLOADS_LABEL)/
|
||||
.PHONY: bench_uploads
|
||||
bench_uploads:
|
||||
$(KEEP_AWAKE) uv run python bench/run.py --profile uploads --label $(UPLOADS_LABEL)
|
||||
|
||||
# то же коротко (самопроверка): «без лимита» и «с лимитом», 10 MiB, 1/10/40
|
||||
# клиентов, один повтор, ~5 мин; в git не идёт
|
||||
.PHONY: bench_uploads_quick
|
||||
bench_uploads_quick:
|
||||
$(KEEP_AWAKE) uv run python bench/run.py --profile uploads_quick --label quick-uploads-$(shell date -u +%Y%m%dT%H%M%SZ)
|
||||
|
||||
# Очередь под перегрузкой (лаба 5, трек 1; design change track1-queue-overload):
|
||||
# стенд mtusi-bench с S3, брокером, relay, worker и уборщиком, настройки
|
||||
# конкуренции и prefetch × классы изображений × 3 повтора и блоки предела, приёма,
|
||||
# второго worker и рестартов, на каждую ячейку — свежий стенд; ~2 ч 10 мин;
|
||||
# результат — evidence/queue/$(QUEUE_LABEL)/. RESUME=1 — продолжить прерванную метку
|
||||
# на том же commit
|
||||
QUEUE_LABEL ?= baseline
|
||||
.PHONY: bench_queue
|
||||
bench_queue:
|
||||
$(KEEP_AWAKE) uv run python bench/run.py --profile queue --label $(QUEUE_LABEL) $(if $(RESUME),--resume)
|
||||
|
||||
# то же коротко (самопроверка, защита): две настройки, предел с пределом 40 и без
|
||||
# него, рестарт worker, второй worker, окна короче, ~11 мин; в git не идёт
|
||||
.PHONY: bench_queue_quick
|
||||
bench_queue_quick:
|
||||
$(KEEP_AWAKE) uv run python bench/run.py --profile queue_quick --label quick-queue-$(shell date -u +%Y%m%dT%H%M%SZ)
|
||||
|
||||
RECONCILE_LABEL ?= baseline
|
||||
|
||||
# трек 2 «5» лабы 4: стоимость сверки bucket и БД на стенде mtusi-bench
|
||||
# (HAProxy, две реплики, PostgreSQL, Valkey и S3 с лимитами рабочего
|
||||
# стенда, разовые проходы уборщика 0,25 CPU / 256 МБ, в управляемом опыте
|
||||
# 1 CPU): наполнение мимо API, этапы 1 000 × 1 MiB и 10k → 30k → 100k ×
|
||||
# 4 KiB, стратегии batch и head, глубокая сверка, фоновая нагрузка с
|
||||
# пределом скорости и без, отказ по пределу на образе до change
|
||||
# (Profile.reconcile_before) и checkout, 3 повтора; ~50 мин; результат —
|
||||
# evidence/reconcile/$(RECONCILE_LABEL)/ (design change track2-reconcile-cost)
|
||||
.PHONY: bench_reconcile
|
||||
bench_reconcile:
|
||||
$(KEEP_AWAKE) uv run python bench/run.py --profile reconcile --label $(RECONCILE_LABEL)
|
||||
|
||||
# то же коротко (самопроверка): 2 000 × 4 KiB, по одному проходу каждого
|
||||
# вида, окна под нагрузкой по 5 с, отказ по пределу с 300 кандидатами,
|
||||
# ~4 мин (3,7 мин на шумном хосте, 2026-10-23); в git не идёт
|
||||
.PHONY: bench_reconcile_quick
|
||||
bench_reconcile_quick:
|
||||
$(KEEP_AWAKE) uv run python bench/run.py --profile reconcile_quick --label quick-reconcile-$(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
|
||||
|
||||
# быстрые тесты сервисов на фейках: без PostgreSQL, Valkey, S3, брокера, docker
|
||||
# и сети (design change unit-of-work, решение 13). Каталог вне student-tests:
|
||||
# правило black-box там прежнее
|
||||
.PHONY: service_test
|
||||
service_test:
|
||||
uv run pytest -c service-tests/pytest.ini service-tests/unit
|
||||
|
||||
# настоящая единица работы, тот же набор условий repo на SQL и общий срок запроса
|
||||
# на временной базе test_uow_<db> в PostgreSQL стенда; база создаётся и мигрирует
|
||||
# в начале, удаляется при любом исходе, рабочая база не затрагивается
|
||||
.PHONY: service_test_db
|
||||
service_test_db: start_db
|
||||
uv run pytest -c service-tests/pytest.ini service-tests/db
|
||||
|
||||
# образ на временной базе test_<POSTGRES_DB>: сборка, миграции, отдельный
|
||||
# контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test,
|
||||
# затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу и объекты
|
||||
# S3 для разбора. Valkey и S3 общие с рабочим стендом: ключи кэша и
|
||||
# объектов разделены именем базы, префикс test_<db>/ удаляется при уборке.
|
||||
# $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку
|
||||
.PHONY: test_isolated
|
||||
test_isolated: env_setup start_db start_cache start_s3 start_broker
|
||||
$(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"
|
||||
|
||||
+275
@@ -0,0 +1,275 @@
|
||||
# Вопросы и решения лабы 5
|
||||
|
||||
Решения, принятые без пользователя, и вопросы, которые не блокируют работу.
|
||||
Раздел на каждый change: `## <change>`, внутри «Решения» и «Вопросы».
|
||||
Вопросы преподавателю дублируются в `REPORT.md`.
|
||||
|
||||
## Ответы пользователя перед прогоном (2026-10-31)
|
||||
|
||||
- Оценка — 5, трек 1 «Очередь под перегрузкой».
|
||||
- Брокер — RabbitMQ 4.
|
||||
- Без пользователя можно: коммиты на ветках `feat/<change>`, ff-merge в
|
||||
`solution/bvt2301-safronov`, архивация, установка зависимостей и образов,
|
||||
запуск стенда и замеров, в конце `git push` ветки решения в свой fork.
|
||||
PR не открывать.
|
||||
- Противоречие в контракте: брать самую строгую трактовку, которая проходит
|
||||
публичные тесты, контракт и тесты не менять, записать решение и вопрос
|
||||
преподавателю здесь и в `REPORT.md`, прогон не останавливать.
|
||||
- Предупреждения о хосте, явно не влияющие на результат замера, прогон не
|
||||
останавливают.
|
||||
|
||||
## Ответы пользователя во время прогона (2026-10-31)
|
||||
|
||||
- Паттерн Unit of Work входит в лабу: полный вариант для всех сервисов (API,
|
||||
worker, relay, уборщик, replay): сервисы получают UoW вместо `AsyncSession` и
|
||||
`db_scope`, repo доступны через него. Поведение и контракт не меняются.
|
||||
- UoW — полноценно по Cosmic Python (указание пользователя). Прогон понимает это как
|
||||
главы 2 и 6: абстрактные repo и UoW, реализации на SQLAlchemy, `async with uow`
|
||||
в сервисе, откат при выходе без `commit`, фейки и быстрые тесты сервисов на них.
|
||||
Фейковые тесты — новый каталог вне `student-tests/`, правило black-box там остаётся.
|
||||
Не входят: доменная модель с classical mapping, агрегаты, события и message bus.
|
||||
- Порядок: отдельный change `unit-of-work` после архивации
|
||||
`pipeline-reliability` и до `track1-queue-overload`: трек 1 измеряет итоговый код.
|
||||
|
||||
## Для пользователя после прогона
|
||||
|
||||
- Остался volume пробы `asyncprobe_rabbitmq_data` (стадия propose
|
||||
`async-attachments`, контейнеров и сети нет). Агенту отказали в
|
||||
`docker compose down -v`, поэтому прогон его не удалял. Удалить вручную:
|
||||
`docker volume rm asyncprobe_rabbitmq_data`.
|
||||
- Остались volumes проб и временных проектов этого прогона: `bootprobe_s3_data`,
|
||||
`mtusi-lab5-rs_postgres_data`, `mtusi-lab5-rs_s3_data`,
|
||||
`mtusi-rsig_postgres_data`, `mtusi-rsig_rabbitmq_data`, `mtusi-rsig_s3_data`.
|
||||
Прогон их не удалял. Перед удалением убедиться, что контейнеров на них нет
|
||||
(`docker ps -a --filter volume=<имя>`), затем `docker volume rm <имя>`.
|
||||
- На хосте 150 анонимных volumes. Чьи они, не проверялось, часть может быть
|
||||
чужой, поэтому `docker volume prune` без просмотра запускать не стоит.
|
||||
- Остались volumes пробы стадии propose `track1-queue-overload`:
|
||||
`q1probe_postgres_data`, `q1probe_rabbitmq_data`, `q1probe_s3_data` (контейнеров,
|
||||
сетей и образов нет). При уборке автопроверка отказала в команде с `docker compose
|
||||
… down -v`, поэтому прогон их не удалял. Удалить вручную: `docker volume rm
|
||||
q1probe_postgres_data q1probe_rabbitmq_data q1probe_s3_data`.
|
||||
|
||||
## Перенос из лабы 4
|
||||
|
||||
### Решения
|
||||
|
||||
- Три изменения по уровням рубрики: `async-attachments` (3),
|
||||
`pipeline-reliability` (4), `track1-queue-overload` (5).
|
||||
- `Makefile`, `.gitignore`, `.dockerignore` лабы 4 совпадают с новым skeleton
|
||||
плюс свои секции, поэтому взяты целиком. `.env.example` — свой файл лабы 4:
|
||||
новые имена skeleton (`BROKER_URL_FILE`, `WORKER_CONCURRENCY`,
|
||||
`JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS`, `STAGING_RETENTION_SECONDS`)
|
||||
сопоставляет change `async-attachments`.
|
||||
- `evidence/` не переносится: сверка покрытия `make student_test` красная по
|
||||
`test_exclusion_evidence_exists`, пока файлы не сняты заново на стенде лабы 5
|
||||
(последний шаг прогона).
|
||||
- Commit «до» профилей `rollout`, `uploads` и `reconcile` стенда `bench/` —
|
||||
commit переноса: коммитов лабы 4 в истории лабы 5 нет. Вариант «до» у
|
||||
`uploads` и `reconcile` больше не показывает старое поведение, эти профили
|
||||
остались как инструменты, их результаты — в отчёте лабы 4.
|
||||
|
||||
### Вопросы
|
||||
|
||||
Пока нет.
|
||||
|
||||
## async-attachments
|
||||
|
||||
Подробности и отвергнутые варианты — `openspec/changes/archive/2026-10-31-async-attachments/design.md`.
|
||||
|
||||
### Решения
|
||||
|
||||
- **Очередь — классическая durable**, а не quorum: на одном узле реплик нет, задержка на
|
||||
пробе выше, счётчик доставок и at-least-once dead-lettering не нужны, реестр `failed` и
|
||||
счёт попыток — в PostgreSQL (решение 4). Аргументов у очереди нет: DLX и пределы следующие
|
||||
изменения ставят политиками.
|
||||
- **Образ брокера — `rabbitmq:4.3.7`**, а не свежий 4.4.0; предел памяти задан явно: брокер не
|
||||
видит лимит контейнера (проба: 4760 МиБ при лимите 512 МБ); `hostname` постоянный, иначе
|
||||
пересозданный контейнер не находит данные в volume.
|
||||
- **Staging — приватный префикс того же bucket**, `<база>/staging/<id>/original`. Сверка его не
|
||||
видит: её префикс — `<база>/attachments/`. Конечный ключ оригинала назначается при вставке;
|
||||
отдельная колонка `staging_key` оставляет очистку staging следующему изменению.
|
||||
- **Запись намерения:** `queued` и задание — одна транзакция; это и есть будущий outbox
|
||||
(`state = 'queued' AND published_at IS NULL`). Отдельной таблицы outbox и relay на этом уровне
|
||||
нет.
|
||||
- **Брокер недоступен — 503, не 202** (решение 3): без relay намерение никто не доставит. Отмена —
|
||||
условной транзакцией: задание уже взято — 202, иначе вложение возвращается в `pending` и уходит
|
||||
к уборщику. Разрыв COMMIT и publish назван в спеке, design и `REPORT.md`.
|
||||
- **`/health/ready` — только PostgreSQL:** брокер и worker не входят, как S3 (решение 10). Иначе отказ
|
||||
брокера вывел бы все реплики из LB.
|
||||
- **Повтор — фиксированная пауза** (`[worker] retry_delay_seconds`) и новое сообщение с `attempt + 1`, а не
|
||||
`nack`: контракт требует, чтобы `attempt` отражал управляемую попытку. Backoff с jitter — следующее
|
||||
изменение. Каждая начатая попытка считается; при недоступном PostgreSQL записать нечего, задание ждёт в
|
||||
очереди.
|
||||
- **Коды:** `invalid_image`, `processing_failed` (объект staging отсутствует или испорчен), `retry_exhausted`.
|
||||
Причина для оператора — `attachment_jobs.last_error_code` и журнал worker.
|
||||
- **Порядок проверок сообщения:** неизвестное, чужое и `pending` — 404 до ключа; `failed` — 409 после захвата
|
||||
ключа, с откатом. В списке есть и то и другое — 404.
|
||||
- **Ключ эффекта** `(attachment_id, pipeline_version, variant)` — первичный ключ `attachment_variants`. Оригинал —
|
||||
не строка этой таблицы: схема `Variant` контракта не знает имени `original`, его итог — поля самого вложения.
|
||||
- **Thumbnail считается своим кодом,** а не `Image.thumbnail`: Pillow округляет к ближайшей пропорции, контракт
|
||||
— вниз. Лимит worker 1 ГБ — по замеру: две задачи PNG RGBA на 40 Мпкс ≈ 800 МиБ.
|
||||
- **Один пользователь брокера на API и worker:** разделение прав — лаба 7. Management-плагина нет, состояние
|
||||
очереди — `rabbitmqctl` в контейнере.
|
||||
- **Сопоставление имён skeleton:** `BROKER_URL_FILE` → `[broker]` мостами из `RABBITMQ_*`; `WORKER_CONCURRENCY` →
|
||||
`[worker] concurrency`; `JOB_MAX_ATTEMPTS` → `max_attempts`; `JOB_TIMEOUT_SECONDS` → `job_timeout_seconds`;
|
||||
`STAGING_RETENTION_SECONDS` — поля пока нет, появляется с очисткой staging.
|
||||
- **Цепочка LB:** срок публикации 2 с: после тела 29 с < `timeout server` 30 с, наибольшая длительность загрузки 76 с
|
||||
< дренаж 90 с. Прежние значения LB не меняются.
|
||||
- **Apply:** `request_id` записей задания ставит сервис обработки сразу после разбора сообщения (а не `main.py`): разбор — его
|
||||
шаг, задача доставки своя, контекст не течёт. `DROP` — третий исход `JobOutcome` рядом с `ACK` и `REQUEUE` дизайна: сообщение не
|
||||
по схеме возвращать в очередь нельзя. Сообщение задания с `attachment_id` не своей строки считается неизвестным (`ACK`).
|
||||
Подробности — design, «Уточнения apply».
|
||||
- **Группа 15:** снят ещё `make bench_uploads` (метка `baseline`): на неё ссылаются два исключения сверки, а в плане снятия её не было. Новые файлы `evidence/` на время замеров вынесены из дерева, чтобы паспорта не получили ложный `dirty: true`. Design, «Уточнения apply», п. 16–17.
|
||||
- **Найдено при снятии, не исправлено** (код в группе 15 не меняется, запись в `KNOWN_ISSUES.md` — за основной сессией): в записи «Uploaded attachment» поле `content_type` пишется как `<ImageType.PNG: 'image/png'>`, а не `image/png` (`src/core/services/attachment.py`, `_store`; `evidence/worker/logs.md`). Секретов там нет, запись читается хуже.
|
||||
|
||||
### Предложения на потом
|
||||
|
||||
Найдено проверкой `async-attachments`, код `src/` здесь не менялся: evidence снят на `ff1a83b`. Все пять закрыты изменением `pipeline-reliability` (S5, S6, W2 — кодом worker; два последних пункта — дельтой `load-benchmark` и `bench/run.py`).
|
||||
|
||||
- **S5, срок закрытия worker:** комментарий `_CLOSE_TIMEOUT_SECONDS` (`src/worker/main.py:41-43`) обещает сумму меньше срока остановки контейнера 10 с, а худший случай — 8 + 5 × 0,5 = 10,5 с, при `graceful_shutdown_seconds` 9 — 11,5 с. Либо уменьшить составляющие, либо поправить комментарий и верхнюю границу настройки.
|
||||
- **S6, пауза повтора и сигнал:** сигнал прерывает паузу и даёт `REQUEUE`, а claim не смотрит `next_attempt_at`: перезапущенный worker начнёт попытку раньше паузы (`attachment_processing.py`).
|
||||
- **W2, дубль после `busy`:** `redelivered` стоит и после `nack(requeue=True)`, поэтому при попытке дольше паузы дубль возьмёт задание параллельно живой попытке и потратит её номер, а на последней попытке даст `retry_exhausted`, пока первая ещё идёт (`attachment_processing.py:230`; design, решение 7). Эффект не дублируется. Закрывается lease: живую попытку отличать по `lease_expires_at`, а не по флагу.
|
||||
- **Спек `load-benchmark`, «Профиль сверки»:** там всё ещё «на образе до change», а `reconcile_before` = `04f8592`: та же неточность, что исправлена у профиля загрузок. Требования нет в дельте этого change, поэтому оно здесь не менялось.
|
||||
- **`bench/run.py:1744, 2941`:** в паспорт пишется `.Image` как `id` образа, а сравнивать образы надо по метке `com.docker.compose.image` (`.claude/rules/docker.md`).
|
||||
|
||||
### Вопросы
|
||||
|
||||
Вопросы преподавателю, переносятся в `REPORT.md` (`tasks.md`, задача 15.5). Прогон не останавливают: взята самая
|
||||
строгая трактовка, которая проходит публичные тесты, контракт и тесты не менялись.
|
||||
|
||||
1. Failed-вложение прикреплять нельзя (409), а повтор с тем же `Idempotency-Key` обязан вернуть тот же 201. Что отвечать на
|
||||
повтор сообщения, чьё вложение стало `failed` уже после отправки? Сделано: новое сообщение — 409, повтор с ключом — 201 с
|
||||
тем же `Message`. Другой ответ меняет одну ветку `send_message` и сценарий `idempotency`.
|
||||
2. `contracts/attachment-states.md`: «неуспешные и непривязанные исходники имеют документированный retention и cleanup» — без
|
||||
уровня рубрики, а в `README.md` очистка относится к уровню 4. Сделано: на уровне 3 очистки нет, ограничение названо в
|
||||
`REPORT.md`, очистка и `STAGING_RETENTION_SECONDS` — в `pipeline-reliability`. Другой ответ переносит задачу очистки на этот
|
||||
уровень; схема к ней готова.
|
||||
3. Допустим ли на уровне 3 ответ 503 при недоступном брокере? Контракт требует 202 только после устойчивой передачи; на уровне 3 нет
|
||||
relay, поэтому намерение в БД само не доставится. Сделано: 503 с понятным отказом, на уровне 4 с relay станет 202. Другой ответ
|
||||
требует relay уже здесь.
|
||||
|
||||
## pipeline-reliability
|
||||
|
||||
Подробности и отвергнутые варианты — `openspec/changes/archive/2026-10-31-pipeline-reliability/design.md`; пробы — его таблица «Пробы» (проект compose `plprobe`, volumes не создавались, после проб ничего не осталось).
|
||||
|
||||
### Решения
|
||||
|
||||
- **Вопросы №2 и №3 раздела `async-attachments` закрывает это изменение.** №3: отказ брокера больше не даёт 503, на загрузке 503 только от S3 и PostgreSQL; реплики API вообще не обращаются к брокеру и не получают его пароль. №2: срок хранения `[cleaner] staging_retention_seconds`, 86400 с — значение из `.env.example` skeleton.
|
||||
- **Relay — отдельный сервис** на образе API (`python -m src.relay`, 0,25 CPU / 256 МБ, пул 1), а не задача реплик, worker или уборщика: остановка worker на защите не должна останавливать публикацию, плановая сверка уборщика не должна её задерживать. Намерения — те же строки `attachment_jobs`, отдельной таблицы outbox нет.
|
||||
- **Публикация внутри транзакции** — исключение из правила «брокера в транзакции нет», как DELETE уборщика: `FOR UPDATE SKIP LOCKED` на пакет и есть защита двух relay от дублей. Срок 2 с меньше срока шага 6 с и простоя транзакции 10 с.
|
||||
- **Опрос 0,25 с, а не LISTEN/NOTIFY:** опрос всё равно нужен для сроков, а пустая выборка стоит 0,05 мс (проба).
|
||||
- **Сообщение — подсказка, истина в строке задания.** Worker больше не публикует и не ждёт паузу в месте конкуренции: следующую попытку публикует relay по `next_attempt_at`. Дубль при живой аренде и сообщение раньше срока подтверждаются без эффекта. Это закрывает W2 и S6.
|
||||
- **Аренда без пульса:** срок = `job_timeout_seconds` + `lease_margin_seconds` (70 с). Попытка теперь жёстко ограничена сроком, поэтому истёкшая аренда значит «мёртв или заморожен». Цена — после KILL worker следующая попытка ждёт до 70 с.
|
||||
- **Fencing номером попытки:** результат прежней попытки больше не принимается (на уровне 3 принимался). Поэтому номер `attempt` монотонен, а бюджет после replay — колонка `attempt_base`.
|
||||
- **Backoff:** случайная величина из `[d / 2, d]`, `d = min(300, 5 × 2^(N−1))`. Полный jitter отвергнут: нижняя граница суммы пауз стремилась бы к нулю, и рестарт S3 (~25 с) мог бы исчерпать попытки; сейчас сумма 37,5–75 с.
|
||||
- **Реестр `failed` — в PostgreSQL, DLQ брокера нет:** всё принятое живёт в БД, а сообщение не по схеме работы не несёт. Replay — операторская команда `make replay` (dry-run по умолчанию, с `--apply` выбор обязателен), аудит — таблица `attachment_job_replays`.
|
||||
- **Декодирование — новый процесс на задание:** без секретов в окружении, с `RLIMIT_AS`, `RLIMIT_CPU` и сроком. Проба нашла JPEG в пределах контракта, который не декодируется за 60 с: 10 MiB повторённых сканов. Цена — ~100 мс CPU на маленьком файле; forkserver (9 мс) отвергнут сейчас, граница — один модуль, если трек 1 покажет необходимость.
|
||||
- **Лимиты по умолчанию:** память 450 МиБ (наибольший `VmPeak` на пробе 417), CPU 15 с (наибольшее законное 0,55 с), срок 40 с, меньше срока попытки. Лимит памяти не действует на хосте macOS: `setrlimit` отказывает, в журнале это видно.
|
||||
- **Новых значений `error_code` нет:** лимиты дают `invalid_image`, причина — в `last_error_code`. Реплика прежней версии упала бы на незнакомом значении enum.
|
||||
- **Варианты:** `thumbnail` и `crop` — JPEG, `quality` 85; `optimized` — WebP, `quality` 80, `method` 4 (`method` 6 на пробе в 3,5 раза дольше без выигрыша), без EXIF, XMP и ICC. Crop из основы 1280 только при короткой стороне не меньше 256, иначе из декодированного: у 5000 × 10 иначе квадрат в 2 px. Профиль ICC отбрасывается, ограничение в отчёте.
|
||||
- **Staging удаляет уборщик, не worker:** право удаления у него уже есть, а worker читает и пишет весь bucket. Цена — объект живёт до следующего прохода, 60 с.
|
||||
- **Сверка** видит объекты staging: `orphan_staging` с порогом срока хранения, а не grace: база, восстановленная из копии, иначе быстро сделала бы staging живых строк «объектами без метаданных». Наличие объектов вариантов не проверяет: действия нет, рубрика не требует; ограничение остаётся в отчёте.
|
||||
- **Точек сбоя в коде нет:** самое узкое окно «после COMMIT до ack» снимается снаружи: отложенный триггер, `pg_stat_activity`, `docker kill -s STOP`, `docker kill` (проба).
|
||||
- **Остановка worker (S5):** верхняя граница `graceful_shutdown_seconds` — 8, закрытие клиентов одним сроком, худший случай 9,5 с.
|
||||
- **`bench/`:** профиль загрузок больше не запускает брокер, `Profile.rollout_from` → `7f38948`, образ в паспорте — метка `com.docker.compose.image`.
|
||||
- **Сценарии «Брокер не подтвердил задание» и «Загрузка без подтверждения брокера убрана» сохранены именем:** `openspec validate --strict` не даёт убрать сценарий правкой дельты. Первый теперь про 202 при остановленном брокере, второй — про реплику прежней версии на время замены.
|
||||
- **Решения apply (подробно — design, «Уточнения apply»):** у `make replay` `--attachment-id` и фильтр по коду или причине вместе нельзя (код 2); `FOR NO KEY UPDATE` и ack после фиксации проверяются пробой блокировки строки и счётчиком `messages_unacknowledged`: прежний вид тестов этих регрессий не замечал; откат реплик на прежний образ — с `infra/rollback/broker.compose.yml`, без него загрузка 503; зависший worker в тесте — отдельный процесс с длинными сроками и `expire-lease`, иначе его прерывал бы таймер, а не fencing.
|
||||
- **Удалено при коммите:** `src/utils/thumbnail.py` и `src/infra/broker/instance.py` без импортов удалила основная сессия, вошло в `e2a6427`.
|
||||
- **Группа 15:** метка `bench_rollout` снята первой, на чистом дереве, остальные доказательства — после: новые файлы `evidence/` выносить из дерева не пришлось (`git.dirty` false). Полный `make failure_checks` — при остановленном рабочем стенде, чтобы не сужать малый запас времени к концу набора: 140 из 140, тесты не правились. `driver.py pipeline-state` при замороженном брокере — отдельный файл `evidence/relay/pipeline-state.md`; `broker-check --require-test-queue` снят между двумя `make test_isolated`. `evidence/s3/worker-key.md`, `evidence/migrations/async-attachments.md`, метки `evidence/rollout/async-attachments`, `evidence/uploads/baseline` остаются со своим `ff1a83b`: это переход уровня 3, новые снимки — `evidence/s3/cleaner-staging.md`, `evidence/migrations/pipeline-reliability.md`, метка `evidence/rollout/pipeline-reliability`.
|
||||
- **Правки по проверке (группа 16):** исходник закрывается только при переводе в RGBA: остальные ветки `_prepared` на границе и так укладываются в лимит (пробы, design, «Уточнения apply», п. 19). Тест типов PNG — в обычном наборе (`test_pixel_limit_png_modes`), а не в проверках отказов: особого стенда ему не нужно. Прежний поток зависшего worker сохранён отдельным тестом `test_hung_worker_thawed_after_ready`: усиленный `test_hung_worker_lease_fencing` его не заменяет, сценарий «Зависший worker» проверяет другое окно. Для второй попытки hook получил `run-worker-second`: основной worker стенда со сроком 10 с при разморозке прервал бы таймер.
|
||||
- **Архив:** перед архивом основные спеки сверены с дельтами по требованиям, описаниям и сценариям, правок вне дельт от `99a222e` нет, поэтому синхронизация ничего не изменила. Каталог перенесён `mv` по шагу 5 `/opsx:archive`: `openspec archive` применил бы дельты повторно к уже обновлённым спекам. Запись «Три изменения по уровням рубрики» в разделе «Перенос из лабы 4» оставлена как решение своего времени; порядок после архива — `unit-of-work`, затем `track1-queue-overload` (`AGENTS.md`).
|
||||
|
||||
### Вопросы
|
||||
|
||||
Вопросы преподавателю, переносятся в `REPORT.md` (`tasks.md`, задача 15.5). Прогон не останавливают: взята самая строгая трактовка, которая проходит публичные тесты, контракт и тесты не менялись.
|
||||
|
||||
1. Контракт требует применять EXIF orientation и компоновать alpha на белый только у thumbnail. Как с `crop` и `optimized`? Сделано: ориентация применяется у обоих (иначе EXIF, удалённый из WebP, повернул бы изображение), `crop` компонуется на белый (JPEG), а `optimized` сохраняет прозрачность (WebP её умеет). Другой ответ правит одну функцию и сценарий.
|
||||
2. Контракт называет replay «явным операторским», но не говорит, как его вызывать, а новые возможности просит добавлять в `contracts/extensions.openapi.json`. Достаточно ли команды в контейнере? Сделано: `make replay`, HTTP-ручки нет: в API нет роли оператора. Другой ответ добавляет ручку поверх той же транзакции.
|
||||
3. Изображение, которое не уложилось в лимиты времени или памяти обработки, — это `invalid_image` или отдельный код? Контракт приводит коды как пример. Сделано: `invalid_image`, точная причина — в записи для оператора. Другой ответ добавляет значение enum и требует порядка обновления реплик раньше worker.
|
||||
4. Контракт требует retention для «неуспешных и непривязанных исходников», но молчит о конечных объектах, которые успела записать неудачная попытка. Сделано: по истечении срока удаляются и они, метаданные `failed` остаются. Другой ответ убирает один шаг очистки.
|
||||
5. Секреты worker читаются процессом обработки через `/proc/1/environ` под тем же UID: окружение самого процесса обработки их не содержит, но после эксплойта декодера защиты нет. Кодом не исправлено, ограничение названо в `REPORT.md` и `worker.md`. Предложение: `prctl(PR_SET_DUMPABLE, 0)` в процессе worker до запуска процессов обработки: тогда чужой процесс того же UID не откроет его `/proc/<pid>/environ` и `mem`. Требуется ли это на уровне лабы?
|
||||
|
||||
## unit-of-work
|
||||
|
||||
Подробности и отвергнутые варианты — `openspec/changes/archive/2026-11-01-unit-of-work/design.md`; пробы — его раздел «Пробы» (проект compose `uowprobe`, данные в tmpfs, volumes не создавались, после проб ничего не осталось).
|
||||
|
||||
### Решения
|
||||
|
||||
- **Общий срок JSON-запроса остался, это расхождение с буквальной постановкой** «`request_timeout_seconds` — срок UoW, а не запроса» (решение 6). Срок блока — как в постановке, но на роутерах пользователей, сессий, чатов и сообщений сверх него стоит зависимость `request_deadline` той же настройкой. Без неё проба дала 503 за 3,31 с вместо 2 с при сроке 2 с (при 6 с — до 12 с, больше `timeout server` 10 с: 504 от LB вместо 503 реплики), и очередь хэшей шла без срока: 40 входов ждали 4,69 с вместо отказа за 2 с. Отменить решение просто (убрать `dependencies=` у четырёх `include_router`), но тогда придётся менять цепочку LB и её спек.
|
||||
- **Откат при выходе из блока — под сроком, отмена задачи сбрасывает соединение** (решение 4). Прежний `session_scope` откатывал уже вне срока: на JSON-ручках незаметно (после ответа), на шаге замороженный PostgreSQL повесил бы готовый ответ до разморозки (проба: 8,38 с и 8,64 с против 4,01 с). Цена: отказ БД при откате успешного чтения — 503, окно в один обмен.
|
||||
- **Цена шага принята, проверка соединения при выдаче — одним запросом** (решение 7). На пробе вторая выдача опускает потолок реплики 1 CPU на истории и отправке на 10–25 %, CPU PostgreSQL поднимает на 13–51 %. Проверка диалекта asyncpg стоит три обмена (`BEGIN`, `;`, `ROLLBACK`, транзакция там ради pgbouncer, которого на стенде нет); с одним обменом CPU PostgreSQL около прежнего, потолок −1…−22 %, p50 +0,2…0,5 мс, удержание соединения на запрос −20…−36 % (шум прежнего кода между прогонами до 10 %). Это мера, а не часть паттерна; подмена опирается на внутренние имена адаптера, SQLAlchemy закреплён `<2.2`. Чтение без транзакции и соединение Core вместо сессии ORM отвергнуты и остаются готовыми мерами, если замер на коммите покажет больше.
|
||||
- **Порты — `src/core/ports/`, реализации repo остаются в `src/core/repos/`, `SqlAlchemyUnitOfWork` — `src/infra/db/uow.py`** (решение 1). Атрибуты единицы работы: `users`, `sessions`, `chats`, `messages`, `idempotency`, `attachments`, `jobs`, `variants`, `job_replays`.
|
||||
- **Строже книги:** вложенный вход и repo вне блока — ошибка, commit заканчивает блок (решение 2). Весь нынешний код и так фиксирует последним действием блока; autobegin `AsyncSession` иначе открыл бы молчаливую транзакцию без срока.
|
||||
- **Экземпляр единицы работы — на задачу:** запрос в API, доставка в worker, сервис в последовательных процессах (решение 3).
|
||||
- **`CurrentUserBrief` убран:** любой вход теперь короткий блок, а различие с JSON-ручками — только в общем сроке на роутере (решение 6). Свойство «соединение в пуле до тела запроса» сохраняется.
|
||||
- **Кэш и S3 — те же модули с клиентом первым параметром;** в тестах настоящие функции поверх фейков клиентов (решение 8).
|
||||
- **Фейки — по контракту метода, общий набор `service-tests/repo_contract.py` на фейке и на SQL** (решение 11). Отсюда вторая цель `make service_test_db` на временной базе: она же проверяет настоящую единицу работы и общий срок запроса, а замороженный сервер даёт TCP-прокси, без `docker pause` рабочего PostgreSQL.
|
||||
- **Каталог `service-tests/`, цели `make service_test` и `make service_test_db`;** новых зависимостей нет: `async def` тесты запускает плагин `anyio`.
|
||||
- **Новые сценарии — в capability `unit-of-work`, дельта `data-storage` только меняет текст:** `student-tests/` этим изменением не правятся, а сверка покрытия упала бы на сценарии без теста. `unit-of-work` в `CAPABILITIES` не входит: её проверяют `service-tests/`.
|
||||
- **Замер «до» — из временного `git worktree` на commit до кода,** подряд с «после» и A/A (`tasks.md`, 13.1): `make bench_ab` требует коммита отката. Метки с профилем `quick` под своими именами идут в git, потому что на них ссылается отчёт. `Profile.rollout_from` не меняется, сравнение с предыдущей версией — аргументом `--from`.
|
||||
|
||||
- **Решения apply** (`design.md`, «Уточнения apply»): `commit` и `rollback` единицы работы — в базовом классе, реальные шаги `_commit` и `_rollback`, иначе правила блока дублировались бы в фейке; `rollback()` заканчивает блок, как и `commit()`; временная база — хуки pytest, а не фикстура, чтобы удаляться и при прерывании; замороженный прокси размораживается сторожем через 8 с, чтобы регрессия падала, а не висела.
|
||||
- **`driver.py reconcile-cycle` на наполненном стенде даёт один ложный FAIL** («exit code after X and Y are removed»): на 11 тыс. объектов проход идёт ~5,8 с, и проба F (grace 30 с) стареет раньше проверки. От кода не зависит, записано в `KNOWN_ISSUES.md`, не чинилось: вне изменения.
|
||||
- **Правки verify** (`design.md`, уточнения 17–20). `BoundedCloseConnection` обрывает транспорт сам: дешёвая проверка (решение 7) превращала старую утечку сокета после заморозки в сессии PostgreSQL сверх пула без срока, откатывать её не понадобилось. При общем сроке таймера блока нет (`ContextVar` с задачей, `asyncio.timeout(None)`): иначе вторая отмена прерывала закрытие соединения. Заметное следствие: 503 при заморозке теперь приходит за `T` + закрытие, 4 с при сроке 2 с (при 6 с — 8 с < `timeout server` 10 с), а не за `T`. `service_factory` worker вынесен из `run()`, чтобы тест ловил регрессию в самой сборке.
|
||||
- **Архив:** синхронизацию и перенос каталога выполнил один вызов `openspec archive unit-of-work -y`, отдельного шага `/opsx:sync` не было: иначе `openspec archive` применил бы дельты повторно. Основные спеки затем сверены с дельтами: `unit-of-work` совпадает с дельтой, в `data-storage` изменилось только требование о пуле.
|
||||
|
||||
### Вопросы
|
||||
|
||||
Пока нет. Вопросов преподавателю это изменение не добавляет: контракт и поведение API те же.
|
||||
|
||||
### Для пользователя
|
||||
|
||||
Основная сессия приняла расхождения с первоначальной постановкой, потому что сама её сформулировала, а решения пользователя они не меняют: общий срок JSON-запроса (решение 6) и дешёвую проверку соединения при выдаче (решение 7). Условие для второго: `make service_test_db` проверяет обрыв соединения с подменённой проверкой, чтобы смена внутренних имён SQLAlchemy падала тестом. Цена паттерна на этом стенде, замер на коммите (`evidence/compare/unit-of-work-aa__unit-of-work-after.md` и `unit-of-work-before__unit-of-work-after.md`): потолок реплики на истории и отправке ниже, медианы −14,1 и −12,6 % от метки того же кода, снятой прямо перед «после» (ниже 18 ячеек из 18), −6,6 и −4,3 % от снятой позже (16 из 18). Один повтор на ячейку, две метки одного кода расходятся до 14–17 %: знак устойчив, точной величины нет. За оценку design (−1…−22 %) цена по ближней метке не вышла, число соединений то же. Рост CPU при 200/с (API +10,8 %) того же порядка, что расхождение двух прогонов одного кода (9,2 %). Вывод — `REPORT.md`.
|
||||
|
||||
## track1-queue-overload
|
||||
|
||||
Подробности и отвергнутые варианты — `openspec/changes/archive/2026-11-02-track1-queue-overload/design.md`; пробы — его раздел «Пробы» (проект compose `q1probe`, образ `git archive 5a97416`, файлы в scratchpad). Это пробы, а не результат: результат — основная метка `evidence/queue/baseline4/` (`baseline` снята раньше правок verify, `baseline2` и `baseline3` — с выгрузкой хоста).
|
||||
|
||||
### Решения
|
||||
|
||||
- **Граница принятой работы — предел незавершённых заданий (`queued` + `processing`), `[uploads] max_unfinished_jobs`, по умолчанию 250, 0 — без предела:** у предела загрузка получает 429 `rate_limited` с `Retry-After: 5`, сразу, без чтения тела и места. Без неё бэклог упирается только в диск: пробы показали, что брокер его не сдержит (200 000 сообщений — 106 МиБ анонимной памяти), а 202 отвечает всегда (решение 1).
|
||||
- **Значение 250 — из потолка худшего класса:** PNG RGBA 40 Мпкс, 0,92 задания в секунду на 1 CPU: ожидание ~270 с, меньше порога потерянного сообщения 300 с; staging не больше ~2,4 ГиБ. Проверяется меткой, при другом числе worker предел другой (решение 2).
|
||||
- **Предел один на стенд и мягкий:** считается в PostgreSQL, превышение — только загрузки в полёте, `реплик × (мест + ожидающих)`, на стенде 40. Жёсткий предел потребовал бы блокировки на фиксацию и компенсации записанного объекта. Не на чат и не на пользователя, и считает задания, а не байты: ограничения названы в отчёте.
|
||||
- **Счёт — тремя существующими частичными индексами с `LIMIT` на группу:** 0,05–0,13 мс при любом бэклоге, под оборотом до ~1 мс; нового индекса и миграции нет. Счётчик одной строкой отвергнут пробой: −16…−49 % потолка оборота заданий. Проверка — в том же блоке, что членство: шаг с PostgreSQL не прибавляется, цепочка LB прежняя (решение 3). Цена на загрузку по прототипу: +0,9 мс p50, +0,8 мс CPU реплики, +0,4 мс CPU PostgreSQL; отказ — 1,9 и 0,3 мс.
|
||||
- **Метрики очереди брокера — плагин `rabbitmq_prometheus` только в профиле:** `rabbitmqctl` стоит 0,52 с CPU в cgroup брокера на вызов и испортил бы замер (проба). На рабочем стенде плагина нет.
|
||||
- **Истина о готовности — метаданные по HTTP после разбора очереди, а не живой опрос:** `updated_at` у `ready` не меняется, опрос нагружал бы API в замере. Счётчики очереди — `psql` сэмплера, только чтение.
|
||||
- **Настройки метки:** (1, 1), (2, 2) по умолчанию, (4, 4), (2, 256), классы `s`, `m`, `lj`, `lp`; конкуренция сверх двух при 1 CPU на пробах не ускоряет, поэтому настоящее ускорение показывает блок второго worker. Значения по умолчанию меняются только по правилу решения 12, отдельным commit после метки.
|
||||
- **Копии при большом prefetch в метку не входят:** опыт требует менять порог потерянного сообщения; проба — 188 копий на 150 заданий при пороге 15 с, эффект нулевой.
|
||||
- **Профиль `uploads` и четыре прежних API стенда отказов — с выключенным пределом:** там задания копятся намеренно, предел мерил бы не то (решение 13). Пятый API — «узкий по заданиям».
|
||||
- **Worker в профиле очереди перезапускается, как на рабочем стенде (`restart: unless-stopped`):** пробы — при (4, 4) на `lp` ядро может убить и процесс 1 (журнал ядра, `exit 137`), и с `restart: "no"` ячейка простаивала бы с ложными `stuck`. Перезапуски — столбец и пометка (решение 10). У S3 остаётся `"no"`: его гибель должна быть видна.
|
||||
- **Блок приёма — `m`, 15/с, 45 с, с пределом по умолчанию:** пробы показали всю цепочку: S3, с ~10-й секунды 429 от мест, с ~35-й 429 от предела, а готовых/с падает с 2,9 до ~0,6. S3 — общий ресурс приёма и worker: гипотеза H9 (решения 4, 8, 12).
|
||||
- **Время полной метки — ~2 ч 10 мин** при трёх повторах 19 конфигураций, `RESUME=1` как у серий: окна выбраны по пробам так, чтобы уложиться (решение 14).
|
||||
- **Apply: перезапуск worker считается завершением ядром, пометка `oom`:** счётчик `oom_kill` умершей жизни прочитать нельзя, cgroup уходит раньше тика. Другие причины аварийного выхода в метке от него не отличаются (design, «Уточнения apply», п. 1).
|
||||
- **Apply: доля второго worker считается только по разбору накопленного,** без окна `after`: иначе H3 ложно не подтверждалась бы. Порог не менялся (там же, п. 2).
|
||||
- **Apply: CPU окна — с интерполяцией на краях;** разность только по внутренним отсчётам занижала его на ~10 % (там же, п. 3).
|
||||
- **Apply: блоки, которых нет в быстром профиле, проверены разово** скриптом в scratchpad поверх `run.main` (там же, п. 4).
|
||||
- **Правки verify: `oom` — только подтверждённое завершение ядром.** Причина — события Docker (`oom`, `kill`, `die` с кодом), столбцы `worker_die_*`; `oom_kill` больше не прибавляет каждый перезапуск. На этом считаются H2 и правило рекомендации; условия гипотез не менялись, а смысл стал тем, что в них написано (design, «Уточнения apply», п. 8). Осталось открытым: перезапуск не от ядра условия правила не нарушает, только пометка `worker_crash` (вопрос 3).
|
||||
- **Правки verify: настройка, снятая не на всех классах, не кандидат в рекомендацию.** Порог 90 % не менялся. По плану это (1, 1) и (2, 256): «наименьшая конкуренция» теперь выбирается только между (2, 2) и (4, 4), а (1, 1) может быть только названа. Метка `baseline` даёт тот же итог (2, 2) (там же, п. 9).
|
||||
- **Правки verify: лишняя строка в базе — отказ метки, как `lost`, но условие H6 не расширено:** пометка `unexpected` вне записанного до метки списка H6; строка, которую объясняет 5xx или обрыв, пометку не даёт (там же, п. 10).
|
||||
- **Правки verify: `UP 1/2` — реплика ещё в балансировке:** она получает запросы, `lb_down` на неё не срабатывает. Опора — сценарий «реплики MUST NOT выводиться из балансировщика» (там же, п. 11).
|
||||
- **Метка `baseline2` не основная, снимается `baseline3`:** за съёмку хост выгрузил в swap 309 432 страницы, пять ячеек с `host_swap`, в четырёх задержка вышла за разброс соседних повторов. Указание пользователя «забить» касается косяков хоста, явно не меняющих результат, а здесь результат ячеек изменился. Без пяти ячеек вердикты H1–H9 и рекомендация те же, но правило (design, решение 11; `bench.md`) записано до метки и не смягчается после. Каталог `baseline2` остаётся в git как запись. Если выгрузка повторится, третьей пересъёмки нет: основной станет метка с меньшим числом задетых ячеек, они будут названы в отчёте (задача 10.20а).
|
||||
- **Решение пользователя (2026-11-02): при выгрузке результат сохраняется, после `baseline3` — ещё один прогон `baseline4`, больше пересъёмок нет.** Отступление от правила «переснять» (design, решение 11; `bench.md`) принято по этому решению. Основная — метка с меньшим числом задетых ячеек, при равенстве — с меньшим `swapouts_delta`, выбор не зависит от вердиктов (задача 10.20б). В `baseline3` — 26 046 страниц, одна задетая ячейка, и вердикт H2 «нет»: `lp`, duration (4,4)/(2,2) = 0,965; в `baseline` и `baseline2` он был «подтверждено». Эта ячейка (`lp-c2p256-r1`) в условие не входит.
|
||||
- **Основная метка — `baseline4` (код `d68a016`, метка `b104690`):** `swapouts_delta` 0, задетых ячеек нет, H2 подтверждена, H4 нет, рекомендация (2, 2). Вердикты всех меток и разбор H2 — `REPORT.md`, «Очередь под перегрузкой». Предположение «в медиану `duration_ms` попадают в основном задания, пережившие перезапуски» по данным не подтверждено и не опровергнуто: журналы в метку не копируются, косвенный признак два вида значений не разделяет, с числом перезапусков связь есть, но неполная. Порог и вердикты не менялись.
|
||||
- **Финальные доказательства вне бенчмарка, команды драйвера.** Разовые пробы перенесены тремя командами, а не двумя: `worker-memory` (рабочий стенд, через LB), `freeze-sessions` (работает и на рабочем стенде: заморожен только прокси пробы) и `freeze-lb` (`docker pause` — запрещён на рабочем PostgreSQL). `freeze-lb` сама поднимает и убирает временный проект `mtusi-lab5-freeze`, а не ждёт его по окружению, как `reconcile-signal`: иначе проверяющему пришлось бы собирать стенд руками; данные в tmpfs, поэтому `down` без `-v` ничего не оставляет. Значения — случайные, из `.env.example`: `.env` не читается.
|
||||
- **`freeze-sessions` идёт в одноразовом контейнере `api`, а не из дерева кода через `uv run`:** так пробе не нужен `.env` и код образа совпадает со стендом. httpx в образе нет, вызовы ASGI — своим клиентом; остальная логика `double_cancel.py` та же. Прежний файл называл аргументы пробы неверно: `2 6 1` и `2 6 4` — пул 2 и 1 или 4 запроса, а не срок 2 и пул 1 или 4; добавлен режим с настоящим пулом 4.
|
||||
- **`make test_isolated` перед `cache-check` при первой съёмке — код 2.** Его набор требует файлы, которых ещё нет, а ключи временной базы он при этом оставляет: команды шли не через `&&`, причина названа в шапке `evidence/cache/hits.md`.
|
||||
- **Шаги `evidence/idempotency/replay-after-restart.md` — `driver.py req` и `docker compose`,** скрипт только соединил их: отдельной команды драйвера не заводилось, задача её не просила, а шаги повторяются руками.
|
||||
- **Пересняты `evidence/tests/student-test-lb.md` и `evidence/tests/test-isolated.md`:** задача их не называла, но на `d8fe2e8` они показывали единственный красный тест, который эта задача закрыла. `evidence/tests/failure-checks.md` остаётся на `d8fe2e8`: полный прогон на ноутбуке запрещён условиями задачи. Позже файл переснят в `4a7d89d`: прогон с шестью проверками предела стартовал на `b104690`, отчёт ссылается на него.
|
||||
- **Повторный verify: «мест на CPU» в сценарии «Бэклог уходит за измеренное время» — два на CPU worker, «без перезапусков» — и без завершений по команде:** граница H1, а столбец `worker_restarts` у `kill-worker` 0, хотя строки так же ждут аренду. Запас разброса — решение 11. Вердикты H1–H9 от этого не считаются (design, «Уточнения apply», п. 14).
|
||||
- **В `REPORT.md` добавлен вопрос 12 (`PR_SET_DUMPABLE`):** он был вопросом преподавателю в `QUESTIONS.md`, но в нумерованный список отчёта не попал.
|
||||
- **Секреты в новых файлах `evidence/` сверены по токенам и путям, не по значениям `.env`:** файл `.env` в этой работе не читается. `evidence/tests/secrets.md` остаётся на прежнем commit; поиск значений по всему `evidence/` — перед PR.
|
||||
- **Архив:** перед архивом основные спеки сверены с дельтами скриптом по требованиям, описаниям и сценариям: восемь capability, расхождений нет (задача 4.7 и правки verify), поэтому синхронизация ничего не изменила. Каталог перенесён `mv` по шагу 5 `/opsx:archive`: `openspec archive` применил бы дельты повторно.
|
||||
|
||||
### Вопросы
|
||||
|
||||
Вопросы преподавателю, переносятся в `REPORT.md` («Открытые вопросы преподавателю»). Прогон не останавливают: взята самая строгая трактовка, которая проходит публичные тесты, контракт и тесты не менялись.
|
||||
|
||||
1. Предел незавершённых заданий: 429 или 503? Контракт называет 429 «ограничением частоты запросов», а здесь ограничено количество принятой работы; 503 в нём — «зависимость недоступна». Сделано: 429 `rate_limited` с `Retry-After` — как у занятых мест загрузки (вопрос 1 в отчёте), зависимости живы, и реплика остаётся готовой. Другой ответ меняет строку `DOMAIN_ERRORS` и сценарии.
|
||||
2. Рубрика уровня 3 показывает «worker остановлен → upload 202», а трек 1 требует ограничить принятую работу. Как долго загрузка обязана отвечать 202 при остановленном worker? Сделано: пока незавершённых меньше предела (250); дальше 429, а текст, история, метаданные, готовые байты и `/health/ready` работают. Сценарий защиты грузит единицы файлов. Другой ответ — значение настройки.
|
||||
|
||||
Вопрос пользователю (основной сессии), прогон не останавливает:
|
||||
|
||||
3. Правило рекомендации требует «без `oom` и `failed`». После правки S5 аварийный перезапуск worker не от ядра (`worker_crash`) это условие не нарушает: раньше такой перезапуск считался `oom` косвенно. Условие не менялось, потому что записано до метки. В метке таких случаев не ждём (пробы: только ядро). Появится — считать настройку некандидатом? Сейчас: пометка в сводке, решение — в отчёте.
|
||||
|
||||
**Решение основной сессии:** правило не менять, оно записано до метки. Если `worker_crash` появится в основной метке, отчёт называет такую настройку отдельно и не рекомендует её, не перекрашивая вердикт правила. В `baseline2`, `baseline3` и `baseline4` таких случаев нет (`worker_die_other` 0); у `baseline` этого столбца нет.
|
||||
@@ -1,37 +1,845 @@
|
||||
# Отчёт — лабораторная 5
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
|
||||
- Целевая оценка; выбранный трек 5: оценка 5, трек 1 «Очередь под перегрузкой»
|
||||
- Состояние отчёта: закрыты **уровень 3** (change `async-attachments`) и **уровень 4** (change `pipeline-reliability`); уровень 5, трек 1 — change `track1-queue-overload`, раздел «Очередь под перегрузкой». Все доказательства исключений сверки покрытия сняты на стенде этой лабы
|
||||
- Ветка решения: `solution/bvt2301-safronov`, в неё по очереди вливаются `feat/async-attachments`, `feat/pipeline-reliability`, `feat/unit-of-work`, `feat/track1-queue-overload`
|
||||
- Commit: трек 1 — код `d68a016`, метка `b104690` (раздел «Очередь под перегрузкой»); уровни 3 и 4 — `d8fe2e8` (ветка `feat/unit-of-work`, перенос на единицу работы и правки verify); снятое на `9639aa1`, `6ba74b1`, `399da05`, `e2a6427` и `ff1a83b` названо в разделе доказательств
|
||||
- PR: по шаблону `.github/pull_request_template.md`, заголовок `ЛР 5 — БВТ2301 — Сафронов — на 5`; номер — после публикации
|
||||
- Согласования с преподавателем: три договорённости лаб 1–4 действуют, новых в лабе 5 нет (раздел «Согласования с преподавателем»). Открытые вопросы преподавателю — 12, раздел «Открытые вопросы преподавателю»; решения без пользователя — `QUESTIONS.md`
|
||||
- Источники, библиотеки и помощь ИИ — последний раздел
|
||||
|
||||
## Запуск из чистого clone
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
**Версии.** Образ API: `python:3.12.14-slim-trixie`, uv 0.12.17. LB: `haproxy:3.4.6-trixie`. PostgreSQL: `postgres:18.6-trixie`. Valkey: `valkey/valkey:9.1.2-trixie`. S3: `chrislusf/seaweedfs:4.48`. Брокер: `rabbitmq:4.3.7`. Все закреплены тегом и digest в `Dockerfile` и `docker-compose.yml`. Приложение: Python 3.12, FastAPI, aio-pika 10.2.1 (aiormq 7.2.4), Pillow 13.0.0, aiobotocore; остальное строго по `uv.lock`. Проверено на Docker 29.9.2, Compose 5.6.1, macOS на Apple M3 Pro.
|
||||
|
||||
**Нужно на машине:** Docker с BuildKit и Compose v2, `make`, `openssl`, `curl`, `python3` 3.9+ (публичные проверки и драйвер скилла), uv (`make validate`, `make student_test`, `make test_isolated`, `make failure_checks`, `make bench*`, `make run_dev`). Свободные порты `127.0.0.1`: 8080 (LB), 5433 (PostgreSQL), 6380 (Valkey), 8334 (S3), 5673 (AMQP), 18088 (`make test_isolated`).
|
||||
|
||||
**Действий оператора нет.** `make env_setup` создаёт `.env` и `config.toml` из шаблонов, подставляет случайные пароли и ключи и печатает только имена. В существующий `.env` он дописывает недостающие переменные (секреты брокера и ключи worker при переходе с лабы 4), прежние строки не меняет. Пароль брокера, как и пароль PostgreSQL, задаётся при первом создании volume.
|
||||
|
||||
### Способ 1: всё в compose — `make run_docker`
|
||||
|
||||
```sh
|
||||
git clone <fork> && cd <каталог clone> && git checkout solution/bvt2301-safronov
|
||||
make run_docker # env_setup + build + up -d: postgres, valkey, s3, rabbitmq → migrate, s3-bootstrap → api × 2, relay, worker, cleaner → haproxy
|
||||
make replicas # дождаться healthy реплик; готовность стенда — haproxy (healthy) и /health/ready через LB
|
||||
make check
|
||||
uv sync && make validate PYTHON=.venv/bin/python
|
||||
make test # публичный smoke: 202, опрос до ready, оригинал и настоящий JPEG thumbnail
|
||||
make instances # ≥2 X-Instance-Id одной сессии через LB
|
||||
make s3_check # приватность bucket: права ключей API, уборщика и worker
|
||||
make student_test
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && make replicas
|
||||
python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 defense-scenario
|
||||
python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 defense-faults # шаг 4 защиты, ~2–4 мин
|
||||
make replay # реестр failed, только показ; APPLY=1 ATTACHMENT=<id> — вернуть в работу
|
||||
make failure_checks # отдельный стенд <проект>-failures, ~40 мин; рабочий стенд не трогается
|
||||
```
|
||||
|
||||
Миграции применяет одноразовый сервис `migrate`, bucket и пользователей S3 — `s3-bootstrap`; реплики, relay, уборщик и worker их ждут. Очередь объявляют relay и worker при подключении: отдельного bootstrap брокера нет, реплики API к брокеру не обращаются.
|
||||
|
||||
### Способ 2: сервис на хосте — `make run_dev`, `make run_worker`, `make run_relay`
|
||||
|
||||
```sh
|
||||
make run_dev # терминал 1: Postgres и миграции с хоста, Valkey, S3 с bootstrap, брокер в compose; API на 127.0.0.1:8080 с reload
|
||||
make run_worker # терминал 2: worker на хосте; ключи worker — из .env в окружение процесса, значения не печатаются
|
||||
make run_relay # терминал 3: relay на хосте; без него задания ждут в PostgreSQL
|
||||
curl -s http://127.0.0.1:8080/health/ready
|
||||
make test
|
||||
EXPECT_REPLICAS=1 make student_test
|
||||
```
|
||||
|
||||
Ожидание готовности — `/health/ready` отвечает 200. Остановка процессов — Ctrl+C.
|
||||
|
||||
Вариант README без make: `make env_setup`, `docker compose --env-file .env config --quiet`, `docker compose --env-file .env up -d --build`.
|
||||
|
||||
### Остановка и удаление данных
|
||||
|
||||
- `make stop` — остановить контейнеры; `make down` — удалить контейнеры. Volumes `postgres_data`, `s3_data`, `rabbitmq_data` остаются.
|
||||
- `make wipe_data` — намеренное удаление учебных данных и volumes (спрашивает `yes`).
|
||||
|
||||
## Архитектура и решения
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
```text
|
||||
клиент → HAProxy (127.0.0.1:8080) → api × 2 ──┬─ PostgreSQL (источник истины: метаданные, задания = outbox, варианты)
|
||||
├─ Valkey (кэш карточек чатов)
|
||||
└─ S3: <база>/staging/<id>/original
|
||||
relay → PostgreSQL: state = 'queued' AND published_at IS NULL, срок наступил; истёкшие аренды
|
||||
→ RabbitMQ: durable-очередь <база>.attachment.process.v1, publisher confirm, затем отметка published_at
|
||||
│ job_id, attachment_id, pipeline_version, attempt…
|
||||
▼
|
||||
worker → PostgreSQL: claim с арендой и номером попытки → render: отдельный процесс на задание, лимиты, без секретов
|
||||
→ S3: <база>/attachments/<id>/original, …/v1-thumbnail, v1-crop, v1-optimized
|
||||
→ PostgreSQL: ready или failed с fencing, затем ack
|
||||
cleaner → PostgreSQL + S3 (pending, staging у ready и по сроку у failed, сверка bucket и БД)
|
||||
make replay → relay replay: реестр failed и возврат работы с аудитом
|
||||
```
|
||||
|
||||
**Перенесено из лаб 2–4 без изменения поведения** (подробности — `REPORT.md` репозитория `mtusi2026lab4-safronov`): вход Basic → Bearer-сессия в PostgreSQL, пароль — Argon2id (`RFC_9106_LOW_MEMORY`: t=3, m=64 MiB, p=4), SHA-256 токена в БД; кэш карточек; реплики без состояния за HAProxy, идемпотентность сообщений, `make rolling_update`; приватный S3 с тремя пользователями, места загрузки, уборщик и сверка.
|
||||
|
||||
**Изменено на уровне 3** (design change `async-attachments`):
|
||||
|
||||
- `POST …/attachments` — 202 со снимком `queued`;
|
||||
- worker: claim задания под `FOR UPDATE`, чтение staging и сверка размера и SHA-256 со строкой, PUT оригинала в конечный ключ, варианты, фиксация `ready` вместе с вариантами и заданием одной транзакцией, ack;
|
||||
- состояния `queued`, `processing`, `ready`, `failed` в API; `pending` наружу не виден (404);
|
||||
- скачивание не готового вложения — 409, отсутствующий вариант готового — 404; `failed` в сообщении — 409, а повтор отправленного сообщения с тем же ключом — тот же 201;
|
||||
- схема только расширена: `attachment_jobs`, `attachment_variants`, `attachments.staging_key` и `error_code`, более широкий CHECK статуса (`NOT VALID`).
|
||||
|
||||
**Изменено на уровне 4** (design change `pipeline-reliability`):
|
||||
|
||||
- порядок приёма: строка `pending` с ключами → PUT в staging → `queued` с заданием одной транзакцией → 202. Брокера в пути запроса нет, у реплик ни клиента, ни пароля;
|
||||
- outbox — те же строки `attachment_jobs` (`state = 'queued' AND published_at IS NULL`); relay публикует с подтверждением под `FOR UPDATE SKIP LOCKED`, отмечает только подтверждённые, возвращает истёкшие аренды и потерянные сообщения;
|
||||
- сообщение — подсказка, истина в строке задания: дубль при живой аренде и сообщение раньше срока подтверждаются без эффекта; аренда `job_timeout + lease_margin` без пульса, номер попытки — fencing;
|
||||
- варианты `crop` и `optimized`; декодирует только отдельный процесс на задание с лимитами;
|
||||
- backoff с jitter, постоянные и временные ошибки, реестр `failed` в PostgreSQL и `make replay` с аудитом (`attachment_job_replays`, `attempt_base`);
|
||||
- `prefetch` отдельно от `concurrency`; очистка staging уборщиком, класс сверки `orphan_staging`;
|
||||
- схема только расширена: ревизии `c7e2f1a04b56` и `d3f9a6b2c1e7`.
|
||||
|
||||
**Единица работы** (design change `unit-of-work`, Cosmic Python, главы 2 и 6). С PostgreSQL сервисы всех процессов работают только через абстракции `src/core/ports/`: `AbstractUnitOfWork` и абстрактные repo; реализации на SQLAlchemy выбирают точки входа (`src/api/dependencies.py`, `src/worker/main.py`, `src/relay/main.py`, `src/cleaner/main.py`). Остальные зависимости конкретные и названы: `Cache`, `ObjectStorage`, `JobPublisher`, `ImageRenderer` сервис импортирует как типы и получает конструктором (сигнатуры фейков сверяет тест, `design.md`, решение 8), а `src.infra.password` и логгер вызывает прямо из модуля (уточнение 20). Граница транзакции одна и видна в сервисе: `async with self.uow:` — один блок, одна транзакция; явный `await self.uow.commit()`, выход без него — откат. Вложенный блок и repo вне блока или после фиксации — ошибка, в том числе на фейке. Доменной модели, агрегатов и message bus нет: логика и так в сервисах, а границы транзакций заданы контрактом. Кэш Valkey и S3 в единицу работы не входят: фиксация и откат на них не действуют. Соединение занято на шаг: JSON-ручка получает его на вход и на операцию отдельно, а на хэш пароля, между шагами и на передачу ответа оно в пуле. `[database] request_timeout_seconds` — срок блока вместе с откатом при выходе; на JSON-ручках та же настройка ещё и общий срок запроса (`request_deadline`), иначе два шага дали бы до 12 с при `timeout server` 10 с, а очередь хэшей шла бы без срока. Поведение API, контракт, схема и настройки те же.
|
||||
|
||||
Схема слоёв и поток отправки сообщения (каждая связь сверена с импортами и вызовами кода; поиском по связям помогал граф кода `graphify`, он только подсказка: схема написана руками):
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph entry["Точки сборки"]
|
||||
deps["src/api/dependencies.py"]
|
||||
procs["src/worker, src/relay, src/cleaner (main.py)"]
|
||||
end
|
||||
subgraph api["API"]
|
||||
routers["src/api/routers/v1/*"]
|
||||
end
|
||||
subgraph core["Домен"]
|
||||
services["src/core/services/*"]
|
||||
ports["src/core/ports/*: AbstractUnitOfWork, Abstract*Repository"]
|
||||
clientrepos["src/core/repos: chat_cache, attachment_object"]
|
||||
end
|
||||
subgraph infra["Реализации"]
|
||||
uow["src/infra/db/uow.py: SqlAlchemyUnitOfWork"]
|
||||
scope["src/infra/db/scope.py: session_scope, deadline_scope"]
|
||||
sqlrepos["src/core/repos/*: SqlAlchemy*Repository"]
|
||||
clients["src/infra: Cache, ObjectStorage, JobPublisher, ImageRenderer"]
|
||||
password["src/infra/password.py"]
|
||||
end
|
||||
pg[("PostgreSQL")]
|
||||
routers --> deps
|
||||
deps --> services
|
||||
procs --> services
|
||||
deps --> uow
|
||||
procs --> uow
|
||||
deps --> scope
|
||||
services --> ports
|
||||
services --> clientrepos
|
||||
services -- "тип клиента, вызовы издателя и процесса обработки" --> clients
|
||||
services -- "хэш пароля" --> password
|
||||
clientrepos --> clients
|
||||
uow -. реализует .-> ports
|
||||
sqlrepos -. реализует .-> ports
|
||||
uow --> scope
|
||||
uow --> sqlrepos
|
||||
sqlrepos --> pg
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant R as message router
|
||||
participant D as request_deadline, get_current_session
|
||||
participant S as MessageService.send_message
|
||||
participant U as SqlAlchemyUnitOfWork
|
||||
participant P as PostgreSQL
|
||||
participant C as chat_cache
|
||||
D->>U: блок входа: sessions.get_current_session
|
||||
U->>P: проверка соединения, SELECT, ROLLBACK
|
||||
R->>S: chat_id, sender_id, text, idempotency_key
|
||||
S->>U: async with self.uow
|
||||
S->>C: require_member: карточка из кэша
|
||||
C-->>S: промах
|
||||
S->>U: chats.get_chat
|
||||
S->>U: attachments.get_attachments, если есть вложения
|
||||
S->>U: idempotency.claim_key
|
||||
S->>U: messages.insert_message, связи
|
||||
S->>U: commit
|
||||
U->>P: проверка соединения, BEGIN, выражения, COMMIT
|
||||
S-->>R: MessageFullDTO
|
||||
```
|
||||
|
||||
Быстрые тесты сервисов — каталог `service-tests/` вне образа и вне `student-tests/`: `make service_test` гоняет ветки всех сервисов на фейках без хранилищ и docker, `make service_test_db` на временной базе проверяет настоящую единицу работы, общий срок запроса и тот же набор условий repo, что и на фейке (`service-tests/repo_contract.py`). Блокировки и поведение под конкуренцией фейк не воспроизводит: это по-прежнему `make failure_checks`.
|
||||
|
||||
Цена шага — вторая выдача соединения на двухшаговой ручке, новых соединений нет. Её снижает проверка соединения при выдаче одним запросом `;` вместо трёх (`_ping_once`, опирается на внутренние имена адаптера, смену имён ловит `make service_test_db`). Осталось то, что в таблицах ниже: цену приняли, готовые меры (чтение без транзакции, соединение Core вместо сессии) не применялись (`design.md`, решение 7).
|
||||
|
||||
Обмены с PostgreSQL на запрос (журнал `log_statement = all`, проба до кода, `design.md`, Context; на commit не переснимались: выражения те же):
|
||||
|
||||
| Ручка | До | На шаг без меры | С мерой (`_ping_once`) |
|
||||
|---|---|---|---|
|
||||
| `GET /users/me` | 6 | 6 | 4 |
|
||||
| `GET …/messages` | 7 | 12 | 8 |
|
||||
| `POST …/messages` | 8 | 13 | 9 |
|
||||
|
||||
Потолок и CPU реплики до и после, закрытая модель, 1 реплика 1 CPU, один повтор на ячейку: `caffeinate -isu uv run python bench/run.py --profile quick --label unit-of-work-before` и `unit-of-work-aa` на `b2fb88f` (`src` как на `9efab79`, временный `git worktree`), `--label unit-of-work-after` на `6ba74b1`; `make bench_compare BEFORE=unit-of-work-before AFTER=unit-of-work-after AA=unit-of-work-aa` и `make bench_compare BEFORE=unit-of-work-aa AFTER=unit-of-work-after AA=unit-of-work-before`. Метки — `evidence/bench/unit-of-work-*/`, сравнения — `evidence/compare/unit-of-work-before__unit-of-work-after.md` и `evidence/compare/unit-of-work-aa__unit-of-work-after.md`. Метки сняты до правок verify (`BoundedCloseConnection`, таймер блока при общем сроке): на пути без отказа те правки убирают один таймер блока и не добавляют обменов; метки не переснимались. У всех трёх `git.dirty` false, `host_warnings` пусты, `swapouts_delta` 0; посторонние контейнеры на хосте — `domains-api-1`, `domains-bot-1`, `domains-postgres-1` (названы в паспортах). Первая съёмка `unit-of-work-before` дала предупреждение о выгрузке 27708 страниц в swap и переснята (`bench.md`): порядок меток — aa, after, rollout, затем before, в той же сессии хоста; отброшенная метка в git не идёт.
|
||||
|
||||
Порядок съёмки: `aa` 20:19, `after` 20:23, затем rollout, `before` 20:32 UTC. Код `aa` и `before` один, поэтому обе метки — «до», и каждая служит уровнем шума для другой (`bench_compare` считает шум от своего «до»: одна пара меток даёт 14,8 и 17,4 %, 34,8 и 53,4 %).
|
||||
|
||||
| Сценарий | «До» | Шум A/A, наибольшее Δ RPS | Δ RPS по 9 ячейкам: медиана (мин…макс) | Ячеек ниже «до» | Вывод `bench_compare` | p50 при 1 клиенте, мс (1k, 5k, 10k) |
|
||||
|---|---|---|---|---|---|---|
|
||||
| история | `aa`, сразу перед `after` | 17,4 % (5k × 1) | −14,1 % (−21,1…−6,3) | 9 из 9 | эффект — 1k × 1 (−21,1 %) и 5k × 1 (−17,5 %), остальные в пределах шума | 1,78 → 2,22; 1,79 → 2,16; 1,83 → 2,22 |
|
||||
| история | `before`, после rollout | 14,8 % (5k × 1) | −6,6 % (−18,8…−3,2) | 9 из 9 | эффект — 1k × 1 (−16,2 %) и 1k × 16 (−18,8 %), остальные в пределах шума | 1,86 → 2,22; 1,95 → 2,16; 1,85 → 2,22 |
|
||||
| отправка | `aa`, сразу перед `after` | 53,4 % (5k × 16) | −12,6 % (−18,7…−2,1) | 9 из 9 | всё в пределах шума | 2,01 → 2,40; 2,06 → 2,33; 2,06 → 2,41 |
|
||||
| отправка | `before`, после rollout | 34,8 % (5k × 16) | −4,3 % (−23,5…+37,5) | 7 из 9 | в пределах шума, кроме 5k × 16: +37,5 % — выброс ячейки «до» | 2,05 → 2,40; 2,07 → 2,33; 1,89 → 2,41 |
|
||||
|
||||
Шум отправки задан одним выбросом: 5k × 16 в `before` — 383 RPS при 588 в `aa`. Без этой ячейки наибольшее расхождение A/A — 14,2 % (10k × 1, 433 и 495 RPS; считано не командой, а по `evidence/bench/unit-of-work-{aa,before}/runs.csv`), и −23,5 % той же ячейки от `before` выходит за него; от `aa` она даёт −12,6 %.
|
||||
|
||||
CPU реплики на запрос от `aa`: выше в 18 ячейках из 18, история +116…+266 мкс, отправка +26…+332 мкс. От `before`: выше в 15 из 18, исключения — 5k × 1 истории (−99), 5k × 1 и 5k × 16 отправки (−3 и −681, та же ячейка-выброс). p95 и все ячейки — в `evidence/compare/`.
|
||||
|
||||
**Что показывают данные.** Соединение на шаг снижает потолок реплики на этой закрытой модели: от метки того же кода, снятой прямо перед `after`, ниже все 18 ячеек, медианы −14,1 % на истории и −12,6 % на отправке, и в тех же 18 ячейках выше CPU реплики на запрос. От метки, снятой позже, медианы −6,6 и −4,3 %, ниже 16 ячеек из 18.
|
||||
|
||||
**Чего данные не показывают.** Точной величины: на ячейку один повтор, две метки одного кода расходятся до 14–17 % даже без выброса, а по правилу `bench_compare` эффектом названы только 2 ячейки истории из 9 в каждом сравнении. Ячейки одной метки сняты подряд и независимыми не считаются: 18 из 18 говорит об устойчивости знака, а не о размере. `before` ниже `aa` в 13 ячейках из 18 при том же коде; если хост за эти 13 минут замедлялся, ближнее сравнение цену завышает, а дальнее занижает, и данные этого не различают. Поэтому цена — снижение потолка примерно от 4–7 до 13–14 % по медианам, а не одно число.
|
||||
|
||||
**С оценкой `design.md`** (потолок −1…−22 %, p50 при 150/с +0,2…0,5 мс) цена не расходится: от `aa` все 18 ячеек внутри (−2,1…−21,1 %), от `before` вне её три ячейки: +0,4 %, +37,5 % и −23,5 %. p50 здесь при 1 клиенте закрытой модели, а не при 150/с, прирост +0,21…+0,52 мс.
|
||||
|
||||
CPU на успешный запрос при постоянных 200 запросах в секунду (100 записей, 100 чтений; две реплики разных версий в одном прогоне): `bench/run.py --profile rollout --from b2fb88f --label unit-of-work-previous` на `6ba74b1`, `evidence/rollout/unit-of-work-previous/summary.md`, `git.dirty` false, `host_warnings` пусты:
|
||||
|
||||
| Компонент | До замены, мкс | После замены, мкс |
|
||||
|---|---|---|
|
||||
| API всего | 3066 | 3398 |
|
||||
| PostgreSQL | 478 | 560 |
|
||||
|
||||
Уровень шума — два прогона замены на один и тот же новый код: `evidence/rollout/unit-of-work/summary.md` даёт после замены API 3113 мкс и PostgreSQL 524 мкс, этот прогон — 3398 и 560. Расхождение одного кода (отношение чисел двух `summary.md`, считано вручную): API 285 мкс, 9,2 %; PostgreSQL 36 мкс, 6,9 %. Рост в прогоне выше: API на 332 мкс, 10,8 %, — того же порядка, поэтому отличить его от шума нельзя; PostgreSQL на 82 мкс, 17,2 %, — вдвое больше расхождения, но пара прогонов одна, и этого мало для вывода. Значения «до» двух прогонов для шума не годятся: там разный прежний код.
|
||||
|
||||
Замена с `b2fb88f` на `6ba74b1`: 10,2 с, ошибок 0 / 0 / 0, 12001 сообщение = 12001 ключ. Удержание соединения на запрос по пробе `design.md` (Context) ниже на 20–36 %; на commit отдельно не измерялось.
|
||||
|
||||
**Транзакционные границы.** Ключ эффекта — первичный ключ `attachment_variants (attachment_id, pipeline_version, variant)`, логическая работа — `UNIQUE (attachment_id, pipeline_version)` в `attachment_jobs`. Вызовов S3 и брокера внутри блоков единицы работы нет, кроме двух осознанных исключений с коротким сроком: публикация relay (2 с < срока блока 6 с < простоя транзакции 10 с: блокировка строки и есть признак «публикует другой relay») и DELETE уборщика под блокировкой строки. Намеренные особенности перенесены без изменения порядка: уборка зависшей загрузки — два блока (пометка, затем объект и строка), вход закрывает блок чтения до KDF, занятый ключ идемпотентности снимает блокировку фиксацией до ответа, а компенсация загрузки различает сбой выражения и сбой на самой фиксации флагом перед явным `commit()`: автокоммит при выходе этого бы не дал (`design.md`, решение 10).
|
||||
|
||||
### Варианты и лимиты обработки
|
||||
|
||||
| Вариант | Формат | Размер | Параметры | Метаданные |
|
||||
|---|---|---|---|---|
|
||||
| `thumbnail` | JPEG | вписан в 256 × 256, вниз, без увеличения | `quality=85` | EXIF и ICC не пишутся |
|
||||
| `crop` | JPEG | 128 × 128, центр, маленькие растягиваются | `quality=85`, альфа на белый | то же |
|
||||
| `optimized` | WebP | вписан в 1280 × 1280, без увеличения | `quality=80`, `method=4` (`method=6` на пробе в 3,5 раза дольше без выигрыша) | EXIF, XMP, ICC нет; ориентация применена; прозрачность сохранена |
|
||||
|
||||
Все три — из одного декодирования, результат детерминирован (design, таблица «Пробы»). Pillow нет ни в репликах, ни в процессе 1 worker (`evidence/worker/process.md`).
|
||||
|
||||
| Лимит | Механизм | Значение | Превышение |
|
||||
|---|---|---|---|
|
||||
| байты | размер объекта против строки до чтения тела; CHECK контракта | 10 MiB | `source_corrupted`, `processing_failed`, постоянная |
|
||||
| пиксели | `width × height` до декодирования | 40 млн | `limit_pixels`, `invalid_image`, постоянная |
|
||||
| память | `RLIMIT_AS` процесса обработки | 450 МиБ | `limit_memory`, `invalid_image`, постоянная |
|
||||
| CPU | `RLIMIT_CPU`, `RLIMIT_CORE` = 0 | 15 с | `limit_cpu`, `invalid_image`, постоянная |
|
||||
| время | родитель убивает процесс | 40 с, меньше срока попытки 60 с | `timeout`, временная |
|
||||
|
||||
Настоящий случай «дорогого» файла — прогрессивный JPEG в пределах контракта, один скан повторён 445 227 раз: `test_limit_cpu_scan_bomb`.
|
||||
|
||||
**Бюджет памяти контейнера worker (1 ГБ).** Замер двух файлов разом, команда `driver.py --port 8080 worker-memory`, два прогона на `9639aa1` (`evidence/worker/memory.md`): пик процесса обработки на 40 Мпкс (`render_peak_kib`, лимит 450 МиБ) зависит от типа файла: PNG RGBA и всё, что переводится в RGBA (серый с альфой, RGB с tRNS, палитра с tRNS), — 357 МиБ, серый 16 бит — 404 МиБ, а на обеих границах контракта сразу, 40 Мпкс и ~10 MiB файла, — 367 и 414 МиБ. `VmHWM` процесса 1 при двух телах ~10 MiB — до 159 МиБ. Самый дорогой случай, два серых 16 бит на обеих границах: `memory.peak` контейнера 926 и 705 МиБ в двух прогонах (пик зависит от совпадения пиков двух процессов), `oom_kill` 0; у двух PNG 10 MiB из шума — 262 МиБ. Опора — верхняя оценка суммой пиков: 159 + 2 × 414 = 987 МиБ < 1 ГБ. Если памяти всё же не хватит, ядро убьёт самый большой процесс обработки, а не worker (проба), это временная ошибка.
|
||||
|
||||
### Сервисы стенда и лимиты
|
||||
|
||||
| Сервис | Роль | CPU | Память | Порт на хосте |
|
||||
|---|---|---|---|---|
|
||||
| `haproxy` | LB, единственная публичная точка | 1 | 256 МБ | `127.0.0.1:8080` |
|
||||
| `api` × 2 | приём, без состояния | 1 на реплику | 512 МБ на реплику | нет |
|
||||
| `relay` | публикация намерений, истёкшие аренды, `python -m src.relay`, без healthcheck | 0,25 | 256 МБ | нет |
|
||||
| `worker` | обработка, `python -m src.worker`, без healthcheck | 1 | 1 ГБ | нет |
|
||||
| `cleaner` | незавершённые загрузки, очистка staging, сверка | 0,25 | 256 МБ | нет |
|
||||
| `postgres` | источник истины, volume | 2 | 1 ГБ | loopback 5433 |
|
||||
| `valkey` | кэш, без persistence | 0,5 | 128 МБ | loopback 6380 |
|
||||
| `s3` | SeaweedFS, volume | 1 | 512 МБ | loopback 8334 |
|
||||
| `rabbitmq` | брокер, volume, предел памяти 400 МиБ | 1 | 512 МБ | loopback 5673 |
|
||||
| `migrate` (разовый) | миграции | 0,5 | 256 МБ | нет |
|
||||
| `s3-bootstrap` (разовый) | bucket, политики, пользователи | 0,5 | 128 МБ | нет |
|
||||
|
||||
**Сумма постоянных сервисов:** 9,0 CPU, 4992 МБ при двух репликах; вместе с разовыми — 10,0 CPU, 5376 МБ.
|
||||
|
||||
**Соединения PostgreSQL:** `API_REPLICAS × 10 + migrate 1 + cleaner 1 + worker 2 + relay 1`. При двух репликах 25; во время поочерёдной замены (третья реплика) 35; `max_connections` 100. Переполнения пула нет (`max_overflow` 0).
|
||||
|
||||
**Лимит worker 1 ГБ:** расчёт — раздел «Варианты и лимиты обработки», проверяет `test_max_pixels_fit_worker_memory`. На метке `baseline4` при конкуренции 2 `memory.peak` до 836 МиБ на самом дорогом классе; конкуренция 4 в этот лимит на нём не помещается (раздел «Очередь под перегрузкой»).
|
||||
|
||||
**Предел принятой работы:** `[uploads] max_unfinished_jobs` 250 незавершённых заданий на стенд, 0 — без предела. Обоснование по измеренному потолку — там же.
|
||||
|
||||
### Соответствие переменных `.env.example`
|
||||
|
||||
Имена лаб 1–4 — без изменений, таблицы в отчёте лабы 4 («Соответствие переменных», «Соответствие имён skeleton `S3_*`»). Новые имена лабы 5:
|
||||
|
||||
| Имя skeleton | Где у нас | Почему так |
|
||||
|---|---|---|
|
||||
| `BROKER_URL_FILE` | `[broker]` мостами из `RABBITMQ_*` (`BROKER__HOST`, `BROKER__PORT`, `BROKER__USER`, `BROKER__PASSWORD`) | значения, а не файл, как `DATABASE_URL_FILE`: пароль нужен и контейнеру брокера, строка URL с паролем не собирается |
|
||||
| `WORKER_CONCURRENCY` | `[worker] concurrency` (2) | читает только worker |
|
||||
| `JOB_MAX_ATTEMPTS` | `[worker] max_attempts` (5) | то же |
|
||||
| `JOB_TIMEOUT_SECONDS` | `[worker] job_timeout_seconds` (60) | то же |
|
||||
| `STAGING_RETENTION_SECONDS` | `[cleaner] staging_retention_seconds` (86400) | читает только уборщик; значение из `.env.example` skeleton |
|
||||
|
||||
Новые настройки уровня 4 (значения по умолчанию, вывод записи о старте — `evidence/worker/process.md`, `evidence/relay/process.md`):
|
||||
|
||||
- `[worker]`: `prefetch` 2, `lease_margin_seconds` 10, `retry_base_delay_seconds` 5, `retry_max_delay_seconds` 300, `render_timeout_seconds` 40, `render_cpu_limit_seconds` 15, `render_memory_limit_mib` 450, `graceful_shutdown_seconds` 8 (не больше 8);
|
||||
- `[relay]`: `poll_interval_seconds` 0,25, `batch_size` 100, `max_published_backlog` 1000 (0 — без предела), `republish_after_seconds` 300, `failure_pause_seconds` 2.
|
||||
|
||||
Секреты по сервисам: пароль брокера — только `rabbitmq`, `relay`, `worker`, у `api` настроек брокера нет; ключи `S3_WORKER_*` — только `s3-bootstrap` и `worker`; у worker нет пароля Valkey и ключей API и уборщика; у relay нет S3 и Valkey; в окружении процесса обработки секретов нет.
|
||||
|
||||
### Критичные и некритичные зависимости `/health/ready`
|
||||
|
||||
| Зависимость | В готовности | Причина и поведение при отказе |
|
||||
|---|---|---|
|
||||
| PostgreSQL | да | без него не работают сессии и данные: обязательный путь стоит, 503 |
|
||||
| Valkey | нет | кэш: отказ — обход, чтение из PostgreSQL |
|
||||
| S3 | нет | нужен только путям байтов вложений: они отвечают 503, текст и история работают |
|
||||
| Брокер | нет | брокера в пути запроса нет: загрузка отвечает 202, намерение ждёт в PostgreSQL |
|
||||
| Relay | нет | без него задания ждут в PostgreSQL, приём не страдает |
|
||||
| Worker | нет | к синхронному пути не относится |
|
||||
|
||||
**Отказ брокера.** Загрузка — **202, а не 503** (на уровне 3 было 503): намерение уже в PostgreSQL, relay пишет «Broker is unavailable» и опубликует после возврата; 503 на загрузке теперь только от S3 и PostgreSQL. Проверки: `test_upload_with_broker_stopped`, `test_upload_with_broker_paused`. **Отказ relay.** Загрузка — 202, задание `queued` с пустой отметкой, следующий запуск публикует (`test_relay_killed_before_publish`). **Отказ worker.** API принимает, relay публикует; resize синхронно не делается: Pillow в процессе API не загружен (`_imaging` нет в `/proc/1/maps`, `evidence/worker/process.md`).
|
||||
|
||||
### Разрыв COMMIT и publish и окна отказа
|
||||
|
||||
Разрыв закрыт transactional outbox на тех же строках: намерение и `queued` — одна транзакция, публикует отдельный relay по этим строкам, а не процесс запроса. Отдельной таблицы нет: это было бы второе состояние той же работы. LISTEN/NOTIFY отвергнут: опрос всё равно нужен для сроков, а пустая выборка стоит 0,05 мс.
|
||||
|
||||
| Окно | Что происходит | Что видит клиент |
|
||||
|---|---|---|
|
||||
| после staging до записи задания | `pending` и объект staging; их убирает уборщик | 503 или обрыв |
|
||||
| после COMMIT `queued` до ответа | работа идёт: relay опубликует | обрыв; вложение станет `ready`, клиент о нём не знает, как и в лабе 4 |
|
||||
| после COMMIT до publish (relay упал) | намерение в БД, следующий проход публикует | 202 уже получен |
|
||||
| после publish до confirm | исход неизвестен: новая публикация, возможен дубль | опрос `queued` |
|
||||
| после confirm до отметки `published_at` | откат отметки, новая публикация, дубль — no-op | опрос `queued` или `processing` |
|
||||
| после записи S3 до COMMIT результата | аренда истекает, новая попытка пишет те же ключи | опрос `processing`, затем `queued` |
|
||||
| после COMMIT результата до ack | повторная доставка — no-op с ack | опрос `ready` |
|
||||
|
||||
Сбои внедрены снаружи, без точек сбоя в коде (триггер на `filename` прогона, `docker kill`): `driver.py defense-faults` на рабочем стенде → `evidence/attachments/defense-faults.md`, те же окна — `test_defense_faults`. Запись «Разрыв COMMIT и publish» из `KNOWN_ISSUES.md` удалена.
|
||||
|
||||
**Смесь версий и порядок обновления** (design, Migration Plan). Шага оператора нет: секретов не прибавилось. Без простоя: `docker compose up -d s3-bootstrap`, `make rolling_update` (две ревизии, затем реплики), `docker compose up -d --no-deps worker cleaner`, затем `docker compose up -d --no-deps relay`; до запуска relay загрузки отвечают 202 и ждут. Worker обновляется раньше relay: прежний worker делает только thumbnail. Откат: `make rolling_update COMMIT=<прежний> MIGRATE=0 COMPOSE_FILE=docker-compose.yml:infra/rollback/broker.compose.yml` (прежним репликам нужен пароль брокера, только на время отката), прежние worker и уборщик, relay останавливается, схема остаётся. Новых статусов и `error_code` нет, поэтому 500 на чтении, как при переходе 201 → 202, здесь нет; проба — `evidence/migrations/pipeline-reliability.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` |
|
||||
| 2026-10-20 | Лаба 4: «пустой текст» сообщения — это и `""`, и текст только из пробельных символов. Допустимы: вложение + непустой текст, без вложения + непустой текст, вложение + пустой текст. Значит, `" "` с хотя бы одним вложением — 201, без вложений — 400 | спек `messages` (change `attachments`, сценарий «Пробелы с вложением»), design `attachments`, решение 8; `.claude/rules/api-contract.md` |
|
||||
|
||||
Расхождения FastAPI, разрешённые согласованием: 422 переведён в 400; битый JSON — 400 раньше 401, остальная валидация — после зависимостей.
|
||||
|
||||
### Открытые вопросы преподавателю
|
||||
|
||||
Контракт допускает несколько трактовок, ответа пока нет. Взята самая строгая, проходящая публичные тесты. Подход от ответа не зависит. Вопросы 1 и 2 перенесены из лабы 4, полный разбор — в её отчёте.
|
||||
|
||||
1. **Все места загрузки реплики заняты: 429 или 503?** Сделано: 429 `rate_limited` с `Retry-After: 1`.
|
||||
2. **Что отвечает API на вложение, чей оригинал по сверке потерян?** Сделано: метаданные — 200, байты — 404, ссылка в новом сообщении — 201; до пометки сверкой байты — 500.
|
||||
3. **Failed-вложение прикреплять нельзя (409), а повтор с тем же `Idempotency-Key` обязан вернуть тот же 201.** Что отвечать на повтор сообщения, чьё вложение стало `failed` уже после отправки? Сделано: новое сообщение — 409, повтор с ключом — 201 с тем же `Message`. Другой ответ меняет одну ветку `send_message` и сценарий `idempotency`.
|
||||
4. **`contracts/attachment-states.md` требует документированный retention и cleanup неуспешных исходников без указания уровня, а `README.md` относит очистку к уровню 4.** Закрыт уровнем 4: `[cleaner] staging_retention_seconds` 86400 с, очистка у `ready` следующим проходом, у `failed` по сроку. На уровне 3 очистки не было.
|
||||
5. **Допустим ли на уровне 3 ответ 503 при недоступном брокере?** Закрыт уровнем 4: отказ брокера больше не даёт 503, на загрузке 503 только от S3 и PostgreSQL. На уровне 3 был 503: relay ещё не было.
|
||||
6. **Контракт требует EXIF orientation и alpha на белый только у thumbnail. Как с `crop` и `optimized`?** Сделано: ориентация применяется у обоих (иначе EXIF, удалённый из WebP, повернул бы изображение), `crop` компонуется на белый (JPEG), `optimized` сохраняет прозрачность. Другой ответ правит одну функцию и сценарий.
|
||||
7. **Контракт называет replay «явным операторским», но не говорит, как его вызывать.** Достаточно ли команды в контейнере? Сделано: `make replay`, HTTP-ручки нет: в API нет роли оператора. Другой ответ добавляет ручку поверх той же транзакции.
|
||||
8. **Изображение, не уложившееся в лимиты времени или памяти обработки, — это `invalid_image` или отдельный код?** Сделано: `invalid_image`, точная причина — в записи для оператора. Другой ответ добавляет значение enum и требует обновить реплики раньше worker.
|
||||
9. **Контракт требует retention «неуспешных и непривязанных исходников», но молчит о конечных объектах, которые успела записать неудачная попытка.** Сделано: по истечении срока удаляются и они, метаданные `failed` остаются. Другой ответ убирает один шаг очистки.
|
||||
10. **Предел незавершённых заданий: 429 или 503?** Контракт называет 429 «ограничением частоты запросов», здесь ограничено количество принятой работы; 503 — «зависимость недоступна». Сделано: 429 `rate_limited` с `Retry-After: 5`, как у занятых мест: зависимости живы, реплика готова. Другой ответ меняет строку `DOMAIN_ERRORS` и сценарии.
|
||||
11. **Как долго загрузка обязана отвечать 202 при остановленном worker?** Рубрика уровня 3 показывает «worker остановлен → upload 202», трек 1 требует ограничить принятую работу. Сделано: пока незавершённых меньше предела (250); дальше 429, а текст, история, метаданные, готовые байты и `/health/ready` работают. Другой ответ — значение настройки.
|
||||
12. **Требуется ли на уровне лабы закрыть чтение секретов worker процессом обработки?** Он идёт под тем же UID и может прочитать `/proc/1/environ` (раздел «Ограничения и следующие шаги»). Сделано: кодом не исправлено, в окружении самого процесса обработки секретов нет. Предложение — `PR_SET_DUMPABLE=0` в процессе worker до запуска процессов обработки: одна строка на старте worker и сценарий.
|
||||
|
||||
### Ответы на вопросы защиты
|
||||
|
||||
**Чем publisher confirm отличается от consumer ack?** Confirm — брокер сообщает издателю, что принял сообщение на себя: durable-очередь, persistent-сообщение, записано. Это граница между relay и брокером: только после неё relay ставит отметку `published_at`, неподтверждённое остаётся намерением и публикуется снова. Ack — потребитель сообщает брокеру, что сообщение можно удалить. Worker шлёт его только после фиксации исхода в PostgreSQL (`ready`, `failed`, `queued` со сроком следующей попытки) или решения «эффекта не нужно». Это разные участки пути: confirm ничего не говорит об обработке, ack — о доставке. Ни тот, ни другой больше не определяют ответ клиенту: 202 — это COMMIT в PostgreSQL.
|
||||
|
||||
**Что именно уже сохранено в момент 202?** Проверенный оригинал целиком в staging приватного S3, строка вложения и намерение обработки в PostgreSQL (`queued`, `attempt` 0, одна транзакция). Сообщения в очереди может ещё не быть: его опубликует relay, и брокер в этот момент может быть недоступен. Вариантов и объекта в конечном ключе ещё нет. Проверка — `test_durable_state_at_202`, переживание — `test_api_killed_after_202`, `test_relay_killed_before_publish`, `test_broker_restart_keeps_job`, `test_broker_kill_keeps_confirmed`.
|
||||
|
||||
**Почему повторная доставка нормальна и где ключ идемпотентности job?** Подтверждение и результат работы нельзя зафиксировать атомарно: процесс может умереть между COMMIT и ack, relay — между confirm и отметкой, и сообщение придёт снова. Это at least once, а не exactly once. Эффект идемпотентен: ключ — `(attachment_id, pipeline_version, variant)`, первичный ключ `attachment_variants`, вставка `ON CONFLICT DO NOTHING`; ключи объектов одни и те же при каждом повторе, логическая работа — `UNIQUE (attachment_id, pipeline_version)`. Сообщение — подсказка, истина в строке: доставка готовой работы подтверждается без записи (`test_redelivery_of_ready_is_noop`, `test_crash_after_commit_before_ack`: `attempt` 1, тот же `updated_at`), `ready` не откатывается, replay готового — отказ `already_ready`.
|
||||
|
||||
**Как отличить зависший worker от долго работающего и не запустить два неконтролируемых дубля?** Только сроком: флаг `redelivered` этого не доказывает, брокер ставит его и после `nack`. Попытка жёстко ограничена: шаги прерывает `asyncio.timeout(job_timeout_seconds)`, процесс обработки убивается, поэтому аренда `job_timeout + lease_margin` (70 с) обходится без пульса. Истёкшая аренда значит «мёртв или заморожен», такую попытку возвращает relay. Пока аренда жива, дубль подтверждается без эффекта и без траты номера (`busy`, `test_duplicate_during_processing`), долгая живая попытка не теряет работу (`test_long_attempt_keeps_lease`). Новая попытка получает новый номер, и фиксация условна: `state = 'processing' AND attempt = :своя`. Размороженный прежний процесс получает `superseded` и ничего не меняет, в том числе пока новая попытка ещё идёт: тогда решает только номер (`test_hung_worker_lease_fencing`). Цена — после KILL следующая попытка ждёт аренду, до 70 с (наблюдали 70 с, `evidence/attachments/defense-faults.md`). Пульс отвергнут: запись на задание каждые несколько секунд, зависимость от event loop и ложные срабатывания под перегрузкой.
|
||||
|
||||
**Где работа перестаёт приниматься и ускоряться, и почему предел — 429?** Приниматься — на местах загрузки реплики и на пределе незавершённых заданий: оба уровня отвечают 429 с `Retry-After`. Ускоряться — на CPU worker: при 1 CPU конкуренция сверх двух не поднимает потолок, а на `lp` ломает обработку; у файлов на границе байтов ещё на CPU S3, общем для приёма и обработки. За входом клиент видит только дольше неизменный `queued`. 429, а не 503: зависимости живы, реплика готова и остаётся в LB, а текст, история, метаданные и готовые байты работают. Трактовка — вопрос 10 преподавателю. Числа — раздел «Очередь под перегрузкой».
|
||||
|
||||
### Сценарий защиты
|
||||
|
||||
Порядок автоматизирован: `driver.py --port 8080 defense-scenario` → `evidence/attachments/defense.md`, тот же порядок на стенде отказов — `test_defense_scenario`.
|
||||
|
||||
1. `make test`: 202, опрос до `ready`, оригинал и настоящий JPEG thumbnail.
|
||||
2. `docker compose stop worker`, загрузка — 202, снимок `queued`; сообщение с вложением — 201; скачивание — 409; текстовое сообщение — 201; в очереди ≥ 1 сообщение, потребителей 0.
|
||||
3. `scripts/restart.sh` — рестарт LB, реплик, PostgreSQL, Valkey, S3 и брокера с сохранением volumes; сообщение в очереди, прежний токен читает `queued`. `docker compose start worker` — та же запись `ready`; оригинал с тем же SHA-256, thumbnail 256 × 160, crop 128 × 128, optimized WebP 320 × 200. В файле — ID и `StartedAt` до и после, без токенов. Relay не трогается.
|
||||
4. `driver.py --port 8080 defense-faults` → `evidence/attachments/defense-faults.md`: шесть окон на рабочем стенде (таблица ниже). Триггеры — только на уникальный `filename` прогона, после прогона их нет, worker и relay запущены при любом исходе.
|
||||
|
||||
| Окно | Действие | Начато попыток | Итог |
|
||||
|---|---|---|---|
|
||||
| после записи объектов до COMMIT | `kill worker`, ожидание аренды | 2 | `ready` через 70 с, те же SHA-256 в S3 и метаданных |
|
||||
| после COMMIT до ack | заморозка и `kill worker`, сообщение вернулось | 1 | `ready`, no-op, тот же `updated_at`, очередь пуста |
|
||||
| после COMMIT `queued` до publish | `kill relay`, загрузка 202, 0 сообщений, запуск | 1 | `ready` без ручного задания |
|
||||
| после confirm до отметки | `kill relay`, сообщение есть, отметки нет, запуск — 2 сообщения | 1 | `ready`, дубль без эффекта |
|
||||
| replay `failed` | staging подменён, `failed` `source_corrupted`, реестр без изменений, объект возвращён, `--apply` | 2 | `ready`, то же задание, `attempt_base` 1, запись аудита |
|
||||
| replay готового | `--apply` на `ready` | 1 | код 3, `already_ready`, ничего не изменилось |
|
||||
|
||||
5. **Для 5 — выбранный эксперимент, трек 1:** `make bench_queue_quick` (~11 мин, рабочий стенд — `make stop`) на глазах или заранее и разбор `evidence/queue/baseline4/summary.md`: таблица настроек, плато предела, второй worker, рестарты.
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
В шапке каждого файла — команда, дата, commit и стенд. На `9639aa1` (код `src/` и `bench/` тот же, что на `5ee3257`, изменён только драйвер скилла: новые команды `worker-memory`, `freeze-sessions`, `freeze-lb`) сняты `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated.md`, `evidence/cache/hits.md`, `evidence/auth/passwords-and-tokens.md`, `evidence/idempotency/replay-after-restart.md`, `evidence/worker/memory.md`, `evidence/storage/freeze-sessions.md`. На `b104690` (коммит файла `4a7d89d`, шесть проверок предела заданий) снят `evidence/tests/failure-checks.md`. На `d8fe2e8` (правки verify: сессии после заморозки, один срок на JSON-запрос, тест одновременных доставок) снят `evidence/tests/service-tests.md`. На `6ba74b1` (единица работы, поведение то же) сняты метки `evidence/bench/unit-of-work-after/` и `evidence/rollout/unit-of-work*/`, а ещё `evidence/replicas/test-persistence.md`, `evidence/failover/test-failover.md`, `evidence/attachments/defense-faults.md`, `evidence/s3/privacy.md`, `evidence/worker/process.md`, `evidence/relay/process.md`. На `399da05` снята таблица «Красные прогоны» в `failure-checks.md`. Остальные файлы уровня 4 сняты на `e2a6427`: из кода приложения `399da05` меняет только `src/utils/image_variants.py`, одну ветку перевода в RGBA, а `6ba74b1` поведения не меняет. `d8fe2e8` меняет только путь отказа: метки и файлы на `6ba74b1` не переснимались, потому что на пути без отказа правка убирает один таймер блока и обменов с PostgreSQL не добавляет, а `make failure_checks` на новом commit те же отказы прошёл. Остались снятыми на прежнем коде `ff1a83b` и названы так в шапках: метка `evidence/uploads/baseline/`, `evidence/rollout/async-attachments/`, `evidence/migrations/async-attachments.md`, `evidence/s3/worker-key.md`: это доказательства перехода уровня 3, их поведение уровень 4 не менял.
|
||||
|
||||
### Уровень 3
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
| Публичный smoke | `make test` | `PASS: lab5 public API scenario` | `evidence/tests/test-isolated.md` |
|
||||
| Минимум лаб 1–4 сохранён с переходом 201 → 202 | `make student_test` через LB | 224 passed, реплики выполнены; сверка: 389 сценариев, 358 проверены, 31 исключение | `evidence/tests/student-test-lb.md` |
|
||||
| Тот же набор на временной базе | `make test_isolated` | smoke PASS; 218 passed, 6 skipped (реплики); уборка полная | `evidence/tests/test-isolated.md` |
|
||||
| Отказы | `make failure_checks` (`b104690`) | 147 passed, pytest 2214 с, `crash markers 0` | `evidence/tests/failure-checks.md` |
|
||||
| Ветки сервисов и настоящая единица работы | `make service_test`, `make service_test_db` (`d8fe2e8`) | 201 passed за 1,44 с без хранилищ; 75 passed за 32,47 с на временной базе; 16 регрессий дают названный красный. С тестами предела заданий сейчас 215 и 78 passed (прогон перед коммитом этой правки, файл доказательства не переснимался) | `evidence/tests/service-tests.md` |
|
||||
| Заморозка PostgreSQL: сессий сверх пула нет, одна запись об отказе | `driver.py --port 8080 freeze-sessions` (TCP-прокси пробы, сервер не трогается), `driver.py freeze-lb` (`docker pause` на своём временном проекте, рабочий `mtusi-lab5` — код 2); то же в тестах `test_no_sessions_over_pool_after_freeze`, `test_deadline_in_second_block_single_record` | 503 за 4,00–4,03 с при сроке 2 с, записей пула нет, сессий через прокси 0 во всех раундах; через LB 503 за 8,01–8,09 с, 504 нет, сессий до и после каждой заморозки поровну | `evidence/storage/freeze-sessions.md` |
|
||||
| 202 только после устойчивого приёма и сохранения задания | `test_durable_state_at_202`, `test_upload_with_broker_stopped`, `test_upload_with_broker_paused` | к 202 объект в staging, строка и намерение в одной транзакции; брокер остановлен или заморожен — по-прежнему 202, намерение ждёт (на уровне 3 было 503) | `evidence/tests/failure-checks.md` |
|
||||
| Остановка API после ответа не теряет работу | `test_api_killed_after_202` | реплика убита после 202, вложение становится `ready` | `evidence/tests/failure-checks.md` |
|
||||
| Отдельные broker и worker в общем compose | `driver.py broker-check`, `driver.py worker-process` | образ с тегом и digest, volume, AMQP только на loopback; PID 1 `python -m src.worker`, лимиты 1 CPU / 1 ГБ | `evidence/broker/stand.md`, `evidence/worker/process.md` |
|
||||
| Сообщения durable | `broker-check`, `test_queue_durable` | очередь durable, сообщение persistent | `evidence/broker/stand.md`, `evidence/tests/failure-checks.md` |
|
||||
| Доставка at least once, ack после устойчивого эффекта | `test_worker_killed_during_processing`, `test_redelivery_of_ready_is_noop` | worker убит посреди обработки — задание доводится; регрессия «ack до фиксации» делает тест красным (design, «Уточнения apply», п. 12) | `evidence/tests/failure-checks.md` |
|
||||
| Недоступность worker не вызывает синхронный resize | `test_worker_down_api_serves`, `worker-process` | API принимает и отвечает, `_imaging` нет в процессах реплик | `evidence/tests/failure-checks.md`, `evidence/worker/process.md` |
|
||||
| Состояния в API | `test_attachment_becomes_ready`, `test_queued_while_worker_stopped`, `test_processing_visible`, `test_undecodable_becomes_failed` | `queued`, `processing`, `ready`, `failed` видны в метаданных | `evidence/tests/student-test-lb.md`, `evidence/tests/failure-checks.md` |
|
||||
| Оригинал неизменен | `test_original_published_unchanged`, `driver.py attachment-storage` | те же байты и SHA-256; байты только в приватном bucket | `evidence/tests/failure-checks.md`, `evidence/attachments/storage.md` |
|
||||
| Thumbnail по контракту | `test_thumbnail_*`, `test_download_thumbnail` | 256 × 160 у fixture, округление вниз, минимум 1 px, EXIF, alpha на белый, настоящий JPEG, размеры и SHA-256 сходятся с метаданными | `evidence/tests/student-test-lb.md`, `evidence/attachments/defense.md` |
|
||||
| Ограниченный retry | `[worker] max_attempts` = 5, `test_transient_error_retried`, `test_attempts_exhausted` | временная ошибка повторяется под тем же `job_id`, исчерпание — `failed` с `retry_exhausted` | `evidence/worker/process.md`, `evidence/tests/failure-checks.md` |
|
||||
| Финальное `failed` с безопасным `error_code` | `test_undecodable_becomes_failed`, `test_staging_corrupted`, журнал | `invalid_image`, `processing_failed`; причина для оператора — в задании и журнале | `evidence/worker/logs.md`, `evidence/tests/failure-checks.md` |
|
||||
| Повтор не создаёт второго набора вариантов | `test_ready_failure_retried`, `test_redelivery_of_ready_is_noop`; проба ограничения | второй вариант с тем же именем — 23505 `pk_attachment_variants` | `evidence/attachments/storage.md`, `evidence/migrations/async-attachments.md` |
|
||||
| В сообщении нет bytes и credentials | `test_job_message_matches_schema` | сообщение проходит `contracts/jobs.schema.json`, только ID и служебные поля | `evidence/tests/failure-checks.md` |
|
||||
| Демонстрация: worker остановлен → … → `ready` | `driver.py --port 8080 defense-scenario` | все строки `expected` = `got`, `StartedAt` API и брокера новые, у relay прежний; thumbnail 256 × 160, crop 128 × 128, optimized 320 × 200 | `evidence/attachments/defense.md` |
|
||||
| Принятое задание переживает рестарт брокера с volume | `test_broker_restart_keeps_job`, `test_broker_kill_keeps_confirmed`, `test_broker_recreated` | сообщения на месте после `stop`, `KILL` и `up --force-recreate` | `evidence/tests/failure-checks.md` |
|
||||
| Очереди разных баз разделены | `make test_isolated KEEP_TEST_DB=1`, `broker-check --require-test-queue`, `make test_isolated` | очередь временной базы есть после первого и нет после второго | `evidence/broker/isolated.md` |
|
||||
| Сохранность и hook | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS`; `api`, `haproxy`, `postgres`, `rabbitmq`, `s3`, `valkey` — те же контейнеры и новый `StartedAt`, `relay`, `worker` и `cleaner` прежние | `evidence/replicas/test-persistence.md` |
|
||||
| Отказ реплики | `make test-failover` `stop` и `kill` | `failed_attempts` 0, восстановление 1,72 и 0,85 с | `evidence/failover/test-failover.md` |
|
||||
| Принявшая реплика остановлена | `driver.py attachment-failover --mode stop\|kill` | файл отдаёт другая реплика, SHA-256 тот же, постороннему 404 | `evidence/attachments/failover.md` |
|
||||
| Согласованность БД и S3 | `driver.py upload-consistency` | 503, строки `pending` не видны, уборщик убрал по ключу staging, объектов без строки 0 | `evidence/attachments/consistency.md` |
|
||||
| Приватность S3, права worker | `make s3_check` | `PASS: 90 checks`; worker: запись и чтение — да, удаление, список, админ — 403 | `evidence/s3/cleaner-staging.md` (и `evidence/s3/worker-key.md`, `ff1a83b`) |
|
||||
| Журнал worker | проба на стенде | общий `request_id` записей задания, `filename` 0 раз, сообщение не по схеме — `error` без содержимого | `evidence/worker/logs.md` |
|
||||
| Миграция только расширяет, откат без отката схемы | проба на временной базе, `make rolling_update COMMIT=cc33a03 MIGRATE=0` и возврат (`ff1a83b`) | CHECK `NOT VALID`, по `lock_timeout` — без изменений; прежний образ работает, чтение нового статуса — 500 | `evidence/migrations/async-attachments.md` |
|
||||
| Сроки LB пути загрузки | `driver.py lb-upload-timeouts` | 202 после 12 с молчания, 504 через 10 и 30 с, 400 в формате контракта | `evidence/uploads/lb-timeouts.md` |
|
||||
| Замена реплик под нагрузкой | `make bench_rollout ROLLOUT_LABEL=async-attachments` (`ff1a83b`), `ROLLOUT_LABEL=pipeline-reliability` (`e2a6427`), `ROLLOUT_LABEL=unit-of-work` (`6ba74b1`) | 8,52, 8,67 и 8,68 с, ошибок 0, новые миграции, записей столько же, сколько ключей (12000 и 12001) | `evidence/rollout/async-attachments/summary.md`, `evidence/rollout/pipeline-reliability/summary.md`, `evidence/rollout/unit-of-work/summary.md` |
|
||||
| Память реплики при загрузках | `make bench_uploads` (`ff1a83b`) | «с лимитом» 10 MiB: пик 172,9 / 180,1 / 185,6 MiB при 10 / 20 / 40 клиентах, OOM 0, 5xx 0 | `evidence/uploads/baseline/summary.md` |
|
||||
| Секретов в доказательствах нет | поиск значений из `.env` по `evidence/` | 17 значений, 0 совпадений | `evidence/tests/secrets.md` |
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
Исключения сверки покрытия подтверждены файлами этой лабы: `evidence/cache/hits.md`, `evidence/auth/passwords-and-tokens.md`, `evidence/idempotency/replay-after-restart.md` сняты на `9639aa1`, `test_exclusion_evidence_exists` зелёный.
|
||||
|
||||
### Уровень 4
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Crop 128 × 128 по контракту | `test_crop_center`, `test_crop_small`, `test_crop_orientation_alpha`, `test_download_crop_optimized` | центр, маленькие растягиваются, ориентация, alpha на белый, JPEG; размеры и SHA-256 по байтам | `evidence/tests/student-test-lb.md`, `evidence/attachments/defense.md` |
|
||||
| Optimized WebP, параметры качества и удаление метаданных описаны | `test_optimized_fit`, `test_optimized_small`, `test_optimized_no_metadata`, `test_optimized_alpha`; раздел «Варианты и лимиты обработки» | вписан в 1280, без увеличения; `quality=80`, `method=4`; EXIF, XMP, ICC нет; прозрачность цела | `evidence/tests/student-test-lb.md`, `evidence/attachments/defense.md` |
|
||||
| Лимит по bytes | `test_limit_oversized_staging` | объект больше строки не читается: `processing_failed` | `evidence/tests/failure-checks.md` |
|
||||
| Лимит по пикселям | `test_limit_pixels` | `invalid_image`, причина `limit_pixels` | `evidence/tests/failure-checks.md` |
|
||||
| Лимит по времени | `test_limit_cpu_scan_bomb`, `test_limit_render_timeout` | настоящий дорогой JPEG прерван по CPU: `invalid_image`; срок процесса — временная ошибка | `evidence/tests/failure-checks.md` |
|
||||
| Лимит по памяти worker | `test_limit_memory`, `test_max_pixels_fit_worker_memory`, `test_pixel_limit_png_modes`, `test_render_killed`, `driver.py worker-process` | `RLIMIT_AS` — `invalid_image`; 40 Мпкс укладывается в любом типе PNG, включая серый с альфой и RGB с tRNS; убитый процесс обработки не роняет worker; лимиты 1 CPU / 1 ГБ; два файла на обеих границах — `memory.peak` 705–926 МиБ, сумма пиков 987 МиБ, OOM нет (`driver.py worker-memory`) | `evidence/tests/failure-checks.md`, `evidence/worker/process.md`, `evidence/worker/memory.md` |
|
||||
| Разрыв PostgreSQL и брокера закрыт outbox | `test_upload_with_broker_stopped`, `test_upload_with_broker_paused`, `test_relay_survives_broker_outage`, `test_relay_survives_database_outage`, `driver.py relay-process`, `broker-check` | 202 без брокера; у реплик нет настроек брокера; relay переживает отказы (тот же `StartedAt`, `RestartCount` 0) | `evidence/tests/failure-checks.md`, `evidence/relay/process.md`, `evidence/broker/stand.md` |
|
||||
| Crash между COMMIT и publish, задача доходит до `ready` без ручного задания | `driver.py defense-faults`, окна «после COMMIT `queued` до publish» и «после подтверждения до отметки»; `test_relay_killed_before_publish`, `test_relay_killed_after_confirm` | `published_at` пуст, 0 сообщений, после запуска relay — `ready`, `attempt` 1; при KILL после confirm — 2 сообщения, `ready`, `attempt` 1, очередь пуста | `evidence/attachments/defense-faults.md`, `evidence/tests/failure-checks.md` |
|
||||
| Состояние намерений видно оператору | `driver.py pipeline-state`, в том числе при замороженном брокере | задания по состояниям, due, аренды; брокер заморожен — `available: false`, код 0 | `evidence/relay/pipeline-state.md` |
|
||||
| Backoff с jitter | `test_retry_backoff_with_jitter`, `test_retry_waits_outside_worker`, `test_relay_respects_next_attempt` | пауза растёт случайно в `[d/2, d]`, не занимает место конкуренции, попытка не раньше срока; регрессия «фиксированная пауза» — красный | `evidence/tests/failure-checks.md` |
|
||||
| Различие постоянных и временных ошибок | `test_undecodable_becomes_failed`, `test_staging_corrupted`, `test_transient_error_retried`, `test_attempts_exhausted` | постоянная — `failed` сразу (`attempt` 1); временная повторяется, затем `retry_exhausted` | `evidence/tests/failure-checks.md`, `evidence/worker/logs.md` |
|
||||
| Реестр `failed` | `make replay`, `test_replay_registry_dry_run`, `test_replay_by_code` | показ без изменений; выбор по коду и причине; реестр — строки PostgreSQL, отдельной DLQ нет | `evidence/relay/logs.md`, `evidence/attachments/defense-faults.md` |
|
||||
| Безопасный явный replay, не дубль успешной job | `driver.py defense-faults`, окна replay; `test_replay_returns_work`, `test_replay_ready_refused`, `test_replay_in_progress_refused`, `test_replay_without_source_refused`, `test_replay_new_budget` | `--apply` с выбором, то же задание, `attempt` 2, `attempt_base` 1, запись аудита; `ready` — код 3 `already_ready`, ничего не изменилось | `evidence/attachments/defense-faults.md`, `evidence/relay/logs.md` |
|
||||
| Остановка worker после записи объекта до ack, повтор завершает тот же результат | `driver.py defense-faults`, окна «после записи объектов до COMMIT» и «после COMMIT до ack»; `test_crash_after_objects_before_commit`, `test_crash_after_commit_before_ack` | те же SHA-256 трёх объектов в S3 и метаданных, `attempt` 2; после COMMIT — no-op, тот же `updated_at` | `evidence/attachments/defense-faults.md`, `evidence/tests/failure-checks.md` |
|
||||
| Timeout и lease зависшего `processing` | `test_hung_worker_lease_fencing`, `test_hung_worker_thawed_after_ready`, `test_long_attempt_keeps_lease`, `test_duplicate_during_processing`, `test_last_attempt_lost`, `test_worker_killed_during_processing` | истёкшую аренду возвращает relay; прежняя попытка после разморозки — `superseded`; живая не теряется, дубль без эффекта | `evidence/tests/failure-checks.md` |
|
||||
| Ограниченная конкуренция и prefetch | `test_concurrency_bounded`, `test_prefetch_bounded`, `test_published_backlog_limit`, `test_broker_memory_alarm` | prefetch 2 + конкуренция 2, сообщения сверх них у брокера; предел опубликованных 1000 | `evidence/tests/failure-checks.md`, `evidence/worker/process.md` |
|
||||
| Очистка staging после безопасной фиксации | `test_staging_removed_after_ready`, `test_staging_retention`, `test_staging_keeps_current_work`, `test_staging_cleanup_survives_outage`, `test_staging_foreign_key_kept`, `test_reconcile_orphan_staging`, `driver.py upload-consistency`, `make s3_check` | у `ready` убран следующим проходом (`removed_ready`), у `failed` по сроку; текущая работа цела; отказ S3 не держит сообщения; список уборщика только по двум префиксам | `evidence/tests/failure-checks.md`, `evidence/attachments/consistency.md`, `evidence/s3/cleaner-staging.md` |
|
||||
| Шаг 4 сценария защиты | `driver.py --port 8080 defense-faults` | шесть окон, все строки `expected` = `got`, триггеров не осталось | `evidence/attachments/defense-faults.md` |
|
||||
| Тесты ловят нарушение | десять временных регрессий задачи 10.9 | каждая даёт названный красный, откачена, хэши `src` совпали | `evidence/tests/failure-checks.md`, раздел «Красные прогоны» |
|
||||
| Журнал relay и worker, без `filename` и секретов | проба на стенде | общий `request_id`, причина и оператор replay, метка `filename` 0 раз | `evidence/worker/logs.md`, `evidence/relay/logs.md` |
|
||||
| Миграции расширяют, откат работает | проба на временной базе, откат на `7f38948` и возврат | CHECK `NOT VALID`, индексы `indisvalid`, планы по индексам решения 10, по `lock_timeout` без изменений; прежний образ работает; вложение прежнего образа — один thumbnail, `crop` 404, сверка без находок | `evidence/migrations/pipeline-reliability.md` |
|
||||
| Сроки LB после отказа от публикации | `driver.py lb-upload-timeouts` | 202 после 12 с молчания, 504 через 10 и 30 с, 400 в формате контракта; цепочка 26 с и 73 с | `evidence/uploads/lb-timeouts.md` |
|
||||
| Очереди разных баз разделены | `make test_isolated KEEP_TEST_DB=1`, `broker-check --require-test-queue`, `make test_isolated` | очередь временной базы есть после первого и нет после второго | `evidence/broker/isolated.md` |
|
||||
| Замена реплик с двумя ревизиями под нагрузкой | `make bench_rollout ROLLOUT_LABEL=pipeline-reliability` | 8,67 с, ошибок 0, `a1d4c7e90b23` → `d3f9a6b2c1e7`, записей 12000 = ключей 12000, `dirty` false | `evidence/rollout/pipeline-reliability/summary.md` |
|
||||
|
||||
### Трек 1 уровня 5
|
||||
|
||||
Change `track1-queue-overload`, код `d68a016`, метка `baseline4` — `b104690`. Гипотезы, таблицы и выводы — раздел «Очередь под перегрузкой».
|
||||
|
||||
| Критерий | Команда | Результат | Файл |
|
||||
|---|---|---|---|
|
||||
| ≥3 настройки на разных размерах | `make bench_queue QUEUE_LABEL=baseline4` | 4 настройки × 4 класса (12 конфигураций) × 3 повтора | `evidence/queue/baseline4/summary.md` |
|
||||
| Throughput, очередь, queue lag, p95 до `ready`, RSS | там же | таблица «Настройки и классы» | `evidence/queue/baseline4/cells.csv`, `timeline.csv` |
|
||||
| Backpressure и ограничение принятой работы | там же, `make failure_checks FAULT_ARGS='-k backlog'` | плато 250 против 423; 429 от мест, затем от предела; 6 проверок отказов `test_backlog_*` (`-k backlog` выбирает ещё `test_published_backlog_limit` — предел опубликованных у relay) | `evidence/queue/baseline4/summary.md`, `evidence/tests/failure-checks.md` |
|
||||
| Восстановление | там же | ноль незавершённых без оператора в 57 ячейках, потерянных и зависших 0, `failed` 0 в этой метке; в `baseline` и `baseline3` на `lp` (4, 4) — 2 и 4 задания в `failed`, возврат — `make replay` | `evidence/queue/baseline4/cells.csv` |
|
||||
| Компромисс latency и ресурсов | там же | раздел «Очередь под перегрузкой» | `REPORT.md` |
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
### Поочерёдная замена на версию с брокером: метка `async-attachments`
|
||||
|
||||
Гипотеза: миграция и замена реплик с `04f8592` на `ff1a83b` идут без ошибок клиента, потому что схема только расширяется, а публикация ленива и не нужна чтениям и записи сообщений.
|
||||
|
||||
Методика — `make bench_rollout`: `git.dirty` false, `swapouts_delta` 0, посторонних контейнеров нет. Две реплики API 1 CPU / 512 МБ, PostgreSQL 2 CPU / 1 ГБ, Valkey 0,5 CPU / 128 МБ, HAProxy 1 CPU / 256 МБ, k6: 100 записей с ключом и 100 чтений в секунду, один прогон. В профиле только сообщения и история: загрузки не участвуют, поэтому смесь 201 и 202 он не показывает.
|
||||
|
||||
| Замена | Сборка / миграция | Ревизия | Ошибки до / во время / после | Успешных в секунду | p95 до / макс. во время | Записи |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 8,52 с | 1 / 1 с | `5c3e1f0a9b7d` → `a1d4c7e90b23` | 0 / 0 / 0 | 200 / мин. 200 | 4 / 8 мс | 12000 сообщений = 12000 ключей, повторов 0 |
|
||||
|
||||
CPU API всего: 0,54 ядра до и 0,55 после, 0,78 во время. Гипотеза подтверждена. Сырые данные — `evidence/rollout/async-attachments/`.
|
||||
|
||||
### Поочерёдная замена на версию с relay: метка `pipeline-reliability`
|
||||
|
||||
Гипотеза: две ревизии (атомарная и индексы `CONCURRENTLY`) и замена реплик с `7f38948` на `e2a6427` идут без ошибок клиента: схема только расширяется, а новым репликам брокер не нужен. Методика та же: `git.dirty` false, `swapouts_delta` 0, посторонних контейнеров нет, питание от сети. Загрузки в профиле не участвуют.
|
||||
|
||||
| Замена | Сборка / миграция | Ревизия | Ошибки до / во время / после | Успешных в секунду | p95 до / макс. во время | Записи |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 8,67 с | 1 / 2 с | `a1d4c7e90b23` → `d3f9a6b2c1e7` | 0 / 0 / 0 | 200 / мин. 200 | 5 / 72 мс | 12000 сообщений = 12000 ключей, повторов 0 |
|
||||
|
||||
CPU API всего: 0,61 ядра до, 0,95 во время, 0,62 после. Гипотеза подтверждена. Сырые данные — `evidence/rollout/pipeline-reliability/`.
|
||||
|
||||
### Поочерёдная замена на единицу работы: метки `unit-of-work` и `unit-of-work-previous`
|
||||
|
||||
Гипотеза: API, схема и настройки те же, поэтому замена на `6ba74b1` идёт без ошибок клиента и с версии до `pipeline-reliability`, и с предыдущего commit. Методика та же: `git.dirty` false, `swapouts_delta` 0, `host_warnings` пусты, питание от сети; посторонние контейнеры на хосте — `domains-api-1`, `domains-bot-1`, `domains-postgres-1` (названы в паспортах).
|
||||
|
||||
| Метка, откуда | Замена | Сборка / миграция | Ревизия | Ошибки до / во время / после | Успешных в секунду | p95 до / макс. во время | Записи |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `unit-of-work`, `7f38948` (`make bench_rollout ROLLOUT_LABEL=unit-of-work`) | 8,68 с | 0 / 2 с | `a1d4c7e90b23` → `d3f9a6b2c1e7` | 0 / 0 / 0 | 200 / мин. 200 | 6 / 161 мс | 12001 сообщение = 12001 ключ |
|
||||
| `unit-of-work-previous`, `b2fb88f` (`bench/run.py --profile rollout --from b2fb88f`) | 10,2 с | 1 / 3 с | `d3f9a6b2c1e7` → `d3f9a6b2c1e7` | 0 / 0 / 0 | 200 / мин. 200 | 7 / 180 мс | 12001 сообщение = 12001 ключ |
|
||||
|
||||
CPU API на запрос до и после замены у `unit-of-work`: 3089 и 3113 мкс, PostgreSQL 493 и 524 мкс; у `unit-of-work-previous` — раздел «Единица работы» выше. Гипотеза подтверждена. Сырые данные — `evidence/rollout/unit-of-work/`, `evidence/rollout/unit-of-work-previous/`.
|
||||
|
||||
### Память реплики при загрузках: метка `baseline`
|
||||
|
||||
Снята на `ff1a83b`, потому что на неё ссылаются исключения сверки лабы 4; с этой меткой новые не сравниваются (с уровня 4 профиль не запускает брокер). Методика — `make bench_uploads`: одна реплика 1 CPU / 512 МБ без swap, 72 прогона, 50 мин, медиана из 3 повторов; worker не запущен, задания ждут в очереди. Поправки к чтению — `evidence/uploads/README.md`.
|
||||
|
||||
| Вариант, 10 MiB | C = 10: пик, MiB | C = 20 | C = 40 | OOM при 40 | Загрузок/с при 10 | p95 при 10, мс |
|
||||
|---|---|---|---|---|---|---|
|
||||
| с лимитом | 172,9 | 180,1 | 185,6 | 0/3 | 10,50 | 1253 |
|
||||
| без лимита | 227,6 | 331,0 | OOM | 3/3 | 9,00 | 1480 |
|
||||
|
||||
H1 (пик ограничен местами) и H4 (нет 503 по сроку S3) выполнены. H2 в сводке — «нет»: вариант «до» теперь `04f8592`, где места уже есть, поэтому прежнее поведение он не показывает; настоящее «до» — отчёт лабы 4. H3 в сводке — «нет»: на 1 MiB «с лимитом» даёт 85–89 % «без лимита» при пороге 90 %, на 10 MiB — 117–121 %. Память приёма после перехода на брокер в границах прежних сценариев спека: ~185 MiB из 512 при 40 клиентах.
|
||||
|
||||
### Очередь под перегрузкой
|
||||
|
||||
Трек 1 уровня 5, change `track1-queue-overload`. **Основная метка — `baseline4`: код commit `d68a016`, метка commit `b104690`** (`dirty` false, 57 ячеек из 57, 2 ч 00 мин, `swapouts_delta` 0, сна нет, предупреждений о хосте нет, посторонних контейнеров нет). `src/` и `bench/` на коммитах меток `baseline2`–`baseline4` те же, что на `5ee3257`; после них `bench/run.py` получил только поле паспорта с образами S3 и брокера. Паспорт `baseline4` его не содержит, поле появилось после метки; её образы (`git show d68a016:docker-compose.yml`): S3 `chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d`, брокер `rabbitmq:4.3.7@sha256:bd88985187aa73cd598fa0d8b31d49b2f814a6d9e58f6d5a89bae588669d946a`. Гипотезы и правило записаны и закоммичены раньше первой метки, пороги с тех пор не менялись. Числа порогов — из проб стадии propose (design, раздел «Пробы»); числа результатов ниже — из `evidence/queue/baseline4/summary.md`, `cells.csv` и `timeline.csv`, если не названа другая метка.
|
||||
|
||||
**Четыре метки.** Снято четыре, основная выбрана правилом, записанным заранее и не зависящим от вердиктов: меньше задетых выгрузкой ячеек, при равенстве — меньше `swapouts_delta` (`QUESTIONS.md`; `openspec/changes/archive/2026-11-02-track1-queue-overload/tasks.md`, 10.20б). Остальные каталоги остаются в репозитории как запись.
|
||||
|
||||
| Метка | Код | Commit метки | Выгрузка, страниц | Ячеек с `host_swap` | Статус |
|
||||
|---|---|---|---|---|---|
|
||||
| `baseline` | `d667fa3` | `7999002` | 0 | 0 | снята до правок инструмента, запись |
|
||||
| `baseline2` | `5ee3257` | `9639aa1` | 309 432 | 5 | запись |
|
||||
| `baseline3` | `1373e7d` | `d68a016` | 26 046 | 1 (`lp-c2p256-r1`) | запись |
|
||||
| `baseline4` | `d68a016` | `b104690` | 0 | 0 | **основная** |
|
||||
|
||||
Почему `baseline` переснята: проверка нашла ошибки инструмента, которые нельзя поправить задним числом. Что в ней неверно:
|
||||
|
||||
- `lb_down` считал строку `BACKEND` репликой, и выход одной реплики не срабатывал: условие H7 «`lb_down` нет» метка не проверяла;
|
||||
- `cpu_worker_per_job_s` занижен на ~6–11 %: CPU до конца восстановления делился на все `ready`, включая окно `after` (медианы конфигураций матрицы `baseline` к `baseline4`, без `lp-c4p4`: 5,6–8,8 % при конкуренции до двух, 8,2–10,8 % при четырёх);
|
||||
- каждый перезапуск worker считался завершением ядром: причина в метке не проверялась;
|
||||
- queue lag есть только на ячейку, а не по окнам, в сводке его нет; CPU и троттлинг — не по всем окнам и ролям;
|
||||
- нет счётчика перезапусков relay, лишние строки в базе не искались.
|
||||
|
||||
Пороги H1–H9 и порог правила рекомендации не менялись.
|
||||
|
||||
**Главное.** В основной метке подтверждены H1, H2, H3, H5, H6, H7, H8, H9, **H4 не подтверждена** (1 ячейка из 33 ниже порога, разбор ниже). **H2 разошлась между метками:** в `baseline3` она «нет», разбор ниже. Рекомендация правила — (2, 2) во всех четырёх метках, значения по умолчанию оставлены. Конкуренция сверх двух при 1 CPU не ускоряет, а на `lp` (4, 4) ломает обработку: ядро завершало процессы во всех 12 ячейках четырёх меток, в основной — `oom_kill` 68 и 5 завершений процесса 1, throughput разбора 0,36 вместо 0,96. Настоящее ускорение даёт второй worker.
|
||||
|
||||
**Команда:** `make bench_queue QUEUE_LABEL=baseline4` (занятая метка — отказ, ~2 ч 10 мин, `RESUME=1`), самопроверка — `make bench_queue_quick` (~11 мин, метка в git не идёт).
|
||||
|
||||
**Методика.** Стенд `mtusi-bench`: LB, две реплики API 1 CPU / 512 МБ, PostgreSQL 2 CPU / 1 ГБ, Valkey, S3 1 CPU / 512 МБ, брокер 1 CPU / 512 МБ, relay 0,25 CPU / 256 МБ, worker 1 CPU / 1 ГБ, уборщик 0,25 CPU / 256 МБ — лимиты рабочего стенда, без swap; у worker — `restart: unless-stopped`, как на рабочем стенде. Каждая ячейка — свежий стенд на новых volume.
|
||||
|
||||
- **Настройки** (конкуренция, prefetch): (1, 1), (2, 2) — значения по умолчанию, (4, 4), (2, 256).
|
||||
- **Классы:** `s` — JPEG 1600 × 1200, q85, ~0,5 MiB; `m` — PNG из шума ~3,5 Мпкс, ~10 MiB; `lj` — JPEG 8000 × 5000, q88, ~8,6 MiB; `lp` — PNG RGBA 8000 × 5000, значащие 4 бита на канал, ~10 MiB. Файлы детерминированы от зерна, размеры и SHA-256 — в паспорте.
|
||||
- **Матрица:** (2, 2) и (4, 4) на всех классах; (1, 1) на `m` и `lp`; (2, 256) на `s` и `lp`, по три повтора, круги с перестановкой от зерна; план — в паспорте до первой ячейки.
|
||||
- **Интенсивность** одна на класс для всех настроек, низкая / высокая, загрузок/с: `s` 1,5 / 8, `m` 1,5 / 6, `lj` 1,2 / 6, `lp` 0,5 / 2,5. Открытая модель (`constant-arrival-rate`), ответ не повторяется: 429 — отказ.
|
||||
- **Окна:** `before` 10 с низкой λ; `over` 20 с высокой (блоки предела и рестартов — 25 с, приёма — 45 с); `recovery` — до нуля незавершённых, не дольше 420 с; `after` 10 с низкой λ.
|
||||
- **Контрольный поток** всё время: запись 10/с, чтение истории 10/с, скачивание готовых 5/с.
|
||||
- **Блоки:** `gate-on` и `gate-off` — `s`, (2, 2), 20/с, предел по умолчанию и выключен; `accept` — `m`, (2, 2), 15/с, 45 с; `w2-p2`, `w2-p256` — второй worker в конце `over`; `kill-worker` — KILL и запуск посреди `over`; `restart-broker` — `compose restart` посреди `over`.
|
||||
- **Шум:** разброс — min–max трёх повторов. Разница двух конфигураций считается эффектом, только если их разбросы не пересекаются и разница медиан больше наибольшего разброса пары; иначе «в пределах шума». Отдельной метки A/A нет: настройка по умолчанию повторяется в каждом круге.
|
||||
|
||||
**Определения.**
|
||||
|
||||
| Что | Как считается | Откуда |
|
||||
|---|---|---|
|
||||
| Очередь, `outbox` | `queued`, не опубликовано, срок наступил | PostgreSQL |
|
||||
| `waiting` | `queued`, не опубликовано, срок не наступил: пауза следующей попытки | PostgreSQL |
|
||||
| `published` | `queued`, брокер подтвердил, никто не взял | PostgreSQL |
|
||||
| `broker_ready`, `broker_unacked` | сообщения в очереди брокера и выданные, не подтверждённые | метрики брокера |
|
||||
| `processing` | взято, идёт аренда | PostgreSQL |
|
||||
| `prefetched` | `max(0, broker_unacked − processing)`: у worker, ждёт места конкуренции | вычисляется |
|
||||
| `unfinished` | `outbox + waiting + published + processing`: то, что считает предел | PostgreSQL |
|
||||
| `oldest_s` | возраст старейшего незавершённого | PostgreSQL |
|
||||
| Throughput | вложений с `updated_at` статуса `ready` в окне `over` и в окне `recovery`, делённые на длину окна | `GET /attachments/{id}` |
|
||||
| Время до `ready` | `updated_at` у `ready` минус момент ответа 202; p50, p95, p99 по окну прихода; `before` и `after` — повторы сводятся вместе | `GET /attachments/{id}`, k6 |
|
||||
| Queue lag | возраст старейшего незавершённого, пик по окну тика (`peak_oldest_<окно>_s`), и время задания от подтверждения брокером до взятия, p50 и p95 по окну прихода (`queue_wait_<окно>_*_ms`) | PostgreSQL, журнал worker |
|
||||
| Восстановление | от последней загрузки окна `over` до нуля незавершённых | k6, PostgreSQL |
|
||||
| RSS | `VmHWM` процесса 1 worker, `render_peak_kib` процесса обработки (p50, наибольший), `memory.peak`, наибольшая `anon`, `oom_kill`; у перезапущенного контейнера — наибольшее и сумма по жизням | `/proc`, журнал, cgroup |
|
||||
| Причина завершения worker | `worker_die_oom` (`oom` и код 137), `worker_die_command` (`kill`), `worker_die_other` (остальное, `worker_exit_codes`) | `docker events` |
|
||||
|
||||
**Гипотезы.**
|
||||
|
||||
| № | Гипотеза | Подтверждено, если |
|
||||
|---|---|---|
|
||||
| H1 | Потолок при 1 CPU — CPU worker; конкуренция сверх двух его не поднимает | на всех классах медиана throughput окна `recovery` (4, 4) / (2, 2) ≤ 1,05; CPU worker в окне `over` при c ≥ 2 ≥ 0,85 ядра; на `m` и `lp` (1, 1) / (2, 2) ≤ 1,0 |
|
||||
| H2 | Обработка задания дольше пропорционально конкуренции, память растёт на пик процесса | `duration_ms` p50 (4, 4) / (2, 2) ≥ 1,5 на всех классах; `memory.peak` (2, 2) < 1 ГБ без `oom` на всех классах; (4, 4) на `lp`: `memory.peak` ≥ 95 % лимита во всех повторах, `oom_kill` > 0 хотя бы в одном; (4, 4) на `lj`: без `oom`, пик ≤ 500 МиБ |
|
||||
| H3 | Большой prefetch не меняет throughput одного worker и прячет очередь от брокера и второго worker | (2, 256) / (2, 2): throughput в [0,85; 1,15], p95 до `ready` в [0,8; 1,25] на `s` и `lp`; пик `broker_ready` ≤ 10 % пика незавершённых у (2, 256), ≥ 70 % у (2, 2); блок второго worker: доля второго среди заданий, завершённых после его запуска, ≥ 30 % при `prefetch` 2 и ≤ 5 % при 256, восстановление p256 / p2 ≥ 1,4 |
|
||||
| H4 | Задержка под перегрузкой — это очередь | на всех ячейках матрицы без `oom` p95 до `ready` окна `over` в [0,8; 1,25] × пик незавершённых / throughput |
|
||||
| H5 | Предел ограничивает принятую работу и срок ожидания | `gate-on`: пик незавершённых ≤ 290, 429 > 0, у всех `Retry-After` 5, 5xx нет, 429 = записи `backlog`; `gate-off`: пик ≥ 375; `gate-on` / `gate-off`: p95 до `ready` и восстановление ≤ 0,75; p95 до `ready` `gate-on` в [0,8; 1,25] × предел / throughput; загрузка `before` p50 `gate-on` − `gate-off` ≤ 3 мс |
|
||||
| H6 | Восстановление: система приходит в норму сама и никого не теряет | во всех ячейках `lost`, `stuck`, `duplicate`, `sha_mismatch` нет; восстановление ≤ 1,3 × пик незавершённых / throughput окна `over` (матрица без `oom`, предел); p95 `after` ≤ 1,5 × p95 `before` по конфигурации; `failed` только при `oom` и только `retry_exhausted` |
|
||||
| H7 | Перегрузка очереди не задевает остальной API | во всех окнах всех ячеек, кроме `accept`: p95 записи и чтения ≤ 200 мс, скачивания ≤ 500 мс; 5xx контрольного потока нет; `lb_down` нет |
|
||||
| H8 | Рестарты под перегрузкой не теряют работу | `kill-worker`: всё `ready`, заданий с повторной попыткой ≤ 2, очередь разобрана не позже большего из «конец `over` + 1,3 × пик / throughput» и «KILL + аренда 70 с + 15 с»; `restart-broker`: всё `ready`, заданий с повторной попыткой нет, 5xx на загрузке нет, восстановление ≤ 1,3 × пик / throughput + 15 с |
|
||||
| H9 | Приём ограничен S3, местами и затем пределом, а не падением; S3 общий с worker | `accept`: первый 429 `busy` раньше первого `backlog`, оба есть, 5xx нет; CPU S3 в первые 30 с окна ≥ 0,85; принято за окно / длина окна ≥ 6/с; пик незавершённых ≤ 290; готовых/с в окне ≤ 1,5 при ≥ 2,4 в окне восстановления; контрольный поток: запись и чтение p95 ≤ 200 мс, скачивание ≤ 1 с, без 5xx |
|
||||
|
||||
Вердикт считает `bench/overload.py` в сводке метки: «подтверждено», «нет», «нет данных».
|
||||
|
||||
**Уточнения условий (пороги те же).**
|
||||
|
||||
- **H3, доля второго worker.** Порог говорит «среди заданий, завершённых после его запуска», а код считает только до нуля незавершённых. Окно `after` к опыту не относится: оно приходит после разбора бэклога, большого prefetch уже нечем держать, и новые задания брокер делит поровну при любом `prefetch`. Измерено: при prefetch 256 буквальная доля (`second_share_all`, все завершённые после запуска) — 6,7 / 6,9 / 6,1 %, то есть при буквальном прочтении порога ≤ 5 % H3 — **«нет»**. Вердикт считает прежний `second_share` (только разбор): 0 заданий во всех повторах. В самом окне `after` (`second_share_after`) доля 0,50 / 0,50 / 0,47. Порог не менялся, уточнение названо здесь, а не спрятано.
|
||||
- **H2 и правило рекомендации — по подтверждённому `oom`.** В `baseline` любой перезапуск считался `oom`; с `baseline2` это только завершение, подтверждённое событиями Docker, или счётчик cgroup. Условия не менялись, смысл стал тем, что в них написано; аварийный перезапуск не от ядра — пометка `worker_crash`, условие правила он не нарушает (`QUESTIONS.md`, вопрос 3). В `baseline2`–`baseline4` таких завершений нет (`worker_die_other` 0).
|
||||
|
||||
**Правило рекомендации.** Кандидат — настройка без `oom` и `failed` ни на одном классе, с throughput не ниже 90 % лучшей на каждом классе; из кандидатов — наименьшая конкуренция, а `prefetch` равен конкуренции. Настройка, снятая не на всех классах, не кандидат: по плану это (1, 1) и (2, 256), сводка их называет, порог 90 % прежний. Значения по умолчанию меняются, только если рекомендация отличается от (2, 2), и выигрыш по throughput или памяти на каком-либо классе вне шума при том, что на остальных она не хуже в пределах шума; такая правка — отдельный commit после метки с повтором `make bench_queue_quick`. Компромисс latency и ресурсов — вывод из таблиц метки; проверяемая формула: `concurrency ≤ min(CPU + доля ожидания, (лимит − база) / пик процесса)`.
|
||||
|
||||
**Вердикты основной метки** (`evidence/queue/baseline4/summary.md`, раздел «Гипотезы»).
|
||||
|
||||
| № | Вердикт | На чём |
|
||||
|---|---|---|
|
||||
| H1 | подтверждено | (4, 4) / (2, 2) по throughput восстановления: `s` 2,46 / 3,08, `m` 2,75 / 2,85, `lj` 1,98 / 2,34, `lp` 0,36 / 0,96; (1, 1) / (2, 2): `m` 2,50 / 2,85, `lp` 0,93 / 0,96 |
|
||||
| H2 | подтверждено | `duration_ms` p50 (4, 4) / (2, 2): `s` 1504 / 619, `m` 1400 / 660, `lj` 1822 / 814, `lp` 4105 / 2029 мс; `memory.peak` (2, 2) не выше 836 МиБ; `lp` (4, 4) — 1024 МиБ во всех повторах; `lj` (4, 4) — до 305 МиБ. На `lp` условие неустойчиво, разбор ниже |
|
||||
| H3 | подтверждено | пик очереди брокера при (2, 256) — 0, при (2, 2) на `s` — 96 из 100; второй worker взял 47–49 % заданий при `prefetch` 2 и 0 при 256; буквальное прочтение — «нет», см. уточнение выше |
|
||||
| H4 | **нет** | `m-c1p1-r1` 0,780 при нижней границе 0,8; разбор ниже |
|
||||
| H5 | подтверждено | пик 250 с пределом против 423 без него; p95 80,2 против 130,6 с; восстановление 80,5 против 137,5 с; все 429 — от предела, `Retry-After` 5; загрузка `before` p50 16 против 16 мс |
|
||||
| H6 | подтверждено | `lost`, `stuck`, `duplicate`, `sha_mismatch` — 0 во всех ячейках, 2280 проверенных SHA-256, `failed` 0, `unexpected_rows` 0 |
|
||||
| H7 | подтверждено | вне `accept` наибольшие p95 за все окна: запись 38,5, чтение 16,6, скачивание 105,6 мс; 5xx контрольного потока нет; `lb_down` нет: `lb_up_min` 2 во всех 57 ячейках, в этой проверке подсчёт уже верный |
|
||||
| H8 | подтверждено | `kill-worker`: заданий с повтором 2 во всех повторах, восстановление 58,5 с, завершение — команда; `restart-broker`: повторов 0, 5xx нет, восстановление 45,6 с, у relay перезапусков и завершений 0 |
|
||||
| H9 | подтверждено | первый `busy` на 2,9–3,1 с, первый `backlog` на 33,9–36,3 с; CPU S3 в первые 30 с 1,00; принято 302–310 за 45 с; пик 279–286; готовых/с 0,80–0,98 в окне и 2,92–3,07 после |
|
||||
|
||||
**Вердикты всех меток.** Числа условий и причины — `evidence/queue/<метка>/summary.md`.
|
||||
|
||||
| № | `baseline` | `baseline2` | `baseline3` | `baseline4` (основная) |
|
||||
|---|---|---|---|---|
|
||||
| H1 | подтверждено | подтверждено | подтверждено | подтверждено |
|
||||
| H2 | подтверждено | подтверждено | **нет**: `lp`, duration (4, 4) / (2, 2) = 0,965 | подтверждено |
|
||||
| H3 | подтверждено | подтверждено | подтверждено | подтверждено |
|
||||
| H4 | **нет**: 2 ячейки `m-c1p1`, 0,797 и 0,778 | **нет**: 3 ячейки `m-c1p1`, 0,794, 0,762, 0,727 | **нет**: 2 ячейки `m-c1p1`, 0,785 и 0,781 | **нет**: 1 ячейка `m-c1p1`, 0,780 |
|
||||
| H5–H9 | подтверждено | подтверждено | подтверждено | подтверждено |
|
||||
| Рекомендация | (2, 2) | (2, 2) | (2, 2) | (2, 2) |
|
||||
|
||||
**H2 разошлась между метками, и это видно по самой конфигурации.** `lp` (4, 4) от прогона к прогону сильно плавает. Основная метка подтверждает H2, но устойчивым подтверждением на `lp` это считать нельзя: условие не выполнилось в одной метке из четырёх, а в самой `baseline4` один повтор дал 2844 мс. На остальных классах отношение устойчиво: `s` 2,37–2,68, `m` 2,10–2,12, `lj` 2,17–2,29.
|
||||
|
||||
| Метка | Перезапуски, сумма | `failed` | Восст., с: медиана (min–max) | Готовых/с разбора | `duration_ms` p50 (4, 4), r1 / r2 / r3 | p50 (2, 2), медиана | Отношение |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `baseline` | 16 | 2 | 187,1 (83,1–249,1) | 0,24 | 1831 / 4288 / 3902 | 2060 | 1,894 |
|
||||
| `baseline2` | 5 | 0 | 102,0 (86,0–108,1) | 0,43 | 4291 / 4212 / 3733 | 2089 | 2,016 |
|
||||
| `baseline3` | 18 | 4 | 220,7 (163,7–332,5) | 0,20 | 4381 / 1997 / 1984 | 2070 | **0,965** |
|
||||
| `baseline4` | 5 | 0 | 95,0 (65,8–186,4) | 0,36 | 4211 / 2844 / 4105 | 2029 | 2,023 |
|
||||
|
||||
**Разбор H2 «нет» в `baseline3`.** Вердикт и порог не меняются.
|
||||
|
||||
- **Откуда 0,965.** Отношение — медиана трёх медиан. При (2, 2) всё стабильно: 2070 / 2039 / 2092 мс. При (4, 4) один повтор — 4381 мс, как обычно, а два — 1997 и 1984 мс, и медиана попала на них. `render_ms` p50 упал вместе с ними (3992 / 1823 / 1875 мс): снижение в самой обработке, а не в S3 или PostgreSQL.
|
||||
- **Значения двух видов.** Из 12 ячеек `lp` (4, 4) четырёх меток восемь лежат в 3733–4381 мс, четыре ниже: 1831, 1984, 1997, 2844 мс. То есть низкие значения бывают и в других метках (`baseline` r1, `baseline4` r2); там они не стали медианой.
|
||||
- **Предположение: в медиану попадают в основном задания, пережившие перезапуски. Данные его не подтверждают, но и не опровергают.** Журналы в метку не копируются, стенд удалён, поэтому по отдельным заданиям проверить нечем. Есть только косвенное:
|
||||
- **Доля готовых после первой гибели процесса 1** (косвенно: первая секунда, где `processing` больше конкуренции: строки убитого процесса ждут аренду, `timeline.csv`). Признак двух видов не разделяет: у низких 75–92 %, но у шести из восьми высоких тоже 70–92 % (`baseline3` r1: 91 % и 4381 мс). Корреляция с `duration_ms` по 12 ячейкам −0,30.
|
||||
- **Число перезапусков.** Связь есть, но неполная: все 6 ячеек с 0–3 перезапусками — 3733 мс и выше; из 6 ячеек с 4–10 перезапусками четыре низкие, две высокие (`baseline` r3 — 5 и 3902 мс, `baseline3` r1 — 5 и 4381 мс). Корреляция −0,78 на 12 точках: это связь, а не доказательство причины.
|
||||
- **Доля заданий с повтором:** корреляция −0,55, `baseline2` r2 — 60 % и 4212 мс.
|
||||
- **Что видно из кода, а не из замера.** `duration_p50_ms` считается по всем записям «Attachment became ready» журнала worker, а не только по окну перегрузки. Туда входят 12 файлов `s` разогрева и задания окон `before` и `after`, идущие почти без конкуренции. В `lp-c4p4-r2` метки `baseline3` это 22 записи из 73 (12 + 5 + 5). Значит, расчётом, медиана уходит к низким значениям, как только ещё ~15 из 51 задания окна `over` выполняются не при полной конкуренции. Поэтому условие на `lp` чувствительно: кого именно касается это снижение, метка не показывает.
|
||||
- **Выгрузка хоста здесь ни при чём по условию:** её единственная ячейка в `baseline3`, `lp-c2p256-r1`, в условие H2 не входит.
|
||||
|
||||
**Выгрузка хоста.** В двух метках хост выгружал страницы в swap (таблица меток выше), третья пересъёмка прошла чисто, и пользователь принял решение не переснимать бесконечно: при выгрузке результат сохраняется, после `baseline3` — ещё один прогон, больше пересъёмок нет (`QUESTIONS.md`). Причина выгрузки не установлена. Задетые ячейки `baseline2` по времени восстановления выше ближнего соседнего повтора:
|
||||
|
||||
| Ячейка | Страниц за ячейку | Восст., с | Ближний соседний повтор, с | Разница |
|
||||
|---|---|---|---|---|
|
||||
| `gate-on-s-c2p2-r3` | 23 380 | 85,57 | 84,40 | +1,4 % |
|
||||
| `w2-p256-s-c2p256-r1` | 1 852 | 36,40 | 34,48 | +5,6 % |
|
||||
| `gate-off-s-c2p2-r3` | 4 524 | 157,44 | 142,38 | +10,6 % |
|
||||
| `lp-c1p1-r3` | 25 068 | 40,34 | 36,41 | +10,8 % |
|
||||
| `accept-m-c2p2-r3` | 197 012 | 106,22 | 94,03 | +13,0 % |
|
||||
|
||||
Эффект 1–13 % с объёмом не растёт: 23 380 страниц — +1,4 %, 4 524 — +10,6 %. Похожий разброс бывает и без пометки: восстановление к среднему двух соседних повторов выше 5 % у 22 ячеек из 198 без пометки (конфигурации без задетых ячеек, без `lp-c4p4`), например `s-c4p4-r1` чистой `baseline4` +9,6 %. Причинная связь выгрузки с задержкой не показана. Без пяти ячеек вердикты и рекомендация `baseline2` те же.
|
||||
|
||||
**Оговорка к H6: `lp` (4, 4).** В основной метке условие «p95 `after` ≤ 1,5 × p95 `before`» содержательно: `before` 1,36 / 1,30 / 1,28 с, `after` 1,31 / 1,28 / 1,35 с. Но в `baseline` и `baseline3` оно проходило без смысловой нагрузки: у одного повтора p95 `before` 83,27 с и 78,44 с, потому что окно задето OOM, и о возврате задержки условие там ничего не доказывало; сам `after` был 1,31–1,63 с. Порог не менялся.
|
||||
|
||||
**Настройки и классы** (`evidence/queue/baseline4/summary.md`, «Ячейки по конфигурациям»; медиана и min–max трёх повторов). «Процесс» — пик процесса обработки по его отчёту: p50 / наибольший. Queue lag — пик возраста старейшего незавершённого по окнам before / over / after; ожидание — время задания в очереди p50 / p95, по окнам прихода before; over; after.
|
||||
|
||||
| Класс | (c, p) | Готовых/с: окно | восстановление | Пик незаверш. | Пик брокера | До `ready` over p50 / p95 / p99, с | Восст., с | `memory.peak`, МиБ | VmHWM, МиБ | Процесс, МиБ | CPU worker, S3 | Троттлинг worker | OOM | Перезапуски | Queue lag, с | Ожидание в очереди, мс |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| `s` | (2, 2) | 3.10 (3.05–3.10) | 3.08 (3.05–3.08) | 100 (97–100) | 96 (95–97) | 16.3 / 30.4 / 31.9 | 32.5 (32.4–32.6) | 175 (175–176) | 114 | 49 / 49 | 0.99, 0.07 | 0.99 | 0 | 0 | 0.5 / 12.1 / 0.5 | 2 / 4; 15544 / 29570; 2 / 3 |
|
||||
| `s` | (4, 4) | 2.65 (2.50–2.70) | 2.46 (2.32–2.49) | 107 (106–108) | 102 (101–104) | 20.9 / 41.1 / 42.6 | 43.4 (43.4–47.6) | 250 (249–251) | 116 | 49 / 49 | 1.00, 0.08 | 0.99 | 0 | 0 | 0.4 / 12.9 / 0.4 | 2 / 3; 19022 / 39208; 2 / 4 |
|
||||
| `s` | (2, 256) | 3.00 (3.00–3.10) | 3.08 (3.05–3.15) | 99 (98–100) | 0 (0–0) | 16.3 / 30.5 / 32.0 | 32.5 (32.4–32.5) | 175 (175–175) | 114 | 49 / 49 | 1.00, 0.07 | 1.00 | 0 | 0 | 0.4 / 12.0 / 0.5 | 2 / 3; 15572 / 29721; 2 / 3 |
|
||||
| `m` | (1, 1) | 2.30 (2.05–2.30) | 2.50 (2.37–2.53) | 77 (76–80) | 76 (75–78) | 16.6 / 30.2 / 31.2 | 32.3 (30.2–32.4) | 154 (154–154) | 136 | 58 / 58 | 0.73, 0.71 | 0.13 | 0 | 0 | 0.7 / 12.3 / 0.4 | 2 / 413; 16136 / 29785; 2 / 59 |
|
||||
| `m` | (2, 2) | 2.85 (2.70–2.90) | 2.85 (2.82–2.95) | 66 (63–67) | 62 (61–64) | 11.7 / 21.5 / 22.4 | 23.2 (22.4–23.3) | 210 (210–211) | 160 | 58 / 58 | 0.96, 0.77 | 0.88 | 0 | 0 | 0.3 / 10.5 / 0.4 | 1 / 3; 10967 / 20533; 2 / 2 |
|
||||
| `m` | (4, 4) | 2.75 (2.75–2.75) | 2.75 (2.57–2.78) | 66 (66–67) | 62 (61–63) | 12.3 / 23.1 / 23.9 | 24.4 (24.2–26.3) | 300 (294–300) | 200 | 58 / 58 | 0.97, 0.79 | 0.94 | 0 | 0 | 0.4 / 10.5 / 0.6 | 1 / 2; 10681 / 21535; 1 / 2 |
|
||||
| `lj` | (2, 2) | 2.25 (2.20–2.25) | 2.34 (2.34–2.37) | 76 (76–77) | 74 (73–74) | 16.5 / 30.7 / 32.0 | 32.3 (32.3–32.5) | 204 (204–206) | 152 | 57 / 57 | 0.96, 0.62 | 0.93 | 0 | 0 | 0.7 / 12.2 / 0.6 | 1 / 2; 15586 / 29734; 2 / 2 |
|
||||
| `lj` | (4, 4) | 2.15 (2.10–2.15) | 1.98 (1.95–2.17) | 77 (77–78) | 74 (73–74) | 19.4 / 37.3 / 38.7 | 39.5 (36.3–40.4) | 295 (276–305) | 188 | 57 / 57 | 0.98, 0.63 | 0.97 | 0 | 0 | 0.7 / 12.6 / 0.6 | 1 / 2; 17210 / 35123; 1 / 3 |
|
||||
| `lp` | (1, 1) | 0.85 (0.85–0.85) | 0.93 (0.93–0.93) | 34 (33–35) | 33 (32–34) | 19.1 / 34.9 / 36.2 | 36.5 (35.5–37.1) | 467 (466–470) | 136 | 367 / 368 | 0.88, 0.29 | 0.21 | 0 | 0 | 1.1 / 13.1 / 1.1 | 2 / 1104; 17896 / 33663; 1 / 2 |
|
||||
| `lp` | (2, 2) | 0.90 (0.90–0.90) | 0.96 (0.96–0.99) | 33 (32–34) | 32 (30–32) | 18.9 / 33.0 / 34.2 | 33.9 (33.9–35.0) | 834 (825–836) | 160 | 367 / 368 | 0.97, 0.30 | 0.97 | 0 | 0 | 1.1 / 12.3 / 1.0 | 1 / 2; 16790 / 30859; 2 / 2 |
|
||||
| `lp` | (2, 256) | 0.90 (0.90–0.90) | 0.96 (0.96–0.96) | 33 (32–34) | 0 (0–0) | 19.0 / 33.6 / 34.9 | 34.8 (33.5–35.1) | 831 (694–836) | 160 | 367 / 368 | 0.97, 0.30 | 0.98 | 0 | 0 | 1.1 / 12.2 / 1.1 | 2 / 2; 16922 / 31475; 2 / 2 |
|
||||
| `lp` | (4, 4) | 0.85 (0.50–0.85) | 0.36 (0.21–0.51) | 34 (34–40) | 30 (29–32) | 21.4 / 98.5 / 98.8 | 95.0 (65.8–186.4) | 1024 (1024–1024) | 206 | 367 / 368 | 0.98, 0.31 | 0.97 | 68 | 5 | 1.1 / 12.4 / 0.6 | 2 / 2; 9499 / 29496; 2 / 2 |
|
||||
|
||||
- **VmHWM у `lp` (4, 4) (206 МиБ) — только последняя жизнь контейнера:** его читают в конце ячейки, а контейнер за ячейку перезапускался до 4 раз. Это не наибольшее значение за ячейку и не сравнимо с соседними строками.
|
||||
- **Столбцы OOM и «Перезапуски»** — суммы трёх повторов. OOM — счётчик cgroup (63) плюс завершения процесса 1, подтверждённые событиями Docker (5). Завершения worker: на всех конфигурациях, кроме `lp` (4, 4) и `kill-worker`, — ни одного; прочих (`worker_die_other`) нет.
|
||||
- **Реплик в LB** наименьшее (`lb_up_min`) — 2 в каждой ячейке, `lb_down` не сработал. Лишних строк в базе (`unexpected_rows`) нет.
|
||||
- **Lag и `oldest_s`.** Пик возраста в окне `over` ограничен длиной окна; ожидание заданий, пришедших в это окно, больше: в матрице p95 до 39,2 с по медиане строки (`s` (4, 4)) и до 43,4 с в отдельной ячейке (`s-c4p4-r1`). На `m` и `lp` при (1, 1) p95 ожидания окна `before` — 413 и 1104 мс при единицах у остальных; вероятно, при одном месте конкуренции следующее задание ждёт текущее, отдельно это не мерилось.
|
||||
|
||||
**Блоки** (`evidence/queue/baseline4/summary.md`, «Ячейки по конфигурациям» и «Блоки»; столбец второго worker — `evidence/queue/baseline4/cells.csv`).
|
||||
|
||||
| Блок | Принято | 429 | Готовых/с: окно | восстановление | Пик | p95 до `ready`, с | Восст., с | Queue lag over, с | Второй worker |
|
||||
|---|---|---|---|---|---|---|---|---|---|
|
||||
| `gate-on`: 20/с, 25 с, предел 250 | 356 (356–357) | 175 (174–176) | 3.04 | 3.10 | 250 (250–250) | 80.2 | 80.5 (80.5–81.4) | 20.7 | — |
|
||||
| `gate-off`: то же, без предела | 532 (531–533) | 0 | 3.04 | 3.08 | 423 (422–424) | 130.6 | 137.5 (137.4–138.5) | 20.7 | — |
|
||||
| `accept`: `m`, 15/с, 45 с | 339 (333–342) | 368 (365–373) | 0.91 (0.80–0.98) | 3.00 (2.92–3.07) | 284 (279–286) | 91.7 | 89.3 (84.4–94.5) | 39.2 | — |
|
||||
| `w2-p2` | 192 (191–193) | 0 | 3.00 | 5.78 (5.53–5.85) | 100 (99–101) | 17.1 | 17.6 (17.4–18.4) | 12.3 | 48–49 заданий, 0,47–0,49 |
|
||||
| `w2-p256` | 192 (190–192) | 0 | 3.05 | 2.99 (2.99–3.05) | 100 (99–101) | 31.1 | 33.4 (32.6–34.4) | 12.1 | 0 заданий |
|
||||
| `kill-worker` | 233 (232–233) | 0 | 2.88 | 2.23 (2.21–2.26) | 128 (127–130) | 40.1 | 58.5 (58.4–58.5) | 19.8 | — |
|
||||
| `restart-broker` | 233 (232–233) | 0 | 2.56 | 3.02 (3.02–3.10) | 137 (137–138) | 42.9 | 45.6 (44.5–46.4) | 16.8 | — |
|
||||
|
||||
**Второй worker в обоих прочтениях** (`second_share` — порог H3, только разбор; `second_share_all` — буквально, все завершённые после запуска; `second_share_after` — само окно `after`).
|
||||
|
||||
| Блок, r1 / r2 / r3 | `second_share` | Заданий при разборе | `second_share_all` | Заданий всего | `second_share_after` |
|
||||
|---|---|---|---|---|---|
|
||||
| `w2-p2` | 0,471 / 0,471 / 0,485 | 48 / 48 / 49 | 0,475 / 0,470 / 0,491 | 56 / 55 / 57 | 0,500 / 0,467 / 0,533 |
|
||||
| `w2-p256` | 0 / 0 / 0 | 0 / 0 / 0 | 0,067 / 0,069 / 0,061 | 8 / 8 / 7 | 0,500 / 0,500 / 0,467 |
|
||||
|
||||
**Backpressure: где работа перестаёт приниматься и ускоряться.**
|
||||
|
||||
| Уровень | Значение | Что видит клиент | Что показала метка |
|
||||
|---|---|---|---|
|
||||
| Места загрузки реплики | 4 + 16, ожидание 5 с | 429, `Retry-After: 1` | `accept`: 206–234 отказа с 2,9–3,1 с окна, загрузка 202 p50 4,6–5,0 с |
|
||||
| Предел заданий | 250 | 429, `Retry-After: 5`, сразу | `gate-on`: плато ровно 250, первый отказ на ~14,7 с; `accept`: 131–167 отказов с 33,9–36,3 с, пик 279–286 |
|
||||
| Шлюз S3, общий с worker | 1 CPU | загрузка дольше | `accept`: CPU S3 1,00 в первые 30 с, готовых/с 0,80–0,98 вместо 2,92–3,07 после окна |
|
||||
| Outbox | копит | `queued` | не выше 6, relay не узкое место; при рестарте брокера — до 32 |
|
||||
| `max_published_backlog` | 1000 | `queued` | не достигнут ни в одной ячейке |
|
||||
| Предел памяти брокера | 400 МиБ | `queued` | не достигнут: память брокера по ячейкам 138–224 МиБ. Срабатывание проверяет `test_broker_memory_alarm`, отказы публикации в метке — только в `restart-broker` (2 прохода) |
|
||||
| `prefetch` | 2 | `queued` | неподтверждённых не больше `prefetch` во всех ячейках матрицы с (2, 2); при 256 — до 99 на `s` и до 34 на `lp`, а в очереди брокера 0 |
|
||||
| `concurrency` | 2 | `processing` | `processing` не больше конкуренции, кроме ячеек с гибелью worker: строки убитого ждут аренду (`kill-worker` — 4, `lp` (4, 4) — 8 и 16 при перезапусках, 4 без них); `w2-p2` — 4 на двух worker, у `w2-p256` пик 2: второй не получил заданий |
|
||||
| Лимит контейнера | 1 ГБ | дольше до `ready`, `failed` при исчерпании попыток | (2, 2) помещается на всех классах, `lp` (4, 4) — нет |
|
||||
|
||||
Клиент за входом видит только дольше не меняющееся `queued`, ни одного кода ошибки. Перестаёт приниматься на первых двух уровнях. Перестаёт ускоряться на CPU worker (конкуренция сверх двух), а на файлах у границы байтов — ещё на CPU S3, и там приём отнимает ресурс у обработки. Предел заданий останавливает это только на ~35-й секунде такой нагрузки: приоритета обработки над приёмом в S3 нет, это ограничение.
|
||||
|
||||
**Разбор H4: почему «нет».** Вердикт остаётся «нет»: условие записано раньше метки и нарушено; в основной метке — на одной ячейке, во всех четырёх метках — только на `m-c1p1`. Отношение p95 окна `over` к «пик / throughput окна `over`» (`evidence/queue/baseline4/cells.csv`). Правая колонка — та же величина с throughput окна `recovery`: это расчёт после метки, порога у него нет, и на вердикт он не влияет.
|
||||
|
||||
| Конфигурация | Записанное условие, r1 / r2 / r3 | С throughput `recovery`, r1 / r2 / r3 |
|
||||
|---|---|---|
|
||||
| `s-c2p2` | 0,944 / 0,953 / 0,943 | 0,939 / 0,952 / 0,937 |
|
||||
| `s-c2p256` | 0,934 / 0,918 / 0,946 | 0,960 / 0,963 / 0,932 |
|
||||
| `s-c4p4` | 1,057 / 1,047 / 0,998 | 0,979 / 0,955 / 0,937 |
|
||||
| `m-c1p1` | **0,780** / 0,902 / 0,851 | 0,951 / 0,931 / 0,936 |
|
||||
| `m-c2p2` | 0,938 / 0,946 / 0,867 | 0,929 / 0,931 / 0,946 |
|
||||
| `m-c4p4` | 1,018 / 0,963 / 0,962 | 0,952 / 0,962 / 0,973 |
|
||||
| `lj-c2p2` | 0,908 / 0,886 / 0,885 | 0,946 / 0,923 / 0,955 |
|
||||
| `lj-c4p4` | 1,034 / 0,975 / 1,041 | 0,962 / 0,983 / 0,957 |
|
||||
| `lp-c1p1` | 0,869 / 0,873 / 0,855 | 0,955 / 0,959 / 0,938 |
|
||||
| `lp-c2p2` | 0,888 / 0,901 / 0,926 | 0,948 / 0,988 / 0,987 |
|
||||
| `lp-c2p256` | 0,899 / 0,892 / 0,917 | 0,957 / 0,950 / 0,980 |
|
||||
|
||||
Всего 33 ячейки без `oom`: по записанному условию 0,780–1,057, одна ниже 0,8; с throughput `recovery` 0,923–0,988.
|
||||
|
||||
- **Проверено по метке.**
|
||||
- На `m` (1, 1) throughput окна `over` 2,05–2,30, окна `recovery` 2,37–2,53.
|
||||
- По `timeline.csv` это не разгон: готовых в секунду ровно ~2 все 20 с окна (`m-c1p1-r1`: первые 10 с — 2,0/с, последние — 2,1/с).
|
||||
- В окне `over` CPU worker 0,69–0,74 и S3 0,71, в `recovery` — 0,75–0,80 и 0,23–0,26.
|
||||
- Задание, пришедшее в конце окна, разбирается уже со скоростью `recovery`, а формула считает его по скорости `over`. Поэтому отношение занижено там, где эти скорости расходятся; сильнее всего — на `m` (1, 1).
|
||||
- **Предположение, метка его не меряет:** в окне `over` worker при (1, 1) медленнее, потому что ждёт S3, занятый приёмом. На это указывают CPU S3 и троттлинг worker 0,07–0,16, но времени ожидания S3 в метке нет.
|
||||
- **Вывод.** Причина в определении: в формулу гипотезы взят throughput окна, а разбирается очередь в основном после него. Это объяснение, а не отмена вердикта. Гипотеза в записанном виде не подтверждена. Данные показывают, что время до `ready` следует за очередью с отклонением до ~22 % вниз, и на классах с заметным S3 отношение почти всегда ниже единицы. На ячейках с `oom` формула неприменима (`lp-c4p4`: 2,461 / 2,291 / 1,409): там задержку определяют аренда и повторы.
|
||||
|
||||
**`lp` (4, 4): что произошло** (`evidence/queue/baseline4/cells.csv`).
|
||||
|
||||
| Повтор | Принято | `ready` | `failed` | `oom_kill` | Завершения процесса 1 (ядро) | Перезапуски | Событий `oom` | Заданий с повтором | Истёкших аренд | `processing`, пик | Восст., с | p95 `over`, с | CPU на задание, с |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| r1 | 62 | 62 | 0 | 16 | 1 | 1 | 9 | 16 | 4 | 8 | 95,04 | 98,45 | 1,393 |
|
||||
| r2 | 60 | 60 | 0 | 27 | 4 | 4 | 19 | 27 | 16 | 16 | 186,44 | 183,28 | 1,594 |
|
||||
| r3 | 62 | 62 | 0 | 25 | 0 | 0 | 11 | 13 | 0 | 4 | 65,82 | 56,36 | 1,464 |
|
||||
|
||||
- **Что значит.** Четыре процесса по 367 МиБ не помещаются в 1 ГБ: `memory.peak` 1024 МиБ, наибольшая `anon` 968–1008 МиБ. Ядро завершает процессы обработки, задания возвращаются на новую попытку и снова занимают память. Работа делается повторно: CPU на задание 1,39–1,59 с против 1,03 при (2, 2). С первого раза не обрабатываются 21–45 % заданий. Когда завершён процесс 1, взятые задания ждут аренду 70 с (пик `processing` 16 при конкуренции 4), и worker простаивает: CPU в окне `recovery` 0,56 / 0,35 / 0,87. Итог — throughput 0,36 вместо 0,96 и p95 98,5 с вместо 33,0 с, при том же лимите. После разбора система приходит в норму: p95 окна `after` 1,28–1,35 с.
|
||||
- **`failed`.** В основной метке 0, но это не значит, что риска нет: в `baseline` 2 задания (`retry_exhausted`, причина `render_killed`), в `baseline3` 4 задания (`retry_exhausted`, причина `lease_expired`) на `lp-c4p4-r1`. Клиент получил на них 202, а теперь видит `status: failed` и `error_code: retry_exhausted`. Варианта нет, новое сообщение с таким вложением получает 409. Сами они не восстановятся: возврат — `make replay ERROR_CODE=retry_exhausted APPLY=1`, оригинал лежит в staging до срока хранения (24 ч). Replay в метках не запускался, его проверяют `make failure_checks` и `driver.py defense-faults`. `lost` 0 означает только, что каждое принятое вложение названо состоянием, а не то, что каждое обработано.
|
||||
- **Расхождение с пробами.** Пробы ждали редких завершений процесса 1: один подтверждённый и один по тем же признакам из пяти прогонов, и в design записано «случайно». Метки показали другое: перезапуски в 11 ячейках из 12, суммы 16, 5, 18 и 5 за три повтора, до 10 в одной ячейке, и только `baseline4` r3 прошла без них. Причина расхождения разобрана только частично: на пробах стоял `restart: "no"`, первое завершение останавливало опыт, повторяться циклу было негде; метка идёт с `unless-stopped`, и цикл доходит до конца. Что перезапуск снова берёт дорогие задания и завершается по той же причине — предположение: повторные завершения в метке отдельно не прослежены. Частоту трёх повторов как оценку не использовать: она только показывает, что завершение не редкость.
|
||||
- **Причины перезапусков теперь измерены** (`docker events`): все 5 перезапусков основной метки — завершение ядром, `worker_die_other` 0. В `kill-worker` — `worker_die_command` 3 из 3, не `oom`. В `baseline` причина не проверялась: там каждый перезапуск прибавлялся к `oom_kill` косвенно, поэтому её столбец с остальными метками не сравнивается.
|
||||
|
||||
**Восстановление** (`evidence/queue/baseline4/cells.csv`). Без действий оператора незавершённых становится ноль во всех 57 ячейках, очередь брокера пуста, `not_recovered` нет. Эффект не дублируется: 0 вторых заданий и наборов вариантов; лишних строк в базе нет; копий relay 0. Скорость разбора при (2, 2) не падает: по медиане `recovery` не ниже окна `over` на `m`, `lj`, `lp`, на `s` 3,08 при 3,10 — в разбросе повторов. Время до `ready` возвращается (H6, условие по конфигурациям). Контрольный поток — H7; в `accept` наибольшие p95 — запись 23,8, чтение 14,0, скачивание 371,9 мс (порог H9 — 1 с), p95 скачивания в окне `over` — 313,8–371,9 мс против 6,8–7,3 на `s` при CPU S3 ~1,0, ошибок нет. Связь с занятым S3 — предположение: отдельно не мерилась.
|
||||
|
||||
Сценарии «Работа копится там, где положено» и «Бэклог уходит за измеренное время» уточнены по факту этой метки (design, «Уточнения apply», п. 14; вердикты не менялись): `processing` — на один worker, кроме строк завершённого процесса, а условие о скорости — только для настройки, которая помещается в лимит памяти, без завершений worker и с конкуренцией до двух мест на CPU. Падение на прочих, окно восстановления при окне перегрузки: `lp` (4, 4) 0,36 при 0,85, `kill-worker` 2,23 при 2,88 (последние две строки ждут аренду), `s` (4, 4) 2,46 (2,32–2,49) при 2,65 (2,50–2,70).
|
||||
|
||||
**Компромисс latency и ресурсов (вывод из таблиц выше).**
|
||||
|
||||
- **Память без скорости.** По правилу шума решения 11 (разбросы не пересекаются, разница медиан больше наибольшего разброса):
|
||||
- (4, 4) против (2, 2) — эффект в худшую сторону на `s` и `lj`: throughput ниже на 20 и 15 %; на `m` 2,75 и 2,85 — в пределах шума. Память выше на 43, 45 и 43 % (`s`, `lj`, `m`). На `lp` — потеря обработки.
|
||||
- (1, 1) против (2, 2) на `lp` — в пределах шума по скорости (0,93 и 0,96), памяти 467 МиБ вместо 834: выигрыш 44 %.
|
||||
- (1, 1) на `m` — эффект: на 12 % медленнее (2,50 и 2,85), памяти 154 МиБ вместо 210, потому что worker при одном задании ещё ждёт S3 (CPU 0,73).
|
||||
- **CPU, а не конкуренция, поднимает потолок.** Второй worker на `s`: 5,78 готовых/с вместо 3,08, восстановление 17,6 с вместо 32,5, ценой ещё 1 CPU и 1 ГБ лимита. Формула масштабирования этим не доказана (ограничения ниже).
|
||||
- **Большой prefetch ничего не даёт и прячет очередь:** та же скорость на `s` и `lp`, брокер показывает 0 готовых, второй worker простаивает, восстановление 33,4 с вместо 17,6.
|
||||
- **Цена отказа клиенту.** Предел обменивает принятые файлы на срок: 175 загрузок из ~532 получают 429, зато p95 до `ready` 80,2 с вместо 130,6. Цена проверки в окне `before`: p50 16 против 16 мс при разбросе 15–19 мс.
|
||||
- **Формула подбора** на двух точках сходится. Память: база ≈ 467 − 368 ≈ 99 МиБ на (1, 1), прогноз для (2, 2) — 99 + 2 × 368 = 835 МиБ при измеренных 834; `(1024 − 99) / 368 ≈ 2,5`, то есть 2 помещается, 4 нет; 3 в метке нет. CPU: при (1, 1) на `m` 0,73 ядра, значит, конкуренция 2 ещё даёт прирост, что и видно; при (2, 2) уже 0,96. Это согласие с данными, а не доказательство: опытов на формулу метка не ставила.
|
||||
|
||||
**Рекомендация и значения по умолчанию** (`evidence/queue/baseline4/summary.md`, «Рекомендация»). Правило решения 12 даёт конкуренцию 2, prefetch 2, как и в трёх других метках. (1, 1) не кандидат: на `m` throughput ниже 90 % лучшей, и снята не на всех классах (нет `lj`, `s`). (4, 4) не кандидат: сводка называет первую найденную причину — на `lj` throughput 1,98 / 2,34 ≈ 0,85 при пороге 0,90, а на `lp` есть и `oom`. **(2, 256) не кандидат: снята не на всех классах (нет `lj`, `m`).** На снятых `s` и `lp` условия она проходит, но условие «на всех классах» для неё не проверено; сверх того `prefetch` больше конкуренции ничего не добавляет (H3). `worker_crash` в метке нет, поэтому решение основной сессии о такой настройке не понадобилось. **Значения оставлены:** рекомендация совпала с (2, 2), поэтому условие смены не наступило и отдельного commit нет. Условия рекомендации: 1 CPU и 1 ГБ на worker. При другом лимите пересчитать по формуле выше; для потока только больших PNG (1, 1) экономит память без потери скорости, но это другая установка, а не значение по умолчанию.
|
||||
|
||||
**Предел 250 по измеренному потолку.** Обоснование решения 2 опиралось на пробу: потолок `lp` 0,92/с и ожидание ~270 с при границе 300 с (`[relay] republish_after_seconds`). Метка: потолок `lp` при (2, 2) — 0,96/с (`recovery`), 250 / 0,96 ≈ 260 с. **Совпало только для измеренных классов:** ожидание меньше 300 с, предел менять незачем. Запас меньше, чем кажется: с окном приёма (0,90/с) ~278 с, с превышением (граница H5 290, измерено до 286) ~302 с при потолке `recovery` и ~322 с при потолке окна, то есть за границей. Выход за границу на (2, 2) копий не даёт: выданное сразу взято, а пока в брокере есть готовые, relay не публикует заново. При (2, 256) задания старше порога получат копию, эффект нулевой по пробе (188 копий на 150 заданий, лишнего эффекта 0). В метке копий 0, но `lp` у предела не снимался.
|
||||
|
||||
| Класс | Потолок (2, 2), готовых/с | Ожидание у предела 250, с | Как получено |
|
||||
|---|---|---|---|
|
||||
| `s` | 3,08 | ~81 | измерено: `gate-on` p95 80,2 с, восстановление 80,5 с |
|
||||
| `m` | 2,85 | ~88 | расчёт; `accept` при пике 284 измерил p95 91,7 с |
|
||||
| `lj` | 2,34 | ~107 | расчёт, у предела не снималось |
|
||||
| `lp` | 0,96 | ~260 | расчёт, у предела не снималось |
|
||||
|
||||
Staging при заполненном пределе: 250 × 10 458 117 байт ≈ 2,4 ГиБ плюс превышение — расчёт, на `lp` у предела не снималось. Отставание очистки: наибольшее число `ready` с необнулённым staging за конфигурацию 49–196 (`timeline.csv`), очищается следующими проходами уборщика (60 с). Ограничение счёта, а не байтов названо ниже.
|
||||
|
||||
**Ограничения метода.**
|
||||
|
||||
- Один хост и ВМ Docker Desktop (arm64, 12 CPU, 7,75 ГиБ): лимит 1 CPU — квота CFS, а не отдельное ядро; генератор и посторонние контейнеры на той же ВМ, доля их CPU видна по `vm`.
|
||||
- Один worker; второй — только в своём блоке и на классе, где S3 не узкое место (CPU S3 ~0,08): общая формула масштабирования не утверждается.
|
||||
- Выгрузка хоста: основная метка чистая, но две другие сняты с ней, причина не установлена (раздел «Выгрузка хоста» выше).
|
||||
- Ячейка — один класс, один файл на все загрузки: смесь размеров и разброс содержимого не мерятся.
|
||||
- Окна короткие, 20–45 с перегрузки: многочасовая перегрузка, autovacuum под длинным оборотом и рост WAL не мерятся, проба — только 90 с оборота.
|
||||
- Открытая модель без повторов: поток клиентов, послушно повторяющих после `Retry-After`, не мерится; отказ считается отказом.
|
||||
- PostgreSQL, relay и брокер в этих интенсивностях не упираются: их предел трек не определяет; `max_published_backlog` и предел памяти брокера нагрузкой не достигаются. Метка это подтвердила (таблица backpressure).
|
||||
- Одна нода S3, staging и конечный префикс на одном диске ВМ; ячейки — на свежем volume, поэтому рост памяти S3 с накопленными объектами не мерится (проба на старом стенде — `KNOWN_ISSUES.md`).
|
||||
- Выборки `before` и `after` малы на `lp`: повторы сводятся, p99 у малых выборок — только справочно.
|
||||
- **Поправлено по меткам.** В решении 12 стояло: завершение процесса 1 ядром при (4, 4) на `lp` случайно, один подтверждённый случай и один по тем же признакам из пяти прогонов. Метки показали его в 11 ячейках из 12: 16, 5, 18 и 5 раз за три повтора. Частота из трёх повторов по-прежнему не следует, но «редко» неверно. «Работа не теряется» верно только с оговоркой: в `baseline` 2 задания и в `baseline3` 4 задания ушли в `failed` и ждали бы `make replay`, в основной — ни одного.
|
||||
- **Повторы `lp` (4, 4) не дают устойчивой оценки:** три повтора этой конфигурации плавают сильнее порогов, отсюда и расхождение H2 между метками.
|
||||
- **Журналы контейнеров в метку не копируются:** по отдельным заданиям выводы проверить нельзя, разбор H2 опирается на медианы ячеек и посекундную шкалу.
|
||||
- **`duration_p50_ms` и столбцы `queue_wait_p*_ms` на ячейку считаются вместе с разогревом** (12 файлов `s`): одинаково во всех метках и настройках, но на `lp` это другой класс в той же медиане.
|
||||
- Предел считает задания, а не байты: `lp` в 3 раза дороже `s` при том же счёте; предел один на стенд, справедливости между пользователями нет.
|
||||
|
||||
### Отказы
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
| Worker остановлен, рестарт API и хранилищ, worker запущен | принятая работа дожидается | `queued` → `ready`, те же байты (`defense.md`) | потерь нет |
|
||||
| Брокер остановлен при загрузке | 202, намерение ждёт, остальное API работает | так (`test_upload_with_broker_stopped`, `test_readiness_without_broker_and_worker`) | после возврата relay публикует, потерь нет |
|
||||
| Брокер заморожен | 202 без ожидания брокера | так (`test_upload_with_broker_paused`) | потерь нет |
|
||||
| Relay убит до публикации | 202, сообщения нет, следующий запуск публикует | так (`defense-faults.md`, `test_relay_killed_before_publish`) | потерь нет, ручного задания нет |
|
||||
| Relay убит после confirm до отметки | дубль сообщения без второго эффекта | так (`defense-faults.md`, `test_relay_killed_after_confirm`) | `attempt` 1, потерь нет |
|
||||
| KILL брокера и `up --force-recreate` с volume | подтверждённые сообщения на месте | так (`test_broker_kill_keeps_confirmed`, `test_broker_recreated`) | потерь нет |
|
||||
| Сообщение потеряно вместе с очередью | relay публикует снова, при непустой очереди копий нет | так (`test_lost_message_republished`, `test_no_copies_while_queue_has_messages`) | через `republish_after_seconds`, 300 с |
|
||||
| Worker убит посреди обработки или после записи объектов | следующая попытка по аренде, те же ключи | так (`defense-faults.md`, `test_worker_killed_during_processing`) | 70 с на рабочем стенде, потерь нет, попытка посчитана |
|
||||
| Worker убит после COMMIT до ack | повторная доставка, no-op | так (`defense-faults.md`, `test_crash_after_commit_before_ack`) | сразу после запуска, потерь нет |
|
||||
| Worker заморожен дольше аренды | новая попытка, прежняя не фиксирует ни при живой новой, ни после её итога | так (`test_hung_worker_lease_fencing`, `test_hung_worker_thawed_after_ready`) | по аренде, дублей эффекта нет |
|
||||
| Дорогой файл в пределах контракта | процесс обработки прерван по CPU, worker цел | так (`test_limit_cpu_scan_bomb`) | 15 с CPU на рабочем стенде, `invalid_image` |
|
||||
| S3 недоступен при обработке | повторы с backoff под одним `job_id`, затем `ready` или `retry_exhausted` | так (`test_transient_error_retried`, `test_attempts_exhausted`) | рабочий стенд выдерживает сумму пауз 37,5–75 с и сроки попыток (расчёт по настройкам, design, решение 4; тесты — на коротких сроках стенда отказов); дольше — `failed`, возврат `make replay` |
|
||||
| S3 недоступен при очистке staging | проход прерван, сообщения не ждут | так (`test_staging_cleanup_survives_outage`) | следующий проход повторяет |
|
||||
| PostgreSQL недоступен при обработке | задание ждёт, попытка не считается | так (`test_database_outage_during_processing`) | потерь нет |
|
||||
| Сообщение не по схеме | отброшено, `error` без содержимого | так (`test_malformed_message_dropped`, `logs.md`) | следующие задания идут |
|
||||
| Реплика API остановлена или убита | запись через другую | `failed_attempts` 0 (`test-failover.md`) | 1,72 и 0,85 с, потерь нет |
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
**Ограничения этого уровня, названные спеками:**
|
||||
|
||||
- **Отказ S3 дольше бюджета.** Сумма пауз 37,5–75 с и сроки попыток: рестарт S3 (~25 с) укладывается, более долгий отказ переводит взятые задания в `failed` `retry_exhausted`. Лечит `make replay ERROR_CODE=retry_exhausted APPLY=1`: это явный шаг оператора, а не автоматика.
|
||||
- **Восстановление после KILL по аренде.** После KILL worker следующая попытка начинается по истечении аренды, до 70 с (наблюдали 70 с). Пульс отвергнут (раздел «Ответы на вопросы защиты»). Повторная доставка уже готовой работы — сразу.
|
||||
- **Дубли сообщений.** Неизвестный исход публикации, crash до отметки и потерянные сообщения дают дубли: at least once. Каждый дубль — `SELECT … FOR UPDATE` и ack, эффект защищён ключом и fencing. Сообщения, которые держит большой prefetch дольше `republish_after_seconds`, брокер готовыми не считает: они могут получить копию.
|
||||
- **Объект, дописанный прежней попыткой.** Фиксацию fencing прежней попытке запрещает, но замороженный процесс после разморозки может записать объект теми же байтами: ключ тот же, версия декодера та же.
|
||||
- **Профиль ICC отбрасывается.** Учебные данные — sRGB; изображение с другим профилем изменит цвет в вариантах.
|
||||
- **Лимит памяти на macOS.** `setrlimit(RLIMIT_AS)` на хосте macOS отказывает, консольный worker это пишет в журнал (`render_memory_limit_applied`); на стенде Linux лимит действует.
|
||||
- **Цена процесса на задание.** Метка `baseline4`: CPU worker на задание при (2, 2) — 0,32 с на `s`, 0,33 на `m`, 0,42 на `lj`, 1,03 на `lp` (`evidence/queue/baseline4/cells.csv`; в `baseline` это число занижено, см. выше). Долю запуска процесса метка не выделяет, проба — ~100 мс на маленьком файле. Forkserver (9 мс) отвергнут сейчас: секреты родителя в окружении и свой жизненный цикл. Граница — один модуль.
|
||||
- **Изоляция секретов процесса обработки неполная.** В его окружении секретов нет, но он идёт под тем же UID, что процесс 1 worker, и может прочитать `/proc/1/environ` с ключами S3 и паролями PostgreSQL и брокера. От случайной утечки это защищает, после эксплойта декодера — нет. Предложение — `PR_SET_DUMPABLE=0` в процессе worker, вопрос преподавателю (`QUESTIONS.md`, `## pipeline-reliability`).
|
||||
- **Дорогие файлы занимают worker.** Предел считает задания, а не байты и CPU. Измерен файл на границе байтов и пикселей: ~1 с CPU, поток таких файлов при 250 незавершённых ждёт ~260 с. **Худший случай не измерен:** scan bomb в пределах контракта стоит лимит процесса, 15 с CPU, расчётом 250 × 15 с ≈ 1 час разбора и копии от relay при таком ожидании. Обоснование предела «ожидание меньше 300 с» верно только для измеренных классов, для этого файла — нет. Защиты, кроме лимита на файл, нет.
|
||||
- **Завершение процесса 1 worker ядром.** Конкуренция, которая не помещается в лимит памяти, стоит не только повторов: `lp` (4, 4) — 5 перезапусков за три прогона в основной метке, 16 и 18 в других, задания ждут аренду 70 с, в `baseline` и `baseline3` 2 и 4 задания ушли в `failed` `retry_exhausted`. Значение по умолчанию на всех классах помещается; правило подбора — раздел «Очередь под перегрузкой».
|
||||
- **Приём у границы байтов отнимает S3 у worker.** Готовых/с 0,80–0,98 вместо 2,92–3,07, пока S3 занят приёмом. Приоритета обработки нет, предел останавливает это на ~35-й секунде такой нагрузки.
|
||||
- **Предел мягкий и один на стенд.** Превышение — загрузки в полёте (измерено до 286 при пределе 250), справедливости между пользователями и чатами нет.
|
||||
- **Сверка не проверяет объекты вариантов.** Наличие и размер объектов вариантов сверка не проверяет: вариант без объекта даёт 500 на скачивание и `error` в журнале (`test_missing_variant`). Объекты staging она с этого уровня видит (`orphan_staging`).
|
||||
- **Удаление очереди при работающем worker.** Потребитель этого не замечает: relay создаст очередь заново, worker нужно перезапустить. На стенде такого нет, кроме уборки своей очереди после остановки своего worker.
|
||||
- **Старые `ready` без `crop` и `optimized`.** Вложения уровня 3 остаются с одним thumbnail, скачивание этих вариантов — 404; replay `ready` запрещён намеренно. Показано в `evidence/migrations/pipeline-reliability.md`.
|
||||
- **Staging и конечный префикс на одном сервере S3.** Устойчивость staging — устойчивость этого сервера и bucket: отказ диска или ВМ теряет и то, и другое.
|
||||
- **Отставание очистки staging.** Объект живёт до следующего прохода уборщика (60 с). Метка `baseline4`: наибольший долг по конфигурациям 49–196 вложений, разбирается следующими проходами; многочасовая нагрузка не мерилась. S3 на долго живущем стенде — `KNOWN_ISSUES.md`.
|
||||
- **Смесь версий при замене на уровень 3 и новые статусы.** С версии лабы 4: прежняя реплика отвечает 201 `ready` и даёт 500 на чтении строки нового статуса (`evidence/migrations/async-attachments.md`). Для загрузок реплик прежней версии, переживших grace, защита пометкой уборщика не гарантирована: они пометку не проверяют. Запись — `KNOWN_ISSUES.md`. Порядок обновления с уровня 3 — раздел «Разрыв COMMIT и publish и окна отказа».
|
||||
- **Прерванное остановкой задание.** Задание, прерванное `docker stop` дольше `graceful_shutdown_seconds` (8 с), считается начатой попыткой и продолжается по аренде: release на пути отмены ненадёжен. Замер на двух дорогих JPEG: 8,15 с, при замороженных PostgreSQL и брокере 9,18 с (`evidence/worker/process.md`). Худший случай остановки 8 + 0,5 + 0,5 + 0,5 = 9,5 с < 10 с.
|
||||
- **Искажения данных скана JPEG.** Структурная проверка и libjpeg байт внутри данных скана ошибкой не считают: такое вложение становится `ready`, а варианты будут с мусором. Проверка не декодирует пиксели при приёме намеренно.
|
||||
- **Цена соединения на шаг.** Двухшаговая JSON-ручка выдаёт соединение дважды: под перегрузкой запрос встаёт в очередь пула дважды, запас на ожидание у него около половины общего срока. Отказ БД при откате успешного чтения — 503, окно в один обмен: откат теперь до ответа. Отмена задачи сбрасывает соединение вместо возврата в пул (design change `unit-of-work`, Risks).
|
||||
- **Подмена `do_ping`.** Дешёвая проверка соединения опирается на внутренние имена адаптера asyncpg в SQLAlchemy: закреплён `<2.2`, смену ловят тесты `test_ping_*` в `make service_test_db`. Прерванная проверка не оставляет сессий сверх пула только потому, что `BoundedCloseConnection` сам обрывает внутренний `_transport` asyncpg (`design.md`, уточнение 17): смену имени ловит `test_no_sessions_over_pool_after_freeze`.
|
||||
- **Фейки не проверяют блокировки.** Быстрый тест зелёный при сломанном `SKIP LOCKED`: блокировки и конкуренцию доказывает только `make failure_checks` (таблица решения 11 design).
|
||||
- **Метаданные и скачивание вложения без общего срока.** Вход и блок — до 12 с при `timeout server` 10 с: клиент получит 504 от LB вместо 503. Дефект прежний, запись — `KNOWN_ISSUES.md`.
|
||||
- **Цепочка LB.** Брокера в пути нет, поэтому самым долгим снова стал путь компенсации: после тела `проверка ~4 + tx1 6 + PUT 5 + tx2 6 ≈ 21 с`, с DELETE компенсации `+ 5 ≈ 26 с` < `timeout server` 30 с. Наибольшая длительность живой загрузки `U = 17 + 30 + 26 ≈ 73 с` < дренаж замены 90 с: до тела `2 × request_timeout_seconds + wait_timeout_seconds` = 17 с; тело — `[uploads] body_timeout_seconds` 30 с.
|
||||
|
||||
**Другие ограничения:**
|
||||
|
||||
- CHECK статуса, `ck_attachments_error_code_failed` и `ck_attachment_jobs_attempt_base` остаются `NOT VALID`: `VALIDATE` держал бы блокировку на время просмотра таблицы, а прежние строки условиям отвечают.
|
||||
- Один пользователь брокера на relay и worker; разделение прав — лаба 7.
|
||||
- Предел памяти брокера 400 МиБ блокирует публикацию: relay получает отказ по сроку 2 с, загрузка по-прежнему 202, намерения копятся в PostgreSQL (`test_broker_memory_alarm`), пока не достигнут предел незавершённых заданий.
|
||||
- Ранний ответ при загрузке: `urllib` напрямую к реплике на большом теле теряет ранний ответ; через LB и с httpx или curl — получает.
|
||||
- Keyset-пагинация: порядок задаёт `(created_at, id)`; `created_at` назначает сервер, при расхождении часов реплик порядок вставки возможен только по этому ключу.
|
||||
|
||||
**Следующие шаги.** Вне трека и не сделано: приоритет обработки над приёмом в S3, предел по байтам и на пользователя, forkserver, рост памяти S3 с накопленными объектами. Подтверждено замером только то, что есть в разделах выше.
|
||||
|
||||
## Источники, библиотеки и использование ИИ
|
||||
|
||||
**Документация:** [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability), [Publisher confirms and acknowledgements](https://www.rabbitmq.com/docs/confirms) (из `README.md` задания); aio-pika — <https://docs.aio-pika.com/>; Pillow — <https://pillow.readthedocs.io/> (`Image.draft`, `resize` с `reducing_gap`, EXIF); PostgreSQL 18 — `NOT VALID`, `FOR UPDATE`, `lock_timeout`; Harry Percival, Bob Gregory, «Architecture Patterns with Python» (Cosmic Python), главы 2 и 6 — Repository и Unit of Work; источники лаб 2–4 — в их отчётах. Поведение брокера и Pillow проверено пробами: таблица «Пробы» в `openspec/changes/archive/2026-10-31-async-attachments/design.md`.
|
||||
|
||||
**Библиотеки:** новые — aio-pika 10.2.1, Pillow 13.0.0 (из dev-группы в основную); уровень 4 новых не добавил: WebP уже есть в Pillow (libwebp 1.6.0); единица работы — тоже: `async def` тесты запускает плагин `anyio`, он уже в зависимостях. Остальное — `uv.lock`. Пробы уровня 4 — таблица «Пробы» `openspec/changes/archive/2026-10-31-pipeline-reliability/design.md`.
|
||||
|
||||
**ИИ.** Код, тесты, инструменты, спеки, снятие доказательств и этот отчёт сделаны с помощью Claude Code (Anthropic) по циклу OpenSpec: предложение, реализация, проверка, правки по проверке, архивация; каждую стадию вёл отдельный агент, основная сессия принимала результат и коммитила. Перенос на единицу работы (`unit-of-work`, по указанию пользователя) — так же, проверен наборами `student-tests/` и `make failure_checks` без их правок и временными регрессиями; очередь под перегрузкой (`track1-queue-overload`) — гипотезы и правило рекомендации записаны до метки, метки сняты командой `make bench_queue`; метку `baseline` отменили ошибки инструмента, найденные проверкой, `baseline2` и `baseline3` не стали основными из-за выгрузки хоста в swap, основная — `baseline4` (`QUESTIONS.md`). Выбор оценки, трека, брокера и единицы работы — решения автора; решения и отвергнутые варианты — `design.md`, принятые без пользователя — `QUESTIONS.md`. Каждый файл `evidence/` снят командой из его шапки на стенде этой лабы, а не сгенерирован; числа в отчёте перенесены из выводов команд на названном commit.
|
||||
|
||||
+13
@@ -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
@@ -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:]))
|
||||
@@ -0,0 +1,172 @@
|
||||
# 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}
|
||||
|
||||
# S3 (лаба 4) запускает только профиль uploads (design change
|
||||
# upload-memory, решение 10): образ, аргументы сервера и лимиты рабочего
|
||||
# стенда, swap = память; bucket и пользователей создаёт тот же
|
||||
# s3-bootstrap. Профили лаб 2–3 его не запускают: старт стенда
|
||||
# перечисляет сервисы, а реплики API поднимает с --no-deps (design change
|
||||
# s3-storage, решение 9). Без порта хоста, без перезапуска, под своим
|
||||
# именем
|
||||
s3:
|
||||
container_name: mtusi-bench-s3
|
||||
restart: "no"
|
||||
ports: !reset []
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: ${BENCH_S3_CPUS:?run make bench}
|
||||
memory: ${BENCH_S3_MEMORY:?run make bench}
|
||||
memswap_limit: ${BENCH_S3_MEMORY:?run make bench}
|
||||
|
||||
# уборщик незавершённых загрузок (design change upload-consistency,
|
||||
# решение 9) описан, как s3; сервис не запускается: старт стенда
|
||||
# перечисляет сервисы, реплики — с --no-deps. Профиль сверки (change
|
||||
# track2-reconcile-cost, решения 1 и 3) запускает его разовыми проходами
|
||||
# `docker compose run --name mtusi-bench-reconcile-<n> cleaner reconcile`.
|
||||
# Образ стенда, без config.toml рабочего стенда, без перезапуска и без
|
||||
# плановой сверки bucket и БД; лимиты BENCH_CLEANER_* без swap — рабочего
|
||||
# стенда, в управляемом опыте — CPU варианта
|
||||
cleaner:
|
||||
container_name: mtusi-bench-cleaner
|
||||
image: mtusi-messenger:bench
|
||||
restart: "no"
|
||||
volumes: !reset []
|
||||
environment:
|
||||
RECONCILER__INTERVAL_SECONDS: "0"
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: ${BENCH_CLEANER_CPUS:?run make bench}
|
||||
memory: ${BENCH_CLEANER_MEMORY:?run make bench}
|
||||
memswap_limit: ${BENCH_CLEANER_MEMORY:?run make bench}
|
||||
|
||||
# брокер описан и не запускается ни одним профилем (design change
|
||||
# pipeline-reliability, решение 16): реплика к нему не обращается, задания
|
||||
# ждут в PostgreSQL. Образ, rabbitmq.conf и лимиты рабочего стенда, swap =
|
||||
# память; без порта хоста, без перезапуска, под своим именем
|
||||
rabbitmq:
|
||||
container_name: mtusi-bench-rabbitmq
|
||||
restart: "no"
|
||||
ports: !reset []
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: ${BENCH_BROKER_CPUS:?run make bench}
|
||||
memory: ${BENCH_BROKER_MEMORY:?run make bench}
|
||||
memswap_limit: ${BENCH_BROKER_MEMORY:?run make bench}
|
||||
|
||||
# relay и worker описаны и не запускаются ни одним профилем: стенд меряет
|
||||
# реплику, а не обработку. Образ стенда, без config.toml рабочего стенда;
|
||||
# лимиты BENCH_RELAY_* и BENCH_WORKER_* compose требует при разборе
|
||||
relay:
|
||||
container_name: mtusi-bench-relay
|
||||
image: mtusi-messenger:bench
|
||||
restart: "no"
|
||||
volumes: !reset []
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: ${BENCH_RELAY_CPUS:?run make bench}
|
||||
memory: ${BENCH_RELAY_MEMORY:?run make bench}
|
||||
memswap_limit: ${BENCH_RELAY_MEMORY:?run make bench}
|
||||
|
||||
worker:
|
||||
container_name: mtusi-bench-worker
|
||||
image: mtusi-messenger:bench
|
||||
restart: "no"
|
||||
volumes: !reset []
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: ${BENCH_WORKER_CPUS:?run make bench}
|
||||
memory: ${BENCH_WORKER_MEMORY:?run make bench}
|
||||
memswap_limit: ${BENCH_WORKER_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
|
||||
@@ -0,0 +1,21 @@
|
||||
# Подстановки 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
|
||||
# S3 запускает только профиль uploads (лаба 4), профили лаб 2–3 — нет;
|
||||
# секреты S3 генерирует run.py
|
||||
S3_HOST=s3
|
||||
S3_PORT=8333
|
||||
S3__BUCKET=bench
|
||||
# брокер, relay и worker описаны и не запускаются (лаба 5); compose требует эти
|
||||
# значения при разборе, пароль брокера генерирует run.py
|
||||
RABBITMQ_HOST=rabbitmq
|
||||
RABBITMQ_PORT=5672
|
||||
RABBITMQ_DEFAULT_USER=bench
|
||||
APP__PORT=8080
|
||||
@@ -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:]))
|
||||
@@ -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)
|
||||
@@ -0,0 +1,116 @@
|
||||
"""Загрузчик объектов профиля сверки: прямой PUT в S3 стенда мимо API.
|
||||
|
||||
Работает только в контейнере `mtusi-bench-fill` на образе стенда
|
||||
(`mtusi-messenger:bench`): botocore образа, `src` не импортируется, каталог
|
||||
`bench/` смонтирован только на чтение, номера, ключи и содержимое объектов
|
||||
— генератор набора `bench/reconcile.py` (design change
|
||||
`track2-reconcile-cost`, решение 3). Ключи пользователя API — окружение
|
||||
контейнера (`S3__ACCESS_KEY_ID`, `S3__SECRET_ACCESS_KEY`: `docker run -e
|
||||
<имя>` без значения в argv); в вывод они не попадают.
|
||||
|
||||
Объекты — номера диапазона [--start, --end), у которых по модели набора
|
||||
есть объект; несколько процессов по нескольку потоков, у каждого процесса
|
||||
свой клиент. Вывод — одна строка `fill: <объектов> objects, <PUT/с>
|
||||
put/s, <с> s`; ошибка любого PUT — код 1.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
from concurrent.futures import ThreadPoolExecutor
|
||||
from multiprocessing import Pool
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
|
||||
import reconcile # noqa: E402
|
||||
|
||||
KEY_ENV = ("S3__ACCESS_KEY_ID", "S3__SECRET_ACCESS_KEY")
|
||||
|
||||
|
||||
def client(endpoint: str, threads: int) -> Any:
|
||||
import botocore.session
|
||||
from botocore.config import Config
|
||||
|
||||
session = botocore.session.get_session()
|
||||
return session.create_client(
|
||||
"s3",
|
||||
endpoint_url=endpoint,
|
||||
region_name="us-east-1",
|
||||
aws_access_key_id=os.environ[KEY_ENV[0]],
|
||||
aws_secret_access_key=os.environ[KEY_ENV[1]],
|
||||
config=Config(
|
||||
s3={"addressing_style": "path"},
|
||||
retries={"total_max_attempts": 3},
|
||||
max_pool_connections=threads,
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def put_chunk(job: tuple[dict[str, Any], list[int]]) -> int:
|
||||
"""Один процесс: свой клиент, потоки по номерам; число записанных."""
|
||||
args, indices = job
|
||||
s3 = client(args["endpoint"], args["threads"])
|
||||
|
||||
def put(index: int) -> None:
|
||||
attachment_id = reconcile.object_id(args["seed"], index)
|
||||
s3.put_object(
|
||||
Bucket=args["bucket"],
|
||||
Key=reconcile.object_key(args["namespace"], attachment_id),
|
||||
Body=reconcile.content(args["seed"], index, args["size"]),
|
||||
ContentType=reconcile.CONTENT_TYPE,
|
||||
)
|
||||
|
||||
with ThreadPoolExecutor(max_workers=args["threads"]) as pool:
|
||||
for _ in pool.map(put, indices):
|
||||
pass
|
||||
return len(indices)
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
parser.add_argument("--endpoint", required=True)
|
||||
parser.add_argument("--bucket", required=True)
|
||||
parser.add_argument("--namespace", required=True)
|
||||
parser.add_argument("--seed", type=int, required=True)
|
||||
parser.add_argument("--start", type=int, required=True)
|
||||
parser.add_argument("--end", type=int, required=True)
|
||||
parser.add_argument("--size", type=int, required=True)
|
||||
parser.add_argument("--force", choices=(reconcile.FORCE_OK,))
|
||||
parser.add_argument("--processes", type=int, default=3)
|
||||
parser.add_argument("--threads", type=int, default=24)
|
||||
args = parser.parse_args(argv)
|
||||
if not Path("/.dockerenv").exists():
|
||||
print("fill: run only in the bench container", flush=True)
|
||||
return 2
|
||||
if any(not os.environ.get(name) for name in KEY_ENV):
|
||||
print(f"fill: {' and '.join(KEY_ENV)} are required", flush=True)
|
||||
return 2
|
||||
indices = reconcile.object_indices(args.start, args.end, args.force)
|
||||
parts = [indices[i :: args.processes] for i in range(args.processes)]
|
||||
shared = {
|
||||
key: getattr(args, key)
|
||||
for key in ("endpoint", "bucket", "namespace", "seed", "size")
|
||||
}
|
||||
shared["threads"] = args.threads
|
||||
started = time.monotonic()
|
||||
try:
|
||||
with Pool(args.processes) as pool:
|
||||
done = sum(pool.map(put_chunk, [(shared, p) for p in parts if p]))
|
||||
except Exception as exc:
|
||||
# без текста исключения botocore: в нём может быть адрес и заголовки
|
||||
print(f"fill: put failed ({type(exc).__name__})", flush=True)
|
||||
return 1
|
||||
seconds = time.monotonic() - started
|
||||
print(
|
||||
f"fill: {done} objects, {done / seconds if seconds else 0:.0f} "
|
||||
f"put/s, {seconds:.1f} s",
|
||||
flush=True,
|
||||
)
|
||||
return 0 if done == len(indices) else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
@@ -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) };
|
||||
}
|
||||
@@ -0,0 +1,138 @@
|
||||
// Фоновая нагрузка профиля сверки (design change track2-reconcile-cost,
|
||||
// решение 10): открытая модель, три сценария constant-arrival-rate через
|
||||
// LB — скачивания оригиналов вложений набора (`/work/downloads.json` от
|
||||
// run.py; читатель фикстуры — владелец и участник чата набора), запись
|
||||
// сообщений в чат записи и чтение его первой страницы истории. Каждый
|
||||
// запрос — строка «bg,<d|w|r>,<отправка мс>,<длительность мс>,<статус>» в
|
||||
// файл консоли k6; run.py делит их на окна до, во время и после прохода
|
||||
// сверки и сверяет число строк со счётчиком bg_lines_<сценарий> и с
|
||||
// итерациями сценариев: снизу, а сверху — с запасом на VU. Оркестратор
|
||||
// останавливает прогон сигналом SIGINT, когда блок проходов закончен:
|
||||
// итог (handleSummary) k6 пишет и тогда.
|
||||
import exec from "k6/execution";
|
||||
import http from "k6/http";
|
||||
import { SharedArray } from "k6/data";
|
||||
import { Counter } from "k6/metrics";
|
||||
|
||||
import {
|
||||
API,
|
||||
PAGE_LIMIT,
|
||||
SUMMARY_THRESHOLDS,
|
||||
SUMMARY_TREND_STATS,
|
||||
WORK_DIR,
|
||||
authHeaders,
|
||||
messageHeaders,
|
||||
summaryFiles,
|
||||
syntheticText,
|
||||
} from "./lib.js";
|
||||
|
||||
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
|
||||
const ids = new SharedArray(
|
||||
"downloads",
|
||||
() => JSON.parse(open(`${WORK_DIR}/downloads.json`)),
|
||||
);
|
||||
const DURATION = __ENV.DURATION || "1h";
|
||||
const PRE_VUS = Number(__ENV.PRE_VUS || 100);
|
||||
const MAX_VUS = Number(__ENV.MAX_VUS || 600);
|
||||
const TIMEOUT = __ENV.TIMEOUT || "15s";
|
||||
const READER = authHeaders(fixture.tokens[fixture.readerId]);
|
||||
// счёт строк bg,… тем же кодом, что их пишет. Итерация, которую остановка
|
||||
// SIGINT прервала уже после строки, в iterations не входит, а её отсчёт
|
||||
// здесь k6 может не принять (контекст итерации уже отменён). run.py
|
||||
// требует строк не меньше счётчика и итераций, а лишних — не больше VU
|
||||
// сценария (design change track2-reconcile-cost, «Уточнения apply», п. 15)
|
||||
const LINES = {
|
||||
d: new Counter("bg_lines_download"),
|
||||
w: new Counter("bg_lines_write"),
|
||||
r: new Counter("bg_lines_read"),
|
||||
};
|
||||
const WRITE_URL = `${API}/chats/${fixture.writeChatId}/messages`;
|
||||
|
||||
function scenario(fn, rate) {
|
||||
return {
|
||||
executor: "constant-arrival-rate",
|
||||
exec: fn,
|
||||
rate,
|
||||
timeUnit: "1s",
|
||||
duration: DURATION,
|
||||
preAllocatedVUs: PRE_VUS,
|
||||
maxVUs: MAX_VUS,
|
||||
gracefulStop: "5s",
|
||||
};
|
||||
}
|
||||
|
||||
export const options = {
|
||||
scenarios: {
|
||||
download: scenario("download", Number(__ENV.DOWNLOAD_RATE)),
|
||||
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:download}": ["count>=0"],
|
||||
"iterations{scenario:write}": ["count>=0"],
|
||||
"iterations{scenario:read}": ["count>=0"],
|
||||
},
|
||||
};
|
||||
|
||||
// длительность — по монотонным таймингам k6 (как в failover.js), с точностью
|
||||
// 0,01 мс: p95 чтения истории — единицы миллисекунд, и целые мс огрубляли
|
||||
// бы отношение r; без ответа (status 0) — разность часов
|
||||
function report(kind, start, res) {
|
||||
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) * 100) / 100,
|
||||
);
|
||||
LINES[kind].add(1);
|
||||
console.log(`bg,${kind},${start},${duration},${res.status}`);
|
||||
}
|
||||
|
||||
export function download() {
|
||||
const n = exec.scenario.iterationInTest;
|
||||
const id = ids[n % ids.length];
|
||||
const start = Date.now();
|
||||
const res = http.get(`${API}/attachments/${id}/content`, {
|
||||
headers: READER,
|
||||
responseType: "none",
|
||||
timeout: TIMEOUT,
|
||||
responseCallback: http.expectedStatuses(200),
|
||||
});
|
||||
report("d", start, res);
|
||||
}
|
||||
|
||||
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("bg", n) }),
|
||||
{
|
||||
headers: messageHeaders(fixture.tokens[sender]),
|
||||
responseType: "none",
|
||||
timeout: TIMEOUT,
|
||||
responseCallback: http.expectedStatuses(201),
|
||||
},
|
||||
);
|
||||
report("w", start, res);
|
||||
}
|
||||
|
||||
export function read() {
|
||||
const start = Date.now();
|
||||
const res = http.get(`${WRITE_URL}?limit=${PAGE_LIMIT}`, {
|
||||
headers: READER,
|
||||
responseType: "none",
|
||||
timeout: TIMEOUT,
|
||||
responseCallback: http.expectedStatuses(200),
|
||||
});
|
||||
report("r", start, res);
|
||||
}
|
||||
|
||||
export function handleSummary(data) {
|
||||
return summaryFiles(data);
|
||||
}
|
||||
@@ -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) };
|
||||
}
|
||||
@@ -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 {};
|
||||
}
|
||||
@@ -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
@@ -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) };
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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) };
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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) };
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
// Профиль очереди (design change track1-queue-overload, решение 6): открытая
|
||||
// модель загрузок через LB. Окна — сценарии constant-arrival-rate, timeUnit 10 с
|
||||
// для дробной интенсивности; VU заранее и без прибавления: тело — open на VU,
|
||||
// создание на ходу с телом 10 MiB теряет итерации. Ответ не повторяется: 429 —
|
||||
// отказ, недосланные итерации — dropped_iterations. Строка на загрузку
|
||||
// «q,<окно>,<отправка мс>,<длительность мс>,<статус>,<Retry-After>,<X-Instance-Id>,
|
||||
// <id>» — в файл консоли (--console-output); setup() пишет «q-t0,<мс>». WINDOWS —
|
||||
// «имя:интенсивность:секунды:VU», окна идут подряд; WARM=N — N загрузок подряд.
|
||||
import exec from "k6/execution";
|
||||
import http from "k6/http";
|
||||
|
||||
import {
|
||||
API,
|
||||
SUMMARY_THRESHOLDS,
|
||||
SUMMARY_TREND_STATS,
|
||||
WORK_DIR,
|
||||
summaryFiles,
|
||||
} from "./lib.js";
|
||||
|
||||
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
|
||||
const BODY = open(`${WORK_DIR}/${__ENV.BODY}`, "b");
|
||||
const MEDIA = __ENV.MEDIA;
|
||||
const WARM = Number(__ENV.WARM || 0);
|
||||
const WINDOWS = (__ENV.WINDOWS || "")
|
||||
.split(",")
|
||||
.filter((item) => item !== "")
|
||||
.map((item) => {
|
||||
const [name, rate, seconds, vus] = item.split(":");
|
||||
return {
|
||||
name,
|
||||
rate: Number(rate),
|
||||
seconds: Number(seconds),
|
||||
vus: Number(vus),
|
||||
};
|
||||
});
|
||||
// больше timeout server LB пути загрузки (30 с): клиент видит ответ LB
|
||||
const TIMEOUT = "60s";
|
||||
const URL = `${API}/chats/${fixture.readChatId}/attachments?filename=bench`;
|
||||
const HEADERS = {
|
||||
Authorization: `Bearer ${fixture.tokens[fixture.readerId]}`,
|
||||
"Content-Type": MEDIA,
|
||||
};
|
||||
|
||||
function scenarios() {
|
||||
if (WARM) {
|
||||
return {
|
||||
warm: { executor: "shared-iterations", vus: 1, iterations: WARM },
|
||||
};
|
||||
}
|
||||
const out = {};
|
||||
let start = 0;
|
||||
for (const item of WINDOWS) {
|
||||
out[item.name] = {
|
||||
executor: "constant-arrival-rate",
|
||||
rate: Math.round(item.rate * 10),
|
||||
timeUnit: "10s",
|
||||
startTime: `${start}s`,
|
||||
duration: `${item.seconds}s`,
|
||||
preAllocatedVUs: item.vus,
|
||||
maxVUs: item.vus,
|
||||
gracefulStop: "45s",
|
||||
};
|
||||
start += item.seconds;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
export const options = {
|
||||
scenarios: scenarios(),
|
||||
summaryTrendStats: SUMMARY_TREND_STATS,
|
||||
// порог всегда выполняется: итерации попадают в итог, run.py сверяет с ними
|
||||
// число строк
|
||||
thresholds: {
|
||||
...SUMMARY_THRESHOLDS,
|
||||
iterations: ["count>=0"],
|
||||
dropped_iterations: ["count>=0"],
|
||||
},
|
||||
};
|
||||
|
||||
export function setup() {
|
||||
const t0 = Date.now();
|
||||
console.log(`q-t0,${t0}`);
|
||||
return t0;
|
||||
}
|
||||
|
||||
export default function () {
|
||||
const start = Date.now();
|
||||
const res = http.post(URL, BODY, {
|
||||
headers: HEADERS,
|
||||
timeout: TIMEOUT,
|
||||
responseCallback: http.expectedStatuses(202, 429),
|
||||
});
|
||||
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),
|
||||
);
|
||||
let id = "-";
|
||||
if (res.status === 202) {
|
||||
id = res.json("id");
|
||||
}
|
||||
const retry = res.headers["Retry-After"] || "-";
|
||||
const instance = res.headers["X-Instance-Id"] || "-";
|
||||
console.log(
|
||||
`q,${exec.scenario.name},${start},${duration},${res.status},${retry},` +
|
||||
`${instance},${id}`,
|
||||
);
|
||||
}
|
||||
|
||||
export function handleSummary(data) {
|
||||
return summaryFiles(data);
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
// Обход принятых вложений профиля очереди (design change track1-queue-overload,
|
||||
// решение 9): истина о готовности — метаданные GET /attachments/{id}, опрос в
|
||||
// замере не нужен: updated_at у ready не меняется после фиксации. Строка на
|
||||
// вложение «qs,<id>,<http>,<status>,<error_code>,<variants>,<updated_at>»; у
|
||||
// выборки (первые SAMPLE ids, порядок задал оркестратор от зерна) — оригинал и
|
||||
// варианты с SHA-256 из метаданных: «qv,<id>,<имя>,<1|0>».
|
||||
import { sha256 } from "k6/crypto";
|
||||
import exec from "k6/execution";
|
||||
import http from "k6/http";
|
||||
import { SharedArray } from "k6/data";
|
||||
|
||||
import { API, WORK_DIR, authHeaders, summaryFiles } from "./lib.js";
|
||||
|
||||
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
|
||||
const ids = new SharedArray("ids", () =>
|
||||
JSON.parse(open(`${WORK_DIR}/${__ENV.IDS}`)),
|
||||
);
|
||||
const SAMPLE = Number(__ENV.SAMPLE || 10);
|
||||
const READER = authHeaders(fixture.tokens[fixture.readerId]);
|
||||
const VARIANTS = ["thumbnail", "crop", "optimized"];
|
||||
|
||||
export const options = {
|
||||
scenarios: {
|
||||
sweep: {
|
||||
executor: "shared-iterations",
|
||||
vus: 4,
|
||||
iterations: Math.max(1, ids.length),
|
||||
maxDuration: "10m",
|
||||
},
|
||||
},
|
||||
thresholds: { iterations: ["count>=0"] },
|
||||
};
|
||||
|
||||
function checkBytes(id, name, expected) {
|
||||
const query = name === "original" ? "" : `?variant=${name}`;
|
||||
const res = http.get(`${API}/attachments/${id}/content${query}`, {
|
||||
headers: READER,
|
||||
responseType: "binary",
|
||||
timeout: "60s",
|
||||
});
|
||||
let good = 0;
|
||||
if (res.status === 200) {
|
||||
good = sha256(res.body, "hex") === expected ? 1 : 0;
|
||||
}
|
||||
console.log(`qv,${id},${name},${good}`);
|
||||
}
|
||||
|
||||
export default function () {
|
||||
const index = exec.scenario.iterationInTest;
|
||||
if (index >= ids.length) {
|
||||
return;
|
||||
}
|
||||
const id = ids[index];
|
||||
const res = http.get(`${API}/attachments/${id}`, {
|
||||
headers: READER,
|
||||
timeout: "30s",
|
||||
responseCallback: http.expectedStatuses(200, 404),
|
||||
});
|
||||
if (res.status !== 200) {
|
||||
console.log(`qs,${id},${res.status},-,-,0,-`);
|
||||
return;
|
||||
}
|
||||
const meta = res.json();
|
||||
const variants = meta.variants || [];
|
||||
console.log(
|
||||
`qs,${id},200,${meta.status},${meta.error_code || "-"},` +
|
||||
`${variants.length},${meta.updated_at}`,
|
||||
);
|
||||
if (index < SAMPLE && meta.status === "ready") {
|
||||
checkBytes(id, "original", meta.sha256);
|
||||
for (const item of variants) {
|
||||
if (VARIANTS.includes(item.name)) {
|
||||
checkBytes(id, item.name, item.sha256);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function handleSummary(data) {
|
||||
return summaryFiles(data);
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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),
|
||||
};
|
||||
}
|
||||
@@ -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) };
|
||||
}
|
||||
@@ -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) };
|
||||
}
|
||||
@@ -0,0 +1,106 @@
|
||||
// Профиль загрузок (design change upload-memory, решение 10): CLIENTS VU
|
||||
// загружают одно и то же тело PNG без пауз (constant-vus) через LB, пока
|
||||
// оркестратор меряет память реплики. На 429 VU ждёт Retry-After, на прочие
|
||||
// ошибки — секунду. Каждая загрузка — строка «up,<vu>,<итерация>,
|
||||
// <отправка мс>,<длительность мс>,<статус>,<X-Instance-Id>» в файл консоли
|
||||
// k6 (--console-output); setup() пишет «up-t0,<мс>» — начало нагрузки на
|
||||
// часах ВМ: окно замера — [t0 + RAMP_S, t0 + RAMP_S + WINDOW_S). WARMUP=1 —
|
||||
// одна разогревающая загрузка, она должна получить код успеха. Успех — 202, у
|
||||
// варианта с образом commit до перехода на 202 — 201 (design change
|
||||
// async-attachments, решение 16); чей код чей, считает bench/uploads.py.
|
||||
import exec from "k6/execution";
|
||||
import http from "k6/http";
|
||||
import { fail, sleep } from "k6";
|
||||
|
||||
import {
|
||||
API,
|
||||
SUMMARY_THRESHOLDS,
|
||||
SUMMARY_TREND_STATS,
|
||||
WORK_DIR,
|
||||
summaryFiles,
|
||||
} from "./lib.js";
|
||||
|
||||
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
|
||||
// тело — файл рабочего каталога, его строит оркестратор (bench/uploads.py)
|
||||
const BODY = open(`${WORK_DIR}/${__ENV.BODY}`, "b");
|
||||
const CLIENTS = Number(__ENV.CLIENTS || 1);
|
||||
const RAMP_S = Number(__ENV.RAMP_S || 3);
|
||||
const WINDOW_S = Number(__ENV.WINDOW_S || 20);
|
||||
const WARMUP = __ENV.WARMUP === "1";
|
||||
const SUCCESS = [201, 202];
|
||||
// больше timeout server LB пути загрузки (30 с): клиент видит ответ LB
|
||||
const TIMEOUT = "60s";
|
||||
const URL = `${API}/chats/${fixture.readChatId}/attachments?filename=bench.png`;
|
||||
// идентификация — Bearer, как authHeaders() в lib.js, но тело — PNG, а не
|
||||
// JSON
|
||||
const HEADERS = {
|
||||
Authorization: `Bearer ${fixture.tokens[fixture.readerId]}`,
|
||||
"Content-Type": "image/png",
|
||||
};
|
||||
|
||||
export const options = {
|
||||
scenarios: {
|
||||
upload: WARMUP
|
||||
? { executor: "per-vu-iterations", vus: 1, iterations: 1 }
|
||||
: {
|
||||
executor: "constant-vus",
|
||||
vus: CLIENTS,
|
||||
duration: `${RAMP_S + WINDOW_S}s`,
|
||||
// начатая загрузка доходит до ответа: больше срока LB (30 с) и
|
||||
// паузы после ответа — строк столько же, сколько итераций
|
||||
gracefulStop: "45s",
|
||||
},
|
||||
},
|
||||
summaryTrendStats: SUMMARY_TREND_STATS,
|
||||
thresholds: {
|
||||
...SUMMARY_THRESHOLDS,
|
||||
"iterations{scenario:upload}": ["count>=0"],
|
||||
},
|
||||
};
|
||||
|
||||
export function setup() {
|
||||
const t0 = Date.now();
|
||||
console.log(`up-t0,${t0}`);
|
||||
return t0;
|
||||
}
|
||||
|
||||
// длительность — по монотонным таймингам k6; без ответа (status 0) —
|
||||
// разность часов
|
||||
function report(start, res) {
|
||||
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(
|
||||
`up,${exec.vu.idInTest},${exec.vu.iterationInScenario},${start},` +
|
||||
`${duration},${res.status},${instance}`,
|
||||
);
|
||||
}
|
||||
|
||||
export default function () {
|
||||
const start = Date.now();
|
||||
const res = http.post(URL, BODY, {
|
||||
headers: HEADERS,
|
||||
responseType: "none",
|
||||
timeout: TIMEOUT,
|
||||
responseCallback: http.expectedStatuses(...SUCCESS),
|
||||
});
|
||||
report(start, res);
|
||||
const success = SUCCESS.includes(res.status);
|
||||
if (WARMUP && !success) {
|
||||
fail(`warmup upload: ${res.status}`);
|
||||
}
|
||||
if (res.status === 429) {
|
||||
const retry = Number(res.headers["Retry-After"]);
|
||||
sleep(retry > 0 ? retry : 1);
|
||||
} else if (!success) {
|
||||
sleep(1);
|
||||
}
|
||||
}
|
||||
|
||||
export function handleSummary(data) {
|
||||
return summaryFiles(data);
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -0,0 +1,161 @@
|
||||
"""Файлы классов профиля очереди (design change `track1-queue-overload`,
|
||||
решение 5): `s`, `m`, `lj`, `lp`, детерминированно от зерна.
|
||||
|
||||
Только в контейнере `mtusi-bench-images` на образе стенда: Pillow образа и та же
|
||||
его версия, что у процесса обработки; `src` не импортируется. На stdout — JSON с
|
||||
размерами, пикселями и SHA-256; файл больше лимита контракта — код 1.
|
||||
|
||||
python make_images.py <зерно> <каталог>
|
||||
"""
|
||||
|
||||
import hashlib
|
||||
import io
|
||||
import json
|
||||
import random
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from PIL import Image, ImageChops
|
||||
from uploads import png_noise
|
||||
|
||||
MAX_BYTES = 10_485_760
|
||||
MAX_PIXELS = 40_000_000
|
||||
LARGE = (8000, 5000)
|
||||
SMALL = (1600, 1200)
|
||||
NOISE_HEIGHT = 3409
|
||||
CELLS_LOW = 64
|
||||
CELLS_HIGH = 512
|
||||
FINE_DIVISOR = 6
|
||||
TILE = 512
|
||||
AMPLITUDE = 24
|
||||
POSTERIZE_MASK = 0xF0
|
||||
|
||||
|
||||
def noise_l(width: int, height: int, seed: int) -> Image.Image:
|
||||
data = random.Random(seed).randbytes(width * height)
|
||||
return Image.frombytes("L", (width, height), data)
|
||||
|
||||
|
||||
def clouds(
|
||||
width: int,
|
||||
height: int,
|
||||
seed: int,
|
||||
cells: int = CELLS_LOW,
|
||||
) -> Image.Image:
|
||||
"""Гладкое поле из шума низкого разрешения: низкие частоты фото."""
|
||||
return noise_l(cells, max(2, cells * height // width), seed).resize(
|
||||
(width, height),
|
||||
Image.Resampling.BICUBIC,
|
||||
)
|
||||
|
||||
|
||||
def detail_tile(
|
||||
width: int,
|
||||
height: int,
|
||||
seed: int,
|
||||
amplitude: int,
|
||||
) -> Image.Image:
|
||||
"""Плитка шума амплитуды `amplitude`, повторённая на всё поле."""
|
||||
tile = noise_l(TILE, TILE, seed).point(lambda v: v * amplitude // 255)
|
||||
field = Image.new("L", (width, height))
|
||||
for y in range(0, height, TILE):
|
||||
for x in range(0, width, TILE):
|
||||
field.paste(tile, (x, y))
|
||||
return field
|
||||
|
||||
|
||||
def bands(
|
||||
width: int,
|
||||
height: int,
|
||||
seed: int,
|
||||
amplitude: int,
|
||||
) -> list[Image.Image]:
|
||||
out = []
|
||||
for number in range(3):
|
||||
band = ImageChops.add(
|
||||
clouds(width, height, seed + number),
|
||||
clouds(
|
||||
width,
|
||||
height,
|
||||
seed + 10 + number,
|
||||
cells=CELLS_HIGH,
|
||||
).point(lambda v: v // FINE_DIVISOR),
|
||||
)
|
||||
if amplitude:
|
||||
band = ImageChops.add(
|
||||
band,
|
||||
detail_tile(width, height, seed + 20 + number, amplitude),
|
||||
)
|
||||
out.append(band)
|
||||
return out
|
||||
|
||||
|
||||
def jpeg(image: Image.Image, quality: int) -> bytes:
|
||||
out = io.BytesIO()
|
||||
image.save(out, format="JPEG", quality=quality, subsampling="4:2:0")
|
||||
return out.getvalue()
|
||||
|
||||
|
||||
def build_s(seed: int) -> bytes:
|
||||
return jpeg(Image.merge("RGB", bands(*SMALL, seed, AMPLITUDE)), 85)
|
||||
|
||||
|
||||
def build_lj(seed: int) -> bytes:
|
||||
return jpeg(Image.merge("RGB", bands(*LARGE, seed + 200, AMPLITUDE)), 88)
|
||||
|
||||
|
||||
def build_lp(seed: int) -> bytes:
|
||||
colour = [
|
||||
band.point(lambda v: v & POSTERIZE_MASK)
|
||||
for band in bands(*LARGE, seed + 200, 0)
|
||||
]
|
||||
alpha = clouds(*LARGE, seed + 300).point(
|
||||
lambda v: (128 + v // 2) & POSTERIZE_MASK,
|
||||
)
|
||||
out = io.BytesIO()
|
||||
Image.merge("RGBA", (*colour, alpha)).save(
|
||||
out,
|
||||
format="PNG",
|
||||
compress_level=6,
|
||||
)
|
||||
return out.getvalue()
|
||||
|
||||
|
||||
def build_m(seed: int) -> bytes:
|
||||
return png_noise(NOISE_HEIGHT, seed + NOISE_HEIGHT)
|
||||
|
||||
|
||||
BUILDERS = {
|
||||
"s": (build_s, "s.jpg", "image/jpeg"),
|
||||
"m": (build_m, "m.png", "image/png"),
|
||||
"lj": (build_lj, "lj.jpg", "image/jpeg"),
|
||||
"lp": (build_lp, "lp.png", "image/png"),
|
||||
}
|
||||
|
||||
|
||||
def main() -> int:
|
||||
seed, directory = int(sys.argv[1]), Path(sys.argv[2])
|
||||
report = {}
|
||||
code = 0
|
||||
for name, (build, filename, media) in BUILDERS.items():
|
||||
data = build(seed)
|
||||
with Image.open(io.BytesIO(data)) as image:
|
||||
width, height = image.size
|
||||
(directory / filename).write_bytes(data)
|
||||
report[name] = {
|
||||
"file": filename,
|
||||
"media_type": media,
|
||||
"bytes": len(data),
|
||||
"width": width,
|
||||
"height": height,
|
||||
"sha256": hashlib.sha256(data).hexdigest(),
|
||||
}
|
||||
if len(data) > MAX_BYTES or width * height > MAX_PIXELS:
|
||||
print(f"{name}: over the contract limit", file=sys.stderr)
|
||||
code = 1
|
||||
print(json.dumps(report))
|
||||
return code
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+2616
File diff suppressed because it is too large
Load Diff
+1341
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,21 @@
|
||||
# Override профиля очереди (третий -f, только этот профиль; design change
|
||||
# track1-queue-overload, решение 10). Плагин метрик брокера и интервал
|
||||
# статистики в секунду: порт 15692 — только сеть стенда, порты брокера сброшены
|
||||
# в bench.compose.yml. Worker перезапускается, как на рабочем стенде: ядро может
|
||||
# завершить его процесс 1, когда конкуренция не помещается в лимит памяти, и без
|
||||
# перезапуска ячейка простояла бы до срока окна с ложными stuck. Пути — от
|
||||
# каталога первого файла compose (корень репозитория)
|
||||
services:
|
||||
rabbitmq:
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./bench/rabbitmq/enabled_plugins
|
||||
target: /etc/rabbitmq/enabled_plugins
|
||||
read_only: true
|
||||
- type: bind
|
||||
source: ./bench/rabbitmq/91-bench.conf
|
||||
target: /etc/rabbitmq/conf.d/91-bench.conf
|
||||
read_only: true
|
||||
|
||||
worker:
|
||||
restart: unless-stopped
|
||||
@@ -0,0 +1,2 @@
|
||||
# Профиль очереди: значения метрик свежие за секунду (проба: 4,7 мс CPU на опрос)
|
||||
collect_statistics_interval = 1000
|
||||
@@ -0,0 +1 @@
|
||||
[rabbitmq_prometheus].
|
||||
+2295
File diff suppressed because it is too large
Load Diff
+1246
File diff suppressed because it is too large
Load Diff
@@ -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)
|
||||
+8754
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,311 @@
|
||||
#!/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: наблюдатель не обращается к
|
||||
# стенду.
|
||||
# peak (профиль uploads, design change upload-memory, решение 10):
|
||||
# <интервал, с> peak <имя> <роль>=<полный id контейнера>…
|
||||
# Контейнер без сети, --user 0, cgroupfs на запись. perl открывает
|
||||
# memory.peak каждого контейнера на чтение и запись, пишет его прежнее
|
||||
# значение (`start <роль> <байт>`) и сбрасывает пик записью в свой
|
||||
# дескриптор (ядро ≥ 6.12): `reset <роль> ok|failed`. Раз в интервал —
|
||||
# `pk <нс> <роль> <id12> <memory.current> <anon> <sock> <oom_kill>`
|
||||
# (`anon`, `sock` — memory.stat, `oom_kill` — memory.events) или
|
||||
# `pk <нс> <роль> <id12> missing`. Появился /work/<имя>.stop — perl
|
||||
# читает пик через тот же дескриптор (`peak <роль> <байт>|missing`),
|
||||
# строка `end <нс>`, выход 0. Всё — в /work/<имя>.log.
|
||||
# queue (профиль очереди, design change track1-queue-overload, решение 10):
|
||||
# <интервал, с> queue <имя очереди>
|
||||
# Сеть mtusi-bench. Обход cgroup, как scan (`cg`), `vm`, `lb`; ещё `mp <нс>
|
||||
# <id12> <memory.peak> <anon> <oom_kill>` на контейнер и `mq <нс> <ready>
|
||||
# <unacked>` — метрики брокера HTTP/1.0 по /dev/tcp (брокер недоступен —
|
||||
# `mq <нс> missing`). В фоне psql с \watch пишет /work/jobs.log (одно
|
||||
# соединение): jobs|<мс>|outbox|waiting|published|processing|oldest_s|
|
||||
# staging_ready. Разбор — bench/overload.py.
|
||||
set -u
|
||||
|
||||
interval=$1
|
||||
shift
|
||||
mode=list
|
||||
if [[ ${1:-} == scan ]]; then
|
||||
mode=scan
|
||||
shift
|
||||
elif [[ ${1:-} == queue ]]; then
|
||||
mode=queue
|
||||
queue_name=$2
|
||||
shift 2
|
||||
elif [[ ${1:-} == peak ]]; then
|
||||
mode=peak
|
||||
name=$2
|
||||
shift 2
|
||||
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
|
||||
|
||||
if [[ $mode == queue ]]; then
|
||||
export PGPASSWORD="$POSTGRES_PASSWORD"
|
||||
psql "host=postgres user=$POSTGRES_USER dbname=$POSTGRES_DB \
|
||||
application_name=bench-sampler" -XAtq -F '|' >/work/jobs.log 2>&1 <<SQL &
|
||||
SELECT 'jobs', (extract(epoch FROM clock_timestamp()) * 1000)::bigint,
|
||||
count(*) FILTER (WHERE state = 'queued' AND published_at IS NULL
|
||||
AND coalesce(next_attempt_at, created_at) <= clock_timestamp()),
|
||||
count(*) FILTER (WHERE state = 'queued' AND published_at IS NULL
|
||||
AND coalesce(next_attempt_at, created_at) > clock_timestamp()),
|
||||
count(*) FILTER (WHERE state = 'queued' AND published_at IS NOT NULL),
|
||||
count(*) FILTER (WHERE state = 'processing'),
|
||||
coalesce(round(extract(epoch FROM clock_timestamp() - min(created_at))::numeric, 1), 0),
|
||||
(SELECT count(*) FROM attachments
|
||||
WHERE status = 'ready' AND staging_key IS NOT NULL)
|
||||
FROM attachment_jobs WHERE state IN ('queued', 'processing')
|
||||
\watch $interval
|
||||
SQL
|
||||
fi
|
||||
|
||||
if [[ $mode == peak ]]; then
|
||||
log=/work/$name.log
|
||||
stop=/work/$name.stop
|
||||
: >"$log"
|
||||
exec 4>>"$log"
|
||||
# пик через свой дескриптор: сброс и чтение — в одном процессе perl, bash
|
||||
# позиционировать дескриптор не умеет
|
||||
perl -e '
|
||||
use strict;
|
||||
my ($stop, @targets) = @ARGV;
|
||||
$| = 1;
|
||||
my %fh;
|
||||
for my $t (@targets) {
|
||||
my ($role, $id) = split /=/, $t, 2;
|
||||
my $path = "/sys/fs/cgroup/docker/$id/memory.peak";
|
||||
my $h;
|
||||
if (!open($h, "+<", $path)) {
|
||||
print "start $role missing\nreset $role failed open\n";
|
||||
next;
|
||||
}
|
||||
my $old = "";
|
||||
sysread($h, $old, 64);
|
||||
chomp $old;
|
||||
print "start $role ", ($old =~ /^\d+$/ ? $old : "missing"), "\n";
|
||||
sysseek($h, 0, 0);
|
||||
if (defined syswrite($h, "reset")) {
|
||||
print "reset $role ok\n";
|
||||
$fh{$role} = $h;
|
||||
} else {
|
||||
print "reset $role failed $!\n";
|
||||
}
|
||||
}
|
||||
select(undef, undef, undef, 0.05) until -e $stop;
|
||||
for my $role (sort keys %fh) {
|
||||
my $h = $fh{$role};
|
||||
my $value = "";
|
||||
if (sysseek($h, 0, 0) && sysread($h, $value, 64)) {
|
||||
chomp $value;
|
||||
}
|
||||
print "peak $role ", ($value =~ /^\d+$/ ? $value : "missing"), "\n";
|
||||
}
|
||||
' "$stop" "$@" >&4 &
|
||||
perl_pid=$!
|
||||
|
||||
pk_line() {
|
||||
local role=$1 id=$2 dir=/sys/fs/cgroup/docker/$2
|
||||
local key val mem= anon= sock= oom=
|
||||
{
|
||||
read -r mem <"$dir/memory.current"
|
||||
while read -r key val; do
|
||||
case $key in
|
||||
anon) anon=$val ;;
|
||||
sock) sock=$val ;;
|
||||
esac
|
||||
done <"$dir/memory.stat"
|
||||
while read -r key val; do
|
||||
[[ $key == oom_kill ]] && oom=$val
|
||||
done <"$dir/memory.events"
|
||||
} 2>/dev/null
|
||||
if [[ -z $mem || -z $anon || -z $sock || -z $oom ]]; then
|
||||
printf 'pk %s %s %s missing\n' "$ns" "$role" "${id:0:12}" >&4
|
||||
return
|
||||
fi
|
||||
printf 'pk %s %s %s %s %s %s %s\n' "$ns" "$role" "${id:0:12}" \
|
||||
"$mem" "$anon" "$sock" "$oom" >&4
|
||||
}
|
||||
|
||||
while [[ ! -e $stop ]]; do
|
||||
ns=${EPOCHREALTIME/./}000
|
||||
for i in "${!ids[@]}"; do
|
||||
pk_line "${roles[$i]}" "${ids[$i]}"
|
||||
done
|
||||
sleep "$interval"
|
||||
done
|
||||
wait "$perl_pid"
|
||||
printf 'end %s\n' "${EPOCHREALTIME/./}000" >&4
|
||||
exit 0
|
||||
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<&-
|
||||
}
|
||||
|
||||
mp_line() {
|
||||
local id=$1 dir=/sys/fs/cgroup/docker/$1
|
||||
local key val peak= anon= oom=
|
||||
{
|
||||
read -r peak <"$dir/memory.peak"
|
||||
while read -r key val; do
|
||||
[[ $key == anon ]] && { anon=$val; break; }
|
||||
done <"$dir/memory.stat"
|
||||
while read -r key val; do
|
||||
[[ $key == oom_kill ]] && oom=$val
|
||||
done <"$dir/memory.events"
|
||||
} 2>/dev/null
|
||||
[[ -n $peak && -n $anon && -n $oom ]] &&
|
||||
printf 'mp %s %s %s %s %s\n' "$ns" "${id:0:12}" "$peak" "$anon" "$oom" >&4
|
||||
}
|
||||
|
||||
mq_line() {
|
||||
local line ready= unacked=
|
||||
if ! exec 3<>/dev/tcp/rabbitmq/15692 2>/dev/null; then
|
||||
printf 'mq %s missing\n' "$ns" >&4
|
||||
return
|
||||
fi
|
||||
printf 'GET /metrics/detailed?vhost=%%2F&family=queue_coarse_metrics HTTP/1.0\r\nHost: x\r\n\r\n' >&3
|
||||
while IFS= read -r line; do
|
||||
line=${line%$'\r'}
|
||||
case $line in
|
||||
rabbitmq_detailed_queue_messages_ready\{*"$queue_name"*) ready=${line##* } ;;
|
||||
rabbitmq_detailed_queue_messages_unacked\{*"$queue_name"*) unacked=${line##* } ;;
|
||||
esac
|
||||
done <&3
|
||||
exec 3<&-
|
||||
# очередь ещё не объявлена — нули, а брокер отвечает
|
||||
printf 'mq %s %s %s\n' "$ns" "${ready:-0}" "${unacked:-0}" >&4
|
||||
}
|
||||
|
||||
hex64='^[0-9a-f]{64}$'
|
||||
|
||||
while :; do
|
||||
# EPOCHREALTIME bash 5 — часы ВМ без запуска date
|
||||
ns=${EPOCHREALTIME/./}000
|
||||
if [[ $mode == scan || $mode == queue ]]; then
|
||||
for dir in /sys/fs/cgroup/docker/*/; do
|
||||
dir=${dir%/}
|
||||
id=${dir##*/}
|
||||
if [[ $id =~ $hex64 ]]; then
|
||||
cg_line - "$id"
|
||||
[[ $mode == queue ]] && mp_line "$id"
|
||||
fi
|
||||
done
|
||||
else
|
||||
for i in "${!ids[@]}"; do
|
||||
cg_line "${roles[$i]}" "${ids[$i]}"
|
||||
done
|
||||
fi
|
||||
vm_line
|
||||
[[ $mode == list || $mode == queue ]] && lb_lines
|
||||
[[ $mode == queue ]] && mq_line
|
||||
sleep "$interval"
|
||||
done
|
||||
+1776
File diff suppressed because it is too large
Load Diff
+1149
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,186 @@
|
||||
# Шаблон 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
|
||||
|
||||
[s3]
|
||||
# Адрес, порт, bucket и ключи пользователя API приходят из .env (мосты к
|
||||
# S3_OUT_PORT и S3_API_*, S3__BUCKET) и из environment compose; здесь их
|
||||
# не указывать.
|
||||
# регион подписи SigV4; SeaweedFS берёт его из запроса
|
||||
region = "us-east-1"
|
||||
# секунды на установку соединения с S3
|
||||
connect_timeout_seconds = 1
|
||||
# секунды на весь вызов S3; меньше timeout server HAProxy (10 с)
|
||||
timeout_seconds = 5
|
||||
# соединений в пуле клиента S3 на процесс
|
||||
max_connections = 10
|
||||
|
||||
[idempotency]
|
||||
# секунды, в течение которых повтор POST сообщения с тем же
|
||||
# Idempotency-Key возвращает исходный результат (имя skeleton
|
||||
# IDEMPOTENCY_TTL_SECONDS); контракт требует не меньше 86400 — 24 ч.
|
||||
# Короткий срок для проверки — окружением IDEMPOTENCY__TTL_SECONDS=2
|
||||
ttl_seconds = 86400
|
||||
|
||||
[uploads]
|
||||
# Места загрузок вложений процесса API; разовая подмена — окружением
|
||||
# UPLOADS__*. Память загрузок ограничена числом мест, а не клиентов.
|
||||
# загрузок, которые процесс обрабатывает одновременно
|
||||
max_concurrent = 4
|
||||
# загрузок, которые ждут места; 0 — без ожидания, сразу 429
|
||||
max_waiting = 16
|
||||
# секунды ожидания места, затем 429 rate_limited с Retry-After; вход,
|
||||
# членство и ожидание (2 × 6 + 5 = 17 с) меньше timeout server LB пути
|
||||
# загрузки (30 с). Проверки при старте нет: больше 18 с — 504 от LB
|
||||
# вместо 429
|
||||
wait_timeout_seconds = 5
|
||||
# секунды на всё тело с момента, как загрузка заняла место; иначе 400
|
||||
body_timeout_seconds = 30
|
||||
# незавершённых заданий стенда (queued и processing), при которых загрузка
|
||||
# сразу получает 429 rate_limited с Retry-After: 5; 0 — без предела. Срок
|
||||
# ожидания = предел / потолок worker; при другом числе worker предел другой
|
||||
max_unfinished_jobs = 250
|
||||
|
||||
[cleaner]
|
||||
# Уборщик незавершённых загрузок (сервис compose cleaner); реплики API
|
||||
# секцию не читают. Разовая подмена — окружением CLEANER__*.
|
||||
# секунды между проходами
|
||||
interval_seconds = 60
|
||||
# секунды: строку pending моложе уборщик не трогает (grace period).
|
||||
# Должно быть больше 2 × [database] request_timeout_seconds +
|
||||
# [s3] timeout_seconds (17 с), иначе уборщик не стартует
|
||||
pending_grace_seconds = 900
|
||||
# строк pending или вложений со staging в одной выборке кандидатов
|
||||
batch_size = 100
|
||||
# секунды хранения объекта staging вложения failed и объекта staging без
|
||||
# метаданных; у ready staging убирается следующим проходом
|
||||
staging_retention_seconds = 86400
|
||||
|
||||
[reconciler]
|
||||
# Сверка bucket и БД процессом уборщика: плановая в сервисе cleaner и
|
||||
# разовая — make reconcile. Grace — [cleaner] pending_grace_seconds.
|
||||
# Разовая подмена — окружением RECONCILER__*.
|
||||
# секунды между плановыми сверками; 0 — без плановой сверки
|
||||
interval_seconds = 3600
|
||||
# ключей на страницу списка S3 и строк на запрос к PostgreSQL, 1–1000
|
||||
page_size = 1000
|
||||
# предел изменений за проход: больше — ни одного изменения и код 3;
|
||||
# разовый проход принимает больший аргументом --max-changes
|
||||
max_changes = 100
|
||||
# предел скорости прохода: объектов S3 в секунду (ключи страниц списка,
|
||||
# HEAD, GET, DELETE) в среднем от начала прохода; 0 — без предела;
|
||||
# разовый проход принимает другой аргументом --max-objects-per-second
|
||||
max_objects_per_second = 2000
|
||||
|
||||
[broker]
|
||||
# Адрес, порт, пользователь и пароль RabbitMQ приходят из .env (мосты к
|
||||
# RABBITMQ_*) и из environment compose; здесь их не указывать.
|
||||
# секунды на установку соединения с брокером
|
||||
connect_timeout_seconds = 2
|
||||
# секунды на публикацию пакета заданий relay целиком: соединение, канал,
|
||||
# публикация и подтверждения; меньше срока шага с БД: блокировки строк
|
||||
# держатся не дольше него
|
||||
publish_timeout_seconds = 2
|
||||
|
||||
[worker]
|
||||
# Worker обработки вложений (сервис compose worker); реплики API и relay
|
||||
# секцию не читают. Разовая подмена — окружением WORKER__*.
|
||||
# заданий, которые worker обрабатывает одновременно (лимит памяти
|
||||
# контейнера — на эту конкуренцию)
|
||||
concurrency = 2
|
||||
# неподтверждённых сообщений, которые выдаёт брокер
|
||||
prefetch = 2
|
||||
# попыток у задания с последнего replay, включая первую
|
||||
max_attempts = 5
|
||||
# секунды на одну попытку
|
||||
job_timeout_seconds = 60
|
||||
# секунды запаса аренды сверх срока попытки
|
||||
lease_margin_seconds = 10
|
||||
# секунды, основа паузы перед следующей попыткой: случайно из [d / 2, d],
|
||||
# d = min(предел, основа × 2^(N − 1))
|
||||
retry_base_delay_seconds = 5
|
||||
# секунды, предел паузы; не меньше основы
|
||||
retry_max_delay_seconds = 300
|
||||
# секунды жизни процесса обработки; меньше срока попытки
|
||||
render_timeout_seconds = 40
|
||||
# секунды CPU процесса обработки, целое
|
||||
render_cpu_limit_seconds = 15
|
||||
# МиБ адресного пространства процесса обработки, целое
|
||||
render_memory_limit_mib = 450
|
||||
# секунды, которые worker ждёт начатые задания после SIGTERM, не больше 8
|
||||
graceful_shutdown_seconds = 8
|
||||
# секунды паузы между попытками соединиться с брокером и перед возвратом
|
||||
# сообщения при отказе PostgreSQL
|
||||
reconnect_seconds = 2
|
||||
|
||||
[relay]
|
||||
# Relay публикации заданий (сервис compose relay); реплики API и worker секцию
|
||||
# не читают. Разовая подмена — окружением RELAY__*.
|
||||
# секунды паузы между проходами, когда публиковать нечего
|
||||
poll_interval_seconds = 0.25
|
||||
# заданий за один проход
|
||||
batch_size = 100
|
||||
# предел опубликованных и не взятых заданий; 0 — без предела
|
||||
max_published_backlog = 1000
|
||||
# секунды: отмеченное задание старше может считаться потерянным, если в
|
||||
# очереди нет готовых сообщений
|
||||
republish_after_seconds = 300
|
||||
# секунды паузы после отказа брокера или PostgreSQL
|
||||
failure_pause_seconds = 2
|
||||
@@ -0,0 +1,560 @@
|
||||
# Стенд лабы 5: HAProxy — единственная точка входа, за ним API ×
|
||||
# API_REPLICAS; PostgreSQL, Valkey (кэш), S3 (SeaweedFS, байты вложений),
|
||||
# RabbitMQ (задания обработки), одноразовые миграции и bootstrap S3, уборщик
|
||||
# незавершённых загрузок, relay публикации заданий, worker обработки вложений.
|
||||
# Правила — .claude/rules/docker.md и balancer.md. Значения — из .env
|
||||
# (шаблон .env.example); литералы только у адреса публикации 127.0.0.1 и
|
||||
# у режима docker. Имя проекта меняется в каждой лабе: от него зависят
|
||||
# имена volumes, и стенд не должен подключаться к данным прошлой лабы.
|
||||
name: mtusi-lab5
|
||||
|
||||
# окружение по сервисам: секреты получают только те, кому они нужны.
|
||||
# PostgreSQL — api, cleaner, relay, worker и 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}
|
||||
|
||||
# S3 — api, cleaner и worker: адрес в сети и bucket; ключи — у каждого своего
|
||||
# пользователя (не административные). Секреты S3 по сервисам (design
|
||||
# change s3-storage, решение 3; upload-consistency, решение 9):
|
||||
# административная пара — только s3, ключ подписи — s3 и s3-bootstrap,
|
||||
# ключи API — s3-bootstrap и api, ключи уборщика — s3-bootstrap и cleaner,
|
||||
# ключи worker — s3-bootstrap и worker
|
||||
x-s3-env: &s3-env
|
||||
S3__HOST: ${S3_HOST:-s3}
|
||||
S3__PORT: ${S3_PORT:-8333}
|
||||
S3__BUCKET: ${S3__BUCKET:-messenger}
|
||||
|
||||
# ключи пользователя API в S3 — только api
|
||||
x-s3-api-keys-env: &s3-api-keys-env
|
||||
S3__ACCESS_KEY_ID: ${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, copy S3 lines from .env.example}
|
||||
S3__SECRET_ACCESS_KEY: ${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, copy S3 lines from .env.example}
|
||||
|
||||
# RabbitMQ — relay и worker: адрес в сети и учётные данные; один пользователь
|
||||
# на оба сервиса, разделение прав — лаба 7 (design change async-attachments,
|
||||
# решение 4). У реплик API брокера нет (design change pipeline-reliability,
|
||||
# решение 1)
|
||||
x-broker-env: &broker-env
|
||||
BROKER__HOST: ${RABBITMQ_HOST:-rabbitmq}
|
||||
BROKER__PORT: ${RABBITMQ_PORT:-5672}
|
||||
BROKER__USER: ${RABBITMQ_DEFAULT_USER:?RABBITMQ_DEFAULT_USER is not set, run make env_setup}
|
||||
BROKER__PASSWORD: ${RABBITMQ_DEFAULT_PASS:?RABBITMQ_DEFAULT_PASS is empty, run make env_setup}
|
||||
|
||||
# образ сервера S3 и bootstrap: тег с версией и digest индекса (amd64 и
|
||||
# arm64)
|
||||
x-s3-image: &s3-image chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d
|
||||
|
||||
# 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 + cleaner (пул 1) + worker (пул 2) +
|
||||
# relay (пул 1) ≤ max_connections (100): 2 × 10 + 1 + 1 + 2 + 1 = 25,
|
||||
# при поочерёдной замене 3 × 10 + 1 + 1 + 2 + 1 = 35; расчёт — 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
|
||||
|
||||
# S3 — байты вложений (design change s3-storage, решения 1–2): master,
|
||||
# volume, filer и шлюз S3 одним процессом weed server. Служебные серверы
|
||||
# слушают только 127.0.0.1 контейнера, в сеть выходят порт API S3
|
||||
# (S3_PORT) и gRPC шлюза (S3_PORT + 10000), закрытый ключом подписи.
|
||||
# Entrypoint образа сам переходит на пользователя seaweed и добавляет
|
||||
# -dir=/data -volume.max=0 -master.volumeSizeLimitMB=1024
|
||||
s3:
|
||||
image: *s3-image
|
||||
restart: unless-stopped
|
||||
command:
|
||||
- server
|
||||
# master, volume и filer — только loopback контейнера
|
||||
- -ip=127.0.0.1
|
||||
- -ip.bind=127.0.0.1
|
||||
# по умолчанию master шлёт статистику на telemetry.seaweedfs.com
|
||||
- -master.telemetry=false
|
||||
# узел один, выборам ждать некого: перезапуск до healthy ~7 с, а не ~24
|
||||
- -master.electionTimeout=1s
|
||||
# пауза перед остановкой тома нужна кластеру, а не одному узлу
|
||||
- -volume.preStopSeconds=0
|
||||
- -filer
|
||||
- -s3
|
||||
- -s3.ip.bind=0.0.0.0
|
||||
- -s3.port=${S3_PORT:-8333}
|
||||
# REST Catalog и Lance по умолчанию открыты на 8181 и 9101
|
||||
- -s3.port.iceberg=0
|
||||
- -s3.port.lance=0
|
||||
# встроенный IAM API на порту S3 не нужен: bootstrap — weed shell
|
||||
- -s3.iam=false
|
||||
# шлюз держит не больше 64 МБ загрузок одновременно, лишние ждут
|
||||
- -s3.concurrentUploadLimitMB=64
|
||||
environment:
|
||||
# административная пара: учётная запись есть с первого старта, и
|
||||
# анонимного окна нет. Только у сервера: ни API, ни bootstrap её не
|
||||
# получают
|
||||
AWS_ACCESS_KEY_ID: ${S3_ROOT_ACCESS_KEY:?S3_ROOT_ACCESS_KEY is empty, copy S3 lines from .env.example}
|
||||
AWS_SECRET_ACCESS_KEY: ${S3_ROOT_SECRET_KEY:?S3_ROOT_SECRET_KEY is empty, copy S3 lines from .env.example}
|
||||
# без ключа подписи gRPC шлюза принимает учётную запись
|
||||
# администратора от любого контейнера сети
|
||||
WEED_JWT_FILER_SIGNING_KEY: ${S3_JWT_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, copy S3 lines from .env.example}
|
||||
# сборщик мусора Go чаще у предела: вместе с лимитом загрузок 20
|
||||
# одновременных PUT по 10 MiB укладываются в 512 МБ
|
||||
GOMEMLIMIT: 400MiB
|
||||
# порт API S3 для healthcheck
|
||||
S3_PORT: ${S3_PORT:-8333}
|
||||
ports:
|
||||
# только localhost и только API S3: к нему подключается приложение в
|
||||
# console; консоль, UI и служебные серверы не публикуются
|
||||
- "127.0.0.1:${S3_OUT_PORT:-8334}:${S3_PORT:-8333}"
|
||||
volumes:
|
||||
# volume образа (Config.Volumes): тома, filer и IAM
|
||||
- s3_data:/data
|
||||
networks:
|
||||
default:
|
||||
# любое значение S3_HOST указывает на этот сервис
|
||||
aliases:
|
||||
- ${S3_HOST:-s3}
|
||||
healthcheck:
|
||||
# master выбран, том зарегистрирован у master (непустой DataNodes в
|
||||
# /dir/status), filer и шлюз S3 отвечают; всё на loopback. Без
|
||||
# проверки тома healthy наступал на ~4 с раньше регистрации, и первая
|
||||
# запись ждала её до ~4,8 с при сроке вызова 5 с. $$ — переменная
|
||||
# контейнера
|
||||
test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:9333/cluster/healthz && wget -q -O - http://127.0.0.1:9333/dir/status | grep -qF '\"DataNodes\":[{' && wget -q -O /dev/null http://127.0.0.1:8888/healthz && wget -q -O /dev/null \"http://127.0.0.1:$$S3_PORT/healthz\""]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 10
|
||||
start_period: 30s
|
||||
start_interval: 1s
|
||||
# плавная остановка ~15 с: срок ожидания подписок filer зашит в код.
|
||||
# При 10 с остановка кончалась бы SIGKILL (код 137)
|
||||
stop_grace_period: 20s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
# память — GOMEMLIMIT и лимит загрузок выше
|
||||
cpus: "1.0"
|
||||
memory: 512M
|
||||
|
||||
# брокер заданий обработки вложений (design change async-attachments,
|
||||
# решение 4). hostname постоянный: имя узла задаёт каталог данных, и
|
||||
# пересозданный контейнер иначе не нашёл бы свои данные в том же volume.
|
||||
# Учётная запись приложения создаётся при первом старте на пустом volume.
|
||||
# Наружу — только AMQP на loopback, для запуска в консоли
|
||||
rabbitmq:
|
||||
image: rabbitmq:4.3.7@sha256:bd88985187aa73cd598fa0d8b31d49b2f814a6d9e58f6d5a89bae588669d946a
|
||||
hostname: rabbitmq
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
RABBITMQ_DEFAULT_USER: ${RABBITMQ_DEFAULT_USER:?RABBITMQ_DEFAULT_USER is not set, run make env_setup}
|
||||
RABBITMQ_DEFAULT_PASS: ${RABBITMQ_DEFAULT_PASS:?RABBITMQ_DEFAULT_PASS is empty, run make env_setup}
|
||||
RABBITMQ_NODE_PORT: ${RABBITMQ_PORT:-5672}
|
||||
ports:
|
||||
- "127.0.0.1:${RABBITMQ_OUT_PORT:-5673}:${RABBITMQ_PORT:-5672}"
|
||||
volumes:
|
||||
# volume образа (Config.Volumes): очереди и сообщения
|
||||
- rabbitmq_data:/var/lib/rabbitmq
|
||||
- type: bind
|
||||
source: ./infra/rabbitmq/rabbitmq.conf
|
||||
target: /etc/rabbitmq/conf.d/90-messenger.conf
|
||||
read_only: true
|
||||
bind:
|
||||
create_host_path: false
|
||||
networks:
|
||||
default:
|
||||
# любое значение RABBITMQ_HOST указывает на этот сервис
|
||||
aliases:
|
||||
- ${RABBITMQ_HOST:-rabbitmq}
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "rabbitmq-diagnostics -q check_port_connectivity"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 30s
|
||||
start_interval: 1s
|
||||
# брокер завершается сам за ~2 с; 20 с — запас на большую очередь
|
||||
stop_grace_period: 20s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
# предел памяти брокера — 400 МиБ в infra/rabbitmq/rabbitmq.conf
|
||||
cpus: "1.0"
|
||||
memory: 512M
|
||||
|
||||
# bootstrap S3 — один раз до реплик, как миграции (решение 4): приватный
|
||||
# bucket, пользователь API с политикой «только объекты своего bucket»,
|
||||
# пользователь уборщика — «чтение и удаление объектов своего bucket»,
|
||||
# проверки приватности вне API. Повтор сводит состояние к .env и ничего
|
||||
# не ломает. В сетевом пространстве s3: master и filer сервера на
|
||||
# 127.0.0.1 доступны ему, а в сети их нет. make s3_check запускает его
|
||||
# же в режиме check
|
||||
s3-bootstrap:
|
||||
image: *s3-image
|
||||
network_mode: service:s3
|
||||
user: seaweed
|
||||
entrypoint: ["sh", "/opt/s3/bootstrap.sh"]
|
||||
command: ["apply"]
|
||||
restart: "no"
|
||||
environment:
|
||||
S3_BUCKET: ${S3__BUCKET:-messenger}
|
||||
S3_PORT: ${S3_PORT:-8333}
|
||||
# ключ подписи: им weed shell подписывает вызовы IAM filer
|
||||
WEED_JWT_FILER_SIGNING_KEY: ${S3_JWT_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, copy S3 lines from .env.example}
|
||||
S3_API_ACCESS_KEY: ${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, copy S3 lines from .env.example}
|
||||
S3_API_SECRET_KEY: ${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, copy S3 lines from .env.example}
|
||||
S3_CLEANER_ACCESS_KEY: ${S3_CLEANER_ACCESS_KEY:?S3_CLEANER_ACCESS_KEY is empty, run make env_setup}
|
||||
S3_CLEANER_SECRET_KEY: ${S3_CLEANER_SECRET_KEY:?S3_CLEANER_SECRET_KEY is empty, run make env_setup}
|
||||
S3_WORKER_ACCESS_KEY: ${S3_WORKER_ACCESS_KEY:?S3_WORKER_ACCESS_KEY is empty, run make env_setup}
|
||||
S3_WORKER_SECRET_KEY: ${S3_WORKER_SECRET_KEY:?S3_WORKER_SECRET_KEY is empty, run make env_setup}
|
||||
# список объектов уборщику — только по префиксу вложений своей базы
|
||||
# (сверка bucket и БД, design change track2-reconciler, решение 2);
|
||||
# не секрет, уборщик строит префикс сам из имени базы
|
||||
S3_CLEANER_LIST_PREFIX: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env_setup}/attachments/
|
||||
HOME: /tmp
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/s3/bootstrap.sh
|
||||
target: /opt/s3/bootstrap.sh
|
||||
read_only: true
|
||||
bind:
|
||||
create_host_path: false
|
||||
# файл ключа для curl и политика — только в памяти. /data — volume
|
||||
# образа (Config.Volumes): без tmpfs каждый новый контейнер bootstrap
|
||||
# оставлял бы анонимный volume
|
||||
tmpfs:
|
||||
- /tmp
|
||||
- /data
|
||||
depends_on:
|
||||
s3:
|
||||
condition: service_healthy
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
# пик по пробе — 35 MiB, 0,76 с CPU
|
||||
cpus: "0.5"
|
||||
memory: 128M
|
||||
|
||||
# миграции — один раз до реплик, сами реплики их не запускают
|
||||
migrate:
|
||||
# образ собирает сервис api (make run_docker, make test_isolated)
|
||||
image: mtusi-messenger:lab5
|
||||
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:lab5
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
<<: [*db-env, *cache-env, *s3-env, *s3-api-keys-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
|
||||
# bucket и пользователь API есть до первого запроса
|
||||
s3-bootstrap:
|
||||
condition: service_completed_successfully
|
||||
# healthcheck — из образа; SIGKILL не раньше, чем через 10 с
|
||||
stop_grace_period: 10s
|
||||
# буфер приёма сокетов реплики — до 512 KiB, а не до 32 MiB ВМ Docker:
|
||||
# ядро копит недочитанное тело (ожидание места загрузки, отказ до тела)
|
||||
# в буфере сокета, и он считается памятью контейнера. Параметр сетевого
|
||||
# пространства контейнера — его получают все контейнеры сервиса, в том
|
||||
# числе bench/, make test_isolated и стенд отказов (design change
|
||||
# upload-memory, решение 6). В консоли (make run_dev) его нет
|
||||
sysctls:
|
||||
net.ipv4.tcp_rmem: "4096 131072 524288"
|
||||
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
|
||||
|
||||
# уборщик незавершённых загрузок (design change upload-consistency,
|
||||
# решения 2 и 9): строки pending старше grace и их объекты. Один процесс
|
||||
# на образе API со своей командой; реплики его не ждут, сам он ждёт
|
||||
# схему и пользователя S3. Портов нет, HTTP не слушает
|
||||
cleaner:
|
||||
image: mtusi-messenger:lab5
|
||||
pull_policy: never
|
||||
# точка входа, а не command: разовый проход —
|
||||
# docker compose run --rm --no-deps cleaner --once
|
||||
entrypoint: ["python", "-m", "src.cleaner"]
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
<<: [*db-env, *s3-env]
|
||||
# проход последовательный: второе соединение не нужно
|
||||
DATABASE__POOL_SIZE: "1"
|
||||
# пользователь уборщика: чтение и удаление объектов, без записи и
|
||||
# списка; ключей API, пароля Valkey и административных ключей S3 нет
|
||||
S3__ACCESS_KEY_ID: ${S3_CLEANER_ACCESS_KEY:?S3_CLEANER_ACCESS_KEY is empty, run make env_setup}
|
||||
S3__SECRET_ACCESS_KEY: ${S3_CLEANER_SECRET_KEY:?S3_CLEANER_SECRET_KEY is empty, run make env_setup}
|
||||
volumes:
|
||||
- *config-toml
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
migrate:
|
||||
condition: service_completed_successfully
|
||||
s3-bootstrap:
|
||||
condition: service_completed_successfully
|
||||
# healthcheck образа — HTTP /health/ready, а уборщик HTTP не слушает.
|
||||
# Живость — журнал: старт, проходы, отказы
|
||||
healthcheck:
|
||||
disable: true
|
||||
# SIGTERM: текущая строка доводится (≤ 6 с), затем выход с кодом 0
|
||||
stop_grace_period: 10s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: "0.25"
|
||||
memory: 256M
|
||||
|
||||
# relay (design change pipeline-reliability, решения 1 и 2): доводит намерения
|
||||
# из PostgreSQL до брокера, возвращает истёкшие аренды. Один процесс на образе
|
||||
# API; реплики его не ждут: без него загрузка отвечает 202, задания ждут в
|
||||
# PostgreSQL. Разовая команда реестра — make replay (docker compose run --rm
|
||||
# --no-deps relay replay …). Портов нет, HTTP не слушает
|
||||
relay:
|
||||
image: mtusi-messenger:lab5
|
||||
pull_policy: never
|
||||
# точка входа, а не command: аргументы после имени сервиса — подкоманда
|
||||
entrypoint: ["python", "-m", "src.relay"]
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
# только PostgreSQL и брокер: ни ключей S3, ни пароля Valkey
|
||||
<<: [*db-env, *broker-env]
|
||||
# проход последовательный: второе соединение не нужно
|
||||
DATABASE__POOL_SIZE: "1"
|
||||
volumes:
|
||||
- *config-toml
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
rabbitmq:
|
||||
condition: service_healthy
|
||||
migrate:
|
||||
condition: service_completed_successfully
|
||||
# healthcheck образа — HTTP /health/ready, а relay HTTP не слушает. Живость
|
||||
# — журнал и очередь
|
||||
healthcheck:
|
||||
disable: true
|
||||
# SIGTERM: текущий шаг доводится (≤ 6 с), затем выход с кодом 0
|
||||
stop_grace_period: 10s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: "0.25"
|
||||
memory: 256M
|
||||
|
||||
# worker обработки вложений (design change async-attachments, решение 6):
|
||||
# отдельный процесс на образе API; декодирование и варианты — в процессе
|
||||
# обработки на задание, ни у реплик, ни в самом worker декодера нет
|
||||
# (pipeline-reliability, решение 7). Портов нет, HTTP не слушает; реплики его
|
||||
# не ждут
|
||||
worker:
|
||||
image: mtusi-messenger:lab5
|
||||
pull_policy: never
|
||||
entrypoint: ["python", "-m", "src.worker"]
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
<<: [*db-env, *s3-env, *broker-env]
|
||||
# шаги с БД короткие: соединение на задание
|
||||
DATABASE__POOL_SIZE: "2"
|
||||
# пользователь worker: чтение и запись объектов, без удаления и
|
||||
# списка; ключей API и уборщика, пароля Valkey и административных
|
||||
# ключей S3 нет
|
||||
S3__ACCESS_KEY_ID: ${S3_WORKER_ACCESS_KEY:?S3_WORKER_ACCESS_KEY is empty, run make env_setup}
|
||||
S3__SECRET_ACCESS_KEY: ${S3_WORKER_SECRET_KEY:?S3_WORKER_SECRET_KEY is empty, run make env_setup}
|
||||
volumes:
|
||||
- *config-toml
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
rabbitmq:
|
||||
condition: service_healthy
|
||||
migrate:
|
||||
condition: service_completed_successfully
|
||||
s3-bootstrap:
|
||||
condition: service_completed_successfully
|
||||
# healthcheck образа — HTTP /health/ready, а worker HTTP не слушает.
|
||||
# Живость — журнал и очередь
|
||||
healthcheck:
|
||||
disable: true
|
||||
# SIGTERM: начатые задания ждут ≤ [worker] graceful_shutdown_seconds,
|
||||
# закрытие клиентов — в сумме не больше 9,5 с
|
||||
stop_grace_period: 10s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
# два процесса обработки PNG RGBA на 40 Мпкс: ~360 МиБ VmHWM на
|
||||
# процесс, вместе с worker и телами меньше лимита при конкуренции 2
|
||||
# (расчёт — REPORT.md); лимит адресного пространства процесса — 450 МиБ
|
||||
cpus: "1.0"
|
||||
memory: 1G
|
||||
|
||||
# единственная точка входа: реплики находит через 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:
|
||||
s3_data:
|
||||
rabbitmq_data:
|
||||
@@ -0,0 +1,50 @@
|
||||
# Согласованность БД и S3 на рабочем стенде
|
||||
|
||||
- Команда: `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 upload-consistency`
|
||||
- Дата: 2026-10-31, 13:26:56–13:27:41 UTC; код выхода 0
|
||||
- Commit: `e2a6427` (ветка `feat/pipeline-reliability`), рабочее дерево без правок кода (добавлены только файлы `evidence/`)
|
||||
- Стенд: проект compose `mtusi-lab5`, собран `make run_docker` из `HEAD`
|
||||
- Что показано: загрузка при замороженном S3 и со сбоем фиксации `queued` — 503; строки `pending` не видны (404); компенсация удалила объект staging; `cleaner --once` с grace 30 с убрал обе строки и объекты по ключу staging; тот же проход убрал staging готового R (с уровня 4: `removed_ready`, `staging_key` пуст); объектов без строки нет; R цело
|
||||
- Вывод сокращён: записи уборщика — только основные поля
|
||||
|
||||
```text
|
||||
upload with paused S3: 503 after 5.1 s
|
||||
pending af17a40f-983c-4625-a2c0-a8488750a7cb: pending age 5 s key messenger/attachments/af17a40f-983c-4625-a2c0-a8488750a7cb/original
|
||||
pending bf78eca6-fcb5-4498-9306-3702cce10ab6: pending age 0 s key messenger/attachments/bf78eca6-fcb5-4498-9306-3702cce10ab6/original
|
||||
waiting 30 s for grace 30 s
|
||||
cleaner --once (grace 30 s): exit 0
|
||||
Started cleaner: mode once, interval_seconds 60.0, pending_grace_seconds 30, batch_size 100, staging_retention_seconds 86400, live_upload_bound_seconds 17.0
|
||||
Removed stale attachment: af17a40f-983c-4625-a2c0-a8488750a7cb
|
||||
Removed stale attachment: bf78eca6-fcb5-4498-9306-3702cce10ab6
|
||||
Finished cleanup pass: removed 2, skipped 0, interrupted_by null, duration_ms 221
|
||||
Finished staging cleanup pass: removed_ready 2, removed_failed 0, skipped 0, interrupted_by null, duration_ms 84
|
||||
Stopped cleaner: exit_code 0
|
||||
bucket messenger, prefix messenger/: 2428 objects, 2432 rows, 0 objects without a row
|
||||
attachment R uploaded expected 202 got 202
|
||||
attachment R processed expected ready got ready
|
||||
upload with paused S3 expected 503 got 503
|
||||
new pending rows (paused) expected 1 got 1
|
||||
upload with queued failure expected 503 got 503
|
||||
new pending rows (queued failure) expected 1 got 1
|
||||
staging object after compensation expected absent got absent
|
||||
staging object of the paused upload expected absent got absent
|
||||
driver trigger left expected 0 got 0
|
||||
metadata of pending af17a40f expected 404 got 404
|
||||
content of pending af17a40f expected 404 got 404
|
||||
message with af17a40f expected 404 got 404
|
||||
metadata of pending bf78eca6 expected 404 got 404
|
||||
content of pending bf78eca6 expected 404 got 404
|
||||
message with bf78eca6 expected 404 got 404
|
||||
cleaner --once exit code expected 0 got 0
|
||||
R staging_key after the pass expected NULL got NULL
|
||||
R metadata unchanged expected yes got yes
|
||||
row of af17a40f expected absent got absent
|
||||
object of af17a40f expected absent got absent
|
||||
row of bf78eca6 expected absent got absent
|
||||
object of bf78eca6 expected absent got absent
|
||||
objects without a row expected 0 got 0
|
||||
R staging object after the pass expected absent got absent
|
||||
R downloaded expected 200 got 200
|
||||
R sha256 = uploaded expected yes got yes
|
||||
PASS: pending rows are invisible, the queued failure is compensated, the cleaner removed both uploads, no object without a row, R intact
|
||||
```
|
||||
@@ -0,0 +1,105 @@
|
||||
# Шаг 4 сценария защиты: окна отказа
|
||||
|
||||
- Команда: `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 defense-faults`
|
||||
- Дата: 2026-10-31, 20:42:18–20:44:28 UTC; код выхода 0, итог `PASS`
|
||||
- Commit: `6ba74b1` (ветка `feat/unit-of-work`), рабочее дерево без правок кода (добавлены только файлы `evidence/`)
|
||||
- Стенд: проект compose `mtusi-lab5`, собран `make run_docker` из `HEAD`: HAProxy, две реплики API, relay, worker, cleaner, PostgreSQL, Valkey, S3, RabbitMQ
|
||||
- Спек: `student-tests`, «Шаг 4 на рабочем стенде»; решения 1, 3, 5, 14, 17 design change `pipeline-reliability`. Особенности транзакций перенесены на единицу работы без изменения порядка (design change `unit-of-work`, решение 10)
|
||||
- Точек сбоя в коде нет: окна держат триггеры `driver_df_*` только на уникальный `filename` прогона, `docker kill` снаружи. Токенов и секретов в выводе нет
|
||||
- Вывод сокращён: оставлена итоговая таблица «ожидаемо → получено»; строки скачивания вариантов свёрнуты (в каждом окне и у каждого варианта: 200, тип, размеры по байтам, SHA-256 = метаданным: `thumbnail` 256×160 JPEG, `crop` 128×128 JPEG, `optimized` 320×200 WebP), значения SHA-256 и id сокращены до совпало. Все строки совпали, расхождений нет
|
||||
|
||||
```text
|
||||
window: after writing objects, before COMMIT
|
||||
queue empty before the window expected 0 got 0
|
||||
upload expected 202 got 202
|
||||
COMMIT of ready waits in the trigger expected yes got yes
|
||||
docker kill worker expected 0 got 0
|
||||
job state after kill expected processing got processing
|
||||
attempt after kill expected 1 got 1
|
||||
thumbnail, crop, optimized object written expected yes got yes
|
||||
docker start worker expected 0 got 0
|
||||
ready 70 s after the kill
|
||||
attachment status expected ready got ready
|
||||
next attempt not before the lease expired expected yes got yes
|
||||
variants in metadata expected crop,optimized,thumbnail got crop,optimized,thumbnail
|
||||
variants: same sha256 in S3 and in metadata совпало у трёх
|
||||
attempt expected 2 got 2
|
||||
job state expected succeeded got succeeded
|
||||
queue empty expected 0 got 0
|
||||
|
||||
window: after COMMIT, before ack
|
||||
queue empty before the window expected 0 got 0
|
||||
upload expected 202 got 202
|
||||
COMMIT waits in the deferred trigger expected yes got yes
|
||||
freeze worker expected 0 got 0
|
||||
job state while frozen expected succeeded got succeeded
|
||||
docker kill worker expected 0 got 0
|
||||
message returned to the queue (no ack) expected 1 got 1
|
||||
docker start worker expected 0 got 0
|
||||
redelivered: 'Skipped job message', finished expected yes got yes
|
||||
new attempts expected 0 got 0
|
||||
queue empty expected 0 got 0
|
||||
same updated_at совпало
|
||||
attempt expected 1 got 1
|
||||
metadata unchanged expected yes got yes
|
||||
|
||||
window: after COMMIT queued, before publish
|
||||
queue empty before the window expected 0 got 0
|
||||
docker kill relay expected 0 got 0
|
||||
relay stays down expected no got no
|
||||
upload expected 202 got 202
|
||||
job state expected queued got queued
|
||||
published_at expected None got None
|
||||
messages in the queue expected 0 got 0
|
||||
docker start relay expected 0 got 0
|
||||
attachment status expected ready got ready
|
||||
attempt expected 1 got 1
|
||||
|
||||
window: after broker confirm, before the mark
|
||||
queue empty before the window expected 0 got 0
|
||||
upload expected 202 got 202
|
||||
the mark waits in the trigger expected yes got yes
|
||||
docker kill relay expected 0 got 0
|
||||
message in the queue expected 1 got 1
|
||||
published_at expected None got None
|
||||
docker start relay expected 0 got 0
|
||||
two messages with the worker stopped expected 2 got 2
|
||||
docker start worker expected 0 got 0
|
||||
attachment status expected ready got ready
|
||||
queue empty expected 0 got 0
|
||||
attempt expected 1 got 1
|
||||
|
||||
window: replay of a failed job
|
||||
queue empty before the window expected 0 got 0
|
||||
upload expected 202 got 202
|
||||
put other bytes expected 0 got 0
|
||||
docker start worker expected 0 got 0
|
||||
attachment status expected failed got failed
|
||||
error_code expected processing_failed got processing_failed
|
||||
reason expected source_corrupted got source_corrupted
|
||||
registry names the job expected yes got yes
|
||||
registry changes nothing совпало
|
||||
put original bytes expected 0 got 0
|
||||
replay exit code expected 0 got 0
|
||||
'Replayed job' record expected yes got yes
|
||||
attachment status expected ready got ready
|
||||
download original expected 200 got 200
|
||||
original sha256 = uploaded совпало
|
||||
same job совпало
|
||||
attempt expected 2 got 2
|
||||
attempt_base expected 1 got 1
|
||||
audit совпало (operator driver-defense-faults, processing_failed, source_corrupted)
|
||||
|
||||
window: replay of a ready job
|
||||
upload expected 202 got 202
|
||||
attachment status expected ready got ready
|
||||
replay exit code expected 3 got 3
|
||||
refusal expected already_ready got already_ready
|
||||
metadata unchanged expected yes got yes
|
||||
job unchanged совпало
|
||||
audit records expected 0 got 0
|
||||
|
||||
end: driver triggers left expected 0 got 0
|
||||
PASS: every window finished with the same result, no duplicate effect
|
||||
worker and relay running at the end: yes
|
||||
```
|
||||
@@ -0,0 +1,57 @@
|
||||
# Сценарий защиты лабы 5
|
||||
|
||||
- Команда: `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 defense-scenario`
|
||||
- Дата: 2026-10-31, 13:23:21–13:24:00 UTC; код выхода 0
|
||||
- Commit: `e2a6427` (ветка `feat/pipeline-reliability`), рабочее дерево без правок кода (добавлены только файлы `evidence/`)
|
||||
- Стенд: проект compose `mtusi-lab5`, собран `make run_docker` из `HEAD`: HAProxy, две реплики API, relay, worker, cleaner, PostgreSQL, Valkey, S3, RabbitMQ
|
||||
- Порядок действий (`README.md`, «Сценарий защиты», шаги 1–3): worker остановлен → загрузка 202 → сообщение с вложением 201 → скачивание 409 → текст 201 → сообщение в очереди (его опубликовал relay), 0 потребителей → рестарт API и хранилищ с сохранением volumes → worker запущен → `ready`, оригинал и три варианта. Шаг 4 — `evidence/attachments/defense-faults.md`
|
||||
- Токенов и секретов в выводе нет; пользователи и чат синтетические
|
||||
- Вывод сокращён: итоговая таблица «проверка → ожидаемо → получено» (34 строки, все совпали) заменена её итогом
|
||||
|
||||
```text
|
||||
fixture sample.png: 111817 bytes, sha256 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
|
||||
docker compose stop worker: 0
|
||||
upload sample.png: 202
|
||||
attachment id 0a0fe6a1-5c32-4c53-905a-43b05c6234f1, via d7f1b8c394b9
|
||||
snapshot status: queued
|
||||
message with the attachment: 201
|
||||
message id 50bc7674-f224-41c1-b060-513cad06197b
|
||||
download before processing: 409
|
||||
text message: 201
|
||||
text message id 9c596523-2b5d-4529-9bf6-244e0e705056
|
||||
job in the queue before restart: yes
|
||||
queue consumers before restart: 0
|
||||
scripts/restart.sh: 0
|
||||
LB ready after restart: yes
|
||||
job in the queue after restart: yes
|
||||
metadata after restart (same session): 200
|
||||
status after restart: queued
|
||||
docker compose start worker: 0
|
||||
attachment status: ready
|
||||
download original: 200
|
||||
original sha256 = uploaded: yes
|
||||
variants in metadata: crop,optimized,thumbnail
|
||||
download thumbnail: 200
|
||||
thumbnail content type: image/jpeg
|
||||
thumbnail size by bytes: (256, 160)
|
||||
thumbnail sha256 = metadata: yes
|
||||
download crop: 200
|
||||
crop content type: image/jpeg
|
||||
crop size by bytes: (128, 128)
|
||||
crop sha256 = metadata: yes
|
||||
download optimized: 200
|
||||
optimized content type: image/webp
|
||||
optimized size by bytes: (320, 200)
|
||||
optimized sha256 = metadata: yes
|
||||
relay StartedAt unchanged: yes
|
||||
history after restart: 200
|
||||
history keeps both messages: yes
|
||||
containers: StartedAt before -> after
|
||||
mtusi-lab5-api-10: 2026-10-31T13:20:34.275408667Z -> 2026-10-31T13:23:49.132257549Z
|
||||
mtusi-lab5-api-9: 2026-10-31T13:20:34.192033042Z -> 2026-10-31T13:23:49.056454424Z
|
||||
mtusi-lab5-rabbitmq-1: 2026-10-31T13:20:26.063079844Z -> 2026-10-31T13:23:26.563060594Z
|
||||
api and rabbitmq restarted: expected yes, got yes
|
||||
all rows of the check table: expected = got
|
||||
PASS: the file is accepted while the worker is stopped and becomes ready after the restart
|
||||
worker and relay running at the end: yes
|
||||
```
|
||||
@@ -0,0 +1,48 @@
|
||||
# Принявшая реплика остановлена
|
||||
|
||||
- Команда: `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 attachment-failover --mode stop`, затем то же с `--mode kill` (`make replicas` драйвер выполняет сам в `finally`)
|
||||
- Дата: 2026-10-31, 13:26:45–13:26:56 UTC; оба прогона — код выхода 0
|
||||
- Commit: `e2a6427` (ветка `feat/pipeline-reliability`), рабочее дерево без правок кода (добавлены только файлы `evidence/`)
|
||||
- Стенд: проект compose `mtusi-lab5`, собран `make run_docker` из `HEAD`
|
||||
- Сценарий: `attachments` «Принявшая реплика остановлена»
|
||||
- Вывод сокращён: убраны снимки `docker compose ps` до и после (все сервисы `Up`, реплики `healthy`)
|
||||
|
||||
## `stop`
|
||||
|
||||
```text
|
||||
mode: stop; fixture sample.png: 111817 bytes
|
||||
sha256 uploaded: 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
|
||||
sha256 downloaded: 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
|
||||
step expected got x-instance-id
|
||||
alice uploads 202 202 d7f1b8c394b9
|
||||
attachment is ready ready ready
|
||||
alice sends message 201 201 e933a5daf6b3
|
||||
stop-one.sh stop 0 0 d7f1b8c394b9
|
||||
bob downloads 200 200 e933a5daf6b3
|
||||
bob reads metadata 200 200 e933a5daf6b3
|
||||
eve reads metadata 404 404 e933a5daf6b3
|
||||
eve downloads 404 404 e933a5daf6b3
|
||||
make replicas 0 0
|
||||
LB slots UP 2 2
|
||||
PASS: accepted by d7f1b8c394b9, served by e933a5daf6b3 after stop, sha256 matches, outsider gets 404
|
||||
```
|
||||
|
||||
## `kill`
|
||||
|
||||
```text
|
||||
mode: kill; fixture sample.png: 111817 bytes
|
||||
sha256 uploaded: 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
|
||||
sha256 downloaded: 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
|
||||
step expected got x-instance-id
|
||||
alice uploads 202 202 d7f1b8c394b9
|
||||
attachment is ready ready ready
|
||||
alice sends message 201 201 d7f1b8c394b9
|
||||
stop-one.sh kill 0 0 d7f1b8c394b9
|
||||
bob downloads 200 200 e933a5daf6b3
|
||||
bob reads metadata 200 200 e933a5daf6b3
|
||||
eve reads metadata 404 404 e933a5daf6b3
|
||||
eve downloads 404 404 e933a5daf6b3
|
||||
make replicas 0 0
|
||||
LB slots UP 2 2
|
||||
PASS: accepted by d7f1b8c394b9, served by e933a5daf6b3 after kill, sha256 matches, outsider gets 404
|
||||
```
|
||||
@@ -0,0 +1,103 @@
|
||||
# Вложения: метаданные, байты и ограничения обработки
|
||||
|
||||
- Команда: `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 attachment-storage`
|
||||
- Дата: 2026-10-31, 13:26:32 UTC; код выхода 0
|
||||
- Commit: `e2a6427` (ветка `feat/pipeline-reliability`), рабочее дерево без правок кода (добавлены только файлы `evidence/`)
|
||||
- Стенд: проект compose `mtusi-lab5`, собран `make run_docker` из `HEAD`
|
||||
- Сценарии: `attachments` «Байты не в БД и не на диске API», `data-storage` «Ограничения обработки в схеме» (пробы в откатываемой транзакции, с уровня 4 — ещё запись аудита с неизвестным заданием)
|
||||
- Вывод сокращён: таблица второго вложения повторяет первую и совпала с ожидаемым
|
||||
|
||||
```text
|
||||
columns of attachment tables:
|
||||
attachment_job_replays id uuid
|
||||
attachment_job_replays job_id uuid
|
||||
attachment_job_replays operator text
|
||||
attachment_job_replays error_code text
|
||||
attachment_job_replays reason text
|
||||
attachment_job_replays attempt integer
|
||||
attachment_job_replays created_at timestamp with time zone
|
||||
attachment_jobs id uuid
|
||||
attachment_jobs attachment_id uuid
|
||||
attachment_jobs pipeline_version integer
|
||||
attachment_jobs state text
|
||||
attachment_jobs attempt integer
|
||||
attachment_jobs last_error_code text
|
||||
attachment_jobs next_attempt_at timestamp with time zone
|
||||
attachment_jobs lease_expires_at timestamp with time zone
|
||||
attachment_jobs published_at timestamp with time zone
|
||||
attachment_jobs updated_at timestamp with time zone
|
||||
attachment_jobs finished_at timestamp with time zone
|
||||
attachment_jobs created_at timestamp with time zone
|
||||
attachment_jobs attempt_base integer
|
||||
attachment_variants attachment_id uuid
|
||||
attachment_variants pipeline_version integer
|
||||
attachment_variants variant text
|
||||
attachment_variants object_key text
|
||||
attachment_variants content_type text
|
||||
attachment_variants size_bytes integer
|
||||
attachment_variants width integer
|
||||
attachment_variants height integer
|
||||
attachment_variants sha256 bytea
|
||||
attachment_variants created_at timestamp with time zone
|
||||
attachments id uuid
|
||||
attachments chat_id uuid
|
||||
attachments owner_id uuid
|
||||
attachments filename text
|
||||
attachments content_type text
|
||||
attachments size_bytes integer
|
||||
attachments sha256 bytea
|
||||
attachments object_key text
|
||||
attachments status text
|
||||
attachments updated_at timestamp with time zone
|
||||
attachments created_at timestamp with time zone
|
||||
attachments lost_at timestamp with time zone
|
||||
attachments staging_key text
|
||||
attachments error_code text
|
||||
message_attachments message_id uuid
|
||||
message_attachments position smallint
|
||||
message_attachments attachment_id uuid
|
||||
message_attachments created_at timestamp with time zone
|
||||
upload via d7f1b8c394b9: object_key messenger/attachments/03924317-901e-49db-bcf4-6995c907e1d4/original, staging_key messenger/staging/03924317-901e-49db-bcf4-6995c907e1d4/original
|
||||
sha256 uploaded 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75, downloaded by a member (200) 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
|
||||
upload via e933a5daf6b3: object_key messenger/attachments/516e7758-6489-4538-a004-6439aae23035/original, staging_key messenger/staging/516e7758-6489-4538-a004-6439aae23035/original
|
||||
sha256 uploaded 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75, downloaded by a member (200) 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
|
||||
constraint probes (rolled back):
|
||||
second job of the version: 23505 uq_attachment_jobs_attachment_id_pipeline_version
|
||||
second variant of the name: 23505 pk_attachment_variants
|
||||
error_code on not failed: 23514 ck_attachments_error_code_failed
|
||||
replay audit of an unknown job: 23503 fk_attachment_job_replays_job_id_attachment_jobs
|
||||
docker diff e933a5daf6b3: 2 changes
|
||||
C /app
|
||||
A /app/config.toml
|
||||
docker diff d7f1b8c394b9: 2 changes
|
||||
C /app
|
||||
A /app/config.toml
|
||||
docker diff ecbefb38ea10: 2 changes
|
||||
C /app
|
||||
A /app/config.toml
|
||||
bytea columns expected attachment_variants.sha256,attachments.sha256 got attachment_variants.sha256,attachments.sha256
|
||||
octet_length(sha256) expected 32 got 32
|
||||
object_key form expected messenger/attachments/03924317-901e-49db-bcf4-6995c907e1d4/original got messenger/attachments/03924317-901e-49db-bcf4-6995c907e1d4/original
|
||||
staging_key: its form or already empty expected yes got yes
|
||||
filename not in key expected no got no
|
||||
variant rows expected crop,optimized,thumbnail got crop,optimized,thumbnail
|
||||
crop in bucket expected yes got yes
|
||||
anonymous GET of crop expected 403 got 403
|
||||
optimized in bucket expected yes got yes
|
||||
anonymous GET of optimized expected 403 got 403
|
||||
thumbnail in bucket expected yes got yes
|
||||
anonymous GET of thumbnail expected 403 got 403
|
||||
object in bucket, bytes expected 111817 got 111817
|
||||
anonymous GET of the key expected 403 got 403
|
||||
downloaded sha256 = uploaded expected yes got yes
|
||||
probe: second job of the version expected 23505 uq_attachment_jobs_attachment_id_pipeline_version got 23505 uq_attachment_jobs_attachment_id_pipeline_version
|
||||
probe: second variant of the name expected 23505 pk_attachment_variants got 23505 pk_attachment_variants
|
||||
probe: error_code on not failed expected 23514 ck_attachments_error_code_failed got 23514 ck_attachments_error_code_failed
|
||||
probe: replay audit of an unknown job expected 23503 fk_attachment_job_replays_job_id_attachment_jobs got 23503 fk_attachment_job_replays_job_id_attachment_jobs
|
||||
jobs | variants after the probes expected 1|3 got 1|3
|
||||
original files in e933a5daf6b3 expected 0 got 0
|
||||
original files in d7f1b8c394b9 expected 0 got 0
|
||||
original files in ecbefb38ea10 expected 0 got 0
|
||||
sha256 of the fixture: 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
|
||||
PASS: metadata in PostgreSQL, bytes only in the private bucket messenger, none in the API containers
|
||||
```
|
||||
@@ -0,0 +1,19 @@
|
||||
# Хранение паролей и токенов
|
||||
|
||||
- Команда: `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 auth-storage`
|
||||
- Дата: 2026-11-01, 10:33:45–10:33:46 UTC; код выхода 0
|
||||
- Commit: `9639aa1` (ветка `feat/track1-queue-overload`), код `src/` и `bench/` тот же, что на `5ee3257`; на рабочем дереве изменён только `.claude/skills/run-mtusi-messenger/driver.py`, команда `auth-storage` не менялась
|
||||
- Стенд: проект compose `mtusi-lab5`, две реплики за HAProxy, собран `make run_docker` из `HEAD`; пользователи синтетические, пароль и токен только в памяти драйвера, в вывод не попадают
|
||||
- Спеки: `users`, «Хэш в БД», `sessions`, «Токена нет в хранилище» (исключения сверки покрытия: схема и дамп по HTTP не видны)
|
||||
|
||||
Итог: в `users` — строки Argon2id с разной солью у одного пароля, в `sessions` — только SHA-256 токена (32 байта); ни токена (текстом и в hex), ни пароля в `pg_dump --data-only` нет.
|
||||
|
||||
```text
|
||||
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: 12 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,0 +1,673 @@
|
||||
# План запроса истории: размер 10k
|
||||
|
||||
Commit b2fb88f
|
||||
Читаемый чат — 10000 сообщений; фоновые чаты: 2 × 1k, 10 × 100, 50 × 10.
|
||||
Страница — `limit` профиля; «после» — сколько сообщений чата до
|
||||
страницы.
|
||||
|
||||
## Планы приложения
|
||||
|
||||
auto_explain (ANALYZE, BUFFERS, TIMING): запрос, параметры и план,
|
||||
с которыми его выполнило приложение (prepared statement asyncpg).
|
||||
|
||||
### read 10k: first, после 0
|
||||
|
||||
duration: 0.184 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee', $2 = '51'
|
||||
Limit (cost=0.29..9.59 rows=51 width=153) (actual time=0.042..0.140 rows=51.00 loops=1)
|
||||
Buffers: shared hit=17
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..1825.36 rows=10000 width=153) (actual time=0.040..0.135 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=17
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### read 10k: middle, после 5000
|
||||
|
||||
duration: 0.146 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee', $2 = '2026-10-31 20:22:09.184908+00', $3 = 'e12757c1-c860-44ed-8d49-05bd9ef9ed8a', $4 = '51'
|
||||
Limit (cost=0.29..21.79 rows=7 width=153) (actual time=0.032..0.107 rows=51.00 loops=1)
|
||||
Buffers: shared hit=53
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..218.45 rows=71 width=153) (actual time=0.030..0.103 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=53
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### read 10k: last, после 9900
|
||||
|
||||
duration: 0.144 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee', $2 = '2026-10-31 20:22:20.445692+00', $3 = 'ff794cf6-13c4-4816-a97e-ef0fc4ef4326', $4 = '51'
|
||||
Limit (cost=0.29..21.79 rows=7 width=153) (actual time=0.031..0.113 rows=51.00 loops=1)
|
||||
Buffers: shared hit=54
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..218.45 rows=71 width=153) (actual time=0.030..0.109 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=54
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: first, после 0
|
||||
|
||||
duration: 0.150 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '8b619ecf-de9e-4043-8b20-40346656f7ba', $2 = '51'
|
||||
Limit (cost=0.29..54.04 rows=51 width=153) (actual time=0.033..0.117 rows=51.00 loops=1)
|
||||
Buffers: shared hit=46
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..1054.25 rows=1000 width=153) (actual time=0.033..0.114 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '8b619ecf-de9e-4043-8b20-40346656f7ba'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=46
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: middle, после 500
|
||||
|
||||
duration: 0.185 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = '8b619ecf-de9e-4043-8b20-40346656f7ba', $2 = '2026-10-31 20:22:09.183192+00', $3 = '6c079c72-956b-4d22-902d-50525cd17715', $4 = '51'
|
||||
Limit (cost=0.29..21.79 rows=7 width=153) (actual time=0.023..0.140 rows=51.00 loops=1)
|
||||
Buffers: shared hit=52
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..218.45 rows=71 width=153) (actual time=0.022..0.137 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=52
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: last, после 900
|
||||
|
||||
duration: 0.126 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = '8b619ecf-de9e-4043-8b20-40346656f7ba', $2 = '2026-10-31 20:22:18.306084+00', $3 = '20861ffc-3d7f-413e-a417-26cec0b4dcb3', $4 = '51'
|
||||
Limit (cost=0.29..21.79 rows=7 width=153) (actual time=0.016..0.096 rows=51.00 loops=1)
|
||||
Buffers: shared hit=47
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..218.45 rows=71 width=153) (actual time=0.016..0.093 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=47
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 100: first, после 0
|
||||
|
||||
duration: 0.165 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '2c89c970-25a2-4db8-be56-14a7e9aa8283', $2 = '51'
|
||||
Limit (cost=0.29..151.02 rows=51 width=153) (actual time=0.013..0.134 rows=51.00 loops=1)
|
||||
Buffers: shared hit=48
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..295.85 rows=100 width=153) (actual time=0.013..0.131 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '2c89c970-25a2-4db8-be56-14a7e9aa8283'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=48
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 10: first, после 0
|
||||
|
||||
duration: 0.073 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = 'd96f0cdc-62d0-4949-b4e8-9f94e470ece5', $2 = '51'
|
||||
Limit (cost=0.29..38.25 rows=10 width=153) (actual time=0.028..0.065 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..38.25 rows=10 width=153) (actual time=0.027..0.064 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = 'd96f0cdc-62d0-4949-b4e8-9f94e470ece5'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=12
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.002..0.002 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
## Страницы сравнения в psql: варианты
|
||||
|
||||
Тот же текст запроса и те же параметры, что у плана приложения этой
|
||||
страницы, в одной транзакции, которая откатывается: индексы базы
|
||||
после неё те же. Каждый вариант выполнен дважды, здесь — второе
|
||||
выполнение. `psql` — индекс приложения, custom plan; `generic` — он
|
||||
же с force_generic_plan; `or-cursor` — условие курсора через OR;
|
||||
`no-index` — без индекса приложения; варианты индекса вместо него:
|
||||
`chat_only` (chat_id), `covering` (chat_id, created_at, id) INCLUDE (sender_id, text).
|
||||
|
||||
### read 10k: middle, после 5000
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.29..14.64 rows=51 width=153) (actual time=0.006..0.057 rows=51.00 loops=1)
|
||||
Buffers: shared hit=53
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..1408.11 rows=5000 width=153) (actual time=0.005..0.053 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:22:09.184908+00'::timestamp with time zone, 'e12757c1-c860-44ed-8d49-05bd9ef9ed8a'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=53
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.044 ms
|
||||
Execution Time: 0.065 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.29..21.79 rows=7 width=153) (actual time=0.014..0.065 rows=51.00 loops=1)
|
||||
Buffers: shared hit=53
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..218.45 rows=71 width=153) (actual time=0.014..0.062 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=53
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.011 ms
|
||||
Execution Time: 0.077 ms
|
||||
|
||||
#### or-cursor
|
||||
|
||||
Limit (cost=0.29..18.90 rows=51 width=153) (actual time=0.720..0.763 rows=51.00 loops=1)
|
||||
Buffers: shared hit=5063
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..1825.36 rows=5000 width=153) (actual time=0.720..0.760 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee'::uuid)
|
||||
Filter: ((created_at > '2026-10-31 20:22:09.184908+00'::timestamp with time zone) OR ((created_at = '2026-10-31 20:22:09.184908+00'::timestamp with time zone) AND (id > 'e12757c1-c860-44ed-8d49-05bd9ef9ed8a'::uuid)))
|
||||
Rows Removed by Filter: 5000
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=5063
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.061 ms
|
||||
Execution Time: 0.779 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=771.06..771.19 rows=51 width=153) (actual time=3.982..3.986 rows=51.00 loops=1)
|
||||
Buffers: shared hit=293
|
||||
-> Sort (cost=771.06..783.56 rows=5000 width=153) (actual time=3.982..3.984 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 44kB
|
||||
Buffers: shared hit=293
|
||||
-> Seq Scan on messages (cost=0.00..604.25 rows=5000 width=153) (actual time=0.224..3.444 rows=5000.00 loops=1)
|
||||
Filter: ((chat_id = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:22:09.184908+00'::timestamp with time zone, 'e12757c1-c860-44ed-8d49-05bd9ef9ed8a'::uuid)))
|
||||
Rows Removed by Filter: 8500
|
||||
Buffers: shared hit=293
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=5000)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=5000)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.069 ms
|
||||
Execution Time: 3.995 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=771.06..771.19 rows=51 width=153) (actual time=3.710..3.713 rows=51.00 loops=1)
|
||||
Buffers: shared hit=293
|
||||
-> Sort (cost=771.06..783.56 rows=5000 width=153) (actual time=3.710..3.711 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 44kB
|
||||
Buffers: shared hit=293
|
||||
-> Seq Scan on messages (cost=0.00..604.25 rows=5000 width=153) (actual time=0.208..3.168 rows=5000.00 loops=1)
|
||||
Filter: ((chat_id = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:22:09.184908+00'::timestamp with time zone, 'e12757c1-c860-44ed-8d49-05bd9ef9ed8a'::uuid)))
|
||||
Rows Removed by Filter: 8500
|
||||
Buffers: shared hit=293
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=5000)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=5000)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.037 ms
|
||||
Execution Time: 3.719 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.41..6.19 rows=51 width=153) (actual time=0.007..0.044 rows=51.00 loops=1)
|
||||
Buffers: shared hit=5
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.41..567.41 rows=5000 width=153) (actual time=0.006..0.041 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = 'e7f0a7ce-371e-41c8-8b8c-182d863d4eee'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:22:09.184908+00'::timestamp with time zone, 'e12757c1-c860-44ed-8d49-05bd9ef9ed8a'::uuid)))
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=5
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.048 ms
|
||||
Execution Time: 0.052 ms
|
||||
|
||||
### bg 1k: middle, после 500
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.29..95.89 rows=51 width=153) (actual time=0.006..0.049 rows=51.00 loops=1)
|
||||
Buffers: shared hit=52
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..937.55 rows=500 width=153) (actual time=0.006..0.046 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '8b619ecf-de9e-4043-8b20-40346656f7ba'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:22:09.183192+00'::timestamp with time zone, '6c079c72-956b-4d22-902d-50525cd17715'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=52
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.041 ms
|
||||
Execution Time: 0.057 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.29..21.79 rows=7 width=153) (actual time=0.012..0.061 rows=51.00 loops=1)
|
||||
Buffers: shared hit=52
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..218.45 rows=71 width=153) (actual time=0.011..0.058 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=52
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.009 ms
|
||||
Execution Time: 0.072 ms
|
||||
|
||||
#### or-cursor
|
||||
|
||||
Limit (cost=0.29..107.79 rows=51 width=153) (actual time=0.083..0.121 rows=51.00 loops=1)
|
||||
Buffers: shared hit=502
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..1054.25 rows=500 width=153) (actual time=0.083..0.119 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '8b619ecf-de9e-4043-8b20-40346656f7ba'::uuid)
|
||||
Filter: ((created_at > '2026-10-31 20:22:09.183192+00'::timestamp with time zone) OR ((created_at = '2026-10-31 20:22:09.183192+00'::timestamp with time zone) AND (id > '6c079c72-956b-4d22-902d-50525cd17715'::uuid)))
|
||||
Rows Removed by Filter: 500
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=502
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.076 ms
|
||||
Execution Time: 0.129 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=553.43..553.56 rows=51 width=153) (actual time=0.666..0.669 rows=51.00 loops=1)
|
||||
Buffers: shared hit=293
|
||||
-> Sort (cost=553.43..554.68 rows=500 width=153) (actual time=0.666..0.667 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 39kB
|
||||
Buffers: shared hit=293
|
||||
-> Seq Scan on messages (cost=0.00..536.75 rows=500 width=153) (actual time=0.192..0.613 rows=500.00 loops=1)
|
||||
Filter: ((chat_id = '8b619ecf-de9e-4043-8b20-40346656f7ba'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:22:09.183192+00'::timestamp with time zone, '6c079c72-956b-4d22-902d-50525cd17715'::uuid)))
|
||||
Rows Removed by Filter: 13000
|
||||
Buffers: shared hit=293
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.066 ms
|
||||
Execution Time: 0.676 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=350.59..350.72 rows=51 width=153) (actual time=0.507..0.511 rows=51.00 loops=1)
|
||||
Buffers: shared hit=281
|
||||
-> Sort (cost=350.59..351.84 rows=500 width=153) (actual time=0.507..0.509 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 39kB
|
||||
Buffers: shared hit=281
|
||||
-> Bitmap Heap Scan on messages (cost=15.91..333.91 rows=500 width=153) (actual time=0.094..0.442 rows=500.00 loops=1)
|
||||
Recheck Cond: (chat_id = '8b619ecf-de9e-4043-8b20-40346656f7ba'::uuid)
|
||||
Filter: (ROW(created_at, id) > ROW('2026-10-31 20:22:09.183192+00'::timestamp with time zone, '6c079c72-956b-4d22-902d-50525cd17715'::uuid))
|
||||
Rows Removed by Filter: 500
|
||||
Heap Blocks: exact=278
|
||||
Buffers: shared hit=281
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..15.79 rows=1000 width=0) (actual time=0.022..0.022 rows=1000.00 loops=1)
|
||||
Index Cond: (chat_id = '8b619ecf-de9e-4043-8b20-40346656f7ba'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=3
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.042 ms
|
||||
Execution Time: 0.517 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.41..6.28 rows=51 width=153) (actual time=0.007..0.046 rows=51.00 loops=1)
|
||||
Buffers: shared hit=5
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.41..57.91 rows=500 width=153) (actual time=0.006..0.044 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '8b619ecf-de9e-4043-8b20-40346656f7ba'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:22:09.183192+00'::timestamp with time zone, '6c079c72-956b-4d22-902d-50525cd17715'::uuid)))
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=5
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.063 ms
|
||||
Execution Time: 0.054 ms
|
||||
|
||||
### bg 100: first, после 0
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.29..151.02 rows=51 width=153) (actual time=0.005..0.050 rows=51.00 loops=1)
|
||||
Buffers: shared hit=48
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..295.85 rows=100 width=153) (actual time=0.005..0.047 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '2c89c970-25a2-4db8-be56-14a7e9aa8283'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=48
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.044 ms
|
||||
Execution Time: 0.055 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.29..53.03 rows=21 width=153) (actual time=0.012..0.061 rows=51.00 loops=1)
|
||||
Buffers: shared hit=48
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..537.76 rows=214 width=153) (actual time=0.011..0.058 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = $1)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=48
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.005 ms
|
||||
Execution Time: 0.069 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=466.57..466.70 rows=51 width=153) (actual time=0.394..0.397 rows=51.00 loops=1)
|
||||
Buffers: shared hit=293
|
||||
-> Sort (cost=466.57..466.82 rows=100 width=153) (actual time=0.393..0.395 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=293
|
||||
-> Seq Scan on messages (cost=0.00..463.25 rows=100 width=153) (actual time=0.007..0.376 rows=100.00 loops=1)
|
||||
Filter: (chat_id = '2c89c970-25a2-4db8-be56-14a7e9aa8283'::uuid)
|
||||
Rows Removed by Filter: 13400
|
||||
Buffers: shared hit=293
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.037 ms
|
||||
Execution Time: 0.402 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=215.36..215.48 rows=51 width=153) (actual time=0.110..0.114 rows=51.00 loops=1)
|
||||
Buffers: shared hit=91
|
||||
-> Sort (cost=215.36..215.61 rows=100 width=153) (actual time=0.110..0.112 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=91
|
||||
-> Bitmap Heap Scan on messages (cost=5.06..212.03 rows=100 width=153) (actual time=0.011..0.097 rows=100.00 loops=1)
|
||||
Recheck Cond: (chat_id = '2c89c970-25a2-4db8-be56-14a7e9aa8283'::uuid)
|
||||
Heap Blocks: exact=89
|
||||
Buffers: shared hit=91
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..5.04 rows=100 width=0) (actual time=0.004..0.004 rows=100.00 loops=1)
|
||||
Index Cond: (chat_id = '2c89c970-25a2-4db8-be56-14a7e9aa8283'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.036 ms
|
||||
Execution Time: 0.120 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.41..6.15 rows=51 width=153) (actual time=0.005..0.042 rows=51.00 loops=1)
|
||||
Buffers: shared hit=5
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.41..11.66 rows=100 width=153) (actual time=0.005..0.040 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '2c89c970-25a2-4db8-be56-14a7e9aa8283'::uuid)
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=5
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.038 ms
|
||||
Execution Time: 0.049 ms
|
||||
|
||||
### bg 10: first, после 0
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.29..38.25 rows=10 width=153) (actual time=0.008..0.018 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..38.25 rows=10 width=153) (actual time=0.008..0.017 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = 'd96f0cdc-62d0-4949-b4e8-9f94e470ece5'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=12
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.061 ms
|
||||
Execution Time: 0.026 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.29..53.03 rows=21 width=153) (actual time=0.013..0.026 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..537.76 rows=214 width=153) (actual time=0.013..0.024 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = $1)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=12
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.006 ms
|
||||
Execution Time: 0.035 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=462.07..462.09 rows=10 width=153) (actual time=0.307..0.308 rows=10.00 loops=1)
|
||||
Buffers: shared hit=293
|
||||
-> Sort (cost=462.07..462.09 rows=10 width=153) (actual time=0.307..0.307 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=293
|
||||
-> Seq Scan on messages (cost=0.00..461.90 rows=10 width=153) (actual time=0.017..0.294 rows=10.00 loops=1)
|
||||
Filter: (chat_id = 'd96f0cdc-62d0-4949-b4e8-9f94e470ece5'::uuid)
|
||||
Rows Removed by Filter: 13490
|
||||
Buffers: shared hit=293
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.050 ms
|
||||
Execution Time: 0.313 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=33.48..33.50 rows=10 width=153) (actual time=0.019..0.021 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Sort (cost=33.48..33.50 rows=10 width=153) (actual time=0.019..0.020 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=12
|
||||
-> Index Scan using bench_variant on messages (cost=0.29..33.31 rows=10 width=153) (actual time=0.006..0.017 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = 'd96f0cdc-62d0-4949-b4e8-9f94e470ece5'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=12
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.066 ms
|
||||
Execution Time: 0.030 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.41..4.74 rows=10 width=153) (actual time=0.005..0.012 rows=10.00 loops=1)
|
||||
Buffers: shared hit=5
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.41..4.74 rows=10 width=153) (actual time=0.005..0.012 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = 'd96f0cdc-62d0-4949-b4e8-9f94e470ece5'::uuid)
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=5
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.040 ms
|
||||
Execution Time: 0.017 ms
|
||||
@@ -0,0 +1,731 @@
|
||||
# План запроса истории: размер 1k
|
||||
|
||||
Commit b2fb88f
|
||||
Читаемый чат — 1000 сообщений; фоновые чаты: 2 × 1k, 10 × 100, 50 × 10.
|
||||
Страница — `limit` профиля; «после» — сколько сообщений чата до
|
||||
страницы.
|
||||
|
||||
## Планы приложения
|
||||
|
||||
auto_explain (ANALYZE, BUFFERS, TIMING): запрос, параметры и план,
|
||||
с которыми его выполнило приложение (prepared statement asyncpg).
|
||||
|
||||
### read 1k: first, после 0
|
||||
|
||||
duration: 0.147 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = 'e89c392b-46c2-4a1d-a798-2ca1f4787398', $2 = '51'
|
||||
Limit (cost=0.28..24.74 rows=51 width=153) (actual time=0.040..0.113 rows=51.00 loops=1)
|
||||
Buffers: shared hit=32
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..479.84 rows=1000 width=153) (actual time=0.039..0.109 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=32
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### read 1k: middle, после 500
|
||||
|
||||
duration: 0.121 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = 'e89c392b-46c2-4a1d-a798-2ca1f4787398', $2 = '2026-10-31 20:19:42.570021+00', $3 = 'cb5ad463-2531-42b3-8858-75d9f4d51aa0', $4 = '51'
|
||||
Limit (cost=0.28..45.12 rows=51 width=153) (actual time=0.016..0.085 rows=51.00 loops=1)
|
||||
Buffers: shared hit=51
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..440.73 rows=501 width=153) (actual time=0.016..0.082 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:42.570021+00'::timestamp with time zone, 'cb5ad463-2531-42b3-8858-75d9f4d51aa0'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=51
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### read 1k: last, после 900
|
||||
|
||||
duration: 0.240 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = 'e89c392b-46c2-4a1d-a798-2ca1f4787398', $2 = '2026-10-31 20:19:45.708241+00', $3 = '10ad2de8-b01a-4b52-a049-d90b26b5aa5b', $4 = '51'
|
||||
Limit (cost=120.17..120.30 rows=51 width=153) (actual time=0.193..0.198 rows=51.00 loops=1)
|
||||
Buffers: shared hit=28
|
||||
-> Sort (cost=120.17..120.42 rows=100 width=153) (actual time=0.193..0.195 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=28
|
||||
-> Bitmap Heap Scan on messages (cost=9.31..116.85 rows=100 width=153) (actual time=0.029..0.144 rows=100.00 loops=1)
|
||||
Recheck Cond: ((chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:45.708241+00'::timestamp with time zone, '10ad2de8-b01a-4b52-a049-d90b26b5aa5b'::uuid)))
|
||||
Heap Blocks: exact=20
|
||||
Buffers: shared hit=22
|
||||
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..9.28 rows=100 width=0) (actual time=0.010..0.010 rows=100.00 loops=1)
|
||||
Index Cond: ((chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:45.708241+00'::timestamp with time zone, '10ad2de8-b01a-4b52-a049-d90b26b5aa5b'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: first, после 0
|
||||
|
||||
duration: 0.106 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3', $2 = '51'
|
||||
Limit (cost=0.28..24.74 rows=51 width=153) (actual time=0.010..0.078 rows=51.00 loops=1)
|
||||
Buffers: shared hit=37
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..479.84 rows=1000 width=153) (actual time=0.009..0.075 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=37
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: middle, после 500
|
||||
|
||||
duration: 0.105 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3', $2 = '2026-10-31 20:19:42.593379+00', $3 = '41e10366-ac36-468e-965e-54b7bd0290ce', $4 = '51'
|
||||
Limit (cost=0.28..45.38 rows=51 width=153) (actual time=0.012..0.075 rows=51.00 loops=1)
|
||||
Buffers: shared hit=53
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..440.63 rows=498 width=153) (actual time=0.011..0.072 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:42.593379+00'::timestamp with time zone, '41e10366-ac36-468e-965e-54b7bd0290ce'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=53
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: last, после 900
|
||||
|
||||
duration: 0.156 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3', $2 = '2026-10-31 20:19:45.714312+00', $3 = '630019db-1266-44cc-b5d6-fcb3edda0b30', $4 = '51'
|
||||
Limit (cost=120.09..120.21 rows=51 width=153) (actual time=0.125..0.130 rows=51.00 loops=1)
|
||||
Buffers: shared hit=18
|
||||
-> Sort (cost=120.09..120.33 rows=99 width=153) (actual time=0.125..0.127 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=18
|
||||
-> Bitmap Heap Scan on messages (cost=9.30..116.81 rows=99 width=153) (actual time=0.019..0.104 rows=100.00 loops=1)
|
||||
Recheck Cond: ((chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:45.714312+00'::timestamp with time zone, '630019db-1266-44cc-b5d6-fcb3edda0b30'::uuid)))
|
||||
Heap Blocks: exact=16
|
||||
Buffers: shared hit=18
|
||||
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..9.27 rows=99 width=0) (actual time=0.009..0.009 rows=100.00 loops=1)
|
||||
Index Cond: ((chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:45.714312+00'::timestamp with time zone, '630019db-1266-44cc-b5d6-fcb3edda0b30'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 100: first, после 0
|
||||
|
||||
duration: 0.231 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '3694cad0-8739-4553-ba44-604daaaa3382', $2 = '51'
|
||||
Limit (cost=119.42..119.55 rows=51 width=153) (actual time=0.197..0.201 rows=51.00 loops=1)
|
||||
Buffers: shared hit=64
|
||||
-> Sort (cost=119.42..119.67 rows=100 width=153) (actual time=0.197..0.199 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=64
|
||||
-> Bitmap Heap Scan on messages (cost=9.06..116.10 rows=100 width=153) (actual time=0.033..0.175 rows=100.00 loops=1)
|
||||
Recheck Cond: (chat_id = '3694cad0-8739-4553-ba44-604daaaa3382'::uuid)
|
||||
Heap Blocks: exact=62
|
||||
Buffers: shared hit=64
|
||||
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..9.03 rows=100 width=0) (actual time=0.010..0.010 rows=100.00 loops=1)
|
||||
Index Cond: (chat_id = '3694cad0-8739-4553-ba44-604daaaa3382'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 10: first, после 0
|
||||
|
||||
duration: 0.041 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '173df049-0e59-461f-afe3-8a15542fa0c5', $2 = '51'
|
||||
Limit (cost=35.36..35.39 rows=10 width=153) (actual time=0.036..0.037 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Sort (cost=35.36..35.39 rows=10 width=153) (actual time=0.036..0.036 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Heap Scan on messages (cost=4.36..35.20 rows=10 width=153) (actual time=0.014..0.032 rows=10.00 loops=1)
|
||||
Recheck Cond: (chat_id = '173df049-0e59-461f-afe3-8a15542fa0c5'::uuid)
|
||||
Heap Blocks: exact=10
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..4.36 rows=10 width=0) (actual time=0.005..0.005 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = '173df049-0e59-461f-afe3-8a15542fa0c5'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
## Страницы сравнения в psql: варианты
|
||||
|
||||
Тот же текст запроса и те же параметры, что у плана приложения этой
|
||||
страницы, в одной транзакции, которая откатывается: индексы базы
|
||||
после неё те же. Каждый вариант выполнен дважды, здесь — второе
|
||||
выполнение. `psql` — индекс приложения, custom plan; `generic` — он
|
||||
же с force_generic_plan; `or-cursor` — условие курсора через OR;
|
||||
`no-index` — без индекса приложения; варианты индекса вместо него:
|
||||
`chat_only` (chat_id), `covering` (chat_id, created_at, id) INCLUDE (sender_id, text).
|
||||
|
||||
### read 1k: middle, после 500
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.28..45.12 rows=51 width=153) (actual time=0.009..0.057 rows=51.00 loops=1)
|
||||
Buffers: shared hit=51
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..440.73 rows=501 width=153) (actual time=0.009..0.054 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:42.570021+00'::timestamp with time zone, 'cb5ad463-2531-42b3-8858-75d9f4d51aa0'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=51
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.048 ms
|
||||
Execution Time: 0.065 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.28..7.93 rows=2 width=153) (actual time=0.009..0.064 rows=51.00 loops=1)
|
||||
Buffers: shared hit=51
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..92.02 rows=24 width=153) (actual time=0.009..0.061 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=51
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.006 ms
|
||||
Execution Time: 0.072 ms
|
||||
|
||||
#### or-cursor
|
||||
|
||||
Limit (cost=0.28..49.10 rows=51 width=153) (actual time=0.085..0.131 rows=51.00 loops=1)
|
||||
Buffers: shared hit=525
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..479.86 rows=501 width=153) (actual time=0.085..0.128 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid)
|
||||
Filter: ((created_at > '2026-10-31 20:19:42.570021+00'::timestamp with time zone) OR ((created_at = '2026-10-31 20:19:42.570021+00'::timestamp with time zone) AND (id > 'cb5ad463-2531-42b3-8858-75d9f4d51aa0'::uuid)))
|
||||
Rows Removed by Filter: 500
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=525
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.046 ms
|
||||
Execution Time: 0.136 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=203.98..204.11 rows=51 width=153) (actual time=0.545..0.550 rows=51.00 loops=1)
|
||||
Buffers: shared hit=101
|
||||
-> Sort (cost=203.98..205.23 rows=501 width=153) (actual time=0.545..0.547 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 40kB
|
||||
Buffers: shared hit=101
|
||||
-> Seq Scan on messages (cost=0.00..187.27 rows=501 width=153) (actual time=0.077..0.485 rows=500.00 loops=1)
|
||||
Filter: ((chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:42.570021+00'::timestamp with time zone, 'cb5ad463-2531-42b3-8858-75d9f4d51aa0'::uuid)))
|
||||
Rows Removed by Filter: 4000
|
||||
Buffers: shared hit=101
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.073 ms
|
||||
Execution Time: 0.560 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=158.64..158.76 rows=51 width=153) (actual time=0.507..0.512 rows=51.00 loops=1)
|
||||
Buffers: shared hit=103
|
||||
-> Sort (cost=158.64..159.89 rows=501 width=153) (actual time=0.507..0.509 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 40kB
|
||||
Buffers: shared hit=103
|
||||
-> Bitmap Heap Scan on messages (cost=15.91..141.92 rows=501 width=153) (actual time=0.053..0.431 rows=500.00 loops=1)
|
||||
Recheck Cond: (chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid)
|
||||
Filter: (ROW(created_at, id) > ROW('2026-10-31 20:19:42.570021+00'::timestamp with time zone, 'cb5ad463-2531-42b3-8858-75d9f4d51aa0'::uuid))
|
||||
Rows Removed by Filter: 500
|
||||
Heap Blocks: exact=101
|
||||
Buffers: shared hit=103
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..15.78 rows=1000 width=0) (actual time=0.011..0.012 rows=1000.00 loops=1)
|
||||
Index Cond: (chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.045 ms
|
||||
Execution Time: 0.519 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.28..6.14 rows=51 width=153) (actual time=0.006..0.048 rows=51.00 loops=1)
|
||||
Buffers: shared hit=4
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.28..57.82 rows=501 width=153) (actual time=0.006..0.045 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = 'e89c392b-46c2-4a1d-a798-2ca1f4787398'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:42.570021+00'::timestamp with time zone, 'cb5ad463-2531-42b3-8858-75d9f4d51aa0'::uuid)))
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=4
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.044 ms
|
||||
Execution Time: 0.055 ms
|
||||
|
||||
### bg 1k: middle, после 500
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.28..45.38 rows=51 width=153) (actual time=0.011..0.072 rows=51.00 loops=1)
|
||||
Buffers: shared hit=53
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..440.63 rows=498 width=153) (actual time=0.010..0.070 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:42.593379+00'::timestamp with time zone, '41e10366-ac36-468e-965e-54b7bd0290ce'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=53
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.067 ms
|
||||
Execution Time: 0.084 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.28..7.93 rows=2 width=153) (actual time=0.010..0.060 rows=51.00 loops=1)
|
||||
Buffers: shared hit=53
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..92.02 rows=24 width=153) (actual time=0.010..0.057 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=53
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.007 ms
|
||||
Execution Time: 0.069 ms
|
||||
|
||||
#### or-cursor
|
||||
|
||||
Limit (cost=0.28..49.39 rows=51 width=153) (actual time=0.082..0.139 rows=51.00 loops=1)
|
||||
Buffers: shared hit=528
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..479.81 rows=498 width=153) (actual time=0.082..0.137 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid)
|
||||
Filter: ((created_at > '2026-10-31 20:19:42.593379+00'::timestamp with time zone) OR ((created_at = '2026-10-31 20:19:42.593379+00'::timestamp with time zone) AND (id > '41e10366-ac36-468e-965e-54b7bd0290ce'::uuid)))
|
||||
Rows Removed by Filter: 500
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=528
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.055 ms
|
||||
Execution Time: 0.146 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=203.83..203.96 rows=51 width=153) (actual time=0.602..0.605 rows=51.00 loops=1)
|
||||
Buffers: shared hit=101
|
||||
-> Sort (cost=203.83..205.08 rows=498 width=153) (actual time=0.602..0.603 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 40kB
|
||||
Buffers: shared hit=101
|
||||
-> Seq Scan on messages (cost=0.00..187.22 rows=498 width=153) (actual time=0.076..0.544 rows=500.00 loops=1)
|
||||
Filter: ((chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:42.593379+00'::timestamp with time zone, '41e10366-ac36-468e-965e-54b7bd0290ce'::uuid)))
|
||||
Rows Removed by Filter: 4000
|
||||
Buffers: shared hit=101
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.050 ms
|
||||
Execution Time: 0.612 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=158.49..158.62 rows=51 width=153) (actual time=0.442..0.446 rows=51.00 loops=1)
|
||||
Buffers: shared hit=101
|
||||
-> Sort (cost=158.49..159.74 rows=498 width=153) (actual time=0.442..0.443 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 40kB
|
||||
Buffers: shared hit=101
|
||||
-> Bitmap Heap Scan on messages (cost=15.91..141.88 rows=498 width=153) (actual time=0.053..0.390 rows=500.00 loops=1)
|
||||
Recheck Cond: (chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid)
|
||||
Filter: (ROW(created_at, id) > ROW('2026-10-31 20:19:42.593379+00'::timestamp with time zone, '41e10366-ac36-468e-965e-54b7bd0290ce'::uuid))
|
||||
Rows Removed by Filter: 500
|
||||
Heap Blocks: exact=99
|
||||
Buffers: shared hit=101
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..15.78 rows=1000 width=0) (actual time=0.014..0.014 rows=1000.00 loops=1)
|
||||
Index Cond: (chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.037 ms
|
||||
Execution Time: 0.453 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.28..6.16 rows=51 width=153) (actual time=0.007..0.042 rows=51.00 loops=1)
|
||||
Buffers: shared hit=4
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.28..57.71 rows=498 width=153) (actual time=0.007..0.040 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '1c02e8d5-8fbd-4500-9374-1e4e3f22f2e3'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:19:42.593379+00'::timestamp with time zone, '41e10366-ac36-468e-965e-54b7bd0290ce'::uuid)))
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=4
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.056 ms
|
||||
Execution Time: 0.051 ms
|
||||
|
||||
### bg 100: first, после 0
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=119.42..119.55 rows=51 width=153) (actual time=0.106..0.110 rows=51.00 loops=1)
|
||||
Buffers: shared hit=64
|
||||
-> Sort (cost=119.42..119.67 rows=100 width=153) (actual time=0.106..0.108 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=64
|
||||
-> Bitmap Heap Scan on messages (cost=9.06..116.10 rows=100 width=153) (actual time=0.014..0.093 rows=100.00 loops=1)
|
||||
Recheck Cond: (chat_id = '3694cad0-8739-4553-ba44-604daaaa3382'::uuid)
|
||||
Heap Blocks: exact=62
|
||||
Buffers: shared hit=64
|
||||
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..9.03 rows=100 width=0) (actual time=0.007..0.007 rows=100.00 loops=1)
|
||||
Index Cond: (chat_id = '3694cad0-8739-4553-ba44-604daaaa3382'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.040 ms
|
||||
Execution Time: 0.127 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.28..21.54 rows=7 width=153) (actual time=0.008..0.058 rows=51.00 loops=1)
|
||||
Buffers: shared hit=50
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..215.88 rows=71 width=153) (actual time=0.008..0.055 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = $1)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=50
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.003 ms
|
||||
Execution Time: 0.063 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=162.07..162.20 rows=51 width=153) (actual time=0.196..0.200 rows=51.00 loops=1)
|
||||
Buffers: shared hit=101
|
||||
-> Sort (cost=162.07..162.32 rows=100 width=153) (actual time=0.196..0.197 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=101
|
||||
-> Seq Scan on messages (cost=0.00..158.75 rows=100 width=153) (actual time=0.005..0.182 rows=100.00 loops=1)
|
||||
Filter: (chat_id = '3694cad0-8739-4553-ba44-604daaaa3382'::uuid)
|
||||
Rows Removed by Filter: 4400
|
||||
Buffers: shared hit=101
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.048 ms
|
||||
Execution Time: 0.207 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=115.42..115.55 rows=51 width=153) (actual time=0.116..0.120 rows=51.00 loops=1)
|
||||
Buffers: shared hit=64
|
||||
-> Sort (cost=115.42..115.67 rows=100 width=153) (actual time=0.116..0.118 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=64
|
||||
-> Bitmap Heap Scan on messages (cost=5.06..112.10 rows=100 width=153) (actual time=0.010..0.103 rows=100.00 loops=1)
|
||||
Recheck Cond: (chat_id = '3694cad0-8739-4553-ba44-604daaaa3382'::uuid)
|
||||
Heap Blocks: exact=62
|
||||
Buffers: shared hit=64
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..5.03 rows=100 width=0) (actual time=0.004..0.004 rows=100.00 loops=1)
|
||||
Index Cond: (chat_id = '3694cad0-8739-4553-ba44-604daaaa3382'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.038 ms
|
||||
Execution Time: 0.127 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.28..6.02 rows=51 width=153) (actual time=0.007..0.042 rows=51.00 loops=1)
|
||||
Buffers: shared hit=4
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.28..11.53 rows=100 width=153) (actual time=0.007..0.040 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '3694cad0-8739-4553-ba44-604daaaa3382'::uuid)
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=4
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.053 ms
|
||||
Execution Time: 0.052 ms
|
||||
|
||||
### bg 10: first, после 0
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=35.36..35.39 rows=10 width=153) (actual time=0.022..0.024 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Sort (cost=35.36..35.39 rows=10 width=153) (actual time=0.022..0.023 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Heap Scan on messages (cost=4.36..35.20 rows=10 width=153) (actual time=0.009..0.020 rows=10.00 loops=1)
|
||||
Recheck Cond: (chat_id = '173df049-0e59-461f-afe3-8a15542fa0c5'::uuid)
|
||||
Heap Blocks: exact=10
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..4.36 rows=10 width=0) (actual time=0.003..0.003 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = '173df049-0e59-461f-afe3-8a15542fa0c5'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.044 ms
|
||||
Execution Time: 0.032 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.28..21.54 rows=7 width=153) (actual time=0.007..0.017 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.28..215.88 rows=71 width=153) (actual time=0.007..0.016 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = $1)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=12
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.003 ms
|
||||
Execution Time: 0.023 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=157.57..157.59 rows=10 width=153) (actual time=0.121..0.123 rows=10.00 loops=1)
|
||||
Buffers: shared hit=101
|
||||
-> Sort (cost=157.57..157.59 rows=10 width=153) (actual time=0.121..0.122 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=101
|
||||
-> Seq Scan on messages (cost=0.00..157.40 rows=10 width=153) (actual time=0.019..0.118 rows=10.00 loops=1)
|
||||
Filter: (chat_id = '173df049-0e59-461f-afe3-8a15542fa0c5'::uuid)
|
||||
Rows Removed by Filter: 4490
|
||||
Buffers: shared hit=101
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.051 ms
|
||||
Execution Time: 0.130 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=35.36..35.39 rows=10 width=153) (actual time=0.020..0.021 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Sort (cost=35.36..35.39 rows=10 width=153) (actual time=0.019..0.020 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Heap Scan on messages (cost=4.36..35.20 rows=10 width=153) (actual time=0.008..0.018 rows=10.00 loops=1)
|
||||
Recheck Cond: (chat_id = '173df049-0e59-461f-afe3-8a15542fa0c5'::uuid)
|
||||
Heap Blocks: exact=10
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..4.36 rows=10 width=0) (actual time=0.003..0.003 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = '173df049-0e59-461f-afe3-8a15542fa0c5'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.036 ms
|
||||
Execution Time: 0.026 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.28..4.61 rows=10 width=153) (actual time=0.005..0.011 rows=10.00 loops=1)
|
||||
Buffers: shared hit=3
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.28..4.61 rows=10 width=153) (actual time=0.005..0.011 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = '173df049-0e59-461f-afe3-8a15542fa0c5'::uuid)
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=3
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.036 ms
|
||||
Execution Time: 0.017 ms
|
||||
@@ -0,0 +1,693 @@
|
||||
# План запроса истории: размер 5k
|
||||
|
||||
Commit b2fb88f
|
||||
Читаемый чат — 5000 сообщений; фоновые чаты: 2 × 1k, 10 × 100, 50 × 10.
|
||||
Страница — `limit` профиля; «после» — сколько сообщений чата до
|
||||
страницы.
|
||||
|
||||
## Планы приложения
|
||||
|
||||
auto_explain (ANALYZE, BUFFERS, TIMING): запрос, параметры и план,
|
||||
с которыми его выполнило приложение (prepared statement asyncpg).
|
||||
|
||||
### read 5k: first, после 0
|
||||
|
||||
duration: 0.100 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '80b7184b-2dce-467f-80f1-54ef9f806be7', $2 = '51'
|
||||
Limit (cost=0.29..11.51 rows=51 width=153) (actual time=0.018..0.071 rows=51.00 loops=1)
|
||||
Buffers: shared hit=25
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..1100.82 rows=5000 width=153) (actual time=0.018..0.068 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '80b7184b-2dce-467f-80f1-54ef9f806be7'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=25
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### read 5k: middle, после 2500
|
||||
|
||||
duration: 0.113 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = '80b7184b-2dce-467f-80f1-54ef9f806be7', $2 = '2026-10-31 20:20:52.094182+00', $3 = '451aa0da-83f8-4f73-ac9d-8a4efcc8ecd3', $4 = '51'
|
||||
Limit (cost=0.29..14.23 rows=4 width=153) (actual time=0.022..0.080 rows=51.00 loops=1)
|
||||
Buffers: shared hit=54
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..157.19 rows=45 width=153) (actual time=0.021..0.076 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=54
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### read 5k: last, после 4900
|
||||
|
||||
duration: 0.112 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = '80b7184b-2dce-467f-80f1-54ef9f806be7', $2 = '2026-10-31 20:20:59.127167+00', $3 = 'd29a2234-a752-4b15-97ca-bc3a5fe16f81', $4 = '51'
|
||||
Limit (cost=0.29..14.23 rows=4 width=153) (actual time=0.022..0.079 rows=51.00 loops=1)
|
||||
Buffers: shared hit=53
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..157.19 rows=45 width=153) (actual time=0.021..0.075 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=53
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: first, после 0
|
||||
|
||||
duration: 0.253 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008', $2 = '51'
|
||||
Limit (cost=0.29..39.63 rows=51 width=153) (actual time=0.033..0.158 rows=51.00 loops=1)
|
||||
Buffers: shared hit=45
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..771.85 rows=1000 width=153) (actual time=0.032..0.152 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=45
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: middle, после 500
|
||||
|
||||
duration: 0.109 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008', $2 = '2026-10-31 20:20:52.084497+00', $3 = '9087eb30-8899-4c5d-8728-7327affbc2a1', $4 = '51'
|
||||
Limit (cost=0.29..14.23 rows=4 width=153) (actual time=0.018..0.078 rows=51.00 loops=1)
|
||||
Buffers: shared hit=52
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..157.19 rows=45 width=153) (actual time=0.017..0.075 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=52
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 1k: last, после 900
|
||||
|
||||
duration: 0.114 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID) ORDER BY messages.created_at, messages.id
|
||||
LIMIT $4::INTEGER
|
||||
Query Parameters: $1 = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008', $2 = '2026-10-31 20:20:57.953096+00', $3 = 'aa061a11-d99b-430e-8d57-8956f75927c3', $4 = '51'
|
||||
Limit (cost=0.29..14.23 rows=4 width=153) (actual time=0.019..0.080 rows=51.00 loops=1)
|
||||
Buffers: shared hit=51
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..157.19 rows=45 width=153) (actual time=0.018..0.077 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=51
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 100: first, после 0
|
||||
|
||||
duration: 0.124 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '6c3ce1eb-20ca-48e7-af3c-920956940be7', $2 = '51'
|
||||
Limit (cost=0.29..154.66 rows=51 width=153) (actual time=0.012..0.077 rows=51.00 loops=1)
|
||||
Buffers: shared hit=47
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..302.99 rows=100 width=153) (actual time=0.012..0.074 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '6c3ce1eb-20ca-48e7-af3c-920956940be7'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=47
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
### bg 10: first, после 0
|
||||
|
||||
duration: 0.042 ms plan:
|
||||
Query Text: SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at, array((SELECT message_attachments.attachment_id
|
||||
FROM message_attachments
|
||||
WHERE message_attachments.message_id = messages.id ORDER BY message_attachments.position)) AS attachment_ids
|
||||
FROM messages
|
||||
WHERE messages.chat_id = $1::UUID ORDER BY messages.created_at, messages.id
|
||||
LIMIT $2::INTEGER
|
||||
Query Parameters: $1 = '90a36fb9-ae42-4016-a663-65307e1e1e19', $2 = '51'
|
||||
Limit (cost=37.85..37.87 rows=10 width=153) (actual time=0.037..0.038 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Sort (cost=37.85..37.87 rows=10 width=153) (actual time=0.036..0.037 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Heap Scan on messages (cost=4.36..37.68 rows=10 width=153) (actual time=0.017..0.033 rows=10.00 loops=1)
|
||||
Recheck Cond: (chat_id = '90a36fb9-ae42-4016-a663-65307e1e1e19'::uuid)
|
||||
Heap Blocks: exact=10
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..4.36 rows=10 width=0) (actual time=0.006..0.006 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = '90a36fb9-ae42-4016-a663-65307e1e1e19'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
|
||||
## Страницы сравнения в psql: варианты
|
||||
|
||||
Тот же текст запроса и те же параметры, что у плана приложения этой
|
||||
страницы, в одной транзакции, которая откатывается: индексы базы
|
||||
после неё те же. Каждый вариант выполнен дважды, здесь — второе
|
||||
выполнение. `psql` — индекс приложения, custom plan; `generic` — он
|
||||
же с force_generic_plan; `or-cursor` — условие курсора через OR;
|
||||
`no-index` — без индекса приложения; варианты индекса вместо него:
|
||||
`chat_only` (chat_id), `covering` (chat_id, created_at, id) INCLUDE (sender_id, text).
|
||||
|
||||
### read 5k: middle, после 2500
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.29..18.68 rows=51 width=153) (actual time=0.011..0.061 rows=51.00 loops=1)
|
||||
Buffers: shared hit=54
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..901.43 rows=2499 width=153) (actual time=0.011..0.058 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '80b7184b-2dce-467f-80f1-54ef9f806be7'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:20:52.094182+00'::timestamp with time zone, '451aa0da-83f8-4f73-ac9d-8a4efcc8ecd3'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=54
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.060 ms
|
||||
Execution Time: 0.070 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.29..14.23 rows=4 width=153) (actual time=0.014..0.070 rows=51.00 loops=1)
|
||||
Buffers: shared hit=54
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..157.19 rows=45 width=153) (actual time=0.013..0.064 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=54
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.011 ms
|
||||
Execution Time: 0.081 ms
|
||||
|
||||
#### or-cursor
|
||||
|
||||
Limit (cost=0.29..22.74 rows=51 width=153) (actual time=0.376..0.420 rows=51.00 loops=1)
|
||||
Buffers: shared hit=2541
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..1100.80 rows=2499 width=153) (actual time=0.376..0.417 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '80b7184b-2dce-467f-80f1-54ef9f806be7'::uuid)
|
||||
Filter: ((created_at > '2026-10-31 20:20:52.094182+00'::timestamp with time zone) OR ((created_at = '2026-10-31 20:20:52.094182+00'::timestamp with time zone) AND (id > '451aa0da-83f8-4f73-ac9d-8a4efcc8ecd3'::uuid)))
|
||||
Rows Removed by Filter: 2500
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2541
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.083 ms
|
||||
Execution Time: 0.431 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=455.61..455.73 rows=51 width=153) (actual time=2.173..2.177 rows=51.00 loops=1)
|
||||
Buffers: shared hit=186
|
||||
-> Sort (cost=455.61..461.85 rows=2499 width=153) (actual time=2.173..2.175 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 43kB
|
||||
Buffers: shared hit=186
|
||||
-> Seq Scan on messages (cost=0.00..372.24 rows=2499 width=153) (actual time=0.165..1.896 rows=2500.00 loops=1)
|
||||
Filter: ((chat_id = '80b7184b-2dce-467f-80f1-54ef9f806be7'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:20:52.094182+00'::timestamp with time zone, '451aa0da-83f8-4f73-ac9d-8a4efcc8ecd3'::uuid)))
|
||||
Rows Removed by Filter: 6000
|
||||
Buffers: shared hit=186
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=2500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=2500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.061 ms
|
||||
Execution Time: 2.186 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=455.61..455.73 rows=51 width=153) (actual time=2.048..2.052 rows=51.00 loops=1)
|
||||
Buffers: shared hit=186
|
||||
-> Sort (cost=455.61..461.85 rows=2499 width=153) (actual time=2.047..2.049 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 43kB
|
||||
Buffers: shared hit=186
|
||||
-> Seq Scan on messages (cost=0.00..372.24 rows=2499 width=153) (actual time=0.140..1.778 rows=2500.00 loops=1)
|
||||
Filter: ((chat_id = '80b7184b-2dce-467f-80f1-54ef9f806be7'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:20:52.094182+00'::timestamp with time zone, '451aa0da-83f8-4f73-ac9d-8a4efcc8ecd3'::uuid)))
|
||||
Rows Removed by Filter: 6000
|
||||
Buffers: shared hit=186
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=2500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=2500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.037 ms
|
||||
Execution Time: 2.057 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.41..6.28 rows=51 width=153) (actual time=0.009..0.097 rows=51.00 loops=1)
|
||||
Buffers: shared hit=5
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.41..287.88 rows=2499 width=153) (actual time=0.009..0.093 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '80b7184b-2dce-467f-80f1-54ef9f806be7'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:20:52.094182+00'::timestamp with time zone, '451aa0da-83f8-4f73-ac9d-8a4efcc8ecd3'::uuid)))
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=5
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.086 ms
|
||||
Execution Time: 0.108 ms
|
||||
|
||||
### bg 1k: middle, после 500
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.29..74.92 rows=51 width=153) (actual time=0.009..0.069 rows=51.00 loops=1)
|
||||
Buffers: shared hit=52
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..731.98 rows=500 width=153) (actual time=0.008..0.066 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:20:52.084497+00'::timestamp with time zone, '9087eb30-8899-4c5d-8728-7327affbc2a1'::uuid)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=52
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.050 ms
|
||||
Execution Time: 0.076 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.29..14.23 rows=4 width=153) (actual time=0.010..0.066 rows=51.00 loops=1)
|
||||
Buffers: shared hit=52
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..157.19 rows=45 width=153) (actual time=0.009..0.064 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = $1) AND (ROW(created_at, id) > ROW($2, $3)))
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=52
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.007 ms
|
||||
Execution Time: 0.076 ms
|
||||
|
||||
#### or-cursor
|
||||
|
||||
Limit (cost=0.29..78.98 rows=51 width=153) (actual time=0.100..0.138 rows=51.00 loops=1)
|
||||
Buffers: shared hit=530
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..771.85 rows=500 width=153) (actual time=0.100..0.136 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008'::uuid)
|
||||
Filter: ((created_at > '2026-10-31 20:20:52.084497+00'::timestamp with time zone) OR ((created_at = '2026-10-31 20:20:52.084497+00'::timestamp with time zone) AND (id > '9087eb30-8899-4c5d-8728-7327affbc2a1'::uuid)))
|
||||
Rows Removed by Filter: 500
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=530
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.048 ms
|
||||
Execution Time: 0.143 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=358.93..359.06 rows=51 width=153) (actual time=0.633..0.637 rows=51.00 loops=1)
|
||||
Buffers: shared hit=186
|
||||
-> Sort (cost=358.93..360.18 rows=500 width=153) (actual time=0.633..0.635 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 40kB
|
||||
Buffers: shared hit=186
|
||||
-> Seq Scan on messages (cost=0.00..342.25 rows=500 width=153) (actual time=0.143..0.576 rows=500.00 loops=1)
|
||||
Filter: ((chat_id = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:20:52.084497+00'::timestamp with time zone, '9087eb30-8899-4c5d-8728-7327affbc2a1'::uuid)))
|
||||
Rows Removed by Filter: 8000
|
||||
Buffers: shared hit=186
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.041 ms
|
||||
Execution Time: 0.643 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=243.59..243.72 rows=51 width=153) (actual time=0.472..0.476 rows=51.00 loops=1)
|
||||
Buffers: shared hit=186
|
||||
-> Sort (cost=243.59..244.84 rows=500 width=153) (actual time=0.472..0.474 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: top-N heapsort Memory: 40kB
|
||||
Buffers: shared hit=186
|
||||
-> Bitmap Heap Scan on messages (cost=15.91..226.91 rows=500 width=153) (actual time=0.092..0.416 rows=500.00 loops=1)
|
||||
Recheck Cond: (chat_id = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008'::uuid)
|
||||
Filter: (ROW(created_at, id) > ROW('2026-10-31 20:20:52.084497+00'::timestamp with time zone, '9087eb30-8899-4c5d-8728-7327affbc2a1'::uuid))
|
||||
Rows Removed by Filter: 500
|
||||
Heap Blocks: exact=183
|
||||
Buffers: shared hit=186
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..15.79 rows=1000 width=0) (actual time=0.019..0.019 rows=1000.00 loops=1)
|
||||
Index Cond: (chat_id = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=3
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=500)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.044 ms
|
||||
Execution Time: 0.483 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.41..6.28 rows=51 width=153) (actual time=0.004..0.052 rows=51.00 loops=1)
|
||||
Buffers: shared hit=5
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.41..57.91 rows=500 width=153) (actual time=0.004..0.050 rows=51.00 loops=1)
|
||||
Index Cond: ((chat_id = '6ae81a0d-d05a-4b3b-b7f6-2013260aa008'::uuid) AND (ROW(created_at, id) > ROW('2026-10-31 20:20:52.084497+00'::timestamp with time zone, '9087eb30-8899-4c5d-8728-7327affbc2a1'::uuid)))
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=5
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.028 ms
|
||||
Execution Time: 0.058 ms
|
||||
|
||||
### bg 100: first, после 0
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=0.29..154.66 rows=51 width=153) (actual time=0.007..0.064 rows=51.00 loops=1)
|
||||
Buffers: shared hit=47
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..302.99 rows=100 width=153) (actual time=0.007..0.062 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '6c3ce1eb-20ca-48e7-af3c-920956940be7'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=47
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.037 ms
|
||||
Execution Time: 0.072 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.29..39.82 rows=14 width=153) (actual time=0.009..0.062 rows=51.00 loops=1)
|
||||
Buffers: shared hit=47
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..381.47 rows=135 width=153) (actual time=0.009..0.059 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = $1)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=47
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.003 ms
|
||||
Execution Time: 0.067 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=297.07..297.20 rows=51 width=153) (actual time=0.281..0.284 rows=51.00 loops=1)
|
||||
Buffers: shared hit=186
|
||||
-> Sort (cost=297.07..297.32 rows=100 width=153) (actual time=0.281..0.282 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=186
|
||||
-> Seq Scan on messages (cost=0.00..293.75 rows=100 width=153) (actual time=0.010..0.266 rows=100.00 loops=1)
|
||||
Filter: (chat_id = '6c3ce1eb-20ca-48e7-af3c-920956940be7'::uuid)
|
||||
Rows Removed by Filter: 8400
|
||||
Buffers: shared hit=186
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.035 ms
|
||||
Execution Time: 0.290 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=172.68..172.80 rows=51 width=153) (actual time=0.133..0.136 rows=51.00 loops=1)
|
||||
Buffers: shared hit=79
|
||||
-> Sort (cost=172.68..172.93 rows=100 width=153) (actual time=0.133..0.134 rows=51.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 50kB
|
||||
Buffers: shared hit=79
|
||||
-> Bitmap Heap Scan on messages (cost=5.06..169.35 rows=100 width=153) (actual time=0.013..0.120 rows=100.00 loops=1)
|
||||
Recheck Cond: (chat_id = '6c3ce1eb-20ca-48e7-af3c-920956940be7'::uuid)
|
||||
Heap Blocks: exact=77
|
||||
Buffers: shared hit=79
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..5.04 rows=100 width=0) (actual time=0.004..0.004 rows=100.00 loops=1)
|
||||
Index Cond: (chat_id = '6c3ce1eb-20ca-48e7-af3c-920956940be7'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=100)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=100)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.040 ms
|
||||
Execution Time: 0.143 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.41..6.15 rows=51 width=153) (actual time=0.005..0.055 rows=51.00 loops=1)
|
||||
Buffers: shared hit=5
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.41..11.66 rows=100 width=153) (actual time=0.005..0.052 rows=51.00 loops=1)
|
||||
Index Cond: (chat_id = '6c3ce1eb-20ca-48e7-af3c-920956940be7'::uuid)
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=5
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=51)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.035 ms
|
||||
Execution Time: 0.062 ms
|
||||
|
||||
### bg 10: first, после 0
|
||||
|
||||
#### psql
|
||||
|
||||
Limit (cost=37.85..37.87 rows=10 width=153) (actual time=0.026..0.027 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Sort (cost=37.85..37.87 rows=10 width=153) (actual time=0.026..0.026 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Heap Scan on messages (cost=4.36..37.68 rows=10 width=153) (actual time=0.013..0.023 rows=10.00 loops=1)
|
||||
Recheck Cond: (chat_id = '90a36fb9-ae42-4016-a663-65307e1e1e19'::uuid)
|
||||
Heap Blocks: exact=10
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..4.36 rows=10 width=0) (actual time=0.005..0.005 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = '90a36fb9-ae42-4016-a663-65307e1e1e19'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.039 ms
|
||||
Execution Time: 0.040 ms
|
||||
|
||||
#### generic
|
||||
|
||||
Limit (cost=0.29..39.82 rows=14 width=153) (actual time=0.011..0.023 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Index Scan using ix_messages_chat_id_created_at_id on messages (cost=0.29..381.47 rows=135 width=153) (actual time=0.011..0.022 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = $1)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=12
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning Time: 0.005 ms
|
||||
Execution Time: 0.032 ms
|
||||
|
||||
#### no-index
|
||||
|
||||
Limit (cost=292.57..292.59 rows=10 width=153) (actual time=0.214..0.215 rows=10.00 loops=1)
|
||||
Buffers: shared hit=186
|
||||
-> Sort (cost=292.57..292.59 rows=10 width=153) (actual time=0.214..0.214 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=186
|
||||
-> Seq Scan on messages (cost=0.00..292.40 rows=10 width=153) (actual time=0.016..0.212 rows=10.00 loops=1)
|
||||
Filter: (chat_id = '90a36fb9-ae42-4016-a663-65307e1e1e19'::uuid)
|
||||
Rows Removed by Filter: 8490
|
||||
Buffers: shared hit=186
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.032 ms
|
||||
Execution Time: 0.220 ms
|
||||
|
||||
#### chat_only
|
||||
|
||||
Limit (cost=37.85..37.87 rows=10 width=153) (actual time=0.023..0.025 rows=10.00 loops=1)
|
||||
Buffers: shared hit=12
|
||||
-> Sort (cost=37.85..37.87 rows=10 width=153) (actual time=0.023..0.024 rows=10.00 loops=1)
|
||||
Sort Key: messages.created_at, messages.id
|
||||
Sort Method: quicksort Memory: 27kB
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Heap Scan on messages (cost=4.36..37.68 rows=10 width=153) (actual time=0.009..0.020 rows=10.00 loops=1)
|
||||
Recheck Cond: (chat_id = '90a36fb9-ae42-4016-a663-65307e1e1e19'::uuid)
|
||||
Heap Blocks: exact=10
|
||||
Buffers: shared hit=12
|
||||
-> Bitmap Index Scan on bench_variant (cost=0.00..4.36 rows=10 width=0) (actual time=0.003..0.003 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = '90a36fb9-ae42-4016-a663-65307e1e1e19'::uuid)
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=2
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.052 ms
|
||||
Execution Time: 0.033 ms
|
||||
|
||||
#### covering
|
||||
|
||||
Limit (cost=0.41..4.74 rows=10 width=153) (actual time=0.006..0.015 rows=10.00 loops=1)
|
||||
Buffers: shared hit=4
|
||||
-> Index Only Scan using bench_variant on messages (cost=0.41..4.74 rows=10 width=153) (actual time=0.006..0.014 rows=10.00 loops=1)
|
||||
Index Cond: (chat_id = '90a36fb9-ae42-4016-a663-65307e1e1e19'::uuid)
|
||||
Heap Fetches: 0
|
||||
Index Searches: 1
|
||||
Buffers: shared hit=4
|
||||
SubPlan 1
|
||||
-> Sort (cost=0.01..0.02 rows=1 width=18) (actual time=0.001..0.001 rows=0.00 loops=10)
|
||||
Sort Key: message_attachments."position"
|
||||
Sort Method: quicksort Memory: 25kB
|
||||
-> Seq Scan on message_attachments (cost=0.00..0.00 rows=1 width=18) (actual time=0.000..0.000 rows=0.00 loops=10)
|
||||
Filter: (message_id = messages.id)
|
||||
Planning:
|
||||
Buffers: shared hit=3
|
||||
Planning Time: 0.038 ms
|
||||
Execution Time: 0.021 ms
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,4 @@
|
||||
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
|
||||
1000,1,0,4500,7.804,4500,0,576.6,0.0,51.614,108.971,151.826,222.608,0.999,125.0,116.1,0.119,,0.203,,
|
||||
5000,1,0,8500,14.658,8500,0,579.9,0.0,51.796,112.909,148.343,224.403,0.999,125.2,115.5,0.11,,0.2,,
|
||||
10000,1,0,13500,23.029,13500,0,586.2,0.0,51.517,104.946,144.711,250.139,0.999,125.1,118.1,0.109,,0.202,,
|
||||
|
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"label": "unit-of-work-aa",
|
||||
"profile": "quick",
|
||||
"stage": "done",
|
||||
"size": 10000,
|
||||
"runs_done": 18,
|
||||
"runs_total": 18,
|
||||
"elapsed_s": 224,
|
||||
"eta_s": 0,
|
||||
"warnings": [],
|
||||
"updated_at": "2026-10-31T20:23:06+00:00"
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
{"metrics":{"checks":{"contains":"default","values":{"passes":13500,"fails":0,"rate":1},"type":"rate"},"iteration_duration":{"type":"trend","contains":"time","values":{"p(99)":144.76235140999998,"max":250.22325,"avg":54.54204372888884,"min":11.426459,"med":51.578166499999995,"p(50)":51.578166499999995,"p(95)":104.99915444999999}},"http_req_duration":{"contains":"time","values":{"p(50)":51.517271,"p(95)":104.94581249999997,"p(99)":144.71090033,"max":250.138834,"avg":54.476573535036856,"min":11.378083,"med":51.517271},"type":"trend"},"http_req_tls_handshaking":{"type":"trend","contains":"time","values":{"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0,"avg":0,"min":0}},"http_req_connecting":{"type":"trend","contains":"time","values":{"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0.339042,"avg":0.0004472439999999999,"min":0}},"data_received":{"type":"counter","contains":"data","values":{"count":6615000,"rate":287252.68865780847}},"iterations":{"type":"counter","contains":"default","values":{"count":13500,"rate":586.2299768526703}},"vus_max":{"contains":"default","values":{"max":32,"value":32,"min":32},"type":"gauge"},"http_req_sending":{"values":{"max":0.49325,"avg":0.005056908518518449,"min":0.001958,"med":0.003792,"p(50)":0.003792,"p(95)":0.010083,"p(99)":0.020041009999999998},"type":"trend","contains":"time"},"http_reqs":{"contains":"default","values":{"count":13500,"rate":586.2299768526703},"type":"counter"},"http_req_receiving":{"type":"trend","contains":"time","values":{"avg":0.016185549777777898,"min":0.004666,"med":0.013917,"p(50)":0.013917,"p(95)":0.03204404999999998,"p(99)":0.051001249999999984,"max":0.396084}},"data_sent":{"type":"counter","contains":"data","values":{"rate":220422.47129660405,"count":5076000}},"http_req_blocked":{"type":"trend","contains":"time","values":{"min":0.000458,"med":0.001,"p(50)":0.001,"p(95)":0.002083,"p(99)":0.003708,"max":1.04975,"avg":0.002860772888888782}},"vus":{"type":"gauge","contains":"default","values":{"value":30,"min":30,"max":32}},"http_req_duration{expected_response:true}":{"type":"trend","contains":"time","values":{"min":11.378083,"med":51.517271,"p(50)":51.517271,"p(95)":104.94581249999997,"p(99)":144.71090033,"max":250.138834,"avg":54.476573535036856},"thresholds":{"max>=0":{"ok":true}}},"http_req_waiting":{"type":"trend","contains":"time","values":{"p(50)":51.493958,"p(95)":104.92815829999999,"p(99)":144.69301542,"max":250.105042,"avg":54.45533107674069,"min":11.361542,"med":51.493958}},"http_req_failed":{"contains":"default","values":{"rate":0,"passes":0,"fails":13500},"type":"rate"}},"root_group":{"groups":[],"checks":[{"name":"message 201","path":"::message 201","id":"6445aff337e1ade0bc10402fbac79882","passes":13500,"fails":0}],"name":"","path":"","id":"d41d8cd98f00b204e9800998ecf8427e"},"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"isStdOutTTY":false,"isStdErrTTY":false,"testRunDurationMs":23028.50508}}
|
||||
@@ -0,0 +1 @@
|
||||
{"root_group":{"path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"name":"message 201","path":"::message 201","id":"6445aff337e1ade0bc10402fbac79882","passes":4500,"fails":0}],"name":""},"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"isStdOutTTY":false,"isStdErrTTY":false,"testRunDurationMs":7804.259545},"metrics":{"checks":{"type":"rate","contains":"default","values":{"rate":1,"passes":4500,"fails":0}},"http_req_duration":{"contains":"time","values":{"min":11.5215,"med":51.614146,"p(50)":51.614146,"p(95)":108.97147644999998,"p(99)":151.82628041,"max":222.607834,"avg":55.30293323288895},"type":"trend"},"http_req_failed":{"type":"rate","contains":"default","values":{"rate":0,"passes":0,"fails":4500}},"http_req_connecting":{"type":"trend","contains":"time","values":{"avg":0.0006185642222222222,"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0.276958}},"http_req_receiving":{"contains":"time","values":{"p(50)":0.014166,"p(95)":0.03429404999999999,"p(99)":0.05739041999999994,"max":0.412167,"avg":0.016828069555555564,"min":0.004625,"med":0.014166},"type":"trend"},"vus":{"type":"gauge","contains":"default","values":{"max":32,"value":32,"min":32}},"vus_max":{"contains":"default","values":{"min":32,"max":32,"value":32},"type":"gauge"},"http_req_blocked":{"type":"trend","contains":"time","values":{"med":0.000959,"p(50)":0.000959,"p(95)":0.002125,"p(99)":0.007750419999999998,"max":0.906167,"avg":0.0033415228888889355,"min":0.0005}},"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_received":{"type":"counter","contains":"data","values":{"count":2205000,"rate":282538.0149501422}},"http_req_sending":{"values":{"p(95)":0.010459,"p(99)":0.01895801,"max":0.2155,"avg":0.005030362666666664,"min":0.002125,"med":0.003958,"p(50)":0.003958},"type":"trend","contains":"time"},"iterations":{"type":"counter","contains":"default","values":{"rate":576.6081937758004,"count":4500}},"iteration_duration":{"contains":"time","values":{"p(99)":151.91362333,"max":222.664875,"avg":55.37190353111107,"min":11.580458,"med":51.66479150000001,"p(50)":51.66479150000001,"p(95)":109.01507884999998},"type":"trend"},"http_req_duration{expected_response:true}":{"type":"trend","contains":"time","values":{"min":11.5215,"med":51.614146,"p(50)":51.614146,"p(95)":108.97147644999998,"p(99)":151.82628041,"max":222.607834,"avg":55.30293323288895},"thresholds":{"max>=0":{"ok":true}}},"http_reqs":{"values":{"count":4500,"rate":576.6081937758004},"type":"counter","contains":"default"},"data_sent":{"contains":"data","values":{"count":1692000,"rate":216804.68085970095},"type":"counter"},"http_req_waiting":{"type":"trend","contains":"time","values":{"med":51.5932295,"p(50)":51.5932295,"p(95)":108.95620064999999,"p(99)":151.80782051,"max":222.588416,"avg":55.2810748006667,"min":11.507208}}}}
|
||||
@@ -0,0 +1 @@
|
||||
{"root_group":{"name":"","path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"name":"message 201","path":"::message 201","id":"6445aff337e1ade0bc10402fbac79882","passes":8500,"fails":0}]},"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"testRunDurationMs":14657.63784,"isStdOutTTY":false,"isStdErrTTY":false},"metrics":{"data_received":{"type":"counter","contains":"data","values":{"count":4165000,"rate":284152.1973365935}},"http_req_receiving":{"type":"trend","contains":"time","values":{"p(95)":0.032960099999999985,"p(99)":0.05421175999999997,"max":0.301458,"avg":0.016481440823529543,"min":0.004417,"med":0.014,"p(50)":0.014}},"http_req_failed":{"type":"rate","contains":"default","values":{"rate":0,"passes":0,"fails":8500}},"http_req_waiting":{"values":{"p(50)":51.780333,"p(95)":112.89164854999999,"p(99)":148.32381375,"max":224.371292,"avg":55.03091433164729,"min":10.888125,"med":51.780333},"type":"trend","contains":"time"},"vus":{"type":"gauge","contains":"default","values":{"max":32,"value":32,"min":32}},"vus_max":{"contains":"default","values":{"value":32,"min":32,"max":32},"type":"gauge"},"http_reqs":{"values":{"count":8500,"rate":579.9024435440683},"type":"counter","contains":"default"},"http_req_tls_handshaking":{"contains":"time","values":{"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0,"avg":0},"type":"trend"},"iteration_duration":{"contains":"time","values":{"med":51.8613955,"p(50)":51.8613955,"p(95)":112.95544794999998,"p(99)":148.40809108,"max":224.47075,"avg":55.11979060494095,"min":10.95575},"type":"trend"},"http_req_sending":{"type":"trend","contains":"time","values":{"p(50)":0.003792,"p(95)":0.010084,"p(99)":0.018791419999999996,"max":0.267417,"avg":0.004890888588235243,"min":0.001791,"med":0.003792}},"checks":{"contains":"default","values":{"rate":1,"passes":8500,"fails":0},"type":"rate"},"http_req_duration{expected_response:true}":{"contains":"time","values":{"avg":55.052286661058716,"min":10.902833,"med":51.795646000000005,"p(50)":51.795646000000005,"p(95)":112.90908569999999,"p(99)":148.34328125999997,"max":224.402542},"thresholds":{"max>=0":{"ok":true}},"type":"trend"},"http_req_duration":{"values":{"avg":55.052286661058716,"min":10.902833,"med":51.795646000000005,"p(50)":51.795646000000005,"p(95)":112.90908569999999,"p(99)":148.34328125999997,"max":224.402542},"type":"trend","contains":"time"},"http_req_blocked":{"type":"trend","contains":"time","values":{"max":1.013542,"avg":0.004023293411764744,"min":0.000458,"med":0.001,"p(50)":0.001,"p(95)":0.002083,"p(99)":0.0046254099999999965}},"http_req_connecting":{"values":{"avg":0.0007623968235294118,"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0.350917},"type":"trend","contains":"time"},"data_sent":{"type":"counter","contains":"data","values":{"count":3196000,"rate":218043.3187725697}},"iterations":{"type":"counter","contains":"default","values":{"count":8500,"rate":579.9024435440683}}}}
|
||||
@@ -0,0 +1 @@
|
||||
{"metrics":{"http_req_receiving":{"contains":"time","values":{"med":0.020792,"p(50)":0.020792,"p(95)":0.053574599999999986,"p(99)":0.08314983999999999,"max":0.184625,"avg":0.02564272890338361,"min":0.012291},"type":"trend"},"checks":{"contains":"default","values":{"rate":1,"passes":4906,"fails":0},"type":"rate"},"data_sent":{"type":"counter","contains":"data","values":{"count":1025354,"rate":204990.90979468572}},"iteration_duration":{"type":"trend","contains":"time","values":{"p(99)":3.6188283599999997,"max":85.096792,"avg":2.0356424728903417,"min":1.551791,"med":1.895666,"p(50)":1.895666,"p(95)":2.7046919999999997}},"http_req_waiting":{"type":"trend","contains":"time","values":{"avg":1.9329760978393826,"min":1.486833,"med":1.807208,"p(50)":1.807208,"p(95)":2.504284,"p(99)":3.4146998399999995,"max":84.908542}},"vus_max":{"type":"gauge","contains":"default","values":{"value":1,"min":1,"max":1}},"http_req_duration":{"type":"trend","contains":"time","values":{"max":84.977166,"avg":1.962735408887078,"min":1.50225,"med":1.83075,"p(50)":1.83075,"p(95)":2.5664751999999993,"p(99)":3.4802585199999996}},"http_req_tls_handshaking":{"type":"trend","contains":"time","values":{"p(95)":0,"p(99)":0,"max":0,"avg":0,"min":0,"med":0,"p(50)":0}},"http_req_sending":{"type":"trend","contains":"time","values":{"p(50)":0.003,"p(95)":0.008766399999999995,"p(99)":0.017405319999999988,"max":0.155417,"avg":0.004116582144313109,"min":0.001666,"med":0.003}},"iterations":{"values":{"count":2453,"rate":490.4088751069036},"type":"counter","contains":"default"},"vus":{"type":"gauge","contains":"default","values":{"min":1,"max":1,"value":1}},"http_req_duration{expected_response:true}":{"type":"trend","contains":"time","values":{"p(99)":3.4802585199999996,"max":84.977166,"avg":1.962735408887078,"min":1.50225,"med":1.83075,"p(50)":1.83075,"p(95)":2.5664751999999993},"thresholds":{"max>=0":{"ok":true}}},"http_reqs":{"values":{"count":2453,"rate":490.4088751069036},"type":"counter","contains":"default"},"http_req_connecting":{"contains":"time","values":{"avg":0.00004835915205870362,"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0.118625},"type":"trend"},"http_req_blocked":{"type":"trend","contains":"time","values":{"min":0.000542,"med":0.001041,"p(50)":0.001041,"p(95)":0.002333,"p(99)":0.0034148399999999984,"max":0.486958,"avg":0.0014451271911944483}},"http_req_failed":{"type":"rate","contains":"default","values":{"rate":0,"passes":0,"fails":2453}},"data_received":{"values":{"count":35713227,"rate":7139862.8126814095},"type":"counter","contains":"data"}},"root_group":{"id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"fails":0,"name":"status 200","path":"::status 200","id":"fad9fa412b86fcb03bee97c80dcd61f1","passes":2453},{"name":"full page","path":"::full page","id":"736a4affc4111c8285c374c0b4d25aed","passes":2453,"fails":0}],"name":"","path":""},"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"isStdOutTTY":false,"isStdErrTTY":false,"testRunDurationMs":5001.948628}}
|
||||
@@ -0,0 +1 @@
|
||||
{"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"testRunDurationMs":5019.671711,"isStdOutTTY":false,"isStdErrTTY":false},"metrics":{"data_received":{"values":{"count":47243955,"rate":9411761.907949204},"type":"counter","contains":"data"},"vus_max":{"type":"gauge","contains":"default","values":{"value":16,"min":16,"max":16}},"http_req_receiving":{"values":{"avg":0.024742592295839763,"min":0.008459,"med":0.019292,"p(50)":0.019292,"p(95)":0.05186679999999999,"p(99)":0.10284651999999997,"max":0.438125},"type":"trend","contains":"time"},"http_reqs":{"type":"counter","contains":"default","values":{"rate":646.4566184455803,"count":3245}},"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_waiting":{"type":"trend","contains":"time","values":{"p(95)":46.18396639999993,"p(99)":71.60269499999998,"max":114.556125,"avg":24.59960431093986,"min":8.968417,"med":21.929209,"p(50)":21.929209}},"http_req_sending":{"values":{"min":0.001792,"med":0.003,"p(50)":0.003,"p(95)":0.008458,"p(99)":0.018902999999999996,"max":0.130666,"avg":0.0039610767334360975},"type":"trend","contains":"time"},"iterations":{"type":"counter","contains":"default","values":{"count":3245,"rate":646.4566184455803}},"http_req_blocked":{"contains":"time","values":{"avg":0.003439970724191103,"min":0.0005,"med":0.000917,"p(50)":0.000917,"p(95)":0.002167,"p(99)":0.0061485199999999985,"max":0.585125},"type":"trend"},"checks":{"type":"rate","contains":"default","values":{"rate":1,"passes":6490,"fails":0}},"vus":{"type":"gauge","contains":"default","values":{"value":16,"min":16,"max":16}},"iteration_duration":{"type":"trend","contains":"time","values":{"max":114.636042,"avg":24.702842439753418,"min":9.031625,"med":22.034792,"p(50)":22.034792,"p(95)":46.357516799999914,"p(99)":71.70724799999998}},"http_req_failed":{"type":"rate","contains":"default","values":{"passes":0,"fails":3245,"rate":0}},"http_req_duration{expected_response:true}":{"contains":"time","values":{"min":8.984208,"med":21.958834,"p(50)":21.958834,"p(95)":46.24320819999993,"p(99)":71.63251995999998,"max":114.57775,"avg":24.628307979969204},"thresholds":{"max>=0":{"ok":true}},"type":"trend"},"http_req_duration":{"type":"trend","contains":"time","values":{"p(99)":71.63251995999998,"max":114.57775,"avg":24.628307979969204,"min":8.984208,"med":21.958834,"p(50)":21.958834,"p(95)":46.24320819999993}},"data_sent":{"values":{"count":1356410,"rate":270218.8665102525},"type":"counter","contains":"data"},"http_req_connecting":{"type":"trend","contains":"time","values":{"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0.1645,"avg":0.000370775654853621}}},"root_group":{"name":"","path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"name":"status 200","path":"::status 200","id":"fad9fa412b86fcb03bee97c80dcd61f1","passes":3245,"fails":0},{"fails":0,"name":"full page","path":"::full page","id":"736a4affc4111c8285c374c0b4d25aed","passes":3245}]}}
|
||||
@@ -0,0 +1 @@
|
||||
{"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"isStdOutTTY":false,"isStdErrTTY":false,"testRunDurationMs":5011.529779},"metrics":{"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}},"http_req_duration{expected_response:true}":{"type":"trend","contains":"time","values":{"max":45.538875,"avg":5.689445096292062,"min":3.606375,"med":5.338625,"p(50)":5.338625,"p(95)":7.03525,"p(99)":9.824547999999993},"thresholds":{"max>=0":{"ok":true}}},"http_req_failed":{"type":"rate","contains":"default","values":{"fails":3479,"rate":0,"passes":0}},"data_sent":{"type":"counter","contains":"data","values":{"count":1454222,"rate":290175.26865622564}},"data_received":{"type":"counter","contains":"data","values":{"count":50650761,"rate":10106846.259248776}},"iteration_duration":{"type":"trend","contains":"time","values":{"p(50)":5.399542,"p(95)":7.147579499999998,"p(99)":9.941798519999988,"max":45.592625,"avg":5.756671475998839,"min":3.661667,"med":5.399542}},"http_req_sending":{"type":"trend","contains":"time","values":{"med":0.002792,"p(50)":0.002792,"p(95)":0.00675,"p(99)":0.017477259999999998,"max":0.241125,"avg":0.003896505605058975,"min":0.001666}},"vus":{"type":"gauge","contains":"default","values":{"max":4,"value":4,"min":4}},"iterations":{"type":"counter","contains":"default","values":{"count":3479,"rate":694.1992073115446}},"http_req_receiving":{"type":"trend","contains":"time","values":{"p(99)":0.0865657599999999,"max":0.3295,"avg":0.022590152917505008,"min":0.007375,"med":0.018333,"p(50)":0.018333,"p(95)":0.04400409999999999}},"http_req_duration":{"type":"trend","contains":"time","values":{"avg":5.689445096292062,"min":3.606375,"med":5.338625,"p(50)":5.338625,"p(95)":7.03525,"p(99)":9.824547999999993,"max":45.538875}},"vus_max":{"values":{"value":4,"min":4,"max":4},"type":"gauge","contains":"default"},"http_req_blocked":{"type":"trend","contains":"time","values":{"p(95)":0.001916,"p(99)":0.0031340199999999986,"max":0.700708,"avg":0.001768398102903145,"min":0.000541,"med":0.000875,"p(50)":0.000875}},"http_req_waiting":{"type":"trend","contains":"time","values":{"avg":5.662958437769487,"min":3.582459,"med":5.316708,"p(50)":5.316708,"p(95)":6.996358,"p(99)":9.792100979999994,"max":45.517916}},"http_req_connecting":{"contains":"time","values":{"p(50)":0,"p(95)":0,"p(99)":0,"max":0.190542,"avg":0.00017812848519689565,"min":0,"med":0},"type":"trend"},"http_reqs":{"type":"counter","contains":"default","values":{"count":3479,"rate":694.1992073115446}},"checks":{"contains":"default","values":{"rate":1,"passes":6958,"fails":0},"type":"rate"}},"root_group":{"groups":[],"checks":[{"path":"::status 200","id":"fad9fa412b86fcb03bee97c80dcd61f1","passes":3479,"fails":0,"name":"status 200"},{"path":"::full page","id":"736a4affc4111c8285c374c0b4d25aed","passes":3479,"fails":0,"name":"full page"}],"name":"","path":"","id":"d41d8cd98f00b204e9800998ecf8427e"}}
|
||||
@@ -0,0 +1 @@
|
||||
{"metrics":{"http_req_failed":{"type":"rate","contains":"default","values":{"fails":2644,"rate":0,"passes":0}},"http_reqs":{"values":{"count":2644,"rate":528.76398207808},"type":"counter","contains":"default"},"http_req_connecting":{"type":"trend","contains":"time","values":{"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0.113167,"avg":0.000042801437216338884}},"http_req_blocked":{"type":"trend","contains":"time","values":{"min":0.000541,"med":0.000958,"p(50)":0.000958,"p(95)":0.001875,"p(99)":0.0028153699999999993,"max":0.481166,"avg":0.0012639568835098244}},"http_req_tls_handshaking":{"contains":"time","values":{"avg":0,"min":0,"med":0,"p(50)":0,"p(95)":0,"p(99)":0,"max":0},"type":"trend"},"vus":{"type":"gauge","contains":"default","values":{"min":1,"max":1,"value":1}},"http_req_waiting":{"type":"trend","contains":"time","values":{"p(95)":2.1086411999999997,"p(99)":2.48973644,"max":5.192542,"avg":1.7930774803328309,"min":1.51975,"med":1.757021,"p(50)":1.757021}},"data_sent":{"type":"counter","contains":"data","values":{"count":1105192,"rate":221023.34450863744}},"http_req_duration":{"type":"trend","contains":"time","values":{"p(95)":2.156706249999999,"p(99)":2.54961031,"max":5.288125,"avg":1.820558904689867,"min":1.551166,"med":1.7807705,"p(50)":1.7807705}},"http_req_sending":{"values":{"avg":0.0038285355521936824,"min":0.001708,"med":0.002792,"p(50)":0.002792,"p(95)":0.006660699999999995,"p(99)":0.018350939999999986,"max":0.41575},"type":"trend","contains":"time"},"checks":{"type":"rate","contains":"default","values":{"passes":5288,"fails":0,"rate":1}},"iteration_duration":{"values":{"p(95)":2.24451065,"p(99)":2.6700183699999998,"max":5.453458,"avg":1.8878566168683786,"min":1.600708,"med":1.8409165,"p(50)":1.8409165},"type":"trend","contains":"time"},"vus_max":{"type":"gauge","contains":"default","values":{"value":1,"min":1,"max":1}},"http_req_receiving":{"type":"trend","contains":"time","values":{"p(99)":0.06927338,"max":0.384875,"avg":0.02365288880484111,"min":0.010208,"med":0.019333,"p(50)":0.019333,"p(95)":0.046493849999999996}},"data_received":{"type":"counter","contains":"data","values":{"count":38493996,"rate":7698274.815074766}},"iterations":{"type":"counter","contains":"default","values":{"count":2644,"rate":528.76398207808}},"http_req_duration{expected_response:true}":{"type":"trend","contains":"time","values":{"med":1.7807705,"p(50)":1.7807705,"p(95)":2.156706249999999,"p(99)":2.54961031,"max":5.288125,"avg":1.820558904689867,"min":1.551166},"thresholds":{"max>=0":{"ok":true}}}},"root_group":{"name":"","path":"","id":"d41d8cd98f00b204e9800998ecf8427e","groups":[],"checks":[{"name":"status 200","path":"::status 200","id":"fad9fa412b86fcb03bee97c80dcd61f1","passes":2644,"fails":0},{"name":"full page","path":"::full page","id":"736a4affc4111c8285c374c0b4d25aed","passes":2644,"fails":0}]},"options":{"summaryTrendStats":["avg","min","med","p(50)","p(95)","p(99)","max"],"summaryTimeUnit":"","noColor":true},"state":{"isStdErrTTY":false,"testRunDurationMs":5000.340586,"isStdOutTTY":false}}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user