Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
This commit is contained in:
1 parent
288e6e94ac
commit
c1175d389f
699 files changed
+110197
-4117
No files matched your search
@@ -0,0 +1,58 @@
|
||||
# PagesWiki design documentation
|
||||
|
||||
## Current reading order
|
||||
|
||||
The reorganized Japanese handbook is [ja/index.md](ja/index.md), published under
|
||||
`https://pages.anya.jp/lab/pageswiki-dev/`. It separates implemented slices,
|
||||
proposals, unresolved decisions and delivery gates. Its chapter identifiers are
|
||||
language-neutral; existing English source documents remain here for traceability
|
||||
and future aligned translations, not as automatically current English editions.
|
||||
|
||||
- Concepts and boundaries: chapters 1–6.
|
||||
- Existing product and runtime: chapters 7–11.
|
||||
- Organizer / task / calendar / RSS / mail / HTML editing proposals: chapters 12–17.
|
||||
- Operations, i18n, ordered work, decisions and sources: chapters 18–22.
|
||||
- [Source-to-chapter inventory](ja/sources.md).
|
||||
- [Decision and inconsistency register](ja/decisions.md).
|
||||
|
||||
## Document roles
|
||||
|
||||
`arch.md`, `address-model.md`, `access-model.md`, `auth.md` and `i18n-delivery.md`
|
||||
include original conceptual drafts. Detailed topic documents describe contracts
|
||||
and implementation slices. `implementation-status.md` contains dated progress;
|
||||
older paragraphs are historical and may be superseded. The roadmap is a task
|
||||
inventory; the execution ledger is verification/deployment history, not a blanket
|
||||
feature-completeness claim.
|
||||
|
||||
For new work, update the relevant chapter and detailed contract together. Keep
|
||||
stable identity, authorization and bounded processing constraints. Do not convert
|
||||
design proposals into active features or public grants merely by documenting them.
|
||||
|
||||
## Publication
|
||||
|
||||
Japanese Markdown under `ja/` is the editing source. The documentation export
|
||||
tool renders canonical HTML with the application's Markdown renderer, validates
|
||||
chapter links, and emits a manifest. Upload through the trusted data CLI with an
|
||||
explicit Domain and `PAGESWIKI_LANG=ja`; no authentication/publication policy is
|
||||
changed. Record resulting Page/Revision identities separately from source text.
|
||||
English publication is deferred until an aligned translation and language UI
|
||||
are ready. Never overwrite Japanese with English at language `und`.
|
||||
|
||||
Generate a fresh, empty staging directory, then run:
|
||||
|
||||
```sh
|
||||
go run ./tools/design-export -out /tmp/pageswiki-design-staging
|
||||
go test ./tools/design-export
|
||||
```
|
||||
|
||||
The tool does not access the database or network. Review `manifest.json`, check
|
||||
destination collisions, and select the correct database/Domain explicitly before
|
||||
using `data/pageswiki-cli put` for each rendered HTML file and manifest Path.
|
||||
The index maps to `/lab/pageswiki-dev`, not `/lab/pageswiki-dev/index`.
|
||||
Do not blindly replace existing Wiki edits on a later publication: compare the
|
||||
recorded Revision UUID/hash with the current head and resolve divergence first.
|
||||
|
||||
The initial upload receipt is [publication-ja-2026-09-19.json](publication-ja-2026-09-19.json).
|
||||
All 23 canonical payloads were read back and compared. Source hashes and stored
|
||||
Page/Revision identities support later language alignment. Anonymous HTTPS access
|
||||
still redirects to login; this upload did not change public access settings.
|
||||
@@ -0,0 +1,665 @@
|
||||
# Access Model draft
|
||||
|
||||
## Goal
|
||||
|
||||
Separate:
|
||||
|
||||
```text
|
||||
knowledge navigation
|
||||
projection rendering
|
||||
editing surfaces
|
||||
object retrieval
|
||||
native execution
|
||||
```
|
||||
|
||||
into independent runtime layers.
|
||||
|
||||
The system treats:
|
||||
|
||||
```
|
||||
content != rendering != editor != storage
|
||||
```
|
||||
|
||||
as a core architectural principle.
|
||||
|
||||
# Core Principle
|
||||
|
||||
Pages Wiki does NOT treat editors as canonical reality.
|
||||
|
||||
Editors are:
|
||||
|
||||
```text
|
||||
authoring projections
|
||||
```
|
||||
|
||||
onto canonical semantic object structures.
|
||||
|
||||
Canonical storage is:
|
||||
|
||||
```text
|
||||
DOM/object graph centered
|
||||
```
|
||||
|
||||
depending on object class.
|
||||
|
||||
# High-Level Access Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
KA[Knowledge Access]
|
||||
PA[Projection Access]
|
||||
EA[Editing Access]
|
||||
OA[Object Access]
|
||||
NA[Native Access]
|
||||
|
||||
KA --> PA
|
||||
PA --> EA
|
||||
|
||||
PA --> OA
|
||||
EA --> OA
|
||||
|
||||
PA --> NA
|
||||
EA --> NA
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# 1. Knowledge Access
|
||||
|
||||
## Purpose
|
||||
|
||||
Semantic navigation for humans.
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
/research/network/bgp
|
||||
/dev/api/auth
|
||||
/hr/onboarding
|
||||
```
|
||||
|
||||
# Responsibilities
|
||||
|
||||
- semantic routing
|
||||
- hierarchy traversal
|
||||
- language negotiation
|
||||
- capability evaluation
|
||||
- object resolution
|
||||
|
||||
# Output
|
||||
|
||||
Usually:
|
||||
|
||||
```text
|
||||
rendered semantic projection
|
||||
```
|
||||
|
||||
# Resolution Pipeline
|
||||
|
||||
```text
|
||||
path
|
||||
↓
|
||||
uuid
|
||||
↓
|
||||
revision
|
||||
↓
|
||||
projection
|
||||
```
|
||||
|
||||
# Important Principle
|
||||
|
||||
Knowledge access is:
|
||||
|
||||
```text
|
||||
human semantic navigation
|
||||
```
|
||||
|
||||
NOT raw object retrieval.
|
||||
|
||||
# 2. Projection Access
|
||||
|
||||
## Purpose
|
||||
|
||||
Interpret semantic objects into runtime surfaces.
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
/_/view/flow/uuid:abcd
|
||||
/_/view/slides/uuid:abcd
|
||||
/_/view/sheet/uuid:abcd
|
||||
/_/view/print/uuid:abcd
|
||||
/_/view/canvas/uuid:abcd
|
||||
```
|
||||
|
||||
# Projection Examples
|
||||
|
||||
| Projection | Meaning |
|
||||
| --- | --- |
|
||||
| `flow` | Flowing article |
|
||||
| `slides` | Staged presentation |
|
||||
| `print` | Printable layout |
|
||||
| `sheet` | Spreadsheet runtime |
|
||||
| `canvas` | Whiteboard/canvas |
|
||||
| `topology` | Graph topology |
|
||||
| `preview` | Lightweight rendering |
|
||||
|
||||
# Important Principle
|
||||
|
||||
Projection is:
|
||||
|
||||
```text
|
||||
runtime interpretation
|
||||
```
|
||||
|
||||
NOT canonical storage.
|
||||
|
||||
# Same Object, Multiple Projections
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
OBJ[Semantic Object]
|
||||
|
||||
FLOW[Flow Projection]
|
||||
SLIDE[Slides Projection]
|
||||
PRINT[Print Projection]
|
||||
SHEET[Sheet Projection]
|
||||
|
||||
OBJ --> FLOW
|
||||
OBJ --> SLIDE
|
||||
OBJ --> PRINT
|
||||
OBJ --> SHEET
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# 3. Editing Access
|
||||
|
||||
## Purpose
|
||||
|
||||
Provide authoring surfaces.
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Editors are:
|
||||
|
||||
```text
|
||||
projection-specific authoring surfaces
|
||||
```
|
||||
|
||||
NOT canonical storage owners.
|
||||
|
||||
* * *
|
||||
|
||||
# Editor Pipeline
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
EDITOR[Editor]
|
||||
AST[Semantic Object Graph]
|
||||
REV[Revision Snapshot]
|
||||
|
||||
EDITOR --> AST
|
||||
AST --> REV
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Supported Editors
|
||||
|
||||
| Editor | Purpose |
|
||||
| --- | --- |
|
||||
| Markdown | Lightweight flow editing |
|
||||
| WYSIWYG | Visual article editing |
|
||||
| Raw HTML | Direct DOM editing |
|
||||
| Slide Editor | Presentation authoring |
|
||||
| Sheet Editor | Spreadsheet runtime editing |
|
||||
| Whiteboard Editor | Canvas editing |
|
||||
| DrawIO-like Editor | Topology editing |
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
All editors ultimately produce:
|
||||
|
||||
```text
|
||||
semantic object graph
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```text
|
||||
canonical DOM representation
|
||||
```
|
||||
|
||||
depending on object class.
|
||||
|
||||
* * *
|
||||
|
||||
# Editor Negotiation
|
||||
|
||||
Runtime selects editor based on:
|
||||
|
||||
- object class
|
||||
- supported projection types
|
||||
- runtime capabilities
|
||||
- user preferences
|
||||
- available native integrations
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
HTML article
|
||||
```
|
||||
|
||||
Available editors:
|
||||
|
||||
- Markdown
|
||||
- WYSIWYG
|
||||
- Raw HTML
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
Presentation object
|
||||
```
|
||||
|
||||
Available editors:
|
||||
|
||||
- Slide editor
|
||||
- Raw DOM editor
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
Spreadsheet object
|
||||
```
|
||||
|
||||
Available editors:
|
||||
|
||||
- Sheet runtime editor
|
||||
- Native Excel integration
|
||||
|
||||
* * *
|
||||
|
||||
# 4. Object Access
|
||||
|
||||
## Purpose
|
||||
|
||||
Raw immutable object retrieval.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
/_/obj/sha256:abcd
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Typical Objects
|
||||
|
||||
- PDF
|
||||
- PPTX
|
||||
- XLSX
|
||||
- PNG
|
||||
- SVG
|
||||
- JS
|
||||
- CSS
|
||||
- DrawIO payload
|
||||
- Excalidraw payload
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Object access is:
|
||||
|
||||
```text
|
||||
transport/storage retrieval
|
||||
```
|
||||
|
||||
NOT semantic navigation.
|
||||
|
||||
* * *
|
||||
|
||||
# Object Access Pipeline
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
OBJREF[Object Reference]
|
||||
FETCH[Object Fetch]
|
||||
CACHE[Cache/CDN]
|
||||
RETURN[Runtime Consumer]
|
||||
|
||||
OBJREF --> FETCH
|
||||
FETCH --> CACHE
|
||||
CACHE --> RETURN
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Object retrieval supports:
|
||||
|
||||
- deduplication
|
||||
- CDN caching
|
||||
- immutable references
|
||||
- snapshot reproducibility
|
||||
- derived object generation
|
||||
|
||||
* * *
|
||||
|
||||
# 5. Native Access
|
||||
|
||||
## Purpose
|
||||
|
||||
Bridge semantic objects into local/native applications.
|
||||
|
||||
> Implementation status: TODO. The current integration-adapter runtime only
|
||||
> permits hosted HTTP(S) viewers and editors. Direct executable launch requires
|
||||
> a separately designed local helper, temporary workspace, credential store,
|
||||
> executable allowlist, conflict detection, and Revision write-back protocol.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
| Semantic Link | Native Projection |
|
||||
| --- | --- |
|
||||
| `teams.office.com` | `msteams://` |
|
||||
| `mailto:` | Mail client |
|
||||
| `tel:` | Dialer |
|
||||
| `vscode://` | VS Code |
|
||||
| `figma://` | Figma |
|
||||
| `slack://` | Slack |
|
||||
|
||||
* * *
|
||||
|
||||
# Native Resolution Pipeline
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
LINK[Semantic Link]
|
||||
RES[Resolver]
|
||||
NATIVE[Native Handler]
|
||||
WEB[Web Fallback]
|
||||
|
||||
LINK --> RES
|
||||
|
||||
RES --> NATIVE
|
||||
RES --> WEB
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Links represent:
|
||||
|
||||
```text
|
||||
semantic execution intent
|
||||
```
|
||||
|
||||
NOT fixed transport mechanisms.
|
||||
|
||||
* * *
|
||||
|
||||
# Runtime chooses:
|
||||
|
||||
- native app
|
||||
- browser fallback
|
||||
- embedded projection
|
||||
- external mounted surface
|
||||
|
||||
depending on environment.
|
||||
|
||||
* * *
|
||||
|
||||
# 6. Workspace Plane vs Revision Plane
|
||||
|
||||
## Workspace Plane
|
||||
|
||||
Mutable editing world.
|
||||
|
||||
Contains:
|
||||
|
||||
- path
|
||||
- alias
|
||||
- asset
|
||||
- live editors
|
||||
|
||||
* * *
|
||||
|
||||
# Revision Plane
|
||||
|
||||
Immutable historical world.
|
||||
|
||||
Contains:
|
||||
|
||||
- revision
|
||||
- sha256 snapshots
|
||||
- derived projections
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Editors operate on:
|
||||
|
||||
```text
|
||||
workspace objects
|
||||
```
|
||||
|
||||
Revisions store:
|
||||
|
||||
```text
|
||||
immutable semantic snapshots
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# 7. Canonical Storage Principle
|
||||
|
||||
Canonical storage depends on object class.
|
||||
|
||||
* * *
|
||||
|
||||
# Flow Articles
|
||||
|
||||
Canonical form:
|
||||
|
||||
```text
|
||||
HTML DOM
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Presentation Objects
|
||||
|
||||
Canonical form:
|
||||
|
||||
```text
|
||||
presentation object graph
|
||||
```
|
||||
|
||||
Projected into:
|
||||
|
||||
- SVG sections
|
||||
- HTML slides
|
||||
- print layouts
|
||||
|
||||
* * *
|
||||
|
||||
# Spreadsheet Objects
|
||||
|
||||
Canonical form:
|
||||
|
||||
```text
|
||||
structured semantic table graph
|
||||
```
|
||||
|
||||
Projected into:
|
||||
|
||||
- HTML tables
|
||||
- spreadsheet runtime
|
||||
- CSV
|
||||
- print layouts
|
||||
|
||||
* * *
|
||||
|
||||
# Canvas/Whiteboard Objects
|
||||
|
||||
Canonical form:
|
||||
|
||||
```text
|
||||
spatial object graph
|
||||
```
|
||||
|
||||
Projected into:
|
||||
|
||||
- SVG
|
||||
- interactive canvas
|
||||
- thumbnails
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Projection-specific formats are:
|
||||
|
||||
```text
|
||||
runtime surfaces
|
||||
```
|
||||
|
||||
NOT canonical storage truth.
|
||||
|
||||
* * *
|
||||
|
||||
# 8. Embedded Object Model
|
||||
|
||||
Embedded objects may be:
|
||||
|
||||
| Type | Meaning |
|
||||
| --- | --- |
|
||||
| Inline | Embedded payload |
|
||||
| Linked | Immutable external object |
|
||||
| Mounted | Live external application |
|
||||
| Derived | Generated projection |
|
||||
| Lazy | Runtime-fetched object |
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```html
|
||||
<embedded-object
|
||||
kind="drawio"
|
||||
immutable-ref="sha256:abcd"
|
||||
></embedded-object>
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Large payloads should generally use:
|
||||
|
||||
```text
|
||||
external immutable object references
|
||||
```
|
||||
|
||||
instead of giant inline blobs.
|
||||
|
||||
* * *
|
||||
|
||||
# 9. Semantic Link Model
|
||||
|
||||
Semantic links may resolve into:
|
||||
|
||||
- knowledge paths
|
||||
- projections
|
||||
- native applications
|
||||
- external services
|
||||
- embedded runtimes
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
/research/network/bgp
|
||||
```
|
||||
|
||||
may contain:
|
||||
|
||||
```text
|
||||
teams://
|
||||
mailto:
|
||||
vscode://
|
||||
figma://
|
||||
tel:
|
||||
```
|
||||
|
||||
runtime-aware semantic links.
|
||||
|
||||
* * *
|
||||
|
||||
# 10. Final Architectural Direction
|
||||
|
||||
Pages Wiki evolves toward:
|
||||
|
||||
```text
|
||||
semantic knowledge runtime environment
|
||||
```
|
||||
|
||||
rather than:
|
||||
|
||||
```text
|
||||
filesystem-oriented wiki
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Conceptual Summary
|
||||
|
||||
| Layer | Responsibility |
|
||||
| --- | --- |
|
||||
| Knowledge Access | Semantic navigation |
|
||||
| Projection Access | Runtime interpretation |
|
||||
| Editing Access | Authoring surfaces |
|
||||
| Object Access | Immutable retrieval |
|
||||
| Native Access | Local runtime execution |
|
||||
|
||||
* * *
|
||||
|
||||
# Final Principle
|
||||
|
||||
Pages Wiki separates:
|
||||
|
||||
```text
|
||||
meaning
|
||||
identity
|
||||
projection
|
||||
editing
|
||||
storage
|
||||
runtime execution
|
||||
```
|
||||
|
||||
into independent architectural planes.
|
||||
@@ -0,0 +1,644 @@
|
||||
# Address Model Draft
|
||||
|
||||
## Goal
|
||||
|
||||
Separate:
|
||||
|
||||
```text
|
||||
identity
|
||||
reachability
|
||||
semantic meaning
|
||||
projection
|
||||
mutability
|
||||
```
|
||||
|
||||
into independent address layers.
|
||||
|
||||
The addressing model is designed to support:
|
||||
|
||||
- semantic navigation
|
||||
- immutable revisions
|
||||
- mutable editing workspaces
|
||||
- object storage
|
||||
- projection rendering
|
||||
- delegated sharing
|
||||
- graph-capable knowledge topology
|
||||
|
||||
## Core Principle
|
||||
|
||||
```text
|
||||
Address != Meaning
|
||||
```
|
||||
|
||||
Addresses are:
|
||||
|
||||
```text
|
||||
reachable locators
|
||||
```
|
||||
|
||||
NOT semantic meaning themselves.
|
||||
|
||||
* * *
|
||||
|
||||
# Address Layer Overview
|
||||
|
||||
| Scheme | Purpose | Mutable | Human-oriented |
|
||||
| --- | --- | --- | --- |
|
||||
| `path:` | Semantic navigation | yes | yes |
|
||||
| `uuid:` | Stable Page/Object identity | no | partially |
|
||||
| `rev:` | Immutable historical snapshot | no | no |
|
||||
| `sha256:` | Immutable content identity | no | no |
|
||||
| `asset:` | Mutable editable workspace | yes | partially |
|
||||
| `alias:` | Semantic pointer | yes | yes |
|
||||
| `share:` | Delegated capability projection | caveat-bound | yes |
|
||||
| `derived:` | Generated object | preferably no | no |
|
||||
| `external:` | Foreign mounted object | provider-defined | partially |
|
||||
|
||||
* * *
|
||||
|
||||
# 1. path:
|
||||
|
||||
## Purpose
|
||||
|
||||
Human semantic routing namespace.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
/research/network/bgp
|
||||
/dev/api/auth
|
||||
/hr/onboarding
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value mutable yes human-readable yes semantic yes canonical identity no
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Paths are:
|
||||
|
||||
```text
|
||||
semantic navigation surfaces
|
||||
```
|
||||
|
||||
NOT canonical object identities.
|
||||
|
||||
* * *
|
||||
|
||||
# Resolution Flow
|
||||
|
||||
```text
|
||||
path
|
||||
↓
|
||||
uuid
|
||||
↓
|
||||
revision
|
||||
↓
|
||||
projection
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# 2. uuid:
|
||||
|
||||
## Purpose
|
||||
|
||||
Stable semantic object identity.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
uuid:550e8400-e29b-41d4-a716-446655440000
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value mutable no semantic no canonical identity yes stable yes
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
UUIDs are:
|
||||
|
||||
```text
|
||||
opaque reachable locators
|
||||
```
|
||||
|
||||
NOT semantic meaning.
|
||||
|
||||
* * *
|
||||
|
||||
# UUID Targets
|
||||
|
||||
UUID may identify:
|
||||
|
||||
- HTML document object
|
||||
- PDF semantic object
|
||||
- Spreadsheet object
|
||||
- DrawIO semantic object
|
||||
- Presentation object
|
||||
- Embedded semantic object
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
UUID does NOT imply rendering format.
|
||||
|
||||
Projection decides interpretation.
|
||||
|
||||
* * *
|
||||
|
||||
# 3. rev:
|
||||
|
||||
## Purpose
|
||||
|
||||
Immutable historical semantic snapshot.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
rev:018f6b5d...
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value immutable yes historical yes reproducible yes
|
||||
|
||||
* * *
|
||||
|
||||
# Revision Responsibilities
|
||||
|
||||
A revision freezes:
|
||||
|
||||
- HTML structure
|
||||
- embedded object references
|
||||
- semantic state
|
||||
- projection state
|
||||
|
||||
A Revision has its own UUID. Immutable payload identity is represented
|
||||
separately by `sha256:`. A Revision record links a Page UUID, language tag,
|
||||
Document hash, authoring metadata, and creation time.
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Revisions MUST reference:
|
||||
|
||||
```text
|
||||
immutable object references only
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Forbidden
|
||||
|
||||
```text
|
||||
revision -> mutable asset HEAD
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Allowed
|
||||
|
||||
```text
|
||||
revision -> sha256 immutable snapshot
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# 4. sha256:
|
||||
|
||||
## Purpose
|
||||
|
||||
Immutable content-addressed object identity.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
sha256:deadbeef...
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value immutable yes content-addressed yes deduplicatable yes cacheable yes
|
||||
|
||||
* * *
|
||||
|
||||
# Typical Targets
|
||||
|
||||
- DrawIO payload
|
||||
- Excalidraw payload
|
||||
- PDF binary
|
||||
- Image
|
||||
- CSS snapshot
|
||||
- JS snapshot
|
||||
- PPTX binary
|
||||
- XLSX binary
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
sha256 objects are:
|
||||
|
||||
```text
|
||||
historical truth
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# 5. asset:
|
||||
|
||||
The normative lifecycle, freezing, authorization, and retention rules are in
|
||||
[`asset-model.md`](asset-model.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
Mutable editable workspace object.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
asset:drawio:network-core
|
||||
asset:xlsx:q1-budget
|
||||
asset:slide:roadmap
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value mutable yes editable yes workspace-oriented yes
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Assets represent:
|
||||
|
||||
```text
|
||||
current editable HEAD
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Save Flow
|
||||
|
||||
```text
|
||||
asset mutable HEAD
|
||||
↓
|
||||
save
|
||||
↓
|
||||
snapshot
|
||||
↓
|
||||
sha256 immutable object
|
||||
```
|
||||
|
||||
For HTML Revisions, supported embedding attributes containing an `asset:`
|
||||
address are resolved at save time. Unresolved Asset HEADs reject the save.
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Asset identity represents:
|
||||
|
||||
```text
|
||||
semantic continuity of editing
|
||||
```
|
||||
|
||||
NOT immutable historical truth.
|
||||
|
||||
* * *
|
||||
|
||||
# 6. alias:
|
||||
|
||||
## Purpose
|
||||
|
||||
Semantic indirection pointer.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
alias:latest-network-design
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value mutable yes semantic yes canonical no
|
||||
|
||||
* * *
|
||||
|
||||
# Typical Uses
|
||||
|
||||
- latest stable design
|
||||
- current handbook
|
||||
- canonical public URL
|
||||
- migration pointer
|
||||
|
||||
* * *
|
||||
|
||||
# 7. share:
|
||||
|
||||
## Purpose
|
||||
|
||||
Delegated capability projection.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
share:abcdef
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Typical Projection
|
||||
|
||||
```text
|
||||
/s/abcdef
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value temporary usually delegated yes capability-bound yes
|
||||
|
||||
* * *
|
||||
|
||||
# Internal Model
|
||||
|
||||
Share addresses usually resolve to:
|
||||
|
||||
```text
|
||||
macaroon delegated capability
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# 8. derived:
|
||||
|
||||
## Purpose
|
||||
|
||||
Generated/transformed object identity.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
derived:thumbnail:sha256:abcd
|
||||
derived:ocr:sha256:abcd
|
||||
derived:preview-svg:sha256:abcd
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value generated yes reproducible usually immutable preferred
|
||||
|
||||
* * *
|
||||
|
||||
# Typical Derived Objects
|
||||
|
||||
- thumbnails
|
||||
- OCR text
|
||||
- SVG previews
|
||||
- rendered PDF pages
|
||||
- AI summaries
|
||||
- embeddings
|
||||
|
||||
* * *
|
||||
|
||||
# 9. external:
|
||||
|
||||
## Purpose
|
||||
|
||||
Mounted foreign object reference.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
external:gdrive:file123
|
||||
external:figma:abcd
|
||||
external:slack:thread456
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Properties
|
||||
|
||||
Property Value foreign ownership yes mutability external-defined projection-capable yes
|
||||
|
||||
* * *
|
||||
|
||||
# Runtime Resolution Pipeline
|
||||
|
||||
```text
|
||||
path
|
||||
↓
|
||||
uuid
|
||||
↓
|
||||
revision
|
||||
↓
|
||||
projection
|
||||
↓
|
||||
embedded object resolution
|
||||
↓
|
||||
sha256 / asset / external
|
||||
↓
|
||||
renderer
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Projection Principle
|
||||
|
||||
## Address != Rendering
|
||||
|
||||
Rendering is determined by:
|
||||
|
||||
- mime type
|
||||
- object class
|
||||
- projection adapter
|
||||
- user context
|
||||
- runtime capability
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
uuid:abcd
|
||||
```
|
||||
|
||||
may render as:
|
||||
|
||||
- HTML article
|
||||
- PDF viewer
|
||||
- slide deck
|
||||
- spreadsheet runtime
|
||||
- whiteboard canvas
|
||||
|
||||
depending on projection adapter.
|
||||
|
||||
The adapter contract, bounded-delivery rules, and structured-format roadmap
|
||||
are defined in [projection-adapters.md](projection-adapters.md).
|
||||
|
||||
* * *
|
||||
|
||||
## Raw Document Projection
|
||||
|
||||
Raw payload delivery is a projection, not another identity namespace. The
|
||||
HTTP form therefore carries an explicit internal address:
|
||||
|
||||
```text
|
||||
/v/raw/path:/manual/report
|
||||
/v/raw/uuid:550e8400-e29b-41d4-a716-446655440000
|
||||
/v/raw/rev:018f6b5d...
|
||||
```
|
||||
|
||||
Viewer embeds `path:` when displaying the current semantic projection.
|
||||
Immutable Revision Viewer embeds `rev:`. A bare `/raw/<semantic-path>` is
|
||||
forbidden because it conflates projection, reachability, and identity.
|
||||
|
||||
## Path Rename
|
||||
|
||||
Rename changes reachability, not Page identity. It is committed atomically as:
|
||||
|
||||
```text
|
||||
link(new-path, existing-page-uuid)
|
||||
unlink(old-path, existing-page-uuid)
|
||||
```
|
||||
|
||||
Recursive rename applies the same mapping to every descendant in one database
|
||||
transaction. Destination collisions abort the entire operation. When the
|
||||
basename of an extension-bearing file changes, the latest language projections
|
||||
receive a new Revision carrying the new `filename`; older Revisions remain
|
||||
immutable.
|
||||
|
||||
* * *
|
||||
|
||||
# Mutability Model
|
||||
|
||||
| Layer | Mutable |
|
||||
| --- | --- |
|
||||
| `path:` | yes |
|
||||
| `alias:` | yes |
|
||||
| `asset:` | yes |
|
||||
| `uuid:` | no |
|
||||
| `rev:` | no |
|
||||
| `sha256:` | no |
|
||||
| `derived:` | preferably no |
|
||||
|
||||
* * *
|
||||
|
||||
# Important Separation
|
||||
|
||||
## Workspace Plane
|
||||
|
||||
Mutable editing world.
|
||||
|
||||
Contains:
|
||||
|
||||
- asset:
|
||||
- path:
|
||||
- alias:
|
||||
|
||||
* * *
|
||||
|
||||
# Revision Plane
|
||||
|
||||
Immutable historical world.
|
||||
|
||||
Contains:
|
||||
|
||||
- rev:
|
||||
- sha256:
|
||||
- derived:
|
||||
|
||||
* * *
|
||||
|
||||
# Core Architectural Principle
|
||||
|
||||
Pages Wiki separates:
|
||||
|
||||
```text
|
||||
semantic navigation
|
||||
identity
|
||||
content storage
|
||||
projection
|
||||
editing
|
||||
history
|
||||
```
|
||||
|
||||
into independent planes.
|
||||
|
||||
* * *
|
||||
|
||||
# Conceptual Summary
|
||||
|
||||
| Layer | Responsibility |
|
||||
| --- | --- |
|
||||
| `path:` | Semantic routing |
|
||||
| `uuid:` | Stable Page/Object identity |
|
||||
| `rev:` | Historical snapshot identity |
|
||||
| `sha256:` | Immutable content reality |
|
||||
| `asset:` | Mutable editing continuity |
|
||||
| Projection | Runtime interpretation |
|
||||
| Capability | Authorized reachability |
|
||||
|
||||
* * *
|
||||
|
||||
# Final Conceptual Direction
|
||||
|
||||
Pages Wiki evolves toward:
|
||||
|
||||
```text
|
||||
semantic knowledge routing
|
||||
+
|
||||
immutable object graph
|
||||
+
|
||||
projection-oriented rendering
|
||||
+
|
||||
capability-based reachability
|
||||
```
|
||||
|
||||
rather than:
|
||||
|
||||
```text
|
||||
filesystem-oriented page hierarchy
|
||||
```
|
||||
@@ -0,0 +1,438 @@
|
||||
# Overview
|
||||
|
||||
## Concept
|
||||
|
||||
Pages Wiki is designed as **semantic locality driven knowledge system** rather than a traditional filesystem wiki.
|
||||
|
||||
### Key properties
|
||||
|
||||
- Hierarchy-oriented UI
|
||||
- Graph-capable Internal model
|
||||
- Language-neutral Semantic paths
|
||||
- Capability-centric authorization
|
||||
- Delegated access via macaroons xxx
|
||||
|
||||
## Knowledge City Model
|
||||
|
||||
Pages Wiki don’t only comprises Machine friendly but also Human-Facing friendly with Knowledge City Model.
|
||||
|
||||
Knowledge City Model constitute five administrative division unit called ‘domain’, ‘quartier’, ‘street’, ‘spot’, ‘page’.
|
||||
|
||||
- ‘page’ is minimal knowledge unit.
|
||||
- ‘spot’ constitute multiple pages. Namely, spot is minimal knowledge group.
|
||||
|
||||
- An overgrown knowledge spot can’t be upgraded to a street.
|
||||
- ‘zone’ is managed unit in data structure.
|
||||
|
||||
- ‘street’ is group of spot. ‘street’ used minimal knowledge city block.
|
||||
|
||||
- If existed mixed spot and various page, it is unconsolidated street.
|
||||
- ‘quartier’ can be called if it consists of an aggregation of streets delineated through urban planning.
|
||||
|
||||
- An overgrown knowledge street can be upgraded to a quartier.
|
||||
- ‘Domain’ is really site group. For example, ’Domain’ may indicate division and department group, project, and team. ‘Domain’ used as subdomain space in URI.
|
||||
- ‘Domain’ managed by one ‘Campus’.
|
||||
|
||||
```mermaid
|
||||
|
||||
graph TD
|
||||
Cm[Campus]
|
||||
|
||||
DmA[Domain: Sales Unit]
|
||||
DmB[Domain: Technical Unit]
|
||||
DmC[Domain: Management Unit]
|
||||
|
||||
%% Campus から Domain への接続
|
||||
Cm-..->DmA
|
||||
Cm-..->DmB
|
||||
Cm-..->DmC
|
||||
|
||||
%% Zone定義(Quartier と Street を内包し、縦に並ぶよう調整)
|
||||
subgraph Zone ["Zone"]
|
||||
direction TB
|
||||
|
||||
%% Quartier レ法
|
||||
QtA[Quartier: Network]
|
||||
QtB[Quartier: Server]
|
||||
QtC[Quartier: Application]
|
||||
|
||||
%% Street レ法
|
||||
StA[Street: DNS]
|
||||
StB[Street: Web]
|
||||
StC[Street: Mail]
|
||||
|
||||
%% Zone内での上下関係を固定するための接続
|
||||
QtB-->StA
|
||||
QtB-->StB
|
||||
StB-.if it is overgrown, upgrade to 'quartier'.->QtB
|
||||
QtB-->StC
|
||||
end
|
||||
|
||||
%% Domain から Zone(Quartier) への接続
|
||||
DmB-->QtA
|
||||
DmB-->QtB
|
||||
DmB-->QtC
|
||||
|
||||
%% Zone(Street) から下位レイヤーへの接続
|
||||
SpA[Spot: Web Infrastructure]
|
||||
SpB[Spot: Wiki Application]
|
||||
SpC[Spot: Search Engine]
|
||||
|
||||
StB-->SpA
|
||||
StB-->SpB
|
||||
StB-->SpC
|
||||
|
||||
%% Spot から Page への接続
|
||||
PgA[Page: Access Control Model]
|
||||
PgB[Page: Addressing Model]
|
||||
PgC[Page: Authenticating Model]
|
||||
|
||||
SpB-->PgA
|
||||
SpB-->PgB
|
||||
SpB-->PgC
|
||||
```
|
||||
|
||||
## Internal Semantic Structure
|
||||
|
||||
Pages Wiki is arranged by machine-friendly semantic structure.
|
||||
|
||||
The detailed responsibilities, invariants, schema, projections, API surface,
|
||||
and implementation order for Quartier, Street, Spot, and MagicPage are defined
|
||||
in [Knowledge City Model Detailed Design](knowledge-city-model.md).
|
||||
|
||||
Collaboration, notification, delegated sharing, extension providers, external
|
||||
storage, malware inspection, controller DR, and multi-node HA must preserve
|
||||
these identities through the contracts in
|
||||
[Platform Extension Architecture](platform-extension-architecture.md). These
|
||||
features extend Page/Revision/City projections; they do not introduce alternate
|
||||
Page identity, mutable Revision payloads, or filesystem-style ownership.
|
||||
|
||||
- ‘ZoneTree’ is arranged tree-structured model for control ‘quartier’ and ‘street’, and so ‘spot’ as external pointer. ZoneTree referenced from domain.
|
||||
- ‘SpotGraph’ is page pointer graph from spot.
|
||||
|
||||
- SpotGraph point page ID. Multiple spot can any page with page ID(called ‘MagicPage’).
|
||||
- Revision
|
||||
|
||||
- A Page UUID owns an ordered Revision history.
|
||||
- Each immutable Revision has a Revision UUID and references an immutable
|
||||
Document by SHA-256.
|
||||
- Revision identity and Document content identity are distinct.
|
||||
- Revisions carry a BCP 47 language tag; `und` represents legacy or
|
||||
language-unspecified content.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
|
||||
Dm[Domain]
|
||||
ZT[Zone Tree]
|
||||
SG[Spot Graph]
|
||||
PG[Pages]
|
||||
RV[Revisions]
|
||||
|
||||
Dm--Domain refer to ZoneTree-->ZT
|
||||
ZT--ZoneTree refer to spot with SpotGraph-->SG
|
||||
SG--SpotGraph refer to page-->PG
|
||||
PG--page refer to revisions-->RV
|
||||
```
|
||||
|
||||
### MagicPage
|
||||
|
||||
The MagicPage can reach from multiple spot without depending quartier and street. So, A single Page may appear in multiple Spots.
|
||||
|
||||
This creates: rooted multitree
|
||||
|
||||
instead of strict filesystem hierarchy.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
|
||||
SPA[Spot A]
|
||||
SPB[Spot B]
|
||||
SPC[Spot C]
|
||||
|
||||
P1[Page UUID=P1]
|
||||
P2[Page UUID=P2]
|
||||
|
||||
SPA --> P1
|
||||
SPB --> P1
|
||||
SPC --> P2
|
||||
```
|
||||
|
||||
## Language Projection Model
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
|
||||
REQ[Request]
|
||||
AL[Accept-Language]
|
||||
P[Page UUID]
|
||||
|
||||
JAJP[Revision ja-JP]
|
||||
JA[Revision ja]
|
||||
EN[Revision en]
|
||||
|
||||
REQ --> AL
|
||||
AL --> P
|
||||
|
||||
P --> JAJP
|
||||
JAJP -->|not found| JA
|
||||
JA -->|not found| EN
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```http
|
||||
GET /dev/api/auth
|
||||
Accept-Language: ja-JP,ja;q=0.9,en;q=0.8
|
||||
```
|
||||
|
||||
# Canonical Identity Model
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
DOMAIN[Domain UUID]
|
||||
PATH[Semantic Path]
|
||||
UUID[Page UUID]
|
||||
REV[Revision]
|
||||
|
||||
DOMAIN --> PATH
|
||||
PATH --> UUID
|
||||
UUID --> REV
|
||||
```
|
||||
|
||||
### Important Principle
|
||||
|
||||
```text
|
||||
path != object
|
||||
representation != object
|
||||
(domain_uuid, path) = semantic address
|
||||
object UUID = instance-global identity
|
||||
```
|
||||
|
||||
A Domain owns a semantic path namespace, not the Page Object itself. The same
|
||||
normalized path may exist in multiple Domains without conflict, and multiple
|
||||
Domains may bind different paths to the same Page UUID. Cross-Domain links use
|
||||
an absolute URL containing the destination FQDN. See
|
||||
`domain-namespace-federation.md` for local/remote placement and Campus
|
||||
authority modes.
|
||||
|
||||
## Authentication / Authorization Flow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
OIDC[OIDC Provider]
|
||||
PR[Principal]
|
||||
MB[Membership]
|
||||
RL[Role]
|
||||
CAP[Capability Graph]
|
||||
|
||||
OIDC --> PR
|
||||
PR --> MB
|
||||
MB --> RL
|
||||
RL --> CAP
|
||||
```
|
||||
|
||||
### Important Separation
|
||||
|
||||
| Layer | Responsibility |
|
||||
| --- | --- |
|
||||
| OIDC | Identity proof |
|
||||
| Principal | Canonical internal identity |
|
||||
| Membership | Organizational mapping |
|
||||
| Role | Semantic grouping |
|
||||
| Capability | Actual authority |
|
||||
|
||||
## Capability Model
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
PR[Principal]
|
||||
CAP[Capabilities]
|
||||
|
||||
SP[Spot]
|
||||
PAGE[Page]
|
||||
|
||||
PR --> CAP
|
||||
CAP --> SP
|
||||
SP --> PAGE
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```text
|
||||
Alice
|
||||
└─ auth-api:read
|
||||
```
|
||||
|
||||
Spot:
|
||||
|
||||
```text
|
||||
Auth API
|
||||
└─ requires auth-api:read
|
||||
```
|
||||
|
||||
## Capability Evaluation
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
REQ[Read Request]
|
||||
PR[Principal]
|
||||
SP[Spot]
|
||||
CAP[Capability Check]
|
||||
ALLOW[Allow]
|
||||
DENY[Implicit Deny]
|
||||
|
||||
REQ --> PR
|
||||
REQ --> SP
|
||||
|
||||
PR --> CAP
|
||||
SP --> CAP
|
||||
|
||||
CAP -->|has capability| ALLOW
|
||||
CAP -->|missing capability| DENY
|
||||
```
|
||||
|
||||
### Important Principle
|
||||
|
||||
```text
|
||||
default deny
|
||||
positive grants only
|
||||
```
|
||||
|
||||
## Macaroon Delegation
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
PR[Principal]
|
||||
CAP[Capability]
|
||||
|
||||
MAC[Macaroon]
|
||||
CAV[Caveats]
|
||||
|
||||
USR[Temporary User]
|
||||
|
||||
PR --> CAP
|
||||
CAP --> MAC
|
||||
MAC --> CAV
|
||||
MAC --> USR
|
||||
```
|
||||
|
||||
### Caveat Examples
|
||||
|
||||
- expires
|
||||
- readonly
|
||||
- network restriction
|
||||
- lang restriction
|
||||
- path restriction
|
||||
|
||||
## Share Link Model
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
SHARE["/s/abcdef"]
|
||||
|
||||
MAC[Anonymous Macaroon]
|
||||
|
||||
SP[Spot]
|
||||
VIEW[Read-only Projection]
|
||||
|
||||
SHARE --> MAC
|
||||
MAC --> SP
|
||||
SP --> VIEW
|
||||
```
|
||||
|
||||
## Storage Model
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
PAGE[Page UUID]
|
||||
REV1[Revision 1]
|
||||
REV2[Revision 2]
|
||||
REV3[Revision 3]
|
||||
|
||||
PAGE --> REV1
|
||||
PAGE --> REV2
|
||||
PAGE --> REV3
|
||||
```
|
||||
|
||||
Metadata is stored in the database. Immutable Document payloads use a global
|
||||
content-addressed filesystem:
|
||||
|
||||
```text
|
||||
documents/
|
||||
└─ sha256/
|
||||
└─ ab/
|
||||
└─ abcdef...
|
||||
```
|
||||
|
||||
The payload extension is not used as identity. MIME type and canonical format
|
||||
are metadata. A Revision row references the hash and never references a
|
||||
mutable asset HEAD.
|
||||
|
||||
## Runtime Rendering Pipeline
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
REQ[HTTP Request]
|
||||
|
||||
PATH[Semantic Path]
|
||||
UUID[Page UUID]
|
||||
LANG[Language Resolution]
|
||||
REV[Revision]
|
||||
AUTH[Capability Evaluation]
|
||||
RENDER[Render]
|
||||
|
||||
REQ --> PATH
|
||||
PATH --> UUID
|
||||
UUID --> LANG
|
||||
LANG --> REV
|
||||
REV --> AUTH
|
||||
AUTH --> RENDER
|
||||
```
|
||||
|
||||
## Overall Architectural Direction
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
|
||||
UI[Hierarchy UI]
|
||||
TREE[Rooted Tree]
|
||||
GRAPH[Semantic Graph]
|
||||
UUID[UUID Identity]
|
||||
LANG[Language Projection]
|
||||
CAP[Capability Access]
|
||||
MAC[Macaroon Delegation]
|
||||
|
||||
UI --> TREE
|
||||
TREE --> GRAPH
|
||||
GRAPH --> UUID
|
||||
UUID --> LANG
|
||||
LANG --> CAP
|
||||
CAP --> MAC
|
||||
```
|
||||
|
||||
## Final Summary
|
||||
|
||||
### Pages Wiki is:
|
||||
|
||||
- hierarchy-oriented for humans
|
||||
- graph-capable internally
|
||||
- semantic-locality-driven
|
||||
- UUID identity based
|
||||
- language-neutral
|
||||
- capability-centric
|
||||
- projection-oriented
|
||||
|
||||
### NOT:
|
||||
|
||||
- filesystem ACL centric
|
||||
- path identity centric
|
||||
- language hierarchy centric
|
||||
@@ -0,0 +1,34 @@
|
||||
# Archive Import and Knowledge City Planning
|
||||
|
||||
Archive import is a staged, auditable operation. Uploading an archive never
|
||||
writes Pages directly.
|
||||
|
||||
## Pipeline
|
||||
|
||||
1. Store the uploaded ZIP or tar-family archive in private import storage.
|
||||
2. Queue `import.analyze`; foreground requests always take scheduler priority.
|
||||
3. Validate entry names, link types, file count and expanded byte limits.
|
||||
4. Produce an immutable dry-run manifest containing source path, destination
|
||||
Path, detected content type and initial Quartier/Street/Spot suggestions.
|
||||
5. Allow a curator to edit, merge, exclude and approve suggestions.
|
||||
6. Queue import execution in bounded batches. Markdown is transpiled to the
|
||||
canonical HTML Document while its source representation remains available.
|
||||
7. Record created UUIDs and topology operations in an import journal so a
|
||||
session can be reviewed, retried or rolled back.
|
||||
|
||||
## Safety limits
|
||||
|
||||
- archive upload: 512 MiB;
|
||||
- expanded content: 2 GiB;
|
||||
- entries: 10,000;
|
||||
- absolute paths, `..`, NUL, hard links and symbolic links are rejected;
|
||||
- supported staging formats: ZIP, tar, tar.gz/tgz and tar.xz/txz.
|
||||
|
||||
## Initial suggestion rules
|
||||
|
||||
The first directory component proposes a Quartier, the second proposes a
|
||||
Street, and the nearest containing directory proposes a Spot. Markdown receives
|
||||
higher initial confidence than opaque assets. Later scoring incorporates
|
||||
front matter, headings, README/index portals, internal links, vocabulary and
|
||||
existing City boundaries. Suggestions never mutate City topology until a
|
||||
curator confirms the plan.
|
||||
@@ -0,0 +1,247 @@
|
||||
# Asset Model
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
An Asset is a mutable authoring identity whose HEAD points to one immutable
|
||||
Document. It represents continuity of editing for binary or application-native
|
||||
material such as an image, DrawIO scene, Excalidraw scene, spreadsheet, slide
|
||||
deck, audio file, or video file.
|
||||
|
||||
An Asset is not:
|
||||
|
||||
- a Semantic Path or a Viewer URL;
|
||||
- a Page Revision;
|
||||
- immutable historical truth;
|
||||
- an authorization capability;
|
||||
- a remote-instance address.
|
||||
|
||||
The identity layers remain distinct:
|
||||
|
||||
| Identity | Meaning | Mutable |
|
||||
| --- | --- | --- |
|
||||
| `asset:<type>:<name>` | Editable Asset identity and current HEAD | yes |
|
||||
| `sha256:<hash>` | Exact immutable Document bytes | no |
|
||||
| `rev:<uuid>` | Immutable Page Revision that may refer to Documents | no |
|
||||
| `path:/...` | Domain-scoped semantic reachability | yes |
|
||||
|
||||
## 2. Address and scope
|
||||
|
||||
The canonical local address is:
|
||||
|
||||
```text
|
||||
asset:<type>:<name>
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
asset:image:knowledge-city-logo
|
||||
asset:drawio:network-core
|
||||
asset:xlsx:q1-budget
|
||||
```
|
||||
|
||||
`type` is a projection/editor hint, not trusted MIME metadata. `name` is the
|
||||
stable authoring name. The complete address is Domain-local, case-sensitive,
|
||||
and unique by `(domain_uuid, address)` in the `assets` table.
|
||||
|
||||
Asset authoring identity is Domain-scoped so separate Domains may independently
|
||||
own `asset:image:logo`. Immutable Documents remain content-addressed and may be
|
||||
deduplicated across Domains. A local `asset:` address must never be resolved on
|
||||
another instance. A remote resource requires an absolute HTTPS URL and an
|
||||
explicit federation or external-object contract.
|
||||
|
||||
## 3. Stored state
|
||||
|
||||
The current additive schema is:
|
||||
|
||||
| Column | Meaning |
|
||||
| --- | --- |
|
||||
| `domain_uuid` | Owning Domain; part of the composite primary key |
|
||||
| `address` | Canonical `asset:` identity; part of the composite primary key |
|
||||
| `object_uuid` | Stable Object UUID with kind `asset` |
|
||||
| `head_document_hash` | Current immutable Document SHA-256; empty means no HEAD |
|
||||
| `created_at_ms` | Asset creation time |
|
||||
| `content_type` | Mutable MIME metadata for the current HEAD |
|
||||
| `filename` | Mutable filename metadata for the current HEAD |
|
||||
| `size_bytes` | Current HEAD byte length |
|
||||
| `updated_at_ms` | Last HEAD update time |
|
||||
|
||||
The bytes are stored in the Document Store under their SHA-256. The Asset row
|
||||
contains no duplicate body. Filename, MIME type, and size describe the mutable
|
||||
HEAD but do not participate in Document identity. Immutable delivery uses
|
||||
bounded content detection when historical metadata is unavailable.
|
||||
|
||||
## 4. State transitions
|
||||
|
||||
### Create or update HEAD
|
||||
|
||||
```text
|
||||
input bytes
|
||||
-> calculate SHA-256
|
||||
-> atomically persist immutable Document
|
||||
-> compare with Asset HEAD
|
||||
-> create Asset or move HEAD
|
||||
```
|
||||
|
||||
Writing identical bytes with unchanged MIME and filename is a no-op. Correcting
|
||||
MIME or filename records a metadata/history update without changing the hash.
|
||||
Moving HEAD never mutates or overwrites the
|
||||
old Document. The local CLI currently implements this operation through
|
||||
`put LOCAL asset:<type>:<name>` and `edit asset:<type>:<name>`.
|
||||
|
||||
Asset HEAD updates do not create Page Revisions. An old Document remains live
|
||||
when a Page Revision has frozen a reference to it; otherwise it may become
|
||||
garbage after it is no longer an Asset HEAD. Garbage collection must treat
|
||||
current Asset HEADs and `revision_document_refs` as roots.
|
||||
|
||||
### Read
|
||||
|
||||
`view`, `cat`, and `get` resolve the Asset HEAD at operation time. These are
|
||||
mutable reads and must not be used for reproducible rendering or historical
|
||||
export. Reproducible consumers use the resolved `sha256:` identity.
|
||||
|
||||
### Delete
|
||||
|
||||
Administrator HTTP deletion removes the mutable Asset identity only; it does
|
||||
not delete a Document still
|
||||
referenced by a Revision, another Asset HEAD, export, or retention root.
|
||||
Automatic retention and physical Document collection policy remain pending.
|
||||
|
||||
## 5. Revision save and freezing
|
||||
|
||||
A saved Page Revision must never use a live `asset:` dependency as its rendered
|
||||
payload. It does retain the authoring address as provenance so a later edit can
|
||||
resolve the then-current HEAD. For HTML payloads, the server resolves `asset:`
|
||||
values at save time:
|
||||
|
||||
| Authoring input | Stored Revision |
|
||||
| --- | --- |
|
||||
| `asset-ref="asset:…"` | Retain `asset-ref`; add/update `immutable-ref="sha256:<hash>"` |
|
||||
| `immutable-ref="asset:…"` | Normalize to retained `asset-ref` plus fixed `immutable-ref` |
|
||||
| `src="asset:…"` | Fixed `src="/_/obj/sha256:<hash>"` plus `data-pageswiki-asset-src="asset:…"` |
|
||||
| `href="asset:…"` | Fixed `href` plus `data-pageswiki-asset-href` provenance |
|
||||
| `poster="asset:…"` | Fixed `poster` plus `data-pageswiki-asset-poster` provenance |
|
||||
| `data="asset:…"` | Fixed `data` plus `data-pageswiki-asset-data` provenance |
|
||||
|
||||
Only HTML attribute values are transformed. Explanatory prose, code blocks,
|
||||
and non-HTML payloads are not rewritten. A missing Asset or an Asset without a
|
||||
valid HEAD rejects the save with `ErrEmbeddedAssetUnavailable`; silently
|
||||
leaving a mutable dependency is forbidden.
|
||||
|
||||
On a later save, the provenance address is resolved again and the fixed hash is
|
||||
updated to the current Asset HEAD. Merely viewing an old Revision never resolves
|
||||
the mutable address and therefore remains reproducible.
|
||||
|
||||
### Authoring forms
|
||||
|
||||
Markdown may use ordinary resource and link syntax because compilation produces
|
||||
the supported HTML attributes:
|
||||
|
||||
```markdown
|
||||

|
||||
[Download the workbook](asset:xlsx:q1-budget)
|
||||
```
|
||||
|
||||
Equivalent HTML examples are:
|
||||
|
||||
```html
|
||||
<img src="asset:image:knowledge-city-logo" alt="Knowledge City logo">
|
||||
<a href="asset:xlsx:q1-budget">Download the workbook</a>
|
||||
<video poster="asset:image:intro-poster">
|
||||
<source src="asset:video:intro">
|
||||
</video>
|
||||
<embedded-object
|
||||
kind="drawio"
|
||||
asset-ref="asset:drawio:network-core">
|
||||
</embedded-object>
|
||||
```
|
||||
|
||||
`asset:` is accepted only in `asset-ref`, legacy `immutable-ref`, `src`, `href`,
|
||||
`poster`, and `data`. CSS `url()`, `srcset`, inline scripts, arbitrary
|
||||
`data-*` attributes, and plain text are not resolvers. They require a future
|
||||
typed parser rather than unsafe textual replacement.
|
||||
|
||||
### Access surfaces
|
||||
|
||||
| Surface | Address | Semantics |
|
||||
| --- | --- | --- |
|
||||
| CLI authoring | `asset:<type>:<name>` | Mutable HEAD read/write in selected Domain |
|
||||
| Administrator HEAD URL | `/v/raw/asset:<type>:<name>` | Resolves current HEAD on every request; private and non-canonical |
|
||||
| HTML/Markdown authoring | `asset:<type>:<name>` | Resolved only while saving a Revision |
|
||||
| Stored semantic reference | `asset-ref="asset:…"` | Provenance for later editing; never rendered directly |
|
||||
| Stored immutable reference | `sha256:<hash>` | Exact dependency identity |
|
||||
| Browser delivery | `/_/obj/sha256:<hash>` | Authorized immutable GET/HEAD/Range |
|
||||
| Management API | `/_/api/v1/assets?address=asset:…` | Domain-admin metadata and mutation surface |
|
||||
|
||||
The mutable Asset URL is an authenticated administrator authoring projection;
|
||||
it is never emitted into published Pages or historical Revisions. It uses a
|
||||
private revalidation cache policy and reports both the Asset address and
|
||||
resolved HEAD hash in response headers. Published Pages always load the frozen
|
||||
Document URL.
|
||||
|
||||
Every frozen dependency is recorded as:
|
||||
|
||||
```text
|
||||
revision_document_refs(revision_uuid, document_hash)
|
||||
```
|
||||
|
||||
This relation is part of Revision truth. It enables dependency inspection,
|
||||
authorization, export, and garbage-collection reachability without reparsing
|
||||
historical HTML.
|
||||
|
||||
## 6. Delivery and authorization
|
||||
|
||||
Immutable bytes are delivered through:
|
||||
|
||||
```text
|
||||
/_/obj/sha256:<hash>
|
||||
```
|
||||
|
||||
Knowing a hash is not authorization. Delivery succeeds only when the Document
|
||||
is either the body of, or a frozen dependency of, a Revision whose Object has a
|
||||
readable Path in the current Domain. The response exposes Object, Revision, and
|
||||
Document identities in the PagesWiki metadata headers and supports ETag, HEAD,
|
||||
and byte ranges.
|
||||
|
||||
The current HEAD of a Domain Asset may also be inspected through the same
|
||||
immutable URL by a Domain or Campus administrator, even before any Revision has
|
||||
frozen it. This administrative exception is for Asset management and does not
|
||||
make the mutable HEAD anonymously readable. Once frozen into a Page Revision,
|
||||
ordinary access follows that Page's read authorization.
|
||||
|
||||
The trusted local CLI bypasses HTTP Capability evaluation and is controlled by
|
||||
database and filesystem permissions. The administrator HTTP API is restricted
|
||||
to Domain or Campus administrators and requires an Asset HEAD ETag for updates
|
||||
and deletion, or `If-None-Match: *` for creation. It records immutable HEAD
|
||||
history with actor identity. Moving this endpoint into the typed policy matrix
|
||||
and general audit outbox remains pending. Last-writer-wins HTTP updates are not
|
||||
accepted.
|
||||
|
||||
## 7. Consistency rules
|
||||
|
||||
1. `head_document_hash` and every frozen dependency must be a lowercase,
|
||||
64-character SHA-256.
|
||||
2. Asset HEAD movement never changes existing Documents or Revisions.
|
||||
3. Revision save resolves all supported embedded Asset references or fails.
|
||||
4. `asset:` is authoring identity; `sha256:` is delivery/storage identity.
|
||||
5. A hash, Asset address, or Object UUID never grants access by itself.
|
||||
6. Cross-instance Asset resolution is forbidden without an explicit origin.
|
||||
7. GC must preserve Documents reachable from Revisions, frozen references,
|
||||
current Asset HEADs, and configured retention roots.
|
||||
|
||||
## 8. Implementation status
|
||||
|
||||
| Capability | Status |
|
||||
| --- | --- |
|
||||
| Local CLI create/update/read/edit | active |
|
||||
| Content-addressed Document persistence | active |
|
||||
| HTML save-time freezing | active |
|
||||
| Revision-to-Document dependency records | active |
|
||||
| Authorized immutable HTTP delivery | active |
|
||||
| Asset owner excluded from Zombie Object GC | active |
|
||||
| Asset MIME/filename/size metadata | active |
|
||||
| Administrator HTTP CRUD and ETag/CAS updates | active |
|
||||
| Initial Domain Asset management UI | active |
|
||||
| History/restore and dependency detail UI | active |
|
||||
| Delete/retention UI and audit trail | designed, not implemented |
|
||||
| Remote/federated Asset synchronization | not designed as implicit lookup |
|
||||
@@ -0,0 +1,152 @@
|
||||
# Authentication and Authorization Backend
|
||||
|
||||
## Boundary
|
||||
|
||||
Authentication proves an identity. Every authenticator produces the same
|
||||
internal `principal_uuid`; authenticators never grant document access directly.
|
||||
Authorization is Domain-scoped and evaluates positive grants only:
|
||||
|
||||
```text
|
||||
request -> session -> principal -> Domain membership -> role -> capability
|
||||
```
|
||||
|
||||
Campus owns trusted identity-provider configuration. A Domain owns membership,
|
||||
roles, grants, session policy, and the default authorization mode. Managed
|
||||
Campus provider metadata is inherited from its controller; secrets remain on
|
||||
the instance that performs authentication and are never federated.
|
||||
|
||||
## Authentication methods
|
||||
|
||||
| Method | Stable external key | Secret location |
|
||||
| --- | --- | --- |
|
||||
| password | normalized username | Argon2id verifier in credential table |
|
||||
| OIDC | exact `(issuer, subject)` | encrypted client secret/config |
|
||||
| LDAP | `(provider UUID, immutable directory attribute)` | encrypted bind secret |
|
||||
| TOTP | principal + factor UUID | encrypted seed; recovery codes hashed |
|
||||
| magic link | normalized verified email | one-use hashed challenge |
|
||||
| device approval | requesting-device challenge UUID | one-use hashed challenge |
|
||||
|
||||
OIDC groups and LDAP groups are attributes. Explicit mapping rules may create
|
||||
or remove Membership/Role bindings, but group names are not capabilities.
|
||||
The route policy, internal group schema, `/g/` namespace, and endpoint matrix
|
||||
are specified in [Endpoint Authorization and Groups](authorization-groups.md).
|
||||
|
||||
## Core records
|
||||
|
||||
- `principals`: canonical person/service identity and lifecycle state.
|
||||
- `principal_identities`: unique provider subjects attached to a Principal.
|
||||
- `auth_credentials`: password/TOTP/recovery material and version metadata.
|
||||
- `domain_memberships`: Principal membership in one Domain.
|
||||
- `auth_roles`, `auth_role_bindings`: Domain roles and membership assignment.
|
||||
- `groups`, `group_members`, `auth_group_role_bindings`: Domain-scoped
|
||||
Principal collections and their Role assignment.
|
||||
- `auth_capability_grants`: positive operation grants with typed targets.
|
||||
- `auth_sessions`: opaque, hashed, rotating browser sessions.
|
||||
- `auth_challenges`: short-lived one-use login/MFA/device challenges.
|
||||
- `auth_audit_log`: append-only authentication and policy decisions.
|
||||
|
||||
Capabilities use verbs `read`, `create`, `upload`, `write`, `rename`, `delete`,
|
||||
`link`, `manage`, and `delegate`. Targets are `domain`, `quartier`, `street`, `spot`, `path`, or
|
||||
`object`. Locality inheritance is resolved by the address model; an exceptional
|
||||
Page/Object grant does not rewrite the path hierarchy.
|
||||
|
||||
## Evaluation
|
||||
|
||||
1. Resolve Domain before reading the session.
|
||||
2. Hash the opaque cookie and load an unexpired, unrevoked session for that
|
||||
Domain. Reject suspended/quarantined Principals.
|
||||
3. Resolve Membership and its Role bindings.
|
||||
4. Match the requested verb and target against positive grants. `manage`
|
||||
includes administrative operations but does not imply `delegate`.
|
||||
5. Record denied sensitive operations and every policy/configuration mutation.
|
||||
|
||||
No matching grant means deny. During migration, `authorization_mode=legacy`
|
||||
leaves existing anonymous behavior intact. Administrators bootstrap an owner,
|
||||
verify access, then switch a Domain to `enforcing`. New Domains should default
|
||||
to `enforcing` once the bootstrap flow is complete.
|
||||
|
||||
## HTTP flows
|
||||
|
||||
- `/_/auth/login`, `/_/auth/logout`, `/_/auth/callback/oidc/{provider}`
|
||||
- `/u/{username}` is the Domain-scoped profile and user-Wiki root.
|
||||
`/u/{username}/_/edit` is its owner-only profile editor and
|
||||
`/_/auth/profile` redirects there. Other descendants are ordinary semantic
|
||||
Wiki paths. Usernames exclude dots so the public handle can be derived as
|
||||
`{username}.{domain FQDN}` without ambiguity.
|
||||
- `/_/auth/challenge/password`, `/totp`, `/magic-link`, `/device`
|
||||
- `/_/api/v1/auth/session`, `/principals`, `/roles`, `/grants`, `/audit`
|
||||
|
||||
Cookies are `Secure`, `HttpOnly`, `SameSite=Lax`, host-only, and contain only a
|
||||
random secret whose SHA-256 hash is stored. Login rotates the session; password
|
||||
or factor changes revoke all Principal sessions. State/nonce/PKCE are mandatory
|
||||
for OIDC. Magic links and device approvals store only a token hash, are
|
||||
single-use, expire quickly, and are bound to Domain and intended action.
|
||||
|
||||
TOTP seeds are encrypted with AES-GCM using a 256-bit instance key stored as
|
||||
`auth.key` beside the Document Store (`0600`), or derived from
|
||||
`PAGESWIKI_AUTH_KEY`. Enrollment remains disabled until a valid six-digit code
|
||||
is confirmed. Login challenges expire after five minutes, allow five attempts,
|
||||
and reject reuse of an accepted 30-second counter.
|
||||
|
||||
OIDC providers are configured per Domain from the authentication panel. The
|
||||
flow uses discovery, Authorization Code, PKCE S256, state, and nonce, then
|
||||
resolves the subject through UserInfo. A first login may bind `(issuer, sub)`
|
||||
only to an existing Principal with the same verified email; it never creates a
|
||||
role or capability from provider claims. Client secrets are encrypted with the
|
||||
instance authentication key.
|
||||
|
||||
LDAP providers are also Domain-scoped. The implemented login sequence follows
|
||||
the same separation used by Wiki.js' LDAP authenticator:
|
||||
|
||||
1. connect to an `ldap://` or `ldaps://` endpoint with an 8-second socket
|
||||
deadline; optionally upgrade an `ldap://` connection with StartTLS;
|
||||
2. bind the configured search service account, or use an anonymous search when
|
||||
both bind fields are empty;
|
||||
3. insert the RFC 4515-escaped login into a configured filter containing
|
||||
`{{username}}`, search below the configured Base DN, and require exactly one
|
||||
result (server size limit 2, time limit 6 seconds);
|
||||
4. read an explicitly configured immutable ID, local username, email, and
|
||||
display-name attribute;
|
||||
5. bind as the returned user DN with the submitted password. A search result by
|
||||
itself is never accepted as proof of authentication;
|
||||
6. resolve the first login by an exact unique local username or email, then
|
||||
persist `(provider UUID, immutable ID)`. Following logins use only that
|
||||
immutable binding. Optional automatic provisioning creates an ordinary
|
||||
`member` with no local password credential.
|
||||
|
||||
The immutable attribute should be `entryUUID` for common LDAP servers or the
|
||||
binary `objectGUID` for Active Directory. DN, email, display name, and account
|
||||
name are mutable attributes and therefore are not stable subjects. Bind
|
||||
passwords use the instance authentication-key encryption; leaving the password
|
||||
blank in the settings form preserves the existing encrypted value. TLS
|
||||
certificate validation is on by default, a private CA can be appended as PEM,
|
||||
and disabling validation is an explicit per-Domain administrator action.
|
||||
|
||||
The settings panel exposes a saved-configuration login test. User passwords are
|
||||
used only for the user-DN bind and are neither persisted nor logged. Connection
|
||||
admission is bounded to four process-wide LDAP operations. The browser receives
|
||||
the same generic invalid-credentials response for lookup and password failures;
|
||||
the server log retains the provider-side error without the submitted username
|
||||
or password.
|
||||
|
||||
SMTP magic links target existing active/read-only Principals by normalized
|
||||
email. The public request response never reveals whether an address exists.
|
||||
Links contain a random token whose hash alone is stored, expire after fifteen
|
||||
minutes, and are consumed atomically once. SMTP credentials use the same
|
||||
encrypted provider-secret storage. Delivery is admitted through a bounded
|
||||
background slot so an SMTP server cannot hold the login request open.
|
||||
|
||||
LDAP and SMTP run through bounded worker queues with timeouts; request handlers
|
||||
do not wait indefinitely on an external directory or mail server. A durable
|
||||
authentication-attempt quota keyed by Domain, normalized account identifier,
|
||||
source prefix, and challenge kind remains required before an Internet-facing
|
||||
multi-tenant deployment; bounded provider admission is not a rate limiter.
|
||||
|
||||
## Delivery order
|
||||
|
||||
1. Common schema, Principal normalization, sessions, RBAC evaluation, audit.
|
||||
2. Bootstrap owner plus password/Argon2id and optional TOTP.
|
||||
3. OIDC Authorization Code + PKCE.
|
||||
4. SMTP magic link and device approval challenges.
|
||||
5. LDAP bind/search with immutable identity mapping.
|
||||
6. Delegated macaroon capabilities after canonical RBAC is enforced.
|
||||
@@ -0,0 +1,642 @@
|
||||
# Pages Wiki vNext Authentication / Authorization Draft
|
||||
|
||||
## Goal
|
||||
|
||||
Separate:
|
||||
|
||||
```text
|
||||
Authentication
|
||||
Identity
|
||||
Capability
|
||||
Delegation
|
||||
Projection
|
||||
```
|
||||
|
||||
into independent layers.
|
||||
|
||||
Avoid tightly coupling:
|
||||
|
||||
```text
|
||||
OIDC groups
|
||||
filesystem ACLs
|
||||
path hierarchy
|
||||
```
|
||||
|
||||
to the knowledge topology.
|
||||
|
||||
* * *
|
||||
|
||||
# Core Philosophy
|
||||
|
||||
## Authentication != Authorization
|
||||
|
||||
Authentication answers:
|
||||
|
||||
```text
|
||||
Who are you?
|
||||
```
|
||||
|
||||
Authorization answers:
|
||||
|
||||
```text
|
||||
What may you do?
|
||||
```
|
||||
|
||||
These are intentionally separated.
|
||||
|
||||
* * *
|
||||
|
||||
# High-Level Architecture
|
||||
|
||||
```text
|
||||
OIDC
|
||||
↓
|
||||
Principal
|
||||
↓
|
||||
Membership / Roles
|
||||
↓
|
||||
Capability Graph
|
||||
↓
|
||||
Macaroon Delegation
|
||||
↓
|
||||
Runtime Policy Evaluation
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Layer 1: Authentication
|
||||
|
||||
## Responsibility
|
||||
|
||||
Identity proof only.
|
||||
|
||||
* * *
|
||||
|
||||
# Recommended Mechanism
|
||||
|
||||
OIDC / OpenID Connect.
|
||||
|
||||
Examples:
|
||||
|
||||
- Keycloak
|
||||
- Authentik
|
||||
- Azure AD
|
||||
- Google Workspace
|
||||
- GitHub OIDC
|
||||
|
||||
* * *
|
||||
|
||||
# OIDC Output
|
||||
|
||||
Example claims:
|
||||
|
||||
```json
|
||||
{
|
||||
"iss": "...",
|
||||
"sub": "...",
|
||||
"email": "...",
|
||||
"groups": [...]
|
||||
}
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
OIDC groups are NOT canonical authorization objects.
|
||||
|
||||
They are only:
|
||||
|
||||
```text
|
||||
external identity attributes
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Layer 2: Principal
|
||||
|
||||
## Responsibility
|
||||
|
||||
Canonical internal identity normalization.
|
||||
|
||||
* * *
|
||||
|
||||
# Principal Model
|
||||
|
||||
```text
|
||||
principal_id
|
||||
issuer
|
||||
subject
|
||||
display_name
|
||||
email
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
The canonical identity inside Pages is:
|
||||
|
||||
```text
|
||||
principal_id
|
||||
```
|
||||
|
||||
NOT:
|
||||
|
||||
```text
|
||||
OIDC group
|
||||
email address
|
||||
username
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Layer 3: Capability Model
|
||||
|
||||
## Responsibility
|
||||
|
||||
Represent authority within the knowledge topology.
|
||||
|
||||
* * *
|
||||
|
||||
# Capability Philosophy
|
||||
|
||||
Capabilities are attached primarily to:
|
||||
|
||||
```text
|
||||
Zone
|
||||
Spot
|
||||
```
|
||||
|
||||
rather than individual Pages.
|
||||
|
||||
* * *
|
||||
|
||||
# Why
|
||||
|
||||
Knowledge naturally clusters around semantic localities.
|
||||
|
||||
ACLs scale better when attached to locality.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
Spot(Auth API)
|
||||
allow:
|
||||
engineering-reader
|
||||
api-editor
|
||||
```
|
||||
|
||||
Pages inherit effective visibility from their locality.
|
||||
|
||||
* * *
|
||||
|
||||
# Capability Model
|
||||
|
||||
```text
|
||||
principal
|
||||
↓
|
||||
membership
|
||||
↓
|
||||
role
|
||||
↓
|
||||
capability
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
engineering-team
|
||||
↓
|
||||
api-editor
|
||||
↓
|
||||
write Spot(Auth API)
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Roles are internal semantic policy objects.
|
||||
|
||||
They are NOT identical to OIDC groups.
|
||||
|
||||
* * *
|
||||
|
||||
# OIDC Mapping
|
||||
|
||||
```text
|
||||
OIDC group
|
||||
↓
|
||||
Pages membership
|
||||
↓
|
||||
Pages role
|
||||
↓
|
||||
Capability
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Capability Target Types
|
||||
|
||||
Capabilities may target:
|
||||
|
||||
| Object Type | Meaning |
|
||||
| --- | --- |
|
||||
| Zone | Containment locality |
|
||||
| Spot | Semantic locality |
|
||||
| Page | Exceptional override only |
|
||||
| Binding | Projection-level visibility |
|
||||
|
||||
* * *
|
||||
|
||||
# Default Authorization Strategy
|
||||
|
||||
## Default Deny
|
||||
|
||||
No capability means:
|
||||
|
||||
```text
|
||||
access denied
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Positive Grant Only
|
||||
|
||||
Avoid large explicit deny graphs.
|
||||
|
||||
Prefer:
|
||||
|
||||
```text
|
||||
grant omission
|
||||
```
|
||||
|
||||
instead of:
|
||||
|
||||
```text
|
||||
explicit deny
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Why
|
||||
|
||||
Explicit deny causes:
|
||||
|
||||
- precedence complexity
|
||||
- inheritance conflicts
|
||||
- ACL explosion
|
||||
- runtime ambiguity
|
||||
|
||||
* * *
|
||||
|
||||
# Recommended Model
|
||||
|
||||
```text
|
||||
allow-only locality policies
|
||||
```
|
||||
|
||||
plus:
|
||||
|
||||
```text
|
||||
principal-side overlays
|
||||
```
|
||||
|
||||
for exceptional cases.
|
||||
|
||||
* * *
|
||||
|
||||
# Exceptional Restriction Handling
|
||||
|
||||
Instead of:
|
||||
|
||||
```text
|
||||
deny alice
|
||||
```
|
||||
|
||||
prefer:
|
||||
|
||||
```text
|
||||
alice.status = suspended
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```text
|
||||
alice lacks capability
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Principal States
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
active
|
||||
readonly
|
||||
suspended
|
||||
quarantined
|
||||
audit-only
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Layer 4: Macaroon
|
||||
|
||||
## Responsibility
|
||||
|
||||
Portable delegated constrained capability.
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Macaroon is NOT the canonical ACL database.
|
||||
|
||||
Macaroon is:
|
||||
|
||||
```text
|
||||
authority artifact
|
||||
delegated capability token
|
||||
portable constrained access proof
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Macaroon Role
|
||||
|
||||
Macaroons transport delegated authority.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
Canonical server-side capability:
|
||||
|
||||
```text
|
||||
Alice
|
||||
└─ read Spot(Auth API)
|
||||
```
|
||||
|
||||
Delegated macaroon:
|
||||
|
||||
```text
|
||||
read-only
|
||||
spot=auth-api
|
||||
expires<2026-02-01
|
||||
office-network-only
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Caveats
|
||||
|
||||
Macaroon caveats attenuate authority.
|
||||
|
||||
Examples:
|
||||
|
||||
Caveat Meaning expires time restriction network source network restriction readonly capability narrowing path locality restriction lang projection restriction method operation restriction
|
||||
|
||||
* * *
|
||||
|
||||
# Important Property
|
||||
|
||||
Macaroons can only:
|
||||
|
||||
```text
|
||||
reduce authority
|
||||
```
|
||||
|
||||
never expand it.
|
||||
|
||||
* * *
|
||||
|
||||
# Runtime Validation
|
||||
|
||||
```text
|
||||
1. Verify macaroon signature
|
||||
2. Verify caveats
|
||||
3. Verify delegated capability validity
|
||||
4. Apply runtime policy
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Share Links
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
/s/abcdef
|
||||
```
|
||||
|
||||
may internally represent:
|
||||
|
||||
```text
|
||||
anonymous delegated macaroon capability
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Important Property
|
||||
|
||||
Share links may work without OIDC login.
|
||||
|
||||
This enables:
|
||||
|
||||
```text
|
||||
identity-less delegated access
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Capability vs ACL
|
||||
|
||||
## Traditional ACL
|
||||
|
||||
```text
|
||||
Object
|
||||
└─ Subjects
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Capability-Oriented Model
|
||||
|
||||
```text
|
||||
Principal
|
||||
└─ Possessed Authorities
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Real-World Analogy
|
||||
|
||||
Pages authorization behaves more like:
|
||||
|
||||
```text
|
||||
building access control
|
||||
```
|
||||
|
||||
than filesystem ACLs.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
```text
|
||||
Zone = building
|
||||
Spot = room
|
||||
Capability = key
|
||||
Macaroon = temporary visitor pass
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Locality Unlock Model
|
||||
|
||||
## Spot
|
||||
|
||||
```text
|
||||
requires capability:
|
||||
auth-api:read
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Principal
|
||||
|
||||
```text
|
||||
possesses:
|
||||
auth-api:read
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Runtime
|
||||
|
||||
```text
|
||||
Does principal possess required capability?
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Capability Delegation
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Alice delegates:
|
||||
read-only access
|
||||
to Spot(Auth API)
|
||||
valid for 24 hours
|
||||
```
|
||||
|
||||
This maps naturally to:
|
||||
|
||||
```text
|
||||
temporary visitor badge
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Runtime Authorization Evaluation
|
||||
|
||||
## Without Macaroon
|
||||
|
||||
```text
|
||||
principal session
|
||||
↓
|
||||
effective capability lookup
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# With Macaroon
|
||||
|
||||
```text
|
||||
verify macaroon
|
||||
↓
|
||||
apply caveats
|
||||
↓
|
||||
treat as delegated capability
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Runtime Evaluation Components
|
||||
|
||||
| Component | Responsibility |
|
||||
| --- | --- |
|
||||
| Principal | Identity |
|
||||
| Capability Graph | Canonical authority |
|
||||
| Macaroon | Delegated authority |
|
||||
| Runtime Policy | Dynamic constraints |
|
||||
| Effective Cache | Acceleration |
|
||||
|
||||
* * *
|
||||
|
||||
# Runtime Constraints
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
time
|
||||
network
|
||||
risk
|
||||
device
|
||||
lang
|
||||
projection
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Effective Capability Cache
|
||||
|
||||
Recommended for scalability.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
principal_effective_capabilities
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
The source of truth is:
|
||||
|
||||
```text
|
||||
server-side capability graph
|
||||
```
|
||||
|
||||
NOT macaroon tokens.
|
||||
|
||||
* * *
|
||||
|
||||
# Architectural Direction
|
||||
|
||||
Layer Model Authentication OIDC Identity Principal Authorization Capability graph Delegation Macaroon Constraints Caveats Runtime Effective policy evaluation
|
||||
|
||||
* * *
|
||||
|
||||
# Conceptual Summary
|
||||
|
||||
Pages Wiki authorization is evolving toward:
|
||||
|
||||
```text
|
||||
semantic locality capability system
|
||||
```
|
||||
|
||||
rather than:
|
||||
|
||||
```text
|
||||
filesystem ACL system
|
||||
```
|
||||
@@ -0,0 +1,410 @@
|
||||
# Endpoint Authorization and Groups
|
||||
|
||||
## Scope
|
||||
|
||||
2026-09-14 extension: [locality access and publication](locality-access-publication.md)
|
||||
adds restrictive named user/group layers over existing grants and a separate
|
||||
explicitly approved anonymous semantic/raw path. For Objects, all local
|
||||
restrictive alias caps apply before the original positive-grant/any-readable-
|
||||
alias rule below. Existing group profiles and administrative roles are unchanged.
|
||||
|
||||
This document completes the backend design between authentication and the
|
||||
existing capability graph. It specifies route-level enforcement, target
|
||||
resolution, groups, and the `/g/` namespace. Authentication providers prove a
|
||||
Principal; neither an OIDC/LDAP group nor an HTTP route grants authority by
|
||||
itself.
|
||||
|
||||
## Request authorization pipeline
|
||||
|
||||
Every registered route has a static `RoutePolicy`. Authorization must not infer
|
||||
authority from arbitrary URL substring matching.
|
||||
|
||||
```go
|
||||
type RoutePolicy struct {
|
||||
Name string
|
||||
Methods map[string]MethodPolicy
|
||||
Authentication AuthenticationPolicy // public, optional, principal, service
|
||||
CSRF bool
|
||||
}
|
||||
|
||||
type MethodPolicy struct {
|
||||
Capability string // read, write, rename, delete, link, manage, delegate
|
||||
Resolve TargetResolver
|
||||
}
|
||||
|
||||
type AuthorizationTarget struct {
|
||||
DomainUUID string
|
||||
Type string // domain, quartier, street, spot, path, object, group
|
||||
ID string // canonical UUID where one exists
|
||||
}
|
||||
```
|
||||
|
||||
The request sequence is fixed:
|
||||
|
||||
1. Normalize the request and attach a request ID.
|
||||
2. Resolve the local Domain from the effective host. Reject remote placement.
|
||||
3. Match a registered route and method. An unregistered method returns `405`.
|
||||
4. Resolve credentials into an optional Principal or a service/delegation
|
||||
context. Domain browser sessions and Bearer tokens use the same stored
|
||||
session record; adapter, federation, and future share tokens are distinct
|
||||
credential types and are never promoted to Principal sessions.
|
||||
5. Guard browser mutations with same-origin Fetch Metadata/Origin before any
|
||||
authorization bypass. Cookie requests missing that evidence require a
|
||||
matching Referer; otherwise deny. Explicit Bearer/service clients may omit
|
||||
browser metadata, but actual cross-origin requests are still rejected. See
|
||||
[browser request boundaries](browser-request-security.md).
|
||||
6. Resolve the target without performing the operation. Path input is
|
||||
normalized and resolved in the current Domain; Object and Revision routes
|
||||
resolve back to their owning Object and all currently relevant bindings.
|
||||
7. Evaluate Principal state, Domain membership, direct Role bindings, group
|
||||
Role bindings, and positive grants. No match means deny.
|
||||
8. Invoke the handler only after authorization. Record sensitive allows,
|
||||
administrative mutations, and all denies in `auth_audit_log`.
|
||||
|
||||
Target resolvers return `404` only after the caller has enough `read` authority
|
||||
to distinguish absence. Otherwise they return `403`, preventing private-object
|
||||
enumeration. Authentication failures are `401` JSON for APIs and a login
|
||||
redirect for browser navigation. Authorization failures are `403` in both.
|
||||
|
||||
For a path, candidate grants are the exact Object/Path exceptional grant, its
|
||||
Spot/Street/Quartier ancestry once ZoneTree exists, and finally the Domain.
|
||||
Evaluation stops at no artificial path segment: only stored topology records
|
||||
participate. Until those locality records exist, the safe fallback is the
|
||||
Domain grant plus exact Object/Path grants, not string-prefix inheritance.
|
||||
|
||||
An Object with several semantic bindings is readable through its UUID when an
|
||||
exact Object grant applies or at least one live binding is readable. Responses
|
||||
then include only bindings separately readable by the caller. A Revision and
|
||||
its raw/derived projections inherit this Object decision; knowing a Revision
|
||||
UUID never supplies authority. Broad Domain grants require a live local binding
|
||||
or recorded creation provenance while the Object has no bindings anywhere.
|
||||
Other unbound/foreign-only Objects require an exact Object grant, never a broad
|
||||
Domain or Object-wildcard grant. See [Object authority scope](object-authority-scope.md).
|
||||
|
||||
## Route policy inventory
|
||||
|
||||
The first implementation slice uses the following policies. A more specific
|
||||
locality target replaces `domain` as Quartier, Street, and Spot records become
|
||||
available.
|
||||
|
||||
| Surface | Methods | Authentication | Capability and target |
|
||||
| --- | --- | --- | --- |
|
||||
| `/health`, static theme/CSS needed by login | GET/HEAD | public | none; health exposes no internals |
|
||||
| `/_/auth/login`, setup, OIDC callback, magic-link request/verify | declared flow methods | public challenge | rate-limited, challenge-bound |
|
||||
| `/_/auth/logout` | GET/HEAD confirmation; POST revocation | principal | revoke the supplied session only; browser origin guard |
|
||||
| `/u/{username}`, `/g/{group}` and semantic Viewer paths | GET/HEAD | optional in legacy, principal in enforcing | `read` resolved path/domain |
|
||||
| `/e/-/...`, `/:/new`, upload and compile write surfaces | GET plus declared writes | principal | `write` resolved path/locality |
|
||||
| `/o/uuid:*`, `/o/path:*`, `/r/view/*`, `/r/history/*`, `/r/diff/*` | GET/HEAD | policy-dependent principal | `read` owning object/path; immutable IDs do not bypass policy |
|
||||
| `/v/raw/*`, previews, archive/email/PDF children | GET/HEAD | policy-dependent principal | `read` source object/revision; cached derivations inherit source policy |
|
||||
| `/v/search`, tree, browser and children | GET/HEAD | optional/principal | filter every result by `read`; never reveal hidden counts or ancestors |
|
||||
| `/l/uuid:*` | GET | principal | `read`; POST/DELETE require `link` on object and affected paths |
|
||||
| object/revision/tag APIs | exact route method | principal | list/read=`read`, create/save/tag=`write`, restore=`write`, purge=`delete` |
|
||||
| path bind/copy/rename/remove APIs | POST | principal | `link`, `write`, `rename`, or `delete` on both source and destination as applicable |
|
||||
| GC zombie list/purge | GET/POST | principal | Domain `manage` |
|
||||
| `/-/sys/config*`, auth administration | GET/POST | principal | Domain `manage`; provider secrets never returned |
|
||||
| event scheduler and queue APIs | GET or mutation method | principal | GET Domain `manage`; mutation Domain `manage` |
|
||||
| adapter registry/open-with | GET/POST | principal | read source plus Domain `manage` for registry mutation |
|
||||
| adapter session exchange/read/write | declared ticket | service | ticket scope, object UUID, base Revision, method, expiry, one use |
|
||||
| federation enrollment | POST | service | Campus enrollment token, rate limit, controller mode; not Domain RBAC |
|
||||
| future `/s/*` | GET/HEAD | delegated | macaroon caveats and underlying still-valid delegated grant |
|
||||
|
||||
Handlers must declare supported methods; a mutating operation is never exposed
|
||||
through GET. Search indexes, recent-object lists, children projection caches,
|
||||
preview caches, archive entries, and adapter workspaces are derived data and
|
||||
must apply the source object's current authorization on every read.
|
||||
|
||||
The server keeps these declarations in a central typed endpoint policy
|
||||
classifier. Exact API routes are method-closed, unknown mutations below a
|
||||
reserved namespace fail closed, and semantic Page mutations use a Path target.
|
||||
Handler-local checks remain authoritative where the target is carried in JSON,
|
||||
multipart data, or an adapter ticket; those checks must be replaced only by a
|
||||
typed target resolver with equivalent source and destination coverage.
|
||||
|
||||
For immutable addresses, authorization resolves back to mutable authority:
|
||||
a Revision is authorized through its Object, and an Object is readable through
|
||||
an exact Object grant or at least one readable live Path binding in the current
|
||||
Domain. Raw bytes, bounded text, generated PDF pages, cached thumbnails, print,
|
||||
history, and diff projections all reuse that decision. Their responses use
|
||||
private caches varying on credentials even when the underlying Revision is
|
||||
content-addressed. Directory/search projections authorize their requested scope
|
||||
and filter every returned Path; hidden entries are excluded from displayed
|
||||
counts.
|
||||
|
||||
Recursive namespace mutations expand the complete stored source set before the
|
||||
transaction. Rename requires `rename` on every source and `create` on every
|
||||
mapped destination; copy requires `read` and `create` respectively; recursive
|
||||
delete requires `delete` on every affected Path. Link management additionally
|
||||
requires `link` authority on the Object and affected Path, and only readable
|
||||
bindings are returned by its UI.
|
||||
|
||||
## Content permission profiles
|
||||
|
||||
The group UI exposes profiles rather than ambiguous collections of checkboxes:
|
||||
|
||||
| Profile | Effective capabilities | Explicit exclusions |
|
||||
| --- | --- | --- |
|
||||
| `read` | `read` | every mutation |
|
||||
| `read_write_once` | `read`, `create`, `upload` for a previously absent target | overwrite, later Revision save, rename, unlink, delete |
|
||||
| `read_write` | `read`, `create`, `upload`, `write`, `rename`, `link` | delete |
|
||||
| `upload_only` | `upload` for a previously absent target | list/read, overwrite, rename, unlink, delete |
|
||||
|
||||
`write` implies `create` and `upload` for canonical direct Role grants, while a
|
||||
group profile stores its exact set above. `create` means create a new semantic
|
||||
binding/Object and its first Revision. `upload` is checked only after the final
|
||||
filename and destination path are normalized. Both fail closed if the target
|
||||
already exists unless `write` is also granted. Deletion is never inferred from
|
||||
write and requires an explicit `delete` grant outside these four profiles.
|
||||
|
||||
`group admin` and `group user` are membership administration roles, not content
|
||||
profiles. Owner and manager are presented as group-admin variants; member is
|
||||
presented as group user. Their Wiki access still comes only from a content
|
||||
permission profile or another Role binding.
|
||||
|
||||
## Group model
|
||||
|
||||
A Pages group is a Domain-scoped collection of Domain memberships. It is not an
|
||||
authentication provider group, a Role, a Capability, a Campus object, or a
|
||||
semantic path. The group UUID is stable while its name and Wiki binding may
|
||||
change.
|
||||
|
||||
```sql
|
||||
CREATE TABLE groups (
|
||||
uuid TEXT PRIMARY KEY,
|
||||
domain_uuid TEXT NOT NULL,
|
||||
name TEXT NOT NULL,
|
||||
display_name TEXT NOT NULL DEFAULT '',
|
||||
description TEXT NOT NULL DEFAULT '',
|
||||
visibility TEXT NOT NULL DEFAULT 'members', -- public, domain, members
|
||||
state TEXT NOT NULL DEFAULT 'active', -- active, readonly, archived
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
updated_at_ms INTEGER NOT NULL,
|
||||
UNIQUE(domain_uuid, name)
|
||||
);
|
||||
|
||||
CREATE TABLE group_members (
|
||||
group_uuid TEXT NOT NULL,
|
||||
membership_uuid TEXT NOT NULL,
|
||||
member_role TEXT NOT NULL DEFAULT 'member', -- owner, manager, member
|
||||
source TEXT NOT NULL DEFAULT 'local', -- local or mapping UUID
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
PRIMARY KEY(group_uuid, membership_uuid)
|
||||
);
|
||||
|
||||
CREATE TABLE auth_group_role_bindings (
|
||||
group_uuid TEXT NOT NULL,
|
||||
role_uuid TEXT NOT NULL,
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
PRIMARY KEY(group_uuid, role_uuid)
|
||||
);
|
||||
|
||||
CREATE TABLE auth_group_mappings (
|
||||
uuid TEXT PRIMARY KEY,
|
||||
domain_uuid TEXT NOT NULL,
|
||||
provider_type TEXT NOT NULL,
|
||||
provider_uuid TEXT NOT NULL,
|
||||
external_group TEXT NOT NULL,
|
||||
group_uuid TEXT NOT NULL,
|
||||
mode TEXT NOT NULL DEFAULT 'additive', -- additive or authoritative
|
||||
enabled INTEGER NOT NULL DEFAULT 1,
|
||||
UNIQUE(domain_uuid, provider_type, provider_uuid, external_group)
|
||||
);
|
||||
```
|
||||
|
||||
Names use `^[a-z0-9][a-z0-9_-]{1,63}$`; dots and the reserved names `_`, `new`,
|
||||
and `sys` are rejected. Display names are unrestricted presentation metadata.
|
||||
Initial implementation permits direct Principal membership only. Nested groups
|
||||
are deliberately deferred to avoid membership cycles and unclear ownership.
|
||||
|
||||
Deleting a group is a soft archive followed by explicit purge. Archive removes
|
||||
effective group Role bindings immediately but retains audit history and its Wiki
|
||||
objects. Purge requires Domain `manage`, fails while bindings/mappings remain,
|
||||
and never deletes Wiki Objects or Revisions implicitly.
|
||||
|
||||
### Effective capabilities
|
||||
|
||||
The evaluator unions positive grants from:
|
||||
|
||||
```text
|
||||
Domain membership -> direct Role bindings -> grants
|
||||
Domain membership -> group membership -> group Role bindings -> grants
|
||||
```
|
||||
|
||||
Then it applies Principal, Domain membership, group, and Role lifecycle state.
|
||||
There are no negative group grants. A Principal who belongs to the same Role
|
||||
both directly and through groups receives one effective grant. Cache keys include
|
||||
`domain_uuid`, `principal_uuid`, and a monotonically increasing policy version;
|
||||
membership, binding, role, grant, or state mutation increments that version.
|
||||
|
||||
`owner`, `manager`, and `member` in `group_members.member_role` govern group
|
||||
administration only:
|
||||
|
||||
- owner: metadata, managers/members, Role bindings, external mappings, archive;
|
||||
- manager: metadata and member list, but not owners, Role bindings, or mappings;
|
||||
- member: view the group according to visibility and use granted Roles.
|
||||
|
||||
Domain `manage` bypasses group-administration roles. Group ownership itself does
|
||||
not imply Wiki `read` or `write`; those remain capabilities. At least one local
|
||||
owner must remain while a group is active.
|
||||
|
||||
Group `visibility` controls only profile metadata and discoverability. `public`
|
||||
does not make the group Wiki public, `domain` does not grant Wiki `read`, and
|
||||
`members` does not make every member a Wiki editor. The normal capability
|
||||
decision always protects the Wiki subtree.
|
||||
|
||||
## `/g/` user interface namespace
|
||||
|
||||
`/g/` is reserved before the semantic Viewer catch-all, parallel to `/u/`:
|
||||
|
||||
| Route | Purpose | Required authority |
|
||||
| --- | --- | --- |
|
||||
| `/g/{groupname}` | Group profile followed by the group Wiki root document | visibility plus Wiki `read` |
|
||||
| `/g/{groupname}/_/edit` | Metadata, owners/managers/members, Role bindings and mappings | group manager/owner or Domain `manage` |
|
||||
| `/g/{groupname}/_/avatar` | Mutable non-revision group image | GET by visibility; PUT/POST owner/manager |
|
||||
| `/g/{groupname}/...` | Ordinary group Wiki semantic subtree | normal path capability |
|
||||
| `/e/-/g/{groupname}/...` | Canonical editor route for group Wiki documents | normal `write` capability |
|
||||
|
||||
The reserved `/_/` segment is intercepted only immediately below the group
|
||||
name. It never creates semantic children named `_`. `/g/` is excluded from the
|
||||
normal root `children` projection just as `/u/` is; group discovery is provided
|
||||
by an explicit group directory UI subject to group visibility.
|
||||
|
||||
The profile shell and Wiki document are separate projections. Absence of a Wiki
|
||||
root document does not make the group absent. Renaming a group changes its
|
||||
`/g/{name}` binding transactionally, preserves the group UUID and Objects, and
|
||||
leaves an optional time-bounded redirect alias. It must check destination path
|
||||
conflicts before mutation.
|
||||
|
||||
## Group API
|
||||
|
||||
HTML forms call versioned JSON endpoints; handlers may render errors for normal
|
||||
browser submission but share the same service layer.
|
||||
|
||||
| Endpoint | Methods | Operation |
|
||||
| --- | --- | --- |
|
||||
| `/_/api/v1/groups` | GET, POST | visible group list; create group |
|
||||
| `/_/api/v1/groups/{uuid}` | GET, PATCH, DELETE | detail; metadata/state; archive |
|
||||
| `/_/api/v1/groups/{uuid}/members` | GET, POST | list; add Domain membership |
|
||||
| `/_/api/v1/groups/{uuid}/members/{membership_uuid}` | PATCH, DELETE | change administrative role; remove |
|
||||
| `/_/api/v1/groups/{uuid}/roles` | GET, PUT, DELETE | effective Role bindings |
|
||||
| `/_/api/v1/groups/{uuid}/mappings` | GET, POST, DELETE | external group mappings |
|
||||
|
||||
All mutations require CSRF for cookie sessions, use optimistic `updated_at_ms`
|
||||
or an ETag, and append actor, request ID, old/new values, and outcome to the
|
||||
audit log. Bulk membership updates are transactional and bounded. List APIs use
|
||||
cursor pagination and do not disclose invisible groups.
|
||||
|
||||
## Implementation boundaries
|
||||
|
||||
Route policies live beside route registration in `internal/server/routes` so a
|
||||
new handler cannot silently inherit a broad default. Startup validates that
|
||||
every non-catch-all route has policies for every accepted method. Typed target
|
||||
resolvers live in `internal/server/authorization_targets.go`; they perform only
|
||||
bounded reads. `internal/store/authorization.go` owns the effective direct and
|
||||
group grant query, while `internal/store/groups.go` owns transactional group
|
||||
mutations. HTTP handlers do not issue authorization SQL directly.
|
||||
|
||||
The semantic Viewer catch-all has one explicit policy whose resolver uses the
|
||||
normalized semantic path. Reserved `/u/` and `/g/` handlers are registered
|
||||
before it and delegate their Wiki descendants back to that same semantic
|
||||
service after resolving the profile shell.
|
||||
|
||||
Minimum audit events are `auth.login.*`, `authz.denied`, `role.binding.*`,
|
||||
`grant.*`, `group.created`, `group.updated`, `group.member.*`,
|
||||
`group.role_binding.*`, `group.mapping.*`, and `group.archived`. Details contain
|
||||
stable UUIDs and changed field names, but never passwords, provider secrets,
|
||||
TOTP seeds, session/challenge tokens, email magic links, or raw OIDC tokens.
|
||||
|
||||
Required integration tests enumerate every registered route/method in the
|
||||
policy registry and cover anonymous, authenticated-but-ungranted, direct Role,
|
||||
group Role, readonly, suspended, cross-Domain, cookie-without-CSRF, Bearer,
|
||||
service-ticket, renamed-path, multiple-binding, and derived-cache access.
|
||||
|
||||
## External group synchronization
|
||||
|
||||
OIDC/LDAP claims are normalized attributes, then matched only against explicit
|
||||
`auth_group_mappings`. No mapping means no change. `additive` adds mapped
|
||||
memberships but never removes local membership. `authoritative` may remove only
|
||||
memberships previously created by that same mapping UUID; it cannot remove a
|
||||
local owner or membership from another source. Every synchronization is audited.
|
||||
|
||||
OIDC synchronization occurs after successful subject verification and before
|
||||
session issuance. Existing sessions observe policy-version changes on their next
|
||||
request. Controller-managed Campus manifests may distribute provider metadata
|
||||
and mapping definitions, but client/bind/SMTP secrets and live group membership
|
||||
are not federated unless a future signed policy explicitly says so.
|
||||
|
||||
## Built-in administrator groups
|
||||
|
||||
Every Domain has reserved `campus_admin` and `domain_admin` groups. They cannot
|
||||
be created, renamed, archived, or repurposed as ordinary groups. Existing owner
|
||||
or Domain-manage bindings seed both groups during migration to avoid lockout.
|
||||
|
||||
- `campus_admin` controls Campus records and tokens, Domain creation,
|
||||
placement, update, and deletion for that Campus. It has an owner-controlled
|
||||
option to project its membership into every Domain belonging to the Campus.
|
||||
- `domain_admin` controls Domain-local configuration, accounts, sessions,
|
||||
groups, Roles, and grants. Only a `domain_admin` may create an ordinary
|
||||
group. It is never inherited merely because two Domains share a Campus.
|
||||
- ordinary group admins control only their own group and cannot grant
|
||||
themselves either built-in administrative membership.
|
||||
|
||||
Campus projection records each independent origin in `campus_admin_grants`;
|
||||
`group_members` is its strongest-role projection. Disabling inheritance or
|
||||
removing a source revokes derived grants transactionally, without promoting
|
||||
inherited entries into new roots. New projection-owned Domain memberships are
|
||||
removed, and their sessions revoked, after the last source disappears unless
|
||||
an independent group/role grant has adopted that membership. Local and other
|
||||
inherited sources are preserved. Legacy memberships with unknown provenance
|
||||
remain inert rather than being guessed to be safe to delete. See
|
||||
[Campus administrator revocation](campus-admin-revocation.md) for the migration
|
||||
boundary, transaction hooks, regression coverage, and remaining protocol work.
|
||||
|
||||
## Cross-Domain identity inheritance
|
||||
|
||||
Cross-instance inheritance uses a Domain-pair PSK, not a browser session or a
|
||||
Campus enrollment token. The source stores only the PSK hash; the receiver
|
||||
stores the PSK encrypted by its instance authentication key. A peer record pins
|
||||
source/target Domain UUIDs, source FQDN, instance fingerprint, enabled datasets,
|
||||
and last successful sequence. TLS remains mandatory except for an explicitly
|
||||
named development-only HTTP setup path.
|
||||
|
||||
The signed snapshot/delta contains Principal UUID plus non-secret profile
|
||||
metadata, stable external identities, groups, administrative membership role,
|
||||
and content permission profiles. It never contains password verifiers, TOTP
|
||||
seeds, recovery codes, sessions, challenges, provider client secrets, SMTP
|
||||
credentials, avatars unless separately enabled, or audit-log secrets.
|
||||
|
||||
Imported rows retain `(source_instance_fingerprint, source_domain_uuid,
|
||||
source_uuid)` as their stable key. Local UUIDs remain local. Each imported
|
||||
membership records its peer UUID as source, so disabling a peer removes only
|
||||
that peer's effective membership. Groups with the same display/name but a
|
||||
different source identity are not merged implicitly.
|
||||
|
||||
The receiver pulls monotonically sequenced deltas and applies each sequence in
|
||||
one transaction. Replay is idempotent; gaps trigger a full snapshot. A changed
|
||||
source fingerprint stops synchronization and emits a warning until a Campus
|
||||
administrator approves the replacement. `campus_admin` may opt into fan-out to
|
||||
all Domains in its Campus; `domain_admin` and ordinary groups are inherited only
|
||||
when explicitly selected by the peer policy.
|
||||
|
||||
## Migration and implementation slices
|
||||
|
||||
1. Replace `requestedCapability` with route policy registration, exact methods,
|
||||
typed target resolvers, and deny/audit tests. Preserve `legacy` only for
|
||||
semantic read routes; administration and mutation are never anonymous.
|
||||
2. Add CSRF for cookie mutations and separate Principal, adapter, federation,
|
||||
and future delegation credential resolvers.
|
||||
3. Add group schema/service, `/g/` routing, profile/edit UI, and i18n. Migrate no
|
||||
existing Role binding destructively; group Role bindings use a new table.
|
||||
4. Extend effective authorization with group bindings and policy-version cache;
|
||||
add direct/group union and state-invalidation tests.
|
||||
5. Add external group mapping and audited OIDC/LDAP group synchronization. LDAP
|
||||
authentication is implemented; directory-group lookup and explicit mapping
|
||||
reconciliation remain separate authorization work and must not be inferred
|
||||
from the successful login attributes.
|
||||
6. Switch new Domains to enforcing after owner bootstrap; retire the broad
|
||||
`legacy` bypass only after the endpoint matrix has integration coverage.
|
||||
|
||||
Rollback disables group-derived evaluation and route-policy enforcement behind
|
||||
separate migration flags; additive tables remain readable. It never drops
|
||||
Principals, sessions, existing direct Role bindings, Objects, or Revisions.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Scoped automatic publication
|
||||
|
||||
Implemented 2026-09-19. Explicit opt-in, local Domain policy; no existing scope is
|
||||
enabled by migration or deployment. This is a live-head publication mechanism,
|
||||
not the reviewer/Inbox workflow in `publication-approval-inbox.md`.
|
||||
|
||||
## Scope and controls
|
||||
|
||||
- City detail → governance dialog → Automatic publication → preview current impact.
|
||||
- `inherit`: no local automatic rule; ancestor automatic rules may apply.
|
||||
- `required`: manual publication only, including descendants. A descendant cannot
|
||||
override this floor by selecting automatic. Supported at Domain/Quartier/Street/Spot.
|
||||
- `automatic`: supported only at Street/Spot, with an effective public audience.
|
||||
Existing eligible Pages, future descendants (including moved-in Pages) and all
|
||||
current language heads are public immediately. Empty scopes can opt in too.
|
||||
- Existing public audience ceilings and user/group restrictions remain authoritative.
|
||||
Aliased Objects, reserved Paths and restricted descendant scopes remain excluded.
|
||||
- Automatic and inherited activation require confirmation of current impact and
|
||||
future publication. Preview binds actor/scope/governance/topology and all automatic
|
||||
rule versions. CAS plus SQLite writer reservation reject stale or concurrent edits.
|
||||
- Stopping automatic publication does not revoke separately frozen approvals. Use
|
||||
audience restriction for complete privacy. Existing publication-revoke also sets
|
||||
this scope to manual-only to stop automatic publication inherited from an ancestor.
|
||||
|
||||
## Authority, data and read behavior
|
||||
|
||||
`locality_auto_publication` stores Domain, node kind/UUID, mode, pinned Path boundary,
|
||||
enabling Principal and version. The enabling Principal must remain an active member
|
||||
with current governance and scoped read authority. Existing owner/admin delegation
|
||||
is reused; ownership, membership and role revocation suspend the corresponding grant.
|
||||
Audit records use `city_governance_events`; no silent new grants or source-content edits.
|
||||
|
||||
Automatic publication uses a read transaction, not materialized approval entries or
|
||||
an asynchronous job. This gives read-after-write publication for authorized posts,
|
||||
CLI writes and edits without a stale scheduler window. Anonymous body/raw reads,
|
||||
public navigation, projected blog/diary titles, RSS and share readiness use the same
|
||||
rules. Manual exact-Revision approvals remain the default and remain separate.
|
||||
|
||||
The boundary is pinned to the configured Path; renaming the Street/Spot boundary
|
||||
suspends its grant until explicitly reconfirmed. Moving a Page outside the boundary
|
||||
does not carry publication with its UUID. Audience restrictions are checked live.
|
||||
Domain/Campus disablement and authorization-mode changes fail closed. Enforcing
|
||||
authorization cannot be switched off while an automatic rule remains configured.
|
||||
|
||||
Public-navigation generations include automatic rules and their authority sources.
|
||||
Role/member invalidation is conditional on the existence of automatic rules, keeping
|
||||
the existing invariant that ordinary authenticated navigation never caches ACLs.
|
||||
|
||||
## API and budgets
|
||||
|
||||
`GET/PATCH /_/api/v1/city/{zones|spots|domains}/{uuid}/governance/auto-publication`
|
||||
uses the existing authenticated handler-owned governance authorization. PATCH fields:
|
||||
`mode`, `version`, `epoch`, `topology_version`, `confirm`, `impact_token`.
|
||||
GET never grants publication. Strict JSON and 4KiB input limits apply.
|
||||
|
||||
Impact previews retain the existing 512-Path limit; a too-large preview still permits
|
||||
manual-only shutdown, but not activation. Live navigation is metadata-only and bounded
|
||||
by 20,000 entries / 4MiB with a 2-second caller deadline. Exact body lookup restricts
|
||||
the query to the requested Path. Policy enumeration is capped at 128 local rows.
|
||||
Errors/budget exhaustion do not fall back to public/unfiltered content.
|
||||
|
||||
## Remaining work
|
||||
|
||||
- Independent reviewer policies, requests, quorum, Inbox and signed Campus inheritance.
|
||||
A future `approval=required` floor must also block this live-head publication mode.
|
||||
- Federation of these policies is not implemented; no automatic-policy fields are
|
||||
added to Domain provisioning manifests.
|
||||
- Larger activation previews need paginated impact review/token binding rather than
|
||||
silently lifting the current limit. Policy tombstone/archived-node cleanup is pending.
|
||||
- External caches, feed-reader copies and already-posted social links cannot be recalled.
|
||||
@@ -0,0 +1,91 @@
|
||||
# Browser request and session boundaries
|
||||
|
||||
Implemented 2026-09-14. All requests pass the browser mutation guard before
|
||||
authorization's legacy-mode or handler-owned route branches. Same-origin forms
|
||||
and fetch calls continue working without page-specific hidden-token injection.
|
||||
|
||||
## CSRF
|
||||
|
||||
The guard uses Go's `http.CrossOriginProtection` (available since Go 1.25) and
|
||||
has no trusted cross-origin list or route-prefix exceptions. Fetch Metadata and
|
||||
Origin distinguish same-origin requests from unrelated or sibling origins;
|
||||
`Origin: null` is rejected. Host resolution never trusts `X-Forwarded-Host`.
|
||||
For legacy clients without same-origin Fetch Metadata, Origin must also use the
|
||||
request's scheme; an HTTP origin cannot target an HTTPS browser session merely
|
||||
because the host matches. TLS-terminating proxies must preserve forwarded scheme.
|
||||
See the [Go 1.25 HTTP release notes](https://go.dev/doc/go1.25#net/http).
|
||||
|
||||
Unsafe requests carrying an ambient session/MFA cookie must additionally have
|
||||
validated origin metadata or a matching HTTP(S) Referer. Missing browser-origin
|
||||
evidence fails closed. Headerless server-to-server clients remain supported;
|
||||
API clients should use explicit Bearer authentication. Cross-origin login,
|
||||
profile/group/configuration/upload and API mutations are covered, not just
|
||||
document save routes. API denials return JSON with status 403.
|
||||
|
||||
Logout is POST-only for revocation; GET/HEAD render confirmation without
|
||||
changing session state. Profile menus submit a native same-origin POST form.
|
||||
Bearer logout revokes exactly the supplied token, not an unrelated cookie.
|
||||
|
||||
Legacy semantic editor GET entry can still allocate an empty Page. Its entry
|
||||
routes are therefore checked as mutations too; direct address-bar/bookmark
|
||||
navigation with browser `Sec-Fetch-Site: none` remains allowed. Moving creation
|
||||
fully into the save transaction remains a separate editor API correction.
|
||||
OIDC/magic-link callbacks are one-use, purpose-bound login flows, not generic
|
||||
state-changing GET endpoints. OIDC additionally has browser-bound state.
|
||||
|
||||
## Credential purpose
|
||||
|
||||
New API tokens begin with `pw_api_`; new cookie sessions begin with
|
||||
`pw_browser_`. The complete prefix plus random secret is SHA-256 hashed in the
|
||||
session store. Changing/removing a prefix cannot convert its purpose.
|
||||
Browser tokens are rejected in Authorization; API tokens are rejected in the
|
||||
session cookie. Adapter/federation/challenge tokens use independent validation
|
||||
and tables and are not accepted as login sessions.
|
||||
|
||||
Unprefixed pre-upgrade sessions retain compatibility until their recorded
|
||||
expiry (normally 24 hours). No live session is forcibly migrated or broadened.
|
||||
Once the old rows expire, new sessions enforce transport separation throughout.
|
||||
Store helpers without HTTP context remain trusted internal APIs.
|
||||
|
||||
Session insertion itself requires an active/readonly Principal and active Domain
|
||||
membership in the same SQL statement. Each session lookup rechecks membership;
|
||||
disabling/removing it invalidates the next request even if a session row remains.
|
||||
Dynamic responses default to `private, no-store` with credential variation;
|
||||
individual immutable projections can opt into a specific private cache policy.
|
||||
|
||||
An explicitly supplied invalid/unknown/ambiguous Authorization header never
|
||||
falls back to a cookie. Duplicate session cookies are rejected. Login body
|
||||
size and local return URLs are validated; slash/backslash/control-character
|
||||
redirect variants cannot redirect to another authority.
|
||||
|
||||
## Request-scoped read authorization
|
||||
|
||||
Domain lookup is cached only in one request. A bounded single-query snapshot
|
||||
loads at most 4096 direct-role/group Path read grants, honoring principal and
|
||||
membership states, exact direct grants and literal group subtree boundaries.
|
||||
It is immutable, contains no list of all document Paths and is discarded at
|
||||
request end. Errors/oversized policies fail closed. Tree/children/search/City
|
||||
read filtering reuses this snapshot; mutation authorization does not.
|
||||
|
||||
The next request rechecks sessions, membership and grants. There is no TTL
|
||||
allow-cache that outlives revocation. A change during an already-rendering
|
||||
request takes effect on the next request; transactional mutation authorization
|
||||
and streaming revocation have separate contracts.
|
||||
|
||||
## City projection
|
||||
|
||||
Map/detail/Spot Page APIs, City macros and Viewer locality badges filter by
|
||||
readable locality boundaries and Page Paths. Counts and portal choices are
|
||||
recomputed from visible Pages; nearby relations require both visible ends.
|
||||
No Domain-only topology ETag is reused across callers (`private, no-store`).
|
||||
Parents without readable boundaries are not exposed just because a descendant
|
||||
or MagicPage happens to be readable. Unbound/hidden aliases are not substituted
|
||||
with UUID links to bypass Path visibility. The complete topology is still loaded
|
||||
before projection; lazy server-side City pagination remains outstanding.
|
||||
|
||||
Regression tests cover cross-origin/missing-metadata denials, login/logout,
|
||||
purpose confusion, exact/wildcard grant semantics, principal states, next-request
|
||||
revocation, hidden City metadata/counts/portals/relations and macro projection.
|
||||
An opt-in Chromium regression additionally submits the real login and logout
|
||||
forms using HttpOnly cookies and actual Fetch Metadata, with no injected Bearer
|
||||
credential, and verifies logout leaves a separate API session intact.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Campus administrator inheritance: revocation and provenance
|
||||
|
||||
Implemented: 2026-09-14. This note supersedes the former insert-only Campus
|
||||
projection described in `authorization-groups.md`. Cross-instance Domain-pair
|
||||
PSK synchronization is still a separate, unimplemented protocol.
|
||||
|
||||
## Authority and data ownership
|
||||
|
||||
`campus_admin_grants` is the authoritative set of independent and inherited
|
||||
grants for the built-in `campus_admin` group only. Its key is
|
||||
`(group_uuid, membership_uuid, source)`. An independent grant uses `local`,
|
||||
`migration`, or an existing non-Campus source identifier. Derived grants use
|
||||
`campus_admin_inherit:<origin group UUID>`.
|
||||
|
||||
`group_members` remains the public/effective membership table. The strongest
|
||||
remaining role wins (`owner > manager > member`), with a direct source winning
|
||||
ties. A weaker local grant is kept in provenance, not overwritten by a stronger
|
||||
inherited role, and becomes effective again when that inherited role expires.
|
||||
Ordinary groups and `domain_admin` retain their existing storage and behavior.
|
||||
|
||||
Projection roots must have an active source group, active principal, active
|
||||
source Domain membership, enabled source Domain, and enabled inheritance flag.
|
||||
The target must be an enabled Domain in the same Campus with an active built-in
|
||||
group. Only independent grants are roots. Derived rows cannot retransmit
|
||||
authority, become new roots, or keep one another alive in a cycle. Multiple
|
||||
independent origins are recorded separately; removing one does not remove the
|
||||
others. Changing a principal to readonly also withdraws inherited administrator
|
||||
membership; changing it back to active can restore the projection but does not
|
||||
revive revoked sessions.
|
||||
|
||||
## Transaction boundary
|
||||
|
||||
The following write paths reconcile within the same SQLite transaction:
|
||||
|
||||
- enabling/disabling Campus inheritance;
|
||||
- adding, changing, or removing an independent Campus group member;
|
||||
- changing a principal's state and revoking its sessions;
|
||||
- updating/deleting a Domain, including moves between Campuses;
|
||||
- applying a managed-Campus topology snapshot or deleting a managed Campus;
|
||||
- built-in group creation/bootstrap migration.
|
||||
|
||||
The projection rebuilds the effective Campus group membership from authoritative
|
||||
grants. Any SQL failure rolls back both the source mutation and the projection.
|
||||
No asynchronous queue or stale authorization cache sits between revocation and
|
||||
the next authorization decision. Direct SQL administration must explicitly run
|
||||
`ProjectCampusAdminMemberships`; deleting only the materialized `group_members`
|
||||
row is not a revocation API. Future LDAP/OIDC mappings and PSK importers must
|
||||
write provenance and reconcile in their own transaction, not edit the cache.
|
||||
|
||||
Inherited-only members cannot be removed at a destination: revoke their origin
|
||||
or disable its inheritance. Removing an independent owner requires another
|
||||
independent owner at that source; an owner inherited from somewhere else is
|
||||
not sufficient. Bootstrap migration records each migrated source binding once
|
||||
in `campus_admin_migrations`, so a later explicit Campus-group removal is not
|
||||
undone by a restart or the creation of another Domain.
|
||||
|
||||
## Domain membership and session cleanup
|
||||
|
||||
`campus_admin_membership_origins` records exactly which Domain memberships the
|
||||
projector created. After the last derived grant disappears, a provenance-owned
|
||||
membership with no other group membership or role binding is removed and that
|
||||
principal's sessions in that Domain are revoked atomically.
|
||||
|
||||
Existing local memberships are never reactivated, relabeled as inherited, or
|
||||
deleted by projection. Adding an independent group grant adopts an inherited
|
||||
membership as local. An independent role binding likewise prevents cleanup and
|
||||
preserves its session. No role binding or capability grant is deleted: the old
|
||||
Campus projection never created `auth_role_bindings`, and revocation of a group
|
||||
membership already removes access through that group's permission profiles.
|
||||
Independent `domain_admin` and direct role capabilities remain unchanged.
|
||||
|
||||
## Upgrade behavior and limits
|
||||
|
||||
Older installations recorded only one source per effective group member and
|
||||
did not record the origin of a Domain membership. On the first schema upgrade,
|
||||
only stored non-inherited Campus group memberships seed authoritative grants;
|
||||
old inherited chains are discarded and regenerated from those roots. A legacy
|
||||
Domain membership with ambiguous origin is retained, while its inherited group
|
||||
authority is revoked normally. Do not guess that an untagged membership belongs
|
||||
to the projector and delete a potentially independent local identity record.
|
||||
An old local grant previously overwritten or mislabeled by the single-source
|
||||
implementation cannot be reconstructed; an administrator must explicitly grant
|
||||
that local role again if needed. Newly recorded grants do not have this loss.
|
||||
|
||||
Reconciliation is set-based and limited to Campus administrator memberships;
|
||||
it runs on administrative changes, not on ordinary reads or session lookups.
|
||||
It currently recomputes all Campus administrator projections in one transaction.
|
||||
Incremental Campus-scoped reconciliation and sequenced cross-instance deltas are
|
||||
future scaling work; do not advertise distributed revocation guarantees before
|
||||
the PSK protocol and its source-disappearance policy exist.
|
||||
|
||||
## Regression coverage
|
||||
|
||||
`groups_inheritance_test.go` covers disable/re-enable, repeated reconciliation,
|
||||
source removal, suspension/quarantine/readonly, removed/disabled/moved source
|
||||
Domains, multiple roots, prevention of transitive amplification, weaker local
|
||||
role restoration, independent role/session preservation, legacy-chain cleanup,
|
||||
restart-safe bootstrap removal, and injected mid-transaction failures for
|
||||
disable/remove/suspend. Existing concurrent owner-integrity tests remain green.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Campus and Domain Model
|
||||
|
||||
## Purpose
|
||||
|
||||
Campus is the top-level administrative and language-default boundary.
|
||||
Domain is the host-selected subdomain space presented to a request. Every
|
||||
Domain belongs to exactly one Campus.
|
||||
|
||||
This slice intentionally stops before ZoneTree. Quartier, Street, Spot, and
|
||||
SpotGraph remain later topology work.
|
||||
|
||||
## Identity
|
||||
|
||||
Both Campus and Domain have:
|
||||
|
||||
- an integer SQLite row ID for local administration;
|
||||
- a stable UUID for relationships;
|
||||
- a normalized, unique machine name;
|
||||
- a human-readable title;
|
||||
- an enabled flag;
|
||||
- a creation timestamp.
|
||||
|
||||
Campus additionally has a BCP 47 default language, authority mode, and FQDN.
|
||||
Domain additionally has a host selector. A selector can be a full host
|
||||
(`docs.example.test`), a subdomain label (`docs`), or empty to select the
|
||||
Campus FQDN itself.
|
||||
|
||||
## Ownership invariants
|
||||
|
||||
- Every Domain `campus_uuid` resolves to an existing Campus.
|
||||
- At least one Campus exists and at least one Campus remains enabled.
|
||||
- A Campus referenced by a Domain cannot be deleted.
|
||||
- A Campus referenced by a Domain cannot be disabled.
|
||||
- Creating or moving a Domain requires an enabled target Campus.
|
||||
- Disabled Domains do not participate in request-host selection.
|
||||
- Request-host resolution is exact and has no last-resort Domain fallback.
|
||||
- An empty Domain host matches only its owning Campus FQDN.
|
||||
- The request Campus is derived from the resolved Domain; it is not selected
|
||||
independently.
|
||||
|
||||
SQLite does not currently rebuild legacy tables to add a foreign-key
|
||||
constraint. These invariants are enforced by store operations so existing
|
||||
installations can migrate without destructive table replacement.
|
||||
|
||||
## Schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE campuses (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
uuid TEXT NOT NULL UNIQUE,
|
||||
name TEXT NOT NULL UNIQUE,
|
||||
title TEXT NOT NULL,
|
||||
default_lang TEXT NOT NULL DEFAULT 'en',
|
||||
authority_mode TEXT NOT NULL DEFAULT 'standalone',
|
||||
fqdn TEXT NOT NULL,
|
||||
enabled INTEGER NOT NULL DEFAULT 1,
|
||||
created_at INTEGER NOT NULL
|
||||
);
|
||||
|
||||
-- Added to domains during initialization:
|
||||
ALTER TABLE domains ADD COLUMN campus_uuid TEXT;
|
||||
CREATE INDEX idx_domains_campus_uuid ON domains(campus_uuid);
|
||||
```
|
||||
|
||||
## Startup migration
|
||||
|
||||
Initialization is idempotent:
|
||||
|
||||
1. The existing District-to-Domain compatibility migration runs.
|
||||
2. If no Campus exists, `Default Campus` is created.
|
||||
3. The nullable `domains.campus_uuid` column is added when absent.
|
||||
4. Empty, unknown, and legacy Campus references are assigned to the enabled
|
||||
default Campus.
|
||||
|
||||
UUIDs, Domain host selectors, and existing paths are preserved.
|
||||
|
||||
## Request context
|
||||
|
||||
The server resolves one Domain from the HTTP Host and then resolves its
|
||||
owning Campus. Both values are exposed as `RequestContext.Domain` and
|
||||
`RequestContext.Campus`.
|
||||
|
||||
Revision language selection uses this order:
|
||||
|
||||
1. explicit language request;
|
||||
2. request language preferences;
|
||||
3. Campus default language;
|
||||
4. system locale;
|
||||
5. language-neutral revision;
|
||||
6. latest revision.
|
||||
|
||||
## Administration
|
||||
|
||||
The Config view supports Campus create, update, and delete, as well as Domain
|
||||
assignment to a Campus. The last enabled Campus cannot be disabled. A Campus
|
||||
must first have its Domains moved or deleted before it can be deleted.
|
||||
|
||||
The data CLI remains object/path/revision/asset oriented. Campus and Domain
|
||||
administration is therefore not added to the CLI in this slice.
|
||||
@@ -0,0 +1,93 @@
|
||||
# City courtyard projection and immersive navigation
|
||||
|
||||
Implemented UI slice, 2026-09-14. Complements
|
||||
[City organization](city-organization-ui.md) and the larger
|
||||
[City review](city-review-and-reconciliation.md); not a replacement for its
|
||||
authorization, reconciliation or Worker hardening work.
|
||||
|
||||
## Interaction
|
||||
|
||||
The browsing sequence is `Domain → Quartier → Street → Spot → Page`.
|
||||
Clicking a Spot now explores its courtyard **inside the map**, rather than
|
||||
immediately navigating to its portal document. The central building represents
|
||||
the Spot; surrounding smaller buildings are its Page placements. The focused
|
||||
Spot offers a separate portal Page link. An actual boundary/portal Page is not
|
||||
repeated as its own surrounding Page building. A descendant suggested by the
|
||||
API as a fallback portal remains independently visible/selectable. Undefined
|
||||
placements use a fountain and retain
|
||||
yellow-green Page markers.
|
||||
|
||||
Page buildings link to their semantic Path, falling back to `/o/uuid:{uuid}`.
|
||||
These are rendering changes only: no document Paths, memberships, UUIDs,
|
||||
revisions or contents are changed. The displayed set follows existing SpotGraph
|
||||
membership, including explicit links; it is not a new filesystem hierarchy.
|
||||
|
||||
Breadcrumbs and clicking outside the courtyard ascend within the map. Map
|
||||
exploration does not call pushState or add browsing history. Actual Page links
|
||||
still navigate normally (from a map popup, in the containing window).
|
||||
Ctrl/Command selection and the existing merge/rename/move dialogs work for
|
||||
whole Spots and individual Page buildings, without following their links.
|
||||
|
||||
## Layout and visual vocabulary
|
||||
|
||||
- Domain/Quartier retain the single generated city fabric and its allocations.
|
||||
- Street close-ups use a deterministic courtyard layout, with generated road
|
||||
segments projected behind it and paths connecting courtyard gates to roads.
|
||||
This is a readable close-up schematic, not geometric continuity at every zoom
|
||||
level. Connected road allocation and natural parcel packing remain future work.
|
||||
- Nonoverlapping plots reserve space for the Spot, six nearby Pages and gates.
|
||||
At most six Spots are rendered per Street screen; further Spots are paginated.
|
||||
- A focused Spot renders at most 24 surrounding Pages per screen, also paginated.
|
||||
Page UUID deduplication prevents multiple graph edges creating duplicate houses.
|
||||
- Labels remain horizontal and visible at rest, with bounded two-line wrapping
|
||||
and full-name/Path tooltips. The existing label toggle controls the new labels.
|
||||
- Native SVG motifs include stucco/terracotta houses, a pediment and colonnade,
|
||||
stone paving, balustrades, cypresses, fountains and ornamental iron gates.
|
||||
Theme-derived stone/brass colors, the academic crest and compass carry the
|
||||
same visual language into the map frame and menu. No external images/fonts
|
||||
or raster-generation service are needed for these additions.
|
||||
|
||||
The new `city-estates.js` module owns only close-up layout and rendering.
|
||||
`city-map.js` retains topology, navigation, generated fabric and API interaction;
|
||||
`city-organizer.js` retains selection and mutations. The obsolete geometry
|
||||
script and mutation-observer Spot repositioning no longer run on the map.
|
||||
Pointer dragging and wheel zoom use SVG coordinates with a screen-pixel drag
|
||||
threshold, including differently sized close-up viewBoxes.
|
||||
|
||||
## Utility menu
|
||||
|
||||
The initial normal and popup screens show the map, breadcrumb, menu launcher,
|
||||
small navigation hint, compass and (only when needed) pagination/selection bar.
|
||||
The permanent inspector, directory, planner and toolbar are moved into a themed
|
||||
native modal (`city-menu.js`):
|
||||
|
||||
- Guide: selected locality, details link and existing editing operations.
|
||||
- Directory: named navigation to Quartier/Street/Spot views.
|
||||
- Planning, for authorized planners only: URL planning and one creation form at
|
||||
a time, selected by kind.
|
||||
- Settings: zoom/reset/labels, topology status, scoped search and account links.
|
||||
|
||||
The dialog uses native modal focus containment and Escape dismissal. Its Escape
|
||||
handler does not propagate to the containing map popup. There is no permanent
|
||||
outer-page scrolling; menu content can scroll independently. Mobile CSS reduces
|
||||
the frame and changes the menu navigation to two columns.
|
||||
|
||||
## Verification and limits
|
||||
|
||||
Opt-in Chromium fixtures cover normal/popup modes: resting labels, Ctrl
|
||||
selection, title/group/merge/move regression, plot nonoverlap, six-Spot and
|
||||
24-Page bounds, full pagination reachability, correct Page/portal links,
|
||||
unchanged map URL/history, menu panel switching, creation-form visibility,
|
||||
directory navigation and background ascent. Screenshots cover sparse Street,
|
||||
dense Spot and menu scenes, including a 390px viewport with Index White. Run:
|
||||
|
||||
```sh
|
||||
PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run 'TestCity(Labels|Organizer|Immersive)Chromium' -count=1
|
||||
```
|
||||
|
||||
These are DOM-rendering bounds, **not** server/API pagination. The map still
|
||||
loads topology and Page placements eagerly; the directory and some inspector
|
||||
option lists still traverse that loaded topology. Per-result authorization,
|
||||
bounded/lazy server projection, connected roads, Worker generation, keyboard
|
||||
directional navigation and auto-reconciliation remain open in CITY-A–D.
|
||||
This slice does not claim to solve those scaling/security gaps.
|
||||
@@ -0,0 +1,81 @@
|
||||
# City organization UI
|
||||
|
||||
Implemented follow-up, 2026-09-13. This is a bounded manual editing slice of
|
||||
[the City review](city-review-and-reconciliation.md), not the automatic outbox
|
||||
or Worker pipeline.
|
||||
|
||||
## User model
|
||||
|
||||
Hierarchy remains `Quartier → Street → Spot → Page`; a Spot cannot own a Spot.
|
||||
Yellow-green points are unclassified Pages, not nested Spot objects.
|
||||
|
||||
- Context menu or inspector pencil: edit a locality's **display title**. UUID,
|
||||
slug/name and Path remain unchanged. Japanese titles are accepted.
|
||||
- Ctrl/Command-click toggles selection of Page buildings/points or whole Spots.
|
||||
Selection persists while navigating between Streets. As of 2026-09-14, ordinary
|
||||
Spot clicks explore a courtyard; Page buildings and the separate portal link
|
||||
navigate to documents. See [immersive map projection](city-immersive-map.md).
|
||||
- The floating icon toolbar/context menu can combine the selection into an
|
||||
existing Spot, or create one Spot containing the selected Pages.
|
||||
- Whole-Spot merge archives the sources, transfers Page placements and
|
||||
incoming/outgoing relations, deduplicates relations and drops self-relations.
|
||||
Source descriptions/charters remain on archived rows; they are not concatenated
|
||||
into the destination. Existing destination labels take precedence over duplicates.
|
||||
- Move relocates whole Spots to a Street, retaining UUIDs. Path boundaries
|
||||
change atomically with Street placement. Single moves allow a custom boundary;
|
||||
bulk moves use the old boundary's final segment under the new Street.
|
||||
Conflicts or invalid ancestry reject the entire operation.
|
||||
|
||||
These operations **preserve document URLs, Page UUIDs, Revisions and content**.
|
||||
Moving a Spot captures its existing inferred members as explicit memberships;
|
||||
the moved boundary may infer new Pages too. This is a City/SpotGraph operation,
|
||||
not recursive filesystem/URL rename. The modal explains the distinction before
|
||||
submission. Changing document URLs remains a separate Path operation.
|
||||
|
||||
## Backend contract
|
||||
|
||||
- `POST /_/api/v1/city/{zones|spots}/{uuid}/title`: title and mandatory
|
||||
`base_version`; zones additionally supply `kind=quartier|street`.
|
||||
- `POST /_/api/v1/city/organize`: mandatory `base_version`, `action=merge|move`,
|
||||
whole-Spot UUIDs and/or `{spot_uuid,page_uuid}` selections. Merge chooses
|
||||
exactly one of `target_spot_uuid` and a `new_spot` definition. Move accepts
|
||||
whole Spots and a destination Street only.
|
||||
- Both routes require existing Domain administrator/manage authorization.
|
||||
Targets, sources, parents and Page membership are revalidated inside the
|
||||
transaction against the current Domain. Stale topology returns 409.
|
||||
- Selection is limited to 200 entries. Expansion is capped at 2,000 Page-edge
|
||||
placements and 2,000 affected relations; larger operations fail without
|
||||
partial application. This is not a background bulk-import API.
|
||||
- Transfer, archive/move, overrides and one topology event/version increment
|
||||
commit together. Title no-ops do not increment versions. Validation/DB failures
|
||||
roll back everything; retries using an old version cannot reapply.
|
||||
- Audit events store requests, source placements and previous Path/Street
|
||||
boundaries. No automatic undo UI or exact reverse-operation endpoint exists
|
||||
yet; this is not a complete reversible merge implementation.
|
||||
|
||||
`city_page_overrides(domain_uuid,page_uuid,spot_uuid)` records manual placement.
|
||||
Active overrides prevent autoplan reconstructing old assignments and suppress
|
||||
inferred membership in other Spots. Other explicit MagicPage edges remain valid.
|
||||
An archived destination no longer suppresses inference; overrides are carried
|
||||
forward when its whole Spot is merged again. This is not the future full
|
||||
generation-provenance/outbox design or a general exclusion-management UI.
|
||||
|
||||
Normal and popup views share a themed native modal and selection toolbar;
|
||||
Ctrl/Command-click in a popup must not trigger top-window navigation.
|
||||
The generator seed no longer includes topology version, and its in-page fabric
|
||||
is reused on reload so renaming does not randomly rebuild the town. Allocation
|
||||
can still change with membership weights; Worker generation and persistent
|
||||
geometry caching remain open.
|
||||
|
||||
## Verification and remaining work
|
||||
|
||||
Store/API tests cover Unicode titles, identity/URL preservation, stale requests,
|
||||
admin denial, invalid/cross-Domain selections, relation transfer/deduplication,
|
||||
inference preservation, and rollback after injected mid-write failure.
|
||||
Chromium tests exercise Ctrl selection/deselection, grouping undefined Pages,
|
||||
rename, whole-Spot merge, relocation and autoplan overrides in normal/popup modes.
|
||||
|
||||
Remaining: editable slug aliases and redirects for merged Spot detail URLs;
|
||||
per-Page override management/undo; URL-renaming with explicit preview;
|
||||
bounded automatic reconciliation; projection authorization/read scaling;
|
||||
Worker/geometry capacity fixes and directional keyboard navigation.
|
||||
@@ -0,0 +1,91 @@
|
||||
# Bounded City read snapshots and literal Path boundaries
|
||||
|
||||
Implemented 2026-09-14. This is a bounded repair of CITY-04/CITY-06, not completion
|
||||
of the [City review](city-review-and-reconciliation.md) or its lazy projection plan.
|
||||
|
||||
## Read contract
|
||||
|
||||
`GetCityMapContext` uses one read-only SQLite transaction with a two-second
|
||||
deadline, shortened by request cancellation. The topology version, Quartiers,
|
||||
Streets, Spots, Page placements and relations all come from that same snapshot.
|
||||
Each cursor is fully scanned, checked and closed before the next query; a
|
||||
one-connection pool therefore works without nested-connection deadlock.
|
||||
|
||||
Quartiers, Streets, Spots and relations use four bulk cursors. Page placements
|
||||
still use one bounded query per Spot, on the **same transaction/connection**.
|
||||
Parent joins require current-Domain active Quartiers/Streets/Spots. Foreign or
|
||||
archived parents cannot introduce children into the model. Explicit Page edges
|
||||
require a current-Domain Path binding, including edges left behind after moving
|
||||
the last binding to another Domain. Relations require two visible active Spots.
|
||||
|
||||
The projection fails with `ErrCityMapBudget` rather than silently truncating:
|
||||
|
||||
| Budget | Limit per complete map |
|
||||
| --- | ---: |
|
||||
| Quartier + Street + Spot nodes | 4,096 |
|
||||
| Page placements, including multiple semantic appearances | 20,000 |
|
||||
| Relations examined | 8,192 |
|
||||
| Database snapshot / connection wait | 2 seconds |
|
||||
|
||||
Errors return an empty model, not partial topology with apparently successful
|
||||
counts. Spot counts deduplicate Page UUIDs while preserving distinct typed edges.
|
||||
Exact boundary Pages remain preferred portals. Query/scan/version errors are
|
||||
propagated, and all error/cancellation paths release cursors and connections.
|
||||
|
||||
`ListSpotPagesContext` applies the same two-second read transaction and 20,000
|
||||
placement safety limit to an HTTP Spot projection. Trusted `ListSpotPages`
|
||||
retains its complete-set contract. This is a safety ceiling, **not pagination**.
|
||||
No Page bodies or revision histories are read for these projections.
|
||||
|
||||
HTTP map/detail/Page projections return `503` with `Retry-After: 5` when a
|
||||
safety ceiling or request deadline is reached, rather than misreporting a
|
||||
large locality as missing. Missing or unreadable localities remain `404`;
|
||||
unexpected storage failures remain `500`.
|
||||
|
||||
The server's separate request-scoped read-policy filter remains mandatory: a
|
||||
consistent Domain snapshot is not authorization to see every locality or Page.
|
||||
No cross-principal model cache or topology-only public ETag is introduced.
|
||||
|
||||
## Literal boundary contract
|
||||
|
||||
All SQL containment/overlap matching in `city.go` and `city_operations.go` uses
|
||||
case-sensitive binary segment ranges, not `LIKE`. A normalized non-root boundary
|
||||
`/a%_` contains its exact Path and the range `[/a%_/, /a%_0)`; `%`, `_`, backslash
|
||||
and Unicode are ordinary characters. `/A` does not contain `/a`, and `/life`
|
||||
does not contain `/life2`. An empty legacy boundary contains nothing.
|
||||
|
||||
Root `/` covers every absolute Path. Creating it therefore conflicts with any
|
||||
other active Quartier boundary, regardless of creation order. Streets and Spots
|
||||
still require strict descendant Paths and their existing valid parent/Domain.
|
||||
No raw Path or UUID is changed, decoded again, lowercased or escaped in storage.
|
||||
|
||||
Creation validation, import overlap lookup, Path-context resolution, inferred
|
||||
Page membership, appearance lookup and health checks use these semantics.
|
||||
Context and health use bounded read snapshots too. The `/u` health exclusion
|
||||
includes the namespace root and descendants, not unrelated or differently-cased
|
||||
Paths. Health is still a basic topology summary, not a full reconciliation of
|
||||
manual membership overrides and all curation semantics.
|
||||
|
||||
## Verification and remaining work
|
||||
|
||||
`city_read_test.go` covers a one-connection pool, WAL concurrent commits between
|
||||
snapshot pinning and topology loading, all three size ceilings, connection-wait
|
||||
cancellation, nested scan errors, connection release, foreign/archived parent
|
||||
edges, foreign explicit Pages, literal wildcard/case/Unicode boundaries, root
|
||||
overlap, and health/context/overlap consistency. Existing City/import/organizer
|
||||
tests remain regression gates.
|
||||
|
||||
2026-09-14 named references: `/v/city/s/{quartier}/{street}` resolves in one
|
||||
bounded query with its current active parent. Legacy unique Street names and
|
||||
explicit `uuid:` references still work; ambiguous legacy references fail closed
|
||||
with the same 404 as missing/hidden nodes. Details check ancestor read access,
|
||||
do not load the map, and propagate cancellation. Breadcrumb macros defer map
|
||||
loading until `nearby` actually needs it. Literal Page links encode `?/#/%`.
|
||||
Regressions: `city_reference_test.go`, `city_links_test.go`, and Chromium
|
||||
`city-links.js` (normal, popup and all three initial-focus levels).
|
||||
|
||||
Still pending: lazy paginated locality/Page APIs; removal of per-Spot Page
|
||||
queries; size limits for individual legacy metadata fields; context propagation
|
||||
to remaining health/macro callers; full URL-autoplan provenance/atomic adoption. Large City data
|
||||
can currently exceed a safety ceiling and show an error until lazy projections
|
||||
are implemented. Raising global limits is not a replacement for that work.
|
||||
@@ -0,0 +1,261 @@
|
||||
# City module review and URL-driven reconciliation
|
||||
|
||||
Reviewed: 2026-09-13; implementation follow-up 2026-09-14.
|
||||
Status: **incremental repairs landed; automatic reconciliation remains design-only**.
|
||||
|
||||
Scope: City stores/APIs, URL autoplan, SVG UI, the bundled gen-city 1.4.6
|
||||
adapter, and scheduler integration. This supplements
|
||||
[Knowledge City Model](knowledge-city-model.md) and the
|
||||
[platform outbox contract](platform-extension-architecture.md#event-and-outbox-contract).
|
||||
Phase 2 checkboxes represent first slices, not completion of these repairs.
|
||||
|
||||
## Landed follow-ups
|
||||
|
||||
- [x] CITY-05 named-route slice: parent-qualified Streets, bounded cancellable
|
||||
detail lookup with active same-Domain ancestors and ambiguity detection;
|
||||
shared links across search, map, inspector, context menu and macros.
|
||||
Detail views no longer load the whole City; map focus and locality search
|
||||
support all three levels. Spot autoplan name collision handling remains open.
|
||||
- [x] Per-result map/detail/Page/macro/badge authorization and private responses;
|
||||
visible portal/count/relation recomputation.
|
||||
- [x] One-connection-safe bounded City/Spot read transactions and binary literal
|
||||
Path containment/overlap/context/health matching; see
|
||||
[read integrity and remaining limits](city-read-integrity.md).
|
||||
- [x] Stable Domain fabric seed, local Worker generation, bounded geometry cache,
|
||||
deadline/cancellation and directional Arrow/WASD/HJKL navigation; see
|
||||
[Worker contract](city-worker-navigation.md).
|
||||
- [x] Horizontal/resting labels, manual organization, nonoverlapping bounded
|
||||
Spot courtyards with Page buildings and a modal utility menu; see
|
||||
[immersive projection](city-immersive-map.md).
|
||||
|
||||
Lazy Page APIs, connected road allocation, deterministic generated Spot names and the
|
||||
outbox/provenance/idempotent inference pipeline are not implied by these checks.
|
||||
|
||||
## Original findings, in repair order
|
||||
|
||||
| ID / priority | Evidence at audit | Correction |
|
||||
| --- | --- | --- |
|
||||
| CITY-01 / P0 | `city_handler.go` returns `GetCityMap` and `ListSpotPages` without per-member authorization. Middleware gates the endpoint, not each returned Page/locality. | Batch-authorize nodes, Page links, portals, relations and counts. Audit details/macros too; Domain read must not expose denied descendants. |
|
||||
| CITY-02 / P1 | `buildCityAutoPlan` ignores Paths shorter than three segments despite its UI's shallow-Page description. `AddSpotPage` increments topology version even on identical repeated UPSERTs. | Explicit root/portal/leaf rules and no-op reconciliation for unchanged inputs. Separate inferred membership from manual edges. |
|
||||
| CITY-03 / P1 | POST `/city/autoplan` synchronously scans all Paths and applies separate node/edge transactions; the first error leaves a partially applied plan. No generation ownership/checkpoint exists. | Preview/adoption, bounded resumable batches, source provenance and itemized conflicts before automatic jobs. |
|
||||
| CITY-04 / P1 | `CityNodeOverlappingPath` merges exact/ancestor/descendant candidates with `LIMIT 1`; it and `ListSpotPages` use unescaped LIKE patterns. Autoplan treats lookup errors as absence. | Literal normalized Path segments, compatible parent/identity matching, explicit ambiguity and DB errors. Test `%`, `_`, case and non-ASCII Paths. |
|
||||
| CITY-05 / P1 | Streets allow repeated names under different parents but `CityNode`/detail URLs resolve by Domain/name. Spots require Domain-unique names, while autoplan derives only a URL segment. | Server-provided unambiguous hrefs, parent-qualified readable Street routes, existing UUID fallback, deterministic Spot name collision handling without altering display titles. |
|
||||
| CITY-06 / P1 | `GetCityMap` nests open cursors and queries per Quartier/Street/Spot, returning every Spot's entire Page list. Autoplan also queries while the Paths cursor is open. No consistent read snapshot. | Bounded bulk queries, snapshots, closed cursors, cancellation and lazy locality/Page APIs. Test with a one-connection pool. |
|
||||
| CITY-07 / P1 | `render()` seeds gen-city with `domain_uuid:topology_version` on every reload. Cached `city-geometry.js` output is assigned to `geometry` but never used by this renderer. | Stable base-fabric seed and one real geometry cache; remove obsolete generation after migration/tests. |
|
||||
| CITY-08 / P1 | gen-city's `async generate()` runs synchronous matrix initialization, recursive path generation and building generation. Layout/SVG construction also runs on the main thread. | Worker generation/layout with cancellation and budgets; separately bound DOM work. `await` alone is not CPU isolation. |
|
||||
| CITY-09 / P1 | `cityLayout` sorts/slices roads by coordinates, not connectivity; early Streets can consume all roads. Spots without buildings are omitted. Proximity uses infinite-line rather than segment distance. | Connected/fair allocation, finite segment projection and fallback picking targets. Geometry scarcity must never hide a logical node. |
|
||||
| CITY-10 / P1 | Street weights sum Spot weights (duplicate Page counting), unlike Quartier weights. Allocation repeats on navigation; a MutationObserver repairs Spot positions afterward. | Deduplicate at every level, cache allocation, place directly, manage label collisions and remove post-render repair. |
|
||||
| CITY-11 / P2 | Three embedded creation panels plus inspector move/binding/relation forms; many dynamic English literals. | Contextual icon actions, shared modal forms, localized errors and progressive disclosure. |
|
||||
| CITY-12 / P2 | Only Enter/Space node keys; no map navigation stack. `showSpot` can append a late response to a different selection. Deleted current nodes can leave an invalid view. | Directional focus, explicit view state, stale-response guards, valid-parent fallback and separate in-map history. |
|
||||
|
||||
CITY-01 describes a confirmed missing check in the inspected call chain, not a
|
||||
production exploit test. CITY-06 is a code-level scaling/pool risk, not a
|
||||
measurement of a production DB lock. Additional correctness requirements:
|
||||
|
||||
- Path/Revision/policy changes can change map output without changing its
|
||||
topology-only ETag. Model and authorization generations belong in validators.
|
||||
- Explicit edges resolve a Page's primary Path, which may be outside the
|
||||
inferred locality or unreadable. Preserve locality-specific safe portal links.
|
||||
- Undefined classification currently guesses from name/path substrings. Add an
|
||||
explicit kind instead of interpreting a user's spelling as system metadata.
|
||||
- Deleting a generated node requires an exclusion/tombstone; otherwise the next
|
||||
sweep recreates it. Offer explicit re-enablement.
|
||||
- Recursive rename already updates City prefixes transactionally. Reuse this
|
||||
identity-preserving behavior rather than recreating locality UUIDs.
|
||||
|
||||
## Component boundaries
|
||||
|
||||
1. **URL topology reconciler**: canonical Path bindings → derived memberships
|
||||
and generated node proposals, running in the existing event scheduler.
|
||||
2. **Authorized City projection**: topology + metadata → a caller-specific,
|
||||
bounded navigation model. Geometry never grants access.
|
||||
3. **Geometry adapter**: stable fabric + permitted model → blocks, connected
|
||||
Streets, anchors, hit targets and labels. gen-city does not own identity.
|
||||
|
||||
Retain gen-city for the first repair and evaluate continuity/capacity/performance
|
||||
fixtures before replacing it or maintaining a fork. Preserve its license and
|
||||
rebuild the committed bundle from `assets/city-generator`, not vendor edits.
|
||||
|
||||
## URL inference and preservation
|
||||
|
||||
- Infer from canonical Domain-scoped Paths, never display slugs, host strings
|
||||
or repeated URL decoding. Use shared reserved-address rules to exclude user,
|
||||
group and system routes instead of an incomplete local exclusion list.
|
||||
- First directory → Quartier; second → Street; third → Spot; deeper descendants
|
||||
→ that Spot. A directory has descendants and may be virtual (no own Page).
|
||||
- A locality-boundary Page is its portal, not a child of itself. For example,
|
||||
`/life/home/kitchen` with descendants is the Kitchen Spot portal;
|
||||
`/life/home/readme` without descendants is an undefined Page on Home Street.
|
||||
- A leaf gaining descendants may gain a locality without changing Page UUID.
|
||||
Change only derived membership, not curated semantic edges.
|
||||
- `/`, `/life`, `/life/home` remain Domain/Quartier/Street portal Pages. Show
|
||||
shallow/unassigned Pages at their nearest valid level; do not manufacture
|
||||
strict-descendant boundaries to force them into a Spot.
|
||||
- Undefined Pages stay individual yellow-green points. An internal bucket must
|
||||
not become a fabricated public `/_undefined` portal.
|
||||
- Store source/rule version and manual overrides separately from descriptions.
|
||||
Existing nodes and `source=local` edges start as manual/unknown: never adopt
|
||||
automatically by matching “Generated from URL Paths” text.
|
||||
- Preview adoption. Reuse exact compatible boundaries; ambiguous ancestors or
|
||||
descendants need explicit mapping. Keep exclusions, UUIDs and Page content.
|
||||
- Aliases may infer multiple memberships, but count each Page UUID once in each
|
||||
aggregate; select readable portal Paths within the locality.
|
||||
|
||||
## Event/queue design
|
||||
|
||||
Extend the shared transactional outbox; do not install expensive callbacks in
|
||||
individual HTTP handlers or build a second scheduler. Cover WebUI, CLI, import,
|
||||
hosted editors, restore, link/unlink, rename and deletion through store writes.
|
||||
|
||||
| Committed change | City invalidation |
|
||||
| --- | --- |
|
||||
| Path bind/create/unlink/delete; Object deletion | Domain/prefix membership and metadata. |
|
||||
| Rename/move, including recursive operations | Old and new prefixes; retain locality UUIDs. |
|
||||
| Revision/edit/restore; filename, MIME or title change | Metadata in Domains binding this Page; unchanged Paths do not regenerate fabric. |
|
||||
| Topology/manual rules | Affected mapping/layout. |
|
||||
| Permission/group inheritance change | Authorized projections, not canonical geometry seed. |
|
||||
| Periodic or manual repair | Same bounded reconciler/checkpoint. |
|
||||
|
||||
Proposed persistent state, **not yet migrated**:
|
||||
|
||||
- Shared `activity_outbox`: instance/event UUID, Domain sequence, event version,
|
||||
actor/source, typed Page/Revision target and old/new Path data. Atomic with the
|
||||
mutation; no document bodies or credentials.
|
||||
- `city_reconcile_state`: Domain, desired/applied sequence, rule version,
|
||||
debounce deadline, continuation cursor and last error/job UUID.
|
||||
- Generated node/membership provenance: stable source key, rule version and
|
||||
manual override/exclusion; independent of explicit SpotGraph edges.
|
||||
- Completed model generation: publish finished snapshots, not half-built
|
||||
reconciliation as a completed map.
|
||||
|
||||
Delivery protocol:
|
||||
|
||||
1. Commit change and outbox event together; rollback emits no work. SQLite
|
||||
invalidation triggers may cover legacy writers, but cannot replace actor-aware
|
||||
events. Unsupported raw SQL edits rely on periodic repair.
|
||||
2. Consume bounded batches, advance desired sequence and coalesce import/rename
|
||||
bursts by prefix/Domain. Do not create a full-scan job for every file.
|
||||
3. Enqueue `city.reconcile`, keyed by Domain. Initial proposed debounce: 2 seconds,
|
||||
maximum coalescing delay: 10 seconds, configurable to avoid starvation under
|
||||
continuous editing. These are starting values, not measured tuning results.
|
||||
4. Capture watermark N and process bounded batches (initial target: 200 Paths,
|
||||
short transactions). Persist derived changes and progress together. Reconcile
|
||||
current state; do not replay stale rename payloads as commands. Recheck source
|
||||
generation before publishing a completed snapshot.
|
||||
5. Acknowledge only processed N. If desired advanced while queued/running, enqueue
|
||||
a successor **after the active job finishes**, or let the dispatcher do so.
|
||||
Current active-key queue deduplication must not acknowledge/drop newer edits.
|
||||
6. Retries are idempotent; unchanged data does not increment topology version.
|
||||
Keep itemized conflicts/cursors. Queue-full, pause, crash and cancellation
|
||||
preserve pending invalidations and unprocessed events.
|
||||
7. `city.reconcile.sweep` is a fair, bounded recovery pass across Domains using
|
||||
the same algorithm. Compact outbox only after consumers' checkpoints/retention
|
||||
requirements allow it.
|
||||
|
||||
Use existing `/_/api/v1/event/` and `/_/api/v1/queue` definitions, trigger, job and
|
||||
log mechanisms. Proposed City event types are **not registered yet**. When POST
|
||||
`/city/autoplan` becomes asynchronous, return `202` with a job UUID and update
|
||||
its UI simultaneously. Dry-run needs bounded results and a base/rule-version
|
||||
token; stale approval must not silently apply a newly recomputed plan.
|
||||
|
||||
Settings are Domain-scoped. Existing Domains start manual; enable URL-auto after
|
||||
an adoption preview. New-Domain URL-auto defaults can follow once gates pass.
|
||||
Manual/scheduled triggers share settings and permission checks. Workers may
|
||||
mutate derived City state only, not arbitrary Pages using an administrator token.
|
||||
|
||||
Use low priority, one City writer per Domain, shared preview/import resource
|
||||
budgets, cancellation and backoff. Keep geometry out of write transactions and
|
||||
request handling. This is single-writer operation: current startup requeue of
|
||||
all running jobs is not an HA lease; multi-instance workers require fencing.
|
||||
|
||||
## Geometry and read scalability
|
||||
|
||||
- Fabric key = Domain UUID + explicit seed + generator/version/options. Ordinary
|
||||
edits and topology increments must not change the seed.
|
||||
- Layout key = fabric + structural/membership generation + layout version;
|
||||
metadata/policy generations are separate. Preserve prior assignments with
|
||||
bounded growth/shrink hysteresis to avoid global rearrangement for one Page.
|
||||
- Build a connected road graph, clip at Quartier boundaries, allocate fairly,
|
||||
project anchors onto bounded segments. Keep every locality pickable with
|
||||
explicit fallback/capacity warnings when geometry is scarce.
|
||||
- Deduplicate weights at every level; leave unoccupied space when membership
|
||||
is small. Use zoom-dependent labels/aggregation for dense points.
|
||||
- Worker generates/allocates with size/time/cancellation limits; viewport/zoom
|
||||
bounds main-thread rendering separately. Superseded results cannot replace
|
||||
newer views. Remove observer-driven placement repair after regression tests.
|
||||
- Top-level API returns Quartier summaries, not every descendant Page. Lazy
|
||||
bounded Street/Spot/Page APIs use bulk queries, snapshots and cancellation.
|
||||
- Cache authorized models by Domain, principal/policy and data generation with
|
||||
private HTTP validators. Invalidate on logout/policy change; don't put restricted
|
||||
labels/coordinates in a shared origin-wide cache. Topology-independent fabric
|
||||
can be cached separately. Remove unused `city-geometry.js` storage work.
|
||||
- During regeneration keep the last valid authorized map, with a small status
|
||||
icon. Failures provide a directory fallback/retry, never block Page navigation.
|
||||
|
||||
## Compact UI and keyboard contract
|
||||
|
||||
- Toolbar: breadcrumbs, search, zoom/reset, add icon, settings icon. Generation
|
||||
status tooltip links to details and existing job monitor, not verbose inline text.
|
||||
- Add opens one modal for Quartier/Street/Spot with contextual parent/Path defaults
|
||||
and ancestry/conflict validation. Page bindings/relations use the same modal
|
||||
shell. Preserve inputs on failure, prevent duplicate submits and scope parents.
|
||||
- Settings modal: manual/URL-auto, adoption preview, rules/exclusions, event timing
|
||||
and explicit regeneration. Changing fabric seed is a separate confirmed action.
|
||||
- Accessible icon names/tooltips, adequate hit areas, visible focus, Japanese and
|
||||
English strings, trapped/restored modal focus. Escape closes innermost overlay
|
||||
before outer map popup. No global form-input shortcuts.
|
||||
|
||||
| Key, only while map navigation is focused | Action |
|
||||
| --- | --- |
|
||||
| Arrows; W/A/S/D; K/H/J/L | Focus nearest visible selectable node up/left/down/right, without activation. |
|
||||
| Enter / Space | Open locality or activate Spot portal/Page, matching click behavior. |
|
||||
| Backspace | Parent City level, without leaving the page. |
|
||||
| `+` / `-`; `0` | Zoom in/out; reset viewport. |
|
||||
| Shift+F10 / Context Menu | Context menu on focused node. |
|
||||
| Escape | Close menu/modal/map popup from inside outward. |
|
||||
| Tab / Shift+Tab | Native accessible traversal, roving tab stop within map nodes. |
|
||||
|
||||
Do not intercept input/textarea/select/contenteditable, IME or Ctrl/Alt/Meta
|
||||
shortcuts. Pointer drag pans; directional keys navigate nodes, with defined
|
||||
offscreen/empty-view fallback. Refresh preserves selection/zoom; deletion falls
|
||||
back to nearest valid parent. Guard async inspector/load responses by selection
|
||||
and request generation, and cancel obsolete requests.
|
||||
|
||||
Locality history is an in-memory stack, not a browser entry for each movement.
|
||||
Existing back/forward buttons invoke browser history; they cannot provide
|
||||
per-locality traversal without entries. Provide distinct map back/forward
|
||||
controls instead of pretending these two requirements are equivalent.
|
||||
|
||||
## Delivery and acceptance checklist
|
||||
|
||||
1. [ ] **CITY-A — correctness gate**: denied descendants, literal Paths, scoped
|
||||
names/links, shallow/portal rules, source-aware idempotent plan/apply.
|
||||
2. [ ] **CITY-B — durable events**: outbox and watermarks, consumer, CLI/import/
|
||||
adapter coverage, concurrent-edit/rollback/retry tests, manual/scheduled/auto UI.
|
||||
3. [ ] **CITY-C — responsive map**: stable seed/cache, Worker, connected allocation,
|
||||
capacity fallbacks, lazy authorized reads and continuity/stale-result tests.
|
||||
4. [ ] **CITY-D — compact navigation**: icons/modals, keyboard/i18n/focus/history,
|
||||
popup and error recovery browser tests.
|
||||
|
||||
CITY-C/D may proceed independently of CITY-B once CITY-A's read/identity
|
||||
contracts are established. Do not enable automatic production reconciliation
|
||||
before CITY-A/B pass. Main-roadmap P0 authentication work remains open.
|
||||
|
||||
Fixtures: 500 / 5,000 / 50,000 Paths, aliases, many tiny Streets, one crowded
|
||||
Street, virtual folders, repeated names, `%`/`_`/Unicode, manual/archived mappings,
|
||||
denied descendants, rename/edit during generation, crash/queue-full/retry/cancel.
|
||||
Record API p50/p95, response size, query count, SQLite write-lock duration,
|
||||
generation CPU/memory and browser long tasks before fixing production budgets.
|
||||
|
||||
Audit checks performed locally:
|
||||
|
||||
- Passed existing tests: `GOCACHE=/tmp/pageswiki-go-cache go test
|
||||
./internal/store ./internal/server -run 'TestCity|Test.*City|Test.*Topology'
|
||||
-count=1`. These do not cover all findings above.
|
||||
- Ran the checked-in gen-city bundle in a Node VM three times, seed key
|
||||
`audit-city:1`, dimensions 240×160. Synchronous call times: about 39/32/29 ms;
|
||||
259 roads and 279 buildings each. A zero-delay timer did not run before
|
||||
generation completed. This supports the source finding of synchronous work,
|
||||
not a browser/production latency benchmark.
|
||||
- No live DB mutation, schema migration, runtime/UI change or deployment in
|
||||
this audit.
|
||||
@@ -0,0 +1,76 @@
|
||||
# City generation Worker and directional navigation
|
||||
|
||||
Implemented bounded CITY-C/D slice, 2026-09-14. Preserves the generated fabric
|
||||
and [courtyard projection](city-immersive-map.md); this does not replace the
|
||||
server topology/reconciliation work in [the City audit](city-review-and-reconciliation.md).
|
||||
|
||||
## Generation and lifecycle
|
||||
|
||||
`city-generator-client.js` retains the asynchronous `PagesWikiGenCity` facade,
|
||||
but the generator bundle is no longer loaded into the main document. A local
|
||||
`city-generator-worker.js` imports the rebuilt gen-city 1.4.6 bundle and returns
|
||||
only numeric roads/building polygons. Its synchronous internals therefore cannot
|
||||
block browser input or navigation. The Worker is terminated when finished, on
|
||||
abort/supersession, on page suspension, or after a 5-second deadline. There is
|
||||
one active generation job per map/client. Same-key requests share the job.
|
||||
|
||||
Inputs are limited to a 256-character stable Domain key and integer dimensions
|
||||
64–320 by 64–240 (the map requests 240 by 160). The adapter and Worker enforce
|
||||
these bounds; returned geometry is limited to 4,096 roads, 4,096 buildings and
|
||||
16 finite vertices per building. The main-thread deadline can kill runaway
|
||||
synchronous Worker code without waiting for it to process a cancellation message.
|
||||
|
||||
The base seed is the Domain UUID, not a topology version or membership count.
|
||||
Geometry-only caches use the generator/layout version, Domain UUID and dimensions
|
||||
as their key. Memory and sessionStorage each retain at most three fabrics; a
|
||||
serialized storage entry must fit 512 KiB. Storage denial, quota exhaustion and
|
||||
corruption do not disable generation. No Page names, Paths, grants, topology
|
||||
or principal information are cached here. Authorized API results remain separate.
|
||||
|
||||
The map aborts superseded fetches and discards late render responses. `pagehide`
|
||||
cancels fetch/generation; BFCache `pageshow` reloads the authorized model and
|
||||
reuses valid geometry. An unsupported/blocked Worker, timeout or malformed result
|
||||
shows a retry action and error without executing gen-city synchronously as a
|
||||
fallback. Utility menus remain usable; this is not a claim that the map works
|
||||
without Workers. The SVG exposes its busy state to assistive technology.
|
||||
|
||||
## Keyboard interaction
|
||||
|
||||
`city-navigation.js` handles directional focus over currently visible Quartier,
|
||||
Street, Spot entry, Page/portal links and overflow controls:
|
||||
|
||||
- Arrow keys, WASD and HJKL choose the nearest useful candidate in the requested
|
||||
screen-space direction; there is no arbitrary wrap across the map.
|
||||
- Enter/Space activates the focused element. Repeated activation keydown is
|
||||
suppressed to avoid drilling through multiple levels while a key is held.
|
||||
- Backspace moves to the parent locality and restores the former child's focus.
|
||||
At the Domain level it stays in the map. It never calls browser back/history.
|
||||
- Ctrl/Command/Alt shortcuts, IME composition, editable fields, controls outside
|
||||
the map, open modals and context menus are not consumed. Ctrl selection and
|
||||
existing dialogs continue to work. Escape remains available to the containing
|
||||
popup/menu rather than being repurposed for hierarchy navigation.
|
||||
|
||||
The existing mouse, semantic Page hrefs, popup top-window Page navigation,
|
||||
horizontal labels and courtyard design are unchanged. Navigation changes local
|
||||
view state only; actual Page links still navigate normally.
|
||||
|
||||
## Verification and remaining limits
|
||||
|
||||
Opt-in Chromium tests run in normal and popup modes with the real Worker and
|
||||
real gen-city output. They cover stable repeated seeds, a deliberately busy
|
||||
Worker while main-thread timers keep running, timeout/abort/supersession,
|
||||
stale messages, storage bounds, invalid results and pagehide/BFCache resumption.
|
||||
Keyboard tests cover all key families, semantic Page activation, focus restoration,
|
||||
modifier/IME/editing/modal exclusion and unchanged URL/history. Existing label,
|
||||
organization, immersive/pagination and mobile-light-theme fixtures still pass:
|
||||
|
||||
```sh
|
||||
PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run 'TestCity(Labels|Organizer|Immersive|Keyboard|Worker)Chromium' -count=1
|
||||
```
|
||||
|
||||
This isolates base-fabric generation, not all City work. Topology-to-road
|
||||
allocation, SVG DOM construction and loaded directory/inspector options remain
|
||||
on the main thread. Connected road allocation, lazy locality projections and
|
||||
larger-scale DOM virtualization remain separate tasks. A future server-side
|
||||
geometry cache could share work across tabs/devices; no cross-tab worker pool
|
||||
or server generation scheduler is introduced here.
|
||||
@@ -0,0 +1,194 @@
|
||||
# Configuration panels, bookmarks, and resource charts
|
||||
|
||||
Resource history is now collected by a built-in background event, not by an
|
||||
open browser. The current persistence, retention and extension-catalog design
|
||||
is specified in [System extensions](system-extensions.md); it supersedes the
|
||||
earlier in-memory live-sampling description below.
|
||||
|
||||
Bookmark sections and direct home-page management are specified in
|
||||
[Home navigation and hosted Vim](home-bookmark-sections-vim.md). The flat
|
||||
bookmark representation below remains compatible; section rows extend it.
|
||||
|
||||
## 設定画面の構成
|
||||
|
||||
`/-/sys/config?panel=<id>` を共通シェルとする。`config_panels.go` の
|
||||
サーバー所有レジストリがグループとパネルIDを定義する。
|
||||
|
||||
| グループ | パネルID |
|
||||
| --- | --- |
|
||||
| 表示・ナビゲーション | `home`, `editor`, `bookmarks`, `nav-home`, `nav-system` |
|
||||
| コンテンツ | `objects`, `assets` |
|
||||
| 認証・アクセス | `auth`(アカウント), `auth-providers`, `auth-sessions` |
|
||||
| キャンパス・ドメイン | `campuses`, `domains` |
|
||||
| 連携アダプタ | `adapters`, `adapters-builtin`, `adapter-<plugin-id>` |
|
||||
| 運用 | `scheduler`(実行状態・リソース), `logs`(実行履歴・ログ), `events`, `queue` |
|
||||
|
||||
選択グループを展開し、他グループは折りたたむ。各summaryは手動でも開閉可能。
|
||||
サイドバー全体を閉じた場合は本文の幅も広げる。小画面は縦並びとする。
|
||||
パネル選択をURLに反映するため再読み込み/直接リンクで同じパネルを開ける。
|
||||
既存の `panel=nav` は `nav-home` として扱う。
|
||||
|
||||
共通CSSは `/static/css/config.css`、遷移・APIエラー処理・グラフは
|
||||
`/static/js/config-panels.js`。チェックボックスはネイティブinputを残した
|
||||
`role=switch` とし、labelの `data-label` をCSSの `attr(data-label)` で表示する。
|
||||
inputにも翻訳済み `aria-label` を付け、キーボード操作・disabled・フォーム所属・
|
||||
送信値を保持する。秘密情報は既存のpassword入力と空欄時保持の契約に従う。
|
||||
|
||||
## スケジューラの情報分離
|
||||
|
||||
- 実行状態: 件数、直近25ジョブ、再試行/キャンセル、プレビュー生成の手動トリガー。
|
||||
- イベント: 実施タイミング、次回実行、追加/実行/削除。周期と日時は選択した
|
||||
スケジュール方式に対応する項目だけ表示。優先度・試行回数・JSONは詳細設定に置く。
|
||||
- キュー: 一時停止、並列数、キュー深度、リトライ待ち時間、履歴保持。
|
||||
- ログ: 直近50件の実行ログ。
|
||||
- リソース: 下記のライブグラフ。
|
||||
|
||||
従来はスケジューラを開くと4種類のAPIをまとめて取得していた。現在は選択した
|
||||
パネルで必要なAPIだけ取得し、遷移時に中止する。定期取得はリソースパネルに限定。
|
||||
設定フォームを定期更新で上書きしない。APIの非JSONエラーも本文/ステータスとして
|
||||
表示し、JSON構文エラーで本来のエラーを隠さない。
|
||||
|
||||
## アセット一覧の障害と是正
|
||||
|
||||
報告: `Unexpected token 'o', "forbidden: "... is not valid JSON`。
|
||||
原因はGETがendpoint policyに登録されていなかったこと。POST/DELETEの登録により
|
||||
同じエンドポイントがmethod-closedになり、一覧GETが認可ハンドラに到達する前に
|
||||
拒否されていた。GET/POST/DELETEは型付きpolicyからアセット管理ハンドラへ渡し、
|
||||
現行のキャンパス/ドメイン管理者権限をハンドラで検証する。
|
||||
|
||||
調査時の `asset:image:profile` は、HEAD、履歴、実ファイルSHA-256が一致し、
|
||||
記録サイズ・実サイズともに2,627バイトだった。データを削除・再生成する必要はない。
|
||||
|
||||
あわせて以下を是正した。
|
||||
|
||||
- 参照数を「同一ドメインにPathを持つ参照元Revisionの異なり数」に統一。
|
||||
過去HEADと現在HEADを含める。詳細はPath別の行を返すため、同じRevisionの
|
||||
別名Pathがある場合の行数は参照数と一致するとは限らない。
|
||||
- HEAD履歴がない旧データも、現在HEADから依存関係を取得可能にした。
|
||||
- 更新/削除は書き込みSQLでも期待HEADを比較し、競合を検出する。
|
||||
- 同じバイト列でもMIME/ファイル名を変えた場合はメタデータと履歴を更新する。
|
||||
- CLIのアセット書き込みもMIME、ファイル名、サイズ、履歴を同一トランザクションで更新。
|
||||
- 一覧APIは `no-store`。画面はテキスト形式の拒否応答も読み取れる。
|
||||
|
||||
HEADハッシュのETagはバイト列の識別子である。メタデータだけの同時更新を厳密に
|
||||
区別するには将来、Asset状態バージョンを含めた条件付き更新契約が必要。
|
||||
|
||||
## ブックマークマネージャー
|
||||
|
||||
`panel=bookmarks` でドメイン共通のブックマークを最大64件管理する。
|
||||
行には名前、指定方法(Path / URL)、宛先、上下移動、削除を用意する。
|
||||
保存時に管理者権限を検証し、入力が不正なら保存済み一覧を変更しない。
|
||||
|
||||
既存の `home_bookmarks` JSONを継承し、`kind` を任意追加する。
|
||||
|
||||
```json
|
||||
[{"label":"Docs","kind":"path","href":"/docs"},
|
||||
{"label":"External","kind":"url","href":"https://example.com/"}]
|
||||
```
|
||||
|
||||
Pathはドメインルート相対の意味を持ち、URL化するときに空白・%・Unicodeを
|
||||
適切にエスケープする。URLはHTTP(S)またはルート相対URLを許可し、JavaScript、
|
||||
プロトコル相対URL、資格情報を含むURLは拒否する。ローカルの宛先は表示時にも認可する。
|
||||
ホーム設定の保存ではブックマークを更新せず、別パネルの保存で消える事故を防ぐ。
|
||||
現在は「検索+ブックマーク」のホームに反映し、共通サイドバー実装時に同じデータを使う。
|
||||
個人ブックマーク、フォルダ分類、UUID追従型ブックマークは将来の別拡張とする。
|
||||
|
||||
## 設定テーブルの表示密度
|
||||
|
||||
設定画面の `.recent-table` / `.config-form-table` に限定して行の余白を圧縮する。
|
||||
セルの上下paddingは0.22rem、行内コントロールは高さ1.8rem、セル内フォームの外余白は0。
|
||||
空のform要素は表示しないが、form IDを用いた行内入力・保存/削除との関連付けは維持する。
|
||||
名前と識別子を1行にまとめ、通常セルは折り返さず、幅不足はテーブル領域内で横スクロール。
|
||||
長いPath・ファイル名・URL・補足説明は全文をDOMとtitleに残した省略表示とする。
|
||||
ログ展開行とその本文は例外として複数行表示を保つ。Viewer/Editorなど他画面のテーブルには適用しない。
|
||||
|
||||
## リソースグラフ
|
||||
|
||||
`scheduler` パネルはhtop型の監視画面とし、上部に現在値と4つのグラフ、下部に
|
||||
実行中ジョブのみを表示する。旧 `panel=resources` は `scheduler` の別名として維持。
|
||||
収集設定・表示期間・自動更新・指標の説明は、タイトル横の歯車から開くネイティブdialogに
|
||||
まとめる。閉じるボタン・Escape・背景クリックで閉じ、歯車へフォーカスを戻す。
|
||||
別パネルへの移動時も閉じる。表示設定は即時反映し、同一originのlocalStorage
|
||||
`pageswiki.monitor.display.v1` に期間・自動更新ON/OFF・現在値とグラフの更新間隔を保存。
|
||||
初期値は1時間・自動更新ON・現在値1秒・グラフ5秒。保存された期間があれば優先する。
|
||||
不正な値は使わず、storage利用不可でも既定値で動作する。収集設定は保存操作でDBへ永続化。
|
||||
時間範囲はタイトル直下に1つだけ表示し、各グラフの時間ラベル・表示点数は出さない。
|
||||
更新操作はリロードアイコン、設定は歯車。履歴へのリンクはサイドバーに集約する。
|
||||
グラフは常に1行4列。狭い画面ではグラフ領域内だけ横スクロールし、2列/1列へ折り返さない。
|
||||
|
||||
`GET /_/api/v1/queue/resources` の現在値と `GET /_/api/v1/queue/jobs?status=running&limit=100`
|
||||
を既定1秒間隔で取得する(要求完了後に次を予約し、重複実行しない)。実行中の絞り込みはLIMITより前にDBで行い、最近終了した
|
||||
ジョブに長時間実行ジョブが埋もれない。ワーカー上限32に対し表示上限100。
|
||||
現在値のキュー統計はstatus索引で待機・実行中だけを集計し、完了履歴を全走査しない。
|
||||
グラフは既定5秒ごとに、現在値から得たライブサンプルを履歴へ重ねて描画する。
|
||||
両間隔は1〜60秒で設定可能。グラフ間隔は現在値の間隔以上に補正する。
|
||||
永続履歴APIの再取得は30秒ごとに抑え、期間変更と手動更新時は即時再取得。
|
||||
ライブバッファも描画も最大361点。I/O速度は間引き前に計算し、時間バケットの最終値を描く。
|
||||
ブラウザ内ライブサンプルはDBへ書き戻さず、再起動後は永続サンプルから復元する。
|
||||
バックグラウンド収集は引き続きビルトイン
|
||||
`resource.sample` イベントで行い、画面を閉じても7日間保持する。
|
||||
詳しい収集契約は [システム拡張](system-extensions.md) を参照。
|
||||
パネルを離れる、タブが非表示になる、自動更新を止める場合は定期取得を停止する。
|
||||
取得中リクエストはAbortControllerで中止し、古い結果が再表示しないよう世代を管理する。
|
||||
|
||||
グラフはテーマの色を使ったSVGで、外部ライブラリ/CDN不要。
|
||||
|
||||
### 実行履歴とログ
|
||||
|
||||
`logs` パネルにジョブと実行ログを統合。既定は終了状態
|
||||
(succeeded/skipped/failed/cancelled)、待機・個別状態のフィルタも用意する。
|
||||
`GET /_/api/v1/queue/jobs?status=history&limit=50&cursor=...` のkeysetページングで
|
||||
50件ずつ置換し、DOMへ無制限に追記しない。順序は投入時刻降順+UUID降順。
|
||||
完了状態用partial indexを指定し、SQLiteが状態別索引のIN検索後に保持履歴全体を
|
||||
一時ソートする計画を避ける。ジョブpayloadは一覧SQLでも応答でも読み出さない。
|
||||
新しいジョブへは更新ボタンで戻る。cursorは位置を表すのみで認可は毎要求再検査する。
|
||||
ログはジョブの展開時だけ `/_/api/v1/event/logs?job_uuid=...&limit=100` で取得。
|
||||
以前のログは `before_id` で100件ずつ置換する。内容はHTMLではなくテキストとして表示。
|
||||
実行中のキャンセル、失敗等の再試行を維持する。終了した実行中行は次回更新で消える。
|
||||
実行状態は秒数・試行数を示すが、ジョブ別のCPU/RSS計測や進捗率を捏造しない。
|
||||
|
||||
| 指標 | 意味 |
|
||||
| --- | --- |
|
||||
| CPU | ホストの1分ロードアベレージ。CPU使用率ではない |
|
||||
| メモリ | このGoプロセスのheap bytes |
|
||||
| I/O | PagesWikiプロセスの読み込み・書き込み速度(B/s)。2系列で表示 |
|
||||
| キュー負荷 | 待機ジョブ数+実行ワーカー数 |
|
||||
|
||||
これらはドメイン別ではなくインスタンス/ホスト単位の指標。
|
||||
ディスク容量は現在値カードに残し、グラフの1枠はI/Oに使う。I/Oの計測範囲と制約は
|
||||
[システム拡張の監視仕様](system-extensions.md#ディスクio)を参照。
|
||||
コンテナCPU制限・RSS・cgroup使用率・複数インスタンス・長期保管は将来の
|
||||
監視プロバイダ拡張として別API/保持方針を設計する。
|
||||
|
||||
## アダプタ個別パネルの拡張契約
|
||||
|
||||
現行プラグインは `adapter-<id>` に個別パネルを持ち、共通partialで接続先・
|
||||
対応MIME/拡張子、有効化、別タブ、既定エディタ、HTML/Markdown変換を編集できる。
|
||||
旧 `/-/sys/config/adapters?id=...` のGETは統合パネルへリダイレクトする。
|
||||
保存も同じパネルに戻り、ドメイン別の既存プラグイン設定へ保存する。
|
||||
|
||||
将来のアダプタ固有項目は次の契約で追加する。
|
||||
|
||||
1. サーバーが信頼するmanifestに `settings_schema_version` と複数のパネル定義を登録。
|
||||
定義は `id`, `title_key`, `group`, `fields` とし、フィールドはboolean、text、
|
||||
enum、number、secretの許可リストから選ぶ。現行partialがその最初の実装。
|
||||
2. 保存先は `(domain_uuid, adapter_id, schema_version)` で区切る。バリデーションと
|
||||
schema移行はサーバー所有。未定義キーは拒否し、秘密値は読み出しレスポンスに含めない。
|
||||
3. 特殊UIが必要な場合のみ、サーバー登録済みの専用partial/モジュールを使う。
|
||||
プラグインやドキュメントから任意HTML/JavaScriptを設定画面に挿入しない。
|
||||
4. 外部設定画面の埋め込みが必要な場合は、別途sandbox iframeと固定originの
|
||||
postMessage契約を設計する。通常ログインCookie/Bearerをiframeへ渡さない。
|
||||
5. アダプタ固有の接続確認・秘密管理・長い検証処理は個別APIとイベントへ分離。
|
||||
|
||||
汎用schema rendererと外部設定iframeは未実装。今回の共通シェル・レジストリ・
|
||||
アダプタpartialを拡張点として使用する。
|
||||
|
||||
## 検証
|
||||
|
||||
- 管理者のAsset GETが成功し、一般ユーザーのGETが拒否されるHTTP回帰テスト。
|
||||
- 参照数のドメイン分離、旧HEAD参照、同一バイト列のメタデータ訂正。
|
||||
- ブックマーク保存/不正URL拒否、アダプタ個別設定の保存と戻り先。
|
||||
- 設定HTMLの重複ID、メニューの未定義パネル、inline JavaScriptの構文検証。
|
||||
- Chromiumでassets/events/queue/resources/bookmarks/adapter個別パネルを確認。
|
||||
`PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run TestConfigChromiumSmoke`
|
||||
- CLI: `python3 -m unittest discover -s data -p test_cli_assets.py`。
|
||||
@@ -0,0 +1,183 @@
|
||||
# Data CLI
|
||||
|
||||
`data/pageswiki-cli` is a local administrative data surface. It provides
|
||||
rsync-like one-shot transfers and an interactive Semantic Path shell.
|
||||
|
||||
It accesses:
|
||||
|
||||
- metadata in `pages.db`;
|
||||
- immutable payloads in `documents/sha256/`;
|
||||
- mutable Asset HEAD metadata in `assets`.
|
||||
|
||||
The implementation uses Python's standard library only.
|
||||
|
||||
## Invocation modes
|
||||
|
||||
### One-shot
|
||||
|
||||
```bash
|
||||
data/pageswiki-cli get path:/manual/start start.html
|
||||
data/pageswiki-cli put start.html path:/manual/start
|
||||
```
|
||||
|
||||
Transfers compare SHA-256 before writing. Identical content is reported as
|
||||
`skipped` and does not create another Revision.
|
||||
|
||||
### Interactive shell
|
||||
|
||||
```bash
|
||||
data/pageswiki-cli shell
|
||||
```
|
||||
|
||||
Invoking without arguments also opens the shell when stdin is a terminal.
|
||||
The shell maintains a Semantic Path working directory:
|
||||
|
||||
```text
|
||||
pages:/> cd /manual
|
||||
pages:/manual> ls
|
||||
pages:/manual> view start
|
||||
```
|
||||
|
||||
The shell uses `readline` when available:
|
||||
|
||||
- Up/Down traverse command history.
|
||||
- Tab completes commands, Semantic Paths, UUIDs, Revisions, Assets, and local
|
||||
transfer paths.
|
||||
- History persists in `~/.pageswiki_history`, or the path specified by
|
||||
`PAGESWIKI_HISTORY`.
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Behavior |
|
||||
| --- | --- |
|
||||
| `ls [PATH]` | List direct Semantic Path children |
|
||||
| `cd PATH` | Change shell Semantic Path |
|
||||
| `mv SOURCE DEST` | Move a Path and its descendants transactionally |
|
||||
| `view [ADDRESS]` | Display metadata and send payload to `PAGER` on a TTY |
|
||||
| `cat [ADDRESS]` | Write only the canonical payload to stdout |
|
||||
| `edit [ADDRESS]` | Edit through `EDITOR` and write back changed content |
|
||||
| `get ADDRESS [LOCAL]` | Download one payload |
|
||||
| `put LOCAL ADDRESS` | Upload a Page Revision or update an Asset HEAD |
|
||||
| `mget REMOTE_PATTERN [DIR]` | Download matching Semantic Paths |
|
||||
| `mput LOCAL_GLOB REMOTE_DIR` | Upload matching local files |
|
||||
| `revision [ADDRESS]` | List a Page's immutable Revision history |
|
||||
| `diff REV REV` | Produce a unified Document diff |
|
||||
| `restore REV` | Create a new Revision from an old Revision |
|
||||
| `link ADDRESS PATH` | Add a Semantic Path projection |
|
||||
| `unlink PATH [ADDRESS]` | Remove a Path projection only |
|
||||
| `pwd` | Show the shell Semantic Path |
|
||||
|
||||
`put` and `mput` infer a Revision Content-Type from the local filename, with
|
||||
the destination Semantic Path as a fallback. Markdown input is converted to
|
||||
canonical HTML and loses only its `.md` / `.markdown` Semantic Path suffix.
|
||||
Other extensions remain part of the Path. Binary payloads are stored as
|
||||
immutable Documents and retain their original filename and Content-Type.
|
||||
| `help` | Show usage |
|
||||
| `exit`, `quit` | Leave the shell |
|
||||
|
||||
`get ADDRESS -` writes to stdout and `put - ADDRESS` reads from stdin.
|
||||
Unlike `view`, `cat` never invokes a pager and is suitable for pipelines.
|
||||
|
||||
## Supported addresses
|
||||
|
||||
| Address | Meaning |
|
||||
| --- | --- |
|
||||
| `path:/...` | Mutable Semantic Path projection |
|
||||
| `uuid:<uuid>` | Stable Page/Object identity |
|
||||
| `rev:<uuid>` | Immutable Revision identity |
|
||||
| `asset:<type>:<name>` | Mutable Asset HEAD |
|
||||
|
||||
A single address without a command retains the earlier inspection behavior.
|
||||
|
||||
## Write semantics
|
||||
|
||||
### Page `put`
|
||||
|
||||
1. Resolve `path:` or `uuid:`.
|
||||
2. Create a Page UUID and Path binding if a Path does not exist.
|
||||
3. Hash the input and atomically persist its immutable Document.
|
||||
4. Compare with the newest Revision in `PAGESWIKI_LANG`.
|
||||
5. Skip identical content or create a new Revision UUID.
|
||||
|
||||
Page payloads must be UTF-8. Binary data belongs in an `asset:` address.
|
||||
|
||||
### Asset `put`
|
||||
|
||||
1. Hash and atomically persist arbitrary bytes.
|
||||
2. Create the Asset identity if absent.
|
||||
3. Skip an identical HEAD or update `head_document_hash`.
|
||||
|
||||
### `edit`
|
||||
|
||||
1. Resolve the current canonical payload.
|
||||
2. Write it to a private temporary file.
|
||||
3. Invoke the command in `EDITOR`.
|
||||
4. Apply Page or Asset `put` semantics when the editor exits successfully.
|
||||
5. Skip unchanged content and remove the temporary file.
|
||||
|
||||
Immutable `rev:` addresses cannot be edited.
|
||||
|
||||
### `mv`
|
||||
|
||||
- Semantic root cannot be moved.
|
||||
- A destination cannot be inside its source.
|
||||
- Every destination is collision-checked before mutation.
|
||||
- A unique temporary namespace avoids primary-key collisions.
|
||||
- All Path updates commit in one SQLite transaction.
|
||||
|
||||
### `restore`
|
||||
|
||||
Restore never rewrites history. It reads the selected immutable Revision and
|
||||
creates a new Revision on the same Page with the same language.
|
||||
|
||||
### `link` and `unlink`
|
||||
|
||||
These commands mutate reachability only. They never delete the Page,
|
||||
Revisions, or Documents. An unlinked Page may become a zombie and remains
|
||||
recoverable by UUID until garbage collection.
|
||||
|
||||
## Consistency and safety
|
||||
|
||||
- SQLite writes use explicit transactions and a busy timeout.
|
||||
- The CLI initializes the additive `assets` table when absent; core schema
|
||||
migrations remain owned by the server.
|
||||
- Documents use temporary files, `fsync`, and atomic replacement.
|
||||
- Payload hashes are verified on every read.
|
||||
- Revision addresses reject writes.
|
||||
- rsync-like transfers skip identical hashes.
|
||||
- Missing canonical Documents may use the transitional SQLite body only when
|
||||
its SHA-256 matches.
|
||||
|
||||
This CLI is a trusted local administrative interface and intentionally bypasses
|
||||
future HTTP Capability evaluation. Filesystem and database permissions define
|
||||
who may use it.
|
||||
|
||||
## Environment
|
||||
|
||||
| Variable | Meaning |
|
||||
| --- | --- |
|
||||
| `PAGESWIKI_DATA_DIR` | Directory containing `pages.db` and `documents/` |
|
||||
| `PAGESWIKI_DB` | Explicit SQLite path |
|
||||
| `PAGESWIKI_DOCUMENTS_DIR` | Explicit Document root |
|
||||
| `PAGESWIKI_LANG` | Language used for selection and Page writes |
|
||||
| `PAGER` | Pager invoked by `view` on an interactive terminal |
|
||||
| `EDITOR` | Editor invoked by `edit` |
|
||||
| `PAGESWIKI_HISTORY` | Interactive command-history file |
|
||||
|
||||
## Asset metadata
|
||||
|
||||
The normative Asset lifecycle and authorization model are defined in
|
||||
[`asset-model.md`](asset-model.md). The CLI is a trusted local implementation
|
||||
of HEAD reads and updates, not the public Asset API.
|
||||
|
||||
| Column | Meaning |
|
||||
| --- | --- |
|
||||
| `domain_uuid` | Domain containing the mutable Asset name |
|
||||
| `address` | Canonical Domain-local `asset:` address |
|
||||
| `object_uuid` | Stable owning Object UUID |
|
||||
| `head_document_hash` | Current immutable Document snapshot |
|
||||
| `created_at_ms` | Creation timestamp |
|
||||
| `updated_at_ms` | HEAD update timestamp |
|
||||
|
||||
Administrator HTTP Asset mutation is available with Domain/Campus-admin checks
|
||||
and ETag preconditions. The CLI remains the trusted local bulk interface.
|
||||
@@ -0,0 +1,278 @@
|
||||
# 日記・ブログ:ビルトインシステム拡張
|
||||
|
||||
初期版 0.1/URL・入口拡張(2026-09-17)。MIME連携アダプタではなく、通常のWiki Pageに
|
||||
付随する日付・記事情報とナビゲーションを提供する。任意の外部コードをロードする
|
||||
プラグイン機構ではない。
|
||||
|
||||
## 実装した範囲
|
||||
|
||||
| | 日記 | ブログ |
|
||||
| --- | --- | --- |
|
||||
| ID | `content.diary` | `content.blog` |
|
||||
| UI | `/v/diary` | `/v/blog` |
|
||||
| 設定 | `/-/sys/config?panel=diary` | `/-/sys/config?panel=blog` |
|
||||
| 一覧 | 月別/日付別 | 日付降順、任意の月・カテゴリで絞り込み |
|
||||
| ナビゲーション | 月カレンダー、最近8件、自分の記事 | 月カレンダー、最近8件、カテゴリ、自分の記事 |
|
||||
| 登録制約 | 同日複数件可 | 同日複数件可 |
|
||||
|
||||
両方ともDomainごとに**既定無効**。Domain管理者が有効化する。無効化しても
|
||||
登録情報、Wikiページ、Revisionは削除しない。
|
||||
|
||||
「新規記事」ダイアログは日付・keyword・タイトル・カテゴリ・Markdown本文を
|
||||
まとめて保存する。既存Pageを使う場合は従来のPath指定による登録も可能。
|
||||
本文の継続編集は既存エディタ、記事情報の変更・登録解除は一覧から行う。
|
||||
|
||||
## 同一インスタンスのDomain射影(第一段階)
|
||||
|
||||
- ドメイン一覧の歯車内で日記・ブログそれぞれの参照元DomainとPath prefixを指定。
|
||||
空の参照元は従来の自Domain記事を表示する。入口形式・有効状態は上の設定で指定する。
|
||||
- `periodical_projections(domain_uuid,kind,source_uuid,prefix)`で参照のみ保持し、
|
||||
Page、Revision、Path、記事情報は複製しない。既存の表示先記事も削除しない。
|
||||
- Campus管理者による設定に限定。同じCampus(同じコントローラの管理単位)の
|
||||
有効なlocal配置Domain同士のみ許可。managed Campus上のローカル設定変更は禁止。
|
||||
自己参照・連鎖・循環を拒否し、閲覧時にも有効状態・配置・所属・連鎖を再検査する。
|
||||
- 初期射影範囲は認証済みの一覧・月/日カレンダー・カテゴリ・最近の記事・own。
|
||||
参照元・表示先の双方の読取ポリシーとprefixで絞り、件数/カテゴリ/ページ送りを
|
||||
その後に計算する。ソース権限は一括読込し、記事ごとのSQL認可問い合わせはしない。
|
||||
Source側がlegacyモードでも、射影では明示的な読取権限を要求する。
|
||||
- 匿名の場合も、設定済みのlocal射影先の `/` と `/v/{kind}/YYYY/MM[/DD]` を
|
||||
閲覧できる。参照元の現在有効な公開承認済みPath/Revisionだけから一覧・件数・
|
||||
最近の記事を構成する。日付は承認済み `{prefix}/YYYY/MM/DD[/keyword]` Path、
|
||||
**登録タイトルはPageの公開状態を継承する公開表示情報**とする(2026-09-19変更)。
|
||||
現在有効な公開承認のあるPageのタイトルだけをJOINで取得し、タイトル変更は
|
||||
次の要求で反映する。カテゴリ・著者・登録日付は公開しない。タイトル未登録なら
|
||||
最新20記事に限り承認済みHTMLのh1を64KiB以内で読み、なければ日付/Path末尾。
|
||||
不正/期限切れの認証情報は匿名へ降格しない。公開変更/失効は次の要求で反映する。
|
||||
記事本文の公開権限を増やさず、未承認の最新Revisionを公開しない。
|
||||
- 表示先の認証セッションでPrincipalを特定する。参照元の同じPrincipalに読取権限が
|
||||
必要。クロスサブドメインCookie共有やセッションの暗黙継承は実装しない。
|
||||
- 専用ドメイン(入口形式がblog/diary)では記事リンクを表示先の
|
||||
`/YYYY/MM/DD[/keyword]` とし、承認済み本文を同じホストで表示する。
|
||||
カレンダー・同月の他の記事(最大31件)・前後の記事を同じ公開集合から構成する。
|
||||
サイト名称・テーマは表示先Domainのもの。記事本文は既存のinert HTML境界を使う。
|
||||
本文中の既知の公開記事リンクも表示先へ変換し、それ以外は参照元URLを保持する。
|
||||
画像のCSPは設定済み参照元originだけ追加許可し、画像自体の公開権限は拡張しない。
|
||||
「参照元で閲覧・編集」は従来通り元FQDNへ移動する。作成・登録・更新・解除の
|
||||
APIを射影先で使うと403。Store transaction側でも射影設定を再検査して拒否する。
|
||||
- entries APIは`source_domain`・`source_origin`・`projection`を付加する。
|
||||
Path/Page UUIDは参照元のもの。日付ナビゲーションは表示先の `/v/{kind}/...`。
|
||||
日付既定値は参照元Timezone、テーマ・名称は表示先Domainの設定。
|
||||
- 一覧は毎回DBから読み、`private, no-store`。ACL失効・元記事変更は次の要求で反映。
|
||||
参照先が無効/remote配置/別Campusへ変わった場合は503で閉じ、自Domain記事への
|
||||
黙った切り替えはしない。同期や既存公開承認をこの参照設定で拡張しない。
|
||||
- この参照設定は現時点では**ローカル専用でmanifest v2には含めない**。
|
||||
別インスタンスへの参照設定配信・認証付き取得・失効・
|
||||
タイトル以外の匿名メタデータ公開・SSOは後続。従って「同じコントローラなら任意の配置先で射影」
|
||||
までを実装済みとはしない。
|
||||
- 専用ドメインの `/rss.xml` はRSS 2.0、最新20記事のタイトル・正規リンク・GUID・
|
||||
Revision日時と、`content:encoded` の安全化済み本文HTML(CDATA)を配信する。
|
||||
本文取得前に正確なRevision公開承認を再確認する。記事リンク・ページ内リンクは
|
||||
表示先の絶対URL、画像やその他の参照元リンクは元ドメインの絶対URLに変換する。
|
||||
上限は1記事1MiB入力、本文合計8MiB、生成処理5秒。上限超過は503とし、黙って
|
||||
本文を切り捨てない。HEADは本文を生成しない。非公開登録情報は含めない。絶対URLは登録FQDNから
|
||||
作り、Hostヘッダー由来のfeed汚染を防ぐ。HTMLにRSS autodiscoveryとRSSリンクを設置。
|
||||
毎回公開承認を確認し、HTTP共有キャッシュは使わない。ただし購読者が既に取得した
|
||||
RSSや本文のコピーは、公開撤回しても遠隔削除できない。
|
||||
|
||||
## 原子的な新規投稿のAPI
|
||||
|
||||
- `/v/blog/-/new`、`/v/diary/-/new` は認証必須の独立した新規記事画面。
|
||||
Domain timezoneの日付・keyword・カテゴリ・Markdown本文を既存posts APIへ送る。
|
||||
作成/Pathの権限はAPI内のtransactionで検証し、保存だけでは公開承認しない。
|
||||
未有効のプラグインは404、射影先は参照元の同ルートへ303で案内する。
|
||||
GETで記事やPathを作成せず、POSTはこの画面URLでは受けない。
|
||||
- 投稿完了画面にXのWeb Intentリンクを表示し、ユーザのクリックでのみXへ移動する。
|
||||
サーバーからの自動投稿・外部SDK・OAuth資格情報の保持は行わない。
|
||||
posts応答の`share_targets`は有効な同Campus/local射影先と入口設定から生成する。
|
||||
ブログ専用ドメインの `/YYYY/MM/DD[/keyword]` を優先し、複数なら選択式。
|
||||
射影設定があるのに利用可能な共有先がなければ、元ドメインへ黙って切り替えない。
|
||||
`published`は公開承認の検査結果。未公開なら警告とクリック時の確認を出す。
|
||||
共有操作で公開承認は変更しない。公開記事ページにはタイトル・canonical URLの
|
||||
OGP/Xカードメタデータを出す(カードの表示や更新時期は外部サービス側に依存)。
|
||||
|
||||
- `POST /_/api/v1/extension/content.{diary|blog}/posts`:`request_id`(UUID)、
|
||||
`title`、`date`、`keyword`、`category`、`body`(Markdown)。未知フィールド拒否。
|
||||
要求JSON上限320 KiB、変換後HTML上限256 KiB。ブラウザ本文入力上限131072文字。
|
||||
- prefixとTimezoneはサーバー設定を使用する。Path・Page UUID・著者の指定は不可。
|
||||
通常のMarkdownレンダラでHTML化し、通常のRevision挿入関数とasset固定処理を共有。
|
||||
- SQLite write予約後にactive membership、ローカル配置、有効状態、create/writeの
|
||||
両権限、上位Locality制限、現在のprefix、Pathの不存在を検査する。
|
||||
Page・provenance・Path・Revision・asset参照・記事情報・journal・再送receiptを
|
||||
同一transactionで確定する。既存Pathは409で拒否し、上書きしない。
|
||||
- `periodical_posts`のDomain/kind/actor/request_idと要求digestで再送を識別する。
|
||||
同じ要求は既存Page UUIDを返し、変更された要求は409。再送にも現在の権限と
|
||||
Path binding/記事登録の存続を要求し、削除後の再送で復元しない。
|
||||
- Document Storeのimmutable blobはcommit前に書き込む。DB rollback時には
|
||||
未参照blobが残り得るが、Page・Revision・Path・記事索引は可視化されない。
|
||||
未参照blob回収とreceipt保持/GCの統合は後続。プロセス内revision書込ロックを共有。
|
||||
- 本文保存は公開承認ではない。匿名の本文・記事情報・日付・件数を追加公開しない。
|
||||
- 日付付き一覧へ遷移して保存結果を表示する。ダイアログ内の入力は送信失敗時に
|
||||
保持し、同じrequest_idで再試行する。ブラウザ永続ストレージには下書きを保存しない。
|
||||
- Search/公開失効など既存DB triggerは共通Revision/Path挿入で適用される。
|
||||
City自動生成・通知への共通outbox配送は依然として後続(journalだけで配送済みとしない)。
|
||||
|
||||
## 記事URLとドメイン入口(2026-09-17)
|
||||
|
||||
- 設定画面の日記/ブログパネルにDomain・kind単位のprefixを追加。既定値は
|
||||
`/diary`・`/blog`。`/`も指定可能。設定変更は既存Pathを移動しない。
|
||||
- 「新規ページ」は日付・任意keywordを指定するダイアログを開く。
|
||||
`{prefix}/yyyy/mm/dd` または `{prefix}/yyyy/mm/dd/{keyword}` をサーバーで
|
||||
検証し、書き込み権限とPathの不存在を確認してエディタへのリンクを返す。
|
||||
日本語keyword可。keywordは単一要素とし、traversal・制御文字・URL区切りは拒否。
|
||||
- エディタを別タブで開き、本文保存後に元のダイアログから記事登録へ進む。
|
||||
この任意の従来フローは二段階操作。新規記事ダイアログでは一括保存できる。
|
||||
計画APIはPageを作成・予約しない。確認後に別の操作が同じ
|
||||
Pathを作成した場合、既存エディタはそのPageを開くため、排他的な新規作成保証は
|
||||
専用の原子的投稿APIが提供する。計画APIは自動上書き・自動登録を行わない。
|
||||
- keywordなしのPageとkeyword付きの子Pageは同日に共存可能。
|
||||
`idx_diary_owner_date`はschema初期化で削除し、既存データは保持する。
|
||||
- Domain設定のトップページ形式に日記/ブログを追加。`home_layout=diary|blog`
|
||||
は認証後の `/` で直接一覧・カレンダーを描画する。日付選択は以下のviewer Pathへ
|
||||
進む。従来の `/v/diary`・`/v/blog` は残す。既存home_pathを削除しない。
|
||||
- 配置先の表示名を「配置先」に短縮。物理的なInstance FQDN・fingerprintと
|
||||
home_layoutは別設定のままとし、別Domainの記事や権限を暗黙に共有しない。
|
||||
- 匿名公開処理は従来の承認済みPage/ディレクトリ表示を維持する。
|
||||
home_layout設定で記事メタデータを公開しない。設定済み射影の匿名カレンダーは
|
||||
上記の公開Path/Revision由来データのみで構成する。
|
||||
- Domain一覧の歯車「ドメインの入口設定」からトップページ・日記/ブログの有効状態・
|
||||
prefixを一括指定できる。配置先そのものは既存のDomain更新フォームで指定する。
|
||||
初回ダイアログは現在の設定値を引き継ぐ。保存後はこのパネルを設定の正本とし、
|
||||
homeパネル/個別プラグインの設定APIからの競合する更新を拒否する。
|
||||
|
||||
### コントローラからの配信
|
||||
|
||||
- `domain_entry_settings(domain_uuid,settings_json)`が明示的な入口設定を保持。
|
||||
Campus管理者のみ更新可能。外部キャンパス管理下ではローカル更新不可。
|
||||
設定検証・管理権限確認・保存・ローカル配置への反映は同一transaction。
|
||||
- 署名付きCampus manifestに`domain_entries`を追加。明示設定がある場合だけ
|
||||
schema_version=2を使用し、設定のない従来manifestはversion=1のままとする。
|
||||
入口設定も署名・内容hash・revision更新の対象。対象CampusのDomainのみ含める。
|
||||
- 受信時はDomainの所属・Layout列挙・prefix・選択したプラグインの有効状態を検証。
|
||||
Domain snapshot、入口設定、local配置のhome_layout/periodical設定、受信checkpointを
|
||||
同じtransactionで更新する。remote配置のDomainには実行設定を有効化しない。
|
||||
- 記事本文・記事登録・公開承認・資格情報・任意configは配信しない。
|
||||
prefix変更も記事移動を発生させない。同一revisionの再送は従来どおり冪等。
|
||||
- v2非対応ノードは同期を拒否するため、**配置先を先に更新してから**入口設定を保存する。
|
||||
enrollmentで`manifest_version=2`と専用の`capability_signature`を送信し、
|
||||
インスタンス鍵で署名した`normalized FQDN + LF + token + LF + manifest=2`を検証する。
|
||||
従来のenrollment署名も併せて必須。古いクライアントの申告なしはversion=1として扱う。
|
||||
- `federation_instance_capabilities(instance_uuid,manifest_version)`で鍵identity単位に
|
||||
能力を記録。FQDNが同一でも鍵変更は別の申告・承認が必要。
|
||||
Campus manifestは全承認済みノードに渡るため、一台でもv2未確認なら入口設定保存を
|
||||
409で拒否し、ダイアログにも案内を表示する。受信側は従来どおり署名・versionを検証し、
|
||||
設定を削ったv1へ黙ってフォールバックしない。
|
||||
- capabilityは対応機能の申告であり、稼働状態・実際の反映完了の証明ではない。
|
||||
enrollment更新時に申告がなくなればversion=1へ戻す。署名は既存enrollment同様
|
||||
token期間中のproofでありnonce付きの鮮度証明ではない。反映ACK/鮮度管理は後続。
|
||||
- manifestで設定が省略された場合は設定解除を意味しない。既存設定を保持する。
|
||||
現段階では管理を解除する操作はなく、Wiki形式への変更・各プラグインの無効化も
|
||||
入口設定パネルから明示的に行う。削除Domainの設定保持/GCは後続。
|
||||
|
||||
### 日付ナビゲーションの正規URL
|
||||
|
||||
- 月別:`GET /v/{diary|blog}/yyyy/mm`。
|
||||
- 日別:`GET /v/{diary|blog}/yyyy/mm/dd`。
|
||||
- 自分の記事:存在フラグ`?own`。カテゴリは`?category=...`、ページ送りは
|
||||
`offset`を維持する。組み合わせは`?category=Work&own`。
|
||||
- `/v/blog`は全期間、`/v/diary`はDomain timezoneの当月。
|
||||
- 旧`month`/`date`/`mine=1`は認証確認後、302で正規URLへ転送する。
|
||||
date単独でも対象月を導出する。矛盾する日付、存在しない日付、重複した日付query、
|
||||
桁数不正は400。未知のHTTPメソッドを許可せず、現段階はGETのみ。
|
||||
- カテゴリ/ownは月移動・日付選択・ページ送りで保持する。フィルタフォームの
|
||||
再適用は日付選択とoffsetをリセットし、指定月(ブログは全期間も可)から表示する。
|
||||
- 専用ドメインの `/` は入口。`/yyyy/mm/dd`は通常Pageの本文を置けるため、
|
||||
日付別一覧をそこへマウントしない。月・日への移動は`/v/{kind}/...`を使用する。
|
||||
- 新規投稿計画APIの`date`は記事作成パラメータであり、閲覧URLの日付queryとは別。
|
||||
将来のQUERY対応はTODO。現段階ではルータや認証middlewareに追加しない。
|
||||
|
||||
## データモデル
|
||||
|
||||
- `periodical_settings(domain_uuid, kind, enabled)`:Domainとプラグイン単位の有効状態。
|
||||
- `periodical_prefixes(domain_uuid, kind, prefix)`:投稿先prefix。未設定時はkind別既定値。
|
||||
- `periodical_entries(domain_uuid, kind, page_uuid, owner_uuid, local_date,
|
||||
title, category, timezone, version)`:正本はPage UUIDで参照する。Pathは保存せず
|
||||
閲覧時に現在のbindingから解決する。renameで日付・カテゴリが失われない。
|
||||
- `periodical_events(id, domain_uuid, kind, page_uuid, actor_uuid, operation,
|
||||
version, created_at_ms)`:設定/登録/解除と同一transactionで記録する変更journal。
|
||||
本文・タイトル・資格情報は複写しない。これは共通outbox配送や通知機能そのものではない。
|
||||
|
||||
本文はDocument Storeと既存Revisionにのみ保存する。登録解除はメタデータだけを
|
||||
外し、Pageを削除しない。最後のPathがなくなったPageは一覧から非表示になる。
|
||||
メタデータの孤立行のGC・完全消去・履歴保持期間は後続の保持ポリシーで扱う。
|
||||
|
||||
日付は明示したcivil date(YYYY-MM-DD)であり、UTC時刻への暗黙変換をしない。
|
||||
作成時のDomain timezoneをサーバーで記録する。設定timezone変更後も過去の記事を
|
||||
別日に移動しない。未来の日付を指定しても公開予約や時刻による自動公開は行わない。
|
||||
著者は最初の登録時の認証済みPrincipalで固定し、クライアントのowner指定は信用しない。
|
||||
|
||||
## 権限と公開範囲
|
||||
|
||||
- 登録情報を利用するUI/APIは**認証必須**。legacyモードでも匿名メタデータ一覧を
|
||||
許さない。設定済み射影の公開Path/Revision由来一覧は上記の限定例外。
|
||||
- 設定変更はactiveなDomain管理者グループのowner/manager。
|
||||
- 記事登録・情報更新・解除は対象Pathのwrite権限と上位Locality制限を再検査する。
|
||||
`upload_only`や`read_write_once`だけでは、既存Pageの記事情報を書き換えられない。
|
||||
既存エディタと同じく、本人の `/u/{username}` Wiki配下は本人の編集権限で扱う。
|
||||
この場合もactive membership・実際のidentity・上位Locality制限を検査する。
|
||||
- 一覧・カテゴリ・カレンダー件数・最近の記事・ページ送りは、現在のPage閲覧権限で
|
||||
絞った後に構築する。非公開の別名で先にdedupeして可視Pageを失わない。
|
||||
- 登録操作は匿名公開承認ではない。Page本文の匿名公開は従来の正確なRevision承認に
|
||||
従う。登録タイトルのみPageの公開状態を継承し、それ以外は個別の承認契約が必要。
|
||||
- 下書き/公開/予約公開を、この登録テーブルの有無や日付と混同しない。
|
||||
公開一覧・RSS/Atomには記事メタデータの承認されたスナップショットと失効検査が必要。
|
||||
|
||||
変更transactionは最初にSQLiteのwrite予約を取得し、active membership、設定、Pathの
|
||||
Page UUID、write grant、group/locality caps、期待versionを同一snapshotで検査する。
|
||||
既存記事の変更にはPage UUIDも要求し、renameやPathの再bindを検出する。
|
||||
削除・再登録後もjournalからversionを引き継ぎ、古い編集要求の再利用を拒否する。
|
||||
古いversionによる登録更新は409で明示し、上書きしない。同日複数記事は許可する。
|
||||
|
||||
## APIと負荷上限
|
||||
|
||||
`/_/api/v1/extension/content.{diary|blog}/{settings|entries}`:
|
||||
|
||||
- `GET settings`:有効状態。`POST settings`:`{enabled: bool}`。
|
||||
GETはprefixも返す。POSTは任意の`prefix`を受け、有効状態・prefix・journalを
|
||||
同一transactionで保存する。prefix省略時は既存設定を維持する。
|
||||
- `GET plan?date=YYYY-MM-DD&keyword=...`:認証・有効状態・対象Pathのwrite権限を
|
||||
確認し、未使用Pathとeditor_hrefを返す。既存Pathは409。POSTは不可。
|
||||
- `GET entries`:現在読める記事のメタデータのみ。
|
||||
- `POST entries`:`path,title,date,category,version`(新規は0)。更新/解除は
|
||||
`page_uuid`と現在のversionを付け、解除には`remove:true`を指定する。
|
||||
- 未定義メソッド・未知フィールド・複数JSON値は拒否。本文上限8 KiB。
|
||||
- UIは20件単位、最近の記事は8件。索引取得は本文を読まない2秒のmetadata query、
|
||||
最大5,000 binding行/4 MiB。超過時は黙って結果を欠落させず503。
|
||||
設定・更新transactionは3秒。UIの編集権限評価は表示中の最大20件だけ。
|
||||
- 初期版はpermission-filtered keyset pagingではない。大規模サイト向けには上限を
|
||||
単純に広げず、バッチ権限評価・索引分割・不透明cursorを先に実装する。
|
||||
- ブラウザ側に記事や権限を永続キャッシュしない。BFCache復帰時に再読込。
|
||||
設定パネルは表示された時だけ非同期で読む。fetchは15秒で打ち切る。
|
||||
|
||||
## 次の実装/TODO
|
||||
|
||||
- [x] Page+初回Revision+記事情報を原子的に作成するMarkdown投稿フォーム。
|
||||
既存の本文保存・asset固定とjournal、冪等再送を実装。
|
||||
- [ ] 投稿journalから共通outboxへの配送、City自動生成・通知、receipt保持期間とGC。
|
||||
- [x] 同一Campus・同一インスタンスの参照型一覧/カレンダー射影と双方の読取権限検査。
|
||||
- [x] 承認済みPath/Revision由来の匿名射影一覧・カレンダー。
|
||||
- [x] 専用ドメイン内の記事本文、登録タイトル、同月/前後ナビゲーション、RSS 2.0。
|
||||
- [ ] タイトル以外の登録メタデータの匿名射影承認、別インスタンスの
|
||||
参照設定配信と認証付き取得・失効、クロスDomain SSO。
|
||||
- [x] Domain入口設定ダイアログと署名付きmanifest v2による設定配信・原子的反映。
|
||||
- [x] 署名付きcapability申告・全承認済みノードのv2事前確認・UI案内。
|
||||
- [ ] Domain新規作成フォームとの一体化、設定の管理解除・GC、配信反映ACK/鮮度管理。
|
||||
- [ ] 残りの記事メタデータの公開承認・Atom。承認ポリシー/Inboxと接続し、
|
||||
Pageや上位階層の公開範囲を広げない。タイトル変更・公開撤回で即時失効。
|
||||
- [ ] 本文抜粋、表紙、複数カテゴリ/タグ。
|
||||
- [ ] 個人/共有コレクション、著者選択、所有者移管/引き継ぎ。
|
||||
- [ ] コメント基盤と最近のコメント:閲覧制限、モデレーション、削除・通知を共通化。
|
||||
- [ ] tDiary取り込み:提供サンプルと公式仕様を確認して対応版/形式を固定する。
|
||||
Ruby/eval/Marshalの任意実行は禁止。既存import session/journalを使い、事前確認、
|
||||
日付・timezone・旧URL・セクション・添付・コメントの対応、再開・重複防止を実装。
|
||||
移行著者は出典であり、ローカル認証ユーザーと偽って紐付けない。
|
||||
- [ ] 共通outbox・保持/export/削除ポリシー・metadata履歴、孤立メタデータのGC。
|
||||
- [ ] 索引のkeyset pagingと負荷試験、外部拡張の署名・分離runtimeは別途。
|
||||
|
||||
検証:登録/更新/解除、同日複数記事、うるう日、write拒否、Domain越境、グループ失効、
|
||||
rename追従、非公開カテゴリ/件数の漏えい、journal失敗時のrollback、version再利用、
|
||||
無効化時のデータ保持、厳格JSON、匿名拒否、PC/モバイルでの設定と登録操作。
|
||||
@@ -0,0 +1,244 @@
|
||||
# Domain Namespace and Federation
|
||||
|
||||
## Decisions
|
||||
|
||||
### Paths are Domain-local
|
||||
|
||||
A semantic path is identified by the pair:
|
||||
|
||||
```text
|
||||
(domain_uuid, normalized_path)
|
||||
```
|
||||
|
||||
Therefore `/handbook` in the Sales Domain and `/handbook` in the Engineering
|
||||
Domain are different bindings and do not conflict.
|
||||
|
||||
The `paths` table uses a composite primary key:
|
||||
|
||||
```sql
|
||||
CREATE TABLE paths_v2 (
|
||||
domain_uuid TEXT NOT NULL,
|
||||
path TEXT NOT NULL,
|
||||
object_uuid TEXT NOT NULL,
|
||||
created_at INTEGER NOT NULL,
|
||||
is_primary INTEGER NOT NULL DEFAULT 0,
|
||||
PRIMARY KEY (domain_uuid, path)
|
||||
);
|
||||
```
|
||||
|
||||
Existing rows are assigned to the current default Domain during migration.
|
||||
All path reads and mutations must receive the request Domain UUID explicitly;
|
||||
silently using a process-wide default is prohibited in request handlers.
|
||||
|
||||
### Objects are instance-global
|
||||
|
||||
Page Objects are not owned by a Domain. Their UUID is globally unique within
|
||||
an instance, while a Domain owns bindings from its paths to Object UUIDs.
|
||||
|
||||
This preserves the MagicPage property:
|
||||
|
||||
```text
|
||||
sales.example.test/guide ─┐
|
||||
engineering.example.test/guide ├─> Page UUID 7a…
|
||||
support.example.test/runbook ─┘
|
||||
```
|
||||
|
||||
Revisions, immutable Documents, tags, and assets remain attached to Object
|
||||
identity. Authorization may still restrict which Domains may bind or expose
|
||||
an Object.
|
||||
|
||||
If stronger tenant isolation is later required, it belongs in policy and
|
||||
storage-placement layers rather than by weakening UUID identity.
|
||||
|
||||
## Link addressing
|
||||
|
||||
Links have two forms:
|
||||
|
||||
- Same Domain: a root-relative semantic path such as `/guide`.
|
||||
- Another Domain or another instance: an absolute URL containing the
|
||||
destination FQDN, such as `https://engineering.example.test/guide`.
|
||||
|
||||
A cross-Domain link must not be stored as a bare `/guide`, because its meaning
|
||||
would change with the request Host. Internally, a locally managed destination
|
||||
may additionally retain `domain_uuid` for rename tracking, but its rendered
|
||||
and exported form is still an absolute URL.
|
||||
|
||||
Object addresses (`uuid:`, `rev:`, and `asset:`) are local-instance addresses.
|
||||
To address another instance they require an origin:
|
||||
|
||||
```text
|
||||
https://engineering.example.test/o/uuid:…
|
||||
https://engineering.example.test/o/rev:…
|
||||
```
|
||||
|
||||
No request should transparently resolve a remote UUID against the local
|
||||
SQLite database.
|
||||
|
||||
## Local and remote Domains
|
||||
|
||||
A configured FQDN does not by itself mean that a Domain is remote. One
|
||||
PagesWiki instance may serve several local FQDNs. Domain placement therefore
|
||||
must be explicit:
|
||||
|
||||
| placement | Meaning |
|
||||
| --- | --- |
|
||||
| `local` | This instance serves the Domain and owns its path namespace. |
|
||||
| `remote` | The Domain is a catalog entry served by another instance. |
|
||||
|
||||
A remote Domain has no writable local path namespace. Its origin is derived
|
||||
from its owning Campus FQDN and Domain host. Proxying remote content is not
|
||||
implicit.
|
||||
|
||||
Implemented additive Domain fields:
|
||||
|
||||
```sql
|
||||
placement TEXT NOT NULL DEFAULT 'local',
|
||||
```
|
||||
|
||||
The URL scheme is transport policy and is not part of Campus or Domain
|
||||
identity.
|
||||
|
||||
## Host resolution
|
||||
|
||||
Campus stores an FQDN without `http://` or `https://`. A Domain host resolves
|
||||
as follows:
|
||||
|
||||
- empty host: the Campus FQDN;
|
||||
- label without a dot: `label.<campus-fqdn>`;
|
||||
- host containing a dot: the host is already an FQDN and is used unchanged.
|
||||
|
||||
Resolution is exact. An unknown request Host does not fall back to an
|
||||
arbitrary default Domain. The Domain with an empty host is selected only when
|
||||
the request Host equals its Campus FQDN.
|
||||
|
||||
## Campus authority modes
|
||||
|
||||
Campus configuration has an explicit authority mode:
|
||||
|
||||
| mode | Responsibility |
|
||||
| --- | --- |
|
||||
| `standalone` | All Campus and local Domain configuration is maintained on this instance. |
|
||||
| `controller` | This instance is authoritative for a Campus topology and publishes desired configuration for managed instances. |
|
||||
| `managed` | This instance accepts topology configuration from one external Campus controller. Local topology edits are disabled. |
|
||||
|
||||
Implemented additive Campus fields:
|
||||
|
||||
```sql
|
||||
authority_mode TEXT NOT NULL DEFAULT 'standalone',
|
||||
fqdn TEXT NOT NULL
|
||||
```
|
||||
|
||||
The FQDN identifies the Campus in every authority mode. A controller Campus
|
||||
may contain both local and remote Domain records. A managed instance stores
|
||||
the controller Campus UUID, FQDN, and Domain UUIDs unchanged.
|
||||
|
||||
A Domain owned by a controller Campus also records `instance_fqdn`. This is
|
||||
the concrete PagesWiki instance selected to serve that Domain. Controller
|
||||
Domains require this value; standalone Domains default it to the Campus FQDN.
|
||||
Managed instances treat Domain topology as read-only because those records
|
||||
are reconciled from the controller.
|
||||
|
||||
Controller instances issue random enrollment tokens. Only a SHA-256 token
|
||||
hash is stored by the controller, and the plaintext token is displayed once.
|
||||
A joining instance presents the token, its FQDN, and the SHA-256 fingerprint
|
||||
of its persistent Ed25519 public key.
|
||||
The enrollment request includes that public key and a signature over the
|
||||
normalized instance FQDN and enrollment token, so the controller verifies
|
||||
proof-of-possession before recording the fingerprint.
|
||||
|
||||
Registration creates a pending instance. An administrator verifies its
|
||||
fingerprint and approves it before it becomes available in the Domain
|
||||
placement selector. The placement stores both the instance FQDN and
|
||||
fingerprint. Re-registering the same FQDN with a different fingerprint
|
||||
creates another pending identity and never inherits the old approval.
|
||||
Pending instances receive Campus metadata but no Domain assignments. Revoking
|
||||
an instance disables Domains assigned to that exact FQDN and fingerprint.
|
||||
Enrollment tokens are individually revocable.
|
||||
|
||||
An external Campus is initialized with:
|
||||
|
||||
```text
|
||||
pageswiki --add-external-campus CAMPUS_FQDN TOKEN
|
||||
```
|
||||
|
||||
Development environments may explicitly select unencrypted transport with
|
||||
`--add-external-campus-http CAMPUS_FQDN TOKEN`. HTTP is never selected
|
||||
implicitly; the standard command always uses HTTPS.
|
||||
|
||||
Either enrollment form may be combined with `--no-default-campus` for a
|
||||
dedicated managed instance. Its bootstrap standalone Campus and Domain remain
|
||||
available while enrollment or approval is pending, and are removed
|
||||
transactionally after the controller assigns the first enabled Domain.
|
||||
|
||||
`PAGESWIKI_INSTANCE_FQDN` supplies the joining instance FQDN. Enrollment
|
||||
fetches and applies the controller Campus name, title, default language,
|
||||
FQDN, and Domain snapshot. These fields are read-only locally. The token is
|
||||
stored under the data directory with mode `0600`; the instance Ed25519 private
|
||||
key is also stored with mode `0600`.
|
||||
|
||||
The Managed Campus Save action performs a Controller health probe without
|
||||
making inherited fields editable. The management view displays a yellow-green
|
||||
lamp after a successful probe and a red lamp after failure. The transport
|
||||
(`https` or explicitly selected `http`) is retained from enrollment. Delete
|
||||
detaches the Managed Campus, its Domain projections, Domain settings, and
|
||||
Path bindings; Page Objects and immutable Revisions remain intact.
|
||||
|
||||
## Domain-scoped settings
|
||||
|
||||
Campus and Domain topology are instance-level administration. All other
|
||||
settings use `(domain_uuid, key)` identity. This includes locale, timezone,
|
||||
theme, home path, editor behavior, navigation, and
|
||||
maintenance preferences. Legacy settings are assigned to the default Domain;
|
||||
new Domains start with product defaults.
|
||||
|
||||
The displayed Wiki name is not an independent setting: it is always the
|
||||
resolved Domain title. Recent Objects are selected by Domain Path bindings.
|
||||
The administration view may inspect another Domain through an explicit
|
||||
Campus and Domain selector.
|
||||
|
||||
## Configuration distribution
|
||||
|
||||
Federation is desired-state synchronization, not shared SQLite access.
|
||||
|
||||
The preferred flow is:
|
||||
|
||||
1. A controller publishes a versioned, signed Campus manifest.
|
||||
2. A managed instance authenticates with its enrollment token and pulls the
|
||||
manifest.
|
||||
3. The instance validates schema version, Campus UUID, allowed hostnames, and
|
||||
monotonic manifest revision.
|
||||
4. It applies the manifest transactionally.
|
||||
5. It reports the applied revision and validation errors.
|
||||
|
||||
Pulling avoids requiring inbound administrative access to every managed
|
||||
instance. A push notification may trigger a pull, but does not contain
|
||||
authoritative configuration itself.
|
||||
|
||||
The manifest controls topology and presentation defaults only. It must not
|
||||
carry SQLite files, revisions, Documents, local secrets, OIDC client secrets,
|
||||
Macaroon root keys, or instance-private signing keys.
|
||||
|
||||
## Security requirements
|
||||
|
||||
- Transport security policy is evaluated separately from the stored FQDN.
|
||||
- Controller manifests require signature verification and replay protection.
|
||||
- A managed instance is pinned to one Campus UUID and controller identity.
|
||||
- Hostname changes require explicit allow-list validation.
|
||||
- Local emergency override and last-known-good rollback are retained.
|
||||
- Controller unavailability does not remove the last applied configuration.
|
||||
- Remote links are rendered as external navigation, never server-side fetched
|
||||
merely because a page contains the link.
|
||||
|
||||
## Migration order
|
||||
|
||||
1. [x] Add placement and authority metadata. Remote Domains have no local
|
||||
writable Path namespace, and managed Campus topology is read-only.
|
||||
2. [x] Rebuild `paths` with `(domain_uuid, path)` identity and assign legacy
|
||||
rows to the default Domain.
|
||||
3. [x] Thread Domain UUID through Store APIs, server handlers, recursive
|
||||
operations, browser/tree queries, and the data CLI.
|
||||
4. [x] Add cross-Domain absolute-link helpers and tests.
|
||||
5. [x] Add signed controller manifests and managed-instance reconciliation.
|
||||
|
||||
Steps 2 and 3 shipped together. Adding `domain_uuid` while leaving unscoped
|
||||
queries would have created cross-Domain data disclosure.
|
||||
@@ -0,0 +1,91 @@
|
||||
# Event Scheduler
|
||||
|
||||
## Purpose
|
||||
|
||||
CPU-, memory-, and decoder-heavy work must not execute in Viewer requests.
|
||||
PagesWiki uses a persistent SQLite event queue for deferred work.
|
||||
|
||||
`event_jobs` records:
|
||||
|
||||
- event UUID and type
|
||||
- idempotency key
|
||||
- JSON payload
|
||||
- `queued`, `running`, `succeeded`, or `failed` status
|
||||
- scheduled time and attempt count
|
||||
- latest error
|
||||
- creation and update timestamps
|
||||
|
||||
The current implementation is a single scheduler loop that may run up to the
|
||||
configured concurrency in goroutines. It checks foreground request activity
|
||||
between claims and keeps one reserved background slot so a long-lived editor or
|
||||
stream cannot starve all jobs. Cross-instance leases are still future work. The
|
||||
transactional Domain outbox now records Page/Revision creation and Path/Object
|
||||
mutations. Domain-local consumer watermarks are durable and monotonic;
|
||||
notification delivery remains future work.
|
||||
External preview tools run through bounded
|
||||
commands with timeouts.
|
||||
|
||||
## Event log retention and trends
|
||||
|
||||
`event_logs` remains the recent, drill-down log. Each record is associated with
|
||||
its event type when the job is known. `event_log_policies` provides per-event
|
||||
retention, aggregation window, bucket size, and maximum raw-row settings; `*`
|
||||
is the safe default. `event_log_buckets` stores compact counts and first/last
|
||||
timestamps by event type, level, and time bucket, so trend charts do not scan
|
||||
the raw log table. The API exposes `/event/logs/trends` and `/event/policies`.
|
||||
|
||||
Retention removes old rows in place and keeps bounded aggregate buckets. A
|
||||
future partition/rotation implementation may replace the physical table, but
|
||||
must use an atomic rename-and-recreate procedure; an online `DROP TABLE` is
|
||||
never used while workers can append logs.
|
||||
|
||||
## Preview Events
|
||||
|
||||
`preview.generate` uses the immutable Document hash as its idempotency key.
|
||||
Viewer never generates a thumbnail. A children projection:
|
||||
|
||||
1. checks the immutable preview cache;
|
||||
2. emits the cached thumbnail URL when present;
|
||||
3. otherwise enqueues the event and immediately renders a format icon.
|
||||
|
||||
The browser polls only the lightweight cache URL for visible entries. Once the
|
||||
job succeeds, it replaces the icon with the cached image without reloading the
|
||||
Page.
|
||||
|
||||
Current generators:
|
||||
|
||||
| Input | Generator | Cached form |
|
||||
| --- | --- | --- |
|
||||
| PNG/JPEG/GIF | bounded Go image resampler | JPEG |
|
||||
| PDF | `pdftoppm`, first page | JPEG |
|
||||
| Video | `ffmpeg`, one frame | JPEG |
|
||||
| Excalidraw | bounded server SVG renderer | sandboxed SVG |
|
||||
|
||||
Individual PDF pages use the same queue. A cache miss returns `202` with
|
||||
`Retry-After`; the browser retries until the scheduler writes the immutable
|
||||
`<document-hash>-p<page>.jpg` file. PDF page counts and non-ZIP archive listings
|
||||
are persisted output of `projection.metadata.generate`, not Viewer work. See
|
||||
[deferred projection metadata](projection-metadata-cache.md) for cache quotas,
|
||||
pending/retry responses, authorization, and decoder limits.
|
||||
|
||||
Generated files live beside the Document Store in `previews/` and are addressed
|
||||
by immutable Document hash. Cache responses are immutable for one year.
|
||||
|
||||
## Scheduling
|
||||
|
||||
- Missing previews are enqueued when an icon projection encounters them.
|
||||
- A periodic sweep runs every 15 minutes.
|
||||
- The first sweep runs shortly after startup.
|
||||
- Configuration → Execution monitor combines resource charts with running jobs
|
||||
only. Job history & logs contains paginated completed jobs and per-job logs.
|
||||
Event definitions exposes the manual “Generate missing previews” trigger.
|
||||
|
||||
See [Configuration panels](configuration-panels.md) for polling, indexed queue
|
||||
listing, lazy log retrieval and legacy resource-panel URL compatibility.
|
||||
|
||||
Failures remain visible in scheduler statistics and logs. Retry/backoff and
|
||||
cancellation are persisted in the queue; a later sweep or manual trigger may
|
||||
enqueue a missing cache again. Preview requests never execute the generator in
|
||||
the normal Viewer request path. Non-ZIP entry extraction remains a bounded
|
||||
foreground stream pending its separate cached-entry design; metadata listing
|
||||
and PDF page counts have migrated to deferred projections.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Signed Campus manifest integrity
|
||||
|
||||
Implemented bounded single-writer-SQLite correction, 2026-09-14. This is not
|
||||
controller HA, key rotation, multi-node metadata fencing or a new federation
|
||||
trust protocol.
|
||||
|
||||
## Controller sequence allocation
|
||||
|
||||
`BuildSignedCampusManifest` canonicalizes the supplied Domain list by UUID,
|
||||
rejects duplicate/missing identities and hashes the Campus plus filtered Domains.
|
||||
A single SQLite `INSERT ... ON CONFLICT DO UPDATE ... RETURNING revision`
|
||||
allocates the sequence against the current persisted hash:
|
||||
|
||||
- First content gets revision 1.
|
||||
- Identical content retains its revision and timestamp.
|
||||
- Changed content atomically increments the previous revision.
|
||||
- Database errors and integer overflow fail, never resetting to revision 1.
|
||||
|
||||
The returned revision is signed with the existing Ed25519 identity. Concurrent
|
||||
calls cannot sign different content with the same revision. Ordering-only changes
|
||||
to the supplied Domain list do not churn revisions. This orders supplied
|
||||
snapshots; it does **not** make the caller's earlier Campus/Domain reads a
|
||||
transactional configuration snapshot. A controller-wide configuration generation
|
||||
is still needed before claiming DR/HA or preventing an old caller snapshot from
|
||||
being issued later with a newer revision.
|
||||
|
||||
## Managed-instance application
|
||||
|
||||
Verify signature, schema, Campus identity and Domain identity/hostname shape
|
||||
before acquiring a database write reservation. Then, in one transaction:
|
||||
|
||||
1. Reserve SQLite's writer with a no-op update to the manifest-state table.
|
||||
This works even for a first enrollment with no row; competing first pins
|
||||
serialize instead of both reading an absent checkpoint.
|
||||
2. Read the pinned fingerprint, applied revision and exact payload. Only
|
||||
`sql.ErrNoRows` means an unpinned Campus. Other database errors fail closed.
|
||||
3. Reject changed signing identity, lower revisions and a reused revision with
|
||||
different payload. An exact duplicate succeeds without reapplying the snapshot.
|
||||
4. Check authority ownership and apply the Campus/Domain snapshot using the
|
||||
transaction-owned helper. Update placement/default locale as before and keep
|
||||
`projectCampusAdminMembershipsTx` in this same transaction.
|
||||
5. Persist the verified public key/fingerprint, revision and payload checkpoint;
|
||||
commit all snapshot, inherited-permission and checkpoint changes together.
|
||||
|
||||
A checkpoint/projection/domain-write failure rolls everything back, including a
|
||||
new trust pin. Retrying the same manifest after a rolled-back failure is safe.
|
||||
No failed/replayed manifest silently retries with relaxed verification.
|
||||
|
||||
## Authority and legacy compatibility
|
||||
|
||||
A valid signature establishes a signing identity, not authority over every
|
||||
local UUID. A managed snapshot cannot replace a standalone/controller Campus
|
||||
or reparent a Domain UUID owned by another Campus. A new managed Campus and
|
||||
updates to its own Domains remain supported, including initial pending enrollment
|
||||
followed by an approved manifest that deploys Domains to the matching instance.
|
||||
|
||||
The legacy unsigned snapshot entry point still permits enrollment/resynchronizing
|
||||
an **unpinned** managed Campus. It acquires the same writer reservation before
|
||||
checking the pin. Once a signed checkpoint exists, unsigned fallback is rejected;
|
||||
omitting a manifest can no longer bypass signing-identity/replay checks. Explicit
|
||||
trust reset or key rotation needs a separate administrator-controlled workflow.
|
||||
Initial enrollment remains trust-on-first-use through the configured controller
|
||||
and enrollment transport; signing does not make an HTTP bootstrap resistant to
|
||||
an active network attacker.
|
||||
|
||||
## Verification and remaining work
|
||||
|
||||
Tests cover 20 concurrent same/changed-content sequence allocations, canonical
|
||||
ordering and overflow, 24 concurrent duplicate/out-of-order deliveries, competing
|
||||
first keys/payloads, injected initial/updated-checkpoint and inherited-projection
|
||||
failures, missing state tables, a one-connection pool, cross-authority collisions,
|
||||
legacy-to-signed upgrade, approved placement/locale inheritance and unsigned
|
||||
downgrade rejection. Existing managed enrollment/reconciliation tests remain in
|
||||
the suite.
|
||||
|
||||
There are no new tables, shared keys or schema migrations. Key rotation, explicit
|
||||
global authority transfer, independently versioned instance projections, bounded
|
||||
configuration capture and DR/HA are follow-ups rather than implied guarantees.
|
||||
@@ -0,0 +1,536 @@
|
||||
# September 2026 execution ledger
|
||||
|
||||
User direction: continue the remaining roadmap in priority order; defer extremely
|
||||
complex/high-risk changes with explicit prerequisites. Preserve existing identity
|
||||
and deployments. This ledger separates completed slices from unresolved gates.
|
||||
|
||||
## Active batch
|
||||
|
||||
### Japanese design consolidation and Wiki publication (2026-09-19)
|
||||
|
||||
- Added a 22-chapter Japanese handbook plus index, separating current behavior,
|
||||
proposals, unresolved choices and historical claims. Original source documents
|
||||
remain unchanged in identity/location; a source inventory maps them to chapters.
|
||||
- Expanded Organizer/tasks/tickets, calendar/contacts/DAV, RSS/FreshRSS/newsboat,
|
||||
IMAP capture and incremental HTML editing proposals with identities, authority,
|
||||
conflict/retention behavior, delivery slices and acceptance fixtures. No new
|
||||
external integration or connector is enabled by this design work.
|
||||
- Reviewed primary RFC and FreshRSS/newsboat documentation; runtime/client
|
||||
compatibility remains a prerequisite, not a claimed implementation.
|
||||
- `tools/design-export` renders with the application Markdown renderer, validates
|
||||
internal chapter links and emits source/payload hashes. Tests cover tables,
|
||||
chapter count, bad links and staging overwrite refusal.
|
||||
- Uploaded 23 new `ja` Page revisions through the trusted local data CLI to
|
||||
`https://pages.anya.jp/lab/pageswiki-dev/`; destination was empty beforehand.
|
||||
Read-back comparison and manifest/DB hash checks passed for all 23 payloads.
|
||||
Receipt: `publication-ja-2026-09-19.json`. Existing English sources are retained.
|
||||
- Anonymous HTTPS access still redirects to login. No publication/authorization
|
||||
settings, external credentials, application runtime or deployment were changed.
|
||||
`go test ./...` and diff checks passed.
|
||||
|
||||
### Scoped automatic publication and compact blog index (2026-09-19)
|
||||
|
||||
- Added explicitly confirmed Street/Spot automatic publication, live revision and
|
||||
publisher-authority checks, inherited manual-approval boundaries, ACL/alias
|
||||
exclusions, and versioned impact previews. Existing settings stay unchanged;
|
||||
no production locality is opted in by this deployment. See
|
||||
[automatic publication](automatic-publication.md) for limits and remaining work.
|
||||
- Blog/diary and projected public indexes use compact date/title tables. The month
|
||||
selector sits above the sidebar calendar; authenticated row actions remain
|
||||
accessible through labelled icons. Existing post editing and public article
|
||||
navigation are preserved.
|
||||
- Full Go tests, vet and diff checks passed. Opt-in Chromium coverage passed for
|
||||
automatic publication, City governance, periodicals and public projection.
|
||||
- Follow-up: month input, apply and reset form a single compact row; SVG buttons
|
||||
have localized tooltips/accessibility labels. Desktop/mobile browser tests
|
||||
enforce single-line controls and placement above the calendar.
|
||||
- Pre-migration online backups of both databases passed quick checks under
|
||||
`/home/anya/.cache/pageswiki-backups/pre-auto-publication-kv0VzP/`.
|
||||
- Deployed app2 then app with image
|
||||
`sha256:8ca7973bb12126ba2291dc9e6e1c9a4c5faad77ff92b56cf4f79ee69e9620523`.
|
||||
Both instances responded successfully with zero restarts; app is healthy.
|
||||
Public HTTPS serves the compact index and three RSS embedded article bodies;
|
||||
both databases still contain zero automatic-publication rules. Production mobile
|
||||
rendering confirms the one-line month controls. Anonymous source editing still
|
||||
redirects to login.
|
||||
- Future tasks/tickets, organizer/DAV, mail ingestion and HTML editing ideas are
|
||||
recorded in [design backlog](organizer-and-editing-ideas.md), not implemented in
|
||||
this batch. Full WYSIWYG remains an explicit undecided design choice.
|
||||
|
||||
### Full-content RSS, standalone composition and X sharing (2026-09-19)
|
||||
|
||||
- RSS `content:encoded` uses the inert HTML pipeline, namespace-aware XML/CDATA,
|
||||
absolute public article/image/anchor URLs and exact live Revision rechecks.
|
||||
Limits: 20 articles, 1MiB input/article, 8MiB total HTML, 5s generation; HEAD skips
|
||||
body work. RSS-reader copies cannot be remotely recalled after unpublishing.
|
||||
- Added authenticated GET-only `/v/blog/-/new` and `/v/diary/-/new`, themed responsive
|
||||
forms backed by the existing atomic posts API. Projection targets redirect to the
|
||||
configured source composer. No GET creates content; disabled plugins return 404.
|
||||
- Post completion offers X Web Intent with title and registered projection-domain
|
||||
URL; multiple eligible Domains are selectable. Invalid/disabled/cross-Campus
|
||||
projections are excluded, and pending publication is explicitly warned/confirmed.
|
||||
No external posting occurs without user action; no OAuth secrets or new grants.
|
||||
- Added namespace/CDATA, absolute link, unsafe HTML, composition route and share-
|
||||
domain/prefix regressions; Chromium covers standalone posting and sharing controls
|
||||
at desktop/mobile widths without navigating to X or creating production content.
|
||||
- Full Go tests, vet, JS syntax, diff check and opt-in Chromium suites passed.
|
||||
Deployed app2 then app with image
|
||||
`sha256:f51dadce7481b480bdd924ad65d050e6d9570a37081c91a7cd5562394d9be4bc`.
|
||||
HTTPS RSS returned 200 with three embedded public HTML bodies and the content
|
||||
namespace; article returned 200 with target-domain OGP URL; both new-entry routes
|
||||
redirected anonymous requests to login (303). app healthy, both containers running
|
||||
with zero restarts. No production article creation or X posting was performed.
|
||||
|
||||
### Dedicated public blog articles and RSS (2026-09-19)
|
||||
|
||||
- Dedicated diary/blog Domains now project approved source article bodies at
|
||||
`/YYYY/MM/DD[/keyword]`. Header/browser title use target Domain branding; article
|
||||
pages keep month calendar, other entries that month and older/newer navigation.
|
||||
Known public article links in sanitized bodies are remapped to the target host.
|
||||
- Registered titles explicitly inherit the Page's live publication status. This
|
||||
changes the earlier h1-only index contract at the user's request. Private category,
|
||||
author and registration date are still omitted; dates derive from approved Paths.
|
||||
No registration table writes, grant changes or migration are needed.
|
||||
- `/rss.xml` emits RSS 2.0 with up to 20 public titles, target-domain links/GUIDs and
|
||||
Revision timestamps. HTML advertises the feed. No private metadata or body copies
|
||||
in RSS; no shared HTTP caching. Subscriber-retained copies cannot be revoked.
|
||||
- Full Go tests, vet, diff check and Chromium tests at 1440/390 px passed. Tests cover
|
||||
keyword routes, domain title, escaped registration titles, sanitized body, previous/
|
||||
next links, feed XML, private entries, edited-revision revocation and both auth modes.
|
||||
- Remaining: Atom, excerpts/covers, publication approval of other metadata, cross-
|
||||
instance projection and SSO. Non-public embedded assets do not gain public access.
|
||||
- Deployed app2 then app with
|
||||
`sha256:2a9743aadf687dedb7465b6e9c22f313818aa59fe341a94c5c6ec82c139386cf`.
|
||||
Anonymous HTTPS index, `/2026/09/17` and `/rss.xml` all returned 200 (one published
|
||||
entry); parent editor still returned login 303. Confirmed registered Japanese title,
|
||||
sanitized body, blog Domain header and calendar in
|
||||
`/tmp/pageswiki-blog-article-review-0919.png`. app healthy; publication count remains
|
||||
one and enforcing config unchanged. No production content/config writes were made
|
||||
by this task; current Object count is 1456 (live instance continues background work).
|
||||
|
||||
### Public diary/blog projection index (2026-09-17)
|
||||
|
||||
- Root cause: configured projection views always required a session, even with
|
||||
approved publications in the source prefix. Added anonymous root/month/day views
|
||||
in enforcing and legacy target modes, using only the source's live publication
|
||||
manifest. Source authorization mode must remain enforcing.
|
||||
- Dates derive from approved Paths; headings from approved HTML, bounded to 64KiB
|
||||
for at most 20 displayed and 8 recent entries. No private article metadata,
|
||||
categories, authors, editor dialogs or unrelated navigation is exposed.
|
||||
- No grants, auth modes, schema or content changed. Body links remain on the source
|
||||
host. Source disablement, invalid credentials and publication revocation fail
|
||||
closed. Registration metadata approval and same-host body projection remain TODO.
|
||||
- Validation: full `go test ./...`, `go vet ./...`, JS syntax, diff check and existing
|
||||
Chromium periodical flow passed. New tests cover both target modes, private
|
||||
registration metadata, unapproved Paths, invalid credentials and edited revisions.
|
||||
- app2 then app deployed with image
|
||||
`sha256:36f5fba8a86db9ed6ea94872400bc86745c6499e3c09b49c11896303a953d86f`.
|
||||
Anonymous HTTPS root/day views on blog.pages.anya.jp returned 200 with exactly one
|
||||
approved article; source article returned 200, parent editor and invalid credentials
|
||||
returned login 303. Browser screenshot checked at
|
||||
`/tmp/pageswiki-public-blog-review.png`. app healthy, both running without restarts.
|
||||
Object/publication counts remained 1455/1; authorization configuration unchanged.
|
||||
|
||||
### Domain entry dialog CSS correction (2026-09-17)
|
||||
|
||||
- Root cause: the modal was nested in a dense administration table cell. Broad
|
||||
descendant selectors made forms inline-flex, help paragraphs inline, and controls
|
||||
inherit compact table sizing. Previously the browser test checked `open` but not
|
||||
actual geometry (a hidden panel ancestor could still conceal the dialog).
|
||||
- Moved modals outside tables and panels into the body. Added isolated responsive
|
||||
fields, block help text, themed controls, toggle labels, sticky header/close button,
|
||||
background scroll lock, accessible dialog title and CSS cache-version update.
|
||||
- New Chromium regression checks at 1440/390 px with Light/Nanoha Dark: visible
|
||||
viewport bounds, no horizontal overflow or overlapping controls, form/help display,
|
||||
sticky close button and close/reopen. Screenshots inspected under
|
||||
`/tmp/pageswiki-domain-entry-review/`. Existing periodical browser flow, full Go
|
||||
tests, vet and diff check passed.
|
||||
- UI-only release; no schema/content/permission changes or database restore.
|
||||
app2 then app updated to
|
||||
`sha256:d2cb4a02e780790294245e60a394e6046be1f3160bc9e4186c0daf7f9a8a4369`.
|
||||
Both health endpoints responded, zero restarts; served config.css matches source.
|
||||
|
||||
### Local diary/blog projection deployment (2026-09-17)
|
||||
|
||||
- First slice: same-Campus, local-placement metadata projection, source-prefix
|
||||
filtering and source+destination read policies; no copied content. Article/body/edit
|
||||
links open the source Domain. No anonymous, cross-instance or host-preserving body
|
||||
projection yet. Local projection settings are not in federation manifests.
|
||||
- Backup directory `/home/anya/.cache/pageswiki-backups/pre-periodical-projection-aw54pH/`:
|
||||
app.sqlite and app2.sqlite, private permissions, both quick_check OK.
|
||||
- app2 then app deployed with image
|
||||
`sha256:e44fbb1a55f7eef4a4c4fec08a87efa8bc7e592f222c99090930c95590d435cf`.
|
||||
Main DB initialization briefly left the listener unavailable during restart;
|
||||
final app health=healthy, app2 health endpoint OK, zero restarts, public HTTPS=200.
|
||||
Running template contains the domain-projection settings forms.
|
||||
- Full tests, vet, diff check, focused race and desktop/mobile Chromium passed.
|
||||
Fixture tests cover no-copy behavior, source ACL denial/revocation, prefix filter,
|
||||
source links, target write rejection, self/cycle/cross-Campus rejection and remote
|
||||
source fail-closed behavior.
|
||||
- Production Objects=1454, publication entries=4, matching pre-update counts.
|
||||
No production projection bindings were created automatically; user chooses source.
|
||||
|
||||
### Diary/blog and Domain entry deployment (2026-09-17)
|
||||
|
||||
- User explicitly authorized backup and deployment. Online SQLite backups:
|
||||
`/home/anya/.cache/pageswiki-backups/pre-domain-entry-6a73yw/app.sqlite`
|
||||
and `app2.sqlite`, directory private / files 0600; both `PRAGMA quick_check=ok`.
|
||||
- Deployed accumulated date-path navigation, atomic article composer, Domain
|
||||
entry-settings gear/dialog and signed manifest v2 to app2 first, then app.
|
||||
- Continued implementation: signed manifest capability proof in enrollment;
|
||||
unknown/legacy approved peers block entry-setting updates with 409 and UI guidance.
|
||||
The check covers all approved Campus peers because they share a Campus manifest.
|
||||
- Final running image on both instances:
|
||||
`sha256:0dbcb4aacbc924855f0b686a859bd10c7932eea9d1736fc9f4be9a6337b694ae`.
|
||||
app healthy, app2 running, zero restarts; Host-routed health checks both OK.
|
||||
`https://pages.anya.jp/` returned 200. Served periodicals.js hash matches source.
|
||||
Running template includes `data-domain-entry-open`; authenticated gear/modal and
|
||||
posting interactions were exercised in isolated Chromium fixtures, not by creating
|
||||
production administrator sessions.
|
||||
- Actual approved ext-node enrollment reports manifest_version=2. Old pending
|
||||
fingerprint remains pending; no approval or identity changes were made.
|
||||
- Main DB before/after: 1454 Objects and 4 publication entries. No entry settings,
|
||||
article content, user roles or publication grants were changed during deployment.
|
||||
- Tests: full `go test ./...`, vet, diff check, browser fixtures at desktop/mobile,
|
||||
capability proof validation, legacy downgrade detection, incompatible-peer
|
||||
rejection, signed manifest integrity/rollback and focused race tests passed.
|
||||
- Remaining: anonymous metadata/calendar publication approval, Domain-create form
|
||||
integration, entry-control release/GC, apply ACK/freshness and journal/outbox delivery.
|
||||
|
||||
- [x] Diary/blog initial built-ins — 2026-09-16.
|
||||
`content.diary` and `content.blog` provide Domain-scoped, default-disabled
|
||||
settings, Page UUID metadata, calendar/recent entries, category/month/mine
|
||||
filters, and register/edit/unregister dialogs. Canonical content and revisions
|
||||
stay in ordinary Pages. Metadata writes reserve SQLite's writer before live
|
||||
membership, Path binding, grant/Locality and version checks; own-user Wiki
|
||||
authority matches the semantic editor. Metadata journal commits atomically;
|
||||
unregister/re-register generations prevent ABA replay. Private metadata is
|
||||
not exposed anonymously; Page publication behavior is unchanged. Atomic
|
||||
new-post composition, public metadata approval/feeds, comments and tDiary
|
||||
import remain [explicit follow-ups](diary-blog-plugins.md).
|
||||
Full Go suite PASS (Server 12.417 s), focused race PASS (Server 5.745 s,
|
||||
Store 1.790 s), vet/JS syntax/diff checks PASS; combined config, public
|
||||
navigation, governance and diary/blog Chromium PASS (9.332 s). PC/mobile
|
||||
screenshots inspected under `/tmp/pageswiki-periodicals-review/`.
|
||||
DB-only backups at
|
||||
`/home/anya/.cache/pageswiki-backups/pre-periodicals-drFK6Ljf/` are mode 0600;
|
||||
both quick_check results are `ok`. Backups use low-priority I/O.
|
||||
Rebuilt image:
|
||||
`sha256:9948aca99fa03eb43dda06a03ae59a680cad3d5b5284fd6c2217e09d69f75c22`.
|
||||
Deployed to both nodes: local Host-routed health checks return `ok`, zero
|
||||
restarts, served JS matches source. Both have all three additive tables and
|
||||
zero enabled instances. Main anonymous root remains 200; diary/blog require
|
||||
login (303) and unauthenticated metadata APIs return 401. Managed legacy-mode
|
||||
diary also requires login. Existing main objects (1,448), publication
|
||||
manifest (one) and approved entries (four) remain unchanged; no plugin was
|
||||
enabled and no article was registered in production during verification.
|
||||
- [x] Public children view controls now match the authenticated icon order and
|
||||
sizing (`▦`, `☷`, `≡`), with localized tooltips/accessible labels and retained
|
||||
active state. Desktop/mobile Chromium PASS (1.948 s), focused navigation tests
|
||||
PASS (0.454 s), JS syntax and diff checks PASS. Rebuilt image:
|
||||
`sha256:35b1fd0e0c291e42769b81dd50a53d237b94071431387c41b289d692a578e2b7`.
|
||||
- [x] Anonymous navigation usability — 2026-09-16 23:19 JST.
|
||||
Added public root/virtual-parent directory landings and read-only
|
||||
`/v/browser/{path}`; separate Page/child-folder links, compact responsive
|
||||
header and direct City exits. Public tree now supports all/per-folder
|
||||
expand/collapse, name/Path filtering and arrow/Home/End navigation. Component
|
||||
sorting keeps `/a/x` before `/a-b` for correct branch operations. Children
|
||||
requests are capped at three concurrent fetches, cancellable and timed out,
|
||||
with generation-safe retries and view-only session preference. Initial
|
||||
directory/pagination links and macro fallback links work without JavaScript.
|
||||
Full Go suite PASS (Server 12.387 s), vet/JS syntax/diff checks PASS;
|
||||
focused race suite PASS (Server 7.287 s); broad Chromium suite PASS (19.837 s),
|
||||
including anonymous navigation at 1440 px and 390 px. Screenshots inspected:
|
||||
`/tmp/pageswiki-public-navigation-review/public-navigation-{1440,390}.png`.
|
||||
Tests cover failure/retry, view switching, hierarchy prefix collisions,
|
||||
pagination/exclusions, private-parent body suppression, bad credentials,
|
||||
mutation denial and warm-cache revocation. See [contract](public-navigation.md).
|
||||
Both nodes rebuilt/deployed with
|
||||
`sha256:cf75c402c04cb185e1c7965480c35b352e2182c857af9367e7b3dfa672a68597`.
|
||||
Both local Host-routed health endpoints return `ok`, zero restarts; managed
|
||||
home returns 200. Main anonymous root/browser/tree/children/City return 200
|
||||
(approximately 1–21 ms in local checks); protected autoplan remains 401.
|
||||
Public directory headers retain private/no-store and inert CSP. Served JS/CSS
|
||||
hashes match source on both nodes. No new schema migration; existing main
|
||||
publication remains one manifest/four entries and its governance, topology,
|
||||
binding, hash and head checks pass. No approvals or production content were
|
||||
changed; no public TLS ingress change or verification is claimed.
|
||||
- [x] Permission-aware public navigation — 2026-09-16 22:44 JST.
|
||||
Ordinary approved Pages now offer asynchronous children, structural breadcrumbs,
|
||||
read-only tree and filtered City Map; remove the public download control.
|
||||
Navigation-free presentation remains a future share-URL concern. Cached data
|
||||
uses SQLite mutation generations; authenticated membership/ACL decisions are
|
||||
evaluated per request. City reload/retry discards previous authorized labels
|
||||
before revalidation. See [navigation contract](public-navigation.md).
|
||||
Full Go suite PASS (Server 9.335 s), vet, JS syntax and diff checks PASS;
|
||||
broad Chromium suite PASS (16.670 s); focused navigation/ACL/publication race
|
||||
tests PASS (Server 7.529 s, Store 14.706 s). Coverage includes warm-cache
|
||||
publication withdrawal and group removal without data-cache invalidation.
|
||||
DB-only SQLite backups in
|
||||
`/home/anya/.cache/pageswiki-backups/pre-public-navigation-FMqnj5pu/` are 0600;
|
||||
both quick_check results are `ok`.
|
||||
Both nodes rebuilt/deployed with
|
||||
`sha256:aade0a87dbdd0966c92908836dda57f5d5a3440028cb2181194104c8ede9f9ae`.
|
||||
Host-routed local health checks return `ok`, both running with zero restarts;
|
||||
managed home returns 200. Main anonymous tree/children/City HTML/map API return
|
||||
200 (approximately 1–18 ms in the local smoke check), while autoplan remains
|
||||
401. Tree response is private/no-store with inert CSP; main served JS hashes
|
||||
match source. Additive navigation schema has 45 invalidation triggers on each
|
||||
node. Existing main publication records remain one manifest/four entries;
|
||||
managed records remain zero. No publication was activated or revoked by this
|
||||
deployment. Public TLS ingress was not changed or certified by local checks.
|
||||
- [x] Document hierarchical approval requirements and approver Inbox delivery.
|
||||
[Approval design](publication-approval-inbox.md) defines inherited required
|
||||
floors, immutable review subjects, live reviewer authorization, transactional
|
||||
outbox/retry and recipient-private notifications. AP-1 through AP-6 remain
|
||||
unchecked implementation work; this design does not enable a new workflow.
|
||||
- [x] Named user/group locality read or read/write permissions, stable subject
|
||||
identity resolution, superior-cap/authority-rank restriction preservation,
|
||||
next-request membership checks, Object alias caps and SQLite namespace fences.
|
||||
Explicit bounded anonymous current-revision approval/withdrawal now serves a
|
||||
separate inert semantic Viewer and streaming raw-media path with safe OGP.
|
||||
Per-scope publication generations prevent replaying pre-revocation consent.
|
||||
See [scope, operational limitations and follow-ups](locality-access-publication.md).
|
||||
Whole Go suite passes (Server 10.176 s, Store 4.560 s), focused race suite
|
||||
passes (Server 6.206 s, Store 1.013 s), and approval/governance Chromium
|
||||
checks pass (1.994 s); the broader browser suite passed (27.547 s).
|
||||
Source-Domain restrictions also clamp exceptional foreign Object grants;
|
||||
a regression verifies that these exceptions cannot bypass the new ACLs.
|
||||
Vet, JS syntax and diff checks pass. SQLite backups (DB only) are under
|
||||
`/home/anya/.cache/pageswiki-backups/pre-locality-access-lpnkGqwV/`, mode 0600;
|
||||
both pass quick_check. Both existing nodes deployed as
|
||||
`sha256:4a797ee34ef0c0fe0d48cea891a943393f0f722f07c192879f61b5dc3456ba9d`.
|
||||
Host-routed local health checks return `ok`, both running with zero restarts.
|
||||
Served governance JS hashes match the workspace on both listeners. All five
|
||||
new access/publication tables exist and remain empty on both DBs: no production
|
||||
restriction or public approval was created. Main anonymous home remains 303,
|
||||
managed legacy home 200; anonymous access/publication administration requests
|
||||
are denied (main 401, managed 403). Managed public TLS/vhost remains the
|
||||
previously recorded infrastructure caveat; these are local listener checks.
|
||||
|
||||
- [x] Quartier/Spot co-owner appointments, Domain/local publication-cap drafts,
|
||||
epoch/topology concurrency checks and in-transaction membership/authority
|
||||
revalidation; local before/after audit and Japanese/English modal settings.
|
||||
Includes bounded appointment-authorized member lookup. Full impact reports,
|
||||
structural mutation fences and anonymous publication remain pending; existing
|
||||
production visibility is unchanged. See [governance contract](locality-publication-ownership.md).
|
||||
Verification: full Go suite (Server 8.584 s, Store 4.015 s), focused race
|
||||
tests (Server 2.698 s, Store 1.015 s), combined City/governance/search/HTML
|
||||
Chromium regressions (16.275 s), vet, JS syntax and diff checks pass.
|
||||
Pre-migration SQLite backups (DB only, not a complete DR package) are under
|
||||
`/home/anya/.cache/pageswiki-backups/pre-governance-aNwngqHe/`, mode 0600.
|
||||
Both backups pass `PRAGMA quick_check`. Both existing app nodes deployed as
|
||||
`sha256:dc6960ba1b01800b08351f660d20848dcca0e0f7f382fe18e362d93f7171d147`.
|
||||
Local Host-routed health checks return `ok`, zero restarts; all four additive
|
||||
governance tables exist on both DBs, with no owners/policies automatically
|
||||
inserted. Served governance JS hashes match the workspace on both nodes.
|
||||
Anonymous governance requests are denied (main 401, managed 403); main home
|
||||
still redirects to login (303). No production owner appointment or public
|
||||
policy change was made as a smoke test. Existing managed public TLS caveat
|
||||
remains; these are local listener/Host checks, not a TLS infrastructure fix.
|
||||
- [x] P0 inert HTML display boundary across semantic/home/profile/object/history/
|
||||
preview/print and HTML/Markdown Editor previews; canonical content unchanged.
|
||||
Application nonce CSP, forged macro-hook stripping, escaped failure fallback,
|
||||
bounded/cancellable City macro reads, and ACL-checked sandboxed diagram cache.
|
||||
See [precise policy and compatibility](html-projection-trust.md). Owner/public
|
||||
APIs and new anonymous access remain disabled/pending. Final full Go suite
|
||||
passes (Server 7.866 s), focused race tests pass (Server 4.247 s, Store
|
||||
1.057 s), and final HTML/PDF/archive/editor/bookmark Chromium tests pass
|
||||
(14.006 s). Broader City/search/login Chromium checks also passed (27.590 s).
|
||||
`go vet`, editor JS syntax and diff checks pass. Read-only compatibility
|
||||
sampling was limited to 500 HTML revisions; it was not a complete Path audit.
|
||||
Deployed both existing nodes as
|
||||
`sha256:41cd97c7705b8be6b1bf763aee7678c5d510878d5ec6d78aa3b3792a7eb32517`.
|
||||
Both local Host-routed `/health` endpoints return `ok`, zero restarts; managed
|
||||
home returns 200 with nonce CSP, nosniff, private/no-store and
|
||||
`X-PagesWiki-HTML-Policy: inert-v1`. Main anonymous home still redirects to
|
||||
login (303). Both served Editor scripts match workspace SHA-256. No schema
|
||||
migration, production document rewrite, visibility change or TLS change.
|
||||
Managed public TLS/vhost caveat from the earlier social-card check remains
|
||||
outside this deployment; these checks do not claim public HTTPS there works.
|
||||
- [x] OGP/X cards for existing public semantic Page/home/City HTML, bounded
|
||||
canonical text extraction, configured-host canonical/image URLs, original
|
||||
image-document cards and an application-owned cached PNG fallback. No crawler
|
||||
auth bypass, external image fetch, schema migration or visibility change.
|
||||
Private/enforcing HTML suppresses metadata and adds noindex. See
|
||||
[social card policy](social-link-cards.md). Full Go suite (Server 6.818 s),
|
||||
social race tests (2.434 s), City/search Chromium checks (3.846 s), vet and
|
||||
diff checks pass. No claim of actual X post/card display; no post was sent.
|
||||
Deployed both nodes as
|
||||
`sha256:a16fa6cbe8a3a6b5141d7d29de0e6faef67989285a9983b2ffa306d4e016b75c`;
|
||||
both health endpoints return `ok`, zero restarts. Managed-host anonymous home
|
||||
includes HTTPS OGP/card URLs, image HEAD returns 200/image/png (7,327 bytes),
|
||||
main `pages.anya.jp` still redirects anonymous crawlers (303). The common
|
||||
image is also reachable through public HTTPS; its 1200×630 output was visually
|
||||
inspected. No private production Page was made public for this test.
|
||||
External caveat: `https://wiki.extpages.anya.jp/` and its image fail TLS with
|
||||
`unrecognized name`; managed-host checks above used its local app listener
|
||||
with the configured Host. Public HTTPS image success was on `pages.anya.jp`.
|
||||
Fix the managed FQDN's TLS/vhost before expecting external cards there.
|
||||
- [x] City named-reference follow-up: qualified Street URLs, shared links,
|
||||
explicit UUID locality search, ancestor-aware lightweight details and literal
|
||||
Page links in both the map and inspector. No schema/data migration required.
|
||||
Whole-map loading is also deferred out of simple City breadcrumb macros.
|
||||
Verification: full Go suite, City/search browser regressions (including
|
||||
repeated Street names and three initial-focus levels), `go vet` and JS syntax
|
||||
checks pass. City/search race tests also pass (Store 35.000 s, Server
|
||||
7.391 s); the combined Chromium suite passes in 13.166 s. The HTML trust gate
|
||||
and broader CITY-A–D work remain open.
|
||||
Deployment: both existing app nodes rebuilt/recreated as
|
||||
`sha256:8e53fec5c485ed5763bf44705cfdf4071d04f2b8932dca038148eedda26f4c42`.
|
||||
Both health endpoints return `ok`, zero restarts; main unauthenticated City
|
||||
request redirects (303), managed-host search returns 200 under its existing
|
||||
policy. Served City map/estate scripts match workspace SHA-256 hashes.
|
||||
- [x] OIDC issuer JWKS signatures, claim validation, bounded discovery/key cache;
|
||||
one-use browser state and collision-safe external account linking.
|
||||
- [x] Bounded SMTP delivery, safe headers/mailboxes, live account checks.
|
||||
- [x] Campus-admin inheritance revocation, provenance and local-right preservation.
|
||||
- [x] Recursive Path mutations: transactional authorized snapshots and literal prefixes.
|
||||
- [x] Browser mutation CSRF protection and explicit credential precedence/logout;
|
||||
browser/API purpose prefixes and atomic active-session checks.
|
||||
- [x] Object authority scope and atomic creation provenance; safe all-alias purge.
|
||||
- [x] Signed manifest allocation/application/checkpoint atomicity and authority guards.
|
||||
- [x] City map/detail/Page list read filtering and private response caching policy.
|
||||
- [x] Batch/request-scoped read authorization to reduce listing query amplification.
|
||||
- [x] PDF/archive metadata scheduler projections with persistent bounded cache.
|
||||
- [x] City generator Worker and directional keyboard navigation.
|
||||
- [x] Search results: compact overview, full Page Path, matching-text excerpts and
|
||||
safe keyword highlighting; retain list/detail/thumbnail integration and read ACLs.
|
||||
- [x] Object/Revision metadata pagination and localized history navigation.
|
||||
- [x] Literal URL encoding in children list/detail/icon projections.
|
||||
- [x] City one-connection-safe read snapshot and literal boundary lookup/health.
|
||||
- [x] Atomic bounded zombie GC and Domain-provenance-scoped HTTP administration.
|
||||
- [x] Integrated Go/browser tests, rebuild, and both instance health checks.
|
||||
|
||||
Update this list only after the corresponding implementation and verification.
|
||||
The broad phase checkboxes stay open when only a bounded slice has landed.
|
||||
|
||||
Focused implementations, constraints and regressions are linked from
|
||||
[Implementation status](implementation-status.md#confirmed-corrections-2026-09-14).
|
||||
## Verification and deployment
|
||||
|
||||
Completed 2026-09-14 01:43 JST. All source changes were frozen before rebuilding;
|
||||
later edits only recorded the final outcomes in design documents.
|
||||
|
||||
- Final `GOMAXPROCS=2 GOCACHE=/tmp/pageswiki-go-cache go test ./... -count=1`:
|
||||
PASS for all packages (server 5.947 s, store 3.105 s).
|
||||
- Targeted server/store `-race` covering authentication, inheritance,
|
||||
recursive/Object integrity, federation, GC, City and metadata projections:
|
||||
PASS (server 21.774 s, store 38.202 s). Independent focused race runs also
|
||||
covered search, pagination and the final deterministic GC regression fixture.
|
||||
- Opt-in Chromium: 13 suites PASS (48.544 s), covering real HttpOnly-cookie
|
||||
login/logout, City normal/popup/mobile and Worker/navigation, search in all
|
||||
three modes, PDF/archive/comic metadata, settings, execution monitor,
|
||||
bookmark/Vim settings UI and editor/home. This does not validate the paused
|
||||
vim.wasm runtime. Artifacts: `/tmp/pageswiki-hardening-final`.
|
||||
- `go vet ./...` and `git diff --check`: PASS.
|
||||
- Before schema migration, online SQLite backups of both nodes completed with
|
||||
`PRAGMA quick_check` = `ok`. Directory:
|
||||
`/home/anya/.cache/pageswiki-backups/pre-hardening-20260914-1wH8jcKm/`.
|
||||
`app.sqlite` and `app2.sqlite` are mode `0600`; their containing directory is
|
||||
private. These are DB snapshots, not complete Document-store/key DR backups.
|
||||
- `docker compose build app` and `docker compose up -d --no-deps app app2`:
|
||||
PASS. Both containers run image
|
||||
`sha256:dc0ac3305c6a6abb42d84e56c8291cabc9c582a421f4ce91ca4276b123735ad2`,
|
||||
with no restart loop. Both local `/health` endpoints return `ok`.
|
||||
- Main-instance search CSS and City Worker client hashes match the working
|
||||
files; managed-instance search CSS matches too when using its configured Host.
|
||||
`https://pages.anya.jp/` and the protected main search route return the
|
||||
expected unauthenticated `303`; the managed Domain search route returns
|
||||
`200` under its existing read configuration. A foreign-Origin unsafe request
|
||||
is rejected with `403`. No production account credentials were used.
|
||||
|
||||
Browser behavior tests used isolated fixture databases, not production content.
|
||||
Live external OIDC/SMTP provider credentials and production multi-user flows
|
||||
were not exercised; protocol, denial and concurrency coverage used test fixtures.
|
||||
|
||||
### Search timeout follow-up — 2026-09-14 03:47 JST
|
||||
|
||||
The user reported a search timeout after the initial deployment. Read-only
|
||||
production-data investigation found a Path-first repeated FTS scan and
|
||||
unbounded snippet input work, neither represented by the original small fixtures.
|
||||
Corrected the join order, rowid excerpt lookup, per-document/total snippet input
|
||||
budgets and optional 400 ms enrichment deadline. Results survive snippet-only
|
||||
timeouts; genuine search failures now have localized, non-leaking retry UI.
|
||||
See [evidence and remaining search limits](search-results.md#timeout-regression-and-correction-2026-09-14).
|
||||
|
||||
- Full Go suite PASS (server 6.869 s, store 3.511 s); search `-race` PASS
|
||||
(server 2.967 s, store 8.063 s); Chromium search PASS (0.740 s);
|
||||
`go vet ./...` and `git diff --check` PASS.
|
||||
- Added query-plan assertions, a 600-Page/1,200-Revision regression, Unicode
|
||||
byte-budget/alias tests, deadline/error tests and large-body UI coverage.
|
||||
- Read-only diagnostics against the existing main DB passed twice, with
|
||||
representative search processing times around 72–506 ms. No production
|
||||
account credentials or Page content were output or changed.
|
||||
- Rebuilt/deployed both app nodes with image
|
||||
`sha256:0f10da866a03167da7811ddc88f66d6a65bd27aae17557c824a9f7b5071b88a8`.
|
||||
Both `/health` endpoints return `ok`, no restart loop, search CSS matches
|
||||
source on both configured hosts. No schema/index migration was needed.
|
||||
|
||||
### City-first search and filters — 2026-09-14 04:05 JST
|
||||
|
||||
Added permission-filtered, metadata-only Quartier/Street/Spot results above
|
||||
Pages. Added a compact options disclosure for MIME/suffix categories, a single
|
||||
extension, and creation/update calendar-date ranges. Options persist in the
|
||||
GET URL and retry link. File-specific filters exclude City metadata; date
|
||||
filters apply to both. City/Page queries share the existing deadline and do
|
||||
not load the full City graph. See [search contracts](search-results.md#city-first-results-and-search-options).
|
||||
|
||||
- Full Go suite PASS (server 6.746 s, store 3.470 s); combined search/City
|
||||
`-race` PASS (server 4.288 s, store 10.257 s). Added filtered-query plan
|
||||
coverage also passed in the final Store search race run (18.373 s).
|
||||
- Chromium desktop/mobile (1440/390 px) PASS, including real City results,
|
||||
safe links, match highlights, preserved filters, all Page view modes and
|
||||
separation from file multi-selection. Final run: 1.173 s. Screenshots:
|
||||
`/tmp/pageswiki-search-city-final/search-results-desktop.png` and
|
||||
`search-results-mobile.png`. `go vet ./...` and `git diff --check` PASS.
|
||||
- Read-only main-DB verification: representative keyword search 79–515 ms,
|
||||
filter-only cases 1–6 ms, City metadata 2 ms. These are Store timings, not
|
||||
authenticated production HTTP measurements. No schema migration is needed.
|
||||
- Both app nodes rebuilt/deployed with image
|
||||
`sha256:1f6d64c354e940c0941db9914a836f47e7285ac962a9c68f9b6cebcddd2e0dc3`.
|
||||
Both `/health` endpoints return `ok`, zero restarts, source CSS hashes match
|
||||
each configured host. Protected public search returns the expected `303`
|
||||
without credentials; managed-node filter-only search returns `200` under
|
||||
its existing read configuration.
|
||||
|
||||
## Deliberate high-risk deferrals
|
||||
|
||||
- Executable authored-HTML compatibility is not supported. Normal HTML now uses
|
||||
the inert projection boundary; any future executable mode requires separate
|
||||
origin/capability approval and isolation tests. Public locality ACLs and owner
|
||||
governance still require transaction/cache revocation gates. See
|
||||
[policy and acceptance tests](html-projection-trust.md).
|
||||
- HA/LB writable metadata, controller DR promotion and distributed job leases:
|
||||
need a selected replication strategy, fencing, key custody and fault drills.
|
||||
- Untrusted third-party code/plugin execution and native application launch:
|
||||
need isolated runtime, signature/capability lifecycle and a separate helper
|
||||
trust model; existing hosted editor integrations remain supported.
|
||||
- Production S3/SSHFS/WebDAV/MWDB/Karton/SNMP/LDAP integrations: implement only
|
||||
after endpoint/credential policy and test services are available. No fabricated
|
||||
live integration claims or unrequested credential/infra provisioning.
|
||||
- Broad notifications/inbox, comments, diary/tDiary import, rankings and external
|
||||
search: retain the existing detailed contracts; gate on transactional activity
|
||||
provenance, privacy/retention and authorization. Small prerequisites may land
|
||||
first, without claiming those product features complete.
|
||||
- vim.wasm runtime remains explicitly on hold from the earlier user instruction.
|
||||
|
||||
These are not removed from the roadmap. Lower-risk outstanding items that do not
|
||||
fit this batch remain unchecked, with the next sequence recorded at handoff.
|
||||
|
||||
## Next implementation sequence
|
||||
|
||||
1. Complete locality Page/alias/dependency impact reports and structural mutation
|
||||
fencing on the implemented owner/draft-policy foundation. Require fresh
|
||||
activation consent and endpoint/cache revocation coverage before anonymous
|
||||
access; never silently activate saved drafts.
|
||||
2. Complete mutation authority/version fencing and local/external account
|
||||
ownership lifecycle, then remaining endpoint/adapter denial audits.
|
||||
3. Add shallow, paginated City projections and transactional mutation outbox /
|
||||
reconciliation provenance; retain manual curation when deriving from URLs.
|
||||
4. Replace remaining full directory aggregates and historical/raw-HTML FTS work
|
||||
with current-only bounded projections; add cancellation-aware streaming or
|
||||
immutable-hash clone operations for large binary changes.
|
||||
5. Resume activity/notification and trusted system-extension product slices
|
||||
after those authority and event-provenance prerequisites. Keep HA/DR and
|
||||
external-service provisioning behind their separately documented decisions.
|
||||
@@ -0,0 +1,146 @@
|
||||
# Home navigation and hosted Vim follow-up
|
||||
|
||||
## Application assets and editor routes
|
||||
|
||||
Templates load CSS and JavaScript from `/static/`. The legacy
|
||||
`/o/path:/system/static/` namespace remains a read-only compatibility alias to
|
||||
the confined static file server. It is not a UUID/Object address and must not
|
||||
be sent through document authorization. Other `/o/` addresses remain protected.
|
||||
|
||||
`/e/docs` and `/e/-/docs` both edit `/docs`; `/e/`, `/e/-`, and `/e/-/`
|
||||
edit `/`. The authorization target and editor use the same path decoder.
|
||||
Database resolution errors must not be mistaken for a missing page.
|
||||
|
||||
## Bookmark sections
|
||||
|
||||
The Domain-scoped `home_bookmarks` JSON array stays backward compatible:
|
||||
|
||||
```json
|
||||
[
|
||||
{"kind":"section","label":"Reference","href":"","children":false},
|
||||
{"kind":"url","label":"Example","href":"https://example.com/"},
|
||||
{"kind":"section","label":"Documents","href":"/docs","children":true}
|
||||
]
|
||||
```
|
||||
|
||||
A section starts a card and owns subsequent links until the next section.
|
||||
Legacy links before any section form a default card. `children=true` replaces
|
||||
that section's displayed links with the immediate children of its parent Path;
|
||||
manually configured links remain stored for when the toggle is turned off.
|
||||
Virtual folders are included, but `/u`, `/_`, and `/-` are excluded at the root.
|
||||
|
||||
Management is available through a small settings icon on every home layout to
|
||||
Domain/Campus admins. A native modal dialog provides focus containment, Escape
|
||||
and close-button dismissal, while retaining unsaved edits if closed. The same
|
||||
section-card editor is used at `/-/sys/config?panel=bookmarks`. Section moves
|
||||
and deletion operate on the entire group; links can be moved to another
|
||||
section using a selector. Page content is never deleted by bookmark deletion.
|
||||
Saves use the existing server validation and request JSON acknowledgement;
|
||||
errors remain in the form instead of navigating away. On success the home
|
||||
reloads its cards. A navigation warning protects unsaved edits. Classic and directory layouts show cards; the
|
||||
search-only layout retains its search focus while allowing management.
|
||||
Limits: 64 rows total, including at most 16 section rows. Labels and URLs are
|
||||
validated server-side; invalid submissions leave previous settings untouched.
|
||||
Path URLs escape literal percent signs, fragments, spaces and Unicode.
|
||||
|
||||
`GET /v/bookmarks?section=<array-index>&after=<last-child-name>` loads children
|
||||
as JSON. It resolves the section within the active Domain, checks the parent
|
||||
and each child against current read permissions, and returns at most 80 scanned
|
||||
children per request with a continuation cursor. No revision bodies, metadata
|
||||
stats, thumbnails or full-Domain listing are loaded. Queries use the Path
|
||||
prefix index and request cancellation. Browser loading is lazy and limited to
|
||||
two concurrent requests. Responses are `no-store`, avoiding stale permission
|
||||
results. Empty filtered pages may still contain a continuation cursor.
|
||||
|
||||
Follow-up: batch authorization and materialized immediate-child indexes for
|
||||
extremely large subtrees; optimistic concurrency for multiple administrators
|
||||
editing the same configuration (currently last successful save wins).
|
||||
|
||||
## vim.wasm configuration and plugins
|
||||
|
||||
The pinned runtime writes injected files using `wx+`: an existing bundled
|
||||
`/.vim/vimrc` is skipped, despite the package README suggesting overwrite.
|
||||
Use a new `/pageswiki.vimrc` MEMFS file and explicit `-u /pageswiki.vimrc`.
|
||||
This is verified inside the real Wasm binary, not merely by HTTP success.
|
||||
|
||||
The Gateway image bundles the existing licensed Hack Nerd Font locally.
|
||||
`document.fonts.load('16px PagesWikiHack')` completes before startup so canvas
|
||||
cell widths use the final font. `guifont=PagesWikiHack:h16` controls actual Vim
|
||||
rendering; CSS alone does not. Font, Worker and Wasm retain same-origin isolation.
|
||||
|
||||
`assets/vimwasm/app/vimrc` sets line numbers, cursor line, status line, search,
|
||||
indentation and dark colors. `pageswiki.vim` is a bundled pure-Vimscript plugin
|
||||
in `/.vim/plugin`, with an explicit runtimepath. Available operations:
|
||||
|
||||
- `:Files` / Space+f: `:find` with Tab completion beneath `/work`.
|
||||
- Space+b: buffer listing and selection.
|
||||
- `[b` / `]b`: previous/next buffer; `:next` still traverses arguments.
|
||||
- Space+w: write; Space+/: clear search highlight.
|
||||
|
||||
The existing BufWritePost export and scoped Gateway write-back remain in use.
|
||||
The base settings are image-managed. Domain administrators can customize them
|
||||
at `/-/sys/config?panel=adapter-vim.wasm`, separately from connection settings.
|
||||
|
||||
### Domain customization contract
|
||||
|
||||
`POST /-/sys/config/vim` stores one `vim_wasm_settings` JSON config value per
|
||||
Domain: `enabled`, `font_size` (10–32), `vimrc`, `colorscheme`, `color_name`.
|
||||
The settings panel uploads UTF-8 files into editable text fields, supports
|
||||
download, custom-colorscheme removal, and reset to defaults. Each script is
|
||||
limited to 64 KiB; NUL bytes, invalid UTF-8 and path-bearing filenames are
|
||||
rejected server-side. One custom colorscheme is managed initially; uploading
|
||||
another replaces that slot. Nothing is written into the host filesystem.
|
||||
|
||||
Only active builtin Domain/Campus administrators can save; readonly accounts
|
||||
cannot mutate executable configuration even if they retain group membership. A supplied Origin must
|
||||
match the request Host. Vimscript is executable trusted configuration and may
|
||||
invoke browser integration features; it is not a safe format for untrusted
|
||||
uploads. This is explicitly disclosed in the UI. No server shell, terminal,
|
||||
package manager or arbitrary process execution is exposed.
|
||||
|
||||
An authorized `vim.wasm` workspace response includes the session Domain's
|
||||
`vim_settings`. The Gateway retains that snapshot in its server-side session
|
||||
and supplies it with `GET /vim/api/session` (`no-store`). Other adapter types
|
||||
do not receive these settings. Changes apply on a newly opened session.
|
||||
|
||||
MEMFS initialization order: bundled defaults, configured font size, source
|
||||
`/pageswiki-user.vimrc`, then a fixed-path custom colorscheme under
|
||||
`/pageswiki-config/colors/pageswiki_custom.vim`. A conventional uploaded name
|
||||
matching `[A-Za-z0-9_-]+.vim` is also registered as a local alias before the
|
||||
user vimrc is sourced, so `colorscheme uploaded` works for `uploaded.vim`.
|
||||
Other uploaded filenames remain display metadata; no uploaded name is inserted
|
||||
into a command. Disabled customization
|
||||
retains source text but does not execute it. `?safe=1` on the Vim frontend URL
|
||||
skips all Domain customizations, including the font size, so a broken startup
|
||||
script cannot prevent recovery through the defaults and settings panel.
|
||||
|
||||
Follow-up: versioned per-user settings, multiple named scheme slots, and an
|
||||
isolated test-startup window. A restricted terminal is not needed for the
|
||||
current configuration workflow. Any future terminal bridge needs a separate
|
||||
capability, runtime sandbox, resource limits and explicit authority design.
|
||||
|
||||
Third-party plugin policy: vendor pinned, licensed pure-Vimscript files into
|
||||
MEMFS and test against this old pinned Vim feature set. Candidate classes are
|
||||
surround/text-object/comment helpers without native or network dependencies;
|
||||
no unreviewed third-party plugin is added by this change. Runtime vim-plug
|
||||
installation is unsupported. Vendoring `fzf.vim` alone is insufficient because
|
||||
fzf requires a native executable; shell/system()-dependent plugins belong in
|
||||
code-server or need a separately designed Wasm/JavaScript bridge.
|
||||
|
||||
## Verification
|
||||
|
||||
`go test ./...` includes asset routing, matching editor/authorization paths,
|
||||
section persistence, invalid input, admin restrictions and child access tests.
|
||||
Opt-in browser tests:
|
||||
|
||||
```sh
|
||||
PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run 'TestEditorHomeChromiumSmoke|TestConfigChromiumSmoke|TestVimWasmChromiumSmoke|TestBookmarkAndVimSettingsChromium' -count=1
|
||||
```
|
||||
|
||||
The Vim test uses CDP real-time waiting (virtual time can finish before Worker
|
||||
compilation), two isolated files and a fake save endpoint. It asserts the actual
|
||||
guifont, loaded `:Files` command, argument count and absence of startup errors.
|
||||
It also edits a buffer with `:write` and verifies that BufWritePost exports the
|
||||
changed bytes to the fake Gateway save endpoint. Both custom settings and safe
|
||||
mode are exercised. UI tests open and close the settings dialog, save a
|
||||
section with automatic children, and upload/save vimrc and colorscheme files.
|
||||
@@ -0,0 +1,317 @@
|
||||
# HTML projection trust boundary
|
||||
|
||||
Audited and remediated: 2026-09-14; controlled external-resource extension:
|
||||
2026-09-23. Status: **normal HTML projections use `controlled-v2`**. Authored
|
||||
active HTML remains denied by default. A Domain administrator may separately
|
||||
approve an exact external resource URL; approved JavaScript is intentionally
|
||||
executable and is therefore a high-trust Domain configuration action.
|
||||
|
||||
## Implemented contract — controlled-v2
|
||||
|
||||
`internal/server/html_projection.go` applies a parser-based allowlist using
|
||||
[bluemonday](https://github.com/microcosm-cc/bluemonday), pinned to v1.0.27. The
|
||||
sequence is bounded token preflight → authored allowlist → tree normalization
|
||||
and authorized macro expansion → diagram references → final allowlist. This
|
||||
changes display projections only, not saved Documents, hashes or Revisions.
|
||||
|
||||
- All known authored-HTML surfaces share this boundary: semantic Viewer,
|
||||
configured home, profile Wiki, object UUID, historical Revision, Preview,
|
||||
print, and HTML/Markdown editor preview. Object viewing checks adapter MIME
|
||||
kind; non-HTML is escaped text or a download link, never blind HTML.
|
||||
- Formatting, tables, code, internal/external links and local passive images
|
||||
are supported. Author scripts, event attributes, forms, iframes, SVG/MathML,
|
||||
styles, arbitrary classes and `data-*` hooks are removed. This is intentional
|
||||
compatibility tightening, not a source migration or an executable trust flag.
|
||||
- By default images must resolve to local `/v/raw/`, `/_/obj/`, `/static/`, or
|
||||
`/o/path:/system/static/` resources after path normalization. External images,
|
||||
relative semantic URLs, data images and arbitrary authenticated GET targets
|
||||
are not loaded by authored markup. Use immutable asset/raw references.
|
||||
- The Domain setting “Approved external resources” is the only exception.
|
||||
External images require an exact normalized HTTPS URL match. External CSS
|
||||
and JavaScript require both an exact HTTPS URL and pinned SHA-256 SRI. The
|
||||
server discards authored integrity/crossorigin attributes and emits canonical
|
||||
`integrity` and `crossorigin=anonymous` attributes from configuration.
|
||||
Approval entries are converted to unpredictable text placeholders before the
|
||||
authored and generated allowlists, then restored as server-authored tags;
|
||||
macro output therefore cannot forge an approval. CSP is derived from the same
|
||||
list: image/style origins and JavaScript content hashes are added while
|
||||
`connect-src` remains same-origin. Revocation takes effect on the next render.
|
||||
Wildcards, HTTP, credentials, fragments, inline script/style and event
|
||||
attributes remain unsupported. Because approved JavaScript can invoke
|
||||
same-origin APIs as the viewer, only immutable audited code should be added.
|
||||
- Authored IDs and fragment targets are SHA-256-namespaced to avoid application
|
||||
DOM collisions. Only code-language classes survive the authored pass.
|
||||
- Only text-node macros expand, not macros in attributes, links or code.
|
||||
Application-owned children hooks cannot be forged by authored `data-*`.
|
||||
Each macro is dispatched once; lookup failures remain escaped authored text,
|
||||
including entity-decoded tags and nested-macro-looking strings.
|
||||
Existing read filtering is retained; City reads inherit request cancellation
|
||||
and use bounded Store projections. Macro output is not cached across readers.
|
||||
- Input is at most 1 MiB; token/tree budgets are 16,384 with depth 128; output
|
||||
is at most 4 MiB before final sanitization; at most 32 macro invocations.
|
||||
Preflight is deliberately conservative for deeply/unclosed malformed HTML.
|
||||
Cooperative request/DB work has a two-second deadline. These are bounds, not
|
||||
hard CPU isolation of the in-process parser. Failure shows a localized warning
|
||||
and at most 64 KiB of escaped source, never original active HTML.
|
||||
- `/_/api/v1/render/markdown` accepts optional `html` only with `projection:true`.
|
||||
Display results are private/no-store. Canonical Markdown-to-HTML conversion
|
||||
remains separate and preserves authoring semantics; it must not be displayed
|
||||
without projection. Editor preview requests debounce/abort obsolete work and
|
||||
fail to escaped text. Saving does not save the sanitized preview.
|
||||
- Normal display/editor templates use per-response CSP nonces for application
|
||||
scripts and prohibit authored inline event handlers. Nonces are inserted into
|
||||
trusted template source **before** request data, never rendered body strings.
|
||||
Same-origin application frames/resources remain available; document styles
|
||||
are removed while application/theme styles remain enabled. Config and other
|
||||
non-document screens are not claimed to have this CSP yet.
|
||||
- Diagram SVG responses, including cache hits, have sandbox CSP and nosniff.
|
||||
GET cache use requires current Domain/Path read authority and a live bounded
|
||||
source reference (128 entries, 32 KiB/source, 30-minute lifetime). These
|
||||
references are keyed by policy version, Domain, Path and source; responses
|
||||
are private/no-store so browser caches do not bypass fresh checks. Reopening
|
||||
the Viewer registers references after restart/eviction. Renderer requests
|
||||
inherit cancellation; source/cache/output reads are size-bounded. Durable
|
||||
diagram scheduling, disk quotas, atomic artifact publication and hard decoder
|
||||
isolation remain follow-up work; foreground diagram GETs are not eliminated.
|
||||
- There is no grandfathering of old active HTML and no document-level trusted
|
||||
executable mode. The explicit Domain approval list above is the only active
|
||||
external-resource exception.
|
||||
Registered application/plugin frames are separate trust contracts. Anonymous
|
||||
locality ACLs, ownership appointments, alias/move fences and public cache
|
||||
revocation must land before enabling new public access.
|
||||
|
||||
Verification: `html_projection_test.go`, `html_projection_browser_test.go`, and
|
||||
`diagram_projection_security_test.go` cover inert attack corpora, resource limits,
|
||||
cancelled requests, unchanged stored content, cache authority/revocation and CSP.
|
||||
Real Chromium loads nine display/editor surfaces as an administrator after a
|
||||
path-scoped writer saves a hostile test document through the real save API.
|
||||
Authored execution and privileged sentinel requests must stay absent; parser-
|
||||
inserted non-nonced scripts/events are also blocked by CSP. Existing PDF/archive/
|
||||
comic, metadata, bookmark and editor browser regressions remain required.
|
||||
|
||||
Read-only compatibility sampling of the main DB's latest 500 HTML **revisions**
|
||||
(not a complete current-Path inventory) found no script/event/iframe/SVG markers
|
||||
in their first 128 KiB, one style-bearing revision, and no body over 1 MiB.
|
||||
This limited marker count is not a sanitizer/security proof or a guarantee that
|
||||
no existing document needs layout changes. No production document was rewritten.
|
||||
|
||||
The following sections preserve the original diagnostic and design rationale;
|
||||
their unsafe behavior describes the **pre-remediation** implementation.
|
||||
|
||||
## Finding and release gate
|
||||
|
||||
Before remediation, saved HTML executed JavaScript in the Pages Wiki application origin
|
||||
when a reader opens its semantic Viewer. Document write permission therefore
|
||||
implicitly grants the ability to execute code as a later reader, including a
|
||||
reader with stronger permissions. Authentication, path ACLs, and CSRF checks do
|
||||
not make authored HTML safe after it is inserted into the authenticated page.
|
||||
HttpOnly cookies cannot be read directly, but same-origin authored code can
|
||||
issue authenticated requests and read accessible responses or the page DOM.
|
||||
|
||||
**Before enabling or broadening shared links, comments, anonymous/public
|
||||
viewing, or untrusted-author publication, this boundary must be closed and its
|
||||
browser regression suite must pass.** This is also an existing risk in private
|
||||
Domains with authors and readers of different privilege levels; it is not
|
||||
limited to future public features. Do not describe the pre-remediation Viewer as an
|
||||
isolated HTML viewer, or treat an HTML MIME classification as a trust decision.
|
||||
|
||||
## Observed entry paths (before remediation)
|
||||
|
||||
The central semantic path is:
|
||||
|
||||
`Revision.Body → expandMacrosForRequest → renderDiagramsInHTML → template.HTML → parent page DOM`
|
||||
|
||||
The macro and diagram helpers replace recognized constructs; they are not HTML
|
||||
sanitizers and preserve unrelated scripts and event attributes. Go's
|
||||
`template.HTML` deliberately bypasses normal template escaping.
|
||||
|
||||
| Entry / projection | Current implementation and insertion |
|
||||
| --- | --- |
|
||||
| `/{semantic-path}` | `internal/server/semantic_handlers.go`, `handleSemanticRoute`: HTML-kind `Revision.Body` is expanded and cast to `template.HTML`; `templates/pages/page.gohtml` inserts `.RenderedHTML` directly into `.page-html`. |
|
||||
| `/` with a configured HTML home Path | `internal/server/handlers.go`, `handleHome`: the saved home body is macro-expanded and inserted through `page.gohtml`. |
|
||||
| `/o/uuid:{object-uuid}` | `internal/server/object_uri_handlers.go`, `handleObjectView`: casts `latest.Body` directly to `template.HTML`, without even the MIME/adapter-kind guard; `object_view.gohtml` inserts it into the parent document. |
|
||||
| `/r/view/{revision-uuid}` | `internal/server/revision_routes.go`, `handleRevisionView`: HTML-kind historical body is cast directly and inserted by `revision_view.gohtml`. |
|
||||
| `/v/preview/{path}` | `internal/server/preview_handler.go`, `handlePreview` / `renderPreviewDocument`: HTML-kind body is expanded and inserted by `preview.gohtml`. |
|
||||
| `/_/view/print/{path:…\|uuid:…\|rev:…}` | `internal/server/print_handler.go`, `handlePrint`: HTML body is expanded and inserted by `print.gohtml`. |
|
||||
| `/u/{username}` | `internal/server/profile_handler.go`, `handleUserProfile`: the associated user Wiki HTML is expanded and inserted by `profile.gohtml`; child Wiki pages use the semantic handler. |
|
||||
| `/e/{path}` live Preview | `static/js/editor.js`: HTML source and Markdown projection responses are assigned to `preview.innerHTML`. This is another active-markup sink to cover; script-tag behavior under `innerHTML` differs from initial document parsing, but event attributes and other active content must not be considered safe. |
|
||||
|
||||
The first row was verified in a real browser. The remaining rows were traced in
|
||||
source and require endpoint-specific browser coverage during remediation. This
|
||||
is an inventory of known sinks, not proof that no additional projection exists.
|
||||
|
||||
### Protections that do not cover these paths
|
||||
|
||||
Raw HTML download/attachment handling in `internal/server/raw_view.go`, the CSP
|
||||
sandbox on raw SVG, and the sandboxed EML HTML frame are separate response
|
||||
paths. They do not constrain saved HTML inserted into the normal Viewer.
|
||||
The audited semantic response had no `Content-Security-Policy` header and its
|
||||
authored content was not in a sandboxed iframe. `nosniff` or a correct
|
||||
`text/html` Content-Type would not remove executable content.
|
||||
|
||||
## Local verification
|
||||
|
||||
A scratch Go test, injected with `go test -overlay` rather than added to the
|
||||
repository, created a temporary migrated DB and temporary Document root. It
|
||||
saved a test-only HTML Revision, bound `/audit/sentinel`, and served the real
|
||||
semantic handler and templates through a localhost `httptest.Server`. A test
|
||||
owner session supplied request authorization; no external instance was used.
|
||||
Headless Chromium loaded that local page.
|
||||
|
||||
The payload contained only a paragraph, an inline script setting
|
||||
`document.documentElement.dataset.htmlScriptAudit`, and an invalid `data:` image
|
||||
whose `onerror` set `dataset.htmlEventAudit`. Both sentinel values became
|
||||
`executed` in the parent DOM. The HTTP response still contained the original
|
||||
inline script and its CSP header was empty. There was no data extraction,
|
||||
credential access, or application mutation from the payload.
|
||||
|
||||
This diagnostic confirmed the current unsafe behavior; it is not a permanent
|
||||
test that expects the vulnerability to remain. Remediation must invert those
|
||||
expectations into denial tests.
|
||||
|
||||
## Mismatch with existing design
|
||||
|
||||
- [Architecture](arch.md) distinguishes immutable Document content from Revision
|
||||
identity. Canonical HTML support does not itself authorize executable
|
||||
JavaScript, and the reviewed architecture does not define all authors as
|
||||
trusted application-script authors.
|
||||
- [Projection adapters](projection-adapters.md), “Security and Failure Rules,”
|
||||
says stored HTML and SVG retain their existing isolation rules. In practice
|
||||
the raw/SVG isolation is not shared by semantic HTML projections. That wording
|
||||
was insufficient to establish the missing boundary. That document now
|
||||
records the implemented common projection boundary and its limits.
|
||||
- [Platform extension architecture](platform-extension-architecture.md)
|
||||
explicitly says document content may request a widget provider/resource but
|
||||
may not supply executable JavaScript; providers use a sandboxed frame or a
|
||||
sanitized server projection. Direct authored HTML execution bypasses that
|
||||
intended separation.
|
||||
- The Preview adapter-kind check prevents treating every binary/text file as
|
||||
HTML, but it does not make a legitimately classified HTML body trusted.
|
||||
|
||||
## Policy rationale: immutable source, controlled projection
|
||||
|
||||
### Normal HTML is inert
|
||||
|
||||
Keep canonical Document bytes, hashes, Revision IDs, history, and authoring
|
||||
round trips unchanged. Enforce safety when producing a display projection,
|
||||
using a parser-based allowlist rather than regular-expression replacements.
|
||||
The normal mode must not allow authored scripts, inline event handlers,
|
||||
executable URLs, active embedded documents, or attributes that create a second
|
||||
execution context. Define URL schemes, relative URL resolution, allowed markup,
|
||||
CSS/layout limits, and external resource/privacy behavior explicitly. SVG,
|
||||
MathML, `srcdoc`, forms, CSS URLs, and DOM-clobbering attributes need explicit
|
||||
decisions, not implicit passthrough.
|
||||
|
||||
Introduce one projection boundary shared by Viewer, home, profile, historical
|
||||
Revision, preview, print, and client-side editor preview. Object-UUID viewing
|
||||
must also use the MIME/adapter registry rather than blindly casting a body.
|
||||
If projection parsing fails or exceeds resource bounds, fail safely to escaped
|
||||
source/download; never fall back to unsanitized HTML.
|
||||
|
||||
Distinguish authored nodes from server-generated macro/widget output. Parse
|
||||
recognized macro requests into structured inputs, authorize their data access,
|
||||
and produce escaped, typed output through trusted renderer contracts. A string
|
||||
that resembles generated markup is not proof of trust. Avoid sanitizing only
|
||||
before an expansion that can reintroduce authored unsafe attributes, or only
|
||||
after expansion without accounting for required application-owned controls.
|
||||
No general template call site should be able to turn arbitrary `Revision.Body`
|
||||
into trusted markup by convention alone.
|
||||
|
||||
Editor authoring mode continues to preserve source, while its visual preview
|
||||
uses the same safe projection policy. Do not conflate a safe display result
|
||||
with a replacement for the canonical body when saving.
|
||||
|
||||
### Explicit trusted HTML is isolated
|
||||
|
||||
If executable HTML compatibility is genuinely required, make it a separate,
|
||||
administrator-granted capability and an explicit Domain policy, not an implied
|
||||
consequence of page write permission. Bind approval to the actual approved
|
||||
content/revision or to a clearly defined trusted publishing workflow: granting
|
||||
trust to a mutable Path must not let any later lower-privilege editor inherit
|
||||
script execution. Define revocation, audit records, and visible mode indicators.
|
||||
|
||||
Executable content must not run with application-origin authority. Consider a
|
||||
dedicated uncredentialed origin or an opaque-origin sandbox, with the minimal
|
||||
permissions needed for that use case. Never combine same-origin document
|
||||
content with permissive `allow-scripts allow-same-origin` and call it isolation.
|
||||
Do not forward application cookies, bearer tokens, unrestricted save callbacks,
|
||||
or privileged data into that context. Any necessary `postMessage` integration
|
||||
must be narrowly typed, sender-checked, capability-scoped, and bounded; an
|
||||
opaque-origin sender requires validating the known frame/window and a dedicated
|
||||
channel rather than trusting the string `null` as an origin.
|
||||
|
||||
Existing application/plugin scripts remain a separate administrator-controlled
|
||||
surface. Registered widget/plugin frames must not become an escape hatch for
|
||||
arbitrary page-authored code or inherited reader capabilities. Shared/public
|
||||
projections and comments must always use the safe policy unless a separately
|
||||
reviewed, isolated publication contract explicitly permits more.
|
||||
|
||||
### Defense in depth and scaling
|
||||
|
||||
Adopt an application CSP compatible with approved application scripts, using
|
||||
nonces/hashes or external script assets rather than unrestricted inline script
|
||||
execution. CSP is defense in depth, not a substitute for safe markup and
|
||||
isolation. Frame responses need their own policy; tightening only the parent
|
||||
page does not fully define each child document's privileges.
|
||||
|
||||
Bound input size, parse depth/nodes, output size, CPU time, and any external
|
||||
resource work. Cache content-only safe projections by immutable Document hash,
|
||||
renderer version, and safety-policy version. Keep ACL-dependent macro output
|
||||
separate or key/revalidate it with Domain, principal/grants, and request context;
|
||||
never reuse a privileged projection as an anonymous/shared response. Cache and
|
||||
preview artifacts generated under an older unsafe policy need invalidation.
|
||||
|
||||
## Compatibility impact and staged implementation
|
||||
|
||||
Existing pages may rely on inline scripts, handlers, style blocks, custom
|
||||
attributes, embedded frames, forms, or SVG. Blanket filtering can break those
|
||||
pages, diagrams, child-list controls, and editor previews. A restrictive CSP
|
||||
also affects inline application scripts. The implementation above deliberately
|
||||
separates these template-owned scripts from authored HTML; original source stays
|
||||
available for editing/download if custom layout needs adjustment.
|
||||
|
||||
1. Approve the default allowlist, external-resource policy, and whether a
|
||||
trusted executable mode is needed at all; record explicit ownership.
|
||||
2. Inventory active constructs with a read-only diagnostic and report affected
|
||||
Paths only to authorized administrators. Do not rewrite stored content.
|
||||
3. Build the common projection boundary and server/client regression fixtures;
|
||||
preserve supported macro, diagram, print, and editor behavior deliberately.
|
||||
4. Integrate every known route, safe error fallbacks, policy-versioned caches,
|
||||
CSP, and any separately reviewed isolated mode. Do not grandfather all old
|
||||
HTML as trusted or infer trust from MIME, filename, creation time, or author
|
||||
display name.
|
||||
5. Verify upgrades and rollback without changing canonical bytes. Only then
|
||||
remove the P0 gate for public sharing, comments, and anonymous expansion.
|
||||
|
||||
## Required tests and acceptance criteria
|
||||
|
||||
- Browser denial fixtures for parser-inserted scripts, event attributes,
|
||||
executable URL variants, SVG/MathML active content, iframe/srcdoc, malformed
|
||||
markup, DOM clobbering, and CSS/resource-policy violations. Use harmless DOM
|
||||
sentinels and local test endpoints, not credential-exfiltration payloads.
|
||||
- Apply the same corpus to semantic Path, configured home, object UUID,
|
||||
historical Revision, user Wiki, preview, print, and both HTML/Markdown editor
|
||||
previews. Test direct navigation, client-side replacement, and restored
|
||||
revisions, not just the first render of new content.
|
||||
- Cross-account fixtures: a lower-privilege author cannot execute in a reader's
|
||||
page or issue reader-authorized mutations. Anonymous/shared viewers and
|
||||
comments cannot activate markup or receive private macro results.
|
||||
- Canonical Document bytes, SHA-256, Revision IDs, downloads, and authoring
|
||||
round trips remain unchanged. Non-HTML bodies are never interpreted as HTML
|
||||
by the object-UUID route. Unknown formats and parser failures stay inert.
|
||||
- Supported formatting, links, images, children macros, diagrams, code blocks,
|
||||
accessibility, themes, and print layouts still work. Template-owned controls
|
||||
are not confused with forged authored markup.
|
||||
- If trusted mode is implemented, verify origin isolation, cookie/token
|
||||
exclusion, navigation/form/download permissions, message validation,
|
||||
approval-on-edit behavior, revocation, and public-projection restrictions.
|
||||
- Test CSP headers and violation behavior, resource bounds, cancellation,
|
||||
oversized/deep input, cache policy-version changes, ACL revocation, and no
|
||||
privileged-to-public cache reuse. A single endpoint-only sanitizer test is
|
||||
insufficient to close this gate.
|
||||
|
||||
Acceptance requires inactive authored markup in every normal projection, an
|
||||
explicitly reviewed policy for any executable mode, preserved canonical
|
||||
content, and passing endpoint/browser integration tests. The normal projection
|
||||
slice meets this boundary with no executable mode. Additional public/shared
|
||||
surfaces must inherit it and pass their own ACL/revocation tests before release.
|
||||
@@ -0,0 +1,395 @@
|
||||
# Language Projection Draft
|
||||
|
||||
## Goal
|
||||
|
||||
Language should NOT affect semantic hierarchy.
|
||||
|
||||
Language is treated as:
|
||||
|
||||
```text
|
||||
projection
|
||||
representation
|
||||
view
|
||||
```
|
||||
|
||||
rather than containment.
|
||||
|
||||
* * *
|
||||
|
||||
# Core Philosophy
|
||||
|
||||
## URL hierarchy is language-neutral
|
||||
|
||||
Paths represent:
|
||||
|
||||
```text
|
||||
semantic location
|
||||
knowledge locality
|
||||
human navigation
|
||||
```
|
||||
|
||||
NOT language ownership.
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
Preferred:
|
||||
|
||||
```text
|
||||
/dev/api/auth
|
||||
```
|
||||
|
||||
Avoid:
|
||||
|
||||
```text
|
||||
/ja/dev/api/auth
|
||||
/en/dev/api/auth
|
||||
```
|
||||
|
||||
because language hierarchy pollutes semantic hierarchy.
|
||||
|
||||
* * *
|
||||
|
||||
# Important Separation
|
||||
|
||||
Layer Meaning Path semantic hierarchy Page UUID identity Revision representation Language projection
|
||||
|
||||
* * *
|
||||
|
||||
# Internal Model
|
||||
|
||||
## Page
|
||||
|
||||
Language-neutral semantic object.
|
||||
|
||||
```text
|
||||
Page UUID
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Page
|
||||
├─ Japanese revision
|
||||
├─ English revision
|
||||
└─ Chinese revision
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Revision
|
||||
|
||||
Language-specific content snapshot.
|
||||
|
||||
## `revisions` table
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `uuid` | Immutable Revision UUID |
|
||||
| `object_uuid` | Parent Page UUID; retained name during the Object-to-Page migration |
|
||||
| `document_hash` | SHA-256 of the immutable canonical payload |
|
||||
| `lang` | Canonical BCP 47 language tag or `und` |
|
||||
| `message` | Commit message |
|
||||
| `created_at_ms` | Unix epoch milliseconds |
|
||||
|
||||
The payload is addressed by `document_hash`; it is not identified by the
|
||||
Revision UUID.
|
||||
|
||||
* * *
|
||||
|
||||
# Language Resolution
|
||||
|
||||
## Request
|
||||
|
||||
```http
|
||||
GET /dev/api/auth
|
||||
Accept-Language: ja-JP,ja;q=0.9,en;q=0.8
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Resolution Flow
|
||||
|
||||
```text
|
||||
Page UUID
|
||||
↓
|
||||
find latest revision(lang=ja-JP)
|
||||
↓ not found
|
||||
find latest revision(lang=ja)
|
||||
↓ not found
|
||||
find latest revision(lang=en)
|
||||
↓ not found
|
||||
find latest revision(lang=campus default)
|
||||
↓ not found
|
||||
find latest revision(lang=system default)
|
||||
↓ not found
|
||||
find latest revision(lang=und)
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Fallback Philosophy
|
||||
|
||||
Language fallback is preferred over URL duplication.
|
||||
|
||||
* * *
|
||||
|
||||
# Recommended Fallback Chain
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
ja-JP
|
||||
↓
|
||||
ja
|
||||
↓
|
||||
campus default
|
||||
↓
|
||||
system default
|
||||
↓
|
||||
und
|
||||
```
|
||||
|
||||
Duplicate candidates are removed while preserving order. Invalid language
|
||||
tags are ignored. `und` is the compatibility projection for revisions created
|
||||
before language-aware delivery.
|
||||
|
||||
* * *
|
||||
|
||||
# Zone Language Metadata
|
||||
|
||||
Zones may optionally define language affinity.
|
||||
|
||||
## `zones`
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `default_lang` | Preferred fallback language |
|
||||
| `allowed_langs` | Allowed languages |
|
||||
|
||||
* * *
|
||||
|
||||
# Example
|
||||
|
||||
## JP-oriented campus
|
||||
|
||||
```text
|
||||
default_lang = ja
|
||||
allowed_langs = ja,en
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Global campus
|
||||
|
||||
```text
|
||||
default_lang = en
|
||||
allowed_langs = *
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Spot Language Metadata
|
||||
|
||||
Spot may optionally specify:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `preferred_lang` | Preferred rendering language |
|
||||
|
||||
This influences rendering preference only.
|
||||
|
||||
It does NOT change identity.
|
||||
|
||||
* * *
|
||||
|
||||
# Canonical URL Policy
|
||||
|
||||
Canonical URL remains language-neutral.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
/dev/api/auth
|
||||
```
|
||||
|
||||
Language selection is handled at rendering time.
|
||||
|
||||
* * *
|
||||
|
||||
# Optional Explicit Language URL
|
||||
|
||||
Explicit language paths may exist for:
|
||||
|
||||
- debugging
|
||||
- preview
|
||||
- direct linking
|
||||
- translators
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
/_/lang/ja/dev/api/auth
|
||||
```
|
||||
|
||||
However:
|
||||
|
||||
```text
|
||||
this is NOT canonical
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Why This Design
|
||||
|
||||
## Prevents hierarchy pollution
|
||||
|
||||
Avoids:
|
||||
|
||||
```text
|
||||
language hierarchy
|
||||
```
|
||||
|
||||
overwriting:
|
||||
|
||||
```text
|
||||
semantic hierarchy
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Benefits
|
||||
|
||||
## 1. Stable semantic URLs
|
||||
|
||||
The same knowledge object keeps the same path.
|
||||
|
||||
* * *
|
||||
|
||||
## 2. Shared semantic identity
|
||||
|
||||
Multiple languages refer to the same:
|
||||
|
||||
```text
|
||||
Page UUID
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
## 3. Better multitree behavior
|
||||
|
||||
Aliases and bindings remain language-neutral.
|
||||
|
||||
* * *
|
||||
|
||||
## 4. Better graph compatibility
|
||||
|
||||
Semantic relations do not duplicate per-language.
|
||||
|
||||
* * *
|
||||
|
||||
# Relation to Existing Architecture
|
||||
|
||||
This design aligns with:
|
||||
|
||||
```text
|
||||
path != object
|
||||
```
|
||||
|
||||
and extends it into:
|
||||
|
||||
```text
|
||||
representation != object
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# Conceptual Mapping
|
||||
|
||||
Concept Meaning Path semantic locator UUID identity Revision representation Language projection
|
||||
|
||||
* * *
|
||||
|
||||
# NDN-like Interpretation
|
||||
|
||||
## Name
|
||||
|
||||
```text
|
||||
/dev/api/auth
|
||||
```
|
||||
|
||||
semantic and language-neutral.
|
||||
|
||||
* * *
|
||||
|
||||
## Content Negotiation
|
||||
|
||||
Language selection behaves similarly to:
|
||||
|
||||
```text
|
||||
content negotiation
|
||||
```
|
||||
|
||||
using:
|
||||
|
||||
```text
|
||||
Accept-Language
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
# UI Philosophy
|
||||
|
||||
Language switching should feel lightweight.
|
||||
|
||||
Example UI:
|
||||
|
||||
```text
|
||||
[Japanese] [English] [中文]
|
||||
```
|
||||
|
||||
without changing semantic location.
|
||||
|
||||
* * *
|
||||
|
||||
# Important Principle
|
||||
|
||||
Language should not fork the knowledge universe.
|
||||
|
||||
Avoid:
|
||||
|
||||
```text
|
||||
ja-wiki
|
||||
en-wiki
|
||||
```
|
||||
|
||||
style silo fragmentation unless intentionally desired.
|
||||
|
||||
* * *
|
||||
|
||||
# Current Recommended Direction
|
||||
|
||||
Layer Model UI semantic hierarchy URL language-neutral Internal revision projection Identity UUID Rendering Accept-Language + fallback
|
||||
|
||||
* * *
|
||||
|
||||
# Summary
|
||||
|
||||
Language is treated as:
|
||||
|
||||
```text
|
||||
projection
|
||||
representation
|
||||
view
|
||||
```
|
||||
|
||||
NOT:
|
||||
|
||||
```text
|
||||
ownership
|
||||
containment
|
||||
hierarchy
|
||||
```
|
||||
|
||||
This preserves semantic structure while supporting multilingual knowledge naturally.
|
||||
@@ -0,0 +1,570 @@
|
||||
# Architecture Implementation Roadmap
|
||||
|
||||
## Principles
|
||||
|
||||
### Task management first slice (2026-09-24)
|
||||
|
||||
2026-09-25 task CalDAV (`0.8.0`, implemented and fixture-tested, **deployed to app/app2 on 2026-09-26 at 00:24 JST**; [deployment record](../operations/deployments/2026-09-26-task-caldav.md)):
|
||||
private fixed VTODO collection, revocable read/read-write app passwords with UI,
|
||||
conditional writes and archive deletion. Real vdirsyncer 0.21.0 / Todoman 4.7.0
|
||||
discovery and bidirectional sync tests. Date-only deadlines; not full CalDAV
|
||||
conformance. See [task CalDAV contract and CLI setup](ja/task-caldav.md).
|
||||
|
||||
2026-09-25 task follow-up (`0.7.0`, implemented and deployed to app/app2 at 07:07 JST):
|
||||
daily/tomorrow planning, explicit carryover rescheduling, hierarchy-aware pagination
|
||||
and parent context, and atomic Wiki-note creation with UUID-bound view/edit actions.
|
||||
See [daily task / Wiki note contract](ja/task-daily-notes.md). Capacity, bulk family
|
||||
planning, manual sorting and shared tasks remain open.
|
||||
|
||||
2026-09-25 follow-up (implemented, fixture-tested and **deployed to app/app2 at 05:59 JST**; [deployment record](../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)):
|
||||
|
||||
- [x] Inline title/status/date editing, independently dated two-level subtasks,
|
||||
bounded monthly day schedule, home shortcut and Today navigation modal (`0.6.0`).
|
||||
- [x] Inbox presentation preferences per account/browser, focused expiring toasts,
|
||||
opt-in return modal, sound presets/volume, notification-only Service Worker.
|
||||
- [x] Opt-in Web Push: transactional Inbox outbox, revocable session-bound subscriptions,
|
||||
VAPID, vendor allowlist/DNS pinning, bounded scheduler delivery/retry/expiry and focus acknowledgements.
|
||||
- [ ] Live OS/browser delivery acceptance with an explicitly opted-in test device
|
||||
(Chrome/Firefox/Safari), iOS home-screen installation and OS power-saving behavior.
|
||||
|
||||
See [active notification contract](ja/active-notifications.md) and
|
||||
[inline task/day schedule contract](ja/task-inline-schedule.md).
|
||||
|
||||
- [x] `organizer.tasks` private per-principal/Domain items and projects, CAS payloads,
|
||||
atomic head/revision/change journal, conditional writes and idempotent creation.
|
||||
- [x] Today, Inbox, Backlog, Someday, Review, Completed and Archive; project/task detail,
|
||||
quick capture, due/planned/review dates, priority, estimate and readable Wiki UUID links.
|
||||
- [x] Bounded lists/history, EN/JA, theme-aware desktop/mobile dialogs, extension kill switch.
|
||||
- [x] Typed independent outbox subscriptions; atomic task/project events, bounded journal
|
||||
migration through the scheduler, no City jobs for task-only changes.
|
||||
- [ ] Shared collections/assignees, export/recovery and bulk review.
|
||||
- [x] Opt-in due/planned-date task reminders, atomic reservations/cancellation,
|
||||
bounded background Inbox delivery, live metadata authorization and badge refresh.
|
||||
- [x] Private local calendar time-block links, durable retry intents, current event time/ETag lookup, unlink tombstones; imported/shared/public calendars excluded.
|
||||
- [x] Persistent Pomodoro: start/pause/resume/finish/cancel, one active session per principal, conditional transitions, bounded scheduler completion and Inbox notification.
|
||||
- [x] Today bounded estimates/current local time blocks/recorded focus intervals, overlap and incomplete-total indicators. Calendar event summaries include an explicitly approved task-title snapshot, never notes.
|
||||
- [ ] Personal capacity, carry-over and period/project reports; historical focus-span backfill; calendar reminders, notification defaults/quiet hours/digests; Pomodoro personal defaults/cycles and routines.
|
||||
|
||||
See [time-block and Pomodoro contracts](ja/task-planning-focus.md) for API, privacy,
|
||||
two-store recovery, polling limits and remaining work. Canonical calendars and task
|
||||
DB metadata both require backup. Production app/app2 deployment completed on
|
||||
2026-09-25 JST; see the [deployment record](../operations/deployments/2026-09-25-task-today.md)
|
||||
for backup, verification and the observed transient scheduler lock contention.
|
||||
- [x] Limited private VTODO / CalDAV with vdirsyncer + Todoman file synchronization.
|
||||
- [ ] Time-of-day deadlines, recurrence/alarms, shared task collections, incremental
|
||||
sync-token and additional CalDAV clients; dependency graph, tickets and offline UI.
|
||||
|
||||
See [Japanese task implementation contract](ja/tasks-implementation.md).
|
||||
The existing `/v/plan` calendar default is unchanged; tasks start at `/v/plan/today`.
|
||||
|
||||
### Calendar subproject (2026-09-22)
|
||||
|
||||
- [x] Small-screen/touch calendar navigation, readable week columns and day selector,
|
||||
scroll-first gestures, compact month counts and VisualViewport-aware editor.
|
||||
[Mobile contract](ja/calendar-mobile.md): fixture-tested and deployed 2026-09-25; iPhone Safari acceptance pending.
|
||||
|
||||
- [x] Initial file-canonical calendar/month snapshots, rebuildable SQLite index,
|
||||
conditional event CRUD and bounded CalDAV time-range REPORT.
|
||||
- [x] `/v/plan` year/month/week/day/events/timeline, event dialogs and per-calendar collaborators.
|
||||
- [x] Per-user default calendar overlays and explicit comma-separated `pretty_name` selection.
|
||||
- [x] Week/day time grids, configured-timezone day boundaries, zoom through 400% with 5-minute precision,
|
||||
ETag-protected move/start/end resizing without refetch, equal overlap lanes, drag-range creation,
|
||||
horizontal rescheduling and `week/list`.
|
||||
- [x] Read-only ICS polling with interval/conditional GET and bounded external CalDAV REPORT/multiget;
|
||||
background event queue, encrypted Basic credentials, SSRF guards and failure-safe snapshots.
|
||||
- [x] Outlook published-ICS projection for METHOD:PUBLISH, VTIMEZONE/TZID, Windows timezone names,
|
||||
bounded RRULE expansion, EXDATE/RDATE, moved/cancelled RECURRENCE-ID instances and orphaned
|
||||
exception projections, plus multi-megabyte synthetic fixtures.
|
||||
- [ ] Recurrence PERIOD/THISANDFUTURE, alarms/durations, provider validation, discovery/OAuth,
|
||||
configurable synchronization windows and conflict-aware bidirectional synchronization.
|
||||
- [ ] Full iCalendar temporal semantics (recurrences, timezones, exceptions), CalDAV discovery/client compatibility,
|
||||
application credentials, synchronization tokens and maintenance/metrics jobs.
|
||||
- [ ] Group sharing, audited administration, ownership recovery and calendar scheduling/notifications.
|
||||
|
||||
See [Japanese implementation contract and limitations](ja/calendar-implementation.md).
|
||||
The initial supported subset is not a claim of full CalDAV conformance.
|
||||
|
||||
System-service plugins are distinct from document adapters. See
|
||||
[System extensions](system-extensions.md) for implementation boundaries and the next slices.
|
||||
|
||||
- [x] Responsive wider bookmark-card grid (viewport-dependent columns).
|
||||
- [x] Built-in resource.sample event, SQLite history, retention and bounded graphs without foreground collection.
|
||||
- [x] Separate system-extension catalog and settings area for trusted built-ins.
|
||||
- [x] Unified execution/resource monitor (running jobs only), paginated job history with lazy logs.
|
||||
- [x] Protect group owners from ordinary member downgrades and atomically retain an owner during concurrent removal.
|
||||
- [ ] Transactional activity outbox and Domain/principal recent-edit projections.
|
||||
- [x] Diary/blog initial built-ins: Page UUID metadata, calendar/recent entries,
|
||||
categories, read-filtered indices, per-Domain enable/disable and registration UI.
|
||||
See [initial scope](diary-blog-plugins.md); this is authenticated, existing-Page registration only.
|
||||
- [x] Diary/blog atomic Markdown new-post composition, transactional metadata/Revision,
|
||||
embedded-asset freezing, idempotent retry and create/write enforcement.
|
||||
- [ ] Diary/blog: anonymous metadata approval/feeds,
|
||||
recent comments and safe resumable tDiary import; declarative time/OS/sunset theme rules.
|
||||
- [x] Diary/blog per-Domain prefixes, optional keyword URL planner, multiple articles
|
||||
per day, and authenticated Domain-root diary/blog entry view (2026-09-17).
|
||||
Legacy Page registration remains available.
|
||||
- [x] Domain entry-settings dialog and signed manifest v2 provisioning of layout,
|
||||
diary/blog enablement and prefixes; atomic destination apply and managed edit guards.
|
||||
- [x] Signed enrollment capability proof and Campus-wide approved-peer v2 preflight
|
||||
before entry-setting changes; unknown/legacy peers block with a visible explanation.
|
||||
- [ ] Entry provisioning inside Domain creation, controlled-settings release/retention,
|
||||
applied-setting acknowledgments and freshness policy.
|
||||
- [x] Diary/blog dated viewer routes `/v/{kind}/yyyy/mm[/dd]`, `own` presence
|
||||
filter, legacy-query redirects, and canonical calendar/filter/pagination navigation.
|
||||
- [x] Local same-Campus diary/blog index/calendar projection without copying articles;
|
||||
source and destination read-policy filtering, source body/edit links, target write guard.
|
||||
- [ ] Project article bodies on destination host, approved anonymous projection,
|
||||
cross-instance source transport/revocation and source-setting federation.
|
||||
- [ ] Rankings, reactions and moderated Page/inline comment services.
|
||||
- [ ] Linkding-compatible bookmark-source injection with scoped credentials.
|
||||
- [ ] Explicit external-search fallback and PagesWiki/GROWI/PukiWiki connectors.
|
||||
- [ ] S3-compatible Document Store; read-only WebDAV/SSH external collections.
|
||||
- [ ] Optional SNMP resource collector with target/OID allowlists and SNMPv3 secrets.
|
||||
- [ ] Third-party system-plugin signature validation, isolated runtime and lifecycle operations.
|
||||
|
||||
vim.wasm runtime fixes are on hold by user request; its existing configuration UI is retained.
|
||||
|
||||
### Prioritized execution order (2026-09-14)
|
||||
|
||||
Feature checkboxes above are not an instruction to bypass the hardening gates.
|
||||
The execution order is maintained in [Implementation status](implementation-status.md#ordered-next-work).
|
||||
|
||||
1. Completed this slice: unified monitor/history UI, bounded/indexed job/log retrieval;
|
||||
first P0 correction: owner downgrade and concurrent last-owner removal protection.
|
||||
2. Completed bounded hardening: OIDC/JWKS, inherited-admin revocation,
|
||||
browser mutation/purpose checks, Domain/Object scope and read filtering;
|
||||
see the [execution ledger](hardening-execution-2026-09.md).
|
||||
3. Completed recursive authorized snapshots, literal prefix transactions and
|
||||
signed manifest/checkpoint atomicity. Remaining write-policy fencing and
|
||||
content-author trust are gates before public/shared collaboration.
|
||||
4. Completed PDF/archive metadata jobs, bounded read-policy snapshots,
|
||||
Object/Revision pagination and improved search; continue lazy City/directory
|
||||
projection, decoder isolation and durable entry extraction.
|
||||
5. Transactional activity outbox, actor attribution, idempotent URL reconciliation
|
||||
and recent-edit projections.
|
||||
6. Diary/widgets/import and themes, then comments/rankings, external search/bookmarks,
|
||||
storage connectors and SNMP. HA leases/fencing gate multi-node deployment;
|
||||
external plugin installation remains disabled until isolation/security gates pass.
|
||||
|
||||
- Migrations must preserve existing UUID and path reachability.
|
||||
- New architecture is introduced in vertical slices with regression tests.
|
||||
- Reserved authorization features must not be simulated with insecure
|
||||
allow-all placeholders.
|
||||
- New collaboration and extension features must use the stable Page UUID,
|
||||
immutable Revision, Domain-scoped policy, projection-adapter, event, and
|
||||
scheduler contracts described in
|
||||
[Platform Extension Architecture](platform-extension-architecture.md).
|
||||
- SQLite remains a supported single-node metadata backend. HA work must add a
|
||||
replicated metadata strategy or explicit single-writer fencing; sharing a
|
||||
live SQLite file over a network filesystem is not an HA design.
|
||||
|
||||
## Phase 1 — Identity and projection foundations
|
||||
|
||||
- [x] Separate Object creation from Semantic Path binding.
|
||||
- [x] Rename the implemented District model to Domain.
|
||||
- [x] Separate Revision UUID from Document SHA-256.
|
||||
- [x] Add Revision language metadata and fallback selection.
|
||||
- [x] Move immutable payloads to `documents/sha256/` with a transitional
|
||||
SQLite compatibility cache.
|
||||
- [x] Add rsync-like and interactive `path:` / `uuid:` / `rev:` / `asset:`
|
||||
data administration.
|
||||
|
||||
## Phase 2 — Knowledge City topology
|
||||
|
||||
Current review: [City reconciliation and navigation](city-review-and-reconciliation.md).
|
||||
The completed items below are initial implementations. The next City slices are:
|
||||
|
||||
- [x] Audit City/autoplan/gen-city and design URL-driven event reconciliation.
|
||||
- [x] CITY-A named links: parent-qualified Street URLs, ambiguity-safe lookup,
|
||||
shared search/map/macro links, ancestor authorization, lightweight details,
|
||||
literal Page URLs and map focus/locality-search regression coverage.
|
||||
- [ ] CITY-A: per-result authorization, literal Paths, scoped links/names,
|
||||
shallow/portal inference, manual ownership and idempotent application.
|
||||
- [ ] CITY-B: transactional mutation outbox → debounced, durable City queue
|
||||
consumer; scheduled/manual repair through the same pipeline.
|
||||
- [ ] CITY-C: stable fabric, Worker/cache, connected roads, bounded lazy
|
||||
projection and capacity-safe picking targets.
|
||||
- [ ] CITY-D: icon/modal creation/settings, arrow/WASD/HJKL navigation,
|
||||
focus/history handling and i18n browser regressions.
|
||||
- [x] City label follow-up: visible resting labels, horizontal Street names,
|
||||
retained hover/focus highlighting and working label toggle; normal/popup tests.
|
||||
- [x] Manual City organization: display-title modal, Ctrl/Command selection,
|
||||
existing/new Spot merge, Street relocation retaining Page URLs, transactional
|
||||
validation and manual-inference overrides; see [contract](city-organization-ui.md).
|
||||
- [x] Immersive City follow-up: focused Spot courtyards and surrounding Page
|
||||
buildings, nonoverlapping bounded/paginated close-ups, themed architectural SVG,
|
||||
modal utility menu and directory navigation; normal/popup regressions. See
|
||||
[projection and limits](city-immersive-map.md); CITY-A–D gates remain open.
|
||||
- [x] Filter City map/details/macros/badges by readable boundaries and Pages;
|
||||
recompute visible portals/counts/relations and use private responses.
|
||||
- [x] Local gen-city Worker with time/input/output/cache bounds, cancellation
|
||||
and retry, plus spatial Arrow/WASD/HJKL navigation in normal/popup modes;
|
||||
see [worker and navigation](city-worker-navigation.md).
|
||||
- [x] One-connection-safe bounded City snapshots and literal Path
|
||||
containment/overlap/context/health; true lazy Page pagination remains open.
|
||||
|
||||
- [x] Define Campus identity and defaults.
|
||||
- [x] Define Domain ownership by Campus.
|
||||
- [x] Scope Semantic Paths by `(domain_uuid, path)`.
|
||||
- [x] Add local/remote Domain placement.
|
||||
- [x] Add absolute cross-Domain link helpers.
|
||||
- [x] Add standalone/controller/managed Campus authority modes.
|
||||
- [x] Scope non-topology configuration by Domain.
|
||||
- [x] Scope Recent Objects by selected Campus and Domain.
|
||||
- [x] Record controller-selected Domain instance FQDN.
|
||||
- [x] Add hashed enrollment tokens and fingerprinted instance registration.
|
||||
- [x] Add pending/approved/revoked instance placement selection.
|
||||
- [x] Add external Campus bootstrap enrollment.
|
||||
- [x] Add Managed Campus health status and detach actions.
|
||||
- [x] Add signed Campus manifest reconciliation.
|
||||
- [x] Implement ZoneTree nodes for Quartier and Street.
|
||||
- [x] Implement Spot identity and ZoneTree pointers.
|
||||
- [x] Implement SpotGraph Page bindings and MagicPage traversal.
|
||||
- [x] Define Quartier planning, Street routing, Spot locality, topology
|
||||
invariants, projections, APIs, policy inheritance, and delivery slices.
|
||||
- [x] Add the initial topology schema, monotonic Domain topology version,
|
||||
topology events, and Quartier/Street/Spot creation stores.
|
||||
- [x] Add the initial interactive `/v/city` SVG guide map and authorized map API.
|
||||
- [x] Add SpotPage/MagicPage edges, Viewer locality badges, Spot detail Page
|
||||
lists, and initial typed SpotGraph relation visualization.
|
||||
- [x] Add Quartier/Street/Spot detail projections, transactional Street/Spot
|
||||
moves, ordering, and reversible SpotPage/SpotRelation edge removal.
|
||||
- [x] Add planning preview/apply, reversible before/after event payloads, and
|
||||
city health analysis.
|
||||
- [x] Add `/v/city` map and locality breadcrumbs.
|
||||
- [x] Add locality-scoped search and topology macros.
|
||||
|
||||
## Phase 3 — Projection runtime
|
||||
|
||||
- [x] Formalize the initial Viewer projection adapter registry and contract.
|
||||
- [x] Route Viewer and semantic editor selection through adapters.
|
||||
- [x] Route preview through adapters, including bounded text and CSV projections.
|
||||
- [x] Route bounded print layouts through adapters at `/_/view/print/<address>`.
|
||||
- [x] Route the semantic Viewer through the initial adapter registry.
|
||||
- [x] Add bounded text retrieval backed by seekable Document Store reads.
|
||||
- [x] Defer PDF page rendering to idempotent scheduler jobs with retrying
|
||||
Viewer delivery and bounded PDF page-count commands.
|
||||
- [ ] Defer non-ZIP archive metadata and entry extraction to cached, bounded
|
||||
scheduler projections.
|
||||
- [x] Persist PDF page-count and non-ZIP metadata via shared scheduler jobs,
|
||||
bounded immutable-hash cache and localized pending/retry views.
|
||||
- [ ] Persist seekable non-ZIP extracted entries with quota/lease/Range and
|
||||
archive-bomb controls; move ZIP central-directory work off the request path.
|
||||
- [x] Add bounded structural JSON retrieval by immutable Revision and lazy
|
||||
JSON-Pointer expansion without unmarshalling the complete payload.
|
||||
- [x] Separate authoring and projection macro transpilation so HTML-to-Markdown
|
||||
round trips preserve `children` while Markdown previews render it.
|
||||
- [ ] Generalize the authoring/projection macro contract to typed extension
|
||||
macros with versioned round-trip and projection tests.
|
||||
- [x] Add ZIP/archive directory and Debian metadata adapters.
|
||||
- [x] Add a bounded CSV table adapter.
|
||||
- [x] Add the bounded `@excalidraw/excalidraw` hosted Viewer plugin with an
|
||||
isolated immutable-Revision contract and safe built-in Canvas fallback.
|
||||
- [x] Separate built-in projections from Domain-scoped hosted adapter plugins.
|
||||
- [x] Restrict hosted adapter targets to HTTP(S) services such as vim.wasm or
|
||||
a separately deployed editor gateway.
|
||||
- [x] Define and implement one-use launch tickets and optimistic Revision
|
||||
write-back with a reference hosted-editor gateway.
|
||||
- [x] Connect an internal code-server instance to the hosted-editor Gateway,
|
||||
with session workspace materialization and autosave Revision write-back.
|
||||
- [x] Connect a cross-origin-isolated vim.wasm frontend to the hosted-editor
|
||||
Gateway contract with hierarchical MEMFS loading and Revision write-back.
|
||||
- [ ] Evaluate a local helper, temporary workspace, and executable allowlist
|
||||
before enabling native applications such as Vim or VS Code.
|
||||
- [x] Freeze embedded mutable Asset HEADs into immutable Document hashes on
|
||||
Revision save and retain authorization references from the containing Page.
|
||||
- [x] Scope mutable Asset addresses and management metadata by Domain.
|
||||
- [x] Add typed Asset MIME/filename/size metadata and immutable HEAD history.
|
||||
- [x] Add administrator HTTP create/update/delete with ETag preconditions.
|
||||
- [x] Add the initial Asset management panel under Domain configuration.
|
||||
- [x] Add Asset HEAD history/restore and Page/Revision dependency-detail UI.
|
||||
- [ ] Add Asset retention controls, policy-matrix capabilities, and general
|
||||
audit-outbox integration as specified in `asset-model.md`.
|
||||
- [ ] Add a capability-checked mutable Asset authoring-preview endpoint and
|
||||
typed `srcset`/CSS resource resolution without allowing live Asset URLs into
|
||||
stored Viewer output.
|
||||
- [x] Add authorized immutable object retrieval at `/_/obj/sha256:<hash>`,
|
||||
limited to Documents referenced by a readable Path in the current Domain.
|
||||
|
||||
## Navigation and home layouts
|
||||
|
||||
See [Home layouts and sidebar design](navigation-home-sidebar.md).
|
||||
|
||||
- [x] Vendor Hack Nerd Font for Browser and Tree without a runtime CDN dependency.
|
||||
- [x] Add Domain-scoped classic, centered-search, and search/bookmark home layouts.
|
||||
- [x] Keep home search global to the current Domain even when rendering `/top`.
|
||||
- [x] Scope `/v/tree/{path}` to the requested subtree with breadcrumbs and cached expansion.
|
||||
- [x] Limit Browser revision lookups to displayed files and repair missing revision indexes.
|
||||
- [x] Define a shared sidebar layout, state ownership, and bounded children API contract.
|
||||
- [ ] Implement the shared sidebar and authorized, paginated lazy navigation API.
|
||||
- [x] Group configuration navigation and split scheduler, queue, logs, resources,
|
||||
authentication providers, and adapter-specific settings into separate panels.
|
||||
- [x] Add accessible themed switches and a Domain bookmark manager for Paths/URLs.
|
||||
- [x] Restore public application assets and align compact/legacy editor paths.
|
||||
- [x] Manage bookmarks from home; section cards and permission-filtered async child links.
|
||||
- [x] Refine bookmark management into an icon-launched modal and section-card editor with group operations.
|
||||
- [x] Add admin-only Domain vimrc/colorscheme upload, download/reset, session-scoped delivery and safe-mode recovery.
|
||||
- [x] Explicitly load hosted Vim configuration, bundle its font and add a pure-Vimscript navigation plugin; verify the real Wasm runtime.
|
||||
See [home navigation and hosted Vim](home-bookmark-sections-vim.md).
|
||||
- [x] Add bounded, visibility-aware live resource graphs without a CDN dependency.
|
||||
- [x] Repair Asset GET authorization and align metadata/history/reference reporting.
|
||||
- [ ] Add versioned adapter-specific settings schemas and secret-field handling;
|
||||
see [Configuration panels](configuration-panels.md).
|
||||
- [ ] Add a transactional directory index and batch authorization for large hierarchies.
|
||||
|
||||
## Phase 4 — Identity and authorization
|
||||
|
||||
- [x] Normalize password, TOTP, OIDC, and magic-link authentication into Principals.
|
||||
- [x] Add the initial direct Membership, Role, and positive-grant schema.
|
||||
- [x] Add the initial Domain-level Capability evaluation with default deny.
|
||||
- [x] Replace capability inference from URL words such as `delete` and `rename`
|
||||
with a centralized typed endpoint policy classifier; deny undefined mutations
|
||||
in reserved namespaces and method-close exact API routes.
|
||||
- [ ] Complete typed object/path target resolvers for derived views and remove
|
||||
the remaining handler-specific authorization exceptions.
|
||||
- [x] Resolve raw, windowed text, PDF-page, preview-cache, print, Object,
|
||||
Revision, history, and diff reads through their source Object/Path grants.
|
||||
- [x] Filter Tree, Browser, Search, Preview listings, and asynchronous children
|
||||
results per visible Path without returning hidden child counts.
|
||||
- [x] Scope the initial Object list and Revision list API responses to the
|
||||
current Domain and readable Object/Path grants.
|
||||
- [x] Declare JSON/multipart target resolution as handler-owned policy and
|
||||
remove route-name bypasses from middleware; enforce every expanded source
|
||||
and destination Path for recursive rename, copy, and delete operations.
|
||||
- [x] Bind hosted adapter sessions to the issuing Principal and re-check
|
||||
current read/write grants on every workspace/content operation.
|
||||
- [ ] Move multipart/JSON source-and-destination mutation checks into typed
|
||||
decoded-request objects shared by middleware and handlers.
|
||||
- [x] Add cookie-session CSRF and credential-type separation (legacy unprefixed
|
||||
sessions expire normally); POST-only logout and live membership checks.
|
||||
- [x] Verify OIDC issuer JWKS signatures/claims/browser state and reject
|
||||
ambiguous email matches or conflicting external-identity binding.
|
||||
- [x] Add Domain-scoped LDAP/LDAPS authentication with service search bind,
|
||||
escaped exact-one user lookup, user-DN password bind, encrypted secrets,
|
||||
immutable provider identity, bounded time/concurrency, optional member-only
|
||||
provisioning, saved-configuration test UI, and Japanese/English labels.
|
||||
- [x] Revoke derived Campus-admin grants transactionally without deleting
|
||||
independent local grants or regenerating removed bootstrap authority.
|
||||
- [x] Scope foreign/unbound Object authority and record atomic API creation
|
||||
provenance; check all local aliases for global Object purge.
|
||||
- [x] Revalidate zombie eligibility within the purge write transaction; scope
|
||||
HTTP/config cleanup by Domain provenance and reject orphan-producing writes.
|
||||
- [x] Bound Object/Revision metadata APIs with cursor pagination and batched
|
||||
read checks; compact search exposes full Path and safe matching excerpts.
|
||||
- [x] Common inert HTML projection boundary, bounded macro expansion, application
|
||||
CSP and cross-account browser denial tests; preserve canonical authoring bytes.
|
||||
See [policy and compatibility](html-projection-trust.md). No executable mode.
|
||||
- [x] Gate the first anonymous semantic/raw slice on explicit current-revision
|
||||
manifests, inert HTML, mutation invalidation and denial/revocation tests.
|
||||
- [ ] Extend those gates to anonymous discovery/dependencies and delegated
|
||||
shares with full impact-aware mutation/alias handling.
|
||||
- [ ] Add Domain groups, group Role bindings, and `/g/` management surfaces.
|
||||
- [ ] Add explicit OIDC/LDAP group mappings and policy-version invalidation;
|
||||
LDAP authentication must remain usable without enabling group synchronization.
|
||||
- [ ] Add auditable policy decisions.
|
||||
- [ ] Add an authorized effective-permission inventory for Campus, Domain,
|
||||
Quartier, Street, Spot, Page, share, group, Role, and Principal scopes.
|
||||
- [ ] Add explicit anonymous-read policy grants without weakening default deny.
|
||||
- [ ] Add signed PSK federation of selected Principal, group, Role, and grant
|
||||
records between Domains, including origin, sequence, conflict, revocation,
|
||||
and `campus_admin` inheritance policy.
|
||||
|
||||
## Cross-phase enabling work — Extension seams
|
||||
|
||||
These items must land before the later feature that depends on them. They are
|
||||
listed separately because they replace concrete single-feature assumptions
|
||||
without changing user-visible Page identity.
|
||||
|
||||
- [ ] Put filesystem `DocumentRoot` access behind the seekable, content-addressed
|
||||
Document Store interface before adding S3 or multi-node payload placement.
|
||||
- [ ] Generalize topology/event-job records into a versioned transactional
|
||||
Domain event outbox before notifications, feeds, metrics, comments, or DR
|
||||
consume mutation events.
|
||||
- [ ] Add a typed extension manifest and provider registry before adding third-
|
||||
party transpilers, widgets, scanners, storage backends, or themes.
|
||||
- [ ] Inventory process-local sessions, caches, preview slots, scheduler state,
|
||||
adapter workspaces, and signing material before declaring LB/HA support.
|
||||
- [ ] Add typed annotation/reaction/assessment stores keyed by Page and Revision
|
||||
UUID before exposing comments, likes, or quality evaluation in Viewer HTML.
|
||||
- [ ] Add privacy, retention, moderation, audit, export, and deletion contracts
|
||||
before collecting view history, engagement, comments, or notification data.
|
||||
|
||||
## Phase 5 — Delegation
|
||||
|
||||
- [ ] Add Macaroon root-key rotation and verification.
|
||||
- [ ] Implement attenuation caveats.
|
||||
- [x] Add server-rendered OGP/X link cards for already-public Page/home/City
|
||||
views, absolute configured-host URLs and a cached PNG fallback; retain
|
||||
authentication and private metadata suppression. See [social cards](social-link-cards.md).
|
||||
- [ ] Add read-only share projections under `/s/`.
|
||||
- [x] Add Quartier/Spot owner appointments and governance dialogs; subordinate
|
||||
publication policies may only narrow superior ceilings. Keep permission to
|
||||
publish separate from actual publication and preserve authenticated ACLs.
|
||||
See [detailed ownership/publication design](locality-publication-ownership.md).
|
||||
- [x] Add named user/group read and read/write settings with ancestor caps,
|
||||
stable identities, next-request membership checks and recovery authority.
|
||||
Initial namespace guards freeze protected moves/aliases and City structure;
|
||||
replace them with impact-aware mutation workflows in the next slice.
|
||||
- [x] Add bounded explicit current-revision approvals and a separate inert
|
||||
anonymous semantic Viewer/raw-media path with safe OGP and revocation tests.
|
||||
No automatic activation of drafts or future edits. See
|
||||
[exact scope and follow-ups](locality-access-publication.md).
|
||||
- [x] Public Page breadcrumbs, asynchronous children, read-only tree and filtered
|
||||
City navigation; database-generation cache invalidation and fresh authenticated
|
||||
read filters. Remove public download controls; reserve isolated presentation
|
||||
for share URLs. See [navigation contract](public-navigation.md).
|
||||
- [x] Add owner-managed `/u/{username}` audiences for profile metadata, avatar,
|
||||
Wiki root and descendants, plus narrowing subtree overrides, a dedicated
|
||||
anonymous reader/navigation snapshot, immediate superior-ceiling revocation,
|
||||
alias/UUID/Revision fences and atomic rename tracking. Keep `/u/` out of the
|
||||
global anonymous tree. See [user-space publication](user-space-publication.md).
|
||||
- [x] Harden anonymous navigation: public root/virtual-folder landing, read-only
|
||||
directory, Page/children round trips, tree expand/collapse/filter/keyboard
|
||||
controls, mobile header and City exits, cancellable bounded children loading,
|
||||
retries and progressive pagination; retain exact-publication boundaries.
|
||||
- [x] Explicit Street/Spot automatic publication with inherited manual-approval
|
||||
boundaries, confirmed impact previews, live publisher/ACL checks and cache
|
||||
invalidation. Existing scopes remain opt-in; see
|
||||
[implemented slice and limits](automatic-publication.md).
|
||||
- [ ] Immutable review requests, scoped approvers, durable outbox delivery and
|
||||
reviewer notification Inbox. Continue the remaining AP-1 through AP-6 work in
|
||||
[approval workflow design](publication-approval-inbox.md); automatic publication
|
||||
does not implement the human approval workflow or silently activate drafts.
|
||||
- [ ] Complete dependency/alias-aware publication previews, large-site review
|
||||
and per-capability audiences; current approvals exclude aliases, restricted
|
||||
user/group scopes and dependencies rather than implicitly publishing them.
|
||||
- [ ] Fence locality publication against alias/move/merge/archive/import bypass,
|
||||
and share one anonymous read evaluator across safe Viewer/media, City/search,
|
||||
children and OGP. Gate enablement on HTML isolation and revocation tests.
|
||||
- [ ] Add share management, expiry, revocation, access audit, optional password,
|
||||
download prohibition, language/path restrictions, and QR-friendly links.
|
||||
- [ ] Ensure share credentials are separate from login, adapter, federation,
|
||||
and API bearer credentials.
|
||||
|
||||
## Phase 6 — Activity, notification, and collaboration
|
||||
|
||||
- [ ] Formalize a Domain-sequenced event outbox for Page, Revision, Path,
|
||||
topology, policy, share, comment, reaction, quality, and federation events.
|
||||
- [ ] Add Page/Spot/Street/Quartier subscription and change-notification rules.
|
||||
- [ ] Add a per-Principal notification inbox with unread state, grouping,
|
||||
filtering, retention, cursor pagination, and authorization-safe deep links.
|
||||
- [ ] Add delivery channels for Web inbox, email digest, webhook, and future
|
||||
push adapters, with retry/dead-letter state in the event scheduler.
|
||||
- [ ] Add recently edited and recently viewed Page projections; keep private
|
||||
activity private and provide retention/opt-out controls.
|
||||
- [ ] Add privacy-aware Page view counters with bot filtering, idempotent event
|
||||
aggregation, time windows, and “most viewed” projections.
|
||||
- [ ] Add Page reactions/likes without modifying immutable Revision payloads.
|
||||
- [ ] Add document-quality assessments with rubric/version, reviewer identity,
|
||||
score history, and machine/human provenance.
|
||||
- [ ] Add Revision-anchored inline comments with text-range anchors, context
|
||||
hashes, orphan/rebase handling, resolution state, and permissions.
|
||||
- [ ] Add Page-level threaded comments below the document with moderation,
|
||||
mentions, subscriptions, edit history, and soft deletion.
|
||||
|
||||
## Phase 7 — Knowledge City services
|
||||
|
||||
- [ ] Complete Campus landing, Domain catalog, controller status, announcements,
|
||||
shared navigation defaults, audit, export, and delegated Campus governance.
|
||||
- [ ] Complete Quartier charter, entrances, localized signage, curators,
|
||||
announcements, scoped activity/search, subscriptions, health, merge/split,
|
||||
export/import, and policy-default surfaces.
|
||||
- [ ] Complete Street route intent, sections, Inbox, landing, activity,
|
||||
maintenance queue, subscriptions, merge/split/promotion, and policy override.
|
||||
- [ ] Complete Spot generated portal, curator workflow, dynamic sections,
|
||||
watchers/digests, backlinks, shortest routes, health states, split/merge,
|
||||
archive/successor, and machine-readable context payload.
|
||||
- [ ] Add Campus/Quartier/Street/Spot notification and permission inventory
|
||||
integration without turning locality into Page identity.
|
||||
|
||||
## Phase 8 — Controller disaster recovery and high availability
|
||||
|
||||
- [ ] Add controller manifest journal replication to a designated DR instance,
|
||||
including signing-key rotation/escrow, encrypted backup, sequence verification,
|
||||
last-known-good snapshots, RPO/RTO reporting, and restore drills.
|
||||
- [ ] Add controller leader election or manual promotion with fencing so two
|
||||
controllers cannot publish the same Campus sequence concurrently.
|
||||
- [ ] Add managed-instance controller failover using a pinned set of controller
|
||||
identities and an auditable promotion epoch.
|
||||
- [ ] Separate process-local cache/session/job state from canonical state and
|
||||
define shared/replicated backends required by multiple application nodes.
|
||||
- [ ] Add health, readiness, graceful drain, idempotency, forwarded-origin
|
||||
validation, and node identity endpoints for load balancers.
|
||||
- [ ] Add an LB reference deployment with TLS termination, WebSocket support,
|
||||
upload limits, no mandatory sticky session, and failure tests.
|
||||
- [ ] Add an HA metadata backend or a fenced single-writer/replica design;
|
||||
never mount the writable SQLite database concurrently from multiple nodes.
|
||||
- [ ] Add Document Store replication/read-repair and background-job leases so
|
||||
only one node performs a claimed task.
|
||||
- [ ] Exercise node loss, controller loss, network partition, stale replica,
|
||||
key rotation, and rollback in automated fault tests.
|
||||
|
||||
## Phase 9 — Content composition and extension runtime
|
||||
|
||||
- [ ] Evaluate tasks/tickets, an organizer with calendar/contact interoperability,
|
||||
RSS/Atom reading and FreshRSS/newsboat integration, IMAP mail-to-Wiki and
|
||||
incremental HTML editor improvements. Full WYSIWYG remains
|
||||
an open decision, not a commitment. See the design-only
|
||||
[organizer and editing ideas](organizer-and-editing-ideas.md); these are not part
|
||||
of the current implementation batch. The detailed design has since been expanded
|
||||
in the [Japanese handbook](ja/index.md), chapters 12–17; implementation remains
|
||||
unchecked and follows [the dependency-ordered plan](ja/roadmap.md).
|
||||
|
||||
- [ ] Add a versioned transpiler registry that converts PukiWiki, Redmine,
|
||||
DokuWiki, MediaWiki, and future source syntaxes into canonical HTML while
|
||||
preserving the original source as immutable metadata or a related Revision.
|
||||
- [ ] Complete Markdown round-trip guarantees and record compiler ID/version,
|
||||
warnings, source map, and canonicalization result on every conversion.
|
||||
- [ ] Add Excalidraw and draw.io canvas projections with immutable asset
|
||||
freezing and configured hosted-editor actions.
|
||||
- [ ] Add Kroki and PlantUML diagram adapters with bounded input, pinned renderer
|
||||
version, cached immutable output, timeout, and network policy.
|
||||
- [ ] Add nwdiag as a bounded network-diagram projection and editor adapter;
|
||||
support static SVG fallback, pinned renderer versions, and explicit source
|
||||
import/save without executing authored code.
|
||||
- [ ] Add a widget/oEmbed registry for Spotify, YouTube, SoundCloud, and future
|
||||
providers with Domain allowlists, consent placeholders, CSP sandboxing,
|
||||
privacy mode, and no arbitrary document-authored script execution.
|
||||
- [ ] Add administrator-packaged widgets with signed manifests, semantic
|
||||
versioning, capability declarations, resource quotas, and disable/rollback.
|
||||
- [ ] Add a generated top-page composer using authorized queries, static blocks,
|
||||
recent work, recent views, popular Pages, featured City entrances, and feeds.
|
||||
- [x] Add initial diary/blog template/query/navigation projections over ordinary
|
||||
Pages, not a new Page identity or date-dependent storage hierarchy. Registration
|
||||
metadata follows Page UUID; atomic new-post composition, local Domain projection,
|
||||
dedicated public article routes/navigation and RSS 2.0 are implemented.
|
||||
Remaining federation/metadata/Atom work is in the [follow-up plan](diary-blog-plugins.md).
|
||||
- [ ] Add directory-scoped RSS/Atom feed widgets with scheduler fetching,
|
||||
conditional requests, sanitization, per-host limits, caching, and provenance.
|
||||
- [ ] Add a bounded CSV table macro and CSV editor projection. RFC 4180-compatible
|
||||
CSV remains the interchange baseline; ODS is a separate multi-sheet adapter.
|
||||
- [ ] Add Reveal-compatible slide projection adapters for HedgeDoc and Slidev,
|
||||
plus a CSS-only scroll-snap/print editor fallback with explicit import/save.
|
||||
- [ ] Add custom theme packages with inheritance, tokens, preview, validation,
|
||||
CSP-safe assets, versioning, export/import, and one-click rollback.
|
||||
|
||||
## Phase 10 — External storage, inspection, and ecosystem
|
||||
|
||||
- [ ] Define a Document Store backend interface preserving SHA-256 identity,
|
||||
seek/range reads, atomic put-if-absent, integrity verification, and streaming.
|
||||
- [ ] Add S3-compatible immutable Document storage with multipart upload,
|
||||
server-side encryption, credential isolation, lifecycle policy, replication,
|
||||
local cache, and read-after-write verification.
|
||||
- [ ] Keep metadata, mutable configuration, and secrets out of the Document
|
||||
Store; external object keys must never replace Document SHA-256 identity.
|
||||
- [ ] Add asynchronous file inspection states (`pending`, `clean`, `suspicious`,
|
||||
`malicious`, `error`, `expired`) and quarantine-aware authorization.
|
||||
- [ ] Add MWDB/Karton integration through a bounded inspection adapter and event
|
||||
queue; Viewer/download policy must fail closed where a Domain requires audit.
|
||||
- [ ] Record scanner engine/version, signatures, hashes, timestamps, verdict
|
||||
provenance, rescan policy, administrator override, and audit events.
|
||||
- [ ] Add an extension catalog/API for projection, editor, transpiler, widget,
|
||||
notification, inspection, storage, search, and theme providers.
|
||||
- [ ] Add typed IPAM, DNS zone/record, and inventory/asset extensions with
|
||||
approval-gated provider writes, dry-run, etag checks, secrets, audit, and
|
||||
bounded queue execution.
|
||||
- [ ] Add extension signature verification, capability review, compatibility
|
||||
ranges, install/upgrade/disable/rollback, health, logs, and resource quotas.
|
||||
|
||||
Each phase requires schema migration, rollback analysis, and tests before the
|
||||
next phase begins.
|
||||
@@ -0,0 +1,401 @@
|
||||
# Implementation status and hardening backlog
|
||||
|
||||
For the consolidated current reading order, use the [Japanese handbook](ja/index.md)
|
||||
and [decision register](ja/decisions.md). Dated entries below preserve history;
|
||||
older statements about missing anonymous navigation, blog publication or RSS are
|
||||
superseded by the newer slices, not additional unfinished implementations.
|
||||
|
||||
This document is a working handoff for the current repository state. It is
|
||||
based on the implementation-roadmap, architecture documents, and a static
|
||||
review of the handlers and stores. Checked roadmap items describe a usable
|
||||
first slice; they do not imply production-ready federation, HA, or extension
|
||||
security.
|
||||
|
||||
## Current state
|
||||
|
||||
2026-09-25 task reminders: explicit per-task due/planned-date switches and a local
|
||||
notification time now schedule owner-only Inbox reminders. Reservations are updated
|
||||
in the source transaction; the bounded scheduler rechecks current state/authority,
|
||||
skips previous-day catch-up, and commits Inbox insertion plus acknowledgment together.
|
||||
Titles are projected under current authorization rather than copied into notices.
|
||||
Notification badges refresh on visible pages without reload. Calendar reminders,
|
||||
quiet hours, digests and external delivery remain pending. See [contract](ja/task-reminders.md).
|
||||
|
||||
2026-09-24 outbox follow-up: City now subscribes only to relevant page/revision/path/object
|
||||
events, with independent consumer checkpoints rather than shared processed flags.
|
||||
Per-type high-water marks avoid repeated full-history discovery. Task/project mutations
|
||||
append metadata-only events in their source transaction; a bounded scheduled bridge
|
||||
replays the earlier task journal idempotently. Notification delivery and retention are
|
||||
not included. See [delivery contract](ja/outbox-delivery.md).
|
||||
|
||||
2026-09-24 task first slice: private `organizer.tasks` items/projects, Today/Inbox/
|
||||
Backlog/Review/Completed/Archive UI, conditional updates, idempotent create,
|
||||
immutable CAS revision payloads and UUID-based Wiki references are implemented.
|
||||
Ownership is distinct from Wiki ACLs; even Domain administrators cannot read
|
||||
another principal's tasks through these endpoints. The local atomic change journal
|
||||
is now connected to the common outbox, but notification delivery, time-block/calendar integration, Pomodoro,
|
||||
sharing and VTODO synchronization remain follow-ups. SQLite metadata and the
|
||||
Document Store must be backed up together. See [contract and remaining work](ja/tasks-implementation.md).
|
||||
|
||||
2026-09-19 outbox foundation: `activity_outbox` now has a persistent, bounded
|
||||
envelope with Domain-local monotonic sequence numbers, actor/target references,
|
||||
idempotency keys, retry state and pending-page retrieval. The append API is
|
||||
transaction-bound and deliberately does not authorize or project payloads.
|
||||
Page creation and Revision writes now append through this envelope in their
|
||||
source transactions. Path rename/delete and Object purge are also recorded;
|
||||
Domain-local consumer checkpoints are durable and monotonic. A debounced City
|
||||
consumer now reconciles pending URL events through the scheduler and advances
|
||||
its checkpoint only after a successful plan. Recipient-scoped notification Inbox
|
||||
storage and an authenticated list/read API are now implemented with idempotent
|
||||
deduplication and keyset pagination; approval request producers, reviewer UI and
|
||||
delivery workers remain pending, so this is not yet a completed activity pipeline.
|
||||
|
||||
Street/Spot automatic publication is opt-in through the governance dialog. Current
|
||||
and future eligible heads follow the pinned Path boundary with live audience and
|
||||
enabling-actor authority checks. Domain/Quartier/Street/Spot manual-only floors narrow
|
||||
it; anonymous navigation/blog projection/RSS/share readiness follow the same policy.
|
||||
Existing scopes stay unchanged. Reviewer/Inbox and policy federation remain pending;
|
||||
see [automatic-publication.md](automatic-publication.md).
|
||||
|
||||
Local diary/blog projection first slice: Campus admins select source Domain and prefix
|
||||
inside the entry dialog. Same-Campus/local placement only, no copied content; both
|
||||
Domains' read policies filter private metadata; editing stays on the source Domain.
|
||||
Target article writes are rejected. Anonymous projection indexes/calendars now derive
|
||||
only from approved source Paths/Revisions, never private registration metadata.
|
||||
Dedicated-domain links now open `/YYYY/MM/DD[/keyword]` on that host with sanitized
|
||||
published bodies, calendar/month/adjacent-article navigation, target Domain branding
|
||||
and `/rss.xml` (20 items). Registered titles now explicitly inherit Page publication
|
||||
visibility; category/owner/registration date stay private. No cross-instance transport,
|
||||
source configuration federation or automatic cross-Domain session sharing yet.
|
||||
|
||||
RSS now includes sanitized, absolute-URL HTML in `content:encoded` with bounded
|
||||
generation and exact publication rechecks. Authenticated `/v/{blog|diary}/-/new`
|
||||
pages reuse atomic composition. Post completion offers X sharing with configured
|
||||
projection-domain URLs, target selection and unpublished-link warnings; no automatic
|
||||
social posting, publication grants or credentials are added.
|
||||
|
||||
Domain entry provisioning is implemented in source: Campus-admin dialog per Domain,
|
||||
explicit allowlisted settings, signed manifest v2 when settings are present, and
|
||||
transactional apply together with Domain snapshot/checkpoint. Legacy manifests without
|
||||
entry settings remain v1. Destinations must be upgraded before activating v2 settings;
|
||||
signed enrollment capability proof and Campus-wide preflight are implemented.
|
||||
Create-form integration, apply acknowledgments/freshness and control-release/GC remain
|
||||
pending. Managed nodes cannot override entry settings locally. No new public grants.
|
||||
|
||||
Atomic diary/blog composition is now implemented in source: Markdown composer,
|
||||
create/write checks inside the writer transaction, Page/Path/Revision/article/journal/
|
||||
receipt atomicity and idempotent retries. Shared Revision insertion and asset freezing
|
||||
are reused. Anonymous article-index approval, City/notification outbox dispatch,
|
||||
receipt retention and application acknowledgments remain pending. Existing
|
||||
two-step editor/registration is optional, not the only new-post workflow.
|
||||
|
||||
2026-09-17 URL/entry slice (source implementation): per-Domain diary/blog prefixes,
|
||||
date/keyword URL planner, same-day multiple diary entries, and home_layout diary/blog
|
||||
rendering at `/`. Placement label shortened; placement identity remains separate.
|
||||
The planner is read-only and does not reserve Paths. Editor save and registration
|
||||
remain separate in the legacy flow; public calendar approval is still TODO.
|
||||
Existing article Paths are not migrated.
|
||||
|
||||
Diary/blog initial slice: `content.diary` and `content.blog` are separate trusted
|
||||
built-ins with Domain enable/disable settings, Page UUID-bound metadata,
|
||||
calendar/recent entries/categories, registration/update/unregister dialogs and
|
||||
fresh read filters. Disabled by default; indices require authentication and
|
||||
registration does not publish a Page. Public index
|
||||
approval/feeds, comments and tDiary import remain explicitly deferred; see
|
||||
[detailed design](diary-blog-plugins.md).
|
||||
|
||||
2026-09-16 anonymous navigation hardening: public root and virtual parents now
|
||||
offer safe directory landing pages, with read-only `/v/browser` and separate
|
||||
Page/children links. Trees support all/per-folder expand/collapse, name/Path
|
||||
filtering and keyboard navigation. Responsive public headers, direct City exits,
|
||||
bounded/abortable asynchronous listings, retry and no-JavaScript pagination are
|
||||
implemented. No additional publication or approval policy is enabled.
|
||||
|
||||
2026-09-16 navigation follow-up: approved public Pages now expose filtered
|
||||
children/tree/City navigation and breadcrumbs, without a download button.
|
||||
Database generations invalidate bounded metadata caches; authenticated filters
|
||||
remain request-scoped, including group revocation on unchanged cached data.
|
||||
Private parent bodies/titles are not exposed through structural folders. See
|
||||
[navigation](public-navigation.md). Hierarchical approval requirements and the
|
||||
reviewer workflow remain [designed and TODO](publication-approval-inbox.md),
|
||||
while the reusable recipient Inbox API is available but not populated by approval
|
||||
requests. Approval request subjects, decisions, generation fencing and bounded
|
||||
expiry sweeps are persisted, but reviewer eligibility and decision UI are not
|
||||
exposed; the current explicit approval workflow remains in force.
|
||||
|
||||
2026-09-14 user/group and anonymous follow-up: named local user/group read or
|
||||
read/write settings now intersect ancestor caps, resolve stable subject IDs and
|
||||
observe live membership. Explicit bounded current-revision approvals enable a
|
||||
separate inert anonymous semantic Viewer and raw-media path with revocation and
|
||||
OGP. Existing visibility is unchanged until configured. Important first-slice
|
||||
limits: authenticated ACLs freeze protected namespace/City structural changes;
|
||||
anonymous edits require reapproval, and discovery/dependencies remain private.
|
||||
See [implementation contract and remaining tasks](locality-access-publication.md).
|
||||
|
||||
2026-09-14 locality governance: scoped Quartier/Spot co-owner appointments,
|
||||
versioned publication-cap drafts, transactional authority rechecks, local audit
|
||||
records and themed Japanese/English settings dialogs are implemented. Domain
|
||||
ceiling is in the City Map utility menu. The subsequent bounded anonymous slice
|
||||
and coarse namespace fences are described above; complete impact-aware
|
||||
mutation/dependency handling remains a next gate. See
|
||||
[exact first-slice scope](locality-publication-ownership.md).
|
||||
|
||||
2026-09-14 P0 HTML remediation, extended 2026-09-23: normal
|
||||
Viewer/home/profile/object/history/print and both Editor previews use the
|
||||
`controlled-v2` allowlist with application CSP. External resources remain
|
||||
default-deny; Domain administrators may approve exact HTTPS image URLs or
|
||||
SHA-256-pinned CSS/JavaScript URLs through the shared Projection/CSP policy.
|
||||
Canonical bytes are preserved; authored scripts/styles/frames are not activated.
|
||||
Diagram cache reads recheck Domain/Path authority and sandbox SVG. See
|
||||
[contract, compatibility and tests](html-projection-trust.md). Ownership/public
|
||||
activation remains separate work, not implicitly enabled by this security fix.
|
||||
|
||||
2026-09-14 publication governance design: explicit Quartier/Spot owners may
|
||||
administer publication only within superior ceilings; appointment authority,
|
||||
cap-vs-publication semantics, mutation/alias fencing and the release sequence
|
||||
are documented in [locality ownership](locality-publication-ownership.md).
|
||||
The owner API/UI and draft policies have subsequently been implemented as above;
|
||||
production visibility has not been changed.
|
||||
|
||||
2026-09-14 social-card follow-up: already-public semantic Pages, home layouts
|
||||
and City views now emit OGP/X metadata with bounded canonical-text summaries,
|
||||
safe absolute URLs and a common PNG cover (original images for image documents).
|
||||
Enforcing domains retain authentication and suppress content-card metadata;
|
||||
no visibility policy was changed. See [contract and limits](social-link-cards.md).
|
||||
|
||||
2026-09-14 City reference follow-up: parent-qualified readable Street URLs now
|
||||
replace ambiguous name-only links in map/search/macros. Details require ancestor
|
||||
read permission and fetch only the requested node; map focus and locality search
|
||||
work for Quartier, Street and Spot. Literal Page link encoding is shared by the
|
||||
map and its inspector. See [read integrity](city-read-integrity.md).
|
||||
|
||||
2026-09-14 City/search options follow-up: metadata-only Quartier/Street/Spot
|
||||
matches appear ahead of Pages, with visible ancestor context and safe links.
|
||||
Search now supports file categories, one extension, and Domain-local calendar
|
||||
date ranges over creation/update times. Filters run before candidate limits;
|
||||
City and Page reads share the existing deadline. See
|
||||
[search options and their exact semantics](search-results.md#city-first-results-and-search-options).
|
||||
|
||||
2026-09-14 search timeout follow-up: corrected a production Path-first repeated
|
||||
FTS scan and costly snippet generation. Input/time-bounded optional excerpts
|
||||
now preserve search results; query-plan and realistic-volume regressions plus
|
||||
read-only live-data timing cover the original blind spot. See
|
||||
[search correction](search-results.md#timeout-regression-and-correction-2026-09-14).
|
||||
|
||||
2026-09-14 hardening follow-up: authentication and inherited authorization,
|
||||
recursive mutations, federation snapshots and garbage collection now have
|
||||
bounded, denial/concurrency-focused regression coverage. City generation and
|
||||
PDF/archive metadata work are off the request/rendering path; search and history
|
||||
have bounded, clearer projections. See the [execution ledger](hardening-execution-2026-09.md)
|
||||
for validation/deployment and explicit deferrals. The subsequently corrected
|
||||
normal HTML boundary is recorded above; broader publication gates remain open.
|
||||
|
||||
2026-09-14 City UI follow-up: Spot clicks now explore their courtyards, with
|
||||
surrounding Page links, bounded nonoverlapping close-ups and a modal utility
|
||||
menu. Manual title/selection/merge/move controls remain available. See
|
||||
[City projection and its remaining limits](city-immersive-map.md).
|
||||
|
||||
2026-09-13 follow-up: execution and resource panels are now one monitor with only
|
||||
running jobs. Completed jobs and lazy, paginated logs share a history panel.
|
||||
Active queue counts avoid scanning completed history; job queries use indexed
|
||||
status filters and keyset pagination. Legacy `panel=resources` resolves to the monitor.
|
||||
The first resumed hardening task protects group owners from ordinary update
|
||||
downgrades and checks last-owner removal within the DELETE itself (including
|
||||
concurrent removals and manager authority against the target's current role).
|
||||
|
||||
Current follow-up adds viewport-responsive bookmark columns, persistent
|
||||
background resource monitoring, and a separate trusted system-extension
|
||||
catalog. Other system services are designed and sequenced in
|
||||
[System extensions](system-extensions.md); third-party plugin execution is
|
||||
not yet enabled. vim.wasm runtime work is paused at the user's request.
|
||||
|
||||
Latest UI follow-up: application asset authorization and `/e/` target decoding
|
||||
are corrected; home bookmarks support admin management, section cards and
|
||||
bounded asynchronous child links. Hosted Vim now explicitly loads its vimrc,
|
||||
local font and pure-Vimscript navigation plugin. See
|
||||
[implementation and remaining limits](home-bookmark-sections-vim.md).
|
||||
|
||||
Viewer shortcut follow-up: `e/f/v/c/u/s/p` and the four Ctrl-arrow navigation
|
||||
bindings are implemented in `static/js/viewer-shortcuts.js`. They suppress
|
||||
themselves while typing or inside dialogs; sharing copies the current canonical
|
||||
URL and opens a user-confirmed X Intent. The X action is cataloged as the trusted
|
||||
builtin `sharing.x` extension; it does not grant publication or create a share
|
||||
credential. Permission shortcut behavior depends on the City governance context.
|
||||
|
||||
The repository currently has working first slices for:
|
||||
|
||||
- Campus and Domain scoped semantic paths, local/remote placement, controller
|
||||
enrollment, signed manifest reconciliation, and the initial Knowledge City
|
||||
topology/map UI.
|
||||
- UUID/Object, immutable Revision, SHA-256 Document storage, language fallback,
|
||||
asset HEAD/history, bounded text and JSON projections, archive/CSV/EML/PDF
|
||||
adapters, and hosted code-server/vim.wasm/Excalidraw adapters.
|
||||
- Password/TOTP sessions, OIDC, LDAP/LDAPS, and SMTP magic-link flows, Domain
|
||||
capabilities, built-in campus/domain administrator groups, group permission
|
||||
profiles, and a centralized endpoint policy classifier.
|
||||
- Persistent event jobs with priority, retry, cancellation, concurrency
|
||||
settings, preview generation, import jobs, and manual scheduler controls.
|
||||
|
||||
The current deployment is a single writable SQLite application node plus a
|
||||
managed external-domain node. This is a supported development topology, not
|
||||
HA: canonical metadata, session revocation, scheduler claims, and adapter
|
||||
state are still process/instance local.
|
||||
|
||||
## Confirmed corrections (2026-09-14)
|
||||
|
||||
The [execution ledger](hardening-execution-2026-09.md) records verification and
|
||||
deployment separately. Completed, regression-tested slices include:
|
||||
|
||||
- OIDC issuer JWKS signatures, algorithm/claim checks, browser-bound state,
|
||||
bounded key/discovery fetches and account-binding collision rejection;
|
||||
[verification contract](oidc-verification.md).
|
||||
- SMTP connection/protocol deadlines, bounded replies, STARTTLS, mailbox/header
|
||||
validation, one-use challenges and live membership checks;
|
||||
[delivery limits](smtp-magic-link-hardening.md).
|
||||
- Campus-admin provenance and transactional derived-membership revocation while
|
||||
retaining independent local grants; [inheritance contract](campus-admin-revocation.md).
|
||||
- Same-origin browser mutation protection, POST logout, typed browser/API
|
||||
credentials, atomic session-state checks and request-scoped batch Path reads;
|
||||
[request boundaries](browser-request-security.md).
|
||||
- Domain scope for Object reads/saves/binds, exact exceptional Object grants and
|
||||
atomic API creation provenance; [Object scope](object-authority-scope.md).
|
||||
- Transactional complete-binding snapshots for recursive Path changes and
|
||||
all-alias Domain-local Object purges; [mutation integrity](path-mutation-integrity.md).
|
||||
- Atomic controller manifest sequence allocation and managed snapshot,
|
||||
inherited-permission and checkpoint application; authority collision and
|
||||
unsigned-downgrade rejection; [manifest integrity](federation-manifest-integrity.md).
|
||||
- Private, per-result City map/details/macros/badges, recomputed visible
|
||||
portals/counts/relations, local generation Worker, cancellation/cache bounds,
|
||||
directional keyboard navigation and immersive courtyards;
|
||||
[navigation contract](city-worker-navigation.md).
|
||||
- Persisted scheduler projections for PDF page counts and non-ZIP archive
|
||||
metadata, localized pending/retry UI and immutable Revision entry links;
|
||||
[projection cache](projection-metadata-cache.md).
|
||||
- Bounded compact search with full Paths, matching-source badges and safe
|
||||
excerpts/highlighting; [search contract](search-results.md).
|
||||
- Bounded metadata-only Object/Revision APIs and paginated history, retaining
|
||||
array response shapes and explicit continuation;
|
||||
[Object pagination](object-list-pagination.md), [Revision pagination](revision-listing.md).
|
||||
- Literal URL encoding in all three children views, including filenames with
|
||||
question marks, fragments, percent signs and non-ASCII characters.
|
||||
- One-connection-safe City read transactions with deadlines/ceilings and literal
|
||||
boundary matching; [read integrity](city-read-integrity.md).
|
||||
- Atomic bounded zombie selection/purge, current-Domain provenance for HTTP
|
||||
administration, retained global maintenance grace and orphan-writer guards;
|
||||
[GC integrity](zombie-gc-integrity.md).
|
||||
|
||||
These are not a claim that every endpoint, derived projection or write path has
|
||||
finished authorization and concurrency review.
|
||||
|
||||
### 2026-09-23: user-space audience controls
|
||||
|
||||
- `/u/{username}/_/edit` now separates profile metadata, avatar, Wiki-root and
|
||||
descendant audiences. Descendant exact/subtree overrides can only narrow the
|
||||
default, are CAS-versioned/audited, and follow atomic Path rename.
|
||||
- A dedicated anonymous live-head reader supplies user profile, Viewer/raw,
|
||||
children, scoped Tree and Browser projections without adding `/u/` to global
|
||||
anonymous navigation. It rechecks the Domain public ceiling per request and
|
||||
rejects aliases and UUID/Revision bypasses.
|
||||
- Authenticated listings and direct Object/Revision authorization also enforce
|
||||
private user-space audiences. Owner and Domain-admin recovery are explicit.
|
||||
Focused revocation, alias, navigation and recursive-rename tests pass. See
|
||||
[user-space publication](user-space-publication.md).
|
||||
|
||||
## Remaining gates and risks
|
||||
|
||||
### P0: authority and content trust
|
||||
|
||||
1. Finish authorization-policy/version fencing inside every write transaction.
|
||||
Recursive binding snapshots protect namespace races, not a concurrent
|
||||
revocation of the grants themselves. Typed decoded mutation targets,
|
||||
handler-method closure and idempotency remain wider cross-handler work.
|
||||
2. Complete publication-impact review and mutation fencing on the implemented
|
||||
owner/draft-policy and [inert HTML boundary](html-projection-trust.md). Keep public
|
||||
enabling gated on structural mutation/alias fences and common anonymous-read
|
||||
policy/revocation tests. See [ownership design](locality-publication-ownership.md).
|
||||
Extend denial tests to each new projection; CSP is not an authorization grant.
|
||||
3. Local-email ownership, explicit external-account linking, provider subject
|
||||
migrations and administrator last-owner suspension/transfer need dedicated
|
||||
lifecycle workflows. Rejecting ambiguous email matches is not email proof.
|
||||
4. Domain-to-Domain PSK identity/group/grant inheritance needs its own origin,
|
||||
replay, conflict and revocation contract. The completed Campus-admin local
|
||||
projection is not that cross-instance synchronization feature.
|
||||
5. Audit remaining list/projection, asset and adapter paths with
|
||||
denial-focused tests before claiming complete Domain isolation. Legacy
|
||||
unknown-origin unbound Objects require explicit grants or trusted recovery.
|
||||
HTTP zombie GC is now provenance-scoped; trusted global maintenance remains
|
||||
a distinct instance authority rather than a Domain administrator operation.
|
||||
|
||||
### P1: City correctness and responsiveness
|
||||
|
||||
See [City review and reconciliation](city-review-and-reconciliation.md).
|
||||
CITY-A through CITY-D remain partially open. Remaining work includes shallow
|
||||
Path/portal inference, deterministic generated Spot name collisions,
|
||||
idempotent no-op application, explicit generated/manual ownership, exclusion
|
||||
tombstones, event watermarks and a transactional mutation outbox.
|
||||
|
||||
Worker generation and bounded courtyard DOM do not solve connected/fair road
|
||||
allocation or all main-thread topology/layout work. Lazy locality/Page
|
||||
projections and a directory index remain important for much larger Wikis.
|
||||
The Viewer sidebar / paginated navigation API is also separate from the
|
||||
already-implemented home layouts and scoped Tree View.
|
||||
|
||||
### P1: projection and storage scaling
|
||||
|
||||
1. Non-ZIP entry extraction still runs a bounded foreground decoder. Durable
|
||||
entry artifacts need quotas, leases, Range semantics and archive-bomb policy.
|
||||
ZIP central-directory parsing and nested/compressed TAR expansion need their
|
||||
own bounded worker/index contract.
|
||||
2. Native decoders have input/output/thread/time bounds, not hard memory/cgroup
|
||||
limits. A weighted scheduler resource budget and decoder isolation remain.
|
||||
3. Search FTS still contains historical revisions; current-only indexing,
|
||||
Japanese infix search and sanitized plain-text indexing are separate tasks.
|
||||
SQL deadlines/candidate bounds limit work, not unlimited recall.
|
||||
4. Browser/children/Tree and some link projections still aggregate large Path
|
||||
sets. Request-scoped ACL removes repeated grant queries but does not replace
|
||||
a directory index, bounded SQL candidates or fully opaque continuations.
|
||||
5. Large-binary restore and several trusted full-list helpers still hydrate or
|
||||
enumerate complete data. HTTP Object/Revision pagination does not silently
|
||||
change explicit CLI full exports.
|
||||
6. Remote Document Store backends, read-repair, retention proofs, cross-instance
|
||||
job leases, dead-letter operations and writable metadata fencing remain.
|
||||
|
||||
### Operations and intentionally deferred high-risk work
|
||||
|
||||
- Existing deployment is two application instances with separate SQLite state,
|
||||
not a shared-writer HA service. DR/LB require replication, fencing, key custody
|
||||
and recovery drills; no live SQLite-over-network-filesystem shortcut.
|
||||
- Enrollment tokens currently present in compose must be moved to a selected
|
||||
secret mechanism and rotated deliberately. No credentials were automatically
|
||||
replaced, printed or copied as part of these repairs.
|
||||
- Untrusted plugin execution/native helpers remain disabled/deferred until the
|
||||
runtime capability/signature/isolation model exists. vim.wasm runtime work
|
||||
remains on the user's explicit hold.
|
||||
- Live S3/SSHFS/WebDAV/MWDB/Karton/SNMP/LDAP integration requires selected endpoints,
|
||||
credentials and test services. No external service was provisioned implicitly.
|
||||
|
||||
## Ordered next work
|
||||
|
||||
1. Add complete publication-impact previews and structural mutation/alias fences
|
||||
to locality governance; keep anonymous access disabled until all publication
|
||||
gates and fresh activation confirmations are satisfied.
|
||||
2. Complete remaining mutation/policy transaction fences and account ownership
|
||||
lifecycle; preserve denial tests and audited provenance.
|
||||
3. Finish bounded/lazy City and directory projections; implement idempotent
|
||||
URL inference with generated/manual ownership before automatic event-driven
|
||||
application.
|
||||
4. Add the transactional Domain activity outbox, verified actor attribution,
|
||||
durable consumer watermarks and recent-edit projections.
|
||||
5. Then add delegated shared links, notifications/inbox, moderated comments,
|
||||
rankings/quality, diary calendar/recent entries/comments and resumable tDiary
|
||||
import. Their detailed contracts remain in [System extensions](system-extensions.md).
|
||||
6. External connectors, isolated third-party plugins and DR/LB/HA follow only
|
||||
after their authority, retention and operations prerequisites are met.
|
||||
|
||||
## Verification expectations
|
||||
|
||||
Every hardening slice must run `go test ./...`, include a regression test for
|
||||
the denied case, and update the relevant design document and roadmap checkbox.
|
||||
Deployment validation must confirm both app nodes are healthy and that a
|
||||
foreground request cannot expose another Domain's Object, Revision, Path, or
|
||||
adapter workspace.
|
||||
@@ -0,0 +1,61 @@
|
||||
# アクティブ通知とWeb Push
|
||||
|
||||
更新:2026-09-25。実装・隔離fixture検証済み。同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。実機Push受信確認は未実施。
|
||||
|
||||
## UIと設定
|
||||
|
||||
通知ベルを開いたInboxの「⚙ 通知設定」に集約する。アカウント・ドメイン・ブラウザごとにlocalStorageへ保存し、他ユーザの設定を継承しない。通知本文はlocalStorageに保存しない。
|
||||
|
||||
| 状態 | 動作 |
|
||||
| --- | --- |
|
||||
| フォーカス中 | 右下に8秒で消えるトースト。最大3個。入力フォーカスを奪わない。既定ON |
|
||||
| 別タブ・別ウィンドウ/タブ終了 | 明示的に許可した端末へWeb Push。OSの通知UIを使用 |
|
||||
| 再訪 | 前回訪問以降の未読がある場合、設定ONならInboxを自動表示。既定OFF |
|
||||
| ダイアログ・入力を操作中 | 自動Inboxは保留し、次の確認時まで待つ |
|
||||
|
||||
新着は30件ずつ取得し、Inboxは「さらに表示」でページングする。訪問watermarkはサーバー時刻を使う。Web Locksと通知UUIDの短い履歴(最大200個)で複数タブのトーストを抑制する。Web Locks非対応時はbest effort。
|
||||
|
||||
音は「なし/ソフト/チャイム/ベル」と音量・試聴。Web Audioはブラウザの自動再生制限に従い、利用者の操作後に有効になる。カスタム音はフォーカス中のページ通知用。背景/タブ終了時の音はOS設定で決まり、サイト側から任意の音に置き換えることは保証しない。
|
||||
|
||||
ブラウザの通知許可は設定操作時のみ要求する。HTTPSと対応ブラウザが必要。iOS等はホーム画面への追加など端末側の条件もある。サービス・省電力・通信・キュー待ちに依存するため、定刻到達を保証するアラーム用途ではない。
|
||||
|
||||
## 配信経路と安全性
|
||||
|
||||
`notification_inbox`挿入のDB triggerで`notification_push_queue`へ原子的に追加する。Inboxの全種類(タスク期限・計画日、Pomodoro、アナウンス等)で同じ経路を使う。購読開始前の通知を一斉再送しない。
|
||||
|
||||
`/_/api/v1/notifications/push`:
|
||||
|
||||
- GET: VAPID公開鍵のみ。秘密鍵はDB内部に保存。
|
||||
- POST: PushSubscription、focused、seen(最大30通知ID)。購読更新/閲覧中のack。
|
||||
- DELETE: 現在の利用者が所有する購読を削除。
|
||||
|
||||
購読はDomain・Principal・**元の認証セッションのハッシュ**に束縛する。Bearer tokenは保存しない。配信時にセッション期限/失効、Principal、membership、Domain配置を再確認する。ログアウト後や無効化後は送信しない。最大8購読/利用者・Domain、30日lease(閲覧時に更新)。
|
||||
|
||||
VAPID秘密鍵は`notification_push_keys`に保存するため、DBバックアップを秘密情報として扱う。鍵を失った復旧では再購読が必要。端末の購読URL・鍵・通知本文をログへ出さない。
|
||||
|
||||
送信先はChrome/Chromium FCM、Mozilla Push、Apple Web Pushに限定。HTTPS/443のみ、資格情報・fragmentを拒否し、公開IPをDNS解決後に固定する。proxy環境変数とredirectは使用しない。プライベートIPへの接続は禁止する。Push本文は暗号化された通知UUID/受取人UUID/Domain UUIDのみ。件名・本文をPushサービスへ送らない。OSに表示するのも一般的な「新着通知」のみ。クリック後に通常の認可されたInboxで詳細を表示する。
|
||||
|
||||
Service Workerは`/static/js/notifications-worker.js`、scopeは`/static/js/`。fetch handlerやページキャッシュを持たず、既存のWikiページ/エディタに古い内容を返さない。notificationclickは同一originの`/v/notification`だけを開く。
|
||||
|
||||
## スケジューラと上限
|
||||
|
||||
イベント`notification.push.deliver`、定義`builtin.notification.push`。既定30秒、priority -3。設定画面のイベント設定から停止・間隔変更・手動実行でき、再起動で既存設定を上書きしない。
|
||||
|
||||
- 最大20件/run、全体25秒、送信要求5秒。DB transaction内でネットワーク通信しない。
|
||||
- 60秒のclaim lease。期限切れを再取得できる。クラッシュ時はat-least-onceだが、ブラウザ通知tagを固定し積み上げない。
|
||||
- 429/5xx/通信失敗は指数backoff、最大5試行。404/410は購読を削除。
|
||||
- キューの有効期間24時間、Push側TTL300秒。期限切れキュー削除は最大500件/run、期限切れ購読削除は100件/run。
|
||||
- フォーカスlease90秒。閲覧中は送信を延期し、ブラウザが一覧を受け取った通知のackでキューを消す。表示できなかったままタブが閉じればlease終了後に再評価する。
|
||||
- 前面pollは30秒。Pushが有効な背景タブは定期pollを停止し、Pushと復帰を契機に更新する。
|
||||
- sent/failed集計をイベントログへ記録。再送でもInbox本体は複製しない。
|
||||
|
||||
フォーカスを失う瞬間やネットワーク遅延にはraceがあり、OS通知を完全に抑制する保証はしない。常に通知権限とOSの設定が優先する。
|
||||
|
||||
## 検証・残TODO
|
||||
|
||||
- Go: 原子rollback、claim重複防止、focus延期とack、他人のack拒否、失効後の配信遮断、backoff、購読API認証、公開鍵のみ、送信先とP-256鍵検証、イベント設定保持。
|
||||
- Chromiumの合成fixture: 前面トースト、再訪Inbox、設定モーダルの横幅、既存Inbox既読/バッジ。実通知サービスへは送っていない。
|
||||
- TODO: 実機Chrome/Firefox/Safari/iOSでの購読・閉タブ配信・復帰・logoutを確認。Pushサービス障害テストの拡充、端末一覧/VAPID rotation UI、quiet hours/digest、種類別設定、OS通知の詳細表示opt-in、端末間の個人設定同期。
|
||||
- TODO: expired/revoked購読の清掃メトリクス、Push queue深さ/遅延/失敗コードの管理UI。旧worker購読の移行手順。
|
||||
|
||||
参考:[MDN Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)、[MDN Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)、[webpush-go](https://github.com/SherClockHolmes/webpush-go)。
|
||||
@@ -0,0 +1,43 @@
|
||||
# 2. アドレス・保存・アセット
|
||||
|
||||
状態:基本モデルとローカル保存は実装済み。外部保存・保持管理の一部はTODO。
|
||||
|
||||
## アドレス表
|
||||
|
||||
| 内部指定 | 意味 | HTTP上の主な入口 |
|
||||
| --- | --- | --- |
|
||||
| `path:/manual/start` | ドメイン内の可変な住所 | `/manual/start` |
|
||||
| `uuid:…` | Page/Objectの安定ID | `/o/uuid:…` |
|
||||
| `rev:…` | 特定の不変Revision | `/r/view/…`、`/v/raw/rev:…` |
|
||||
| `sha256:…` | 不変Document | `/_/obj/sha256:…` |
|
||||
| `asset:image:logo` | ドメイン内の編集用HEAD | 管理者向け `/v/raw/asset:image:logo` |
|
||||
|
||||
通常エディタの正規入口は `/e/-/{path}`。従来の `/e/{path}` は互換入口です。生データは `/v/raw/path:/…` 等を使い、通常Pathと紛らわしい `/raw/` を増設しません。別ドメインへのリンクは宛先FQDNを含む絶対URLです。
|
||||
|
||||
## 保存トランザクション
|
||||
|
||||
1. 言語・MIME・保存対象と現在の書き込み権限を検証する。
|
||||
2. 内容のSHA-256を計算し、`documents/sha256/` に不変Documentを永続化する。
|
||||
3. Page、Revision、必要なPathと依存参照を確定する。
|
||||
4. 派生処理へ通知する。共通outboxの全書き込み接続は後続課題。
|
||||
|
||||
Documentを先に書くため、DBのrollbackで未参照blobが残る可能性はあります。逆に、DBだけ確定して正本バイト列が存在しない状態は許しません。SQLiteのbody列は移行互換用で、Document Storeと二つの正本を作りません。
|
||||
|
||||
## アセットの可変HEADと固定参照
|
||||
|
||||
Asset名は `(domain_uuid, asset address)` で一意です。HEAD変更は旧Documentを上書きしません。HTML保存時に `asset:` を解決し、表示用参照をSHA-256へ固定します。編集用の由来は別属性で残し、次回保存時にHEADを再解決します。
|
||||
|
||||
`revision_document_refs` が依存Documentを記録します。過去Revisionの閲覧で最新HEADへ追従しないことが再現性の条件です。CLIと管理画面ではHEADを扱えますが、公開ページの依存物を自動公開する根拠にはなりません。
|
||||
|
||||
## 認可・条件付き操作
|
||||
|
||||
ハッシュURLは現在のDomainで読めるPageや許可された管理操作との関係を検証します。ETagと `X-PagesWiki-Object-UUID`、`X-PagesWiki-Revision-UUID`、`X-PagesWiki-Document-SHA256` は識別情報であり資格情報ではありません。
|
||||
|
||||
Asset更新は条件付き更新を使います。ただし同じ内容でMIME等だけ変わる競合には、HEADハッシュとは別の状態versionを導入する設計が必要です。
|
||||
|
||||
## TODO
|
||||
|
||||
- 保持期限・削除プレビュー・export中の保護を統合したDocument GC。
|
||||
- Assetの状態version、共通監査outbox、依存関係込みの公開レビュー。
|
||||
- 大容量復元のストリーミング、外部Document backend、破損検出とread-repair。
|
||||
- CLIの全書き込みとWebの正本保存契約の統一。CLIは現在も信頼されたローカル管理経路で、HTTP認可を迂回する点を明示する。
|
||||
@@ -0,0 +1,59 @@
|
||||
# 5. 認証・グループ・権限
|
||||
|
||||
状態:パスワード・TOTP・セッション、OIDC、LDAP、SMTPリンク、グループと主要な認可経路は実装済み。全経路の監査完了を意味しません。
|
||||
|
||||
## 認証から認可へ
|
||||
|
||||
認証器はPrincipal identityを証明します。その後、Domain membership、グループ・Role、対象操作のcapability、上位Localityの制限を評価します。OIDCのclaimやメールアドレスだけで管理権限を付与しません。
|
||||
|
||||
Principalにはactive / readonly / suspended / quarantinedの状態があります。membershipや状態の失効は次の要求で反映します。
|
||||
|
||||
LDAPはドメイン単位で設定します。検索用アカウントで`{{username}}`を
|
||||
RFC 4515エスケープして一意なエントリを取得し、そのエントリのユーザーDNで
|
||||
再bindできた場合だけ認証成功です。初回だけローカルの一意なユーザー名または
|
||||
メールアドレスへ連結でき、その後は`entryUUID`やActive Directoryの
|
||||
`objectGUID`など、設定した不変属性とprovider UUIDの組で識別します。DN、表示名、
|
||||
メールアドレスを継続ログインの識別子にはしません。自動作成は任意で、作成時は
|
||||
ローカルパスワードを持たない通常のmemberに限定します。
|
||||
|
||||
LDAP/LDAPS、StartTLS、証明書検証、追加CA PEM、検索Base DNとfilter、属性mapping、
|
||||
既存アカウントの照合項目、保存済み設定によるログインテストを管理画面から設定
|
||||
できます。bindパスワードは暗号化し、利用者パスワードは保存・ログ出力しません。
|
||||
LDAPグループをPagesWikiのグループや権限へ同期する処理は認証と分離し、明示的な
|
||||
mappingだけを適用する後続タスクです。
|
||||
|
||||
## セッションの目的を分離する
|
||||
|
||||
ブラウザはHttpOnlyのホスト限定Cookie、APIは明示的なBearer credentialを扱います。現行はブラウザ用とAPI用のトークン種別を分け、相互に流用しません。「全画面でlocalStorageへBearerを置く」構成にはしていません。
|
||||
|
||||
adapter、federation、認証challenge、将来のshareはそれぞれ別の検証系です。明示された無効なAuthorizationをCookieで救済しません。Cookie経由の変更には同一origin検証、ログアウトにはPOSTを使います。
|
||||
|
||||
OIDCはissuer・署名・claim・state/nonce/PKCE・browser bindingを検査します。SMTPリンクは短命・一回限りのchallengeで、配送遅延をログイン要求に持ち込みません。メール一致とメール所有の証明、外部identityの明示的な連結は引き続き整理が必要です。
|
||||
|
||||
## 権限プロファイル
|
||||
|
||||
| 表示用プロファイル | 許可する内容 | 許可しない内容 |
|
||||
| --- | --- | --- |
|
||||
| read | 閲覧 | 全変更 |
|
||||
| read/write once | 未存在の対象の新規作成・アップロード、閲覧 | 上書き、再編集、削除 |
|
||||
| read/write | 閲覧・作成・更新・rename・link | deleteの暗黙付与 |
|
||||
| upload only | 指定範囲の未存在対象へアップロード | 一覧、閲覧、上書き、削除 |
|
||||
| group admin / user | グループ内の管理上の役割 | それだけを根拠にした本文権限 |
|
||||
|
||||
削除は独立したgrantです。新規作成・uploadの可否は正規化後の最終Pathをトランザクション内で検査します。Pathを先に調べ、後で無条件上書きする実装は禁止です。
|
||||
|
||||
## 管理グループと所有者
|
||||
|
||||
`campus_admin` はキャンパスとドメイン配置、`domain_admin` はDomain設定・アカウント・グループを管理するビルトイングループです。普通のグループ管理者がこれらを自分へ付与できてはいけません。
|
||||
|
||||
Quartier・Spotのco-ownerは公開設定等の委譲された管理者です。所有者であることと、上位が許可していない公開を広げることは別です。
|
||||
|
||||
## TODO
|
||||
|
||||
- 全変更経路で認可versionと更新対象を同一トランザクションに固定する。
|
||||
- 最後の管理者の停止・移管、メール所有、外部identity連結・解除。
|
||||
- OIDC/LDAP外部グループの明示mapping、由来を保持した同期・失効・監査。
|
||||
- 説明可能な権限総覧:付与元、継承、上位制限、対象操作、失効理由を表示する。
|
||||
- PSK継承、adapter、Asset等を含む拒否・競合・再送テストの拡充。
|
||||
|
||||
個人用 `/u/{username}`、グループ用 `/g/{groupname}` は本文領域と `/_/edit` 等の管理領域を区別します。プロフィール画像変更を本文の無制限履歴と混同しません。ユーザー領域の所有者はプロフィール情報・画像・Wiki root・配下のaudienceを個別に狭められます。`private` は通常のDomain read grantより優先し、所有者と復旧権限を持つDomain管理者だけが読めます。匿名公開はDomainのpublic上限を越えられません。
|
||||
@@ -0,0 +1,35 @@
|
||||
# 10. ブログ・日記・公開ドメイン射影
|
||||
|
||||
状態:投稿・登録・カレンダー・同一インスタンス射影・公開記事・RSSは実装済み。コメント、tDiary移行、遠隔射影はTODO。
|
||||
|
||||
## 記事の実体とURL
|
||||
|
||||
ブログと日記は別のシステム拡張ですが、本文は通常Page/Revisionです。Domainごとのprefixに対し `{prefix}/yyyy/mm/dd`、任意keywordがあれば `{prefix}/yyyy/mm/dd/{keyword}` へ作成します。同日複数記事が可能です。
|
||||
|
||||
日付・著者・カテゴリ等はPage UUIDに紐づく記事メタデータです。Path変更で失わず、登録解除でPage本文は消しません。日付はcivil dateで、timezone変更時に過去の記事を勝手に別日へ移しません。
|
||||
|
||||
## 表示と投稿
|
||||
|
||||
月別は `/v/blog/yyyy/mm`、日別は `/v/blog/yyyy/mm/dd`。日記も同様です。`?own` とカテゴリを日付移動で維持します。`/v/blog` は全期間、日記の入口は当月が基本です。日付の旧query入口は正規Pathへ案内します。
|
||||
|
||||
タイトル下は日付とタイトルのコンパクトな一覧、月入力・適用・リセットはカレンダー上の一行です。大量記事では読みやすさとページ送りを優先します。
|
||||
|
||||
`/v/blog/-/new` と `/v/diary/-/new` は認証された投稿画面です。Page、Path、Revision、記事情報、journal、再送receiptを原子的に作成します。既存Pathは409、同じrequest_idの再送は重複作成せず返します。入力変更後の同じID流用も409です。
|
||||
|
||||
## 専用ドメインはコピーではなく射影
|
||||
|
||||
例:元ドメインの `/blog` を `blog.pages.anya.jp/` に表示します。現行は同一Campus・同一インスタンスに限ります。編集は元ドメイン、表示の名称・テーマは表示先ドメイン、専用記事リンクは `/yyyy/mm/dd[/keyword]` です。
|
||||
|
||||
元が非公開なら、射影の設定だけで公開しません。匿名一覧・月件数・記事本文は承認済みまたは自動公開条件を満たす内容に限定します。登録タイトルはPage公開を継承しますが、他の登録メタデータまで無条件に公開しません。設定不整合で別の内容へ黙ってfallbackしません。
|
||||
|
||||
## RSSとX
|
||||
|
||||
専用ドメインの `/rss.xml` は最新20記事を配信し、`content:encoded` に安全化したHTMLを含めます。リンクを絶対URLへ直し、正確な公開状態を再検査します。1記事1 MiB入力、合計8 MiB、5秒の生成制限を持ちます。
|
||||
|
||||
投稿後のXシェアはWeb Intentをユーザーが押す方式です。設定された専用ドメインのURLを選び、未公開なら警告します。投稿完了、公開完了、X投稿完了を同じ状態にしません。既にRSS等へ複製された本文は撤回できません。
|
||||
|
||||
## TODO
|
||||
|
||||
遠隔記事射影の署名・取得・失効、metadata公開範囲、Atom、keyset paging、outbox接続、receipt/孤立データ保持、予約公開、コメント・最近のコメント、tDiary import。
|
||||
|
||||
tDiaryは対応版・入力形式をfixtureで固定し、Ruby/eval/Marshalを実行して取り込む方法は使いません。旧URL、セクション、添付、コメント著者の出典を保持し、重複・部分失敗から再開できる取り込みを設計します。
|
||||
@@ -0,0 +1,70 @@
|
||||
# 予定・タスク共通CalDAV接続
|
||||
|
||||
2026-09-27追記:`organizer.tasks 0.10.0`で[MKCALENDARによるVTODOリスト作成](caldav-task-lists.md)を追加。共通直下のUUIDはVEVENTまたはVTODOリストを表し、種別でハンドラを選ぶ。予定本文の読み込みで判定しない。
|
||||
|
||||
2026-09-26実装。`organizer.calendar 0.2.0`/`organizer.tasks 0.9.0`。01:33 JSTに本番両インスタンスへ反映済み。[反映・検証記録](../../operations/deployments/2026-09-26-common-caldav.md)。
|
||||
|
||||
2026-09-27追記:[OneTask向け互換モード](caldav-onetask-compatibility.md)を実装、10:01 JSTに本番反映。通常は引き続き`calendar-access`を宣言せず、明示ONで発行した資格情報のみ接続判定互換のため宣言する。完全なRFC準拠ではない。実機の同期完了は未確認。
|
||||
|
||||
## 1. 接続と認証
|
||||
|
||||
共通接続先は `/_/api/v1/caldav/`。slash有無ともリダイレクトせずPROPFINDを処理する。rootはcurrent-user-principal/principal-URL/calendar-home-setを返す。Depth 1は許可された予定カレンダー(VEVENT)と個人タスクコレクション(VTODO)を返す。予定とタスクを同じICSリソースに混在させない。
|
||||
|
||||
| 対象 | URI |
|
||||
| --- | --- |
|
||||
| 共通home/principal | `/_/api/v1/caldav/` |
|
||||
| 予定 | `/_/api/v1/caldav/{calendarUUID}/` |
|
||||
| 個人タスク | `/_/api/v1/caldav/tasks/default/` |
|
||||
| 既存タスク専用home(維持) | `/_/api/v1/caldav/tasks/` |
|
||||
| 接続資格情報の発行/一覧 | `POST/GET /_/api/v1/caldav-credentials` |
|
||||
| 失効 | `DELETE /_/api/v1/caldav-credentials/{id}` |
|
||||
|
||||
予定/タスク両画面の⇄ボタンから共通設定を開く。発行時に対象 `tasks`(タスクのみ)、`calendar`(予定のみ)、`all`(両方)とread/write、有効期間を明示選択する。初期選択は開いた画面の対象で、両方を自動付与しない。
|
||||
|
||||
Basicのユーザー名は資格情報ID、パスワードは発行時のみ表示するランダム値。従来と同様、秘密値はSHA-256のみ保存し、閉じたダイアログからも消去する。通常ログインセッションでのみ発行/失効できる。DAV資格情報をWikiやJSON APIのログインとして利用することはできない(匿名公開APIを非ログイン扱いで参照できることとは別)。HTTPSを使う。
|
||||
|
||||
既存の資格情報と旧管理APIは維持。`organizer_dav_scopes`に対応行がない資格情報は必ず`tasks`として扱う。既存資格情報を予定アクセス付きに更新するAPIは設けず、新規発行と旧資格情報の明示失効で切り替える。新規の予定/共通秘密値は`pw_dav_`、既存互換タスク秘密値は`pw_taskdav_`。古いバイナリは`pw_dav_`を拒否するため、切り戻し時にも予定限定資格情報がタスク権限へ化けない。
|
||||
|
||||
## 2. 認可
|
||||
|
||||
- 資格情報をドメイン/所有者/期限/失効状態に結び、principalとdomain membershipの状態も確認する。
|
||||
- Scopeは対象種別の上限であり、他人のカレンダーを共有する権限ではない。既存のカレンダーowner/member/publicポリシーを別途適用する。
|
||||
- 共通homeの探索結果はscopeと有効な拡張機能で絞る。片方の拡張が無効でも、他方の接続設定・探索は動く。
|
||||
- 予定の書き込みは資格情報のwrite許可、active状態、カレンダーのCanWriteを全て必要とする。外部ソース由来カレンダーは従来通り書き込み不可。
|
||||
- 予定変更時はカレンダーmetadata lock内でACLと資格情報の失効・期限・write・scopeを再確認する。タスクは既存のDB transaction内再確認を維持する。
|
||||
- API・DAV応答はprivate/no-store。通常の匿名公開予定の読取経路は維持し、無効なBasic資格情報を匿名扱いにフォールバックしない。
|
||||
|
||||
## 3. 予定のresource名と正本
|
||||
|
||||
Web作成分は従来の`base64url(UID).ics`を維持。CLIが作成する任意の安全なASCIIファイル名(英数字・`.`・`_`・`-`、末尾`.ics`、最大700 bytes)を受理する。UIDとファイル名は別の識別子。
|
||||
|
||||
CLI由来のUID→filenameは`calendar.json`の`dav_names`として保持する。新規resource予約と月別ICSを同じmanifest置換でcommitする。DBだけのaliasにはせず、索引再構築・カレンダー設定変更でも保持する。削除時は対応aliasも削除する。同じcalendar内のUID重複、filename衝突、既存UIDの差替えを拒否する。
|
||||
|
||||
既存のWeb用canonical URLも引き続き解決する。WebビューアはfilenameをUIDとしてbase64 decodeする前提を廃止し、既存JSONイベントAPIの`?resource={filename}`でサーバー側解決する。`?uid=`も維持。ETag一致時には本文を取り直さない。
|
||||
|
||||
新規PUTは`If-None-Match: *`を推奨するが、chroncal互換で完全な新規identityに限り条件なし作成も可能。既存更新にはIf-Match(未指定428、不一致412)を必須とし、並行作成でも上書きしない。DELETEは予定の削除、タスクのアーカイブという既存の意味を維持する。
|
||||
|
||||
## 4. 取得上限と互換性
|
||||
|
||||
- 従来のtime-range付きREPORTとETagを利用したWeb表示を維持する。
|
||||
- 初回同期用の全件calendar-query(VCALENDAR全体、またはVEVENT指定)を追加。metadata lock内で完全なsnapshotを取得し、最大10,000 resource/32 MiBを超えれば507で全体を失敗させる。黙った切り捨てはしない。
|
||||
- PROPFIND Depth 1による予定resource列挙、全項目calendar-data選択にも対応。無制限Depth、部分projection、未対応filterは拒否する。
|
||||
- 1 resource上限256 KiB、multigetは200 href、DAVリクエストは20秒上限。既存のtime-range上限370日も維持する。
|
||||
- sync-collection/sync-tokenは未対応。405を返し、chroncalはcalendar-queryへフォールバックする。完全なCalDAV適合を示すcalendar-accessは広告しない。
|
||||
- 新規予定のiCalendar対応範囲は従来のまま:単独VEVENT、UTC DATE-TIMEまたはDATE。TZID/VTIMEZONE、浮動時刻、繰り返し、VALARMは書き込み未対応。chroncalの`--timezone`で出力されるVTIMEZONEも拒否する。情報を黙って欠落させる変換はしない。
|
||||
|
||||
## 5. 検証と運用
|
||||
|
||||
隔離したfixture、HOME、XDG、DB、資格情報のみでchroncal 0.10.0の共通探索、予定とタスクの取得、予定作成/CLI編集/Web変更取得/削除、タスク作成/完了/Web変更取得/アーカイブを検証。vdirsyncer/Todomanの既存タスク回帰も実施する。
|
||||
|
||||
権限scope、旧資格情報の移行既定値、read-only、失効、アカウント停止、拡張無効化、既存上書き拒否、並行作成、ACL取消、DB索引再構築、取得上限、Webのresource解決を試験する。ブラウザでは予定・タスク両方の設定UI、発行/失効/秘密値消去と、CLI filenameの予定描画を確認する。
|
||||
|
||||
本番の外部取り込みカレンダーの本文を調査・試験に利用しない。反映確認はhealth、未認証の経路、静的資産、エラーログ件数に限定する。
|
||||
|
||||
## 6. 後続TODO・切り戻し
|
||||
|
||||
- [ ] losslessなTZID/VTIMEZONE、繰り返し・例外、アラームのDAV書込契約。正本を拡張する際は外部ICS取り込みの投影と混同しない。
|
||||
- [ ] sync-token/tombstone/変更journalによる大規模差分同期。
|
||||
- [ ] 資格情報ごとのcalendar ID制限、カレンダー作成・属性変更のDAV対応。
|
||||
- [ ] macOS/iOS等のGUI CalDAVクライアント実機検証。
|
||||
- 旧バイナリは追加DB表を無視できるが、calendar manifestを更新すると未知の`dav_names`を失う。**CLIで予定を作成した後は、旧バイナリでカレンダーを編集しない**。緊急切り戻しではカレンダー拡張を無効化して修正版を待つか、整合したDBと正本のバックアップ復元を別途承認の上で行う。DBのみ復元し正本を過去に戻したつもりにしない。
|
||||
@@ -0,0 +1,34 @@
|
||||
# DAVx⁵/Tasks.orgの互換性調査
|
||||
|
||||
2026-09-27。利用者指定の公開ソース`bitfireAT/davx5-ose`を読み、commit `167dc85f211119db6a98596c08f64e5df32ca679`(2026-09-25)を基準に確認。インストール済みアプリのバージョンとは同一と仮定しない。Android実機でDAVx⁵を実行した検証ではない。
|
||||
|
||||
## 同期方式
|
||||
|
||||
- `core/src/main/kotlin/at/bitfire/davdroid/sync/TasksSyncManager.kt`:タスクは`PROPFIND_REPORT`固定。
|
||||
- `resource/remote/BaseWebDavCollection.kt`:Depth 0のPROPFINDでsupported-report-set、sync-token、getctag等を取得する。
|
||||
- `resource/remote/ResponseExt.kt`:sync-tokenを優先し、なければgetctagを使う。両方なければnull。
|
||||
- `sync/SyncManager.kt`のsyncRequired:状態nullは「同期必要」と判断する。両方ないこと自体で同期を拒否しない。
|
||||
- `sync/TaskSyncer.kt`と`resource/remote/CalDavCollection.kt`:VTODOのcalendar-queryを送り、ETagで比較し、必要なリソースをcalendar-multigetする。タスクqueryにtime-rangeは指定していない。
|
||||
- カレンダーは、期間制限やsync-collection未対応の場合PROPFIND_REPORTを選ぶ。未対応のsync-collectionを広告してはいけない。
|
||||
|
||||
したがって、提示された`XTaskApp / CodeSpark / SyncTaskListsSend`の「sync-token or ctag必須」というエラーは、調査したDAVx⁵の同期コードの挙動とは異なる。端末上でどのアプリが直接CalDAV接続しているかを区別する必要がある。
|
||||
|
||||
## PagesWikiとの差分と残件
|
||||
|
||||
- 既存リストの単純VTODO同期に必要なREPORT、ETag、multigetは既存実装にある。実機確認は未完了。
|
||||
- DAVx⁵のリスト新規作成は`DavCollectionRepository.generateMkColXml`でDAV:resourcetypeを常に付ける。現在のPagesWikiの限定MKCALENDARはこれを未対応propertyとして拒否する。VTODO専用で正しいresourcetypeを受理する回帰試験と実装が必要。
|
||||
- 作成時には説明・色・タイムゾーンや複数component-setも付く場合がある。受理する項目は正本保存・PROPFIND往復まで設計し、未知の意味を黙って破棄しない。
|
||||
- 時刻付きVTODO、繰り返し、VALARMはPagesWikiの現行限定プロファイルでは未対応。DAVx⁵が生成できる全タスク形式に対応済みではない。
|
||||
- リストの削除/属性編集、差分sync-tokenも別途残件。
|
||||
|
||||
## 今回の状態
|
||||
|
||||
追加途中だったctagのローカル変更(追加表・更新フック・応答property)は利用者の指示を受け取り下げた。本番には反映していない。取り下げ後の名前付きリスト・認可・原子性テストは成功。本番は0.10.0のまま。
|
||||
|
||||
利用者はTasks.orgを試す予定。DAVx⁵経由ではDAVx⁵のタスクアプリにTasksを選択し、同期対象の既存リストを有効化する。同じアカウントをTasks.org側に直接CalDAVとしても追加すると、Tasks.orgはDAVx⁵データを無視するため二重設定に注意する。初回は件名・日付だけのタスクで両方向を確認し、複雑な形式は分ける。
|
||||
|
||||
## 参照
|
||||
|
||||
- [調査対象の固定commit](https://github.com/bitfireAT/davx5-ose/tree/167dc85f211119db6a98596c08f64e5df32ca679)
|
||||
- [Tasks.org公式:DAVx⁵連携](https://tasks.org/docs/sync_davx5/)
|
||||
- [DAVx⁵公式:タスク連携](https://manual.davx5.com/tasks_notes.html)
|
||||
@@ -0,0 +1,73 @@
|
||||
# OneTaskのcalendar-access判定への互換対応
|
||||
|
||||
最新追記:利用者のスタックトレースにより`SyncTaskListsSend → CreateCalendar → MKCALENDAR`のVTODOリスト新規作成失敗と特定した。[複数タスクリスト実装](caldav-task-lists.md)で対応する。以下の「MKCALENDAR未対応」は0.9系時点の調査記録。0.10.0で明示的なVTODOリスト作成を追加するが、全機能のRFC準拠は引き続き宣言しない。
|
||||
|
||||
## 2026-09-27 接続診断の追記
|
||||
|
||||
利用者のcurl応答で、共通入口の認証済みOPTIONSが204、`DAV: 1, calendar-access`、`X-PagesWiki-CalDAV-Profile: limited-compatibility`となることを確認した。資格情報の再発行を繰り返す段階ではない。別アプリOneCalendarでの追加成功に続いて、**OneTask側も追加できたと利用者から確認された**。追加順序によるものか再試行によるものかは未確定であり、カレンダーを先に追加することを必須手順にしない。アカウント追加とVTODOの同期・更新成功は分けて扱う。
|
||||
|
||||
従来のアクセスログにはHTTPステータスがなく、10:13 JST頃の共通入口PROPFINDが成功したか判定できなかった。CalDAV経路だけ、次の固定分類による診断ログへ置き換える。
|
||||
|
||||
- method、target(home/task_home/task_collection/task_resource/calendar_collection/calendar_resource/well_known)、status、duration、request_id。
|
||||
- auth(none/basic/malformed_basic/bearer/other/multiple)、outcome(未判定・Basic成功/拒否・session成功・匿名・欠落・不正・複数Authorization)。
|
||||
- challengeの有無、限定互換宣言の有無。
|
||||
- 資格情報ID・ユーザ名・秘密値・Authorization値・Cookie・User-Agent・リソース名・query・XML/ICS本文は出力しない。認証拒否の詳細な秘密値照合結果も公開しない。
|
||||
|
||||
認証・ACL・プロトコル応答は変更しない。401なら認証、403なら権限/未対応要求、207ならクライアントの探索解釈を切り分ける。ただし207でも個別propstatは404になり得るため、207だけで必要プロパティが全て成功したと判断しない。認証省略や権限緩和で迂回しない。外部取り込み予定にはアクセスせず、実データ本文なしのログと隔離fixtureで調査を継続する。
|
||||
|
||||
診断ログ追加は10:16〜10:17 JSTにapp/app2へ反映。認証済み共通入口PROPFINDの207を確認。MKCALENDARの404も観測したが、実行アプリはログから特定できない。外部クライアントからのコレクション新規作成は未対応であり、既存タスクの作成・更新とは別課題として残す。未実装のMKCALENDARを成功扱いしない。
|
||||
|
||||
その後「追加はできたが、タスクの中身が見えず`calendar or event not found`」との報告。10:17:27のMKCALENDAR404と同じ文言を既存カレンダーハンドラが返す。10:18:28にはtask_collectionへのPROPFIND207/basic_acceptedも観測。現在のログにタスク本文取得のREPORT/GET失敗はなく、一覧表示の不具合とMKCALENDAR未対応の関係は未確定。「PagesWiki Tasks」が見えるか、エラーが同期時かリスト新規作成時かを利用者へ確認中。未対応メソッドを存在確認より前で拒否して誤解を招く404を避けること、VTODO探索の階層とクライアント相互運用を検証することを残件とする。接続成功のみで同期解決済みにしない。
|
||||
|
||||
2026-09-27実装、10:01 JSTに本番両インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-27-onetask.md)。**OneTaskアカウント追加は利用者確認済み。ただしタスク表示は未解決。互換ONで発行した資格情報が必要。**
|
||||
|
||||
## 原因と今回の境界
|
||||
|
||||
OneTaskはOPTIONS応答に`calendar-access`がない場合、`This CalDav server does not support calendar-access`として探索を停止する。従来のPagesWikiは限定的なCalDAV実装のため`DAV: 1`のみを返していた。これは認証失敗やPROPFINDの失敗ではない。
|
||||
|
||||
[RFC 4791 §5.1](https://www.rfc-editor.org/rfc/rfc4791.html#section-5.1)では`calendar-access`は全MUST要件への対応宣言である。現在のPagesWikiはその全てを実装していない。従って本変更は**RFC完全準拠への変更ではなく、利用者が明示的に選ぶ接続判定の互換モード**である。付加的な独自ヘッダでこのRFC上の意味を変えられるわけではない。通常モードは今まで通り宣言しない。
|
||||
|
||||
## 設定と保存
|
||||
|
||||
カレンダー/タスクの⇄設定で認証情報を発行するとき、「OneTask互換モード(calendar-accessを宣言)」を選ぶ。初期値はOFF。限定実装と未対応機能を同じ画面に明示し、一覧にもOneTask互換と表示する。
|
||||
|
||||
管理API `POST /_/api/v1/caldav-credentials` の追加フィールド:
|
||||
|
||||
```json
|
||||
{"label":"Android OneTask","scope":"tasks","write":true,"days":90,"calendar_access_compat":true}
|
||||
```
|
||||
|
||||
従来APIも同じフィールドを受理する。scope(対象)とwrite(権限)は別のまま。互換設定で予定への権限や書き込み権限を追加しない。既存認証情報は自動変更しない。公開してしまった秘密値を再利用せず、旧認証情報を失効して新規発行する。
|
||||
|
||||
DBには`organizer_dav_compat(credential_id)`を追加。発行と互換フラグを同じtransactionで保存し、資格情報削除triggerで関連行を削除する。secret自体は従来どおりhashのみ。通常のログインセッション以外で発行できない。
|
||||
|
||||
## 応答
|
||||
|
||||
認証成功後、対象domain/owner/資格情報ID/有効期限に対応する互換行がある場合のみ、共通home・task home・task collection/resource・calendar collection/resourceで以下を返す。
|
||||
|
||||
```http
|
||||
DAV: 1, calendar-access
|
||||
X-PagesWiki-CalDAV-Profile: limited-compatibility
|
||||
```
|
||||
|
||||
既存資格情報・互換OFF・Bearer/Cookieセッション・匿名要求は通常のまま。User-Agentから推測して勝手に互換設定を有効にしない。DB確認エラー時は通常応答に倒す。認証・scope・期限の失敗は401のままであり、失敗を成功応答に偽装しない。
|
||||
|
||||
OPTIONSの204は維持。Allowには実装しているメソッドのみを示し、MKCALENDAR・calendar-schedule・sync-token等を追加宣言しない。task collectionのPROPFINDにはcurrent-user-privilege-setとcurrent-user-principalを追加し、読み取り専用をwriteとして返さない。
|
||||
|
||||
## データと検証
|
||||
|
||||
未対応のTZID/日時付きVTODO期限/繰り返し/VALARM/部分projectionやfilterは引き続き明示的に拒否する。互換設定はこれらを変換・削除して保存を通す機能ではない。ETag必須の既存更新とACLも維持する。
|
||||
|
||||
`TestDAVCalendarAccessCompatibility`は報告されたOPTIONSの判定を再現し、その後の探索・取得・更新・削除、通常モード維持、User-Agent偽装無効、read-only、scope、失効・期限、管理API隔離、未対応繰り返し拒否を確認する。これはOneTaskアプリ自体の実行試験ではない。
|
||||
|
||||
chroncalの共通接続fixtureは互換ONで、旧タスク接続とvdirsyncer/Todomanは通常モードで回帰試験する。Chromiumでは設定の初期OFF、明示ON発行、一覧反映、失効、秘密値消去、タスク画面4サイズを確認する。すべて隔離された合成データを用い、本番資格情報・外部カレンダー本文は使わない。
|
||||
|
||||
2026-09-27の結果:全Goテスト成功。chroncal 0.10.0/vdirsyncer実行fixture成功。`TestCalendarChromiumSmoke`と`TestTasksChromium`(1440/1024/390/320幅)成功。JS構文・`git diff --check`成功。本番へのデプロイ、認証情報の発行・失効はこの作業では行っていない。
|
||||
|
||||
## 運用・残件
|
||||
|
||||
- [x] 本番への反映(2026-09-27 10:01 JST)。DBは追加表とtriggerのみで破壊的変更なし。旧バイナリは互換設定を無視するため、切り戻すとOneTaskの接続判定は再び失敗する。
|
||||
- [x] OneTask実機でアカウント追加(利用者報告)。
|
||||
- [ ] OneTask実機で一覧表示・作成・完了・変更・削除を確認する。一覧表示に問題報告があり、接続成功を全操作成功と扱わない。
|
||||
- [ ] 実機で次の要求が失敗する場合は、Authorization・本文を除去したメソッド、対象経路、status、画面エラーを基に限定fixtureを追加する。
|
||||
- [ ] 完全なRFC対応を目指す作業は共通CalDAVの残件(時間帯・繰り返し・filter等)として別途継続する。
|
||||
@@ -0,0 +1,53 @@
|
||||
# CalDAVタスクリスト作成とプロジェクト同期
|
||||
|
||||
**後続仕様**:0.11.0で通常プロジェクトも個別リストへ統一し、条件なし上書きを受理する。以下は0.10.0の記録。[新しい契約・移行と競合通知TODO](task-dav-project-unification.md)を参照。
|
||||
|
||||
2026-09-27。`organizer.tasks 0.10.0`。OneTaskの`SyncTaskListsSend`が`MKCALENDAR`でVTODOリストを作成する実例に対応する。認証エラーではなく、旧実装が未知のリストUUIDをVEVENTカレンダーとして検索し404にしたことが原因。従来の固定リストと認証・ETag・権限を維持し、成功応答だけを偽装しない。
|
||||
|
||||
10:44〜10:45 JSTに本番両インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-27-task-lists.md)。OneTask実機での再同期確認は利用者待ち。
|
||||
|
||||
## 1. 正本とURI
|
||||
|
||||
- `MKCALENDAR /_/api/v1/caldav/{UUID}/`でVTODO専用リストを作成する。要求URIをそのまま維持し、別URIへのリダイレクトは行わない。
|
||||
- 1リストを1つの個人プロジェクトに対応付ける。表示名はプロジェクトのTitle、所属タスクはProjectUUIDで決まる。外部作成分はWebでも同じプロジェクトとして管理できる。
|
||||
- URIのUUIDとプロジェクトのUUIDは別の識別子。正本プロジェクトの`dav_collection`にURIのUUIDを保存し、通常の版・CAS文書・変更journalを使用する。
|
||||
- DBの`organizer_dav_collections`はdomain/pathの一意性・routing索引。プロジェクト正本の情報から再構築できる。通常JSON APIから`dav_collection`を注入・変更できない。
|
||||
- 従来の`/_/api/v1/caldav/tasks/default/`は維持。DAV専用リストを持つプロジェクトのタスクだけを除外し、それ以外の既存タスク・通常プロジェクトは引き続きここに表示する。既存プロジェクトを勝手に外部リスト化しない。
|
||||
- 名前付きリスト内のリソースは`/_/api/v1/caldav/{UUID}/{filename}.ics`。Webで所属プロジェクトを変更すると、元のリストから消え、移動先に同じUID/filenameで現れる。これはCalDAV MOVE対応ではない。
|
||||
- 共通homeおよび旧task homeの探索で、利用者自身の有効な名前付きリストを返す。タスク拡張だけが有効な場合も使える。
|
||||
|
||||
## 2. 作成契約
|
||||
|
||||
[RFC 4791 §5.3.1](https://www.rfc-editor.org/rfc/rfc4791.html#section-5.3.1)に従い、作成は一括成功か全拒否とする。対応範囲は明示的なVTODO component-setとdisplayname。VEVENT/混在/未対応property/不正XMLを黙って無視しない。
|
||||
|
||||
- UTF-8 XML、application/xmlまたはtext/xml。64 KiB、既存XMLの深さ・要素数制限を適用。
|
||||
- component-setはVTODOのみを必須とする。displayname省略時はURI末尾を用いる。表示名の長さ等は既存プロジェクト検証を適用。
|
||||
- 作成成功201+Location、private/no-cache/no-store。既存URIへの再作成は405+DAV:resource-must-be-null。再送で別プロジェクトを増殖させない。
|
||||
- domain/pathは他利用者分も含めて一意。既存VEVENTカレンダーのディレクトリを上書きしない(存在だけ検査し、予定本文は読まない)。
|
||||
- 1利用者・1ドメインにつき最大256リスト。上限超過507。削除済みとしてURIを再利用する契約はまだ設けない。
|
||||
- タスクscopeまたはall、write権限、active membership/principal、拡張有効状態を検証。作成transaction内でも資格情報の失効・期限・権限を再確認する。
|
||||
- 匿名作成・匿名リスト閲覧は不可。他利用者のリストは404、カレンダーだけの資格情報はタスクへ使えない。
|
||||
|
||||
## 3. タスク同期
|
||||
|
||||
PROPFIND/calendar-query/calendar-multiget/GET/HEAD/PUT/DELETEを既存実装と共通化し、リストごとに完全なsnapshotを返す。別リストのhrefをmultigetに混ぜても個別404にする。
|
||||
|
||||
UIDとfilenameの一意性はリスト内。異なるリストでは同名・同UIDを許可する。DB検索索引のみ、正本上のUIDでは許可しないNULを区切りにプロジェクトUUIDを付与し、既定リストの任意UIDと衝突しないようにする。外部ICSや返却URLに索引用の接頭辞は出さない。
|
||||
|
||||
Web編集時もプロジェクトのリストidentityとタスクのDAVメタデータを保持する。既存更新はETagとversion CAS、DELETEはタスクのアーカイブ。write transaction内で所属リストを再確認する。リストをアーカイブした場合、タスクを既定リストへ漏らさず、DAV上ではそのリストを非表示にする。
|
||||
|
||||
## 4. 検証
|
||||
|
||||
- OneTaskの提供したMKCALENDARのXML形状を合成fixtureで再現。201→探索→PUT→GET→REPORT→完了→Web変更→削除。
|
||||
- 二つのリストの同UID/filename、相互混入防止、multigetの範囲制限、Web所属変更、索引再構築。
|
||||
- 他利用者、read-only、calendar-only、匿名、拡張無効、VEVENT URI衝突、並行二重作成、失敗時にプロジェクトを残さないこと。
|
||||
- chroncalの名前付きリスト往復同期。旧固定リスト・共通VEVENT接続・vdirsyncer/Todomanの回帰。
|
||||
- Webタスク/カレンダー画面のブラウザ回帰。実機OneTaskでの最終同期確認は利用者の再試行で行う。
|
||||
- 本番の資格情報・タスク・外部取り込み予定をfixtureに使用しない。観測は秘匿済みログとhealthに限定する。
|
||||
|
||||
## 5. 残件と切戻し
|
||||
|
||||
- リストのPROPPATCHによる名称・色変更、リストDELETE、DAV MOVEは未対応。リスト名はWebのプロジェクトで変更可能。リストDELETEを全タスク削除として仮実装しない。
|
||||
- DTSTART/DUEの時刻、TZID、繰り返し、VALARM、複雑filterは従来の限定VTODO契約を維持。sync-tokenによる差分同期も別件。
|
||||
- OneTaskが追加のproperty・filter・日時形式を送る場合は実要求に基づき、情報を落とさない形で対応を追加する。アカウント追加成功やCLI試験だけでOneTaskの全操作成功とはしない。
|
||||
- **名前付きリスト作成後、0.9系の旧バイナリでプロジェクト/タスクを編集しない。** 未知のdav_collectionが失われたり、旧既定リストへ混入し得る。緊急切戻しはタスク拡張を停止してから行う。DBだけの無断巻戻しでユーザーの新規タスクを消さない。
|
||||
@@ -0,0 +1,15 @@
|
||||
# カレンダー・Cityのジョブ障害是正(2026-09-22)
|
||||
|
||||
## City
|
||||
|
||||
URL自動生成はSpot名をPathの同じ深さから作るが、Spot名の一意制約はStreet内ではなくDomain全体だった。別Streetで同名のSpotやundefinedを生成するとreconcileが失敗し、outboxが未完了のまま再試行されていた。
|
||||
|
||||
Pathによる既存要素の再利用を優先し、新規作成時に名前が衝突する場合のみPath由来の安定hashを識別名に追加する。表示タイトルは維持する。別Pathの要素を名前だけでマージしない。QuartierとStreetの正規化名衝突も同じ方法で回避する。再実行で要素が増殖しないことを合成データで検証する。
|
||||
|
||||
残タスク:手動作成との同時実行競合のリトライ、繰り返し失敗の再投入backoffと警告集約。過去の失敗ログは成功へ改竄しない。
|
||||
|
||||
## 外部カレンダー接続
|
||||
|
||||
DNS検証後に先頭IPだけへ接続していたため、その経路が利用できない場合に失敗した。他の検証済みIPへ再試行し、DNS/TLS証明書/タイムアウト/安全制限をURLやトークンなしで分類する。localhostとprivate IP直指定は設定段階でも拒否する。
|
||||
|
||||
Outlookへの実接続・予定内容の調査は行わない。ユーザー指定により、以降の検証は合成データのみとし、取り込まれた外部予定にはアクセスしない。一般的なOutlookフィードのTZID、有限RRULE、EXDATE/RDATE、移動・取消を含むRECURRENCE-ID、ゼロ時間予定、Microsoft終日予定を有限期間へ射影する。対応外形式は前回snapshotを維持して失敗させ、通信成功と形式対応を混同しない。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 14. 予定・iCalendar・CalDAV・連絡先
|
||||
|
||||
状態:カレンダー部分は2026-09-22にローカル正本・Plan UI・限定CalDAVを実装開始。最新の契約・実装範囲・残作業は [カレンダー詳細設計](calendar-implementation.md) を参照。以下の旧順序/URI案より同設計を優先する。連絡先と外部同期は引き続き設計案。
|
||||
|
||||
## 四つのレイヤー
|
||||
|
||||
| レイヤー | 役割 | PagesWikiでの扱い案 |
|
||||
| --- | --- | --- |
|
||||
| Wiki URL | 人が開く説明・知識への入口 | rename可能なPage Path |
|
||||
| iCalendar | 予定・タスク等の交換形式 | export/import、UIDと元データを保持 |
|
||||
| CalDAV | カレンダー資源を扱うWebDAV拡張 | remote connector、将来の提供面 |
|
||||
| CardDAV / vCard | 連絡先の通信 / データ形式 | 個人・共有address book |
|
||||
|
||||
iCalendarとCalDAVは同義ではなく、`.ics`を配信するだけでCalDAVサーバーにはなりません。vCardとCardDAVも区別します。[RFC 5545](https://www.rfc-editor.org/rfc/rfc5545)、[RFC 4791](https://www.rfc-editor.org/rfc/rfc4791)、[RFC 6350](https://www.rfc-editor.org/rfc/rfc6350)、[RFC 6352](https://www.rfc-editor.org/rfc/rfc6352)。
|
||||
|
||||
## identity対応案
|
||||
|
||||
local item UUID、calendar UID、remote href、Wiki Page UUIDを対応表に持ちます。Wiki renameでUIDを変更しません。remote href変更は移動・再取得として確認し、同じ題名だけで統合しません。ローカル生成UIDはDomain名変更でも維持します。
|
||||
|
||||
予定はevent、タスクはtodo、連絡先はcontactの型付き状態です。説明用Pageは任意の参照であり、毎回ICS/vCardをHTMLへ変換して正本を置換しません。原形式のDocument snapshotを保持し、未対応propertyの欠落を検出します。
|
||||
|
||||
## 予定のモデル案
|
||||
|
||||
開始・終了、終日フラグ、timezone/TZID、繰り返しrule、例外、参加者、状態、source versionを分離します。終日をUTCの時刻に変換せず、時間帯なしの時刻も区別します。無限recurrenceは画面の対象期間内だけ展開し、件数上限を持ちます。
|
||||
|
||||
例外instanceのキーは元seriesとrecurrence identityです。単発の変更・series全体の変更をUIで分けます。参加依頼、回答、メール送信などのschedulingは単純な予定保存とは別の後続機能です。
|
||||
|
||||
## 同期と競合
|
||||
|
||||
connectorはremote ETagとlocal versionを別々に持ち、更新前の値で条件付き操作します。ETagをDocument SHA-256と仮定しません。対応サーバーではcollection sync-tokenを利用する案ですが、無効なtokenからの再同期と未対応時のboundedな全量照合も必要です。[WebDAV同期仕様](https://www.rfc-editor.org/rfc/rfc6578)。
|
||||
|
||||
通信失敗では外部削除と見なさず、tombstoneは確認できた削除だけです。両側で変更された場合はbase/local/remoteを比較し、内容を保存した競合状態へ移します。勝手な最新版上書きはしません。
|
||||
|
||||
## 連絡先
|
||||
|
||||
address bookの所有者・共有範囲、contact UUID、remote UID、複数メール/電話、名称、所属、写真の固定参照を持ちます。人物Principalとcontactは別です。メール一致だけでユーザーへ自動連結しません。重複候補を示し、mergeは変更前をexportできる確認操作にします。
|
||||
|
||||
## URL/API案と実装順
|
||||
|
||||
人向けは `/v/organizer`、APIは `/_/api/v1/extension/organizer.{calendar|contacts}/…` を候補とします。**未実装・未予約**です。DAV提供面はroot discovery、認証、標準メソッドとルーターの衝突を調査してから決めます。Wiki PathをそのままDAV collectionにしません。
|
||||
|
||||
1. ICS/vCard fixture、入出力preview、警告、重複防止。
|
||||
2. local calendar/agenda・連絡先一覧、権限・version試験。
|
||||
3. 選定サーバーに対するread-only connector。
|
||||
4. 限定された双方向同期、最後に必要性が確認できたDAV提供。
|
||||
|
||||
CAL-1:終日・夏時間・例外。CAL-2:UID/href/Path変更。CAL-3:412競合・token失効。CARD-1:複数propertyと未知項目。DAV-1:権限失効・大量collection・app token失効。これらを完了条件にします。
|
||||
@@ -0,0 +1,165 @@
|
||||
# カレンダー拡張:正本・CalDAV・Plan UI
|
||||
|
||||
更新:2026-09-22。既存の「予定・iCalendar・CalDAV・連絡先」のうちカレンダー部分を具体化する。連絡先、タスク、メール、招待配送は別サブプロジェクト。
|
||||
|
||||
## 1. 判断と実装状態
|
||||
|
||||
正本を SQLite に置かない。カレンダー単位の manifest と月別 iCalendar ファイルを正本とし、DB は消して再構築できる検索索引に限定する。Wiki Page の HTML 化や revision に予定を埋め込まない。
|
||||
|
||||
初期実装は **限定された CalDAV メソッド実装**。完全な CalDAV サーバーの適合性を宣言しない。`DAV: 1` のみ返し、`calendar-access`、`calendar-schedule`、sync-token は未対応のまま広告しない。
|
||||
|
||||
| 項目 | 初期実装 |
|
||||
| --- | --- |
|
||||
| 正本 | カレンダーの manifest、月ごとの VCALENDAR/VEVENT |
|
||||
| 検索 | SQLite に domain/calendar/UID・開始/終了・ETag を索引化 |
|
||||
| 日時 | UTC DATE-TIME、終日 DATE、DTEND は排他的 |
|
||||
| 保存 | 未知の VEVENT property を保持。UI編集は対象フィールドのみ更新 |
|
||||
| 並行更新 | 強い ETag の条件付き更新、競合時412、無条件更新428 |
|
||||
| UI | 年・月・週・日・起点31日一覧・水平タイムライン、詳細・作成・編集・削除 |
|
||||
| 共有 | 所有者、ユーザー単位 read/write、明示的な匿名公開 |
|
||||
| 無効化 | system extension `organizer.calendar` の既存スイッチ |
|
||||
|
||||
ローカルCRUDと正本の1予定表現では、RRULE/RDATE/EXDATE/RECURRENCE-ID、TZID/VTIMEZONE、floating時刻、DURATION、VALARM、VTODO、METHOD による scheduling を**入力拒否**する。外部購読に限り、検証済みのVTIMEZONE/TZIDと単一RRULEを有限期間のUTC/DATE予定へ射影する。受理後に検索から消えたり、繰り返しが単発予定に化けたりしないことを優先する。例外予定などの未対応が残るため、一般のカレンダーアプリを無制限に接続できる段階ではない。
|
||||
|
||||
## 2. URI
|
||||
|
||||
### UI
|
||||
|
||||
- `/v/plan`:最後に開いた表示種別の現在日。表示履歴がなければ現在週。
|
||||
- `/v/plan/cal/yyyy`:年。
|
||||
- `/v/plan/cal/yyyy/mm`:月。
|
||||
- `/v/plan/cal/yyyy/mm/dd`:日。
|
||||
- 同上の `/week`:月曜から日曜、その日を含む週。
|
||||
- 同上の `/events`:その日から31日間の一覧。
|
||||
- 同上の `/timeline`:その日の時間を左から右に配置。
|
||||
- 同上の `/new`:その日を初期値に新規予定ダイアログ。
|
||||
- `/v/plan/event/{UID}`:予定詳細。
|
||||
- `/v/event/new`、`/v/event/{UID}/edit`:指定どおり作成・編集。
|
||||
- `/v/calendar`:`/v/plan` への互換入口。
|
||||
|
||||
複数カレンダー選択は `?calendar=work,personal` のように `pretty_name` をコンマで連結する。各名は個別にURLエンコードし、区切りのコンマはそのままとする。表示設定ダイアログで複数選択・自分の既定値を保存できる。既定値はドメイン内のユーザー単位で、内部UUIDの配列をファイル `preferences/{principalUUID}.json` に保存する。無指定時は可視な既定値を使い、未設定・すべて失効した場合のみ可視な先頭カレンダーへフォールバックする。既定値による移動ではクエリを追加しない。匿名利用は個人設定を持たない。
|
||||
|
||||
`pretty_name` はドメイン内で一意(大文字小文字だけ違う名前も重複)。Unicode NFCの文字/数字、`-`、`_` が使用でき、空白・コンマ・スラッシュ・UUIDそのものは不可。最大120バイト。別途 `name` は自由な表示タイトルとして保持する。月別iCalendar正本の `NAME`([RFC 7986 §5.1](https://www.rfc-editor.org/rfc/rfc7986#section-5.1))、CalDAV collectionのdisplaynameにはpretty_nameを使う。VEVENT単体のUID/ETagやDAV資源hrefは名前変更の影響を受けない。名称の重複チェックはドメイン単位のlockで直列化する。
|
||||
|
||||
旧データのpretty_nameは `calendar-{UUID}` を安全な初期値とし、歯車から変更可能。旧UUIDクエリは互換受付してpretty_nameへ置換する。UUIDを保持する既定設定と予定所属はrenameに追従する。外部に配布した旧pretty_nameリンクのリダイレクトは未提供。
|
||||
|
||||
UIDはカレンダー内で一意。別カレンダー間に同じUIDがあり得るので、生成する詳細リンクはその予定のpretty_nameを1つだけ含める。複数表示の新規予定では、書込可能なカレンダーから作成先を選ぶ。Wiki Pathのrenameは予定UIDに影響しない。
|
||||
|
||||
### プロトコルと管理API
|
||||
|
||||
CalDAV入口:`/_/api/v1/caldav/`。既存のジョブ `/_/api/v1/event/` と混同しない。
|
||||
|
||||
2026-09-26更新:`organizer.calendar 0.2.0`で専用Basic認証・共通principal探索・初回全件同期・CLI resource名を追加。[予定・タスク共通CalDAV](caldav-common.md)が追加契約。以下の旧仕様に対しcollectionのDepth 1、上限付き全件REPORT、CLI指定filename、JSONイベント取得の`?resource=`が追加される。UTC/DATEに限定する書込プロファイルは維持する。
|
||||
|
||||
| URI | 操作 |
|
||||
| --- | --- |
|
||||
| DAV root | OPTIONS、PROPFIND Depth:0/1(可視カレンダー) |
|
||||
| `/{calendarUUID}/` | PROPFIND Depth:0、REPORT calendar-query / calendar-multiget |
|
||||
| `/{calendarUUID}/{base64url(UID)}.ics` | GET/HEAD、PUT、DELETE |
|
||||
| `/_/api/v1/extension/organizer.calendar/calendars` | GET一覧、POST作成 |
|
||||
| 同上 `/{calendarUUID}/settings` | PUT 設定/DELETEカレンダー、manifest version必須 |
|
||||
| 同上 `/{calendarUUID}/events` | GET `?uid=`、POST作成/編集 |
|
||||
| `/_/api/v1/extension/organizer.calendar/event?uid=` | 可視カレンダーからUID解決。複数一致は409 |
|
||||
|
||||
UIDは任意のテキストなのでDAVのファイル名へ直接使わずbase64urlにする。絶対URLのhrefや別カレンダーへのmultigetは受理しない。全件無制限のDepth:infinityやREPORTは提供しない。現在は作成を管理JSON APIで行い、MKCALENDAR/PROPPATCH/ACLは後続。
|
||||
|
||||
## 3. ファイルと障害復旧
|
||||
|
||||
```
|
||||
documents/calendars/{domainUUID}/{calendarUUID}/
|
||||
calendar.json
|
||||
.lock
|
||||
2026-09.{sha256}.ics
|
||||
2026-10.{sha256}.ics
|
||||
```
|
||||
|
||||
`calendar.json` は名前・所有者・公開設定・メンバー・version・月→ファイルSHA-256対応を持つ。月別ファイルは世代ごとに不変。VEVENTは開始月へ収納し、月をまたぐイベントは分割しない。
|
||||
|
||||
変更順序:カレンダーのプロセス間lock取得 → 現manifestとETagを確認 → 変更月の新ファイルを書きfsync → manifestをatomic renameしてディレクトリfsync → 未参照の旧世代を清掃。
|
||||
|
||||
9月から10月へ予定を移動する場合も、両月の新ファイルを準備してからmanifestを一度だけ置換する。中断した未参照ファイルは次の成功時に清掃する。過去世代を無限に保持する履歴設計にはしない。正本バックアップはmanifestとその参照先を一組で取得し、稼働中はlockと協調する必要がある。
|
||||
|
||||
DB表は `calendar_index_state`、`calendar_month_cache`、`calendar_event_cache`。manifest versionが変わったときだけ、hashが変わった月を索引へ反映する。DB反映前の中断は次回アクセスで修復する。DBだけが最新になりファイルが古い状態を正本とはしない。復旧時は3表を**一緒に**破棄し、正本から再構築する。
|
||||
|
||||
手動でICSを書き換える運用は未提供。hash名のファイルを直接編集しない。キャッシュ再構築時にはSHA-256を検証する。正本ファイルのACLは0600、ディレクトリは0700。HAの複数ノード同時書込やネットワークFSのロック保証は別途検証する。
|
||||
|
||||
## 4. 取得・キャッシュ・負荷
|
||||
|
||||
フロントエンドは対象期間の `calendar-query` でgetetagのみ取得。タブ内メモリのETagと一致する予定は再取得しない。変更分だけJSONの予定投影を取得し、同時取得は最大4件。独自にREPORTへ304を返す実装はしない。ICS GETではIf-None-Match/304を利用可能。
|
||||
|
||||
月をまたぐ予定は開始月のファイル列挙ではなく、DBの開始/終了の重なりで取得する。ゼロ時間の予定は開始時点が期間内なら一致。DATEとUTC日時を表示時に混同しない。UIの時刻入力・表示・日境界は**ドメイン設定のタイムゾーン**を用い、正本はUTCで保存する。DSTで存在しない時刻や二重になる時刻をドラッグ操作で暗黙補正せず、編集画面で再指定させる。DATEの検索境界差を補うためUIのREPORTは前後1日を加え、描画時に絞る。
|
||||
|
||||
週・日ビューは67〜400%の6段階で時間軸を拡縮する。100%以下は15分、200%は10分、300〜400%は5分単位で移動・リサイズする。予定中央のドラッグは長さを保った移動、上端は開始、下端は終了の変更である。同時刻帯で重なる予定は最大同時数分の等幅laneへ配置する。短い予定には操作可能な最低表示高を確保し、その表示領域同士も衝突しないlaneへ分ける。保存成功時はAPI応答の予定だけをタブ内集合へ反映してlaneを再計算し、期間REPORTや予定全件を再取得しない。時間列の空白をドラッグすると設定タイムゾーンの選択範囲を入力済みの新規予定ダイアログを開き、クリックだけでは作成しない。
|
||||
|
||||
上限:ドメイン256カレンダー、1資源256KiB、XML64KiB/深さ12、月5000件/16MiB、期間370日、結果5000件、multiget200件、lock待機5秒。超過は部分成功にせずエラー。ETagだけのREPORTは本文をparseしない。永続ブラウザキャッシュや共有CDNへの予定保存は行わない。権限を確認してから304・本文を返す。
|
||||
|
||||
## 5. 権限
|
||||
|
||||
カレンダー所有者が名前・公開設定・collaboratorを管理する。collaboratorは同じドメインの有効なユーザーで、`read` または `write`。writeには予定作成・変更・削除を含むが、共有設定の変更は含まない。readonlyアカウントの書込は不可。グループ共有・所有権移管・管理者による復旧は後続。
|
||||
|
||||
カレンダー全体の削除も所有者だけが行う。設定ダイアログで全予定を含む完全削除を確認し、`DELETE .../settings` に現在のmanifest versionを渡す。古いversionは412とし、削除対象の外部同期ジョブはqueuedなら取消、runningなら取消要求を付ける。正本ディレクトリを原子的に不可視化して削除し、SQLiteの3索引表を消す。ユーザー既定値に残ったUUIDは毎回の可視性検査で除外される。実行済みジョブ履歴とログは監査情報として削除しない。
|
||||
|
||||
匿名公開はカレンダー全体を対象とし、説明・場所を含めて公開する旨をUIで告知する。既存のドメイン公開上限がpublic、ドメイン有効、authorization_mode=enforcingのときだけ有効。上限を閉じれば次の取得から匿名アクセスを拒否する。公開範囲の狭い予定を混在させるには別カレンダーを使う。VEVENTのCLASSだけをアクセス制御として扱わない。
|
||||
|
||||
Page公開とは別の正本なのでCityのSpot/Pathへ暗黙に従属させない。将来Pageへの関連付けをしてもPage参照権限と予定権限は別途評価する。
|
||||
|
||||
## 6. RFC対応の検証と残タスク
|
||||
|
||||
基準:[RFC 5545](https://www.rfc-editor.org/rfc/rfc5545) / [RFC 4791](https://www.rfc-editor.org/rfc/rfc4791)。パーサーは `github.com/emersion/go-ical` を固定バージョンで使用し、アプリ側でDTSTART必須、UTC/DATE、排他的DTEND、UID、不支持property、制御文字、必須項目を追加検証する。出力はCRLF・UTF-8を分断しない75octet折返し。ライブラリ採用だけをRFC適合の証明にはしない。
|
||||
|
||||
- [x] 単発UTC/終日、未知property保持、月境界、同時更新、キャッシュ再構築、公開取消の回帰テスト。
|
||||
- [x] Plan各ビュー、期間REPORT、差分取得、設定・予定ダイアログ、所有者限定のカレンダー完全削除。
|
||||
- [x] 外部購読用のTZID/VTIMEZONE(IANA、主要Windows名、定義内のSTANDARD/DAYLIGHT)と夏時間fixture。
|
||||
- [ ] ローカル正本でのTZID/VTIMEZONE/floating対応、DURATIONの暦日演算。
|
||||
- [x] bounded recurrence展開、EXDATE/RDATE、RECURRENCE-ID例外、時間範囲オーバーラップ、件数・本文量・対応頻度によるCPU/メモリ上限。
|
||||
- [ ] 標準XML precondition/error、PROPFIND/PROPPATCH/MKCALENDARの適合性、principal discovery、`/.well-known/caldav`、Depthと未知filterの完全な検証。
|
||||
- [ ] アプリ専用の失効可能なCalDAV credential、権限のread/writeスコープ、クライアント適合試験(現状は既存session Bearer)。
|
||||
- [ ] collection sync-token、tombstone保持と期限切れの再同期。現状は期間REPORTが正しい集合を返す。
|
||||
- [ ] バッチmultigetの単一索引snapshot化、大量calendarの一覧ページング、UI期間ごとのvirtualization。
|
||||
- [ ] 専用ジョブとしてreindex/検証/容量統計、イベント資源監視、管理者向けバックアップ・restore・所有権復旧。
|
||||
- [ ] グループcollaborator、イベントごとのvisibility、承認Inbox、共有変更監査、変更通知。
|
||||
- [ ] 招待・参加回答・リマインダーはCRUDとは別のevent/scheduler連携。iTIPメール配送を無断で有効にしない。
|
||||
- [x] 外部ICSの条件付きGET購読、外部CalDAVの期間REPORT/差分multigetによるread-only同期(下記制約あり)。
|
||||
- [ ] 外部連携のdiscovery、OAuth、sync-token、取得期間の設定、競合UI付きの双方向同期。
|
||||
|
||||
完全なCalDAV適合性・繰り返し対応の完了までは「一般クライアント互換」の完了チェックを付けない。
|
||||
|
||||
## 7. 今回の検証記録
|
||||
|
||||
- `go test ./internal/calendar ./internal/server -run 'TestCalendar|TestPolicyForRequest'`:成功。
|
||||
- Chromium:月・週・timeline・詳細の描画、設定タイムゾーン、400%/5分ズーム、中央移動、上下端リサイズ、重複予定の等幅配置、ダイアログによる作成/編集/削除、カレンダー名の変更、ETag一致時の本文再取得抑止を確認。
|
||||
- 全体テストは `TestConfigBookmarksSaveAndPanelRegistry` が既存設定画面の `config-form-table` に横スクロールコンテナがないとして失敗。カレンダー画面には当該テーブルは追加していない。別UIタスクとして調査・是正する(テストを緩めない)。
|
||||
|
||||
## 8. 時間軸の操作
|
||||
|
||||
終日の入力・詳細表示では終了日を**含む**。同日開始・同日終了で1日の予定を作成できる。保存時だけ終了日にUTC暦日を1日加算し、編集・表示時には1日戻す。正本ICSとAPIのDTENDはRFC 5545の排他的境界を維持する。既存データの移行・外部予定の書換は不要。
|
||||
|
||||
トップバーはCity・直近の予定・通知・プロフィールの並び。直近の予定は既定カレンダー(未設定なら先頭1件)の今日から31日間を最大20件表示する。`GET /_/api/v1/extension/organizer.calendar/upcoming?date=yyyy-mm-dd` はログイン必須、毎回権限確認、no-store、5秒上限、カレンダー毎20件の本文取得上限を設ける。モーダルを開いたときだけ取得し、閉じたら中断する。通知と予定は背景スクロールを抑止した中央モーダルで、Escape/閉じるボタンに対応する。
|
||||
|
||||
日・週ビューは縦の時間軸、timelineは横の時間軸に予定を表示する。従来の週リストは `/v/plan/cal/yyyy/mm/dd/week/list` とし、先頭行に曜日を表示する。日・週の尺度は40/60/90/120 px/時から選択できる。
|
||||
|
||||
最後に開いた年・月・週・週リスト・日・timeline・予定一覧の表示種別だけをPrincipal単位でブラウザへ保存する。予定本文、カレンダー名、選択日、資格情報は永続化しない。予定の新規作成後は詳細画面へ遷移せず、作成を開始した表示種別と基準日へ戻して再取得する。新規作成専用URLから開始した場合も、保存済み表示種別(未保存なら週)へ戻る。
|
||||
|
||||
書込可能な予定の移動ハンドルをドラッグすると15分単位で日時を変更する。日・週では上下キー、timelineでは左右キーでも移動可能。期間の長さを保持し、Escapeでドラッグを取消す。存在しない/曖昧なローカル時刻への日・週移動を拒否する。保存は既存ETag付きAPIを通し、競合時には上書きしない。終日・外部読取専用の予定にハンドルは表示しない。ブラウザ試験で縦横の実マウス操作とキーボード操作を検証する。
|
||||
|
||||
## 9. 外部カレンダーの読み取り同期
|
||||
|
||||
新しい空のカレンダーを作り、所有者が「外部同期」ダイアログでICS URLまたはCalDAVコレクションURLを設定する。取得間隔は1分〜7日、手動同期・停止を提供する。外部同期を停止しても、取得済み予定と読み取り専用属性は保持する。双方向同期や、既存のローカル予定への混在取込は行わない。公開・collaborator設定は取込先の設定に従うため、私用フィードは非公開カレンダーで利用する。
|
||||
|
||||
- API:`PUT /_/api/v1/extension/organizer.calendar/calendars/{UUID}/source` で設定、同じURIへの `POST` で手動キュー投入。所有者限定、設定更新はmanifest version必須。
|
||||
- 組込イベント `calendar.source.sweep` が60秒ごとに期限を確認し、`calendar.source.sync` を低優先度・カレンダー単位の重複抑制付きでキューへ投入する。実行状態・ログは既存イベント管理に統合。UIを開く必要はない。間隔は次回取得の目安でありキュー混雑により遅れる。
|
||||
- ICS:ETag/Last-Modifiedを条件付きGETに利用する。304では予定を再書込しない。
|
||||
- CalDAV:過去90日〜未来275日のREPORTでgetetagを取得し、変更分のみ100資源単位のcalendar-multigetで取得する。期間外はローカル投影に保持しない。コレクションURLを直接指定し、discoveryはまだ行わない。
|
||||
- 完全な応答を検証してから全月snapshotとmanifestを更新する。取得失敗、未対応形式、部分的なmultiget、途中で変わったETagでは前回の予定を保持。正常な空集合は削除として反映する。安定したUID順で保存し、応答順の変化による書換を避ける。
|
||||
- 上限:ICS本文8MiB、CalDAV各応答8MiB・予定本文合計8MiB、5000件の射影予定、ジョブ50秒。Outlookで約10秒かかる応答を許容するため、response header 25秒・HTTP全体45秒とする。2.6MiB超・4500件の合成fixtureを回帰試験に含める。
|
||||
- Outlook公開ICSの `METHOD:PUBLISH`、`X-WR-CALNAME`、`VTIMEZONE/TZID`、単一 `RRULE`、Microsoft固有X-propertyを受理する。主要Windows TZIDはIANAへ対応付け、それ以外はSTANDARD/DAYLIGHTとTZOFFSETTOの遷移を同期期間について解決する。RRULEは過去90日〜未来275日の各予定へ安定UIDで展開し、内部正本はUTC/DATEのまま維持する。`X-MICROSOFT-CDO-ALLDAYEVENT:TRUE` のローカル午前0時境界はDATEの終日予定へ変換する。
|
||||
- Outlookが出力する `DTSTART == DTEND` の時刻予定はゼロ時間予定として保持し、同じ境界のMicrosoft終日予定だけは排他的終了を翌日に正規化する。終了が開始より前、またはDATEとDATE-TIMEが混在する場合は予定内容をログへ出さず同期全体を失敗させる。
|
||||
- 外部購読の解析済みプロパティ値・パラメータに混入したC0(タブを除く)、DEL、C1制御文字は正本化の前に除去し、予定へ `X-PAGESWIKI-SANITIZED:CONTROL-CHARACTER` 相当の印を残す。ローカルCRUDの厳格な入力検証は緩和しない。NUL、不正UTF-8、制御文字を含むUIDは同一性・構文破壊を避けるため購読全体を拒否する。
|
||||
- RDATEとEXDATE(DATE/DATE-TIME、複数値)、RECURRENCE-IDによる移動・内容変更・取消を親RRULEへ合成する。例外の出力UIDは元のRECURRENCE-IDから安定生成し、移動後も同一インスタンスとして扱う。EXDATEと変更例外が同一回を指す場合は明示的な変更例外を優先する。
|
||||
- 購読射影が親RRULEを省略し、`RECURRENCE-ID` 付きの変更回だけを含む場合は、取消回を無視し、DTSTARTを持つ回を元のRECURRENCE-ID由来の安定UIDで単発射影する。親がないためDTEND省略時の長さは推測せずゼロ時間予定とする。
|
||||
- RDATEのPERIOD、RECURRENCE-IDの`RANGE=THISANDFUTURE`、DURATION、VALARM、floating時刻はまだ未対応。部分的に欠落させずフィード全体を同期エラーにし、前回snapshotを保持する。現段階でOutlookの全機能や一般プロバイダへの完全対応は宣言しない。
|
||||
- 同期失敗はcompose logへdomain UUID、calendar UUID、protocol、処理段階、安全化した理由を出す。購読URL、認証情報、UID、タイトル、説明、場所、ICS本文はログへ出さない。
|
||||
- HTTPS/443の公開アドレスのみ許可する。接続時DNS検証と接続IP固定、プライベート/loopback/link-local等の遮断、リダイレクト再検査、環境proxy無効によりSSRFを防ぐ。認証付きリダイレクトは同一origin限定。
|
||||
- 任意のBasic認証資格情報は既存認証鍵を用いた暗号化とdomain/calendar束縛で保存し、APIに再表示しない。URLに購読トークンを含む場合は保護された0600のmanifestに保存される。URL/認証情報をジョブpayloadに入れず、取得エラーを秘匿化する。バックアップには正本に加えて認証暗号鍵も必要。
|
||||
|
||||
実プロバイダ接続試験、より広いiCalendar形式、資格情報更新・失効の監査、同期専用の容量/CPU指標、取得対象の管理者allowlistは後続タスクとする。
|
||||
@@ -0,0 +1,33 @@
|
||||
# カレンダーのスマートフォンUI
|
||||
|
||||
2026-09-25実装。iPhone SE相当の320×568/375×667と667×375横画面を対象。**Chromiumのタッチ・画面サイズエミュレーションで検証済み。Safari/iPhone実機の確認は未実施。** 同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。
|
||||
|
||||
## 操作と表示
|
||||
|
||||
- 小さい画面では、表示種別の7リンクをselectにまとめる。今日/前後/日付ピッカーは常時表示。
|
||||
- カレンダー選択・更新・新規予定を残し、追加/設定/外部同期/表示対象は「⋯」メニューへ集約。権限による元の表示制御を引き継ぐ。
|
||||
- 上部の重複ナビと重複見出しを省略。見出し自体はスクリーンリーダー用に維持する。
|
||||
- 週ビューは細い7列にせず、縦画面で約1日、横画面で約2日の幅を確保。曜日/日付ボタンで同じ週の列へ横移動する。見出しの日付を押すと日ビューへ進む。PCの7列表示は維持する。
|
||||
- 月ビューは日付と予定件数を表示し、詳細は日ビューで見る。狭いセルへの件名詰め込みは行わない。
|
||||
- 一覧では日付/件名を優先。場所の列はスマホでは省略し、予定詳細で確認する。
|
||||
|
||||
## タッチ操作
|
||||
|
||||
coarse pointerでは通常、予定の上も空き領域もスクロールとpinch zoomを優先する。指が触れただけで時刻変更・範囲作成を開始しない。タップは予定の詳細へ進む。
|
||||
|
||||
時間グリッドの「編集操作」をONにした場合だけ、移動・開始/終了の伸縮・空き領域の範囲選択を有効化する。ON/OFFはaria-pressedで表現。PCのドラッグ・矢印キー操作は維持する。タイムラインの小さいドラッグハンドルはタッチでは隠し、予定詳細から時刻を編集する。
|
||||
|
||||
## Safariへの配慮
|
||||
|
||||
フォームの文字を16px以上、操作領域を40〜44pxに揃える。画面のzoomを禁止するviewport指定は追加しない。編集ダイアログはVisualViewportのheight/offsetを使い、ブラウザバーやソフトキーボードによる変化を考慮する。pinch zoom中はサイズ更新を停止する。CSSのdvh fallbackとsafe-area insetを併用する。
|
||||
|
||||
スマホのスクロール領域と編集ダイアログはbackdrop blurを外し、テーマの背景色でコントラストを確保する。予定データのキャッシュ/REPORT/ETag/タイムゾーン処理は変更しない。
|
||||
|
||||
## 検証と残TODO
|
||||
|
||||
- 合成ローカルカレンダーで320/375縦・667横、ページ横はみ出し、列幅、日付選択、スクロールと編集gesture切替、月の件数、設定メニュー、編集dialogの収まりを自動検証。
|
||||
- 既存のPC CRUD・ドラッグ・resize・400% zoom・ETag試験を継続。
|
||||
- 外部取り込みカレンダーの内容にはアクセスしない。
|
||||
- TODO: Safari実機でソフトキーボード開閉、画面回転、pinch zoom、背景復帰、長い終日予定、多重重複予定を確認。端末・OSバージョンに応じた調整。
|
||||
|
||||
参考:[WebKitの動的viewport単位](https://webkit.org/blog/12669/new-webkit-features-in-safari-15-5/)、[MDN touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/touch-action)。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 3. キャンパス・ドメイン・連携
|
||||
|
||||
状態:ローカル管理、外部キャンパス参加、署名付き設定配信は実装済み。コンテンツ同期・DRとは別機能。
|
||||
|
||||
## FQDNと配置
|
||||
|
||||
キャンパスの設定値はURLではなくFQDNです。ドメインのホスト指定が短い名前ならキャンパスFQDNのサブドメインとして扱い、FQDNならその値を使います。空のホスト名はキャンパスFQDN自身に対応し、未知Hostの受け皿にはしません。
|
||||
|
||||
表示用FQDNと配置先インスタンスは別の情報です。FQDNを指定しただけでは別インスタンスとは限りません。配置先は承認された候補から選び、同じFQDNの鍵フィンガープリント変更は同じ実体として黙認しません。
|
||||
|
||||
## 設定の所有者
|
||||
|
||||
- キャンパス管理:配下ドメイン、配置、参加トークン、キャンパスの共通情報。
|
||||
- ドメイン管理:Wiki名、テーマ、記事・拡張設定、メンバー、権限。
|
||||
- 外部キャンパス管理:コントローラから受け取った管理項目をローカルで独自に上書きしない。
|
||||
- 秘密:実際に認証・接続するインスタンス側に保持し、一般設定manifestへ混ぜない。
|
||||
|
||||
ドメインの設定は個別です。同じキャンパスに属するだけで記事、グループ、認証セッションを共有しません。
|
||||
|
||||
## 参加と配信
|
||||
|
||||
コントローラ発行トークンで参加要求し、インスタンスidentityを承認します。設定manifestは署名と単調なsequenceを持ち、受信側は適用とcheckpoint更新を同一トランザクションで行います。古いsnapshotへの巻き戻しや同名の別authorityへの置換を拒否します。
|
||||
|
||||
入口設定を含むmanifest v2は、全承認済み配置先の対応能力を事前確認します。対応能力の申告は「適用完了」や「オンライン」の証明ではありません。反映ACKと鮮度の明示はTODOです。
|
||||
|
||||
`--add-external-campus` は通常経路、`--add-external-campus-http` は明示的な開発用HTTP経路です。HTTP許可を一般接続の既定値へ拡張しません。
|
||||
|
||||
## 継承の区別
|
||||
|
||||
キャンパス管理者のローカル継承には、付与元ごとの記録と失効処理があります。独立したローカル付与を消さず、継承を切ったときに派生権限だけを除きます。
|
||||
|
||||
Domain間PSKによるidentity・group継承は設計段階です。署名付き差分、失効、origin競合、鍵交代を含む同期契約と実装が必要です。キャンパスmanifestの配信やローカル管理者継承が完成したことをもって、任意ドメイン間の安全な権限同期が完成したとは扱いません。
|
||||
|
||||
## TODOと合格条件
|
||||
|
||||
- 反映ACK、設定管理の解除、削除ドメインの保持・GC。
|
||||
- 同名・異originのグループ衝突、PSK失効、sequence欠落、鍵交換の試験。
|
||||
- 秘密の外部管理と明示的なローテーション手順。
|
||||
- 別インスタンス記事射影は、取得権限・失効・障害時の閉じ方を設計してから実装する。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 21. 決定事項・矛盾の整理・未決事項
|
||||
|
||||
状態:既存設計の統合と、新規構想の判断台帳。設計案を実装完了に読み替えません。
|
||||
|
||||
## 原資料の読み替え
|
||||
|
||||
| 古い記述・混在 | 現在の読み方 |
|
||||
| --- | --- |
|
||||
| OIDCは形だけ、UserInfoだけを根拠にする | 署名・claim・state/nonce等のhardeningが入っている。詳細契約を優先 |
|
||||
| CookieをやめてBearer一本にする | ブラウザCookieとAPI Bearerを目的分離して併用 |
|
||||
| 匿名ナビゲーション・RSSは未実装 | 限定公開条件で実装済み。全metaや全依存物の公開ではない |
|
||||
| 匿名公開はすべて毎Revision再承認 | 手動公開はそのまま。確認したStreet/Spotのみlive-head自動公開可能 |
|
||||
| 個別記事の一覧登録だけが投稿方法 | 原子的な新規投稿APIと独立画面を追加済み |
|
||||
| 同じCampusなら任意ノードでブログ射影 | 現行の参照型記事射影は同一インスタンスまで |
|
||||
| resourceはブラウザを開いたときだけ記録 | 背景イベントで保存。表示更新と保存間隔は別 |
|
||||
| groupプロフィールのnamespaceが設計のみ | 実装側にgroup画面・APIあり。機能ごとの完了度で読む |
|
||||
| Asset名はinstance全体の名前 | mutable Asset名はDomain-local、Document hashは不変content identity |
|
||||
| イベントキューがあるのでoutboxも完成 | queue、個別journal、transactional outbox配送は異なる |
|
||||
| すべての文書はHTML正本 | 文章の正本HTMLと、バイナリ/固有形式の正本を区別 |
|
||||
|
||||
古い文書は削除せず、初期思想・変更理由・実装の追跡用に保持します。本書とコードが違う場合はまず差分を確認し、設計を理由に現在の安全制約を外しません。
|
||||
|
||||
## 新規ADRの案
|
||||
|
||||
| ID | 提案 | 状態・決めるための条件 |
|
||||
| --- | --- | --- |
|
||||
| ADR-O1 | organizerはtyped metadataと任意Page参照 | タスク初版は専用表+既存CAS Document Store(2026-09-24)。通常のObject閲覧・リンク・削除の権限境界を拡大せず、個人所有を確実に分離する。DBは捨てられる索引ではない。[実装契約](tasks-implementation.md) |
|
||||
| ADR-O2 | task共通部+ticket workflow | 提案。番号・外部依頼者・遷移権限の要件確認 |
|
||||
| ADR-O3 | ICS/vCard入出力→read-only DAV→双方向 | 推奨順。対象サーバー/clientを選んで互換表を作る |
|
||||
| ADR-O4 | FreshRSS正本+PagesWiki connector+newsboat | 第一候補。利用環境・追加運用負荷を確認。内蔵readerは代案 |
|
||||
| ADR-O5 | IMAP read-only、Wikiコピーは明示操作 | 初期設計方針。providerとsampleが実装前提 |
|
||||
| ADR-O6 | HTMLパーツを先行し全面WYSIWYGは保留 | 提案。round-tripと操作改善の評価でgo/no-go |
|
||||
| ADR-O7 | Wiki Pathと外部UID/hrefを分離 | 共通の設計制約。rename fixtureを全connectorで実施 |
|
||||
| ADR-O8 | 外部stateの変更は別段階の明示権限 | 共通の設計制約。既読・削除・送信の監査と確認 |
|
||||
|
||||
## 未決事項
|
||||
|
||||
利用するFreshRSSの有無と版、対象CalDAV/CardDAV client、IMAP provider、taskの共有単位、ticketの依頼者公開範囲、保持期限、外部接続を許可するhost、RPO/RTO、WYSIWYG採用基準です。これらが未決でもlocal fixtureと設計は進められますが、外部サービスを勝手に立ち上げたり資格情報を流用したりしません。
|
||||
|
||||
## 文書運用
|
||||
|
||||
新しい決定には理由・代案・互換影響・試験を残します。変更履歴ledgerと現状の説明を分けます。日本語統合版から詳細原資料へ辿れる対応表を維持し、英語版は同じchapter IDで追従させます。
|
||||
@@ -0,0 +1,61 @@
|
||||
# 11. システム拡張・通知・協働
|
||||
|
||||
状態:信頼済みビルトインcatalogと設定入口あり。任意第三者コードのロードは未実装。
|
||||
|
||||
## アダプタとシステム拡張
|
||||
|
||||
アダプタは特定Documentを開く・編集する役割、システム拡張は活動、通知、コメント、予定、メール、RSS、検索provider等のサービスです。外部サービス連携用URLに汎用管理権限を押し込めません。
|
||||
|
||||
現行catalogは `/_/api/v1/extension/`、個別操作は `/_/api/v1/extension/{id}/…` の系統です。catalogに載っても任意コード実行や権限付与は許可されません。
|
||||
|
||||
## 共通manifest案
|
||||
|
||||
安定ID、版、互換範囲、scope、設定schema、必要capability、outbound host、secret reference、購読event、checkpoint、実行image digest、署名、CPU/メモリ/時間/出力制限を宣言します。
|
||||
|
||||
設定はinstance / Domain / Principalを区別します。ホスト所有のフォームを基本にし、独自UIはsandboxと型付きメッセージに限定します。無効化はデータ消去と別操作です。export、移行、rollback、孤立データの保持期間を必須契約にします。
|
||||
|
||||
## 協働機能の正本
|
||||
|
||||
| 機能 | 保存するidentityと状態 | 漏えいさせないもの |
|
||||
| --- | --- | --- |
|
||||
| 最近編集 | event、actor、Page/Revision、Domain sequence | 現在読めないPageのタイトル |
|
||||
| 最近閲覧 | 本人の閲覧履歴と保持期限 | 他者の私的な閲覧履歴 |
|
||||
| いいね・ランキング | Page、反応者、期間集計、計算版 | 非公開Pageの順位や件数 |
|
||||
| 品質評価 | rubric版、評価者、対象Revision、根拠 | 機械評価を人の決裁と偽る表示 |
|
||||
| inline comment | Revision、範囲、周辺hash、孤立状態 | 改訂後の別文章への誤結合 |
|
||||
| コメントthread | Page、投稿・編集履歴、moderation | 削除・権限失効後の本文 |
|
||||
| 通知Inbox | event、受信者、配送・既読 | 保存時点の権限で固定した本文 |
|
||||
|
||||
通知を開く時点で権限を再評価します。権限を失った相手へ昔のタイトル付きメールを新規送信しません。送信済み外部通知の撤回不能性は別途表示します。
|
||||
|
||||
## 外部検索・埋め込み・テーマ
|
||||
|
||||
ローカル検索にない場合も、検索語を自動でGoogle等へ転送しません。宛先と送信語を示して選択させます。GROWI、PukiWiki、他PagesWikiは個別API契約・資格情報・上限を確認します。
|
||||
|
||||
Spotify/YouTube等のwidgetはprovider許可と同意プレースホルダを使います。文書内の任意scriptを実行しません。時間・日没によるテーマは型付き条件とCSS theme IDを扱い、位置情報を無断取得しません。
|
||||
|
||||
## ネットワーク・資産管理拡張(設計TODO)
|
||||
|
||||
IPアドレス管理(IPAM)、DNSゾーン/レコード管理、機器・ソフトウェア等の資産管理は、通常のWiki本文を直接書き換えるアダプタではなく、監査可能なシステム拡張として設計します。正本はそれぞれ `network_prefix`、`dns_zone`/`dns_record`、`asset_item` の型付きエンティティとし、説明・手順・添付資料だけをPage/Assetへの参照で持ちます。
|
||||
|
||||
| 拡張 | 最初の範囲 | 外部副作用と権限 |
|
||||
| --- | --- | --- |
|
||||
| IPAM | prefix、address、予約・割当、重複検査、CIDR表示 | read/writeを分離し、割当変更は承認と監査を必須化 |
|
||||
| DNS | zone、record、TTL、所有者、検証済みtarget、差分 | zone単位の管理者、DNS providerへのapplyはdry-run→承認→idempotent apply |
|
||||
| 資産 | asset、serial、owner、場所、状態、保証・関連Page | 個人情報・秘密値を本文や検索snippetへ出さず、履歴と廃棄を保持 |
|
||||
|
||||
外部DNSやCMDBへ接続する場合も、secret reference、許可origin、rate limit、最終同期時刻、providerのrevision/etagを保存します。DNSの名前解決やIPスキャンをページ表示中に実行せず、イベントキューのbounded jobにします。削除・再利用・移管はsoft deleteと競合検知を経てから行い、失敗時は外部状態と内部状態の差分を通知Inboxへ送ります。API候補は `/_/api/v1/extension/network.ipam/*`、`network.dns/*`、`inventory.assets/*` とし、schemaが固まるまで実装しません。
|
||||
|
||||
## CSV/表・スライド拡張(設計TODO)
|
||||
|
||||
CSVをPage本文へ複製せず、認可済みの別Documentをテーブルとして投影するmacroを用意します。候補構文は `{{csv:/data/items.csv range=A1:H200 header=true}}` とし、Path、Revision(またはasset hash)、列・行上限、表示モードを正規化してキャッシュキーに含めます。macroは表示時にboundedなProjectionを作るだけで、結果HTMLを正本へ逆流させません。CSV Editorは元Revisionを編集し、表投影とは別の操作・競合・権限として扱います。
|
||||
|
||||
交換形式はRFC 4180互換CSV(UTF-8、CRLF、引用符・改行を含むfield、BOMの扱いを明示)を第一正本とします。複数シート、型、数式、結合セル、書式が必要な場合はODSを別アダプタ/Assetとして扱い、CSVへの不可逆変換を黙って行いません。行数、列数、セル長、総バイト、ネストmacroを制限し、malformed inputは安全なテキスト表示へfallbackします。
|
||||
|
||||
スライドは、Markdown/HTMLの正本からReveal.js互換のProjectionを生成する連携アダプタを設けます。HedgeDoc、Slidevは外部originのホスト型アダプタとして、保存・公開・ユーザー情報をPages Wikiの権限へ自動昇格させず、read-only preview→明示的なimport/saveの順にします。JSを使用できない環境向けには、CSS scroll-snap/`:target`/print CSSだけでページ送りできるCSS-only Slide Editorを別実装します。外部ランタイム停止時は静的HTML/Markdownへ安全にfallbackし、任意script、remote import、iframe権限を本文から許可しません。
|
||||
|
||||
ネットワーク図ではnwdiagを追加候補とします。ソースをbounded parserで検証し、renderer version/theme/document hashをキーに静的SVGをキュー生成します。include、外部画像・font、未知directive、危険なSVG属性は拒否し、renderer停止時はescaped sourceまたは最後に検証済みの静的画像へfallbackします。編集アダプタの保存はone-use ticketと楽観的Revision競合を使い、Kroki経由の場合もorigin、timeout、quotaを明示します。
|
||||
|
||||
## 最初に作る共通部
|
||||
|
||||
outbox、actor provenance、現在権限で絞るprojection、設定のsecret参照、connectorの予算と再試行、export/削除です。機能別に通知・認可・秘密管理を作り直さないことを次章以降の前提にします。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 15. RSSビューア・FreshRSS・newsboat
|
||||
|
||||
状態:設計案。既存のブログRSS「配信」と、本章の外部RSS「購読」は別機能。
|
||||
|
||||
## 選択肢と推奨する試作順
|
||||
|
||||
| 案 | 正本 | 利点 | 追加する責任 |
|
||||
| --- | --- | --- | --- |
|
||||
| PagesWiki内蔵reader | ローカルの購読と状態 | Wiki保存と一体のUI | 取得・既読・同期・client対応を全て持つ |
|
||||
| FreshRSS connector | FreshRSSの購読・既読 | 既存reader資産を利用 | API互換性、権限、cacheと失効 |
|
||||
| newsboat単独の橋渡し | newsboat側の購読・状態 | CLI利用に合わせやすい | ローカル連携経路・export/importの設計 |
|
||||
|
||||
FreshRSSにはGoogle Reader互換APIがあり、APIの有効化と専用passwordを使います。newsboatにはFreshRSS連携が用意され、カテゴリのtag化やstar操作を扱えます。[FreshRSS公式API](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html)、[newsboat公式マニュアル](https://newsboat.org/releases/2.42/docs/newsboat.html#_freshrss)。
|
||||
|
||||
このため最初の候補は **FreshRSSを正本、PagesWikiを読取connector、newsboatを同じFreshRSSのclient** とする構成です。これは設計上の提案で、ユーザー環境のFreshRSS導入・採用決定ではありません。PagesWikiがnewsboatをサーバー上で起動したり、そのSQLiteを共有したりする必要はありません。
|
||||
|
||||
## 読取MVP
|
||||
|
||||
購読一覧、フォルダ、記事一覧、外部原文、Wiki保存を提供します。初期段階では表示しただけでFreshRSSへ既読を送りません。UIには「読取専用・既読は同期していない」と明示します。ブラウザへFreshRSS password/tokenを渡さず、backend connectorがsecret参照を使います。
|
||||
|
||||
最小cache案はsource UUID、remote feed/item ID、title、safe excerpt/body hash、canonical URL、published/updated/fetched時刻、remote state/versionです。IDなしRSSにはfeed単位の保守的な代替キーを使い、題名だけで重複排除しません。Atomはentry IDと更新情報を持つ形式です。[Atom仕様](https://www.rfc-editor.org/rfc/rfc4287)。
|
||||
|
||||
## 既読・star同期を追加する条件
|
||||
|
||||
server-authoritative stateと未送信の操作を分けます。操作ごとのrequest_idで重複を防ぎ、成功応答前に確定済みと表示しません。newsboat等で同時変更された場合、古いローカルcacheをまとめて送り返しません。接続解除・認可失効時は未送信変更を勝手に再送しません。
|
||||
|
||||
FreshRSS APIに条件付き更新がない操作もあり得るため、対応版の実機fixtureで競合動作を確認するまで完全な双方向同期を約束しません。
|
||||
|
||||
## 内蔵fetcherを選ぶ場合
|
||||
|
||||
定期event、条件付きGET、host別同時数、timeout、応答サイズ、展開サイズ、backoffを設けます。XML外部entityを無効にし、feed HTMLを安全化します。redirect/DNSを含むSSRF対策、外部画像の同意、個人購読URLや認証情報の秘匿が必要です。
|
||||
|
||||
OPMLは購読の入出力として扱い、既読・star・全本文のバックアップと同一視しません。importはpreview・追加/置換選択・重複確認を行い、既存購読を黙って削除しません。
|
||||
|
||||
## Wiki保存と権利・公開
|
||||
|
||||
既定はURL、出典、短いメモの保存です。全文保存は取得可能性・利用条件・個人用途等を確認する独立操作とし、feedが短いからといって有料記事を自動取得しません。保存先が自動公開範囲なら内容と添付の公開を明示確認します。
|
||||
|
||||
## TODOと受け入れ
|
||||
|
||||
RSS-1:read-only FreshRSS fixture。RSS-2:安全な一覧と出典付きWiki保存。RSS-3:必要なら既読/star送信。RSS-4:内蔵reader採用判断とOPML。オフライン、欠落ID、巨大feed、未知HTML、同期再送、他user情報、feed削除後の保存Page維持を試験します。
|
||||
@@ -0,0 +1,38 @@
|
||||
# 17. HTMLパーツとWYSIWYGの判断
|
||||
|
||||
状態:設計案。全面WYSIWYG採用は未決定。既存エディタを置換しない段階的改善を第一案とします。
|
||||
|
||||
## 解決したい問題
|
||||
|
||||
表、画像とcaption、引用、注意書き、コード、リンク、macro、埋め込みを毎回手書きする負荷を減らします。単にHTMLを隠すことより、既存文書を壊さず効率よく編集できることを重視します。
|
||||
|
||||
## 段階案
|
||||
|
||||
1. Source+Projection previewを保ち、HTMLパーツ挿入paletteを加える。
|
||||
2. 選択範囲の整形、リンク・表・画像の型付きdialogを追加する。
|
||||
3. 対応するblockだけを視覚編集し、未知blockはread-only islandまたはsource編集へ戻す。
|
||||
4. 完全WYSIWYGはfixture評価と操作上の効果が確認できた場合だけ採用判断する。
|
||||
|
||||
HTMLパーツは安定ID、版、schema、HTML template、preview、許可属性、必要providerを持ちます。挿入時に文書へ具体化するパーツと、動的macroを区別します。パーツ更新で過去Revisionを勝手に書き換えません。
|
||||
|
||||
## 保存契約
|
||||
|
||||
canonical HTMLと編集モデルと安全な表示HTMLは別です。preview展開済みchildren、閲覧者ごとのリンク、署名URL、session値を保存しません。unknownな属性を無言で削除するeditorは、その文書を視覚編集できると表示してはいけません。
|
||||
|
||||
保存は対象Page、編集開始Revision、言語、期待versionを照合し、競合時に選択・差分確認へ戻します。autosaveは下書きと本Revisionのどちらかを明示し、previewしただけで公開headを進めません。自動公開範囲では保存が公開へ直結することを表示します。
|
||||
|
||||
## round-trip fixture
|
||||
|
||||
- children等のmacro、asset provenanceと固定hash、embedded-object。
|
||||
- code/pre、入れ子list、table、caption、非ASCII Path、RTL、複数言語。
|
||||
- 未対応HTML、コメント、アクセシビリティ属性、長文・巨大table。
|
||||
- paste時のscript/event属性/外部参照、安全化後と正本の違い。
|
||||
- undo/redo、IME変換中、選択維持、キーボード、screen reader。
|
||||
|
||||
比較はbyte一致だけでなく、許可した正規化以外の意味・依存参照・未知blockを失わないことを検査します。変更なしで保存した場合に大量diffを作るeditorも不合格候補です。
|
||||
|
||||
## 採用判断の条件
|
||||
|
||||
HTMLパーツだけで主な不便が解決するならそこで止めます。完全WYSIWYGは、round-trip・IME・大規模文書・保守性・ライセンス・bundle負荷を比較したADRを作ってから選びます。特定ライブラリ採用や共同編集CRDTの導入は今回決めません。
|
||||
|
||||
EDITOR-1:fixtureとpalette schema。EDITOR-2:少数パーツの挿入。EDITOR-3:限定block prototype。EDITOR-4:比較評価とgo/no-go。共有編集は別の権限・競合・接続設計を必要とする後続事項です。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 19. 多言語と設計書の配信
|
||||
|
||||
状態:Revision言語とfallback、日英UIの基盤あり。全画面の言語選択・翻訳管理・公開版の対応は継続課題。
|
||||
|
||||
## 同じ知識、同じPath
|
||||
|
||||
Pageは言語中立で、RevisionにBCP 47言語tagを持たせます。同じ章の日本語と英語を別Pageとして増やすのではなく、同じPage UUIDの `ja` と `en` を将来の配信先とします。
|
||||
|
||||
UI locale、本文の言語、Campus/Domainの既定言語は同じ設定ではありません。本文が日本語でも英語UIを使えます。`und` は言語未指定・legacy互換であり、「全言語で同じ内容」という保証ではありません。
|
||||
|
||||
## 解決と権限
|
||||
|
||||
明示指定、Accept-Language、地域tagの基底、Campus/system既定、und等を考慮する既存基盤があります。明示選択のURLや全endpointでの一貫性は別の完成条件です。fallbackで別言語を返す場合には選択された言語を把握できるUIが必要です。
|
||||
|
||||
非公開の日本語Revisionを英語fallbackで漏らしたり、その逆を起こしてはいけません。公開承認は言語headと正確なRevisionの関係を含めて検査します。自動公開ルールでは各言語の現在headも対象になる点を管理者へ示します。
|
||||
|
||||
## 今回の設計書配置
|
||||
|
||||
リポジトリの `docs/design/ja/` に日本語の編集元を置き、章IDをファイル名で安定化します。Wikiは `/lab/pageswiki-dev` を総目次とし、その配下へ同じ章IDで配置します。章番号は題名の表示順であってURL identityにしません。
|
||||
|
||||
配信用にMarkdownをHTMLへ変換し、`ja` Revisionとして保存します。日本語版を理由に既存英語資料を削除しません。Wiki側の公開権限を追加・変更しません。
|
||||
|
||||
英語化は原資料を単に一括アップロードするのではなく、日本語版の章ID・現在状態・決定事項と対応させます。原資料には古い構想が残るため、そのまま最新英語版とは扱えません。
|
||||
|
||||
## 翻訳台帳の案
|
||||
|
||||
`chapter_id, source_lang, source_hash, target_lang, translated_from_hash, reviewed_at, status` を持ち、元章の変更でstaleを検出します。翻訳の自動生成とreview済み公開を分けます。言語を切り替えると別の章に移動しないことを検証します。
|
||||
|
||||
## TODO
|
||||
|
||||
言語選択UI、lang別history/diff、translation stale表示、明示指定とcanonical、Content-Language/Vary/cacheの整合、公開言語別の失効、英語版のreview。これらが整うまでは英語の中間資料はリポジトリで保持します。
|
||||
@@ -0,0 +1,53 @@
|
||||
# PagesWiki 開発設計書
|
||||
|
||||
更新日:2026-09-19。日本語の統合設計版。実装の変更履歴ではなく、現在の境界と次の設計判断を確認するための入口です。
|
||||
|
||||
## この設計書の読み方
|
||||
|
||||
- **実装済み**:利用できる機能の範囲。関連する制約や未監査部分も併記します。
|
||||
- **設計案**:今回具体化した方針。API・テーブル・既定値は、実装や互換性試験で確定させます。
|
||||
- **TODO**:未実装の作業。記述やURL例が存在しても利用可能とは限りません。
|
||||
- **保留**:安全性・運用方式・外部環境の選択が必要で、現時点では着手しません。
|
||||
|
||||
既存の英語・日本語の原資料はリポジトリに残します。初期構想と追記が混在するため、現状の読み取りでは本書の状態表示と、対応実装・テストを優先します。チェック済み項目も製品全体の完成を意味しません。
|
||||
|
||||
## 第I部 基盤
|
||||
|
||||
1. [設計思想と責務の分離](/lab/pageswiki-dev/principles)
|
||||
2. [アドレス・保存・アセット](/lab/pageswiki-dev/address-storage)
|
||||
3. [キャンパス・ドメイン・連携](/lab/pageswiki-dev/campus-federation)
|
||||
4. [Knowledge City と案内図](/lab/pageswiki-dev/knowledge-city)
|
||||
5. [認証・グループ・権限](/lab/pageswiki-dev/auth-permissions)
|
||||
6. [公開・承認・共有・匿名ナビゲーション](/lab/pageswiki-dev/publication)
|
||||
|
||||
## 第II部 利用機能と実行基盤
|
||||
|
||||
7. [ビューア・エディタ・連携アダプタ](/lab/pageswiki-dev/viewer-editor)
|
||||
8. [検索・ツリー・ホーム・設定画面](/lab/pageswiki-dev/navigation-search)
|
||||
9. [イベント・キュー・リソース監視](/lab/pageswiki-dev/scheduler-resources)
|
||||
10. [ブログ・日記・公開ドメイン射影](/lab/pageswiki-dev/blog-diary)
|
||||
11. [システム拡張・通知・協働](/lab/pageswiki-dev/extensions)
|
||||
|
||||
## 第III部 オーガナイザーと編集拡張の設計案
|
||||
|
||||
12. [オーガナイザーの共通モデル](/lab/pageswiki-dev/organizer)
|
||||
13. [タスクとチケット](/lab/pageswiki-dev/tasks-tickets)
|
||||
- [個人タスク・プロジェクトの実装契約と次段階](tasks-implementation.md)(2026-09-24)
|
||||
- [個人タスクのCalDAV/CLI連携](task-caldav.md)(2026-09-26、本番反映済み)
|
||||
- [時間枠とPomodoroの実装契約](task-planning-focus.md)(2026-09-25)
|
||||
14. [予定・iCalendar・CalDAV・連絡先](/lab/pageswiki-dev/calendar-contacts)
|
||||
15. [RSSビューア・FreshRSS・newsboat](/lab/pageswiki-dev/feeds)
|
||||
16. [IMAP取り込みとメールからWikiへの保存](/lab/pageswiki-dev/mail)
|
||||
17. [HTMLパーツとWYSIWYGの判断](/lab/pageswiki-dev/html-editor)
|
||||
|
||||
## 第IV部 運用・実装計画
|
||||
|
||||
18. [性能・保全・外部ストレージ・HA/DR](/lab/pageswiki-dev/operations)
|
||||
19. [多言語と設計書の配信](/lab/pageswiki-dev/i18n)
|
||||
20. [実装順序と受け入れ条件](/lab/pageswiki-dev/roadmap)
|
||||
21. [決定事項・矛盾の整理・未決事項](/lab/pageswiki-dev/decisions)
|
||||
22. [原資料との対応と外部仕様](/lab/pageswiki-dev/sources)
|
||||
|
||||
## 今回の範囲
|
||||
|
||||
今回行うのは設計の再整理と日本語設計書の配置です。オーガナイザー、外部サービス、DAVサーバー、メールアカウント、公開権限の新設は行いません。設計書の配置も匿名公開の許可とは別です。
|
||||
@@ -0,0 +1,38 @@
|
||||
# 4. Knowledge City と案内図
|
||||
|
||||
状態:階層、境界、案内図、URL推論・編集の初期実装あり。自動整理の完全な整合性と大規模化は継続課題。
|
||||
|
||||
## 街の役割
|
||||
|
||||
Domainを一つのKnowledge City、Quartierを学区・街区、Streetを通り、Spotを知識の拠点として扱います。道路交通図ではなく、西洋建築の街区・中庭・入口を手がかりに知識へ到達する案内図です。
|
||||
|
||||
Spotを開くと、その拠点と周囲のPageを探索できます。ポータルPageは説明の入口であって、配下の一覧を失わせる自動転送の代用品にはしません。
|
||||
|
||||
## Path境界と多重参照
|
||||
|
||||
`/life`、`/life/home`、`/life/home/kitchen` をQuartier、Street、Spotへ対応させる例では、子境界は親の厳密な子孫です。同階層境界の重複はprimaryな所属の曖昧さを避けるため制限します。移動・統合では境界と親子関係を一緒に検証します。
|
||||
|
||||
Pageのprimary所属はPathから推論し、明示的なSpot参照は別のグラフ辺として持ちます。他のSpotへ紹介してもPageを複製せず、所属させただけで閲覧権限を与えません。Spotの下へ別のSpotを任意にネストさせる操作は現行モデルの階層ではありません。
|
||||
|
||||
## 案内図の表示規約
|
||||
|
||||
- Domainで生成した街の幾何をQuartier・Streetへ割り当て、ズームで文脈を保つ。
|
||||
- Page数は相対重みだけでなく、少量のStreetを小さくする規模の目安にも使う。
|
||||
- 未整理Pageは黄緑の個別ポイント。意味のない重複Spot名を増やさない。
|
||||
- ラベルは原則水平。未ホバー時は場所を把握でき、ホバー時は対象を強調する。
|
||||
- Spot近接・ラベル重なり・クリックとドラッグの判定を試験する。
|
||||
- メニューはモーダルへ集約し、地図ポップアップは地図中心。ESC、矢印、WASD/HJKLを既存操作と衝突させない。
|
||||
- 戻る・進むはアプリ内の状態遷移として扱い、URLの恒久履歴と同じものだと説明しない。
|
||||
|
||||
## URLからの自動整理
|
||||
|
||||
設計案は「推論結果を無条件に再生成」ではなく、手動編集を保護するreconciliationです。生成元、生成版、手動上書き、除外tombstoneを記録し、同じ入力なら変更なしに収束させます。
|
||||
|
||||
更新トランザクションと共通outboxを接続し、作成・編集・rename・削除を記録します。
|
||||
DomainごとのCity consumerは10秒周期でイベントをdebounceし、URLからの自動計画を
|
||||
背景キューで実行します。成功時だけwatermarkを進め、失敗時は再試行します。完全な
|
||||
所有権・分散consumer・通知配送はTODOです。
|
||||
|
||||
## 性能・認可のTODO
|
||||
|
||||
現在のWorker生成や表示数上限だけでは、サーバー側で全体を読む問題は解決しません。局所的な階層取得、Pageのcursor、directory索引を先に整備します。権限で除外した名前・件数・ポータル・辺をcacheから復活させないことを合格条件にします。
|
||||
@@ -0,0 +1,33 @@
|
||||
# 16. IMAP取り込みとメールからWikiへの保存
|
||||
|
||||
状態:設計案。初期はメール原本を変更しない読取専用取り込み。SMTP送信は別機能。
|
||||
|
||||
## データと識別
|
||||
|
||||
account、mailbox、UIDVALIDITY、UIDを組み合わせてremote identityを持ちます。Message-IDは重複・欠落があるため補助情報に留めます。UIDVALIDITY変更は新しい世代として再照合し、UIDだけで別のメールを上書きしません。[IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051)。
|
||||
|
||||
原MIME/EMLは不変Documentとして保存し、headers、本文part、添付、thread候補を派生metadataへ分けます。メールは私的collectionに属し、必要なものだけWiki Pageへコピーします。メールアドレスとローカルPrincipalを自動同一視しません。
|
||||
|
||||
## 初回取り込みと増分
|
||||
|
||||
フォルダ・期間・件数・サイズを選んでpreviewします。UID範囲を小batchで取得し、Documentとmetadata確定後にcheckpointを進めます。既読を付けない取得方式を使い、初期実装ではSTORE、MOVE、EXPUNGE等の変更操作を行いません。本文取得には非既読化の `BODY.PEEK` 等の意味を検証します。[IMAP仕様](https://www.rfc-editor.org/rfc/rfc9051)。
|
||||
|
||||
切断・timeoutは再試行し、外部の削除とは扱いません。IMAP4rev1互換、OAuth、サーバー固有のlabel/folder挙動は対象providerを選んだ上でfixtureにします。IDLEを採用しても定期照合を残し、全accountで無制限な接続を保持しません。
|
||||
|
||||
## 表示
|
||||
|
||||
既存EML parser/viewerを再利用し、HTMLはinert処理または分離表示にします。remote画像は既定で読み込まない案です。CID参照はそのメールの添付へ限定し、別のprivate Documentを指せません。添付名のPath traversal、巨大multipart、圧縮bombを制限します。
|
||||
|
||||
## Wikiへコピーする操作
|
||||
|
||||
確認画面で、宛先Path、題名、本文形式、添付の選択、出典リンク、公開見込みを表示します。共有メールでも自動公開はしません。`copy_receipt(account,message,destination,request_id)` 等で再送を識別し、Page・Revision・固定添付参照・監査を原子的に確定する案です。
|
||||
|
||||
コピーした後、元メールが消えてもWiki Pageを消しません。逆にmirrorの保持期限削除で、Wikiから参照されるDocumentをGCしません。コピーは既読・移動・削除・返信を同時に実行する操作ではありません。
|
||||
|
||||
privateメールをautomatic公開範囲へ入れると公開されるため、宛先policy versionを確認時と書込時で照合します。公開範囲が変化したら409等で再確認させます。本文を読めることと、外部へ公開できることを混同しません。
|
||||
|
||||
## 運用とTODO
|
||||
|
||||
MAIL-1:read-only小規模fixtureとcheckpoint。MAIL-2:EML表示・添付境界。MAIL-3:copy-to-Wikiとpolicy競合。MAIL-4:保持・export・account解除。双方向既読同期やメール送信は後続の明示選択です。
|
||||
|
||||
認証失敗のbackoff、accountごとの予算、暗号化secret、ログのheader/body秘匿、再取得上限を設けます。UIは最終成功と遅延・失敗を表示し、未取得を「メール0件」としません。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 8. 検索・ツリー・ホーム・設定画面
|
||||
|
||||
状態:検索・children・Tree・ホーム・ブックマーク・設定整理の初期機能は実装済み。大規模索引と共通サイドバーは継続課題。
|
||||
|
||||
## 閲覧の入口
|
||||
|
||||
トップバーの検索はhome PathではなくDomain全体の `/` を基準にします。指定フォルダ内の検索とはモードを分けます。結果は全文だけでなくタイトル・Path・City要素のどこに一致したかを示し、Quartier/Street/Spotを上位にまとめます。
|
||||
|
||||
ファイル種別、拡張子、作成・更新日を候補取得の前に適用します。snippet生成失敗で結果全体を消さず、HTMLをそのまま検索結果へ注入しません。日本語の部分一致・現在Revisionだけの索引は残課題です。
|
||||
|
||||
## childrenとTree
|
||||
|
||||
childrenは現在Pathを既定にし、表示形式は本文macroの `view` 引数ではなくナビゲーションのアイコン操作で切り替えます。仮想フォルダでは設定により配下を表示します。サムネイルは描画を妨げず非同期取得します。
|
||||
|
||||
`/v/tree/{path}` は範囲を限定します。展開・全展開・全折りたたみ状態の保持、複数選択、rename・移動・削除はPath操作と一致させます。一般の子一覧から予約ユーザー領域を混入させません。再帰操作は事前の全対象確認と競合検出が必要です。
|
||||
|
||||
## ホームとブックマーク
|
||||
|
||||
通常トップバー型、中央検索型、検索+セクションカード型を選びます。セクションは手動URL/Path、または指定親の子リンクを表示します。設定は歯車のポップアップで、閲覧画面を編集フォームで埋めません。カード列はviewportに適応します。
|
||||
|
||||
外部ブックマーク連携は、手動登録と同期由来を区別し、同期時にローカル項目を削除しません。
|
||||
|
||||
## 設定画面
|
||||
|
||||
基本・認証・ドキュメント・拡張・運用等のグループとサブパネルを使います。選択したパネルだけ非同期で読み込みます。フォームの入力をpollingで上書きしません。トグルの装飾には実際のlabel・フォーカス・キーボード操作を残します。
|
||||
|
||||
テーブルは一行中心、詳細は展開またはポップアップへ。非JSONの403等をJSON parse errorに置き換えず、元の原因を表示します。
|
||||
|
||||
## TODO
|
||||
|
||||
directory索引と不透明cursor、権限付き検索の十分なrecall、共通サイドバー、個人ブックマーク、関連するテーブルのアクセシビリティ試験。キャッシュは認可結果の長期保存にせず、現在の権限を再評価します。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 18. 性能・保全・外部ストレージ・HA/DR
|
||||
|
||||
状態:単一writerのSQLite運用、限定付きジョブ・cache、バックアップ手段あり。HAと外部保存は別途設計・検証が必要。
|
||||
|
||||
## 現状と性能優先順位
|
||||
|
||||
複数インスタンスがあっても、同じDBを共有するHAではありません。各SQLiteとDocument Storeのauthorityを区別します。コンテンツを読む要求に、全履歴走査、全文body hydration、巨大archive展開、外部接続待ちを持ち込まないことが最優先です。
|
||||
|
||||
| 課題 | 次の修正方向 | 完了を判定する試験 |
|
||||
| --- | --- | --- |
|
||||
| 全Path集計 | directory索引・局所query・cursor | 大階層で候補数とDB時間が限定される |
|
||||
| 全City取得 | shallow projection・遅延Page取得 | 小範囲表示で全体を読まない |
|
||||
| 歴史RevisionのFTS | current-only、安全なplain text索引 | 更新・削除・日本語検索・権限失効 |
|
||||
| 大容量restore | immutable参照再利用・stream | heapがpayloadサイズに比例しない |
|
||||
| decoder | process隔離・重み付き予算 | timeout/cancel/メモリ上限で確実に終了 |
|
||||
| 失効とcache | generation+要求時認可 | 古い一覧からprivate内容を復活させない |
|
||||
|
||||
上限を増やす前にquery planと現実的なデータ量を測ります。公開ページの匿名cacheと認証ユーザーの認可cacheを同一にしません。
|
||||
|
||||
## 保全
|
||||
|
||||
DBだけでなくDocument Store、設定、復旧に必要な鍵を区別してバックアップします。稼働SQLiteを単純copyせず、online backup等の整合した手段を使います。Documentの固定hash検証、参照整合性、戻し手順をfixtureまたは別環境で確認します。
|
||||
|
||||
削除・復元は現行権限、全Path binding、依存参照、保持期限を確認します。バックアップ復元による過去権限復活には運用上の失効再適用が必要です。秘密を一般のWiki設計書やログへ複製しません。
|
||||
|
||||
## 外部ストレージ案
|
||||
|
||||
Document backendはStat/Open/ReadAt/PutIfAbsent/Verify/DeleteUnreferencedを持ち、SHA-256 identityを維持します。S3 key・ETag・URLをDocument identityとみなしません。multipart、短命URL、Range、GC、read-after-write確認を試験します。
|
||||
|
||||
WebDAV/SSHFSの可変ファイルとimmutable CASは別です。最初はread-only connector/import、マウントは専用sidecar等の運用責務としWeb要求でmountしません。SSH host key、outbound制限、secret管理が前提です。
|
||||
|
||||
## ファイル監査
|
||||
|
||||
MWDB/Karton等の接続はpending/clean/suspicious/malicious/error/expiredの状態と、engine・版・hash・時刻・由来を持つ非同期処理を案とします。監査必須の範囲ではcleanがない間のviewer/download/adapterを閉じます。scannerへ機密本文を送る操作には別の送信方針が必要です。
|
||||
|
||||
## DRとHAの順序
|
||||
|
||||
コントローラDRは署名manifest journal、鍵の保全、sequence、昇格epoch、旧leaderのfencingから設計します。記事DBとDocumentの複製は別の責務です。Campus manifestは記事バックアップではありません。
|
||||
|
||||
LB/HAにはsession失効共有、job lease、cache invalidation、uploadのnode非依存、WebSocket drain、proxy origin検証を要します。SQLiteをネットワーク共有して複数writerで動かす構成は採りません。fenced single-writer+replicaか、適切なmetadata backendを先に選びます。
|
||||
|
||||
RPO/RTOは目標値をユーザーと決め、復旧訓練の実測で保証範囲を定めます。現在の構成に無根拠な無停止・無損失を約束しません。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 12. オーガナイザーの共通モデル
|
||||
|
||||
状態:設計案。今回は設計のみで、外部アカウント登録や同期を有効にしません。
|
||||
|
||||
## 目的と最初の範囲
|
||||
|
||||
Wikiの知識と、予定・タスク・連絡先・受信情報を相互に参照できる入口を作ります。メール、RSS、カレンダーの既存サービスを全て置き換えることは初期目標ではありません。
|
||||
|
||||
初期の画面は「今日」「タスク」「予定」「受信情報」「連絡先」を切り替える、薄い集約画面とします。各コレクションの権限で絞り、未読件数すら他者へ漏らさない設計です。共有の通知Inboxと、メール受信箱・RSS未読一覧は別物です。
|
||||
|
||||
## identityの案
|
||||
|
||||
| 概念 | 安定したキー | 別途持つ可変情報 |
|
||||
| --- | --- | --- |
|
||||
| collection | ローカルUUID、Domain、所有Principal/共有scope | 表示名・接続先 |
|
||||
| item | ローカルUUID、kind、collection | status、title、version |
|
||||
| Page参照 | Page UUID、参照Domain | 現在のPath・表示URL |
|
||||
| remote binding | connector UUID、remote collection、remote ID | remote href、ETag、checkpoint |
|
||||
| connector | ローカルUUID、provider、owner、許可scope | secret_ref、health、最終成功 |
|
||||
|
||||
イベント、タスク、メール等を無型の一つのJSON表へ押し込む案は採りません。共通identity・監査を持ち、kind固有の表または厳格schemaを持ちます。Wiki本文が必要なitemだけPage UUIDへ関連付けます。全メールを自動でPageにする必要はありません。
|
||||
|
||||
## 正本を一つ選ぶ
|
||||
|
||||
コレクションごとに `local_authoritative`、`remote_readonly`、将来の `remote_sync` を区別します。最初はlocalまたは読取専用mirrorです。remoteを正本とする項目の編集は、無断でlocal版を作るのではなく、未対応または明示的なcopyとして扱います。
|
||||
|
||||
同期を導入した場合もremote IDとWiki Pathを同一identityにしません。renameはbookmark/DAVのresource identityを再生成する理由になりません。
|
||||
|
||||
## 変更と同期の契約案
|
||||
|
||||
変更には期待versionとrequest_idを要求し、item更新・監査・outboxを同一transactionにします。connectorsは小さなbatchで取得し、保存成功後にcheckpointを進めます。再試行は重複排除し、失敗した一件のせいで全件再取り込みしません。
|
||||
|
||||
削除はtombstoneとして配送可能な期間を持たせます。画面から消したこと、mirror cacheを削除したこと、外部原本を削除したことを区別します。時計だけのlast-write-winsで予定やタスクを無言で上書きしません。
|
||||
|
||||
## 接続安全性
|
||||
|
||||
Domain、Principal、provider、許可host、credential purposeを固定します。リダイレクトとDNS再解決も検証し、無制限の内部ネットワーク取得を防ぎます。秘密はsecret_refだけを設定・ログへ載せます。接続解除はtoken失効、job停止、cache保持・削除の選択を伴います。
|
||||
|
||||
## UI案
|
||||
|
||||
一覧はcompact table、詳細はdrawerまたはdialog、設定は歯車。外部由来・最終同期・未送信変更・競合を区別して表示します。オフラインを「空の予定」と扱いません。Wiki保存時は保存先、出典、添付、公開予定の確認を一つの画面で行います。
|
||||
|
||||
## 受け入れ条件と未決事項
|
||||
|
||||
rename後もitem identity維持、権限失効で次要求から不可視、二重配送で重複なし、同期停止時の未送信保護、個人設定のDomain越境拒否を必須にします。共通itemを独立Object kindにするか拡張表に留めるかはprototypeで決め、DB migrationはその後です。
|
||||
@@ -0,0 +1,53 @@
|
||||
# 共通outbox:購読・移行・復旧契約
|
||||
|
||||
更新日:2026-09-25。単一インスタンスのSQLiteと既存イベントキューでの初期実装です。タスクの期限日/計画日通知は[正本と同時に作る予約](task-reminders.md)から配信します。outbox購読による汎用変更通知、分散配送、outboxの自動削除は未実装です。
|
||||
|
||||
## 責務を分ける
|
||||
|
||||
| 要素 | 役割 |
|
||||
| --- | --- |
|
||||
| `activity_outbox` | 正本変更と同時に保存する小さなイベント。Domain-local sequence、UUID、型、actor、対象、一意キー |
|
||||
| `activity_outbox_heads` | Domain・イベント型ごとの最新sequence。INSERT triggerで同じtransaction内に更新 |
|
||||
| `activity_outbox_checkpoints` | consumer・Domainごとの完了位置。成功後にのみ単調に進める |
|
||||
| `event_jobs` | 実際の実行・再試行・優先度・ログ・キャンセル。outboxの記録とは別 |
|
||||
|
||||
`status`、`attempts`、`next_attempt_ms` 等のoutbox旧列は互換のため残しますが、consumer配信の完了や再試行判定には使いません。旧 `processed` 行も、新規consumerにとっては未処理になり得ます。`CompleteActivityOutboxThrough` は指定したconsumerのcheckpointのみ更新します。
|
||||
|
||||
## 購読と負荷
|
||||
|
||||
`ActivitySubscription` のconsumer IDとevent type集合は信頼するworkerコードで定義します。HTTP入力から任意の購読を生成しません。現在のCity購読は `page.created`、`revision.created`、`path.renamed`、`path.unlinked`、`object.deleted` です。タスク変更や無関係の拡張イベントだけではCityジョブを作りません。
|
||||
|
||||
未処理Domainの発見はheadsとcheckpointの比較で行い、全イベント履歴を毎回検索しません。1回最大100 Domain。イベント取得は型ごとにsequence索引から上限件数を取り、その結果をマージします。1回の最終結果は最大500件、型は最大16種類です。無関係のイベントが大量に入っても、対象イベントの手前を何ページも読み飛ばしません。
|
||||
|
||||
同じconsumer IDのまま購読型を増やすと、checkpointより古い新購読型のイベントを取り逃がします。**購読集合の変更時は新しいconsumer IDを使う**ことを契約とします(例:`notifications.tasks.v2`)。再生の開始位置・過去通知の抑止を別途指定します。
|
||||
|
||||
Cityは取得した対象イベントの最終sequenceまで、再構成成功後にcheckpointを進めます。並行して追加された後続イベントは次回に残ります。再構成後・checkpoint保存前の停止は再実行になりますが、既存の冪等な再構成で回復します。途中で失敗したbatchの一部だけを成功扱いにしてはいけません。
|
||||
|
||||
## タスクの直接接続と既存データ
|
||||
|
||||
タスクhead・版・専用ジャーナル・共通outbox・headsを同じtransactionで保存します。どこか一つが失敗したらDBの変更は全体をrollbackします。CASファイルの孤立可能性は従来どおりで、未commitのheadには現れません。
|
||||
|
||||
タスクの一意キーはDomainにスコープされた `organizer:{kind}:{uuid}:{version}`。payloadは版番号と変更時刻のみです。作成の再送、旧記録の再生、ジョブ再試行で二重記録しません。
|
||||
|
||||
`organizer_activity_bridge` は専用ジャーナルの移行位置です。`task.activity.publish` は1回100件、3秒timeout、既定60秒間隔・priority -5。処理したイベントと移行位置を同時commitします。失敗時は位置を進めません。対象が欠損して種類を判定できない場合はエラー停止し、黙ってスキップしません。タスクの物理削除導入時にはtombstoneを追加する必要があります。
|
||||
|
||||
この移行ジョブは拡張のユーザー操作を実行するものではなく、保存済み変更記録の内部保全です。拡張の無効化とは別に、イベント定義のenabledをOFFにできます。既存enabled・intervalの設定は起動時に保持します。`/_/api/v1/event/run` からも既存の管理権限で手動実行できます。ログは件数のみで、個人タスクのタイトルや本文は出しません。
|
||||
|
||||
## アップグレードと保全
|
||||
|
||||
初回のみ旧outboxを集計してheadsを作成します。この移行と完了マーカーはtransaction内で行い、途中失敗は再実行できます。次回以降の起動で履歴全件を再集計しません。既存checkpointと旧processed行は保持します。
|
||||
|
||||
新しいsequenceの採番は保持されたheadsの最大値から行います。将来の履歴整理でsequenceが巻き戻らないための対策ですが、**outboxの自動削除機能を提供するものではありません**。削除可能範囲には全必須consumerの完了確認に加えて、一意キーの再送抑止用tombstoneが必要です。heads・checkpoint・移行位置・正本DBをまとめてバックアップします。
|
||||
|
||||
## 残タスク
|
||||
|
||||
- [x] タスクの期限日/計画日通知:正本transactionで予約を更新し、配信時に現在権限・版を再検査。旧outboxイベントから予約を復活させない。
|
||||
- [ ] 汎用の変更通知consumerと購読設定。
|
||||
- [ ] consumer別の未処理/失敗表示、再生操作、購読変更時のbootstrap。
|
||||
- [ ] 多数の失敗Domainがある場合の公平なdispatch、consumer別backoff/dead-letter。
|
||||
- [ ] Outbox保持ポリシー:必須購読者の進捗、sequenceと一意キーの保全、consumer廃止手続き。
|
||||
- [ ] 分散lease/fencing。現時点でHA時のexactly-onceを保証しない。
|
||||
|
||||
## テスト
|
||||
|
||||
購読者間の独立、型での絞り込み、ページング、旧processed行の取得、初回移行/再起動、transaction rollback、無関係イベント1200件の中の対象取得、sequence巻き戻り防止を検証します。サーバー側では、タスク変更でCityジョブが作られないこと、ページ変更では作られること、タスク保存全体のrollback、移行の再開/重複抑止、管理者の停止・間隔設定保持を検証します。運用DB・外部カレンダーは使用しません。
|
||||
@@ -0,0 +1,36 @@
|
||||
# 1. 設計思想と責務の分離
|
||||
|
||||
状態:基盤は実装済み。拡張への適用は継続中。
|
||||
|
||||
## 知識の住所と実体を分ける
|
||||
|
||||
PagesWikiは、人には階層と街の案内図を提供し、内部では同じ知識を複数の場所から参照できるシステムです。ファイルシステムのコピーをWikiの基本単位にはしません。
|
||||
|
||||
| 層 | 責務 | 他の層と混同しないもの |
|
||||
| --- | --- | --- |
|
||||
| Campus | ドメイン群の管理・配置・管理方針 | 記事本文の自動複製 |
|
||||
| Domain | FQDN、Path名前空間、設定、権限評価 | インスタンスそのもの |
|
||||
| Quartier / Street / Spot | 知識の整理・案内・管理範囲 | Pageの永続ID |
|
||||
| Page | 言語や表示形式に依存しない知識の実体 | Path、ファイル名 |
|
||||
| Revision | Pageの不変な版、言語、内容参照 | 最新版を指す可変名 |
|
||||
| Document | SHA-256で識別する不変バイト列 | 認可情報 |
|
||||
| Projection | 表示・編集・印刷・検索等の表現 | 別のPage正本 |
|
||||
|
||||
## 守る不変条件
|
||||
|
||||
- `(domain_uuid, path)` が意味上の住所。名前変更してもPage UUIDを変えない。
|
||||
- Page UUID、Revision UUID、Document SHA-256は別物。ハッシュを知っていても読めるとは限らない。
|
||||
- 同じPageを複数箇所で紹介しても、Revision履歴を複製しない。
|
||||
- 言語はRevisionの属性。通常のPathに `/ja/` と `/en/` を強制しない。
|
||||
- 閲覧・編集・公開・管理・委譲は別の許可。ログイン成功だけで本文権限を与えない。
|
||||
- コメント、既読、評価、タスク状態はHTMLへ隠しフィールドとして埋め込まず、型付きメタデータとして持つ。
|
||||
|
||||
## 正本・派生データ・外部コピー
|
||||
|
||||
正本の更新と重要なメタデータはトランザクションで確定させます。検索索引、サムネイル、ランキング、通知は派生データとして再構築可能にします。外部メールやRSSの取り込みでは、外部の原本とWikiへの明示的なコピーを区別します。
|
||||
|
||||
現在、全書き込みが共通outboxへ接続されているわけではありません。「イベント化すべき」という設計契約を実装済みと読み替えてはいけません。
|
||||
|
||||
## 変更の受け入れ基準
|
||||
|
||||
機能ごとに、名前変更、権限失効、再試行、停止・再起動、大きな入力、外部障害を試験します。上限超過時に無制限処理や無認可表示へ切り替えません。通常の閲覧・保存を重いバックグラウンド処理より優先します。
|
||||
@@ -0,0 +1,53 @@
|
||||
# 6. 公開・承認・共有・匿名ナビゲーション
|
||||
|
||||
状態:明示的なRevision公開、Street/Spotの自動公開、匿名ナビゲーションは実装済み。承認者Inboxは受信者単位の保存・既読APIまで実装済みで、承認要求の生成・決裁UI・配送ワーカーはTODO。共有URL管理もTODO。
|
||||
|
||||
## 三つの異なるもの
|
||||
|
||||
1. 公開可能な上限:上位管理者が許可するaudience。下位は狭められるが広げられない。
|
||||
2. 実際の公開:特定Revisionの明示承認、または確認済みの自動公開ルール。
|
||||
3. 認証後のread/write:ユーザー・グループの権限。公開設定を変更しただけで編集者を増やさない。
|
||||
|
||||
`public` という上限を保存しただけで配下全部を公開したと扱いません。
|
||||
|
||||
## 現行の自動公開
|
||||
|
||||
| モード | 動作 |
|
||||
| --- | --- |
|
||||
| inherit | この階層ではルールを追加せず上位に従う |
|
||||
| required | この範囲と配下は手動公開のみ。下位の自動公開で解除できない |
|
||||
| automatic | Street/Spotの現在と将来の対象Page、および各言語の現在headを公開 |
|
||||
|
||||
Domain・Quartierもrequiredの上限制約を設定できます。automaticは有効な公開audienceを必要とし、影響プレビューと明示確認、policy/topology/versionの一致で有効化します。空の範囲にも設定できるため、今後作成する記事も対象になり得ます。
|
||||
|
||||
固定したPath境界のrename、設定した本人の権限失効、Domain/Campus無効化は公開を継続する根拠になりません。境界内への移動も対象になり得るため、importやメールコピーでは公開先の確認が重要です。別名、制限された子範囲、予約領域は現行の除外対象です。
|
||||
|
||||
自動公開の停止と、別途承認したRevisionの撤回は同じ操作ではありません。完全に非公開へ戻す場合はaudienceも制限します。新しい導入・migrationで自動公開を有効にしません。
|
||||
|
||||
影響確認は現在512 Path、ルール列挙128行、公開ナビゲーション20,000件/4 MiB等の上限があります。大きい範囲は分割・ページ送り付き確認の実装が必要です。上限超過を認可成功として扱いません。
|
||||
|
||||
## 匿名表示と共有リンク
|
||||
|
||||
公開Pageは読めるchildren・tree・City・パンくずへ移動できます。構造上必要な仮想親フォルダは、非公開の親本文やタイトルを見せる許可ではありません。通常・詳細・アイコン表示を共通化します。公開画面にダウンロード操作を強調する必要はありません。
|
||||
|
||||
ユーザー領域 `/u/{username}` はCityの通常公開から除外したまま、専用の公開設定を `/u/{username}/_/edit` に実装しています。プロフィール情報、プロフィール画像、ユーザーWikiのroot、配下の既定値をそれぞれ `private` / `domain` / `public` から選べます。配下の個別Pathは既定値より狭い範囲に限って上書きでき、その指定はsubtreeにも効きます。Domainの公開上限がpublicで、有効なCampus/Domainかつ認可がenforcingの場合だけpublicを保存・配信できます。上限を閉じれば次の要求から匿名配信も閉じます。
|
||||
|
||||
これは所有者が明示的に有効化する現在headの自動公開です。通常Pageの固定Revision承認を流用せず、将来の編集も同じ範囲で公開されます。匿名children・tree・browserは当該ユーザー領域だけの公開snapshotを使用し、グローバル匿名treeへ `/u/` を混ぜません。別名を持つObject、UUID/Revision経由、予約 `/_/` 経路では迂回できません。詳細は [user-space visibility contract](../user-space-publication.md) を参照してください。
|
||||
|
||||
将来のshare URLは期限・範囲・目的を限定した単一ページ表示が基本です。ログインセッションや公開ナビゲーション全体への昇格はさせません。Macaroonを含む委譲方式は設計段階で、予約 `/s/` があることは実装済みを意味しません。
|
||||
|
||||
## 承認Inboxの設計と実装状況
|
||||
|
||||
承認要求は対象Revision、依存物、scope、policy version、要求者と期限を固定します。変更された本文に旧承認を流用しません。承認者の現在の権限を決裁時に再検査し、outboxから通知Inboxへ重複排除して配送します。
|
||||
|
||||
状態はdraft → requested → approved / rejected / expired / supersededを案とします。取り消し・公開撤回は別監査イベントです。上位の承認必須設定を下位が解除できないこと、自動公開との優先順位、本人承認の可否を実装前に確定します。
|
||||
|
||||
共通通知Inboxの第一段階として、`notification_inbox`にDomain・受信者・イベント・種別を保存し、同じ組合せを重複排除します。`GET /_/api/v1/notifications` は現在のPrincipalに限定して `unread`、`limit`、`before` のkeyset取得を行い、`POST/PATCH /_/api/v1/notifications/read` は同じDomain・受信者の通知だけを既読化します。通知は権限や承認を付与せず、本文や秘密を保存しません。承認要求からの生成と再表示時の権限再検査は次段階です。
|
||||
|
||||
承認要求の対象(Path/Object/RevisionのハッシュとJSON)、policy version、generation、期限、要求者を`publication_requests`に固定保存し、決裁履歴を`publication_decisions`へ追記します。期限付きpending要求はスケジューラが小さなbatchでexpiredへ遷移させます。レビュアーの現在権限を再検査する決裁APIとInbox UIは、まだ公開していません。
|
||||
|
||||
認証済みのDomain管理者向けに、`POST /_/api/v1/publication/requests`でboundedな対象manifestを登録できます。idempotency keyで再送をまとめ、指定されたレビュアーがDomain管理権限を持つ場合だけInbox通知を作成します。`POST /_/api/v1/publication/requests/{uuid}/decisions`はDomainとgenerationを再検査し、承認・拒否をCASで一度だけ適用します。上位方針の継承、定足数、対象Revisionの現在性検査は、公開運用へ進む前の残タスクです。
|
||||
|
||||
## TODO
|
||||
|
||||
依存Assetと別名の完全な影響レビュー、広域の移動・統合時のfence、ルールGC、承認者・定足数・Inbox、署名付きpolicy配信、share失効管理。RSS読者や外部SNSが既に取得したコピーを遠隔削除できるとは約束しません。
|
||||
@@ -0,0 +1,32 @@
|
||||
# 料理レシピ管理(RECIPE)
|
||||
|
||||
状態:設計TODO。通常のWiki文書を置き換えず、Document/Revisionを正本として
|
||||
レシピ用の構造化メタデータと表示Projectionを重ねる。
|
||||
|
||||
## 基本モデル
|
||||
|
||||
- レシピUUID、タイトル、概要、作者、出典、タグ、料理ジャンル、公開範囲。
|
||||
- 材料は名称・数量・単位・任意の代替材料・アレルゲンを持つ。
|
||||
- 手順は順序、本文、所要時間、温度、器具、画像Asset参照を持つ。
|
||||
- 分量(何人分)、準備時間、調理時間、合計時間、難易度を分離する。
|
||||
- Revisionと同じく変更履歴・差分・権限・監査を持ち、公開承認を迂回しない。
|
||||
|
||||
## 表示と編集
|
||||
|
||||
材料の人数倍・縮小、単位変換、買い物リスト化は表示時の派生値とし、正本の
|
||||
数量を破壊しない。Markdown/HTML本文からの移行はpreviewと警告付きで行い、
|
||||
未知の単位や曖昧な数量は文字列として保持する。画像・動画・PDFのAssetは
|
||||
既存のMIME/権限処理を再利用し、本文への埋め込みは安全なProjectionを通す。
|
||||
|
||||
## 連携と拡張
|
||||
|
||||
JSON-LD Recipe、印刷用カード、買い物リスト、カテゴリ・材料検索を候補とする。
|
||||
外部レシピサイトやメールからの取り込みは、出典URL・取得時刻・著作権表示を
|
||||
保持し、無断公開や大量取得を行わない。栄養計算は外部データの版と不確実性を
|
||||
表示し、医療上の助言とは扱わない。
|
||||
|
||||
## 受け入れ条件
|
||||
|
||||
単位変換で丸め誤差を明示すること、権限フィルタ後の検索結果だけを表示すること、
|
||||
Revision競合・削除・Asset失効を再現できるfixtureを用意すること、共有時に作者・
|
||||
出典・公開範囲を再確認することを条件とする。
|
||||
@@ -0,0 +1,63 @@
|
||||
# 20. 実装順序と受け入れ条件
|
||||
|
||||
状態:2026-09-19再整理。旧Phase番号は原ロードマップとの対応用に残し、実装は依存関係とリスク順に進めます。
|
||||
|
||||
## 優先順
|
||||
|
||||
2026-09-27追記:`organizer.tasks 0.11.1`で[既定タスクリスト名の変更](task-dav-default-list-name.md)を実装し、12:51 JSTに[本番両インスタンスへ反映](../../operations/deployments/2026-09-27-default-task-list-name.md)。PROPPATCH 405を解消し、利用者・domain別の表示名を保存、全探索結果へ反映する。実機再試行は確認待ち。色・アイコン・通常プロジェクトのPROPPATCHは別件。
|
||||
|
||||
2026-09-27追記:`organizer.tasks 0.11.0`の[タスク所属統一と上書き同期](task-dav-project-unification.md)を実装し、12:18 JSTに[本番両インスタンスへ反映](../../operations/deployments/2026-09-27-task-unification.md)。全Webプロジェクトを個別CalDAVリストとして公開し、既定リストはプロジェクトなしに限定。無条件PUT/DELETEはトークン別設定なしで受理し、版履歴を保持する。実機再同期は確認待ち。次の優先タスクは競合候補の保存、Inbox通知、上書き前/受信版の比較・採否選択(同文書のTODO)。反映時に観測したスケジューラclaimの一時的DBロックとディスク容量整理も運用記録へ残した。
|
||||
|
||||
2026-09-25追記:個人タスクCalDAV `0.8.0`を実装・隔離試験済み(2026-09-26 00:24 JST本番反映済み)。専用資格情報UI、VTODO、CLI双方向同期。制約と次段階は[タスクCalDAV](task-caldav.md)に整理。
|
||||
|
||||
2026-09-26追記:[予定・タスク共通CalDAV](caldav-common.md)を実装。共通principal/scope付き資格情報/VEVENT・VTODO探索・CLI同期/両画面の共通設定UI。chroncal実行試験とWeb回帰を実施。後続はTZID/VTIMEZONE等のlossless書込、sync-token、資格情報ごとのcalendar制限。反映状況は運用記録を参照。
|
||||
|
||||
2026-09-27追記:[OneTaskのOPTIONS判定互換モード](caldav-onetask-compatibility.md)を資格情報単位で実装、10:01 JSTに本番反映。OneTask実機の全操作確認は残件。通常モードは維持し、未対応データを黙って変換しない。
|
||||
|
||||
2026-09-27追記:[VTODOの複数タスクリスト](caldav-task-lists.md)を`organizer.tasks 0.10.0`として実装。OneTaskのMKCALENDAR失敗に対応し、リストをWebプロジェクトへ対応付ける。隔離試験では新規作成、リスト別CRUD、権限分離、索引復旧、Web所属変更、chroncalの名前付きリスト同期まで確認。後続:OneTask実機の再同期、PROPPATCH/リストDELETE、時刻付き期限・繰り返し・アラーム、差分同期。反映状況は[運用記録](../../operations/deployments/2026-09-27-task-lists.md)を参照。
|
||||
|
||||
| 優先 | 作業単位 | 前提 | 完了条件 |
|
||||
| --- | --- | --- | --- |
|
||||
| P0-1 | 認可transaction fence | typed target、現行認証 | revokeと同時更新の拒否、全変更経路の棚卸し |
|
||||
| P0-2 | 公開影響と構造変更 | inert HTML、現行公開 | alias/依存/移動/統合で公開を無断拡張しない |
|
||||
| P0-3 | identity lifecycle | 現行Principal/group | 外部連結、メール所有、最後の管理者保護 |
|
||||
| P1-1 | 共通outbox | actor・Domain sequence | 正本との原子性、二重配送、checkpoint復旧 |
|
||||
| P1-2 | City/directory局所化 | 所属モデル、索引 | 部分取得、手動編集保持、boundedなreconcile |
|
||||
| P1-3 | 検索・decode・大容量 | 現行上限と測定 | current-only検索、隔離、stream、cancel |
|
||||
| P2-1 | 通知と承認Inbox | P0、outbox | 現在権限で再表示・決裁・失効 |
|
||||
| P2-2 | HTMLパーツ | round-trip fixture | macro/asset/未知HTMLを壊さない |
|
||||
| P2-3 | local task | extension契約、原子的ジャーナル | 個人タスク/プロジェクト・Inbox通知・個人local時間枠・永続化Pomodoro・Todayの見積/時間枠/集中集約を実装済み。次は計画持ち越し、日課、共有 |
|
||||
| P2-4 | RSS読取・Wiki保存 | connector共通部 | FreshRSS fixtureと安全なcopy |
|
||||
| P2-6 | 料理レシピ管理 | Document/Asset、検索、権限 | 材料・分量・手順・調理時間・人数・タグを構造化し、単位変換と安全な共有を検証 |
|
||||
| P3 | calendar/contact/mail | import/secret/競合契約 | read-only同期、明示copy、障害復旧 |
|
||||
| P4 | 外部書込・DAV提供・HA | 運用選択、試験環境 | 双方向競合、fencing、復旧訓練 |
|
||||
| P2-5 | CSV表macro・ODS境界 | projection/asset権限 | RFC4180 fixture、行列上限、Revision競合、safe fallback |
|
||||
| P3-2 | Slide projection/editor | adapter manifest、CSP | Reveal互換preview、CSS-only編集、HedgeDoc/Slidev隔離 |
|
||||
| P3-3 | IPAM・DNS・資産管理 | typed entity、承認Inbox、outbox | 重複検査、dry-run/apply監査、外部同期差分、soft delete |
|
||||
|
||||
P2以降の順序は利用価値で入れ替え可能ですが、P0の該当安全条件と共通outboxを省略しません。read-only prototypeは、本番への外部送信や公開を伴わない隔離fixtureで並行検証できます。
|
||||
|
||||
## 既に使える機能と残り
|
||||
|
||||
2026-09-25追加(0.7.0、2026-09-25 07:07 JST本番反映済み):[日別計画・持ち越し・親子グループ・Wikiメモ](task-daily-notes.md)。期限を変えない再割当て、親子cursor・補足親、初期Wiki本文とタスク紐づけの原子的作成を実装。日別キャパシティ・一括計画・共有は残件。
|
||||
|
||||
2026-09-25追記(同日05:59 JSTに本番反映済み):タスクのインライン編集、2階層サブタスク、月別日割り工程表、ホーム/Todayモーダル、Inboxのアクティブ通知、スマホカレンダーUIを実装・fixture検証。[タスク一覧の契約](task-inline-schedule.md)、[通知とWeb Pushの契約](active-notifications.md)、[スマホカレンダー](calendar-mobile.md)に上限・安全条件・実機確認の残件を記載。
|
||||
|
||||
- アドレス・不変Revision・Document・Asset:基本実装あり。保持・大容量・外部backendが残り。
|
||||
- Campus/Domain・manifest:基本実装あり。反映ACK、PSK権限同期、DRが残り。
|
||||
- City Map:実装あり。局所取得、reconcile所有権、生成品質が残り。
|
||||
- 認証・グループ:実装あり。全endpoint監査・identity lifecycleが残り。
|
||||
- 匿名公開・children/tree/City:実装あり。大規模影響確認、share、承認Inboxが残り。
|
||||
- ブログ・日記・公開射影・本文RSS:実装あり。遠隔射影、コメント、tDiary等が残り。
|
||||
- オーガナイザー:カレンダーと限定CalDAV、個人タスク/プロジェクト・個別ONのInbox通知、個人local時間枠と永続化Pomodoroあり。[タスク実装契約](tasks-implementation.md)、[時間枠とPomodoro](task-planning-focus.md)参照。一般のカレンダー予定通知・共有・VTODO、RSS購読・IMAPは未実装。
|
||||
- 全面WYSIWYG、native app起動、第三者runtime、vim.wasm改善:判断待ちまたは保留。
|
||||
|
||||
## 共通のDone
|
||||
|
||||
仕様状態、schema/migration、rollbackまたはforward-fix手順、認可拒否、権限失効、version競合、重複再送、payload/行数/時間/並列上限、cancel、i18n、アクセシビリティ、運用メトリクスをそろえます。
|
||||
|
||||
Go全体テストと必要なbrowser fixtureを実施し、実装済み表示とdeployment記録を別々に更新します。外部APIはmockのみでlive接続成功と報告しません。
|
||||
|
||||
## 設計タスク一覧
|
||||
|
||||
次章のADR-O1〜O8を採用判断の単位とします。TASK、TICKET、CAL、CARD、DAV、RSS、MAIL、EDITOR、CSV、SLIDE、IPAM、DNS、INV、RECIPEの各IDは詳細章のTODOと対応します。実装開始時に担当・受け入れfixture・依存issue・見直し日を付けます。規模や納期を根拠なしに確約しません。
|
||||
@@ -0,0 +1,40 @@
|
||||
# 9. イベント・キュー・リソース監視
|
||||
|
||||
状態:永続ジョブ、定期実行、再試行・ログ、背景リソース監視あり。共通outboxの
|
||||
永続 envelope(Domain sequence、idempotency、retry state、pending取得)は実装済み。
|
||||
正本変更との同一transaction接続はPage/Revision/Path/Objectの初期経路で実装済み。
|
||||
2026-09-25:consumerごとのcheckpointとイベント型別取得、タスク/プロジェクトの同一transaction接続、個別ONのタスク期限日/計画日Inbox通知も実装済み。汎用変更通知の配送、outbox保持ポリシー、分散leaseはTODO。
|
||||
|
||||
イベントログは生ログとトレンド用bucketを分離する。`event_log_policies`で
|
||||
イベント種別ごとの保持時間、集約開始時間、bucket幅、最大生ログ件数を指定し、
|
||||
`event_log_buckets`には件数と最初・最後の時刻だけを保持する。生ログの削除は
|
||||
稼働中に安全な条件付きDELETEで行い、workerが書き込み中にテーブルをDROPしない。
|
||||
物理partitionの導入時もrename→新規作成→切替を原子的に行う。
|
||||
|
||||
## 責務
|
||||
|
||||
`/_/api/v1/event/` は実行する処理とタイミング、`/_/api/v1/queue/` は実行要求と状態を扱います。予定、実行中、結果、ログ、キュー設定を区別します。イベントは安全な型付き処理であり、ユーザー入力をそのままshell commandへ変換しません。
|
||||
|
||||
## 前景を優先する
|
||||
|
||||
サムネイル・PDF・archive解析等は背景処理へ送ります。ジョブの同時数、入力・出力、時間、再試行を制限し、通常要求の活動を見ながらclaimします。長い接続だけで背景処理が永久停止しないよう、最低限の進行枠も必要です。
|
||||
|
||||
今後はジョブ件数だけでなくCPU/メモリ重みを管理します。native decoderのhard memory limit、プロセス分離、cancel時の子プロセス停止は別の安全条件です。
|
||||
|
||||
## outboxの実装と残り
|
||||
|
||||
正本変更と `activity_outbox` を同一transactionで記録します。Domain sequence、event UUID、型と版、actor、対象UUID、idempotency keyを含めます。本文や秘密をすべて複写しません。[購読・移行・復旧契約](outbox-delivery.md)を参照してください。
|
||||
|
||||
配送はat-least-onceを前提に、consumerごとのcheckpointと重複排除を使います。処理成功後にcheckpointを進め、途中停止から再試行します。City、通知、検索、集計が個別のHTTP handler callbackへ散らばらないようにします。既存の個別journalがあるだけではこの配送契約の完成ではありません。
|
||||
|
||||
## 運用画面とリソース
|
||||
|
||||
実行モニタはリソースグラフ4列と現在実行中のジョブ。設定は歯車、手動更新はアイコン。完了ジョブは履歴・ログへ統合し、ログは選択時に読みます。履歴期間の既定は1時間で選択を保持します。
|
||||
|
||||
現在値の表示更新、グラフの表示更新、背景の保存間隔は異なる設定です。1秒表示にしても1秒ごとの永続化や精密な瞬間使用率を意味しません。ブラウザを閉じても保存イベントは続きます。以前の「60秒既定」という原資料だけを最新設定の根拠にしません。
|
||||
|
||||
I/Oはプロセスの累積read/write bytes差分を時間で割った値です。再起動・欠測・counter減少は0に補間しません。ホスト全体のIOPS、latency、コンテナ合算と混同しません。
|
||||
|
||||
## TODOと検証
|
||||
|
||||
重み付き予算、dead-letterと安全な再投入、分散lease/fencing、outbox、SNMPv3読取collector。停止中の欠測、長いViewer接続、重いPDF連発、ジョブ再送、log大量化でも閲覧を優先できることを測定します。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 22. 原資料との対応と外部仕様
|
||||
|
||||
更新日:2026-09-19。原資料はリポジトリの `docs/design/` に残します。以下はWiki上のファイル配信URLではなく、ソース資料との対応表です。
|
||||
|
||||
## 原資料の分類
|
||||
|
||||
| 本書の章 | 原資料ファイル |
|
||||
| --- | --- |
|
||||
| 設計思想 | `arch.md`、`access-model.md`、`platform-extension-architecture.md` |
|
||||
| アドレス・保存 | `address-model.md`、`uri.md`、`asset-model.md`、`data-cli.md`、`revision-language-model.md` |
|
||||
| Campus・Domain | `campus-domain-model.md`、`domain-namespace-federation.md`、`federation-manifest-integrity.md` |
|
||||
| City | `knowledge-city-model.md`、`city-immersive-map.md`、`city-organization-ui.md`、`city-read-integrity.md`、`city-review-and-reconciliation.md`、`city-worker-navigation.md` |
|
||||
| 認証・権限 | `auth.md`、`auth-backend.md`、`authorization-groups.md`、`browser-request-security.md`、`campus-admin-revocation.md`、`object-authority-scope.md`、`oidc-verification.md`、`smtp-magic-link-hardening.md` |
|
||||
| 公開・共有 | `locality-publication-ownership.md`、`locality-access-publication.md`、`automatic-publication.md`、`publication-approval-inbox.md`、`public-navigation.md`、`social-link-cards.md` |
|
||||
| Viewer・Editor | `projection-adapters.md`、`html-projection-trust.md`、`projection-metadata-cache.md`、`home-bookmark-sections-vim.md` |
|
||||
| ナビゲーション・import | `navigation-home-sidebar.md`、`configuration-panels.md`、`search-results.md`、`archive-import.md`、`path-mutation-integrity.md` |
|
||||
| Scheduler・拡張 | `event-scheduler.md`、`system-extensions.md`、`platform-extension-architecture.md` |
|
||||
| 日記・ブログ | `diary-blog-plugins.md` |
|
||||
| 新規構想 | `organizer-and-editing-ideas.md`、本書第12〜17章 |
|
||||
| 保全・性能 | `object-list-pagination.md`、`revision-listing.md`、`zombie-gc-integrity.md`、`implementation-status.md` |
|
||||
| 多言語 | `i18n-delivery.md`、`revision-language-model.md` |
|
||||
| 実装計画・履歴 | `implementation-roadmap.md`、`implementation-status.md`、`hardening-execution-2026-09.md` |
|
||||
|
||||
初期draft、詳細契約、実装状況、実行履歴は文書の用途が違います。仕様の全項目を実装済みと判定するためにdraftの文体を使わず、コードとテストの実装単位で確認します。
|
||||
|
||||
## 今回の照合対象の実装
|
||||
|
||||
`internal/store/automatic_publication.go`、`locality_publication.go`、`navigation.go`、`periodicals.go`、`public_periodicals.go`、`groups_inheritance.go`、`city_reference.go`、`revision_store.go`、`internal/server/periodical*.go`、`public_periodical*.go`、`internal/extensions/registry.go`、`data/pageswiki-cli` 等を、状態の混同が起きやすい箇所として確認しました。これは全実装の安全性監査を完了したという意味ではありません。
|
||||
|
||||
## 公式仕様と連携資料
|
||||
|
||||
以下は2026-09-19に確認した設計根拠です。プロトコル対応を実装する際は更新RFC・errata・選定clientの版も固定します。
|
||||
|
||||
- [RFC 5545 — iCalendar](https://www.rfc-editor.org/rfc/rfc5545)
|
||||
- [RFC 4791 — CalDAV](https://www.rfc-editor.org/rfc/rfc4791)
|
||||
- [RFC 6350 — vCard](https://www.rfc-editor.org/rfc/rfc6350)
|
||||
- [RFC 6352 — CardDAV](https://www.rfc-editor.org/rfc/rfc6352)
|
||||
- [RFC 6578 — WebDAV Collection Synchronization](https://www.rfc-editor.org/rfc/rfc6578)
|
||||
- [RFC 9051 — IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051)
|
||||
- [RFC 4287 — Atom](https://www.rfc-editor.org/rfc/rfc4287)
|
||||
- [FreshRSS — Google Reader compatible API](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html)
|
||||
- [newsboat 2.42 — FreshRSS integration](https://newsboat.org/releases/2.42/docs/newsboat.html#_freshrss)
|
||||
|
||||
これらの仕様が存在することと、PagesWikiがその機能を提供することは別です。本書のモデル、MVP順序、table/API案はPagesWiki向けの設計提案として区別します。
|
||||
@@ -0,0 +1,183 @@
|
||||
# 個人タスクのCalDAV/CLI連携
|
||||
|
||||
2026-09-27追記:0.11.0の[所属統一と上書き同期](task-dav-project-unification.md)で、全プロジェクトのリスト化と無条件PUT/DELETEを実装し、12:18 JSTに本番両インスタンスへ反映。以下の条件ヘッダ必須という説明は旧版の契約。明示されたETagの条件は引き続き尊重する。
|
||||
|
||||
2026-09-27追記:`organizer.tasks 0.10.0`の[複数タスクリスト](caldav-task-lists.md)で、OneTaskのMKCALENDARとプロジェクト別同期に対応。以下の固定1コレクション・UIDのdomain/owner一意性は初版の説明。名前付きリストではリスト単位の一意性となり、従来URIは既定リストとして維持する。
|
||||
|
||||
更新:2026-09-26。`organizer.tasks 0.9.0`。01:33 JSTにapp/app2へ[共通CalDAVの本番反映](../../operations/deployments/2026-09-26-common-caldav.md)完了。以前の経緯は[chroncal互換性修正](../../operations/deployments/2026-09-26-chroncal-compatibility.md)、初回0.8.0の反映・バックアップは[初回デプロイ記録](../../operations/deployments/2026-09-26-task-caldav.md)を参照。
|
||||
|
||||
## 1. 目的と境界
|
||||
|
||||
2026-09-26追記:`organizer.tasks 0.9.0`で[予定・タスク共通CalDAV](caldav-common.md)を追加。旧タスク専用URLと資格情報は維持する。以下のタスク専用資格情報の制約は旧資格情報/`tasks` scopeに適用し、予定を扱うには新規に`calendar`または`all`を選んで発行する。
|
||||
|
||||
0.8.1互換性修正(2026-09-26):chroncal 0.10.0の探索・初回同期・作成・完了・Web変更取得・削除を隔離fixtureで検証。末尾slashを除くクライアント向けにhome/collectionのslashなしURIも直接処理し、301によるPROPFIND→GET変換を回避する。返却hrefはslash付きのcanonical形式を維持する。
|
||||
|
||||
Webの個人タスクをサードパーティCLIでも扱う。正本を別に増やすのではなく、既存のTaskRecord・版・変更journal・通知予約を共通で使用する。カレンダー予定のVEVENTとは別のVTODOコレクションを提供する。
|
||||
|
||||
- ドメイン×利用者ごとに一つの固定コレクション。未完了・完了・取りやめを含む。アーカイブは除外する。
|
||||
- プロジェクト自体はVTODO化しない。サブタスクは個別のVTODOとして並ぶ。既存のプロジェクト・親子・Wiki関連・取り組む日・工程終了・見積もりはCLIから消されないが、初版ではCalDAV編集項目ではない。
|
||||
- DESCRIPTIONはタスクのプレーンテキストメモ。関連Wikiドキュメントの本文を取得・公開しない。
|
||||
- 匿名公開、共有タスク、アサイン、外部カレンダー取得は行わない。
|
||||
- `organizer.tasks`無効化時はエンドポイント全体を404にする。`organizer.calendar`の有効化は不要。
|
||||
|
||||
RFC 5545 VTODOの**限定プロファイル**。フルCalDAV適合を意味する`calendar-access`は広告せず、`DAV: 1`と対応するREPORT・VTODO component-setを示す。
|
||||
|
||||
## 2. URI・認証
|
||||
|
||||
| 用途 | URI |
|
||||
| --- | --- |
|
||||
| タスク専用home/principal discovery | `/_/api/v1/caldav/tasks/` |
|
||||
| 固定コレクション | `/_/api/v1/caldav/tasks/default/` |
|
||||
| VTODOリソース | `/_/api/v1/caldav/tasks/default/{name}.ics` |
|
||||
| 専用パスワード一覧/発行 | `GET/POST /_/api/v1/extension/organizer.tasks/dav-credentials` |
|
||||
| 専用パスワード失効 | `DELETE /_/api/v1/extension/organizer.tasks/dav-credentials/{id}` |
|
||||
|
||||
タスク画面の上部ツールバーの **⇄(CalDAV / CLI連携)** で発行・失効する。日本語/英語とテーマに追従する。名前、読み取り専用/読み書き、有効期間を指定。UIは30・90・365日、APIは1〜365日、既定90日。利用者・ドメインごとに有効な資格情報を最大20件に制限する。
|
||||
|
||||
HTTP Basicのユーザー名には発行された**認証情報ID**、パスワードには発行されたランダム秘密値を使用する。普段のログイン名やログインパスワードではない。秘密値は発行時のみ表示し、画面を閉じたらDOMから破棄する。DBには256-bit乱数のSHA-256のみを保存する。専用資格情報では通常のタスクJSON API、認証管理API、Wiki、予定カレンダーにはアクセスできない。
|
||||
|
||||
既存のBearerセッションでもこのDAVにアクセスできるが、CLIの常用は専用資格情報を使う。通常セッションで認証した管理APIのみが新規資格情報を発行できる。失効・有効期限・利用者状態・ドメインmembershipを毎回確認。書き込みでは資格情報の失効・read/write権限をタスク更新transaction内で再確認する。Cookie fallbackやCSRF検査を迂回しない。
|
||||
|
||||
本番接続はHTTPSを使用。専用資格情報をコマンド引数・共有設定・ログへ出さない。以下のAPI発行例は説明用で、実際にはUIを推奨する。
|
||||
|
||||
```json
|
||||
{"label":"Laptop / vdirsyncer","write":true,"days":90}
|
||||
```
|
||||
|
||||
## 3. フィールド対応
|
||||
|
||||
| VTODO | PagesWiki |
|
||||
| --- | --- |
|
||||
| UID | 永続同期ID。Web由来はタスクUUID、CLI作成時は外部UIDを保持 |
|
||||
| SUMMARY | 件名(必須、最大300 UTF-8 bytes) |
|
||||
| DESCRIPTION | タスクの非公開メモ(最大16 KiB) |
|
||||
| STATUS | NEEDS-ACTION ↔ 未着手、IN-PROCESS ↔ 進行中、COMPLETED ↔ 完了、CANCELLED ↔ 取りやめ |
|
||||
| DTSTART;VALUE=DATE | 工程開始日(取り組む日ではない) |
|
||||
| DUE;VALUE=DATE | 期限日 |
|
||||
| PRIORITY | 1=最優先、2〜4=高、5=通常、6〜9=低、0/省略=通常。Webからの出力は1/3/5/9 |
|
||||
| COMPLETED | サーバーが記録した完了時刻(UTC) |
|
||||
| CREATED / LAST-MODIFIED / DTSTAMP | サーバーの作成・更新日時(UTC) |
|
||||
| SEQUENCE | タスクversion−1 |
|
||||
|
||||
既存データを上書きするPUTは、公開した対応項目だけを置換する。PRIORITYの元の数値は同じUI優先度の範囲なら保持。CATEGORIES、LOCATION、URL、CLASS、RELATED-TO、X-*はCLI往復メタデータとして保持するが、初版ではPagesWikiの分類・関係・表示を変更しない。RELATED-TOは親子作成APIではない。PERCENT-COMPLETEは保持するがUIの完了判定はSTATUSを正とする。完了後は100を出力し、状態変更時には旧進捗率をクリアする。
|
||||
|
||||
**現在の制限:** DTSTART/DUEはDATEのみ。UTC・ローカル・TZID付きの時刻指定、VTIMEZONE、RRULE/RDATE/EXDATE/RECURRENCE-ID、DURATION、VALARM、ATTENDEE/ORGANIZER/METHODは明示的にエラーにする。時刻・繰り返しを無断で切り落とさない。DTSTAMPは必須のUTC DATE-TIME。
|
||||
|
||||
VTODOはDUE > DTSTARTを要求する。一方、Webの工程日付と期限は独立しているため、同日または期限以前にできない開始日はDAV射影ではDTSTARTを省略する。元のWeb開始日は保持し、期限が変わらない通常のGET→PUTでも消さない。この状態の開始日編集はWebを使用する。工程開始と既存の工程終了の矛盾は422で拒否する。
|
||||
|
||||
CRLF、TEXTエスケープ、75 octetsでUTF-8境界を壊さないfoldを適用する。1リソース=1 VCALENDAR+1 VTODO、最大32 KiB。未対応の意味論は403の`valid-calendar-data`で理由を返す。
|
||||
|
||||
## 4. 同期・競合・復旧
|
||||
|
||||
- PROPFIND Depth 0/1:home discovery、component-set、リソース一覧、ETag。principal/home-setはタスク専用homeに収束する。
|
||||
- REPORT `calendar-query`:VCALENDAR/VTODO component-filter。`calendar-data`の空要素に加え、明示的な`comp name="VCALENDAR"`+`allprop`+`allcomp`による全項目取得に対応。部分選択・展開・time-range/property-filterは403(未対応条件を無視した結果を返さない)。
|
||||
- REPORT `calendar-multiget`:最大200 href、欠損/別authority/コレクション外hrefは個別404。REPORTのDepth省略に対応。
|
||||
- GET/HEAD:正規化ICSとSHA-256 ETag。If-None-Matchで304。
|
||||
- PUT作成:`If-None-Match: *`を推奨。chroncal互換として完全に新規のhrefへの条件なしPUTも受け付けるが、transaction内のhref/UID一意性で競合作成による上書きを防ぐ。既存リソースの更新とDELETE:最新の強いETagの`If-Match`が必要。旧版は412、既存への条件なし更新は428。アーカイブ済みidentityの条件なし復活も428。DBのタスクversionでもCASする。
|
||||
- PUTでは表現を正規化するため、[RFC 9110 §9.3.4](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.3.4)に従いその応答にETagを付けない。クライアントはGET/multigetで正規化版とETagを取り直す。
|
||||
- DELETEはアーカイブ。タスク版・Wikiメモ・子タスクを物理削除しない。Webで復元すると同じhref・UIDで再登場する。
|
||||
- UIDとhrefは別の識別子。外部UIDをUUID形式に強制しない。href名は安全なASCII英数字、`.`、`_`、`-`、最大128 bytes、末尾`.ics`。同じ利用者・ドメイン内でUIDとhrefをそれぞれ一意にする。既存identityの変更は拒否する。
|
||||
- 完了タスクを一覧から除外しない。黙った件数切り捨ては同期クライアントに削除と誤解されるので禁止する。最大10,000件/正本JSON合計32 MiB、超過時507でコレクション全体を失敗させる。大規模運用はsync-token設計へ進める。
|
||||
- 正本TaskRecord内にCLI由来UID/href/受理したICSを保存する。DBの`organizer_dav_resources`は検索索引兼一意性制約で、既存Webタスクを起動時に登録する。更新はタスク版・journal・通知と同一transaction。
|
||||
- 通常一覧・工程表の応答にはICS全文を含めない。詳細とDAVでのみ取得する。
|
||||
- バックアップは従来どおりDBとCASの両方。`organizer_dav_credentials`もDBに含まれる。個別資格情報の復元時には失効済み秘密値の復活に注意し、必要ならすべて失効する。
|
||||
|
||||
## 5. CLI接続手順
|
||||
|
||||
vdirsyncer 0.21.0 + Todoman 4.7.0で検証。検証用資格情報・DB・HTTPサーバーはすべてfixtureで、本番/外部カレンダーの内容にはアクセスしない。
|
||||
|
||||
### vdirsyncer
|
||||
|
||||
`~/.config/vdirsyncer/config`(0600):
|
||||
|
||||
```ini
|
||||
[general]
|
||||
status_path = "~/.local/state/vdirsyncer/"
|
||||
|
||||
[pair pageswiki_tasks]
|
||||
a = "pageswiki_tasks_local"
|
||||
b = "pageswiki_tasks_remote"
|
||||
collections = ["default"]
|
||||
metadata = ["displayname"]
|
||||
|
||||
[storage pageswiki_tasks_local]
|
||||
type = "filesystem"
|
||||
path = "~/.local/share/pageswiki-tasks/"
|
||||
fileext = ".ics"
|
||||
|
||||
[storage pageswiki_tasks_remote]
|
||||
type = "caldav"
|
||||
url = "https://pages.anya.jp/_/api/v1/caldav/tasks/"
|
||||
username = "発行された認証情報ID"
|
||||
password.fetch = ["command", "pass", "show", "pageswiki/task-caldav"]
|
||||
item_types = ["VTODO"]
|
||||
```
|
||||
|
||||
`password.fetch`は利用するパスワード管理ツールに合わせる。`pass show`の対象にはパスワードだけを保存する。セキュリティ上、設定例には実際のパスワードを埋め込まない。
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.local/share/pageswiki-tasks/default
|
||||
vdirsyncer discover pageswiki_tasks
|
||||
vdirsyncer sync pageswiki_tasks
|
||||
vdirsyncer metasync pageswiki_tasks
|
||||
```
|
||||
|
||||
### Todoman
|
||||
|
||||
`~/.config/todoman/config.py`:
|
||||
|
||||
```python
|
||||
path = "~/.local/share/pageswiki-tasks/*"
|
||||
date_format = "%Y-%m-%d"
|
||||
time_format = "%H:%M"
|
||||
default_list = "PagesWiki Tasks" # metasyncでdisplayname取得後。未取得なら "default"
|
||||
default_due = 0 # 自動的な時刻付き期限を生成しない
|
||||
```
|
||||
|
||||
```sh
|
||||
todo list
|
||||
todo new --due 2026-10-01 "CLIから作成するタスク"
|
||||
vdirsyncer sync pageswiki_tasks
|
||||
todo done 1 # 実際の対象IDに置き換える
|
||||
vdirsyncer sync pageswiki_tasks
|
||||
```
|
||||
|
||||
TodomanはローカルICSを編集し、vdirsyncerがサーバーと同期する。Webの変更を取り込むには先にsyncする。競合時の`a wins`/`b wins`は設定せず、差分確認して解消する。
|
||||
|
||||
## 6. 検証と次段階
|
||||
|
||||
### chroncal
|
||||
|
||||
```sh
|
||||
chroncal account add PagesWiki \
|
||||
--server https://pages.anya.jp/_/api/v1/caldav/tasks/ \
|
||||
--username '発行された認証情報ID' \
|
||||
--auth basic --password-cmd 'pass show pageswiki/task-caldav'
|
||||
chroncal todo list
|
||||
chroncal todo add 'CLIで作成' --calendar 'PagesWiki Tasks' --due 2026-10-01
|
||||
chroncal sync run --account PagesWiki
|
||||
```
|
||||
|
||||
パスワード取得コマンドは手元の秘密管理方式に合わせる。通常運用はOS keyringを使用し、`--allow-plaintext`はセキュリティ上の意味を理解した場合のみ。試験ではユーザーの既存設定・DB・keyringを参照しないよう、全XDGディレクトリとHOMEを一時領域へ分離する。
|
||||
|
||||
差分`sync-collection`は未対応のため405を返し、chroncalは全件`calendar-query`にフォールバックする。これは今回のprincipal探索で発生した405とは別で、同期継続が確認できている。追加クライアント対応のために`sync-token`対応を偽って広告しない。
|
||||
|
||||
```sh
|
||||
PAGESWIKI_CHRONCAL=/usr/local/bin/chroncal go test ./internal/server -run '^TestTaskDAVChroncal$' -count=1
|
||||
```
|
||||
|
||||
### 回帰試験
|
||||
|
||||
実装テスト:任意UID/href、JSON UI更新での保持、完了・復元、stale ETag、同時PUT、別利用者・ドメイン分離、専用資格情報の範囲・失効・expiry・suspended、書き込みtransaction内失効、XML namespace/Depth、未対応条件拒否、UTF-8 fold、機能kill switch。
|
||||
|
||||
実CLI試験:discovery、PROPFINDとVTODO calendar-query両経路、multiget、Web→ローカル取得、Todoman作成・完了、Web変更取得、ローカル削除→アーカイブ、再syncで版が増えないこと。
|
||||
|
||||
```sh
|
||||
PAGESWIKI_VDIRSYNCER=/path/to/venv/bin/vdirsyncer go test ./internal/server -run '^TestTaskDAVVdirsyncer$' -count=1
|
||||
```
|
||||
|
||||
同じvenvに`todo`が必要。ブラウザ試験は4サイズで資格情報発行・失効・閉じた後の秘密値破棄・スクロール幅も検証する。
|
||||
|
||||
残件:時刻付き期限の正本設計、繰り返し・VALARM、標準RELATED-TOの双方向階層同期、共有コレクションACL、property/time-rangeフィルター、sync-token/差分同期、アカウント設定への資格情報管理統合、総合principal/well-known discovery、追加クライアント互換試験。現時点では対応をうたわない。
|
||||
|
||||
規範/参考:[RFC 5545 VTODO](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.6.2)、[RFC 4791](https://www.rfc-editor.org/rfc/rfc4791.html)、[vdirsyncer公式設定例](https://github.com/pimutils/vdirsyncer/blob/main/config.example)、[Todoman設定](https://todoman.readthedocs.io/en/stable/configure.html)。
|
||||
@@ -0,0 +1,73 @@
|
||||
# 日別計画・親子グループ・Wikiメモ
|
||||
|
||||
2026-09-25実装。organizer.tasks 0.7.0。今回の変更は2026-09-25 07:07 JST本番反映済み。
|
||||
|
||||
[本番反映記録](../../operations/deployments/2026-09-25-task-daily-notes.md)。
|
||||
|
||||
## 日別の計画
|
||||
|
||||
| 画面 | URI | 対象 |
|
||||
| --- | --- | --- |
|
||||
| 持ち越し | `/v/plan/tasks/carryover` | 昨日以前の計画日、または昨日以前の期限が残る未完了タスク |
|
||||
| 今日 | `/v/plan/today` | 既存の今日の計画・今日までの期限超過 |
|
||||
| 明日 | `/v/plan/tasks/tomorrow` | ドメインのタイムゾーンでの翌日の計画・期限 |
|
||||
| 任意の日 | `/v/plan/tasks/day/YYYY/MM/DD` | 指定日が計画日または期限の未完了タスク |
|
||||
|
||||
日付ピッカーと前後日の移動を提供する。日別画面のクイック作成/新規作成では選択日を計画日に入れる。カレンダー時間枠の初期日付も日別画面の選択日を優先し、他画面はタスクの計画日があれば利用する。時刻の解釈・DST検証は既存のカレンダーAPIによる。
|
||||
|
||||
持ち越し画面では割り当て先日付を指定し、各行の矢印でその日に変更できる。変更するのは `planned_on` のみ。期限・工程日・子の計画日・カレンダーイベントは自動変更しない。期限超過のタスクは計画を将来に移しても持ち越しに残る。完了や取消済み・archive済みは除外する。完了した日の実績表示はこの画面の対象外。
|
||||
|
||||
APIは既存itemsの `view=day&date=YYYY-MM-DD`、`view=carryover`。指定日が不正なら422。今日と持ち越しの基準日はクライアントではなくサーバーのドメイン時刻で決定する。既存のToday集計・外部カレンダーは変更しない。
|
||||
|
||||
## 親子の一覧
|
||||
|
||||
- UIは `hierarchy=1` で取得。親の作成日時/UUIDをグループキーとし、親→子の順で同じグループに配置する。子はグループ内で新しい順。
|
||||
- cursor比較にもグループキーと親子順位を含める。続きを取得した際はUUID単位で統合し、親・子を重複させない。
|
||||
- 子だけが日付や検索条件に一致したときは、同じDomain・所有者の親を補足表示する。「親」マークは親自体がフィルタ対象ではないことを示す。この補足は親に日付を割り当てたり、Today集計へ追加したりしない。
|
||||
- 親を今日・明日へ入れた場合も、展開操作で日付未設定/別日/完了済みを含む子を取得できる。最初に一致した子だけを表示している場合は「すべてのサブタスク」アイコンを提供する。
|
||||
- 展開はオンデマンド、1回100件。超過時はその親の中で続きを読み込む。親情報は最大100件のバッチ取得とし、一覧の各子について個別APIを呼ばない。
|
||||
- 同一画面での再読込では展開済み状態を保持する。画面間・ブラウザ再起動をまたぐ永続化は未対応。
|
||||
- 未保存の編集がある間は一覧再構築・子の置換を抑止し、編集中の入力を破棄しない。
|
||||
|
||||
グループソートには所有者で限定した自己結合を利用する。出力は既定60/最大100件、APIは既存の5秒上限。極端に大量の個人タスクでソートが支配的になった場合、安定したfamily sort keyの索引化を検討する。全ユーザ・全Domainを読み込む設計にはしない。
|
||||
|
||||
## Wikiメモの保存先と動作
|
||||
|
||||
従来のTaskRecord.notesは個人用の短いプレーンテキストメモとして残す。今回の「メモ表示」「メモ編集」は、通常のWiki Pageへ接続する別の導線。
|
||||
|
||||
プロジェクトの編集画面で次を指定する。
|
||||
|
||||
1. **関連するWikiのPath**:実在する、本人が読めるプロジェクトのページ。
|
||||
2. **Wikiメモのサブ階層**:そのページの配下を表す相対Path。既定は `tasks`。複数階層も指定可。
|
||||
|
||||
例:
|
||||
|
||||
- プロジェクトの関連Wiki:`/projects/pageswiki`
|
||||
- サブ階層:`work/notes`
|
||||
- タスク件名:`通知UIの改善`
|
||||
- 作成先:`/projects/pageswiki/work/notes/通知UIの改善`
|
||||
|
||||
件名を1つのPathセグメントとして扱う。`/\\?#%` と制御文字はハイフンへ変換、単独の `.`/`..`/`_` はUUID付きの安全な名前へ置換する。相対サブ階層の絶対Path、空セグメント、親移動、制御空間 `_` は拒否する。
|
||||
|
||||
既存の関連WikiページUUIDがタスクにあれば、それをメモとして使う。なければ上記の候補Pathを確認し、明示的な確認後に新規作成する。初期本文はHTMLエスケープした件名のH1。表示ボタンからでも未作成なら作成確認→エディタとなる。編集時は利用可能な既定のHosted Editorを優先し、それ以外は標準の `/e/-/...` を利用する。
|
||||
|
||||
初回作成後はタスクの `page_uuid` で関連付ける。Wiki側のrename/移動に追従する。タスク件名やプロジェクトのサブ階層を変えても、既存のメモを自動rename/移動しない。同名ページが既にあれば409で停止し、詳細画面からの明示的な関連付け、または件名の変更を案内する。既存の内容を上書き・自動統合しない。
|
||||
|
||||
プロジェクト未選択/関連Wiki未指定の場合は設定を案内する。プロジェクトの関連ページ自体の新規作成は既存Wikiエディタで行う。リンク済みメモが削除・権限失効した場合、同じPathへ勝手に作り直さない。詳細画面で関連付けを明示的に解除してから再作成する。
|
||||
|
||||
## API・保存・公開の境界
|
||||
|
||||
- `GET items/{uuid}/note`:現在のPath、閲覧/編集URL、linked/exists/writable、TaskRecord、ETag。副作用なし。
|
||||
- `POST items/{uuid}/note`:新規作成と関連付け。`If-Match: "{task version}"`、JSON `{"path":"確認した作成先"}` が必要。欠落428、版/確認先変更412、Path衝突409。
|
||||
- Page、Path、初期Revision、タスクhead/revision/journal、共通outboxを同一transactionで確定する。プロジェクト版と関連Path→UUIDもwriter transactionで再照合。DB失敗時にPageや紐づけだけを残さない。CASファイルは既存仕様どおりrollback後に未参照ファイルとして残る可能性がある。
|
||||
- タスクは個人専用のまま。WikiメモはWiki Pathの公開設定と権限に従う。作成確認でこの違いを明示する。タスク所有権だけでWikiのread/create/writeをバイパスしない。
|
||||
- readonly・他人のタスク・失効membership・無効な拡張を拒否。既存Wikiへの明示リンクは従来のpage_path更新を利用する。
|
||||
- DBスキーマ変更なし。`notes_subpath,omitempty` はプロジェクト正本JSONの追加項目。未指定の既存正本のhashは変えない。旧バイナリでプロジェクト設定を保存するとこの追加項目が落ちるため、運用開始後はforward-fixを推奨する。
|
||||
|
||||
## 検証・残り
|
||||
|
||||
Go fixture:日別/持ち越し条件、親子cursor、補足親の私有境界、日付検証、メモ作成、保存失敗rollback、H1 escaping、同名衝突、確認先変更、UUID追従、readonly、Wiki書込権限を検証。
|
||||
|
||||
Chromium fixture(1440/1024/390/320px):親から日付未設定の子を展開、子の重複防止、明日への作成、時間枠の初期日、持ち越しの割当て、メモ編集ボタンで新規Wikiへ遷移、表示ボタンでViewerへ遷移。外部取り込みカレンダーにはアクセスしない。
|
||||
|
||||
残件:親子の計画日の明示的一括変更、日別キャパシティ、日別の完了実績、親子のドラッグ並べ替え、共有、メモの任意rename/移動のタスクUI統合、実機Safari検証。本番2インスタンスへ2026-09-25 07:07 JSTに反映済み。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 既定タスクリストの表示名変更
|
||||
|
||||
2026-09-27、`organizer.tasks 0.11.1`。**12:51 JSTに本番app/app2へ反映済み。** [反映記録](../../operations/deployments/2026-09-27-default-task-list-name.md)。Tasks.org実機の再試行は利用者確認待ち。
|
||||
|
||||
## 原因
|
||||
|
||||
利用者が既定リスト名を変更するとエラーになると報告。本番の秘匿済みログでは03:39:59 UTCに`PROPPATCH target=task_collection status=405`、認証結果は`basic_accepted`。0.11.0ではリストのPROPPATCHが未実装で、既定名`PagesWiki Tasks`も固定値だった。認証不良や名前の衝突ではない。
|
||||
|
||||
## 変更契約
|
||||
|
||||
- `PROPPATCH /_/api/v1/caldav/tasks/default/`のDAV:displaynameのsetを受理。末尾slashなしも同じリスト。
|
||||
- 表示名は`organizer_dav_default_lists`にdomain/owner単位で保存する個人設定。未設定なら従来の`PagesWiki Tasks`。トークンを交換しても同じ利用者の設定を使用する。
|
||||
- URLやプロジェクトなしという所属の意味は変更しない。架空のプロジェクトは作らない。タスク本文、UID、revision、ETagは変わらない。
|
||||
- 共通CalDAV home、旧task home、既定リスト自身のPROPFINDで同じ保存名を返す。索引再構築でも設定を失わない。
|
||||
- UTF-8で1〜300 bytes、空白だけや制御文字は拒否。XMLテキストとしてescapeして返す。名前をアクセスログへ追加しない。
|
||||
|
||||
## PROPPATCHと認可
|
||||
|
||||
[RFC 4918 §9.2](https://www.rfc-editor.org/rfc/rfc4918.html#section-9.2)の原子的更新・Multi-Statusに従う。全命令を検証後に保存し、正常時は207/property status 200。未対応propertyやremoveは403、無効な名前は409、同じ要求のその他の正常propertyは424で、部分更新しない。複数setは順序どおり解釈する。不正XML・DTD・過大なXMLの制限には共通DAV parserを用いる。
|
||||
|
||||
認証、tasks/all scope、write権限を必要とする。保存transaction内でwriterを取得してから現在のmembership/principal/トークンの失効・期限・scope/拡張の有効状態を再確認する。別domain/ownerへの設定変更はできない。
|
||||
|
||||
## 範囲と残件
|
||||
|
||||
今回の対象は既定タスクリストの名前のみ。通常プロジェクト/MKCALENDARリストのPROPPATCH、色・アイコン・任意dead property、リストDELETEは引き続き未実装。プロジェクトの名称はWebのプロジェクト編集で変更可能。Tasks.orgのupdateCollectionはdisplaynameを個別要求し、その後必要に応じて色・アイコンの別要求を送るため、それらの未対応応答は名前変更の成功とは分けて扱う。
|
||||
|
||||
## 検証
|
||||
|
||||
隔離HTTPテストで、日本語・XML特殊文字の名前、3箇所の探索結果、ETag/本文の不変、プロジェクトが増えないこと、schema再実行後の永続性、OPTIONSのPROPPATCH広告、malformed XML/不正名/未対応property混在の原子性を確認。他owner、別domain、readonly、calendar-only、匿名、失効トークン、拡張無効化も検証する。本番の既定名は変更しておらず、実機の再試行は反映後に必要。
|
||||
|
||||
実施結果:全Goテスト成功。chroncalの既定・共通・名前付き・通常Webプロジェクトの同期試験、vdirsyncer/Todoman試験も成功。追加の名前変更・認可・原子性テストは5回反復成功。
|
||||
@@ -0,0 +1,64 @@
|
||||
# タスクの所属統一とCalDAV上書き同期
|
||||
|
||||
後続0.11.1:[既定タスクリストの表示名変更](task-dav-default-list-name.md)を実装し、2026-09-27 12:51 JSTに本番反映。所属・URLは維持したまま、固定名PagesWiki Tasksを利用者ごとに変更できる。
|
||||
|
||||
2026-09-27。`organizer.tasks 0.11.0`。**12:18 JSTに本番app/app2へ反映済み。Tasks.org Desktop実機の再同期は利用者確認待ち。** [反映・移行確認記録](../../operations/deployments/2026-09-27-task-unification.md)。
|
||||
|
||||
利用者の決定:PagesWikiのプロジェクトと外部タスクリストを統一する。条件なしの書き込みは上書きを受け付け、トークン単位の上書き互換スイッチは設けない。競合を通知してどちらを採用するか選ぶ機能は次段階に実装する。
|
||||
|
||||
## 1. 確認した不整合
|
||||
|
||||
0.10.0では、MKCALENDARで作ったリストのみプロジェクトと一対一に対応し、通常のWebプロジェクトはプロジェクトなしのタスクと同じ既定リストに混在していた。また、既存リソースのPUT/DELETEは条件ヘッダ必須で、直接接続クライアントの無条件更新を428で拒否していた。
|
||||
|
||||
Tasks.org公開ソースの確認対象はcommit `0fde622e917ea2cbb0956c3effe9209c11045a67`。`CaldavSynchronizer.pushTask`は`remote.put(requestBody)`、削除は`remote.delete {}`で条件ヘッダを渡さない。依存するdav4kmp `1.0.0-beta01`(commit `dec7bd10952278c7ac196de111880f00d75d8f3e`)もそれを自動補完しない。本番の秘匿ログに認証成功後のPUT 428が反復していた。ただし、利用者のインストール版と調査したソースが同じか、個々のログがDesktop由来かは未確定。ctag追加による解決ではない。
|
||||
|
||||
- [Tasks.org同期処理](https://github.com/tasks/tasks/blob/0fde622e917ea2cbb0956c3effe9209c11045a67/kmp/src/commonMain/kotlin/org/tasks/caldav/CaldavSynchronizer.kt)
|
||||
- [dav4kmp HTTP処理](https://github.com/tasks/dav4kmp/blob/dec7bd10952278c7ac196de111880f00d75d8f3e/src/commonMain/kotlin/at/bitfire/dav4jvm/ktor/DavResource.kt)
|
||||
|
||||
## 2. 所属・URI契約
|
||||
|
||||
| 正本の所属 | CalDAVリスト |
|
||||
| --- | --- |
|
||||
| `ProjectUUID`が空 | `/_/api/v1/caldav/tasks/default/`。既存表示名PagesWiki Tasksは維持し、意味をプロジェクトなしに限定 |
|
||||
| 通常のWebプロジェクト | `/_/api/v1/caldav/tasks/projects/{projectUUID}/` |
|
||||
| 既存MKCALENDARプロジェクト | `/_/api/v1/caldav/{dav_collection}/`。既存URLを維持 |
|
||||
|
||||
- タスクのUUID、UID、filename、ProjectUUID、版、本文を移行で変更しない。名前やカテゴリから所属を推測しない。
|
||||
- 通常プロジェクトのURLは不変UUIDから導出するため、`dav_collection`を正本へ後付けする必要はない。表示名は常にプロジェクトのタイトル。名称変更でURLは変わらない。
|
||||
- `tasks/projects/`はタスク専用名前空間。予定カレンダーのUUIDと衝突しない。外部取り込み予定は読まない。
|
||||
- リストの新規タスクはそのプロジェクトへ所属する。Webで所属を変更するとリスト間を移る。CalDAVのMOVE実装とは別。
|
||||
- 閲覧できるのは同じdomain/ownerのプロジェクトのみ。アーカイブ済みプロジェクトは探索・アクセスから除外し、そのタスクを既定リストへ流出させない。
|
||||
- リスト全体の完全な探索に現在の256件上限を適用し、超過時に部分リストを返さず507にする。将来の大量プロジェクト向け探索最適化は残件。
|
||||
|
||||
## 3. 移行と古いクライアント
|
||||
|
||||
起動時のEnsureTasksSchemaで、ルーティング索引とタスクのリスト別identity索引を同じDB transactionで再構築する。全プロジェクト(アーカイブ済みも含む)とタスクの現行headから導出し、失敗時は全体をrollbackする。正本・履歴を書き換えず、反復実行でURI/ETagは変わらない。起動時の再構築はタスク数に比例する処理であり、リクエストごとには行わない。
|
||||
|
||||
既定リストから通常プロジェクトへ移った旧hrefは`organizer_dav_legacy_hrefs`に移行メタデータとして記録する。旧hrefへのGETは404、古い未同期PUTによる再作成は409 `task_collection_relocated`。別リストを旧href経由で変更・削除するaliasにはしない。これにより、古い端末の再送で同じタスクがプロジェクトなしに増えることを防ぐ。索引を再構築しても移行メタデータは保持する。
|
||||
|
||||
本番反映前後には未送信の変更を保全し、各端末でリストの再探索・新しいプロジェクトの同期有効化を行う。未同期データがある状態でアカウントやローカルデータを削除しない。409の場合は新しい所属リストを確認して未送信変更を反映する。0.10以下へ安易に戻すと旧既定リストに再混在するため、戻す場合はタスク拡張を停止し移行方針を確認する。
|
||||
|
||||
## 4. 書き込みの現行契約
|
||||
|
||||
- 条件ヘッダなしのPUT/DELETEを全タスクCalDAV接続で受理する。追加のトークン互換設定・User-Agent判定は設けない。既存のOPTIONS calendar-access広告設定とは独立した話。
|
||||
- 最後にcommitした内容を採用する。削除は従来どおりアーカイブ。削除後に無条件PUTが来た場合は同じidentityの新しい版として復元する。
|
||||
- 明示されたIf-Match/If-None-MatchはHTTPの事前条件として尊重し、不成立なら412。Web UI/JSON APIの版チェックは変更しない。
|
||||
- 保存は既存のwriter transactionとversion CASを維持する。条件なし書込の競合時は最新headを取得して最大8回再試行し、CalDAVで表現する項目だけを再適用する。PagesWiki固有の計画日・整理先・関連文書等を古いheadへ巻き戻さない。過度な競合は409で再同期を要求する。
|
||||
- 同時新規作成は同じhrefの1identityへ収束する。別hrefへのUID衝突、UID変更、他利用者へのアクセス、失効トークン、readonly、無効化された拡張は従来どおり拒否。
|
||||
- 新規head、CAS本文、organizer_revisions、organizer_changesは既存の同一保存処理を用いる。上書き前の版は保持される。PUT本文を正規化するためPUT成功応答にETagは付けず、GET/REPORTで取得する。
|
||||
- **この段階では競合通知も採否選択UIもない。** 古い端末の変更が新しい内容を上書きし得ることは、今回採用した動作。
|
||||
|
||||
## 5. 次段階:競合通知と採否選択(未実装TODO)
|
||||
|
||||
1. **比較の根拠と来歴**:書き込み元(Web/DAV、資格情報の非秘密ID)、対象task/domain/owner、受信時刻、base版が分かるか、上書き前/採用後の版を記録する。秘密値や生の本文をアクセスログへ出さない。DTSTAMPや端末時計だけで新旧を決めない。
|
||||
2. **baseが不明な更新**:条件なし要求だけでは競合を厳密に判定できない。直近配信版などの補助記録は参照先を共有する端末もあり確定根拠にならないため、「競合候補」として扱う。全ての通常編集を競合扱いしない検出条件と上限・保持期間を設計する。
|
||||
3. **候補保存とInbox outbox**:上書き前/受信版の参照をhead更新と同じtransactionで保存し、ownerの通知Inboxへ重複抑制付きで配送する。通常のアクティブ通知設定に従い、作業を強制的に遮らない。未解決候補が参照する版をGCしない。
|
||||
4. **比較・選択UI**:「上書き前を採用」「受信版を採用」「現在の内容を維持」を項目差分付きで表示。採用は履歴を戻すのではなく新しいrevisionを作成する。
|
||||
5. **解決の競合**:候補の解決時にも最新headを再確認し、通知後の第三の変更を黙って消さない。owner/domain/現在権限を再検証し、解決済み通知の二重操作を防止する。
|
||||
6. **受け入れ試験**:Webと二つのDAV端末の競合、更新対削除、復元、通信再送、遅延したInbox配送、別domain/owner、権限失効、履歴GC、同一候補の二重決裁。
|
||||
|
||||
## 6. 今回の検証範囲
|
||||
|
||||
合成データで通常プロジェクトの探索・所属、旧索引移行・再実行、URI/ETag維持、古いhref再作成防止、名前変更、他owner隔離、アーカイブの非流出、無条件同時更新・同時作成・削除・復元・履歴保持を検証する。既存の明示ETag競合試験、認可試験、共通CalDAV・CLI同期・Web回帰も継続する。外部取り込みカレンダーや本番の認証情報・本文をテストデータにしない。
|
||||
|
||||
実施結果:`go test ./...`成功。追加の所属・上書き試験は10回反復成功、関連試験の`-race`も成功。実chroncalで既定・共通home・MKCALENDAR・通常Webプロジェクトの各リストを検証し、vdirsyncer/Todomanも成功。ChromiumでタスクUI(desktop/laptop/mobile/mobile-small)とカレンダーUIの回帰試験成功。これらは隔離fixtureの結果であり、Tasks.org Desktopの実機成功や本番反映を意味しない。
|
||||
@@ -0,0 +1,49 @@
|
||||
# インラインタスク、サブタスク、日割り工程表
|
||||
|
||||
更新:2026-09-25。`organizer.tasks` 0.6.0。実装・隔離fixture検証済み。同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。
|
||||
|
||||
## 一覧中心の編集
|
||||
|
||||
0.7.0の追加仕様(2026-09-25 07:07 JST本番反映済み):[日別計画・親子グループ・Wikiメモ](task-daily-notes.md)。以下の0.6.0契約を拡張する。
|
||||
|
||||
件名・状態・取り組む日・期限・見直す日・工程開始/終了を一覧で直接編集する。変更確定/フォーカス移動時に保存する。詳細メモ、通知時刻等は既存の詳細画面へ残す。時間枠ボタンは一覧から直接カレンダー追加モーダルを開く。
|
||||
|
||||
保存は行が取得したversionでIf-Matchを行う。完全なTaskRecordを再取得してから変更項目を合成するが、If-Matchは再取得したversionへ勝手に進めない。他の画面との競合では入力を保持し、行の再読込で明示的に破棄できる。編集中/保存中は一覧の自動再読込で入力を捨てない。
|
||||
|
||||
### コンパクト一覧(2026-09-25追加、06:17 JST本番反映済み)
|
||||
|
||||
[本番反映記録](../../operations/deployments/2026-09-25-compact-task-ui.md)。
|
||||
|
||||
- 幅1024px以上は表に近い1タスク1行。共通見出しの下に完了操作・件名・状態・取り組む日・期限・見直す日・工程開始・工程終了・操作を並べる。行高は通常約34px、行内のmargin/gapは0。サブタスクも列幅を揃え、件名の字下げと親へのリンクで階層を示す。
|
||||
- 利用可能な横幅を使い、列が収まらないPC幅では一覧の内側のみ横スクロールする。入力や操作を折り返さず、ページ全体の横はみ出しを防ぐ。詳細・カレンダー追加・再読込・子の展開・子の追加はラベル付きアイコン操作。
|
||||
- 1024px未満はフィールドラベルを省略しないカード状の配置。日付は2列、入力文字16px以上、タッチ対象44px以上。サブタスクは罫線と字下げで区別する。入力・保存契約はPCと同一。
|
||||
- 保存中/成功の通知はスクリーンリーダー向けstatusに残し、行を増やさない。保存エラー・競合は行の下に本文を表示して入力を保持する。アイコンにはtooltipとアクセシブル名を設け、サブタスクの展開状態をaria-expandedで伝える。
|
||||
- Chromium fixtureで1440px・1024px・390px・320px幅、PC列揃え、タッチ領域、インライン保存、階層表示を検証する。実機Safariのdate入力等は引き続き別途確認が必要。
|
||||
|
||||
## 階層と日付
|
||||
|
||||
`parent_uuid`を持つサブタスクを親の一覧からインライン追加できる。初版は親→サブタスクの2階層。同じDomain・所有者のtaskのみ。自己参照・循環・3階層目・他人の親・新規のarchived親への配置を拒否する。親の完了・archiveは既存の子を完了/archiveしない。
|
||||
|
||||
子は独立した件名、状態、各種日付、見積りを持つ。作成時に親のproject/bucket/priorityをコピーするが、その後の自動継承はしない。Todayの見積もりは各項目独立で加算するため、親と子に同じ工数を二重計上しない運用とする。roll-upは未実装。
|
||||
|
||||
新しい`start_on`/`end_on`は工程のcivil dateで、両端を含む。片方だけならその1日。逆順と366日を超える範囲を拒否する。期限/計画日や実際のカレンダー時間枠は自動変更しない。
|
||||
|
||||
## 工程表とナビゲーション
|
||||
|
||||
- `/v/plan/tasks/schedule`:ドメイン現在月。
|
||||
- `/v/plan/tasks/schedule/YYYY/MM`:月の日割り工程表。日付列に工程のバーを表示、タスク詳細へ遷移。
|
||||
- `?project={UUID}`でプロジェクトを絞り込む。
|
||||
- API:`GET /_/api/v1/extension/organizer.tasks/schedule?month=YYYY-MM&project=...`。
|
||||
- 月最大200件、超過はpartial表示。開始日の索引と366日上限で走査範囲を制限する。メモは返さない。
|
||||
- family API:`items?view=family&parent={UUID}`。100件まで+cursor、完了/archive済みの子も確認できる。
|
||||
- ホームの検索ショートカットへタスク一覧アイコン、上部ナビバーへ「今日のタスク」モーダルを追加。開くまで一覧fetchをしない。
|
||||
|
||||
## Migration、検証、次段階
|
||||
|
||||
DBにparent/start/end列と子一覧・工程表索引を追加する。新フィールドは空ならcanonical JSONから省略するため既存正本のhashを変更しない。工程と親参照は版管理対象。同一transactionで正本参照、投影、履歴、outbox、通知を更新する。
|
||||
|
||||
旧バイナリは新フィールドを保存時に落とすため、新しい階層・工程を利用した後の単純なbinary rollbackは避け、forward-fixを優先する。データごと戻す場合はDBと正本を同じバックアップ時点へ戻し、それ以降の更新が失われることを確認する。
|
||||
|
||||
Goで日付範囲、月またぎ、階層制約、親状態と子の独立性を検証。ChromiumでPC/スマートフォン幅のインライン日付編集、子追加、Todayモーダル、時間枠・Pomodoroの既存操作を検証。
|
||||
|
||||
TODO:日割りバーのdrag/resize、折りたたみ状態保持、子の昇格/別の親への移動UI、親への工数roll-up、日付未設定を工程表から割当てる操作、依存関係・共有・日課instance。時間単位の工程表とは別機能として扱う。
|
||||
@@ -0,0 +1,118 @@
|
||||
# タスクの時間枠とPomodoro
|
||||
|
||||
更新:2026-09-25。`organizer.tasks` v0.5.0 の実装契約。[個人タスクの基本設計](tasks-implementation.md)、[期限日/計画日の通知](task-reminders.md)を前提にします。
|
||||
|
||||
## 1. 利用できる画面
|
||||
|
||||
`/v/plan/today` および各タスク画面にPomodoroバーを表示します。集中25分、休憩5分を初期値とし、それぞれ1〜180分の範囲で指定できます。開始/一時停止/再開/終了/中断を提供します。
|
||||
|
||||
保存済みタスクの編集ダイアログに以下を追加します。
|
||||
|
||||
- **時間枠をカレンダーへ**:カレンダー・開始・終了を指定するモーダル。既存の時間枠の表示、予定詳細への移動、未完了要求の再試行、関連解除。
|
||||
- **このタスクに集中**:タスクに関連付けてPomodoroを開始。タスクに未保存の変更があれば、先に保存するよう促します。
|
||||
|
||||
日本語/英語、既存テーマ、PC/スマートフォンに対応します。readonly利用者は状態の表示のみ可能です。完了・アーカイブ済みタスクでは新しい時間枠や関連タイマーを開始しません。タスクに関連付けないタイマーも使えます。
|
||||
|
||||
## 2. 時間枠の意味と境界
|
||||
|
||||
タスクの期限日、取り組む日、カレンダーの割当時刻は別の情報です。時間枠の作成・変更・解除によって、タスクの日付・状態・版を自動更新しません。
|
||||
|
||||
初版の対象は **自分が所有する、非公開・メンバー未設定・Sourceなしのローカルカレンダー** に限定します。公開・共有カレンダー、外部ICS/CalDAV取り込みは除外します。ピッカーはカレンダーのメタデータだけを調べ、外部SourceのURLや資格情報をレスポンスへ含めません。
|
||||
|
||||
予定の作成/再取得時は、カレンダーのロック取得後、ICSスナップショットを読む**前**にこの条件を再検査します。そのためピッカーを開いた後に公開・共有などの設定が変更されても、条件外の予定をタスク連携から読まない設計です。
|
||||
|
||||
利用者の明示した方針に従い、新しく作る予定名は `Focus time(タスクの件名)` とします。作成要求のDB transactionで件名をsnapshot保存し、再試行中にタスク名が変わっても要求の予定名を変えません。改行・制御文字は空白化し、iCalendarのエスケープ/折り返しを適用します。メモ・task UUIDはICSへコピーしません。
|
||||
|
||||
後からそのカレンダーを公開・共有した場合、予定に含めたタスク件名も見えることを作成画面に明記します。既存予定の名前は自動変更しません。旧版で作った `Focus time` や利用者が編集した予定名も、再試行で上書きしません。タスク名の変更による既存予定名への自動同期も行いません。
|
||||
|
||||
1タスクにつき有効な関連は最大100件、1枠は24時間以内。フォームはドメインのタイムゾーンを明示し、そのIANA zoneと現地日時を送信します。存在しない夏時間の時刻は拒否します。夏時間終了時の重複時刻はGoのzone解決に従うため、厳密な片側指定が必要なクライアントはRFC3339オフセット付き日時を送ります。
|
||||
|
||||
## 3. 正本と失敗からの回復
|
||||
|
||||
予定の正本は従来の月別ICS/calendar manifestです。関連と未完了要求の正本はSQLiteの `organizer_time_blocks` です。これらを一つの原子的commitであるかのようには扱いません。
|
||||
|
||||
1. DBのwriter transactionで、所有者・現在のmembership・タスクの種類/状態/版・拡張の有効性を確認し、`pending`要求を記録。
|
||||
2. 要求UUIDから決定的に作るevent UIDで、カレンダー側のロック内で「存在すればそのまま、なければ作成」。
|
||||
3. DBの関連を`active`へ更新。失敗したら`pending`を残し、同じ要求UUIDで再試行。
|
||||
|
||||
再試行は既存予定を上書きしません。予定が移動・時刻変更されても、同一calendar UUID+event UIDから現在時刻とETagを取得します。`active`な予定が削除されていたら、GETや再試行では再作成せず、利用不可として表示します。
|
||||
|
||||
関連解除は`unlinked` tombstone化で、カレンダーの予定を削除しません。同じ要求の再送は拒否し、関連が復活しないようにします。解除と進行中の作成が競合した場合も、解除した関連をactiveへ戻しません。ただし独立したファイルcommitがすでに進んでいれば、関連のない予定が残る可能性があります。予定削除が必要ならカレンダー画面で確認のうえ実施します。
|
||||
|
||||
1つのHTTP要求で全関連のカレンダーデータを走査しません。関連一覧取得はDBのみ。UIは10件ずつ、表示する各関連の現在時刻を逐次取得します。画面を閉じたら続きの取得を止め、各fetchは15秒timeoutです。サーバーの要求処理は5秒timeoutです。
|
||||
|
||||
### 時間枠API
|
||||
|
||||
prefix:`/_/api/v1/extension/organizer.tasks/`
|
||||
|
||||
| Method / suffix | 内容 |
|
||||
| --- | --- |
|
||||
| `GET calendars` | 対象カレンダーのID・名前・pretty_name、ドメインのzone |
|
||||
| `GET blocks?task_uuid=...` | 自分のタスクの有効関連一覧(最大100件、初期要求の日時) |
|
||||
| `GET blocks/{uuid}` | 現在の時刻・ETag・予定href。参照不可なら`available:false` |
|
||||
| `POST blocks` | `uuid,task_uuid,task_version,calendar_uuid,start,end,timezone`で作成/再試行 |
|
||||
| `DELETE blocks/{uuid}` | 関連だけを解除。予定は残す |
|
||||
|
||||
`start/end`はRFC3339、または`yyyy-mm-ddThh:mm`+IANA timezone。保存はUTCに正規化します。新規作成には現在のタスク版を要求。同じ要求の再試行では、タイトル編集などで版が進んでいても、要求内容が不変でタスクが未完了なら許可します。タスクが完了済みなどの場合は、新規/再試行の作成は止めます。未完了要求自体は一覧から解除できます。
|
||||
|
||||
## 4. Pomodoroの状態と永続化
|
||||
|
||||
`organizer_focus`をセッションの正本、`organizer_focus_changes`を状態遷移の監査記録とします。タスクの正本・履歴とは分離します。DBをキャッシュとして削除してはいけません。
|
||||
|
||||
- 状態は`running / paused / completed / cancelled`。
|
||||
- 1インスタンスの同一Principalにつき、ドメインをまたいでもrunning/pausedは1つだけ。DBの部分UNIQUE索引とwriter transactionで保証。
|
||||
- 開始にはクライアントUUID、変更には現在versionを要求。二重開始の再送で開始時刻をリセットしない。古いversionの変更は412。
|
||||
- duration、残時間、終了予定時刻を保存し、休止/再開時に計算する。毎秒の書き込みはしない。
|
||||
- 異なるドメインに有効なセッションがあれば、そちらで終了させてから新しく開始する。他ドメインのtask UUID等はエラーへ出さない。
|
||||
- 権限失効・ドメイン無効化・拡張停止によって他ドメインに取り残された自分のセッションは、新規開始時に`revoked`として中断記録し、利用不能なタイマーが永久に次の開始を妨げないようにする。タスクそのものは変更しない。
|
||||
|
||||
`GET focus`は現在ドメインのactive session、なければ直近のsessionとサーバー現在時刻を返します。`POST focus`は`action=start/pause/resume/complete/cancel`、`uuid,version`を受け、開始時には`phase,minutes,task_uuid`(任意)を指定します。
|
||||
|
||||
ブラウザはサーバー時刻と単調時計を基準に表示を更新し、可視中のみ30秒ごととタブ復帰時にサーバー状態を確認します。非表示中は定期fetchも表示更新もしません。秒表示はDBアクセスを伴いません。別端末での変更は次回取得時に反映され、競合操作は版で拒否します。
|
||||
|
||||
終了は**タイマーの終了**で、タスクの完了ではありません。手動早期終了は残時間を保持します。集中区間は後述のToday画面で日付ごとに集計します。期間別・プロジェクト別の実績ダッシュボードは未実装です。
|
||||
|
||||
### Todayの見通し(v0.5.0)
|
||||
|
||||
`GET /_/api/v1/extension/organizer.tasks/today`を追加。日付は任意入力にせず、ドメインのタイムゾーンにおける今日の0時から翌日0時までを対象とします。夏時間の日は固定24時間ではなく、現地日付で区切ります。
|
||||
|
||||
- **未完了タスクの見積もり**:今日取り組む、または今日までが期限の未完了タスクの見積分数。現在のToday一覧と同じ定義です。完了済みは含めません。最大100件、超過時は一部集計と表示。
|
||||
- **今日の時間枠**:activeな関連を持つ個人localカレンダーについて、ロック内で公開・共有・Sourceを再検査してからキャッシュを現行manifestへ合わせ、期間内のeventを関連へJOINします。初期要求の日時では絞らず、後から別の日へ移した予定も現在の日時で判定します。タスクが完了・アーカイブ済みでも、予定が関連付きで残っていれば時間枠に含めます。
|
||||
- **記録済みの集中時間**:開始/再開から休止/終了までの区間を`organizer_focus_spans`へ保存。session更新・監査と同じtransactionなので、失敗時は区間もrollbackします。休憩と休止中の時間は除き、日付境界で切り分けます。実行中の区間は取得時の現在時刻まで、スケジューラの遅延は本来の終了時刻までで打ち切ります。手動中断までに集中した時間は含めます。
|
||||
|
||||
時間枠は当日内の合計割当時間と、その和集合による占有時間を別々に計算します。差分を重複として表示します。一般の予定・労働時間帯・空き時間はまだ集計しないため、これを一日の可処分時間や完全なキャパシティ表示とは呼びません。
|
||||
|
||||
関連するカレンダーは最大20、各カレンダーの期間内関連は最大100、返す時間枠は全体で最大100、集中区間は最大1000件です。上限超過はpartial flag、参照不可・取得失敗はunavailable件数を返し、不完全な合計を完全な合計のように見せません。本文を表示せず、件名は現在の所有タスクから取得してtextContentで描画します。外部カレンダー内容は読まず、カレンダー拡張停止中は見積もり・集中時間のみ表示します。
|
||||
|
||||
UIは初回、手動更新、タスク/時間枠/タイマーの変更、30秒以上後のタブ復帰で取得します。定期的な全カレンダー走査は行いません。重複fetchをまとめ、非表示になれば中断します。秒単位の実績更新ではなく、更新時点の集計と明記します。
|
||||
|
||||
移行時は現在runningの区間を現行セッションから補います。旧版ですでに終了・休止した過去区間は自動バックフィルしません。旧履歴の検証付き・限定バッチ再構築はTODOです。区間は索引付きの投影ですが、その再構築機能が完成するまではDBと一緒にバックアップしてください。
|
||||
|
||||
## 5. 終了イベントとInbox
|
||||
|
||||
組み込みイベント`task.focus.complete`(定義ID `builtin.task.focus`)を既定60秒・priority -2・再試行3回で登録します。既存設定を再起動で上書きしません。設定画面で停止・間隔変更・手動実行できます。
|
||||
|
||||
最大100セッション/回、3秒上限で、`state,deadline_ms`索引から期限を迎えたrunning sessionを拾います。完了記録・監査・Inbox挿入は同じtransaction。通知の一意キーはセッションUUIDです。再実行でも二重配信しません。
|
||||
|
||||
配信時に現在のPrincipal・membership・Domain・拡張の状態を再検査します。無効なら中断扱いで通知しません。終了から24時間以上遅れたものは完了記録だけを残し、古い通知を大量配信しません。手動で終了/中断したセッションにも余分な終了通知は送りません。
|
||||
|
||||
Inboxは一般的な「タイマーが終了しました」とタスク画面へのリンクのみ。タスク本文・件名はコピーしません。ブラウザを閉じていてもサーバーが動作中なら処理しますが、終了と同時のOS通知やPushを保証する機能ではありません。既定のイベント間隔とキュー待ちによる遅延があります。
|
||||
|
||||
## 6. 検証と次段階
|
||||
|
||||
隔離fixtureで以下を検証します。実際の外部カレンダーの内容は調べません。
|
||||
|
||||
- 時間枠:時差・夏時間gap・古いタスク版・再送・月またぎ移動・予定削除・関連解除・公開/共有後の遮断・件名snapshotとメモ非複製。
|
||||
- ファイル保存後のDB更新失敗からの再試行と、外部Sourceの欠損スナップショットに到達しないguard。
|
||||
- タイマー:並列開始・版競合・休止再開・重複通知防止・通知挿入失敗のrollback・readonly・失効・拡張停止・遅れた通知の抑制。
|
||||
- PC/スマートフォンのChromium:時間枠の作成、予定へのリンク、表示のはみ出し、Pomodoro開始/休止/リロード復元。
|
||||
|
||||
残TODO(優先順):
|
||||
|
||||
1. Todayの並べ替え・前日計画の持ち越しと個人キャパシティ設定。期間別/プロジェクト別の実績、旧集中履歴の限定バッチ再構築。
|
||||
2. 個人タイマーの既定値、集中/休憩の反復と長い休憩。自動連続開始は明示設定にする。
|
||||
3. 時間枠のpending要求の監査/復旧UIを充実させる。永久失敗・tombstone・focus監査の保持/圧縮/exportを設計する。
|
||||
4. 個人通知設定とquiet hours、カレンダー予定そのものの通知。
|
||||
5. 日課テンプレート・日付別instance、前日計画の持ち越し、複数選択整理。
|
||||
|
||||
共有タスク・共同所有カレンダーへの配置・外部カレンダー読み取り・OS通知・CalDAV VTODO同期は今回の対象外です。
|
||||
@@ -0,0 +1,45 @@
|
||||
# タスク通知:予約・配信・取消
|
||||
|
||||
更新日:2026-09-25。個人タスクの期限日/計画日のInbox通知を実装。カレンダー通知、メール、OS push、集中タイマー、quiet hours、通知の集約は未実装。
|
||||
|
||||
## 操作と既定値
|
||||
|
||||
タスク編集に「期限日にInboxへ通知」「取り組む日にInboxへ通知」と時刻入力を追加する。両方とも既定OFF。通知を選択した日付が必須で、未指定の時刻は09:00。期限は引き続き日付型であり、通知時刻によって時刻付きの締切へ変換しない。プロジェクトには通知を設定しない。
|
||||
|
||||
保存時のドメイン設定のタイムゾーンをサーバー側で取得し、`reminder_timezone` に記録する。APIが指定した別のzoneを信用しない。設定画面のzone変更だけでは保存済み予約を動かさず、タスクの再保存で新しいzoneを適用する。編集画面には保存時に適用するzoneを表示する。
|
||||
|
||||
夏時間で存在しない現地時刻は保存を拒否する。重複する現地時刻はGoのタイムゾーン解決で決まる一方の時刻に固定し、二度送らない。civil date/timeとzoneから解決した発火時刻を予約に保存する。
|
||||
|
||||
## 保存と予約
|
||||
|
||||
`TaskRecord` の追加項目:`notify_due`、`notify_planned`、`reminder_time`、`reminder_timezone`。既存レコードの未指定は通知OFFとし、旧データ移行だけで通知を有効にしない。
|
||||
|
||||
`organizer_reminders` はDomain・task UUID・種類を主キーとし、owner、source version、発火時刻、civil date、zone、通知一意キー、pending/sent/skippedを保持する。`(state,fire_at_ms,...)` の索引から配信対象だけを取得する。
|
||||
|
||||
予約の作成/更新/取消は、タスクhead・履歴・専用ジャーナル・共通outboxと同じtransactionで行う。予約作成失敗で他だけがcommitされることはない。予約自体は正本から導く索引であり、共通outboxの旧イベントを使って非同期に復活させない。これにより、完了・日時変更と旧イベントの遅延配送の競合を避ける。
|
||||
|
||||
完了、取りやめ、アーカイブ、通知OFFで対応する予約を取り消す。タイトル/メモの変更ではsource versionのみ追従し、同じ通知を再送しない。日付・通知時刻・zoneの変更は新しい通知機会になる。
|
||||
|
||||
## 配信と権限
|
||||
|
||||
組み込みイベント `task.reminders.deliver`(定義ID `builtin.task.reminders`)を既定60秒間隔で実行する。最大100予約/回、処理上限3秒、priority -2、再試行3回。スケジューラの停止・同時実行数制御に従い、設定画面で間隔変更・停止・手動実行が可能。起動時に管理者の設定を上書きしない。
|
||||
|
||||
SQLite writer transactionの中で候補取得、現在版・状態、現在所有者、membership、Principal状態、Domainの有効性とlocal配置、拡張の有効性を再検査する。送信可能なのはactiveまたはreadonlyの現所有者のみ。他人の担当指定・共有配送はまだ行わない。
|
||||
|
||||
Inbox挿入と予約のsent更新は同時commit。一意キーはDomain、task UUID、種類、civil date/time、zoneから決定する。タスク版番号は一意キーに入れず、予約のsource version照合に使う。したがって件名変更・完了取消・ワーカーの再試行で、同じ機会の通知を再送しない。
|
||||
|
||||
権限失効・拡張無効化・現行版不一致の場合はskippedとし、再試行を繰り返さない。自動で遡って復活させず、再保存された現在の設定で予約を再評価する。Inboxへすでに入った通知は履歴として残すが、現在読めない件名・リンクは表示しない。
|
||||
|
||||
## 遅延と履歴
|
||||
|
||||
配信対象は発火時刻を過ぎた**同じ現地日付**の予約だけ。スケジューラ停止中などに前日以前となった分はskippedとし、古いBacklog通知を大量に送らない。日付境界直前の通知は、実行遅延で翌日に入ると送られない。時刻ぴったりの配信やOS通知を保証するものではない。
|
||||
|
||||
Inboxには一般的な通知文と対象UUIDだけを保存し、個人タスクの件名・本文を複製しない。API/通知詳細表示時に、現所有者・membership・最新予約と版を照合して現在の件名を取得する。完了/取消/日付変更などで対象予約が一致しなければ、「完了・変更済み、または現在利用できません」と表示し、taskへのリンクを外す。通知一覧の表示にCAS本文は読まない。
|
||||
|
||||
上部ナビの未読赤丸は可視タブで最大1分間隔、またはタブ復帰時に小さな問い合わせで更新する。非表示タブでは定期fetchしない。同じスクリプトが共通ヘッダーと通知ページに読み込まれてもイベントを二重登録しない。既存の「Inboxを開いたとき赤丸を消し、表示した通知を既読にする」挙動は維持する。
|
||||
|
||||
## 検証と後続
|
||||
|
||||
テスト対象:初期OFF、指定日とzoneでの予約、夏時間、存在しない時刻、日付変更・完了・取消・アーカイブ・OFF、権限失効、拡張停止、期限切れ予約、同一機会の重複防止、並列配信、予約/Inbox挿入失敗時のrollback、現時点での件名表示、別所有者への漏えい防止。ブラウザでは通知設定の保存、バックグラウンド配信後の赤丸、Inbox表示まで隔離環境で確認する。
|
||||
|
||||
次段階:個人/ドメインの通知既定値、quiet hours、集約、予約状態の詳細表示、ローカルカレンダーの時間枠との関連付け・予定通知。外部から取り込んだカレンダー内容へのアクセスは、別途許可があるまで行わない。
|
||||
@@ -0,0 +1,105 @@
|
||||
# タスク管理拡張:実装契約と次段階
|
||||
|
||||
更新日:2026-09-25。個人用タスク・プロジェクト、明示ONの期限日/計画日通知、個人ローカルカレンダーへの時間枠、永続化Pomodoroを実装。0.7.0で[日別計画・親子グループ・Wikiメモ](task-daily-notes.md)を追加(2026-09-25 07:07 JST本番反映済み)。共有・一般のカレンダー予定通知・CalDAVタスク同期の完成を意味しません。[タスク通知の契約](task-reminders.md)、[時間枠とPomodoro](task-planning-focus.md)も参照してください。
|
||||
|
||||
## 今回利用できる機能
|
||||
|
||||
2026-09-25追記:`0.8.0`で[個人タスクのCalDAV/CLI連携](task-caldav.md)を実装。専用資格情報、限定VTODO、vdirsyncer/Todoman同期、ETag/CASに対応。2026-09-26 00:24 JST本番反映済み。時刻付き期限・繰り返し・共有・フルCalDAV適合は未対応。
|
||||
|
||||
- 今日:ドメインのタイムゾーンにおける今日の計画、今日が期限または期限超過の未完了タスク。
|
||||
- 取り込み箱/Backlog/いつか:取り込んだものを消さずに整理先を変更。
|
||||
- 見直し:見直す日を迎えたもの、または30日間変更されていない未完了タスク。
|
||||
- プロジェクト:名前とメモ、関連Wiki、所属タスクの一覧。タスクは一つのプロジェクトへ所属、または未所属。
|
||||
- タスク:件名、プレーンテキストのメモ、状態、優先度、分単位の見積もり、期限、取り組む日、見直す日、関連Wiki。
|
||||
- 完了/再開、アーカイブ/復元。完了取消でも過去の版は残る。初版は物理削除を提供しない。
|
||||
- タイトル絞り込みとカーソルページング、変更履歴の版番号・日時表示。
|
||||
- 日本語/英語、既存テーマ、デスクトップの左ナビとモバイルの横ナビ・全画面編集モーダル。
|
||||
|
||||
取り組む日は日付のみであり、カレンダーの時間枠ではありません。予定イベントの複製や外部カレンダーの読み取りは行いません。プロフィールメニューの「タスク」とカレンダー画面から到達できます。
|
||||
|
||||
## URIとAPI
|
||||
|
||||
| 用途 | URI |
|
||||
| --- | --- |
|
||||
| 今日 | `/v/plan/today` |
|
||||
| 全未完了 | `/v/plan/tasks` |
|
||||
| 整理先 | `/v/plan/tasks/{inbox,backlog,someday,review,done,archived}` |
|
||||
| プロジェクト | `/v/plan/projects`、`/v/plan/project/{uuid}` |
|
||||
| タスク詳細・新規 | `/v/plan/task/{uuid}`、`/v/plan/task/-/new` |
|
||||
| API一覧・作成 | `/_/api/v1/extension/organizer.tasks/items` |
|
||||
| API取得・置換 | `/_/api/v1/extension/organizer.tasks/items/{uuid}` |
|
||||
| 最近50版の履歴 | `/_/api/v1/extension/organizer.tasks/items/{uuid}/history` |
|
||||
|
||||
`/v/plan` のカレンダー既定ビューは変更しません。既存カレンダーの広いprefixよりタスクの厳密なルートを優先します。プロジェクトは初版ではUUID URIです。pretty nameを後付けしても同一性はUUIDを維持します。
|
||||
|
||||
一覧GETは `kind=task|project`、`view`、`project`、`q`、`limit`、`before` を受け付けます。既定60件、上限100件。作成はPOST、更新はPUT、`If-Match: "{version}"` 必須。ヘッダーなしは428、古い版は412。UUIDをクライアントで生成し、同内容の作成再送は同じ版を返します。異内容の再送は競合です。成功時は `item` と現在読める `page_path`、ETagを返します。一覧はメモ本文を省略するため、編集やクイック完了前に必ず詳細を取得します。
|
||||
|
||||
## 保存と復旧の境界
|
||||
|
||||
`organizer_items` はDomain・所有者・UUID・種類・検索用メタデータ・現在版を保持します。本文を含む型付きJSONは既存Document StoreへSHA-256で保存し、同じJSONをDBにも保持します。`organizer_revisions` は版からDocumentへの参照、`organizer_changes` は後続処理用の小さな変更ジャーナルです。head更新・履歴・変更ジャーナルは同じSQLiteトランザクションです。
|
||||
|
||||
これは通常のWiki Objectではありません。Wiki Objectに直接載せると、既存の汎用閲覧・リンク操作・削除経路すべてにタスク所有権の導入が必要になるため、初版は専用の権限境界に隔離します。Wikiとの関連はPageのObject UUIDです。Pathは読むたびに同じドメイン内の閲覧可能なaliasから解決し、renameへ追従します。関連ページの権限が失効しても、タスクを読む権限がWikiを読む権限を上書きしません。
|
||||
|
||||
**タスクDBは捨てられるキャッシュではありません。** 所有権・current head・版参照を含むSQLiteとDocument Storeを一緒にバックアップします。単独ファイルから全メタデータを復元するインポート/再構築ツールは未実装です。DBロールバック前に保存されたCASファイルは孤立する場合がありますが、headには現れません。将来のCAS GCでは `organizer_revisions.document_hash` もmark対象に含める必要があります。
|
||||
|
||||
2026-09-24追記:共通outboxへの接続を実装しました。タスク/プロジェクト保存は `organizer.task.changed`/`organizer.project.changed` を同一transactionに追加します。本文・件名・期限・Wiki Pathは複写せず、対象UUID・actor・版番号・変更時刻を記録します。Cityは必要なイベント種別のみ購読し、他consumerの完了状態を変更しません。
|
||||
|
||||
旧 `organizer_changes` は削除せず、`task.activity.publish` が1回100件・3秒上限で既存記録を共通outboxへ移行します。既定60秒間隔・低優先度・再試行3回で、イベント設定画面から停止・間隔変更・手動実行が可能です。既存の設定値は再起動で上書きしません。新規保存分も同じ一意キーで確認するため二重イベントを作りません。これはデータ移行・修復用の内部ジョブで、タスク拡張のON/OFFとは独立して停止できます。通知送信やカレンダー読み取りはしません。
|
||||
|
||||
変更記録の保存は通知の配信完了ではありません。タスク期限日/計画日の予約は、正本と同一transactionで更新し、[別の配信ジョブ](task-reminders.md)で現在権限・最新状態・重複防止を検査してInboxへ送ります。移行された旧版outboxイベントから通知予約を再構築しません。汎用の購読者向け変更通知と保持期間は次段階です。[購読・復旧契約](outbox-delivery.md)も参照してください。
|
||||
|
||||
## 権限と制限
|
||||
|
||||
- 登録済みPrincipalと現ドメインの有効membershipが必須。配置先がlocalの有効Domainだけで保存・取得する。legacy認証モードでも匿名は利用不可。
|
||||
- 初版は個人所有。domain_adminも他人のタスク一覧・詳細・履歴を取得できない。
|
||||
- activeは読み書き、readonlyは読み取りのみ。失効・suspended membership・無効Domainは拒否。保存時に同じwriterトランザクションでも再検査する。
|
||||
- `organizer.tasks` は既存のシステム拡張設定で無効化可能。UI/APIを閉じ、保存層でも無効化を検査。データは削除しない。
|
||||
既存CLIの対話シェルでも `extension organizer.tasks off`/`extension organizer.tasks on` で切り替え可能。
|
||||
- Wiki関連付けは同ドメインの実在Pathと現在の読み取り権限が必要。参照先が削除・非公開化されればリンクは表示しない。
|
||||
- プロジェクトは自分の同ドメインのもののみ指定可能。アーカイブされたプロジェクトへの新たな振り分けは不可。既存の所属タスクを勝手に消したりアーカイブしない。
|
||||
- 件名300 UTF-8 bytes、メモ16 KiB、JSONリクエスト32 KiB、一覧100件、履歴50件、API処理5秒の上限。権限ごとのキャッシュを混在させずno-store。
|
||||
- メモはプレーンテキスト。HTML/JSとして実行しない。プロジェクト選択は名前で検索、最大100候補。任意の本文全件取得や全カレンダー取得は行わない。
|
||||
|
||||
## 次の実装順序
|
||||
|
||||
### T2:Backlogと協働の改善
|
||||
|
||||
- [x] アーカイブ一覧でタスク/プロジェクトを切り替え、プロジェクト詳細の設定から復元。
|
||||
- [x] 日別/明日の計画、昨日以前からの持ち越しの明示的な再割当て、親子グループ順・展開、Wikiメモの新規作成/閲覧/編集。
|
||||
- [ ] 任意の並べ替え、日別キャパシティ表示。期限を勝手に変更しない。
|
||||
- [ ] 複数選択の整理/プロジェクト振り分け、チェックリスト、保存検索、ラベル。
|
||||
- [ ] 一覧のタイトル部分一致が大規模化した場合のFTS索引。操作ごとの件数・時間・失敗数の拡張別監視。
|
||||
- [ ] 機械可読export/import、ジャーナルと版の保持・復旧手順。
|
||||
- [ ] collection単位の所有者/編集者/閲覧者。担当への指定と閲覧権限を分離。プロジェクトとWikiの権限を混同しない。
|
||||
|
||||
### T3:カレンダーと通知
|
||||
|
||||
- [x] イベント種別とconsumerごとのoutbox進捗、タスク変更の原子的な記録、既存ジャーナルの限定バッチ移行。
|
||||
- [x] 個人タスクの期限日/計画日の明示ON通知。原子的予約・取消、限定バッチでのInbox配信、現在の権限による表示。
|
||||
- [x] `organizer_time_blocks`:task UUID、calendar UUID、event UIDで関連付け。個人非公開localのみ、現在時刻・ETag取得、同一要求の再試行、関連解除。dueと時間枠を分離。
|
||||
- [x] Todayへタスクに関連した個人local時間枠を当日限定で投影。現在の予定日時で集計し、重複・件数制限・参照不可を明示。外部取り込み内容は扱わない。
|
||||
- [ ] カレンダー通知を共通Inboxへ追加。タスク分の予約更新/取消・権限再検査は実装済み。
|
||||
- [x] タスク通知は発火時刻索引から最大100件を取得。一意キーは通知機会(日付・時刻・zone・種類)、版番号は現在版照合に使う。タイトル変更では再送しない。
|
||||
- [ ] 通知設定:ドメイン既定+個人既定+個別上書き、quiet hours、過去の大量未配信は要約、Inboxと赤丸の挙動は既存設計へ統一。
|
||||
|
||||
### T4:Pomodoro・日課
|
||||
|
||||
- [x] focus sessionをタスクから独立した記録にし、開始/休止/再開/終了/中断を監査。1ユーザー1つのactive sessionを条件付き更新で保証。
|
||||
- [x] ブラウザ表示はサーバーの終了予定時刻・残時間から復元し、毎秒DB書き込みをしない。別端末・リロード・バックグラウンドで継続可能。終了は組み込みイベントからInboxへ通知。
|
||||
- [x] 集中25分/休憩5分の初期値を画面で変更。通知はInboxのみで、OS通知はしない。
|
||||
- [x] Todayに未完了タスク見積もり・時間枠・記録済み集中時間を別集計。休止・休憩を除外し、日付またぎを分割。
|
||||
- [ ] 個人既定値・反復サイクル・長い休憩、期間別実績、旧集中履歴の限定バッチ再構築。
|
||||
- [ ] 日課テンプレートと日付別instance。完了から次回生成するルールは一意キーで再実行可能にする。繰り返しタスクを単一レコードの日時上書きで消費しない。
|
||||
|
||||
### T5:標準連携・高度な管理
|
||||
|
||||
- [x] 個人タスクの限定VTODO/CalDAV、専用資格情報UI/API、vdirsyncer/Todoman同期試験。カレンダーVEVENTの完了とタスク完了を同一視しない。[契約・残件](task-caldav.md)。
|
||||
- [ ] 時刻付き期限・繰り返し・共有・sync-token・追加クライアントの互換性。
|
||||
- [ ] 親子タスク/依存循環検出、週次レビュー、チケットqueue/受付番号/workflow。
|
||||
- [ ] モバイルのオフラインキューと競合UI、ショートカット、押下しやすい複数操作。
|
||||
|
||||
## 受け入れ試験
|
||||
|
||||
`internal/server/tasks_test.go` は個人/Domain境界、readonly・membership失効、kill switch、版競合、作成再送、完了取消の履歴、保存途中のロールバック、日付検証、ページング、プロジェクト参照、Wiki rename追従を検証します。
|
||||
|
||||
`PAGESWIKI_BROWSER_TEST=1` の `TestTasksChromium` は隔離されたDB・HTTPサーバーでデスクトップ/モバイルの実操作を検証します。運用中の外部カレンダー・予定本文にはアクセスしません。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 13. タスクとチケット
|
||||
|
||||
状態:個人用local taskとプロジェクト、期限日/計画日のInbox通知、個人ローカルカレンダーへの時間枠、永続化Pomodoroを実装(2026-09-25)。個人タスクの限定CalDAV/CLI同期は0.8.0で実装・隔離試験済み、2026-09-26 00:24 JST本番反映済み。共有、チケット、一般のカレンダー予定通知、繰り返し・差分CalDAV同期は設計段階です。[実装契約と次段階](tasks-implementation.md)、[時間枠とPomodoro](task-planning-focus.md)、[CalDAV/CLI](task-caldav.md)を参照してください。
|
||||
|
||||
## 二つの用途
|
||||
|
||||
タスクは「誰が何をいつまでにするか」。チケットは受付番号、責任者、状態遷移、履歴、問い合わせや障害等の業務上の単位です。チケットをそのままカレンダー予定にしません。
|
||||
|
||||
第一案は共通work itemを基盤に、task viewとticket workflowを分けます。チケット固有の公開範囲・番号・遷移が複雑になれば専用表へ分離しますが、認証やコメントは共通基盤を再利用します。
|
||||
|
||||
## データ案
|
||||
|
||||
- 共通:UUID、Domain、collection、kind、title、body_page_uuid、creator、assignee、version、created/updated、archive状態。
|
||||
- タスク:status、priority、start/due、完了日時、checklist、parent task、dependency。
|
||||
- チケット:queue UUID、queue内の単調な受付番号、workflow版、type、labels、watchers、resolution。
|
||||
- 添付:固定Document参照と出典。コメント:共通thread。変更履歴:actor付きevent。
|
||||
|
||||
Path、受付番号、題名はidentityではありません。同じPageに複数work itemが関連しても、暗黙に一つへ統合しません。assignee表示とPrincipalの権限付与も別です。
|
||||
|
||||
## 状態と操作
|
||||
|
||||
最初のtaskはtodo / doing / done / cancelledとし、遷移を監査します。未完了への復帰で元の完了記録を消さず、履歴を残します。チケットはopen / in_progress / resolved / closedを案とし、reopen権限、完了理由、受付担当と解決担当を後で分けられる構造にします。
|
||||
|
||||
create/read/update/assign/transition/comment/manageは概念上分離します。外部依頼者には自分のチケットだけを見せる場合があるため、queue一覧の閲覧とticketの閲覧を分けます。担当にしただけで非公開本文が読めるようにしません。
|
||||
|
||||
## 期限・依存・繰り返し
|
||||
|
||||
期限は日付だけか時刻付きかを明示します。日付のみをUTC午前0時へ変換しません。依存は循環を拒否し、削除済み・閲覧不可の依存先の詳細を表示しません。親子進捗の自動集計は別projectionです。
|
||||
|
||||
繰り返しは第二段階。完了時に次のinstanceを作る方式と、iCalendar recurrenceを扱う方式の対応を先に決めます。完了イベントの二重配送で次回タスクが二つ増えない鍵を必要とします。
|
||||
|
||||
## CalDAVとの関係
|
||||
|
||||
iCalendarにはVTODOがあり、CalDAVはカレンダー資源を扱います。ただしクライアントごとのタスク・繰り返し対応を試験する必要があります。これは「CalDAVだけでチケット管理が完成する」という意味ではありません。[iCalendar](https://www.rfc-editor.org/rfc/rfc5545)、[CalDAV](https://www.rfc-editor.org/rfc/rfc4791)。
|
||||
|
||||
最初はlocal task一覧と期限表示、次にVTODOの明示export/import、最後に選定クライアントとの同期を検討します。workflow、コメント、細かな権限をVTODOへ無理に押し込みません。失われる情報を変換警告に残します。
|
||||
|
||||
## 実装TODO
|
||||
|
||||
- TASK-1:個人local作成/取得/更新、version競合、Page参照、所有者限定一覧は実装済み。削除は復元可能なアーカイブ、物理削除は未提供。
|
||||
- TASK-2:日付の期限/計画/見直し、タイトルフィルタ、archive、個別ONのInbox通知は実装済み。担当共有、通知集約、exportは未実装。
|
||||
- TASK-3:checklist/依存とboundedな一覧・calendar射影。
|
||||
- TICKET-1:queue・番号予約・workflow版・権限付き遷移。
|
||||
- TASK-4:VTODO fixture、未対応property保持、繰り返し・同期の判断。
|
||||
|
||||
同時採番、二重POST、完了取消、夏時間・終日、assignee失効、本文削除を受け入れ試験にします。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 7. ビューア・エディタ・連携アダプタ
|
||||
|
||||
状態:主要形式のビューアとホスト型エディタあり。ネイティブ起動・任意外部コード実行は保留。
|
||||
|
||||
## 正本と表示
|
||||
|
||||
文章はHTMLを正本にし、Markdownは編集・import形式として変換します。Office、PDF、画像、音声、動画、Canvas等のバイナリ・固有形式をすべてHTMLへ不可逆変換する意味ではありません。MIME、拡張子、限定された内容判定でProjectionを選びます。
|
||||
|
||||
拡張子のないテキストも文字コードと先頭内容を限定的に調べます。長いTXT/JSONは部分取得し、行番号・syntax highlight・ミニマップ等はブラウザのDOMやメモリ上限の中で動かします。
|
||||
|
||||
## 対応領域
|
||||
|
||||
CSV、コード、PDF、画像lightbox、音声・動画、ZIP等のarchive、コミック、EML、DEB/PEのメタデータ、Excalidraw等に初期実装があります。Office全般の完全再現や任意archiveの無制限展開を保証するものではありません。
|
||||
|
||||
PDFページ数・archiveメタデータ・サムネイルは原則キューで生成し、未生成ならアイコン・待機状態を返します。一部のentry展開はまだ限定された前景処理で、キャッシュ付き生成への移行が必要です。
|
||||
|
||||
## 連携アダプタ
|
||||
|
||||
アダプタはDocumentの表示・編集を担当します。MIME、対応操作、設定schema、外部origin、リソース上限を宣言します。ランキングやメール収集はアダプタではなくシステム拡張です。
|
||||
|
||||
code-server、vim.wasm等はホスト型連携として扱います。workspaceへの配下展開、HTML/Markdown変換、保存競合、短命なsessionをホスト側で制御し、通常のログインcredentialをそのまま渡しません。vim.wasmのruntime改善は現在保留です。ネイティブvim.exe等への直接受け渡しも保留し、補助アプリ不要で自由起動できるとは扱いません。
|
||||
|
||||
## HTMLの安全性
|
||||
|
||||
Viewer・履歴・印刷・Editor previewはinert allowlistを使い、保存されたscript/style/iframeを通常ページの権限で実行しません。正本バイト列を勝手に変更せず、表示段階の安全化として区別します。埋め込みは登録済みproviderとsandboxによる明示契約が必要です。
|
||||
|
||||
## ビューアのキーボード操作
|
||||
|
||||
通常のViewerでは、`e` 編集、`f` 検索、`v` 表示形式切替、`c` 配下への新規作成、`u` アップロード、`s` 共有リンク、`p` 権限導線を使えます。`Ctrl+↑` は親Path、`Ctrl+↓` は配下一覧、`Ctrl+→` / `Ctrl+←` は前後ページです。入力欄・select・textarea・contenteditable・開いているdialogではショートカットを停止します。
|
||||
|
||||
共有リンクは現在の正規URLをコピーし、X Web Intentをユーザー操作で開く方式です。これは公開権限を付与したり、未公開Pageを自動公開したりしません。権限ダイアログがその画面にない場合、City governanceの案内だけを表示します。
|
||||
|
||||
## Macroと変換の二つのモード
|
||||
|
||||
編集用のHTML→Markdownではchildren等のmacro宣言を保持します。表示・preview・export向けのProjectionでは認可済みの結果を展開します。展開された一覧を保存本文へ逆流させないことがround-tripの条件です。
|
||||
|
||||
## TODO
|
||||
|
||||
変換provider/version・警告・原本保持、未対応構文の欠落検知、draw.io・nwdiag等の統合、widgetの許可・同意・CSP、decoder隔離、プラグイン停止時の安全なfallback。HTML編集の段階的改善は第17章で具体化します。nwdiagはネットワーク構成を記述するソースと、静的SVG/画像としてのProjection、明示的な編集アダプタを分離して設計します。
|
||||
@@ -0,0 +1,502 @@
|
||||
# Knowledge City Model Detailed Design
|
||||
|
||||
Implementation review (2026-09-13): see
|
||||
[City review and URL-driven reconciliation](city-review-and-reconciliation.md)
|
||||
for verified gaps and the repair checklist. Authorization, geometry and cache
|
||||
requirements here are design targets, not claims that every current code path
|
||||
already satisfies them.
|
||||
|
||||
Label follow-up (2026-09-13): the current map shows its active level's labels
|
||||
without hover. Street names are horizontal text anchored to their roads (no
|
||||
textPath rotation), including in the Street detail view. Hover/focus retains
|
||||
road highlighting; the explicit Labels toggle hides/shows the current renderer's
|
||||
labels. Normal and popup views have Chromium regressions using vertical/diagonal
|
||||
road fixtures. This does not implement the broader event/Worker/UI repair plan.
|
||||
|
||||
## Purpose
|
||||
|
||||
The [manual organization UI](city-organization-ui.md) supports display-title
|
||||
edits, multi-selection, Spot merging and Street relocation. These preserve
|
||||
document URLs and use explicit Page memberships when the new boundary differs.
|
||||
Spot nesting remains invalid; use a Street parent or merge into another Spot.
|
||||
|
||||
Knowledge City is a human navigation and governance model over the existing
|
||||
Domain, Page UUID, Revision, Document, and semantic-path planes. It must make a
|
||||
large body of knowledge understandable, maintainable, and traversable without
|
||||
turning the database back into a filesystem.
|
||||
|
||||
```text
|
||||
Campus administrative federation and defaults
|
||||
Domain host-selected namespace and policy boundary
|
||||
Quartier planned knowledge district and policy boundary
|
||||
Street operational sequence of nearby Spots
|
||||
Spot smallest semantic locality and Page graph root
|
||||
Page reusable knowledge object
|
||||
Revision immutable historical representation
|
||||
```
|
||||
|
||||
The city hierarchy answers “where is this knowledge curated?” The SpotGraph
|
||||
answers “what else is semantically connected?” Semantic paths answer “how can
|
||||
this Page currently be reached?” These are separate questions.
|
||||
|
||||
## Design principles
|
||||
|
||||
1. **Locality is not identity.** Zone, Spot, Page, and Revision have distinct
|
||||
UUIDs. Moving a Page or Spot never changes Page identity or history.
|
||||
2. **Tree for orientation, graph for knowledge.** Quartier and Street form the
|
||||
ZoneTree. Street points to Spots. Spots form a graph and point to Pages.
|
||||
3. **One planned placement, many semantic appearances.** A Spot has one primary
|
||||
Street placement. A Page may belong to many Spots and is a MagicPage when it
|
||||
does. Shortcuts do not create a second primary placement.
|
||||
4. **Path is a projection with a City boundary.** City placement does not
|
||||
replace UUID identity, but each Quartier, Street, and Spot binds one semantic
|
||||
Path prefix used as its primary jurisdiction. Path moves change inferred
|
||||
locality without changing Page identity or history.
|
||||
5. **Governance follows locality.** Capability defaults may flow Domain →
|
||||
Quartier → Street → Spot. Exceptional Page grants remain explicit. Publication
|
||||
ceilings are restrictive intersections, not overridable defaults: subordinate
|
||||
owners cannot widen superior limits. See [owners and publication](locality-publication-ownership.md).
|
||||
6. **No destructive topology cascade.** Archiving a Zone or Spot does not delete
|
||||
Pages, Revisions, Documents, path bindings, or external links.
|
||||
7. **Planning changes are auditable.** Structural operations are transactional,
|
||||
versioned, previewable, and reversible where identity permits.
|
||||
8. **Language-neutral structure.** Machine names and UUIDs are language-neutral;
|
||||
titles, descriptions, signage, and landing copy may be localized.
|
||||
|
||||
## Quartier
|
||||
|
||||
A Quartier is a deliberately planned aggregation of Streets. It is the largest
|
||||
knowledge-locality boundary below a Domain and exists to make policy and
|
||||
navigation comprehensible at scale.
|
||||
|
||||
### Required functions
|
||||
|
||||
- stable UUID, language-neutral machine name, localized title/description;
|
||||
- charter: purpose, intended audience, inclusion/exclusion criteria;
|
||||
- boundary: owned child Streets; Quartier nesting is not allowed initially;
|
||||
- zoning policy defaults: visibility, curation workflow, retention, templates,
|
||||
language fallback, navigation and search defaults;
|
||||
- governance: curator groups, approval roles, escalation owner and contacts;
|
||||
- explicit Quartier/Spot owner appointments and scoped publication administration,
|
||||
bounded by superior ceilings; ownership does not grant document editing;
|
||||
- entrances: landing projection, featured Spots, announcements and guides;
|
||||
- signage: aliases, keywords, icon/color, breadcrumb label and external links;
|
||||
- scoped search, recent changes, activity feed and subscription;
|
||||
- map and health dashboard for Streets, Spots, orphan Pages and broken links;
|
||||
- lifecycle: draft, active, deprecated, archived;
|
||||
- planning operations: reorder, move Street, merge Quartiers, split Quartier,
|
||||
preview plan, apply transaction, record topology revision;
|
||||
- export/import of topology metadata without copying Page Documents by default.
|
||||
|
||||
Quartier is not created merely because a Street has many children. Promotion is
|
||||
an explicit planning decision with a charter and redistribution plan.
|
||||
|
||||
## Street
|
||||
|
||||
A Street is the smallest ordered Zone and groups nearby Spots for day-to-day
|
||||
navigation. It represents an understandable route through related localities,
|
||||
not a permissionless directory.
|
||||
|
||||
### Required functions
|
||||
|
||||
- stable UUID, machine name and localized signage;
|
||||
- exactly one parent Quartier in the first implementation;
|
||||
- ordered Spot placements with optional sections and featured entrances;
|
||||
- Street-level policy overrides and curator assignment;
|
||||
- Street landing, compact/detail/map views and scoped search;
|
||||
- activity, vacant/overgrown indicators and maintenance queue;
|
||||
- move, reorder, merge, split and deprecate operations;
|
||||
- a documented route intent such as lifecycle, architecture layer, product
|
||||
area, department workflow, or learning sequence.
|
||||
|
||||
An unconsolidated Street may temporarily contain loose Page placements. These
|
||||
are not silently treated as Spots. The UI exposes them as an Inbox requiring a
|
||||
curator to create/select a Spot. The Street remains marked `unconsolidated`
|
||||
until the Inbox is empty.
|
||||
|
||||
### Street-to-Quartier promotion
|
||||
|
||||
Promotion preserves the Zone UUID but changes its kind only through a plan:
|
||||
|
||||
1. preview affected Spot placements, links, policies and aliases;
|
||||
2. define at least one child Street and partition all existing Spots;
|
||||
3. validate names, capabilities and destination conflicts;
|
||||
4. atomically change kind, create child Streets and move placements;
|
||||
5. increment topology version and retain an audit/reversal record.
|
||||
|
||||
A Quartier cannot directly own Spots after the transaction.
|
||||
|
||||
## Spot
|
||||
|
||||
A Spot is the smallest semantic knowledge locality. It is large enough to have
|
||||
its own purpose, curators, Page membership and capability boundary, but it never
|
||||
contains child Spots and cannot be promoted into a Street. An overgrown Spot is
|
||||
split into multiple Spots or has Pages moved/linked elsewhere.
|
||||
|
||||
### Required functions
|
||||
|
||||
- stable UUID, machine name, localized title, summary and curator contacts;
|
||||
- one primary Street placement and lifecycle state;
|
||||
- charter and optional content schema/template;
|
||||
- generated landing projection independent of any one Page;
|
||||
- ordered Page membership with typed edges:
|
||||
`primary`, `guide`, `reference`, `example`, `attachment`, `related`;
|
||||
- Page pinning, featuring, manual ordering and query-backed dynamic sections;
|
||||
- typed Spot-to-Spot relations:
|
||||
`related`, `depends_on`, `supersedes`, `implements`, `learn_before`,
|
||||
`operated_by`;
|
||||
- backlinks, inbound/outbound relation view and shortest knowledge route;
|
||||
- scoped search, activity stream, watchers and change digest;
|
||||
- capability requirements and curator workflow;
|
||||
- health indicators: empty, orphaned, stale, duplicate, overgrown, broken,
|
||||
unreviewed and language-gap;
|
||||
- split, merge, move and archive operations that preserve Pages;
|
||||
- a machine-readable context payload for macros, adapters and future agents.
|
||||
|
||||
Spot membership is a graph edge, not a path link. Adding a Page to a second Spot
|
||||
creates a MagicPage appearance and does not clone its Revisions. Removing the
|
||||
last Spot edge leaves the Page as an orphan candidate but does not delete it.
|
||||
|
||||
## Page placement and MagicPage behavior
|
||||
|
||||
### Semantic Path jurisdiction
|
||||
|
||||
Each active locality binds a normalized, language-neutral Path prefix. A
|
||||
Street prefix must be a strict descendant of its parent Quartier prefix, and a
|
||||
Spot prefix must be a strict descendant of its Street prefix. Boundaries at the
|
||||
same level may not overlap, preventing ambiguous primary locality.
|
||||
|
||||
For example, `/life`, `/life/home`, and `/life/home/kitchen` may bind Quartier
|
||||
`life`, Street `home`, and Spot `kitchen`. Every Page Path below the Spot prefix
|
||||
is inferred as a primary member of that Spot. Pages below only a Street or
|
||||
Quartier remain in that locality's unconsolidated scope until a Spot boundary
|
||||
is planned. Exact and descendant matching is segment-aware, so `/life2` is not
|
||||
inside `/life`.
|
||||
|
||||
This inferred primary membership is evaluated from current Path bindings and
|
||||
is not persisted as Page identity. Explicit `spot_pages` edges remain semantic
|
||||
appearances; they can place the same Page in additional Spots as a MagicPage.
|
||||
An explicit edge takes presentation precedence over an inferred edge within
|
||||
the same Spot. Renaming a Page Path may therefore change its inferred primary
|
||||
locality but never its UUID, revisions, or explicit MagicPage appearances.
|
||||
|
||||
`spot_pages` records why and how a Page appears. The same Page can be primary in
|
||||
one Spot and a reference in another. Each Spot controls its own label, order and
|
||||
visibility of the edge; it does not override Page title/content globally.
|
||||
|
||||
Viewer responses may expose all other Spot appearances only when the caller can
|
||||
read those Spots. Search and breadcrumbs never leak inaccessible locality names
|
||||
or result counts. Cross-Domain appearances are absolute external references
|
||||
containing the destination FQDN; a local Spot edge never pretends to own a
|
||||
remote Page UUID.
|
||||
|
||||
## Topology schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE zones (
|
||||
uuid TEXT PRIMARY KEY,
|
||||
domain_uuid TEXT NOT NULL,
|
||||
kind TEXT NOT NULL, -- quartier, street
|
||||
parent_uuid TEXT, -- NULL for Quartier; Quartier UUID for Street
|
||||
name TEXT NOT NULL,
|
||||
title TEXT NOT NULL DEFAULT '',
|
||||
description TEXT NOT NULL DEFAULT '',
|
||||
charter_json TEXT NOT NULL DEFAULT '{}',
|
||||
policy_json TEXT NOT NULL DEFAULT '{}',
|
||||
state TEXT NOT NULL DEFAULT 'draft',
|
||||
sort_key INTEGER NOT NULL DEFAULT 0,
|
||||
version INTEGER NOT NULL DEFAULT 1,
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
updated_at_ms INTEGER NOT NULL,
|
||||
UNIQUE(domain_uuid, parent_uuid, name)
|
||||
);
|
||||
|
||||
CREATE UNIQUE INDEX idx_zones_quartier_name
|
||||
ON zones(domain_uuid, name) WHERE kind = 'quartier';
|
||||
|
||||
CREATE TABLE zone_localizations (
|
||||
zone_uuid TEXT NOT NULL,
|
||||
lang TEXT NOT NULL,
|
||||
title TEXT NOT NULL,
|
||||
description TEXT NOT NULL DEFAULT '',
|
||||
PRIMARY KEY(zone_uuid, lang)
|
||||
);
|
||||
|
||||
CREATE TABLE spots (
|
||||
uuid TEXT PRIMARY KEY,
|
||||
domain_uuid TEXT NOT NULL,
|
||||
name TEXT NOT NULL,
|
||||
title TEXT NOT NULL DEFAULT '',
|
||||
summary TEXT NOT NULL DEFAULT '',
|
||||
charter_json TEXT NOT NULL DEFAULT '{}',
|
||||
schema_json TEXT NOT NULL DEFAULT '{}',
|
||||
landing_json TEXT NOT NULL DEFAULT '{}',
|
||||
state TEXT NOT NULL DEFAULT 'draft',
|
||||
version INTEGER NOT NULL DEFAULT 1,
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
updated_at_ms INTEGER NOT NULL,
|
||||
UNIQUE(domain_uuid, name)
|
||||
);
|
||||
|
||||
CREATE TABLE street_spots (
|
||||
street_uuid TEXT NOT NULL,
|
||||
spot_uuid TEXT NOT NULL UNIQUE, -- one primary Street placement
|
||||
sort_key INTEGER NOT NULL DEFAULT 0,
|
||||
section TEXT NOT NULL DEFAULT '',
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
PRIMARY KEY(street_uuid, spot_uuid)
|
||||
);
|
||||
|
||||
CREATE TABLE spot_pages (
|
||||
spot_uuid TEXT NOT NULL,
|
||||
page_uuid TEXT NOT NULL,
|
||||
edge_type TEXT NOT NULL DEFAULT 'primary',
|
||||
label TEXT NOT NULL DEFAULT '',
|
||||
sort_key INTEGER NOT NULL DEFAULT 0,
|
||||
featured INTEGER NOT NULL DEFAULT 0,
|
||||
source TEXT NOT NULL DEFAULT 'local',
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
PRIMARY KEY(spot_uuid, page_uuid, edge_type)
|
||||
);
|
||||
|
||||
CREATE TABLE spot_relations (
|
||||
source_spot_uuid TEXT NOT NULL,
|
||||
target_spot_uuid TEXT NOT NULL,
|
||||
relation_type TEXT NOT NULL,
|
||||
weight REAL NOT NULL DEFAULT 1.0,
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
PRIMARY KEY(source_spot_uuid, target_spot_uuid, relation_type)
|
||||
);
|
||||
|
||||
CREATE TABLE street_inbox_pages (
|
||||
street_uuid TEXT NOT NULL,
|
||||
page_uuid TEXT NOT NULL,
|
||||
created_at_ms INTEGER NOT NULL,
|
||||
PRIMARY KEY(street_uuid, page_uuid)
|
||||
);
|
||||
|
||||
CREATE TABLE topology_events (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
domain_uuid TEXT NOT NULL,
|
||||
topology_version INTEGER NOT NULL,
|
||||
actor_principal_uuid TEXT NOT NULL,
|
||||
operation TEXT NOT NULL,
|
||||
target_type TEXT NOT NULL,
|
||||
target_uuid TEXT NOT NULL,
|
||||
before_json TEXT NOT NULL DEFAULT '{}',
|
||||
after_json TEXT NOT NULL DEFAULT '{}',
|
||||
request_id TEXT NOT NULL DEFAULT '',
|
||||
created_at_ms INTEGER NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
Foreign-key-like invariants are enforced transactionally during compatibility
|
||||
migration and later promoted to SQLite foreign keys when legacy tables can be
|
||||
rebuilt safely. Every Domain has a monotonically increasing topology version.
|
||||
|
||||
## Structural invariants
|
||||
|
||||
- a Zone belongs to exactly one Domain;
|
||||
- a Street has exactly one parent Quartier;
|
||||
- a Quartier is directly owned by its Domain and contains Streets, never other
|
||||
Quartiers or Spots;
|
||||
- a Street points to Spots and temporary Inbox Pages, never child Zones;
|
||||
- a Spot has at most one primary Street placement and no child Spot;
|
||||
- Spot and Page on an edge belong to the same local Domain unless the edge is an
|
||||
explicit external reference;
|
||||
- ZoneTree is acyclic and bounded in depth;
|
||||
- `depends_on` and `learn_before` cycles are rejected or explicitly marked;
|
||||
- the last Page/Spot edge removal never cascades to Page deletion;
|
||||
- archived nodes cannot accept new children or edges;
|
||||
- names are normalized and unique only in their declared scope; UUID is the
|
||||
stable reference used by APIs and relations.
|
||||
|
||||
## Policy inheritance
|
||||
|
||||
The effective policy is evaluated in this order:
|
||||
|
||||
```text
|
||||
Domain defaults
|
||||
-> Quartier policy
|
||||
-> Street override
|
||||
-> Spot requirement
|
||||
-> exceptional Page/Object grant
|
||||
```
|
||||
|
||||
Policies remain positive-grant based. A lower locality can require a narrower
|
||||
capability but does not manufacture authority. Curator status is separate from
|
||||
read/write authority, just as group administration is separate from content
|
||||
permissions. Moving a Spot previews any effective-policy change before commit.
|
||||
|
||||
## Human-facing projections
|
||||
|
||||
Knowledge City uses explicit projections so it does not capture ordinary Page
|
||||
paths:
|
||||
|
||||
| Route | Projection |
|
||||
| --- | --- |
|
||||
| `/v/city` | Domain city map and directory |
|
||||
| `/v/city/q/{quartier-name}` | Quartier detail |
|
||||
| `/v/city/s/{quartier-name}/{street-name}` | Parent-qualified Street detail |
|
||||
| `/v/city/p/{spot-name}` | Spot detail and readable Page links |
|
||||
| `/v/city/{q,s,p}/uuid:{uuid}` | Explicit identity selector, stable across renames |
|
||||
| `/v/city?{quartier,street,spot}={uuid}` | Focus that locality in the map |
|
||||
| `/v/city/changes` | Planned authorized topology activity (not implemented) |
|
||||
|
||||
Human links use names; mutation APIs use UUIDs. Legacy `/v/city/s/{name}`
|
||||
resolves only a Domain-unique Street name; ambiguous names return 404 rather
|
||||
than selecting an arbitrary parent. Bare UUID-looking names are not UUID
|
||||
selectors. Named URLs follow current names/parents, not historical redirects.
|
||||
A Spot
|
||||
landing can bind an ordinary semantic path when desired; that binding is an
|
||||
explicit, conflict-checked operation.
|
||||
|
||||
Viewer breadcrumbs can offer two independent trails:
|
||||
|
||||
- semantic path breadcrumbs;
|
||||
- city locality breadcrumbs (Quartier → Street → Spot).
|
||||
|
||||
For MagicPages the UI shows the current Spot trail and an authorized “also in”
|
||||
list. It never chooses a fake universal parent.
|
||||
|
||||
## Search, discovery and knowledge routes
|
||||
|
||||
Search accepts locality scopes (`domain`, `quartier`, `street`, `spot`) and
|
||||
filters authorization before aggregation. Results can use list, detail and
|
||||
thumbnail projections already shared by children/search UI.
|
||||
|
||||
City discovery adds:
|
||||
|
||||
- nearby knowledge from shared Spot and typed Spot relations;
|
||||
- curated routes and learning sequences;
|
||||
- “missing entrance”, “orphan Page”, “empty Spot”, and stale-area reports;
|
||||
- Page-to-Page route explanation through Spot membership/relation edges;
|
||||
- subscriptions to a Spot, Street or Quartier activity stream;
|
||||
- stable topology context for adapters and future retrieval/agent workloads.
|
||||
|
||||
Recommendations never silently alter topology. Dynamic/query-backed sections
|
||||
are projections; curator-approved edges are canonical topology.
|
||||
|
||||
## Macros
|
||||
|
||||
Macros read topology through bounded cached projections:
|
||||
|
||||
```text
|
||||
{{city}}
|
||||
{{quartier}}
|
||||
{{street}}
|
||||
{{spot}}
|
||||
{{spot-pages edge="guide" view="icon"}}
|
||||
{{nearby relation="depends_on"}}
|
||||
{{city-breadcrumbs}}
|
||||
```
|
||||
|
||||
With no explicit UUID, a macro uses the current authorized locality context.
|
||||
Macro output is asynchronous where expensive, contains no unauthorized counts,
|
||||
and is keyed by Domain topology version plus Principal policy version.
|
||||
|
||||
## API surface
|
||||
|
||||
```text
|
||||
GET,POST /_/api/v1/city/zones
|
||||
GET,PATCH,DELETE /_/api/v1/city/zones/{uuid}
|
||||
POST /_/api/v1/city/zones/{uuid}/move
|
||||
POST /_/api/v1/city/streets/{uuid}/promote
|
||||
GET,POST /_/api/v1/city/spots
|
||||
GET,PATCH,DELETE /_/api/v1/city/spots/{uuid}
|
||||
GET,POST,DELETE /_/api/v1/city/spots/{uuid}/pages
|
||||
GET,POST,DELETE /_/api/v1/city/spots/{uuid}/relations
|
||||
GET,POST,DELETE /_/api/v1/city/streets/{uuid}/inbox
|
||||
GET /_/api/v1/city/map
|
||||
GET /_/api/v1/city/health
|
||||
GET /_/api/v1/city/events
|
||||
POST /_/api/v1/city/plans/preview
|
||||
POST /_/api/v1/city/plans/apply
|
||||
```
|
||||
|
||||
Mutations use UUIDs, ETag/version preconditions, idempotency keys for bulk
|
||||
plans, CSRF for cookie sessions and topology-targeted capabilities. Preview and
|
||||
apply use the same validated plan payload; apply rejects a changed topology
|
||||
version.
|
||||
|
||||
## Caching and indexing
|
||||
|
||||
- ZoneTree adjacency and breadcrumb cache: keyed by Domain topology version;
|
||||
- SpotGraph adjacency: keyed by Spot version and authorization policy version;
|
||||
- FTS locality fields: localized title, summary, charter keywords and permitted
|
||||
Page content;
|
||||
- health metrics: scheduler jobs with low priority and incremental invalidation;
|
||||
- map/layout/thumbnail: derived cache, never source of truth;
|
||||
- foreground navigation always outranks topology analysis and preview work.
|
||||
|
||||
### City geometry adapter
|
||||
|
||||
Map geometry is a derived projection behind a replaceable `City Geometry
|
||||
Adapter`; it is never topology identity. The built-in adapter accepts the
|
||||
authorized City Map projection and emits Quartier polygons, Street curves and
|
||||
Spot building lots. Generation is deterministic from Domain UUID, topology
|
||||
version and the ordered topology signature. Browser caches are versioned and
|
||||
bounded, so navigation never waits for background geometry generation.
|
||||
|
||||
An external town generator may replace this adapter when it returns the same
|
||||
neutral geometry contract. Generator-specific IDs must not enter Zone, Spot,
|
||||
Page or Path identity. A later persisted layout layer may pin curator-adjusted
|
||||
coordinates independently of regenerated background parcels.
|
||||
|
||||
The generator runs once per Domain topology version. Its single road/building
|
||||
fabric is partitioned into contiguous Quartier regions rather than generating
|
||||
and stitching independent towns. Region targets use unique Page UUID weights:
|
||||
Path/primary `1.0`, guide `0.7`, example `0.5`, attachment `0.25`, and
|
||||
reference/related `0.15`. Repeated paths and MagicPage appearances therefore
|
||||
do not multiply physical area. Street road capacity uses the summed weighted
|
||||
Spot membership, while Spots are assigned to buildings nearest their Street
|
||||
segments. Minimum shares prevent empty or new localities from disappearing.
|
||||
|
||||
Allocation is absolute as well as relative. Weighted Page demand determines
|
||||
the occupied fraction of the generated City; unallocated roads and buildings
|
||||
remain visible but have no Knowledge City owner. Quartiers divide only the
|
||||
occupied region. A Street receives roughly 1.5 generated road segments per
|
||||
weighted Page, with a one-segment minimum, rather than consuming every road in
|
||||
its Quartier. Only when demand approaches generated capacity may the planned
|
||||
localities fill most of the map.
|
||||
|
||||
## Federation and inheritance
|
||||
|
||||
The Domain owning a topology is authoritative. Controller-managed Campus
|
||||
manifests may place or replicate its definition, but two instances do not
|
||||
concurrently edit the same topology without an explicit leader and sequence.
|
||||
Domain PSK identity/group inheritance does not automatically inherit ZoneTree or
|
||||
SpotGraph. A later topology peer policy must opt in separately.
|
||||
|
||||
Cross-Domain Spot relations carry destination FQDN, Domain UUID, remote Spot
|
||||
UUID and last verified instance fingerprint. They degrade to external links
|
||||
when offline and never create a local writable clone.
|
||||
|
||||
## Lifecycle and maintenance
|
||||
|
||||
Creation starts in `draft`; activation requires valid placement, charter and
|
||||
curator. Deprecation supplies a successor and signage. Archive removes the node
|
||||
from default navigation but preserves stable UUID access for authorized audit.
|
||||
Purge is exceptional, Domain-admin-only, requires no structural references and
|
||||
does not purge Pages.
|
||||
|
||||
Health rules are advisory except for structural invariants. Suggested initial
|
||||
thresholds are configurable per Domain rather than hard-coded: Page count,
|
||||
staleness interval, broken-link ratio, missing language and unreviewed changes.
|
||||
|
||||
## Delivery plan
|
||||
|
||||
1. Add topology schema, Domain topology version, stores and invariant tests.
|
||||
2. Implement Quartier/Street CRUD, map projection and capability target
|
||||
resolvers; no automatic path rewrite.
|
||||
3. Implement Spot CRUD, primary Street placement and generated landing.
|
||||
4. Implement SpotPage/MagicPage edges, authorized “also in”, backlinks and
|
||||
city breadcrumbs.
|
||||
5. Add Spot relations, scoped search, nearby knowledge and route explanation.
|
||||
6. Add planning preview/apply, Street promotion, split/merge and audit events.
|
||||
7. Add health scheduler, maintenance queues, subscriptions and topology macros.
|
||||
8. Add optional signed topology federation only after single-authority behavior
|
||||
and rollback are proven.
|
||||
|
||||
Each slice requires migration rollback, cross-Domain isolation, authorization,
|
||||
cycle, concurrent-version and cache-invalidation tests.
|
||||
@@ -0,0 +1,182 @@
|
||||
# User/group access and approved anonymous publication
|
||||
|
||||
Implemented first slice, 2026-09-14. This extends, rather than replaces,
|
||||
[locality governance](locality-publication-ownership.md) and
|
||||
[endpoint authorization](authorization-groups.md). No production ACL or public
|
||||
approval is installed automatically. Existing legacy domains remain legacy;
|
||||
configuration of these controls requires `authorization_mode=enforcing`.
|
||||
|
||||
2026-09-16 update: [public navigation](public-navigation.md) supersedes the
|
||||
navigation-disabled first-slice restrictions below for children, tree, City Map
|
||||
and locality links. Normal public Pages are navigable and have no download
|
||||
button; a navigation-free view is reserved for share URLs. Approval-policy
|
||||
inheritance and reviewer Inbox are [design/TODO only](publication-approval-inbox.md).
|
||||
|
||||
## Authenticated user/group permissions
|
||||
|
||||
Domain, Quartier, Street and Spot governance dialogs expose a separate access
|
||||
form. `inherit` adds no restriction; `restricted` selects up to 64 local users
|
||||
or groups. Empty selection denies non-administrative content access.
|
||||
|
||||
| Setting | Newly granted content capabilities | Not newly granted |
|
||||
| --- | --- | --- |
|
||||
| Read only | read | all mutations |
|
||||
| Read/write | read, write, create, upload | delete, rename, link, manage, ownership |
|
||||
|
||||
This locality selector is deliberately narrower than the existing group-wide
|
||||
`read_write` profile (which also includes rename/link). Existing grants continue
|
||||
to supply their original capabilities, subject to locality restrictions and the
|
||||
temporary namespace fences below. Do not interpret it as an administrator role.
|
||||
|
||||
- Matching subjects at one locality form a union. Every applicable ancestor
|
||||
restriction is then intersected. A child cannot grant write through a
|
||||
read-only parent or grant access to a subject excluded by a parent.
|
||||
- A Domain administrator can establish a positive grant. A delegated owner can
|
||||
restrict existing/ancestor-granted rights, not invent a new positive grant.
|
||||
- Policy authority is retained: Domain admin = 3, Quartier owner = 2, Spot owner
|
||||
= 1. A subordinate editing a superior-authored policy may remove subjects or
|
||||
downgrade read/write to read, but cannot clear it, add subjects, or promote
|
||||
read to read/write. Such narrowing retains the superior grant/rank.
|
||||
- Active built-in Domain administrators bypass locality content caps for
|
||||
recovery, but still require their underlying capability grants. Ordinary
|
||||
members of an administrative group are not automatically administrators.
|
||||
- Usernames resolve to stable local membership IDs; group names resolve to
|
||||
stable group IDs. Name reuse must not transfer rights. Supplied IDs must
|
||||
agree with resolved names. Group membership, account state and Domain
|
||||
membership are re-evaluated on the next request, not held in a global cache.
|
||||
Readonly principals cannot gain write from a matching group.
|
||||
- The initial username picker resolves password-type username identities;
|
||||
external-only identities need a local username identity before selection.
|
||||
- Object/raw/history access intersects the restrictive caps on all local
|
||||
aliases, even when an Object grant or a different readable alias exists.
|
||||
Listings use a bounded request-scoped snapshot; no positive Object grant
|
||||
reveals otherwise hidden semantic aliases.
|
||||
Exact foreign Object grants also cannot bypass a restricted source-Domain
|
||||
binding; cross-Domain delegation of these new ACLs is not implemented.
|
||||
- Saves recheck active governance authority and epoch/topology in a reserved
|
||||
SQLite write transaction and append local before/after audit records.
|
||||
Content operations already authorized/in flight are not recalled; this is
|
||||
not a distributed linearizable revocation protocol.
|
||||
|
||||
`GET/PATCH /_/api/v1/city/{domains,zones,spots}/{uuid}/governance/access`
|
||||
uses `epoch`, `topology_version`, `mode`, and entries containing
|
||||
`kind: user|group`, `name`, `permission: read|read_write`, optional stable `id`.
|
||||
Readonly scope, authority rank and grant flags are computed server-side.
|
||||
Missing/stale versions fail; client fields cannot assert administrator status.
|
||||
|
||||
### Temporary namespace guard (important operational limitation)
|
||||
|
||||
Applying a restriction is refused when an in-scope Object already has aliases
|
||||
outside that scope or in another Domain. Resolve these bindings first.
|
||||
SQLite guards apply to CLI/import/direct-store paths as well as HTTP:
|
||||
|
||||
- Protected Path move, removal and rebinding are refused, as is adding an
|
||||
existing Object inside a restricted scope or aliasing a protected Object out.
|
||||
- New Objects may receive their first Path and revision normally.
|
||||
- City parent/path/state changes and deletions in an ACL-bearing Domain are
|
||||
blocked, including Street–Spot membership changes. Title-only changes remain
|
||||
possible. Automatic/import City mapping may therefore be refused; this is a
|
||||
fail-closed guard, **not** a completed impact-aware reconciliation workflow.
|
||||
- Enforcing mode cannot be disabled while restrictions exist.
|
||||
|
||||
Do not work around these guards by silently dropping ACLs. A Domain admin can
|
||||
explicitly remove restrictions, but that changes access and needs deliberate
|
||||
review. Replacing this coarse guard with atomic, impact-reviewed mutations is
|
||||
the next priority.
|
||||
|
||||
## Anonymous current-content approvals
|
||||
|
||||
A public Domain ceiling merely permits publication. A local public policy
|
||||
within all ancestor ceilings supplies intent; saving it alone publishes nothing.
|
||||
The dialog's anonymous section offers target enumeration, explicit approval,
|
||||
and revocation. It warns that external caches cannot be recalled.
|
||||
|
||||
`GET /_/api/v1/city/{domains,zones,spots}/{uuid}/governance/publication`
|
||||
returns an impact token, epoch/topology version, eligible current
|
||||
Path/Object/Revision/SHA-256/language tuples and excluded Paths. Domain itself
|
||||
is not publishable. A candidate is excluded if it has any aliases, is in a
|
||||
reserved namespace, or is under either a user/group restriction or a local
|
||||
authenticated-only ceiling. The actor must be able to read every candidate;
|
||||
governance authority alone cannot enumerate/publish another user's secrets.
|
||||
|
||||
The metadata-only preview is bounded to 512 Paths, 32 language heads per Object,
|
||||
2048 entries and three seconds. Exceeding a limit rejects the whole approval;
|
||||
there is no silently truncated approval. The digest includes actor, Domain,
|
||||
scope, versions, entries and exclusions. It is a concurrency commitment, not a
|
||||
bearer credential. An authorized actor must still approve it.
|
||||
|
||||
`PATCH .../publication` receives `epoch`, `topology_version`, `publication_version`, `enabled`,
|
||||
`impact_token`, `confirm`. Activation reserves the SQL writer, checks current
|
||||
authority, regenerates impact and compares the digest before writing one atomic
|
||||
manifest. A per-scope publication generation advances on both approval and
|
||||
revocation, so pre-revocation consent cannot be replayed to publish again.
|
||||
Revocation does not need impact enumeration or read access to all
|
||||
old contents, so an oversized/now-restricted manifest remains revocable.
|
||||
|
||||
- Approval binds only current immutable revisions, never future edits or new
|
||||
descendants. All language heads in the preview are included explicitly.
|
||||
- Ordinary Page edits withdraw the affected language entry; Path binding/alias
|
||||
changes withdraw the Object's entries. Restoring an old binding does not
|
||||
silently revive approval. SQLite triggers cover direct store/CLI writes too.
|
||||
- Governance/ACL/owner changes invalidate all manifests in that Domain through
|
||||
their epoch. City changes invalidate manifests conservatively, including
|
||||
title changes in this first slice. Reapproval is explicit.
|
||||
- Different scopes may approve the same Path. Revoking one approval removes
|
||||
only that approval; the UI states that another scope may still publish it.
|
||||
An ancestor authenticated-only policy or a user/group restriction invalidates
|
||||
the Domain's approvals and prevents reapproval of the restricted subtree.
|
||||
- Manifest presence prevents switching the Domain to legacy authorization.
|
||||
- Revocation controls the next request, including conditional/Range requests.
|
||||
It cannot recall in-flight bytes or copies retained by browsers/crawlers.
|
||||
|
||||
## Public read surface and exclusions
|
||||
|
||||
Only GET/HEAD of a known semantic Page URL or `/v/raw/path:{semantic-path}`
|
||||
can use the approved anonymous read path under enforcing mode. It is considered
|
||||
only when no session cookie or Authorization header exists. Invalid/expired
|
||||
credentials do not downgrade to anonymous. Valid authenticated requests keep
|
||||
the authenticated authorization pipeline.
|
||||
|
||||
Every read checks enabled host-resolved Domain, live binding, current language
|
||||
head, approved digest and current governance/topology versions. Lookup is
|
||||
Path-indexed, metadata-only and limited to two seconds. Raw streaming uses
|
||||
`OpenDocument`/`ServeContent` with Range support and existing identity headers;
|
||||
it does not hydrate large documents or queue preview generation.
|
||||
|
||||
The dedicated themed Viewer includes no private topbar, bookmarks, user menu,
|
||||
City ancestors or automatic discovery. HTML uses `controlled-v2` plus nonce CSP;
|
||||
code/text is escaped and bounded. Raster images, audio/video and native PDF
|
||||
frames are supported. Raw HTML/SVG/unknown files are sandboxed attachments.
|
||||
Responses remain private/no-store, varying on credentials and language.
|
||||
OGP/X metadata derives only from this approved content and configured Domain
|
||||
identity; ordinary enforcing responses continue suppressing social metadata.
|
||||
|
||||
**Not part of this slice:** anonymous City/search/browser/children expansion,
|
||||
asset/hash/UUID/revision/history access, derived thumbnails, archive viewers,
|
||||
diagrams, hosted adapters, and dependency manifests. Authored macros remain
|
||||
literal on anonymous HTML pages. Referenced assets are not automatically made
|
||||
public. Restricted user/group scopes are not anonymously publishable: an
|
||||
“everyone can read, selected subjects can write” audience needs a later
|
||||
per-capability audience model (existing write grants remain usable outside a
|
||||
restricted scope). No public production Page is created as a deployment test.
|
||||
|
||||
## Follow-up tasks
|
||||
|
||||
- [ ] Transactional impact-aware move/merge/import/reconciliation, replacing the
|
||||
coarse authenticated namespace freeze without weakening restrictions.
|
||||
- [ ] Atomic per-content-operation authorization snapshots where still checked
|
||||
before mutation; bounded grant evaluation with large policy catalogs.
|
||||
- [ ] Stable local usernames for external-only identities and bounded group
|
||||
name autocomplete; stale/deleted subject diagnostics and orphan cleanup.
|
||||
- [ ] Per-capability audiences (anonymous read plus named writers), preview of
|
||||
effective inherited user/group membership, and privilege-impact confirmation.
|
||||
- [ ] Dependency-aware anonymous children/City/search/media projections and
|
||||
shared assets, retaining exact source/alias authority and revocation.
|
||||
- [ ] Paginated manifest review for larger sites, targeted epoch invalidation,
|
||||
publication expiry/status monitoring and approval co-ownership visibility.
|
||||
- [ ] Domain-sequenced transactional outbox and federated ACL/approval protocol;
|
||||
new local ACL tables are not implicitly exported by current group inheritance.
|
||||
|
||||
Tests: `TestLocalityUserGroupAccess`, `TestAnonymousApprovedPublication`,
|
||||
`TestCityGovernanceChromium`, `TestAnonymousPublicationChromium`, existing
|
||||
governance concurrency, HTML/browser/auth/read-policy and full regression suites.
|
||||
@@ -0,0 +1,271 @@
|
||||
# Locality owners and constrained publication
|
||||
|
||||
Status (2026-09-14): **owner appointments and publication-policy drafts implemented**.
|
||||
The subsequent [user/group and anonymous approval slice](locality-access-publication.md)
|
||||
now enables separately approved current-revision Viewer/media access. It supersedes
|
||||
the earlier anonymous-disabled status below, not the remaining full dependency/
|
||||
mutation gates. No saved draft is activated automatically. This supersedes the earlier proposal
|
||||
that a child publication setting could simply override an ancestor's restriction.
|
||||
|
||||
## Implemented first slice
|
||||
|
||||
- Stable-UUID Quartier/Spot bindings support up to 32 co-owners. Appointment is
|
||||
limited to active local Domain memberships; only active principals/memberships
|
||||
exercise authority. Revocation/suspension is checked on each request.
|
||||
- `domain_admin` owner/manager membership is authoritative for this API; generic
|
||||
document write/manage grants, ordinary group administration and an unrelated
|
||||
`campus_admin` membership are not a fallback. Existing explicitly inherited
|
||||
Domain authority must materialize through the established group lifecycle.
|
||||
- Quartier owners govern their own Quartier, Streets and Spots, and appoint
|
||||
Spot owners only. They cannot appoint peers. Spot owners cannot appoint peers
|
||||
or mutate topology/content through this feature. Existing content read ACLs
|
||||
still govern detail pages; the governance API itself exposes configuration,
|
||||
not Page bodies or an unfiltered Page list.
|
||||
- Domain policy defaults to `authenticated_acl`; `public` there permits draft
|
||||
publication but does not publish the root. Local defaults are `inherit`.
|
||||
The evaluator intersects all caps, separately retaining publication intent.
|
||||
Saving `public` beneath a restrictive cap fails; superior tightening clamps
|
||||
previously stored descendant intent without erasing it.
|
||||
- Relaxations require explicit confirmation. **This is a draft confirmation,
|
||||
not publication-impact consent**. This endpoint retains `impact_complete:false`;
|
||||
its `publication_enabled` now reports this node's separate approved manifest.
|
||||
`GET/PATCH .../publication` provides bounded current-revision review/approval,
|
||||
excluding aliases and dependencies. Do not silently activate saved drafts.
|
||||
- `GET` / `PATCH /_/api/v1/city/{zones,spots,domains}/{uuid}/governance` are
|
||||
handler-authorized with the existing session and CSRF protections. Only the
|
||||
requesting Domain UUID is accepted for `domains`. Zone kind and active,
|
||||
same-Domain parentage/strict descendant Paths are verified, not inferred from
|
||||
client claims. Invalid/missing targets fail closed.
|
||||
- `POST .../governance/preview` validates a proposed owner/policy draft without
|
||||
persisting it; it is **not** a Page/alias publication-impact report.
|
||||
`GET .../governance/members?q=...` is appointment-authorized, returns at most
|
||||
30 matching active local display identities, and never returns emails/tokens.
|
||||
- PATCH/preview require both Domain governance `epoch` and `topology_version`.
|
||||
A write reservation is acquired before reading actor membership, group/owner
|
||||
authority, parent chain and policies, so a concurrent revocation cannot commit
|
||||
between authority validation and the write. Stale versions return 409. Preview
|
||||
rolls back its short reservation; no-op saves currently advance the epoch.
|
||||
Request work has a two-second context deadline; SQLite busy handling can still
|
||||
return retryable unavailability. There are no cross-request authority caches.
|
||||
- Additive tables are `city_owner_bindings`, `locality_publication_policies`,
|
||||
`city_governance_epochs`, and `city_governance_events`. Audit records contain
|
||||
actor UUID, node UUID, epoch, timestamps and before/after configuration, not
|
||||
document bodies or secrets. These are a local transactional audit log, not
|
||||
the future durable Domain activity outbox or request-ID-correlated audit UI.
|
||||
- Details have a themed settings-icon dialog with owners, member lookup, local
|
||||
policy, ancestor caps and draft result. Domain draft ceiling is reachable
|
||||
from the City Map utility menu's settings icon; configuration-panel embedding
|
||||
can reuse this component later. Labels, confirmations and errors support
|
||||
Japanese/English. Opening/closing and stale async responses are guarded.
|
||||
|
||||
Not completed: complete dependency/alias impact, impact-aware move/merge/archive/
|
||||
import/reconciliation (the current ACL guard rejects structural changes), orphan
|
||||
binding cleanup, anonymous discovery, full audit UI/outbox and automatic future
|
||||
revision publication. The separate bounded Viewer/media activation and revocation
|
||||
slice is specified in [the implementation contract](locality-access-publication.md).
|
||||
|
||||
Verification: `city_governance_test.go` in Store/Server covers cap intersections,
|
||||
multiple owners, self/peer appointment denial, unrelated Quartier/Domain denial,
|
||||
active membership checks, owner/admin revocation, blocked intents, explicit
|
||||
relaxation, non-persisting preview, stale epochs/topology, concurrent saves and
|
||||
CSRF. `city_governance_browser_test.go` exercises real dialog/member search/save/
|
||||
reopen for both locality and Domain controls in Chromium.
|
||||
|
||||
## Requirements and boundary
|
||||
|
||||
- Quartiers and Spots can have explicitly appointed owners, including multiple
|
||||
co-owners. Ownership is scoped governance, not a Domain administrator Role.
|
||||
- A subordinate owner may narrow the publication audience permitted by superior
|
||||
governance, never enlarge it beyond an ancestor's ceiling.
|
||||
- Preserve existing authenticated content ACLs. Ownership and publication do not
|
||||
implicitly grant editing, deleting, membership administration, historical
|
||||
Revision access, object enumeration or arbitrary code execution.
|
||||
- Do not disable `authorization_mode=enforcing` to implement public localities.
|
||||
Anonymous publication must be a separate, explicitly authorized read path.
|
||||
- Broadening anonymous access must use
|
||||
[safe HTML projections](html-projection-trust.md), now implemented for normal
|
||||
displays, and pass the governance/mutation/revocation gates below. OGP itself
|
||||
grants no read authority.
|
||||
|
||||
## Ownership and appointments
|
||||
|
||||
Initial bindings refer to active Domain memberships (and their Principal), not
|
||||
usernames. User renames do not change ownership. Multiple owners are supported;
|
||||
an ownerless node falls under its superior administrators. Group ownership can
|
||||
be added later only with an explicit group-membership/delegation policy; ordinary
|
||||
group managers must not silently acquire publication-administration powers.
|
||||
|
||||
| Actor | May appoint/remove owners | May administer publication |
|
||||
| --- | --- | --- |
|
||||
| Domain administrator | Quartier and Spot owners in its Domain | Domain ceilings and locality policies |
|
||||
| Quartier owner | Spot owners within that Quartier | That Quartier, its Streets and Spots, bounded by superior ceilings |
|
||||
| Spot owner | No appointment or co-owner changes by default | Its own Spot, bounded by all superior ceilings |
|
||||
| Ordinary Page author / group admin | None by this feature | None by this feature |
|
||||
|
||||
Quartier owners do not appoint their own peers or remove superior authority.
|
||||
Spot owners do not transfer ownership or add co-owners themselves. Superior
|
||||
appointment keeps delegated authority auditable and avoids accidental transfer
|
||||
of publication control. Street has no independent owner role in this slice;
|
||||
its Quartier governs Street policy. A future Street owner must obey the same
|
||||
attenuation rules, not create a separate bypass.
|
||||
|
||||
Campus administrators retain their existing Campus authority and explicit
|
||||
Domain-admin inheritance semantics. Do not add an unconditional cross-Domain
|
||||
content/ownership bypass merely because an account belongs to `campus_admin`.
|
||||
|
||||
Owner appointments, revocations, account suspension and Domain membership
|
||||
revocation take effect on the next request. Ownership bindings cannot outlive
|
||||
their Domain scope or be imported as authority through untrusted topology data.
|
||||
An owner must also have explicit read access to inspect document content; a
|
||||
governance UI can report counts without revealing otherwise unreadable bodies.
|
||||
|
||||
## Publication ceiling is not a publication grant
|
||||
|
||||
There are two independent decisions:
|
||||
|
||||
1. **Ceiling:** the widest audience superior governance allows.
|
||||
2. **Publication intent:** whether this locality and its Path subtree are
|
||||
actually being published, or inherit an explicit ancestor publication.
|
||||
|
||||
A Domain starts with an authenticated-only ceiling and no anonymous publication.
|
||||
Allowing public publication at the Domain ceiling does not publish the Domain
|
||||
root, unconfigured localities, or arbitrary Pages. A Quartier/Spot owner must
|
||||
then explicitly publish a locality, or inherit an already published ancestor.
|
||||
|
||||
The first UI supports:
|
||||
|
||||
- `inherit`: retain the ancestor publication intent; add no restriction.
|
||||
- `public`: request anonymous read for this boundary and descendants. Accepted
|
||||
only when every ancestor ceiling allows it; also establishes public intent
|
||||
inherited by descendants.
|
||||
- `authenticated_acl`: block anonymous reads here and below. Authenticated
|
||||
readers still need the existing read grants; this does **not** grant every
|
||||
logged-in account access. It acts as a ceiling that descendants cannot widen.
|
||||
|
||||
Thus a public Quartier may contain an authenticated-only Spot, but an
|
||||
authenticated-only Quartier cannot contain a public Spot. An unconfigured
|
||||
Quartier under a Domain that merely *allows* publication is not public; a Spot
|
||||
may explicitly be published there only if no ancestor imposed a narrower cap.
|
||||
Unpublished parent metadata is not thereby published with that Spot.
|
||||
|
||||
For anonymous access:
|
||||
|
||||
`allowed = explicit-or-inherited publication intent AND every ancestor ceiling`
|
||||
|
||||
For authenticated readers, retain the existing ACL evaluator. If selected-group
|
||||
audience caps are introduced later, they must be an additional intersection,
|
||||
not a positive grant or a priority-ordered override. Formally, effective audience
|
||||
is the intersection of all applicable caps and the branch's positive read basis.
|
||||
Predicates should be combined at evaluation time; do not enumerate users to
|
||||
compare audiences. This slice does not introduce selected-group restrictions
|
||||
or change current positive-grant semantics without a separate migration.
|
||||
|
||||
An attempted `public` save under an authenticated-only cap fails explicitly;
|
||||
do not store a misleading, silently clamped UI value. If a superior subsequently
|
||||
tightens a ceiling, existing descendant public intent becomes ineffective
|
||||
immediately without deleting the descendant's policy. A later relaxation must
|
||||
preview and explicitly confirm any previously blocked public intent becoming
|
||||
effective. Explicit child `authenticated_acl` restrictions remain in force.
|
||||
|
||||
Returning a child from `authenticated_acl` to `inherit` can reopen access where
|
||||
the parent is public. It is permitted within the owner's superior ceiling, but
|
||||
requires the same public-impact confirmation as choosing `public`. Attenuation
|
||||
is relative to superior authority, not an irreversible chronological lock.
|
||||
|
||||
## Scope and bypass resistance
|
||||
|
||||
- Publication follows the literal Path boundary, including its portal and new
|
||||
descendant Pages. `/life` never matches `/lifestyle`; `%`, `_`, Unicode and
|
||||
encoded separators are not SQL wildcards or a second decoding opportunity.
|
||||
- Related Spot/Page appearances, reference edges and bookmarks never convey
|
||||
publication. A public Page can link to a private Page without exposing its
|
||||
private title, description, contents or preview.
|
||||
- City/search/children/OGP/thumbnail projections use the same anonymous read
|
||||
decision. Suppress unreadable ancestor names in public breadcrumbs; do not
|
||||
make the ancestor public merely to show a published child.
|
||||
- Owner and policy bindings are keyed by stable UUID. Changing a boundary,
|
||||
moving a Street/Spot, recursive rename, link/unlink, import, merge, archive,
|
||||
deletion and reconciliation all require publication-impact checks. Ordinary
|
||||
document `write`, `rename` or `link` cannot publish previously private bytes
|
||||
by moving/aliasing them into a public boundary. New content written directly
|
||||
into an already public boundary follows its policy; make that visible in UI.
|
||||
- Do not silently discard restrictions on node deletion, merge or archive.
|
||||
Preserve equivalent restrictions or require a superior-authorized explicit
|
||||
policy transition. Reconciliation cannot remove manually imposed restrictions
|
||||
or create owner bindings.
|
||||
- Aliases require special attention: if an Object is published through one
|
||||
allowed Path, those same content bytes are not secret through another alias.
|
||||
Warn in impact previews and require publication authority; do not expose other
|
||||
alias names or infer that raw UUID/hash/history endpoints are now public.
|
||||
- Initially publish only the current safe Viewer and the current approved media
|
||||
needed by it. Assets, previews and embedded resources get independent checks;
|
||||
never enumerate or publish historical revisions through a public Page.
|
||||
|
||||
## Persistence and remaining target API contract
|
||||
|
||||
Separate tables, rather than opaque `zones.policy_json` authorization:
|
||||
|
||||
- `city_owner_bindings`: Domain UUID, node kind/UUID, membership UUID, appointing
|
||||
Principal, timestamps; unique binding per node/member.
|
||||
- `locality_publication_policies`: Domain UUID, node kind/UUID (including Domain),
|
||||
intent/cap, policy version, actor and timestamps. Initial enum constraints
|
||||
disallow arbitrary audience JSON. Ancestor joins validate active, same-Domain
|
||||
parentage. Governance version is independent of cosmetic layout version.
|
||||
- Domain publication-policy epoch: changes to ancestors invalidate derived
|
||||
decisions, summaries and pending impact confirmations.
|
||||
- Audit/outbox: before/after owners, policies and effective-publication impact,
|
||||
actor, versions and request ID. No payload bodies or secrets in audit records.
|
||||
|
||||
Handler-owned endpoints (configuration operations implemented; full publication
|
||||
impact reports remain pending):
|
||||
|
||||
| Endpoint | Purpose |
|
||||
| --- | --- |
|
||||
| `GET /_/api/v1/city/{zones,spots}/{uuid}/governance` | Authorized owners, local policy, superior ceilings and effective result |
|
||||
| `POST /_/api/v1/city/{zones,spots}/{uuid}/governance/preview` | Owner/policy draft validation only |
|
||||
| `PATCH /_/api/v1/city/{zones,spots}/{uuid}/governance` | Versioned owner/policy mutation with scoped authority |
|
||||
| `GET/PATCH .../governance/access` | Named user/group restrictions within superior caps |
|
||||
| `GET/PATCH .../governance/publication` | Bounded current-revision impact, explicit approval and revocation |
|
||||
|
||||
Domain ceiling is Domain-scoped with its own policy epoch; the current UI lives
|
||||
in the City Map utility menu and can later be embedded in Domain configuration.
|
||||
The endpoint registry must deliberately admit scoped owners for these operations;
|
||||
do not relax the existing Domain-admin guard on unrelated City mutations.
|
||||
|
||||
Resolve actor membership/ownership, parent chain, caps and expected policy epoch
|
||||
in one transaction. Stale versions return 409; insufficient authority returns
|
||||
403 (or 404 for an unreadable target). Fail closed on unknown/malformed policies,
|
||||
missing parents, foreign references, limits and query errors. Reject exhausted
|
||||
impact previews rather than treating a truncated list as complete consent.
|
||||
|
||||
Use bounded bulk reads / request-scoped snapshots, not a query per Page or a
|
||||
process-wide authority cache. Public-mode decisions must be part of cache keys;
|
||||
revocation takes precedence over any immutable-image cache reuse. Third-party
|
||||
social caches cannot be recalled after publication; disclose this at confirmation.
|
||||
|
||||
## UI and implementation sequence
|
||||
|
||||
Use a settings-icon modal in Quartier/Spot details, with three compact sections:
|
||||
owners, publication, and affected Pages. Show the superior ceiling, local choice,
|
||||
effective status and the source of each inherited restriction. Disable forbidden
|
||||
choices with explanations, but enforce all rules again server-side. Use existing
|
||||
locale/theme/dialog conventions; localize both UI and permission errors.
|
||||
|
||||
Implementation order:
|
||||
|
||||
1. Completed prerequisite: inert HTML projection boundary and browser denial
|
||||
regressions. No executable compatibility mode or anonymous grant was added.
|
||||
2. Completed first slice: scoped owner bindings / appointments, versioned policy
|
||||
storage, pure cap evaluator and governance API/UI. Public enabling and full
|
||||
Page/alias impact preview remain release-gated.
|
||||
3. Structural mutation/alias/import/reconciliation fencing and publication audit.
|
||||
4. Common anonymous read policy under enforcing authorization, safe current
|
||||
Viewer/media projections, filtered discovery and OGP integration.
|
||||
5. Revocation/cache tests and staged enablement without changing existing Domains.
|
||||
|
||||
Required regressions include co-owners, removed/suspended owners, foreign Domain
|
||||
IDs, parent appointment rules, peer self-appointment denial, direct API bypass,
|
||||
ancestor tightening races, unpublished ancestors with a public child, child
|
||||
reopening within a permitted cap, move/merge/archive/alias bypasses, batch limits,
|
||||
literal Paths, current-vs-history access, private preview dependencies, inherited
|
||||
admin revocation, public/private cache isolation, and preserved canonical bytes.
|
||||
@@ -0,0 +1,132 @@
|
||||
# Home layouts and navigation sidebar
|
||||
|
||||
## 実装済みのトップページ
|
||||
|
||||
配色テーマ(Index、Railgun、Nanoha等)とレイアウトを分離する。
|
||||
`/-/sys/config?panel=home` でドメインごとに設定する。
|
||||
|
||||
| `home_layout` | 表示 |
|
||||
| --- | --- |
|
||||
| `classic`(既定) | 従来のトップバーと `home_path` のページ。未指定時はルート一覧 |
|
||||
| `search` | トップバーなし、画面中央にWiki名と検索欄 |
|
||||
| `directory` | トップバーなし、中央上部に検索欄、その下にブックマーク |
|
||||
|
||||
すべてのトップページ検索は `scope=/`。これは現在のドメイン全体であり、
|
||||
他ドメイン横断検索ではない。`/` で `/top` を表示しても検索対象は `/`。
|
||||
`/top` 自体に直接アクセスした場合は通常のViewerとして `/top` 配下検索を維持する。
|
||||
既存のパス検索を使用し、全文検索エンジンの追加はこの変更に含めない。
|
||||
|
||||
`home_bookmarks` はJSONの `[{label,href}]` をドメイン設定に保存する。
|
||||
管理UIは `panel=bookmarks` の行編集式マネージャーとし、名前とPath/URLを指定する。
|
||||
従来のJSONは互換維持し、指定方法を表す `kind` を任意追加する。
|
||||
最大64件。HTTP(S)とルート相対パスのみ許可し、ローカルのリンクは表示時に
|
||||
現在の閲覧権限を確認する。個人ブックマークとは区別する。
|
||||
`home_path` の内容はclassicでのみ表示し、レイアウト切替で元ページを変更しない。
|
||||
検索型でもアカウントメニューとCity Mapのポップアップは右上から開ける。
|
||||
|
||||
## 実装済みの壁紙とPath Picker
|
||||
|
||||
ドメイン設定の `home_wallpaper_path` は、単一の画像Page Pathまたは仮想フォルダの
|
||||
Pathを受け取る。画像の場合は固定表示し、フォルダの場合は直下にある
|
||||
`image/*` のPageだけを候補としてリクエストごとに暗号学的乱数で1件選ぶ。
|
||||
再帰走査はせず、本文の読み込みやプレビュー生成も行わない。候補とRaw配信の双方に
|
||||
現在の閲覧権限を適用し、非公開画像の存在を匿名トップページへ漏らさない。
|
||||
HTMLは候補がある場合だけ `private, no-cache` とし、画像本体の通常キャッシュは維持する。
|
||||
|
||||
`home_wallpaper_opacity` は0–100の整数で、表示時に0–1へ変換する。画像は装飾目的の
|
||||
空alt、固定配置、`object-fit: cover` とし、Classic、Search、Directory、`home_path`、
|
||||
Diary/Blogトップに共通適用する。コンテンツは独立した上位stacking layerに置く。
|
||||
|
||||
設定画面のPath欄は共通 `GET /_/api/v1/path-picker` を利用する。APIはDomainと現在の
|
||||
Principalで直下の子だけを認可し、最大250件、`private, no-store` で返す。
|
||||
`any`、`file`、`folder`、`image`、`image-or-folder` の型を持ち、UIは対象input IDと
|
||||
modeをdata属性で指定する。これにより今後のストレージ、アダプタ、City設定でも
|
||||
任意HTMLや専用ファイルブラウザを増やさず同じPickerを再利用できる。
|
||||
|
||||
## サイドバー詳細設計(実装待ち)
|
||||
|
||||
管理画面のグループ化されたサイドバーは
|
||||
[Configuration panels](configuration-panels.md) に従い実装済み。
|
||||
以下はViewer等の共通ナビゲーションサイドバーの設計である。
|
||||
|
||||
Viewer、Browser、Treeで共通のナビゲーションコンポーネントを導入する。
|
||||
Browserの既存サイドバーは現在独自実装であるため、共通化時に置換する。
|
||||
Editorの編集幅と検索型トップページの中央配置を維持するため、これらの画面では
|
||||
初期状態を閉じる。City Mapポップアップ内にはサイドバーを表示しない。
|
||||
|
||||
表示要素の順序は次のとおり。
|
||||
|
||||
1. 現在のドメイン名、全体検索、Homeへのリンク。
|
||||
2. 管理者設定の共通ブックマーク。今回の `home_bookmarks` を共通データとして使う。
|
||||
3. 現在のパスを起点とするディレクトリツリー。パンくずで上位へ移動できる。
|
||||
4. City Mapへの入口と、そのパスに対応するQuartier / Street / Spot。
|
||||
5. 将来の個人ブックマーク、最近閲覧・編集したページ。Activity機能のAPIに接続する。
|
||||
|
||||
DOMは共通partialと独立したCSS/JavaScriptへ分離する。配色は既存テーマ変数を使用。
|
||||
PCでは左側の幅可変ペイン(初期16rem、12–28rem)、小画面ではオーバーレイとする。
|
||||
開閉ボタンは `aria-expanded` / `aria-controls` を更新し、オーバーレイはESCで閉じ、
|
||||
トリガーへフォーカスを戻す。非表示状態で本文のグリッド幅を残さない。
|
||||
|
||||
ユーザの幅・開閉・展開状態は `(Domain UUID, Principal UUID, root Path, UI version)`
|
||||
単位で端末に保存する。ページ名・本文・API応答はlocalStorageに保存しない。
|
||||
ログアウト・アカウント切替時は読み込み中リクエストとメモリ上の一覧を破棄する。
|
||||
|
||||
## サイドバー用データ取得契約(実装待ち)
|
||||
|
||||
`GET /_/api/v1/navigation/children?path=/docs&limit=100&cursor=...` を追加する。
|
||||
直接の子のみを返し、`path`, `label`, `is_directory`, `has_children`,
|
||||
`object_uuid`(ある場合), `next_cursor` を含める。曖昧なPageと仮想フォルダの
|
||||
二重行は作らず、同じパスに本文と子がある状態を表現する。
|
||||
|
||||
サーバ側はDomain/Principalの現行権限を適用し、子の存在フラグも閲覧可能な子から
|
||||
算出する。隠しページの件数を返さない。上限200、パス順のカーソル方式とし、
|
||||
権限チェック後にページを構成する。認可はバッチ化し、共有キャッシュには
|
||||
認可済み結果を無条件で入れない。応答は `private, no-store` から開始する。
|
||||
|
||||
初期描画ではサイドバーの枠と現在のパスだけを描画する。展開時に子を取得し、
|
||||
同時リクエスト数を2に制限する。画面遷移時はAbortControllerで中止する。
|
||||
プレビュー生成、全文取得、全Domainツリー取得はこのAPIの仕事に含めない。
|
||||
将来の大規模ツリーは直接の親パス索引/派生ディレクトリテーブルを導入し、
|
||||
Path mutationと同一トランザクションで更新する。
|
||||
|
||||
## 実装済みのTree View
|
||||
|
||||
`/v/tree` は従来どおりルート、`/v/tree/{path}` は指定パス配下だけを表示する。
|
||||
SQLで範囲を絞り、同名接頭辞(`/docs2`)、大文字小文字の違い、別Domain、
|
||||
`%` / `_` を含むパスが混ざらない。`/u` 名前空間の除外と行単位の認可を維持する。
|
||||
パンくず、フォルダ行の配下リンク、アップロード先が現在のルートを引き継ぐ。
|
||||
全展開を初期状態とし、折りたたみ状態をホストと表示ルートごとに保存する。
|
||||
サイドバーと共通化する段階で保存キーにDomain/Principal UUIDを追加する。
|
||||
|
||||
## Browser初回表示の調査・是正
|
||||
|
||||
2026-09-13の読み取り調査で `data/pages.db` は944 Paths、1,614 Revisions。
|
||||
`EXPLAIN QUERY PLAN` は最新リビジョン取得に全走査と一時ソートを示していた。
|
||||
既存DBで `revision_metadata_v1` が適用済みの場合、後から同じマイグレーションに
|
||||
追加されたインデックス作成が省略されることを確認した。
|
||||
|
||||
是正内容:
|
||||
|
||||
- Hack Nerd Font v3.2.1を同梱し、Browser/TreeのCDNフォント依存を除去。
|
||||
`font-display: swap` で初回の文字表示をフォント取得完了まで待たせない。
|
||||
- 完了済みマイグレーションでも `idx_revisions_object_created` を確認・作成。
|
||||
- BrowserのSQLを、配下全体の全Revisionを順位付けする方式から、まず直下の
|
||||
子を集約し、表示するファイルだけ最新Revisionを検索する方式へ変更。
|
||||
- 文書を持つフォルダの重複行を統合。表示する文書のサイズはDocument Storeの
|
||||
statを優先し、SQL互換本文では文字数ではなくバイト数を使用。
|
||||
- テンプレートの言語・タイムゾーン設定を1描画につき1回取得する。
|
||||
|
||||
合成データ(500 Pages、20 Revisions/Page、4KiB/Revision)での
|
||||
`BenchmarkBrowserNestedHistory` は旧SQL約96.6ms、新処理約0.74ms。
|
||||
これはローカルのSQL中心の比較で、実環境の初回表示全体の速度保証ではない。
|
||||
再実行: `go test ./internal/store -run '^$' -bench BenchmarkBrowserNestedHistory`。
|
||||
|
||||
反映後の実DBでは最新Revision検索が `USING COVERING INDEX
|
||||
idx_revisions_object_created (object_uuid=?)` に変わったことを確認した。
|
||||
app/app2のhealthは200、設定済みHost `pages.anya.jp` でローカルTTFと
|
||||
トップページCSSの200配信を確認。トップページ3形式と配下TreeのHTMLは
|
||||
一時DBを用いたHTTPハンドラテストで検証している。
|
||||
|
||||
残課題: 直下の子の集約は配下Pathsの走査を伴う。大規模化には派生ディレクトリ索引、
|
||||
ページング、認可のバッチ化が必要。一般Browserの子件数は権限別に計算する設計へ
|
||||
改める。これらは上記サイドバーAPIと同じ取得層にまとめる。
|
||||
@@ -0,0 +1,41 @@
|
||||
# Object authority is not global Domain authority
|
||||
|
||||
Implemented 2026-09-14. An Object UUID remains a global identity, but a broad
|
||||
Domain capability must not authorize another Domain's Object simply because
|
||||
the caller knows its UUID. Read, Revision/history/projection, save and link
|
||||
checks reuse the same Object resolver.
|
||||
|
||||
Broad Domain/Object-wildcard grants are considered only when the current Domain
|
||||
has a live semantic binding. A separately issued **exact Object grant** remains
|
||||
an intentional exceptional delegation, including an unbound Object. Without
|
||||
such a grant, foreign-only and unknown-origin unbound Objects fail closed.
|
||||
One readable local Path can still authorize Object reads. HTTP purge is stricter:
|
||||
all aliases must belong to this Domain and be individually deletable, with the
|
||||
complete binding set revalidated in the delete transaction.
|
||||
|
||||
## Create → save → bind
|
||||
|
||||
The Object creation API now calls `CreateObjectInDomain`. Creation and insertion
|
||||
of `object_origins(object_uuid, domain_uuid, created_at)` are atomic. While an
|
||||
Object has **no live bindings anywhere**, this provenance permits the creating
|
||||
Domain's normal capability checks, preserving the separate create/save/bind API.
|
||||
It supplies scope, not a capability: a user still needs the requested grant.
|
||||
|
||||
Once bindings exist, provenance is not a substitute for a current local binding.
|
||||
Moving the last binding to another Domain therefore removes the creating
|
||||
Domain's broad access. Explicit exact Object grants are not changed by moving
|
||||
Paths; revocation of those grants has its own authority lifecycle.
|
||||
|
||||
Existing UUIDs and Paths are not rewritten. No unknown legacy unbound Object is
|
||||
silently assigned to the default Domain. Such objects require an exact grant or
|
||||
trusted local administrative recovery; this is a deliberate security boundary.
|
||||
New API-created provenance is not a claim that every historical CLI/import/Page
|
||||
creation recorded ownership. A future verified provenance migration must account
|
||||
for ambiguous multi-Domain history and asset references.
|
||||
|
||||
Regression tests cover foreign reads/Revisions/saves/binds, wildcard versus exact
|
||||
grants, the API create/save/bind sequence, relocation, and unknown unbound Objects.
|
||||
Concurrent grant or namespace revocation during an already-authorized write
|
||||
still requires policy-version/transaction fencing across all write routes;
|
||||
the separate recursive mutation snapshot fixes do not imply that wider gate is
|
||||
complete.
|
||||
@@ -0,0 +1,97 @@
|
||||
# Object metadata list: bounded cursor pagination
|
||||
|
||||
Implemented: 2026-09-14. Endpoint: `GET` / `HEAD /_/api/v1/object/list`.
|
||||
|
||||
## Compatible response and continuation
|
||||
|
||||
The body remains a JSON array of the existing `Object` representation
|
||||
(`UUID`, `Kind`, `CreatedAt`). No Path, revision body, aggregate count, or
|
||||
unreadable Object metadata is added. Empty results serialize as `[]`.
|
||||
|
||||
Query parameters:
|
||||
|
||||
- `limit`: default 100, positive integers, capped at 200.
|
||||
- `cursor`: opaque continuation token from the preceding response.
|
||||
|
||||
When continuation is possible, responses include both `X-Next-Cursor` and an
|
||||
RFC-style `Link: <...>; rel="next"` header containing the same cursor. HEAD
|
||||
returns the corresponding metadata/continuation headers without an entity
|
||||
body. Responses are `private, no-store`; unsupported methods return 405.
|
||||
|
||||
Clients **must continue when a next cursor exists, even if the current array
|
||||
is empty**. A page may examine only unreadable Objects and still have later
|
||||
readable Objects. Absence of a next cursor is the end-of-scan condition. There
|
||||
is deliberately no `total`, denied count, or public scanned-row count.
|
||||
|
||||
Ordering is `(COALESCE(created_at, 0) DESC, uuid ASC)`. The keyset position does
|
||||
not require the boundary Object to continue existing, and handles identical
|
||||
timestamps and legacy NULL timestamps without OFFSET or duplicates. New
|
||||
Objects/links created between requests may appear before or after the current
|
||||
position; pagination is not a multi-request immutable snapshot.
|
||||
The continuation query separately seeks the same-timestamp UUID suffix and
|
||||
then older timestamps, keeping large same-second imports from repeatedly
|
||||
rescanning UUIDs before the cursor.
|
||||
|
||||
## Cursor confidentiality and authority
|
||||
|
||||
The cursor contains its purpose/version, Domain, principal, fifteen-minute
|
||||
expiry, and `(created_at, UUID)` position. The existing instance authentication
|
||||
key encrypts/authenticates it with AES-GCM; the transport encoding is base64url.
|
||||
A base64-only bookmark would disclose the last denied Object's UUID and time
|
||||
on an empty page, so it is explicitly not used.
|
||||
|
||||
Tampered, expired, wrong-purpose, cross-Domain, and cross-principal cursors
|
||||
return a generic 400. Cursors do not carry permissions: current session,
|
||||
membership and grants are reevaluated on every request. They survive a process
|
||||
restart when the authentication key is unchanged. Replicas need the same key
|
||||
to interchange cursors; key distribution itself is not implemented here.
|
||||
|
||||
## Bounded selection and authorization
|
||||
|
||||
The API retains its existing scope: only Objects with a **live semantic Path
|
||||
binding in the current Domain** are candidates. Unbound Objects and Objects
|
||||
bound exclusively in another Domain do not become listable merely because
|
||||
their global UUID or creation origin is known. Direct Object grants authorize
|
||||
metadata among these candidates; they do not widen this listing's scope.
|
||||
|
||||
The handler installs a two-second request context, loads exact Object / broad
|
||||
Domain-or-Object read grants in one bounded query, and uses the shared
|
||||
request-scoped Path-read filter. Principal and Domain membership must be active
|
||||
(readonly Principals may read). Candidate metadata and binding inspection share
|
||||
a read-only SQLite transaction.
|
||||
|
||||
- At most 400 candidates, plus one lookahead row, are selected in SQL.
|
||||
- Direct Object and broad read grants are applied before looking at Paths.
|
||||
- At most 8,000 binding rows are inspected in one batch for the remaining
|
||||
candidates. No per-Object SQL authorization loop remains.
|
||||
- Exact Object / Domain grant loading is capped at 4,096 grants.
|
||||
- If a binding/grant budget is exceeded, the request fails closed with a
|
||||
generic 503. It does not incorrectly skip insufficiently inspected Objects.
|
||||
- A visible page ending early resumes after its last returned Object; a
|
||||
denied-only candidate batch resumes after its last inspected Object.
|
||||
|
||||
Schema initialization adds metadata-order and Object/Domain/Path indexes once.
|
||||
The helper tolerates legacy Domain-only migrations where Object tables have
|
||||
not yet been installed. No foreground listing performs DDL.
|
||||
|
||||
## Remaining scaling work
|
||||
|
||||
Very many cross-Domain Objects can still require scanning the metadata-order
|
||||
index before finding in-Domain candidates; the deadline bounds this rather than
|
||||
a claim of constant query time. Very highly aliased Objects can exceed the
|
||||
binding budget for a Path-only reader. Domain-specific listing projections and
|
||||
SQL-side joins to a compiled, bounded ACL projection would address these cases.
|
||||
The older trusted store listing methods remain available to their other callers;
|
||||
this change specifically bounds the HTTP metadata-list endpoint.
|
||||
|
||||
## Regression tests
|
||||
|
||||
Tests cover default/max limits, stable tied/NULL timestamps, deleted boundary
|
||||
Objects, HEAD behavior, malformed/tampered/expired/scoped cursors, empty pages
|
||||
with continuation, exact Object and Path grants, grant revocation, hidden Path
|
||||
and cursor confidentiality, Domain/unbound exclusion, cancellation, extreme
|
||||
binding budgets, and the legacy Domain-only migration fixture.
|
||||
|
||||
```sh
|
||||
go test -race ./internal/server ./internal/store -run 'TestObjectList|TestObjectMetadata|TestLegacyDistrictsMigrateToDomains' -count=1
|
||||
```
|
||||
@@ -0,0 +1,117 @@
|
||||
# OIDC ID-token verification
|
||||
|
||||
Implemented: 2026-09-14. This closes the unsigned-ID-token acceptance gap in
|
||||
the authentication backend; it is not a claim that every identity-provider or
|
||||
account-lifecycle feature is complete.
|
||||
|
||||
## Authentication boundary
|
||||
|
||||
`/_/auth/oidc` and `/_/auth/callback/oidc` accept GET only. Authorization Code
|
||||
with PKCE S256 still uses a five-minute, one-use, Domain-scoped DB challenge.
|
||||
The challenge now also fixes the configured issuer and client ID, and stores
|
||||
the SHA-256 of a browser-only random secret. A matching HttpOnly, host-only,
|
||||
SameSite=Lax cookie is mandatory at callback. HTTPS uses the `__Host-` cookie
|
||||
prefix, `Secure`, and `/` scope; plain HTTP is retained only for existing local
|
||||
development deployments. Duplicate cookies fail closed. Starting a second
|
||||
login in the same browser supersedes the first browser challenge.
|
||||
|
||||
The callback performs these checks before account binding or session creation:
|
||||
|
||||
1. Consume and validate state, browser binding, and unchanged provider identity.
|
||||
2. Discover the configured HTTPS issuer and require an exact metadata issuer
|
||||
match. Token, UserInfo, authorization, and JWKS endpoints must be HTTPS.
|
||||
3. Exchange the code and require a Bearer access token and a signed ID token.
|
||||
4. Select a public verification key only from that issuer's discovered JWKS.
|
||||
Verify RS256 or ES256 using Go's cryptographic standard library. The
|
||||
algorithm must also be advertised in discovery, match the key type, and
|
||||
match the JWK `alg` when present. `use` and `key_ops` must allow verification.
|
||||
RSA modulus sizes are 2048–8192 bits; ES256 requires a valid P-256 point and
|
||||
its 64-byte JOSE signature. Ambiguous matching keys are rejected; omitted
|
||||
`kid` is allowed only with one suitable key.
|
||||
5. Require exact issuer, subject, client audience, nonce, and valid integer
|
||||
`exp`/`iat`; validate optional `nbf`, `azp`, and `at_hash`. Expired tokens are
|
||||
rejected without grace. Future `iat`/`nbf` permit at most 60 seconds of clock
|
||||
skew. The access-token hash uses the verified signature algorithm's SHA-256.
|
||||
6. Only then fetch UserInfo. Require the same subject and a verified email
|
||||
before resolving the existing external identity or existing local account.
|
||||
|
||||
Both lookup routes require active Domain membership. Email fallback must find
|
||||
exactly one eligible Principal; duplicate matching emails fail closed instead
|
||||
of choosing an arbitrary UUID. External subject binding uses a conditional
|
||||
UPSERT: an existing `(provider type, provider, issuer, subject)` may refresh its
|
||||
attributes only for the same Principal. A concurrent attempt to bind that
|
||||
subject to a different Principal is rejected and cannot proceed to session
|
||||
issuance.
|
||||
|
||||
Provider `email_verified` verifies the provider's claim, not ownership of an
|
||||
email address previously entered into a local Pages Wiki profile. Local-email
|
||||
ownership verification and an explicit account-linking approval policy remain
|
||||
separate requirements; uniqueness checks are not a substitute for them.
|
||||
|
||||
These checks follow [OpenID Connect Core ID-token validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation),
|
||||
with discovery trust rooted in the
|
||||
[configured issuer metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
|
||||
Algorithm allowlisting and rejection of ambiguous data implement the relevant
|
||||
[JWT best-current-practice guidance](https://www.rfc-editor.org/rfc/rfc8725.html).
|
||||
|
||||
The implementation does not follow token-provided `jku`, `jwk`, or `x5u` to
|
||||
obtain trust. Unsigned/symmetric tokens, encryption, unencoded JWS payloads,
|
||||
and critical JOSE extensions are unsupported. Top-level duplicate JSON members
|
||||
(including case variants used by Go struct decoding) and trailing JSON data
|
||||
are rejected.
|
||||
|
||||
## Resource and rotation policy
|
||||
|
||||
| Resource | Bound / policy |
|
||||
| --- | --- |
|
||||
| Provider fetch | 5-second total HTTP timeout, including response body |
|
||||
| Login / callback | Existing 8-second / 10-second request contexts |
|
||||
| Concurrent external requests | 8 process-wide OIDC slots |
|
||||
| Production response headers | 64 KiB |
|
||||
| JSON response | 1 MiB, oversized/truncated input rejected |
|
||||
| Compact ID token / access token | 64 KiB / 16 KiB |
|
||||
| Provider cache | LRU-bounded to 64 exact issuers; public data only |
|
||||
| Signing-key set | At most 128 keys |
|
||||
| Discovery and JWKS freshness | Locally capped at five minutes |
|
||||
| Failed discovery / key-fetch retry | No more than once per 30 seconds |
|
||||
| Signature failure / unknown key | One immediate JWKS refresh, then at most one forced refresh per 30 seconds |
|
||||
|
||||
Concurrent requests for one provider share the same retrieval. A newly fetched
|
||||
JWKS replaces the prior set, including removed keys. A failed forced refresh
|
||||
never authenticates the failing token; other tokens may continue using a
|
||||
still-fresh cached key. Expired keys are never used as an outage fallback.
|
||||
With the local five-minute freshness policy, withdrawal of an otherwise valid
|
||||
cached key is not an instantaneous revocation mechanism.
|
||||
|
||||
All HTTP redirects are rejected, including token exchange and UserInfo, so a
|
||||
redirect cannot forward a client secret or Bearer token. Provider URLs are
|
||||
administrator-controlled; private HTTPS identity providers remain supported.
|
||||
There is no automatic public-network-only SSRF policy or per-provider CA UI.
|
||||
|
||||
## Compatibility limits and follow-up
|
||||
|
||||
- Only RS256 and ES256 are implemented. PS256, EdDSA, encrypted ID tokens,
|
||||
UserInfo JWTs, and dynamic registration remain separate features.
|
||||
- The sole trusted audience is the configured client ID. A singleton audience
|
||||
array is supported; multiple audiences are rejected even when `azp` matches,
|
||||
because no additional-audience trust configuration currently exists.
|
||||
- Exact issuer matching intentionally no longer equates trailing-slash
|
||||
variants. Providers must publish the issuer exactly as configured.
|
||||
- The discovery document must include `jwks_uri` and supported signing
|
||||
algorithms. Token responses must include Bearer `token_type`.
|
||||
- Future work: provider-specific registered signing-algorithm selection,
|
||||
additional-audience trust only if a concrete provider requires it, explicit
|
||||
authentication audit/abuse quotas, configurable cache-header handling, and
|
||||
account-linking policy independent of verified-email matching.
|
||||
- Deployment restarts invalidate the in-memory public-key cache. Login states
|
||||
created before browser/provider binding was added must be restarted.
|
||||
|
||||
## Verification
|
||||
|
||||
`go test -race ./internal/server -run '^TestOIDC' -count=1` covers valid RSA and
|
||||
EC signatures; forged/unsupported/ambiguous signatures; issuer, audience,
|
||||
nonce, time and access-token-hash failures; key usage/curve constraints; key
|
||||
rotation and removed keys; refresh coalescing/backoff; cache/response/key-set
|
||||
bounds; canceled/incomplete response bodies; redirect denial; callback browser
|
||||
binding and duplicate cookies; provider changes; UserInfo subject mismatches;
|
||||
successful session issuance; and one-use state replay denial.
|
||||
@@ -0,0 +1,94 @@
|
||||
# Organizer, task/ticket and HTML editing ideas
|
||||
|
||||
User notes recorded 2026-09-19. **Design backlog; product implementation remains
|
||||
separate.** The user subsequently requested detailed design and Japanese Wiki
|
||||
publication. The expanded proposals now live in [the Japanese handbook](ja/index.md),
|
||||
chapters 12–17, with [decisions and open questions](ja/decisions.md). Original
|
||||
English notes remain below as source material for later aligned translations.
|
||||
Primary protocol and FreshRSS/newsboat documentation has been reviewed; exact
|
||||
client/version interoperability still requires fixtures before implementation.
|
||||
|
||||
## Tasks and tickets
|
||||
|
||||
- [ ] Define lightweight task management: status, assignee, due date, priority,
|
||||
checklist, dependencies, recurring tasks and links to existing Wiki Pages.
|
||||
- [ ] Compare task metadata on ordinary Pages with a dedicated extension entity
|
||||
referencing a Page. Do not make mutable titles or URL Paths durable identity.
|
||||
- [ ] Evaluate CalDAV task interoperability and client support; decide how tasks
|
||||
differ from calendar events and how completion/recurrence map to clients.
|
||||
- [ ] Decide whether ticket management is a task view or a separate extension:
|
||||
ticket numbers, workflow transitions, queues, labels, discussion, attachments,
|
||||
assignments, watchers and notification Inbox integration.
|
||||
- [ ] Keep ACLs, history, audit, search and Domain isolation shared with core
|
||||
facilities rather than introducing an independent permission system.
|
||||
|
||||
## Organizer: URLs, iCalendar, CalDAV and CardDAV
|
||||
|
||||
- [ ] Separate the browser-facing Wiki URL, stable object identity, calendar item
|
||||
UID, export URL and DAV resource URL. Renaming a Wiki Path must not silently
|
||||
duplicate externally synchronized items.
|
||||
- [ ] Start with calendar/list/agenda views and explicit import/export; evaluate
|
||||
read-only subscription feeds before bidirectional synchronization.
|
||||
- [ ] Design timezone/all-day/recurrence/exception handling, conflict resolution,
|
||||
deletions, revisions, sync cursors, conditional writes and bounded pagination.
|
||||
- [ ] Evaluate an external calendar connector versus serving a local CalDAV
|
||||
endpoint; document ownership of canonical data and failure/retry behavior.
|
||||
- [ ] CardDAV contacts: address books, contact identity, duplicates/merge,
|
||||
personal/shared access, import/export and links from contacts to Wiki content.
|
||||
- [ ] Contacts and schedules stay private by default. Scope-specific app tokens,
|
||||
revocation and audit are prerequisites for external client access.
|
||||
|
||||
## RSS viewer and reader integrations
|
||||
|
||||
- [ ] Evaluate an Organizer RSS/Atom reader: subscriptions/folders, unread/recent
|
||||
views, search, bookmarks and explicit article-to-Wiki capture with provenance.
|
||||
- [ ] Compare a built-in reader, integration with FreshRSS, and integration with
|
||||
newsboat. Review their supported interfaces and deployment requirements before
|
||||
choosing an API or promising bidirectional interoperability.
|
||||
- [ ] Decide ownership of subscriptions and read/starred state; define import/
|
||||
export (including OPML), synchronization direction, deduplication, conflicts,
|
||||
offline use, token scope and revocation. Do not assume reader states are portable.
|
||||
- [ ] Reuse background scheduling, bounded fetch/cache and notification facilities;
|
||||
define polling budgets, retention, failure backoff and private subscription ACLs.
|
||||
- [ ] Sanitize feed HTML, block unsafe outbound fetching/SSRF, control remote media,
|
||||
and require an explicit destination/publication warning when saving into Wiki.
|
||||
Distinguish incoming feed reading from the existing outgoing blog RSS feed.
|
||||
|
||||
## IMAP ingestion and mail-to-Wiki
|
||||
|
||||
- [ ] Design read-only IMAP ingestion first: account/folder scope, incremental
|
||||
checkpoints, message deduplication, retry limits and background event scheduling.
|
||||
- [ ] Preserve original MIME/EML provenance and reuse the existing EML viewer for
|
||||
safe HTML/text and attachment handling. Never execute active email content.
|
||||
- [ ] Offer an explicit “Copy to Wiki” operation selecting destination Path and
|
||||
title, with an optional source-message backlink and attachment copy policy.
|
||||
- [ ] Importing a message must not delete/move/mark it read remotely by default.
|
||||
External mutations need separate, explicit configuration and audit.
|
||||
- [ ] Resolve the confidentiality boundary when copying private mail into an
|
||||
automatically public Street/Spot: show a disclosure warning, source/attachment
|
||||
scope and explicit confirmation; no automatic public destination default.
|
||||
- [ ] Plan credential storage, OAuth/app-password handling, message size quotas,
|
||||
attachment scanning, quarantine, deduplication and storage retention.
|
||||
|
||||
## HTML editing: do we actually need full WYSIWYG?
|
||||
|
||||
- [ ] Record real editing pain points before choosing an editor engine. Full
|
||||
WYSIWYG is an open decision, **not a committed implementation**.
|
||||
- [ ] First evaluate small improvements: reusable HTML-part insertion, tables,
|
||||
images/captions, callouts, links, code blocks and keyboard-friendly commands.
|
||||
- [ ] Compare source+preview, selection-based formatting, constrained block editing
|
||||
and full rich-text editing for fidelity, accessibility, performance and maintenance.
|
||||
- [ ] Define immutable round-trip fixtures for macros, assets, embedded adapters,
|
||||
code blocks and arbitrary existing HTML. Editing must not persist expanded macro
|
||||
projections or destructively rewrite unsupported markup.
|
||||
- [ ] Keep canonical HTML, editable representation and safe public rendering
|
||||
distinct. Consider undo/redo, dirty-state warnings, revision conflicts and paste
|
||||
sanitization before collaboration or full rich-text editing.
|
||||
- [ ] Prototype behind an explicit opt-in and decide go/no-go from lossless editing
|
||||
and user value, rather than committing to full WYSIWYG as a prerequisite.
|
||||
|
||||
## Prerequisite order
|
||||
|
||||
Scope/identity/ACL design → extension contracts → small read-only prototypes →
|
||||
write/conflict handling → external synchronization. Prefer reusable notification,
|
||||
scheduler, import journal and storage facilities already on the roadmap.
|
||||
@@ -0,0 +1,94 @@
|
||||
# Recursive Path mutation integrity
|
||||
|
||||
Implemented 2026-09-14. This is a correctness boundary for semantic Path
|
||||
rename, copy and unlink, not a change to the Address/URI identity model.
|
||||
|
||||
## Authorization and write protocol
|
||||
|
||||
1. Normalize absolute API Paths using the same whitespace and trailing-slash
|
||||
rules as the Path store. Do not fold case, decode a second time, or interpret
|
||||
`%`, `_` or `\` as patterns. Reject root mutations.
|
||||
2. Obtain a server-side `PathMutationSnapshot` containing the normalized root,
|
||||
Domain, recursive flag and exact ordered Path/Object bindings. Creation time
|
||||
and primary-link metadata are included so a changed binding is not silently
|
||||
overwritten.
|
||||
3. Authorize each captured source Path and, for rename/copy, its computed
|
||||
destination. The snapshot is an opaque in-process value, never JSON supplied
|
||||
by a client. Permission failures disclose neither descendants nor preview
|
||||
metadata. Preview results are taken from this same checked snapshot.
|
||||
4. Begin a store transaction, enumerate with the identical predicate and compare
|
||||
the whole binding set with the snapshot **before the first write**. Added,
|
||||
removed or rebound descendants, and wrong Domain/root/recursive scopes,
|
||||
reject the operation with HTTP 409. The client must start a fresh operation
|
||||
to obtain fresh authorization; there is no unchecked automatic retry.
|
||||
5. Keep revalidation and all writes inside the same SQLite transaction. A writer
|
||||
that commits after revalidation invalidates a WAL read snapshot: SQLite
|
||||
rejects its upgrade with `SQLITE_BUSY_SNAPSHOT`, also translated to 409.
|
||||
After the first write the transaction holds SQLite's write lock. This is not
|
||||
an assertion of equivalent isolation for a future database backend.
|
||||
|
||||
For multi-selection unlink, validate **all** selected scopes before removing
|
||||
any binding. Overlapping scopes are deduplicated inside the transaction. No
|
||||
Object, Revision or Document is deleted by unlink. Rename retains identity and
|
||||
updates filename Revision metadata and City boundaries transactionally; copy
|
||||
allocates independent Object/Revision identities while reusing content hashes.
|
||||
|
||||
Local trusted code and the administrative CLI can retain the existing unchecked
|
||||
`RenamePathsInDomain` / `CopyPathsInDomain` entry points; these still use the
|
||||
literal bounded enumerator and an atomic transaction. HTTP mutation handlers use
|
||||
the `Checked` methods exclusively.
|
||||
|
||||
## Object purge is a separate authority boundary
|
||||
|
||||
`object/delete` remains a purge: it removes the Object, its Revisions and all
|
||||
bindings, not just the current Path. Its HTTP handler now requires POST and a
|
||||
4 KiB JSON body limit. A store-issued `ObjectDeletionSnapshot` enumerates **all**
|
||||
bindings across Domains and rejects the request if any binding belongs to a
|
||||
different Domain. Every local Path needs a delete grant; one allowed alias or
|
||||
an Object-only grant cannot authorize deleting ungranted aliases. Unknown and
|
||||
unbound Objects fail closed even for a Domain administrator, because the current
|
||||
schema cannot prove Domain ownership without a binding.
|
||||
|
||||
The scoped purge revalidates the exact complete binding set in the purge
|
||||
transaction. A newly added local/foreign alias, removal or rebinding invalidates
|
||||
the operation with HTTP 409. Paths, tags, Revisions and the Object are deleted
|
||||
atomically; immutable content-addressed Documents remain for separate retention/
|
||||
garbage-collection policy. The old global `DeleteObject` store entry point is
|
||||
retained for trusted local administrative callers, not HTTP. Tests cover mixed
|
||||
local grants, shared/unknown/unbound Objects, late alias changes, rollback after
|
||||
Path deletions and successful full purge while retaining the immutable Document.
|
||||
|
||||
## Bounded, literal enumeration
|
||||
|
||||
The Domain/Path index is queried using separate exact and descendant range arms:
|
||||
`path = root` and `root + '/' <= path < root + '0'` with binary collation.
|
||||
This preserves storage case sensitivity and treats SQL wildcard characters
|
||||
literally. A lexical index order places parents before their descendants without
|
||||
a full length sort. The root listing special case excludes the exact root from
|
||||
the descendant arm to avoid duplicates. A query-plan regression checks index
|
||||
range use and absence of a temporary sort.
|
||||
|
||||
One scope/mutation is limited to 10,000 bindings; the API additionally limits
|
||||
unlink selections to 1,000 roots and caps cumulative authorization work at
|
||||
10,000 captured bindings. Oversized operations return HTTP 413, never a partial
|
||||
success. Split large trees into smaller independently authorized operations.
|
||||
All mutation endpoints and rename previews require POST and cap JSON bodies at
|
||||
1 MiB where applicable.
|
||||
|
||||
## Verification and remaining boundaries
|
||||
|
||||
Regression tests cover literal percent/underscore/backslash and case-different
|
||||
neighbors, normalization, denied descendants and destinations, preview leakage,
|
||||
second-connection additions/removals/rebinding between authorization and write,
|
||||
the post-revalidation WAL race, wrong/forged snapshot scope, overlapping deletes,
|
||||
size caps, index plans and rollback after an injected second write (including
|
||||
copied Object/Revision rows).
|
||||
|
||||
This slice does not make authorization-policy updates and Path writes share one
|
||||
transaction. Revocation between the final grant check and the write still needs
|
||||
a policy-version precondition or a transaction-aware authorization service.
|
||||
Copying an Object with a very long Revision history can also exceed an acceptable
|
||||
interactive duration even with the binding cap; a durable authorized background
|
||||
operation is a follow-up. Cross-Domain or unbound Object purge requires a future
|
||||
explicit global administrative ownership/retention policy; it is not inferred
|
||||
from a Domain-scoped request.
|
||||
@@ -0,0 +1,168 @@
|
||||
# Platform Extension Architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
This document keeps current implementation choices from closing off planned
|
||||
collaboration, federation, high-availability, content, security, and storage
|
||||
features. It defines extension boundaries, not permission to bypass existing
|
||||
identity or authorization rules.
|
||||
|
||||
## Non-negotiable identity boundaries
|
||||
|
||||
Future features attach to stable identities:
|
||||
|
||||
| Feature data | Stable attachment |
|
||||
| --- | --- |
|
||||
| semantic navigation | `(domain_uuid, path)` binding |
|
||||
| content history | Page UUID and immutable Revision UUID |
|
||||
| payload | Document SHA-256 |
|
||||
| inline comment | Page UUID + Revision UUID + range/context anchor |
|
||||
| thread, like, view, quality | Page UUID, optionally Revision UUID |
|
||||
| City service | Campus/Domain/Zone/Spot UUID |
|
||||
| notification | event UUID + recipient Principal UUID |
|
||||
| share | delegated capability ID, never a copied Page |
|
||||
|
||||
Comments, likes, counters, inbox state, quality scores, and diary metadata must
|
||||
not be inserted into canonical Page HTML as hidden mutable state. Renaming a
|
||||
Path must not detach them. Creating a Revision must not rewrite their history.
|
||||
|
||||
## Required platform contracts
|
||||
|
||||
### Event and outbox contract
|
||||
|
||||
Every canonical mutation emits a typed event in the same transaction as its
|
||||
state change. An event has an instance UUID, Domain UUID, monotonic Domain
|
||||
sequence, event type/version, actor, target typed address, authorization-safe
|
||||
summary, payload hash, timestamp, and idempotency key. Consumers maintain
|
||||
their own checkpoint. Notifications, feeds, view aggregation, federation,
|
||||
search, DR, webhooks, and quality automation consume events rather than adding
|
||||
callbacks to every write handler.
|
||||
|
||||
The scheduler owns retries, leases, priority, backoff, dead letters, logs, and
|
||||
resource quotas. Foreground Page reads and writes always outrank extension
|
||||
jobs. Delivery is at least once; consumers must be idempotent.
|
||||
|
||||
### Authorization contract
|
||||
|
||||
Every new endpoint declares a typed policy target and operation. Effective
|
||||
permissions can be explained and enumerated without exposing inaccessible
|
||||
objects. Anonymous access is an explicit positive grant to an anonymous
|
||||
Principal class. A share token produces a caveat-limited Principal and never
|
||||
becomes a normal login session.
|
||||
|
||||
Cross-Domain policy sharing uses signed, sequenced records with an authoritative
|
||||
origin. It may inherit identities, groups, Roles, and selected positive grants;
|
||||
it never imports local secrets or silently grants access because Domains share
|
||||
a Campus. Revocation and origin loss are explicit states.
|
||||
|
||||
### Projection and conversion contract
|
||||
|
||||
Viewer, editor, print, preview, transpiler, diagram, widget, and export are
|
||||
projections of an immutable Revision. Adapter selection uses MIME, filename,
|
||||
declared capability, Domain policy, and bounded-delivery needs. Adapter output
|
||||
does not become identity.
|
||||
|
||||
Conversions record source format, compiler/provider ID and version, options,
|
||||
warnings, source map when available, output MIME, and output Document hash.
|
||||
External renderers receive bounded content or one-use retrieval capabilities,
|
||||
not database or unrestricted network access.
|
||||
|
||||
Widgets are registered providers. Document content may request a provider and
|
||||
resource ID, but may not supply executable JavaScript. Rendering uses a
|
||||
sandboxed iframe or sanitized server projection with explicit CSP, consent,
|
||||
origin allowlist, timeout, and privacy policy.
|
||||
|
||||
### Document Store contract
|
||||
|
||||
The canonical interface is content-addressed and supports:
|
||||
|
||||
```text
|
||||
Stat(sha256)
|
||||
Open(sha256) / ReadAt(sha256, offset, length)
|
||||
PutIfAbsent(expected_sha256, stream)
|
||||
Verify(sha256)
|
||||
DeleteUnreferenced(sha256, retention proof)
|
||||
```
|
||||
|
||||
Filesystem and S3 implementations obey the same contract. Bucket/key URLs are
|
||||
placement data and never appear in Revision identity. Metadata databases,
|
||||
credentials, signing keys, sessions, and comments do not belong in this store.
|
||||
|
||||
### Extension manifest contract
|
||||
|
||||
An extension declares stable ID, type, version, PagesWiki compatibility range,
|
||||
entry point, MIME/extensions, requested capabilities, outbound hosts, resource
|
||||
limits, configuration schema, migrations, health probe, and signature. Types
|
||||
include projection, editor, transpiler, diagram, widget, notification,
|
||||
inspection, storage, search, and theme.
|
||||
|
||||
Install, upgrade, disable, and rollback are explicit administrator operations.
|
||||
An unavailable extension degrades to a safe built-in projection; it cannot make
|
||||
canonical Page content unreadable or prevent raw immutable retrieval.
|
||||
|
||||
## Collaboration data model direction
|
||||
|
||||
- `page_activity_events` are append-only canonical facts.
|
||||
- `principal_recent_views` is private derived state with retention controls.
|
||||
- `page_metric_buckets` stores aggregated counts, not raw IP history forever.
|
||||
- `page_reactions` has `(domain_uuid, page_uuid, principal_uuid, reaction)`
|
||||
identity and an audit event.
|
||||
- `quality_assessments` records rubric/version and human or machine provenance.
|
||||
- `comment_threads` attach to Page or Revision; `comment_anchors` retain range,
|
||||
quoted context hash, and rebase/orphan state.
|
||||
- `notifications` reference events and store recipient delivery/read state;
|
||||
notification text is rendered at read time with current authorization.
|
||||
|
||||
Deletion and retention are explicit. A user losing access must stop seeing
|
||||
notification details even if an older notification row remains.
|
||||
|
||||
## Federation and disaster recovery direction
|
||||
|
||||
Controller desired state is a signed, monotonic manifest journal. DR replicates
|
||||
the journal, encrypted signing-key material under a documented recovery policy,
|
||||
and last-known-good snapshots. Promotion creates a new auditable epoch and
|
||||
fences the former leader. Managed instances pin permitted controller identities
|
||||
and reject sequence rollback or concurrent epochs.
|
||||
|
||||
Page Documents, metadata, event logs, and controller desired state have separate
|
||||
backup/replication policies. A Campus manifest is not a database backup.
|
||||
|
||||
## Load balancing and HA constraints
|
||||
|
||||
Application nodes should become disposable after canonical state is externalized:
|
||||
|
||||
- bearer/session validation keys and revocation state are shared or replicated;
|
||||
- background jobs use leases and idempotency keys;
|
||||
- caches are disposable and version-keyed;
|
||||
- uploads stream to canonical storage and do not depend on a later request
|
||||
reaching the same node;
|
||||
- WebSockets support drain/reconnect;
|
||||
- proxy headers are trusted only from configured proxies.
|
||||
|
||||
SQLite remains valid for one writable application node and local replicas or
|
||||
backups. Concurrent writers must use a metadata backend designed for it or a
|
||||
fenced leader; a writable SQLite file on NFS is prohibited.
|
||||
|
||||
## Security and privacy constraints
|
||||
|
||||
- External feeds, widgets, diagram services, and scanners use per-provider
|
||||
outbound allowlists, DNS/IP rebinding defenses, size/time limits, and logs.
|
||||
- Malware inspection is asynchronous but policy can quarantine download and
|
||||
adapter access until a required clean verdict exists.
|
||||
- View history and popularity avoid retaining unnecessary personal data.
|
||||
- Comments, reactions, shares, and notifications are covered by export,
|
||||
retention, moderation, abuse, and audit policy.
|
||||
- Theme packages supply CSS tokens/assets, never privileged script.
|
||||
|
||||
## Compatibility gates for current work
|
||||
|
||||
Before merging a feature, tests must show that it:
|
||||
|
||||
1. preserves Page UUID, Revision UUID, Document hash, and Domain Path semantics;
|
||||
2. declares authorization targets and anonymous/share behavior;
|
||||
3. remains bounded for payload, rows, recursion, time, and concurrency;
|
||||
4. emits versioned events for canonical mutations;
|
||||
5. tolerates retry and duplicate delivery;
|
||||
6. degrades safely when an extension or remote service is unavailable;
|
||||
7. supports migration rollback and mixed-version federation where applicable;
|
||||
8. does not assume process-local state in an HA-targeted code path.
|
||||
@@ -0,0 +1,467 @@
|
||||
# Projection Adapter Design
|
||||
|
||||
## Purpose
|
||||
|
||||
A document address identifies content. It does not select its renderer.
|
||||
Viewer chooses a projection adapter from document metadata and runtime
|
||||
capabilities:
|
||||
|
||||
```text
|
||||
internal address
|
||||
-> revision metadata
|
||||
-> effective MIME detection
|
||||
-> projection adapter selection
|
||||
-> bounded data delivery
|
||||
-> Viewer component
|
||||
```
|
||||
|
||||
The adapter boundary must remain independent from Semantic Path, Page UUID,
|
||||
Revision UUID, and raw payload delivery.
|
||||
|
||||
## Current Adapter Contract
|
||||
|
||||
The server registry in `internal/server/content_adapter.go` describes:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `ID` | Stable adapter identifier exposed as Viewer metadata |
|
||||
| `Kind` | Template component used by the current Viewer |
|
||||
| `Delivery` | HTML, decoded text, raw media, raw frame, or download |
|
||||
| `NeedsText` | Whether safe character decoding is required |
|
||||
| `WindowableText` | Whether large input must move to bounded retrieval |
|
||||
| `Match` | MIME and filename matching predicate |
|
||||
|
||||
Selection is ordered. Specific structured formats must precede generic JSON,
|
||||
text, and download adapters.
|
||||
|
||||
The initial registry reserves these stable IDs:
|
||||
|
||||
| Adapter | Current projection | Intended projection |
|
||||
| --- | --- | --- |
|
||||
| `html` | rendered HTML | rendered HTML |
|
||||
| `text` | CodeMirror text | windowed text |
|
||||
| `csv` | bounded table with sticky header | paginated virtualized table |
|
||||
| `excalidraw` | validated interactive canvas + source fallback | canvas + editor action |
|
||||
| `nwdiag` | bounded network diagram projection | static SVG preview + hosted/editor action |
|
||||
| `archive` | ZIP/RAR/7z/TAR entry table + comic mode | archive directory |
|
||||
| `eml` | decoded headers and body | multipart mail viewer |
|
||||
| `debian-package` | ar/control metadata | package metadata |
|
||||
| `pe` | PE/COFF headers and sections | executable metadata |
|
||||
| `image` | raw media | raw media |
|
||||
| `audio` | raw media | raw media |
|
||||
| `video` | raw media | raw media |
|
||||
| `pdf` | raw frame | PDF viewer |
|
||||
| `download` | download | download |
|
||||
|
||||
These adapters are built in and versioned with Pages Wiki. They are always
|
||||
listed by `GET /_/api/v1/adapter`; they are not configuration records and
|
||||
cannot be deleted by an administrator.
|
||||
|
||||
## Integration Adapter Plugins
|
||||
|
||||
Additional hosted viewers and editors are Domain-scoped integration adapter
|
||||
plugins. They may run at another FQDN or in a separately deployed container.
|
||||
They supplement the built-in projection and do not replace document identity,
|
||||
Raw delivery, or immutable Revision storage.
|
||||
|
||||
Each plugin declares:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `id` | Stable lowercase plugin identifier |
|
||||
| `name` | User-facing name in “Open with” |
|
||||
| `mode` | hosted `viewer` or hosted `editor` |
|
||||
| `media_types` | Exact MIME types or suffix-wildcards such as `image/*` |
|
||||
| `extensions` | Lowercase filename extensions |
|
||||
| `url_template` | Absolute HTTP(S) URL for the hosted service |
|
||||
| `enabled` | Whether it is offered at runtime |
|
||||
|
||||
Templates can use `{url}`, `{path}`, and `{filename}`. Substitutions are
|
||||
URL-encoded. `{url}` is an immutable Revision Raw URL; it never carries a
|
||||
third-party token. Only `http:` and `https:` templates are accepted.
|
||||
|
||||
Native application launch is not implemented. `vim.exe`, `code.exe`,
|
||||
`/usr/bin/vim`, custom URL schemes, a local workspace cache, and a Box Edit
|
||||
style helper remain a future TODO. Legacy `native` records remain visible but
|
||||
are disabled and are never returned as runtime actions.
|
||||
|
||||
Management and runtime discovery use:
|
||||
|
||||
```text
|
||||
GET /_/api/v1/adapter
|
||||
POST /_/api/v1/adapter
|
||||
POST /_/api/v1/adapter/delete
|
||||
GET /_/api/v1/adapter?path=/semantic/path
|
||||
GET /v/open-with?adapter=<id>&path=/semantic/path
|
||||
```
|
||||
|
||||
The server revalidates MIME/extension compatibility when `/v/open-with` is
|
||||
called. A context-menu URL is therefore not an authorization bypass.
|
||||
|
||||
### Hosted Deployment
|
||||
|
||||
A hosted adapter can be deployed beside Pages Wiki without being part of the
|
||||
Pages Wiki process:
|
||||
|
||||
```text
|
||||
pages.example.test -> Pages Wiki
|
||||
code.pages.example.test -> code-server + Pages Wiki adapter gateway
|
||||
vim.pages.example.test -> vim.wasm adapter
|
||||
```
|
||||
|
||||
The current integrated deployment uses one Pages Wiki origin and an internal
|
||||
Gateway service instead of publishing the Gateway port:
|
||||
|
||||
```text
|
||||
pages.anya.jp/_/adaptor/code/* -> adaptor-gateway:3000 -> code-server:8080
|
||||
pages.anya.jp/_/adaptor/vim/* -> adaptor-gateway:3000 -> vim.wasm assets/API
|
||||
```
|
||||
|
||||
`adaptor-gateway:3000` is available only on the Compose network. Pages Wiki
|
||||
owns the public `/_/adaptor/` route, forwards the prefix to the Gateway, and
|
||||
retains the prefix in redirects and cookie paths.
|
||||
|
||||
The first implementation opens the configured service in a top-level browser
|
||||
navigation. Cross-origin iframe embedding is not assumed; a service may opt in
|
||||
later with an explicit CSP `frame-ancestors` policy.
|
||||
|
||||
`vim.wasm` or a purpose-built Web editor can consume the immutable `{url}`
|
||||
directly for read-only use. A general code-server container cannot edit an HTTP
|
||||
Raw URL as a local workspace by itself. It requires an adapter gateway that:
|
||||
|
||||
1. exchanges a short-lived, one-use launch ticket;
|
||||
2. materializes the selected Revision inside a per-session workspace;
|
||||
3. opens that workspace in code-server;
|
||||
4. submits changed bytes as a new Revision with optimistic conflict checking;
|
||||
5. destroys or expires the workspace.
|
||||
|
||||
This launch and write-back contract is implemented by the reference
|
||||
`adaptor-gateway` container. An editor URL template must contain `{ticket}`;
|
||||
the ticket expires after 60 seconds and can be exchanged only once. The
|
||||
gateway stores the resulting eight-hour session bearer server-side and sends
|
||||
it in an Authorization header. Saving creates a new Revision. If the base
|
||||
Revision is no longer current, Pages Wiki returns HTTP 409 and preserves both
|
||||
versions without silently overwriting either one.
|
||||
|
||||
The reference gateway materializes the selected file and its descendant
|
||||
documents in an isolated session directory
|
||||
on a dedicated workspace volume and opens that directory through an internal
|
||||
code-server instance. code-server is not published on a host port and runs
|
||||
with authentication disabled only inside the Compose network; the Gateway
|
||||
requires its HttpOnly adapter session before proxying `/code/`, including
|
||||
WebSocket traffic. A watcher submits changed target bytes as a new Revision.
|
||||
Relative hierarchy and a separate optimistic base Revision are retained for
|
||||
every file. Hosted plugin settings can request a new browser tab and an
|
||||
HTML/Markdown round trip: HTML becomes Markdown in the workspace and is
|
||||
rendered back to canonical HTML when saved.
|
||||
vim.wasm integrates behind this same Gateway contract rather than receiving
|
||||
Pages Wiki database or Document Store access. The Gateway loads the session
|
||||
workspace into vim.wasm MEMFS. A `BufWritePost` hook exports the written file,
|
||||
and the browser sends those bytes through the scoped session API to create a
|
||||
new Revision.
|
||||
|
||||
vim.wasm, its Worker, Wasm binary, and data archive are served with
|
||||
`Cross-Origin-Opener-Policy: same-origin`,
|
||||
`Cross-Origin-Embedder-Policy: require-corp`, and
|
||||
`Cross-Origin-Resource-Policy: same-origin`. The deployment must also use a
|
||||
secure context. A trusted HTTPS adapter URL is preferred; loopback development
|
||||
may use `http://localhost`, which browsers treat as potentially trustworthy.
|
||||
|
||||
```text
|
||||
POST /_/api/v1/adapter/session/exchange
|
||||
GET /_/api/v1/adapter/session/workspace
|
||||
GET /_/api/v1/adapter/session/content
|
||||
PUT /_/api/v1/adapter/session/content
|
||||
```
|
||||
|
||||
Recommended container boundaries are:
|
||||
|
||||
- a dedicated origin and cookie namespace;
|
||||
- an allowlist of adapter origins in Pages Wiki;
|
||||
- no direct mount of the Pages Wiki Document Store or SQLite database;
|
||||
- CPU, memory, process, and workspace quotas per adapter container;
|
||||
- immutable Revision download through Pages Wiki APIs only;
|
||||
- write-back through the narrowly scoped adapter session capability only.
|
||||
- code-server terminal and extension privileges confined to its container;
|
||||
- only the adapter workspace volume shared with the Gateway.
|
||||
|
||||
## File Context Menu
|
||||
|
||||
Directory, search, and file-manager projections expose the same contextual
|
||||
operations: open, rename, copy, paste, move, recursive delete, and “Open
|
||||
with”. Copy/paste uses a browser-local clipboard containing Semantic Paths;
|
||||
the server performs the actual Domain-scoped copy through
|
||||
`POST /_/api/v1/path/copy`.
|
||||
|
||||
A copied Page receives new Object and Revision UUIDs. Its immutable Document
|
||||
hashes are reused, and its Revision history and metadata are preserved. Copy
|
||||
therefore means an independent Page, not a new Path link to the source.
|
||||
“Open with” is shown only for adapters matching the resolved latest Revision.
|
||||
|
||||
Fallback rendering is intentional. Recognizing a format and providing an
|
||||
interactive renderer are separate capabilities.
|
||||
|
||||
PDF page counts and non-ZIP archive listings now use the persistent, bounded
|
||||
[`projection.metadata.generate` cache](projection-metadata-cache.md). Viewer
|
||||
requests enqueue missing metadata and render explicit pending/retry states;
|
||||
decoder subprocesses execute only in the scheduler. Cached entry names remain
|
||||
plain data and receive authorized, immutable-Revision links at response time.
|
||||
|
||||
## Metadata UI
|
||||
|
||||
Viewer must not reserve a full horizontal row for MIME information.
|
||||
Document metadata is exposed from the information control at the right of the
|
||||
breadcrumb bar. It contains:
|
||||
|
||||
- filename
|
||||
- effective MIME type
|
||||
- selected adapter
|
||||
- payload size
|
||||
|
||||
The control must work with both pointer hover and keyboard focus.
|
||||
|
||||
## Web Upload
|
||||
|
||||
`/v/upload` accepts a destination Semantic Path and one file. A destination
|
||||
ending in `/` appends the uploaded filename. An exact existing Path creates a
|
||||
new Revision of the existing Page; it never destroys history. Upload stores the
|
||||
original filename and detected MIME type as Revision metadata.
|
||||
|
||||
The request is bounded to 256 MiB. Specialized resumable upload is a separate
|
||||
future adapter and must not silently raise this synchronous request limit.
|
||||
|
||||
## Media Interaction
|
||||
|
||||
Image projection opens a modal full-viewport lightbox from the inline preview.
|
||||
Audio and video projections retain native controls and add a common toolbar for
|
||||
elapsed time and playback rate. Video additionally exposes Picture-in-Picture
|
||||
when supported and full-screen projection. Raw media remains Range-capable.
|
||||
|
||||
ZIP entries are exposed through a scoped archive-entry projection. It resolves
|
||||
the archive by Domain and semantic Path and never accepts a host filesystem
|
||||
path. Comic mode includes recognized image entries and lazy-loads them in
|
||||
archive order.
|
||||
|
||||
## Folder Search
|
||||
|
||||
The topbar search form sends the current semantic Path as its scope. SQLite
|
||||
searches effective Paths and latest Revision filenames inside that segment
|
||||
boundary and returns at most 100 results. The scope parameter is retained so a
|
||||
later Domain-wide FTS index can add “all” search without changing the topbar
|
||||
contract.
|
||||
|
||||
## Children Macro Views
|
||||
|
||||
Macro processing has explicit modes:
|
||||
|
||||
| Mode | `children` behavior |
|
||||
| --- | --- |
|
||||
| Authoring HTML → Markdown | Preserve the macro source verbatim |
|
||||
| Markdown editor preview | Render Markdown to HTML, then expand the macro |
|
||||
| Saved Viewer projection | Expand from canonical stored HTML |
|
||||
| Markdown source projection | Preserve authoring source |
|
||||
|
||||
Expansion must never run before an authoring round trip: generated async
|
||||
projection markup is runtime output and must not replace the macro in the
|
||||
editor or a subsequent Revision.
|
||||
|
||||
The macro only selects the child Path. Presentation is viewer state rather
|
||||
than document content:
|
||||
|
||||
```text
|
||||
{{children}}
|
||||
{{children:/gallery}}
|
||||
{{children:/downloads exclude=/downloads/private}}
|
||||
```
|
||||
|
||||
The breadcrumb action area exposes thumbnail, detail, and normal-list views.
|
||||
The selected view is stored locally and applies to every `children` projection
|
||||
on the page. Legacy `view=`, `mode=`, and `compact` arguments are ignored.
|
||||
`exclude=` remains part of the macro because it changes the projected set.
|
||||
|
||||
Ctrl/Command-click toggles selection without following the link. Right-clicking
|
||||
a selected item opens bulk move and recursive-delete actions. Moving a virtual
|
||||
folder renames its Path prefix, preserving Object and Revision identity.
|
||||
|
||||
The macro initially emits a lightweight placeholder. Viewer fetches the
|
||||
Domain-scoped `/v/children` projection asynchronously, so Page HTML and other
|
||||
macros are not blocked by metadata or thumbnail discovery.
|
||||
|
||||
Children are delivered in bounded pages. There is no explicit “More” action:
|
||||
an IntersectionObserver requests the next page when its sentinel approaches
|
||||
the viewport, including touch/drag scrolling. The item grid and labels are
|
||||
painted before any preview payload is requested.
|
||||
|
||||
Icon projection uses generated, immutable thumbnails for images, first-page
|
||||
PDF previews, video frames, and Excalidraw scenes. Folders, ZIP archives,
|
||||
Debian packages, audio, plain text, and source code use format-specific SVG
|
||||
icons. Cache checks are viewport-prioritized. Mutable `path:` raw projections
|
||||
use a short private cache; immutable `rev:` projections use a one-year
|
||||
immutable cache and ETag.
|
||||
|
||||
Preview I/O is a background workload. The browser:
|
||||
|
||||
- paints item frames and labels before scheduling preview work;
|
||||
- starts work during an idle period;
|
||||
- allows at most two concurrent previews, or one on data-saver/2G links;
|
||||
- observes only items within 250 px of the viewport;
|
||||
- cancels queued fetches and active Excalidraw requests on page departure.
|
||||
|
||||
Preview Raw URLs carry `preview=1`. The server isolates those requests behind a
|
||||
single global preview slot. Normal Viewer navigation, APIs, and non-preview Raw
|
||||
delivery never wait for this slot.
|
||||
|
||||
File-manager thumbnails no longer use Raw PDF frames or browser video
|
||||
decoders. They consume only immutable files produced by the persistent
|
||||
[event scheduler](event-scheduler.md). Until generation succeeds, the icon
|
||||
projection remains a lightweight format icon.
|
||||
|
||||
## Raw and Derived Projection URLs
|
||||
|
||||
Adapters never construct an alternative identity URL. Raw bytes continue to
|
||||
use an explicit internal address:
|
||||
|
||||
```text
|
||||
/v/raw/path:/reports/annual.pdf
|
||||
/v/raw/uuid:<page-uuid>
|
||||
/v/raw/rev:<revision-uuid>
|
||||
```
|
||||
|
||||
Structured viewers use derived endpoints below `/v/<adapter>/` and carry the
|
||||
same address forms. Proposed examples:
|
||||
|
||||
```text
|
||||
/v/text/path:/logs/server.log?offset=0&limit=65536
|
||||
/v/csv/rev:<revision-uuid>?row=0&limit=200
|
||||
/v/archive/rev:<revision-uuid>?path=/usr/bin
|
||||
/v/deb/rev:<revision-uuid>
|
||||
/v/excalidraw/rev:<revision-uuid>
|
||||
```
|
||||
|
||||
Printable projections use the address-model route
|
||||
`/_/view/print/{path:|uuid:|rev:}` and pin every Raw dependency to the selected
|
||||
immutable Revision. Text and CSV print output is bounded to 2 MiB; media is
|
||||
printed from metadata plus its immutable Raw URL without hydrating its body.
|
||||
Structured formats above the synchronous hydration ceiling degrade to a
|
||||
download link instead of blocking foreground navigation.
|
||||
|
||||
A mutable `path:` request may resolve to a revision and return its UUID in the
|
||||
response. Paging requests after the first response must use `rev:` so a
|
||||
changing current document cannot mix two revisions in one Viewer session.
|
||||
|
||||
## Large Text and JSON
|
||||
|
||||
The current inline text threshold is 2 MiB. Crossing the threshold is recorded
|
||||
as a requirement for windowed delivery. The complete scalable implementation
|
||||
must not hydrate or embed the full document merely to render its first screen.
|
||||
|
||||
The text adapter will use:
|
||||
|
||||
1. metadata-only revision lookup;
|
||||
2. a seekable Document Store reader;
|
||||
3. byte-window retrieval with a fixed server maximum;
|
||||
4. UTF boundary repair and explicit byte offsets;
|
||||
5. line-index checkpoints built asynchronously or lazily;
|
||||
6. client virtualization for visible lines and minimap summaries.
|
||||
|
||||
JSON uses bounded structural streaming at `/v/json/rev:<revision-uuid>`.
|
||||
Expansion fetches a capped direct-child range selected by JSON Pointer. The
|
||||
request handler streams tokens and never unmarshals the complete payload;
|
||||
nested containers are revisited lazily from the immutable Document. A future
|
||||
persistent checkpoint index may accelerate deep pointers without changing the
|
||||
API or Revision identity.
|
||||
|
||||
Responses should include:
|
||||
|
||||
```text
|
||||
revision_uuid
|
||||
document_hash
|
||||
content_type
|
||||
total_bytes
|
||||
offset
|
||||
next_offset
|
||||
line_start
|
||||
line_end
|
||||
truncated
|
||||
```
|
||||
|
||||
Range limits, parse depth, row count, archive entries, and decompressed bytes
|
||||
must be capped server-side.
|
||||
|
||||
## CSV Viewer
|
||||
|
||||
CSV detection uses MIME type or `.csv`. The derived adapter must:
|
||||
|
||||
- sniff delimiter and quoting from a bounded prefix;
|
||||
- expose encoding and dialect in metadata;
|
||||
- paginate rows;
|
||||
- virtualize columns and rows in the browser;
|
||||
- preserve the immutable Revision during paging;
|
||||
- fall back to the text adapter on malformed input.
|
||||
|
||||
## nwdiag network diagrams
|
||||
|
||||
`nwdiag` is a source/document format, not an instruction to execute arbitrary
|
||||
code. The adapter parses a bounded, version-pinned grammar and produces a
|
||||
static SVG (or PNG) projection. It must reject oversized graphs, recursive
|
||||
includes, external image/font imports, unsafe SVG attributes, and unknown
|
||||
directives rather than forwarding them to a renderer. The source Revision is
|
||||
immutable and remains available through the plain/source view.
|
||||
|
||||
An optional hosted editor is a separate `viewer`/`editor` adapter. It receives
|
||||
only an immutable Revision URL and a one-use save ticket, never the browser
|
||||
session token. Save uses optimistic Revision checks and creates a new source
|
||||
Revision; rendering is queued and cached by `(document hash, parser version,
|
||||
theme, renderer version)`. If the renderer or editor is unavailable, the Viewer
|
||||
shows escaped source and the last verified static projection. A future Kroki
|
||||
provider may render nwdiag, but network access, origin allowlists, timeout,
|
||||
resource quotas, and provider version must be explicit.
|
||||
|
||||
## ZIP Viewer
|
||||
|
||||
ZIP projection lists entries without extracting them into the data directory.
|
||||
Entry paths must be normalized and zip-slip paths rejected. Limits apply to
|
||||
entry count, nested archives, compression ratio, total expanded size, and
|
||||
individual previews. Entry download is a derived projection of the containing
|
||||
Revision and entry path.
|
||||
|
||||
## Debian Package Viewer
|
||||
|
||||
The DEB adapter reads the outer `ar` members and bounded control archive only.
|
||||
It exposes package name, version, architecture, dependencies, description,
|
||||
installed size, checksums, and a bounded file list. Maintainer scripts render
|
||||
as escaped text. No package script is executed.
|
||||
|
||||
## Excalidraw
|
||||
|
||||
`.excalidraw` files are recognized before generic JSON. The renderer validates
|
||||
a bounded scene graph and produces an isolated canvas projection.
|
||||
|
||||
The preferred projection is the bundled `org.pageswiki.excalidraw-viewer`
|
||||
plugin. It runs `@excalidraw/excalidraw` in read-only view mode in a separate
|
||||
container and is routed through `/_/adaptor/excalidraw/`. Pages Wiki passes
|
||||
only an immutable same-origin `rev:` Raw URL. The plugin rejects mutable,
|
||||
cross-origin, and over-2-MiB inputs, is framed with a restrictive CSP, and
|
||||
reports readiness through `postMessage`. A timeout, load failure, or invalid
|
||||
scene activates the dependency-free built-in Canvas renderer.
|
||||
|
||||
Configuration may provide an editor URL template. The action receives a
|
||||
read-capable document URL and, only when explicitly authorized, a save callback
|
||||
or capability. Tokens must not be placed in a third-party URL query string.
|
||||
Without a configured editor, Viewer offers the internal canvas and source
|
||||
fallback.
|
||||
|
||||
## Security and Failure Rules
|
||||
|
||||
- Normal HTML displays use the common `controlled-v2` allowlist and application CSP;
|
||||
saved source remains unchanged. Raw HTML attachment, raw/diagram SVG sandbox,
|
||||
and registered application frames retain their separate response contracts.
|
||||
There is no executable authored-HTML mode. See
|
||||
[HTML projection trust and compatibility](html-projection-trust.md); public
|
||||
shares and anonymous viewing still require their own authorization gates.
|
||||
- Archive and package adapters never execute contained files.
|
||||
- Derived adapters operate on immutable revisions after initial resolution.
|
||||
- MIME detection is advisory; parser validation is authoritative.
|
||||
- An unavailable or failed specialized adapter falls back to safe text or
|
||||
download behavior.
|
||||
- Adapter errors do not change document identity or stored content.
|
||||
@@ -0,0 +1,109 @@
|
||||
# Deferred PDF and archive metadata
|
||||
|
||||
Implemented: 2026-09-14. PDF page counts and non-ZIP archive listings no longer
|
||||
run `pdfinfo` or `7z` inside a Viewer, preview, print, or metadata HTTP request.
|
||||
|
||||
## Request and worker contract
|
||||
|
||||
The existing authorized routes expose a metadata mode:
|
||||
|
||||
| Request | Resolution and authorization |
|
||||
| --- | --- |
|
||||
| `/v/pdf-page?rev=<UUID>&metadata=1` | immutable Revision → owning Object's current read authority |
|
||||
| `/v/archive?path=<Path>&rev=<UUID>&metadata=1` | current Domain Path read authority; supplied Revision must belong to that Path's Object |
|
||||
|
||||
The cache is never addressed by an unauthenticated hash-only public endpoint.
|
||||
Authorization is checked even for ready/failed cache hits. Responses vary on
|
||||
`Authorization, Cookie` and use `private, no-store`, so revoked access cannot
|
||||
be bypassed through a browser-cached metadata response.
|
||||
|
||||
- `202`: `{"status":"pending"}`, with `Retry-After: 2`.
|
||||
- `200`: `{"status":"ready", "pdf_pages": N}` or bounded archive `entries`.
|
||||
- `422`: a cached failed projection, with a retry timestamp and `Retry-After`.
|
||||
- `503`: queue/storage unavailable; raw download is still an independent path.
|
||||
|
||||
A miss enqueues `projection.metadata.generate`, keyed by
|
||||
`<parser version>:<kind>:<immutable Document SHA-256>`. Its payload contains only
|
||||
the hash, kind (`pdf` or `archive`), and parser version. Active queue entries are
|
||||
idempotent across requests. Metadata uses the existing scheduler concurrency,
|
||||
pause, foreground-work reservation, cancellation, logs, and manual retry UI;
|
||||
it does not create an independent worker pool. Its priority is currently -5,
|
||||
below ordinary preview jobs, and its max attempts is 1. A failed decoder result
|
||||
is cached for five minutes to prevent repeated visits from creating a retry
|
||||
storm; a scheduler manual retry can run it earlier.
|
||||
|
||||
The semantic Viewer and preview use a metadata-only fast path for PDFs and
|
||||
non-ZIP archives. They do not load the entire Revision body before queueing.
|
||||
The worker opens the immutable Document Store file directly; there is no
|
||||
request-time archive copy into a temporary file. Print uses the same metadata
|
||||
cache for archive tables. Raw PDF iframe delivery remains independent.
|
||||
|
||||
## Persistent cache and bounds
|
||||
|
||||
`projection_metadata` is keyed by `(document_hash, kind, version)`. The payload
|
||||
contains no semantic Path, Revision UUID, generated entry URL, principal, or
|
||||
credential. Request-specific archive links are created after authorization and
|
||||
pin the viewed Revision, so replacing the Page cannot silently extract an entry
|
||||
from a different archive revision.
|
||||
|
||||
| Boundary | Current limit |
|
||||
| --- | --- |
|
||||
| Input Document | 512 MiB, regular Document Store file |
|
||||
| Decoder wall time | 30 seconds; one-second process wait grace |
|
||||
| PDF stdout / accepted count | 64 KiB / 1–10,000 pages |
|
||||
| `7z` stdout | 4 MiB, with partial listing explicitly marked truncated |
|
||||
| Archive entries | 2,000 |
|
||||
| Entry name / total name bytes | 4 KiB / 256 KiB; UTF-8, no control characters |
|
||||
| One persisted result | 1 MiB |
|
||||
| Aggregate cache | 64 MiB payload/error budget and 2,048 records |
|
||||
|
||||
External commands use `nice -n 15`; `7z` has one decoder thread, no interactive
|
||||
password prompt, and no shell interpolation. Output is bounded by a writer
|
||||
that does not expose `bytes.Buffer.ReadFrom` (which would bypass the writer
|
||||
limit through `io.Copy`). Excess output cancels the process. Cache eviction is
|
||||
performed transactionally by the background writer, oldest generation first;
|
||||
foreground hits do not update timestamps or trigger global eviction scans.
|
||||
Evicted entries can be reconstructed from immutable Documents.
|
||||
|
||||
## Browser behavior
|
||||
|
||||
Pending and failed states are explicit and localized in Japanese and English.
|
||||
The client polls every 2–10 seconds, stops after 60 pending polls, pauses while
|
||||
the tab is hidden, and aborts on page exit. A retry button handles a paused queue,
|
||||
network failure, or cached decoder failure. It does not reload the whole page.
|
||||
PDF navigation picks up the total as soon as metadata arrives. An asynchronously
|
||||
loaded archive table is built using DOM text nodes, never filename HTML. Comic
|
||||
mode initializes once its images arrive and preserves single/spread pages,
|
||||
keyboard navigation, hidden inactive images, and browser-history behavior.
|
||||
|
||||
ZIP remains the existing in-process central-directory Viewer and comic mode;
|
||||
its displayed listing is capped at 2,000 entries and its entry URLs now also pin
|
||||
the Revision. Large ZIP central-directory parsing still needs a later metadata
|
||||
worker migration if such archives become common.
|
||||
|
||||
## Explicitly deferred work
|
||||
|
||||
- Non-ZIP **entry extraction** still streams through `7z` in the request path,
|
||||
capped at 128 MiB and 60 seconds. It now treats entry names literally (no
|
||||
wildcard or `@listfile` expansion), safely formats response filenames, and
|
||||
cancels the child when the output cap/client disconnect stops draining it.
|
||||
Persisted, seekable entry projections require their own storage quota,
|
||||
leases, Range/cache semantics, and archive-bomb policy.
|
||||
- Listing is the top-level listing reported by `7z`, not an unlimited recursive
|
||||
traversal of nested archives. Compressed TAR envelopes and nested containers
|
||||
require a separate bounded expansion/index contract.
|
||||
- Per-child-process memory/cgroup quotas and hardened decoder isolation remain
|
||||
deployment work. Input/output/thread/time limits do not imply a hard peak
|
||||
memory bound inside a native decoder.
|
||||
- Multi-instance worker leases and cancellation fencing remain scheduler-wide
|
||||
work; this feature does not claim distributed exactly-once execution.
|
||||
|
||||
## Tests
|
||||
|
||||
Store tests cover key/payload validation, parser-version separation, persistence,
|
||||
and eviction. Server tests prove that cold Viewer/print/metadata calls do not
|
||||
invoke tools, repeated requests enqueue one job, cached authorization denial
|
||||
does not leak metadata or enqueue work, decoder errors are cached, limits are
|
||||
enforced, and ZIP links retain immutable revisions. Opt-in Chromium tests cover
|
||||
pending → ready PDF/table/comic UI, cached failure/retry presentation, and
|
||||
hostile archive filenames rendered as text.
|
||||
@@ -0,0 +1,116 @@
|
||||
# Permission-aware public navigation
|
||||
|
||||
Implemented 2026-09-16. Ordinary approved public Pages are navigable; the isolated,
|
||||
navigation-free presentation belongs to the future share-URL surface, not normal
|
||||
public semantic URLs. No share tokens/endpoints are added in this slice.
|
||||
|
||||
## Public surfaces
|
||||
|
||||
- Public Page headers have a Domain home link, breadcrumbs, directory/tree/City
|
||||
links and login. A parent-folder action and child-directory action make Pages
|
||||
with descendants traversable even without a `children` macro. Mobile headers
|
||||
use labelled icons; keyboard focus and a skip-to-content link are provided;
|
||||
the download button is removed. Existing authorized raw media remains usable.
|
||||
- `children` is expanded to asynchronously fetched, read-only listings, with
|
||||
list/detail/icon modes and lazy continuation. `city`, breadcrumbs, locality
|
||||
links and `spot-pages` use public projections. No private diagram/asset job
|
||||
or neighbor-relation expansion is triggered on an anonymous request.
|
||||
- GET/HEAD `/v/children`, `/v/tree[/{path}]`, `/v/browser[/{path}]`, `/v/city` and
|
||||
`/_/api/v1/city/map` admit absent credentials under enforcing mode. Invalid or
|
||||
expired credentials still cannot downgrade to anonymous. No new mutation,
|
||||
governance, search, object-hash/UUID or history route is opened.
|
||||
- Listings derive from currently approved Path/Object/Revision tuples, using
|
||||
the same live binding/head/governance/topology predicate as body/raw reads.
|
||||
A newly created or edited but unapproved child is not discoverable.
|
||||
- Private/absent parent bodies do not block traversal to public descendants:
|
||||
their already-disclosed URL segments become structural folders linking to
|
||||
`/v/tree/{path}`. This does not authorize the parent Page's body or metadata.
|
||||
Direct semantic requests for a parent (including `/`) also show the safe
|
||||
directory when it has approved descendants but no approved body. Raw requests
|
||||
never fall back to folders. If there are no approved descendants, the ordinary
|
||||
semantic authentication behavior is retained; explicit `/v/browser` and
|
||||
`/v/tree` roots show an empty public index. Unknown/private branches still fail.
|
||||
- City topology is filtered to visible branches. Titles/labels are derived from
|
||||
approved Paths, not private locality prose or placement labels; custom
|
||||
descriptions, summaries and relations are suppressed. Page counts and portals
|
||||
use approved Pages only. Unmapped approved Pages remain reachable in the tree.
|
||||
- Response HTML and JSON remain `private, no-store`. A dedicated public header
|
||||
does not expose private bookmarks, account state or administrative controls.
|
||||
Application CSP also covers the public tree and City Map.
|
||||
|
||||
## Navigation UX hardening — 2026-09-16
|
||||
|
||||
- `/v/browser/{path}` is a dedicated read-only public directory projection, not
|
||||
the authenticated file manager. Initial entries are server-rendered (120 by
|
||||
default, maximum 400); pagination links work without JavaScript. `offset`,
|
||||
bounded `limit` and `exclude` are retained across continuation. A Page with
|
||||
children has separate open-Page and browse-children links.
|
||||
- Tree rows use path-component ordering so `/a/x` stays within `/a`, before
|
||||
`/a-b`. Default all-expanded, per-folder/all collapse, all expand and local
|
||||
name/Path filtering are available. Matching ancestors remain visible. Arrow
|
||||
keys and Home/End move focus; left/right collapse/expand or navigate hierarchy.
|
||||
Filtering is not full-text search and never queries private metadata.
|
||||
- Children use the authenticated UI's icon buttons in the same order: `▦`
|
||||
(icon), `☷` (detail), `≡` (list), with matching compact sizing, localized
|
||||
tooltips and accessible names. Controls expose their active state. Only the view
|
||||
preference is stored in sessionStorage, not Paths, names or permissions.
|
||||
At most three fetches run per document; view changes abort old work and
|
||||
generation checks reject late successes **and errors**. Each fetch times out
|
||||
after 15 seconds and offers a local retry. Page exit aborts outstanding work.
|
||||
Lazy continuation replaces its sentinel; no thumbnail-generation job runs.
|
||||
- Macro placeholders offer a directory link without JavaScript. Directory first
|
||||
pages work without it; subsequent batches have ordinary links. Unknown or
|
||||
private names never affect pagination or continuation counts.
|
||||
- Public City Map has direct exits to directory/tree, while retaining immersive
|
||||
map navigation. No private search, authoring or planning control is added.
|
||||
- Regression coverage includes desktop/mobile Chromium, root/folder/Page round
|
||||
trips, failed-fetch retry, rapidly switched view modes, keyboard/tree prefix
|
||||
collisions, pagination/exclusions, invalid credentials, mutation denial and
|
||||
warm-cache publication withdrawal. No existing publication is auto-enabled.
|
||||
|
||||
## Cache and permission boundaries
|
||||
|
||||
`navigation_generation` is a SQLite-backed invalidation sequence. Triggers on
|
||||
Paths, Revisions, City topology/placement data, configuration/Domain changes,
|
||||
governance epochs and publication manifests/entries advance it atomically with
|
||||
the mutation. This observes changes from other connections/processes and the
|
||||
CLI, not merely HTTP handler callbacks. It is conservative and global: unrelated
|
||||
Domain changes can invalidate data, rather than risking stale permissions.
|
||||
|
||||
Each Server holds at most eight Domain/kind cache entries with a 30-second
|
||||
retention limit. Every hit reads the current database generation. Misses are
|
||||
coalesced per key with cancellable waiters; a generation change while building
|
||||
rejects the mixed snapshot rather than caching it. Public metadata and generic
|
||||
Path catalogs are bounded to 20,000 entries / four MiB; tree depth is bounded
|
||||
to 128 and expanded branch count to 20,000. City uses its existing bounded
|
||||
metadata-only snapshot. No canonical Page bodies enter this cache.
|
||||
|
||||
Authenticated City/Path data caches contain **data, not permissions**. Each
|
||||
request reloads its Principal/group/locality filter before projecting cached
|
||||
data. Group removal must revoke navigation on the next request even when the
|
||||
data generation has not changed. Anonymous approvals are a separate cache kind;
|
||||
authenticated filtered responses are never shared with anonymous requests.
|
||||
|
||||
Tree branches are constructed from readable actual Paths. Children filtering
|
||||
and exclusion happen before pagination, so hidden children do not affect totals,
|
||||
continuation or empty pages. Detail/icon metadata queries are restricted to the
|
||||
visible page (at most 400 actual children); private virtual-parent metadata is
|
||||
not fetched. Icons do not enqueue foreground preview jobs.
|
||||
|
||||
Public pages/tree reload on BFCache restoration. City clears old rendered labels
|
||||
before revalidation and uses no-store fetches, so a failed refresh does not leave
|
||||
old authorized labels visible. Existing browser-side City geometry caches remain
|
||||
geometry-only; no names, grants or Page bodies are persisted there. Already
|
||||
delivered/in-flight data cannot be recalled; this is next-request invalidation,
|
||||
not a real-time push revocation protocol.
|
||||
|
||||
## Remaining work
|
||||
|
||||
- [ ] Per-Domain fine-grained data generations to reduce conservative misses;
|
||||
cache memory accounting and large-site paging beyond bounded first-slice limits.
|
||||
- [ ] Public dependency/asset/thumbnail manifests and neighbor relations, approved
|
||||
custom City labels, anonymous search and public named City detail pages.
|
||||
- [ ] Hierarchical approval requirements and reviewer notification Inbox:
|
||||
[design and implementation TODO](publication-approval-inbox.md).
|
||||
- [ ] Dedicated isolated share-URL presentation with purpose-bound credentials;
|
||||
never reuse public navigation's broader discovery scope for a narrow share.
|
||||
@@ -0,0 +1,148 @@
|
||||
# Hierarchical publication approval and reviewer Inbox
|
||||
|
||||
Status: reviewer/approval workflow remains design / implementation TODO. The
|
||||
recipient-scoped notification Inbox storage and read API are implemented as a
|
||||
first slice; approval request producers, reviewer UI and decision lifecycle are
|
||||
not enabled yet. As of
|
||||
2026-09-19, explicit Street/Spot live-head publication is implemented separately in
|
||||
[automatic-publication.md](automatic-publication.md). Existing scopes still default
|
||||
to exact current-revision approval. No reviewer requests, Inbox or implicit opt-in
|
||||
are introduced by that implementation.
|
||||
|
||||
## Separate audience, approval and revision-following policies
|
||||
|
||||
Public/read/write audience controls answer *who may access*. Approval controls
|
||||
answer *whether a proposed publication needs review*. Neither grants the other's
|
||||
authority. In particular, an approval must never bypass an ancestor audience
|
||||
cap, a user/group restriction, or the current actor's read/publish authority.
|
||||
|
||||
Each Campus → Domain → Quartier → Street → Spot → Page/Path boundary can carry:
|
||||
|
||||
- `approval: inherit | required | not_required`;
|
||||
- reviewer selection by stable Principal/membership or group UUIDs;
|
||||
- review quorum (initial implementation: one independent reviewer), expiration
|
||||
and optional self-approval prohibition (initial default: prohibited).
|
||||
|
||||
`required` is a superior floor: effective approval is required if any ancestor
|
||||
requires it; a subordinate `not_required` cannot turn it off. With no inherited
|
||||
floor, the owner may choose `required` or `not_required` within delegated
|
||||
governance authority. Newly introduced policy defaults preserve today's explicit
|
||||
approval requirement. Campus policy is a signed, versioned inherited ceiling for
|
||||
managed instances, not a remotely writable local bypass.
|
||||
|
||||
Reviewer eligibility is also constrained by superior delegation. A subordinate
|
||||
cannot satisfy required review by appointing an arbitrary reader, itself, or a
|
||||
group it controls. Reviewers need explicit review authority for this scope and
|
||||
read authority over every proposed source. A Domain administrator's recovery
|
||||
override, if added, is a separate explicit, audited action, not a silent quorum
|
||||
bypass. No approver available means blocked/pending, never automatic approval.
|
||||
|
||||
`not_required` means an authorized publication action can proceed after the
|
||||
same impact and audience validation without waiting for another person's review.
|
||||
It does **not** turn every edit/new child public. A future `revision_policy:
|
||||
frozen | follow_head` must be explicit and separately constrained by ancestors;
|
||||
the initial implementation keeps exact approved revision tuples. Visibility
|
||||
tightening and revocation are immediate and must never wait for approval.
|
||||
|
||||
## Request lifecycle and immutable subject
|
||||
|
||||
1. Publisher previews the bounded exact Path/Object/Revision/SHA-256/language
|
||||
set, dependencies and alias impact.
|
||||
2. If review is required, create an idempotent `pending` request, an audit event
|
||||
and a notification outbox record in one reserved SQLite write transaction.
|
||||
3. Resolve eligible reviewers and deliver an Inbox item via the event queue.
|
||||
Notification delivery failure retries independently of the pending request.
|
||||
4. The reviewer opens the Inbox item, re-authenticates as needed, sees a current
|
||||
permission-filtered impact/diff, then approves, rejects, or requests changes.
|
||||
5. Approval atomically rechecks current membership/reviewer authority, audience,
|
||||
all governance and approval-policy versions, source heads/bindings, expiry,
|
||||
quorum and request generation. Only then activate the publication manifest.
|
||||
|
||||
Terminal states: `approved`, `rejected`, `withdrawn`, `expired`, `superseded`.
|
||||
An intervening edit, path move, changed audience/policy, or obsolete reviewer
|
||||
authority makes the old request unusable; it cannot approve a newer head.
|
||||
Superseded requests keep their audit record and link to an explicitly resubmitted
|
||||
replacement. Rejection does not grant access or silently change content.
|
||||
CAS transitions and idempotency prevent double approvals or replay after revoke.
|
||||
|
||||
The requester can withdraw its pending request. Authorized superior governance
|
||||
can cancel requests for the scope. Approval history cannot be erased by clearing
|
||||
an Inbox item or deleting its notification. Group changes may reroute undelivered
|
||||
notifications but do not silently alter the immutable publication subject.
|
||||
|
||||
## Notification Inbox
|
||||
|
||||
- Inbox entries are recipient-specific, with unread/read state, creation time,
|
||||
event kind, request status and a safe internal deep link. Inbox counts and
|
||||
queries are scoped to the current Principal and Domain.
|
||||
- Store request IDs and minimal event metadata, not document text, titles of
|
||||
unreadable Paths, bearer tokens, preview bodies or unfiltered reviewer lists.
|
||||
- On listing and opening, recheck live eligibility. If permissions are removed,
|
||||
show a generic unavailable/resolved item without the protected title or diff.
|
||||
A notification itself is not a read or approve capability.
|
||||
- First slice: in-product Inbox only. SMTP/push notifications are separate,
|
||||
opt-in channels fed by the same durable outbox and disclosure checks.
|
||||
- Group fan-out is bounded and deduplicated by `(event, recipient, channel)`;
|
||||
large reviewer groups are delivered in batches. Delivery retries cannot create
|
||||
multiple requests or make a stale request approvable.
|
||||
- Cross-instance routing must use the authoritative Domain. Do not copy an
|
||||
approval request into another Domain and treat it as locally authoritative.
|
||||
|
||||
## Persistence and API status
|
||||
|
||||
- `publication_approval_policies`: scope, mode, reviewer constraints, policy
|
||||
generation, actor, timestamps; separate from audience/publication intent.
|
||||
- `publication_requests`: immutable subject digest/manifest, source and policy
|
||||
versions, requester, state, generation, expiry, idempotency key.
|
||||
- `publication_decisions`: request, reviewer stable ID, decision, justification,
|
||||
timestamp; append-only audit, unique reviewer vote per request generation.
|
||||
- Domain activity outbox and recipient Inbox tables from the notification
|
||||
roadmap are implemented with indexed `(domain, recipient, unread, created_at,
|
||||
id)` keyset pagination. `GET /_/api/v1/notifications` lists the current
|
||||
principal's entries and accepts `unread=1`, `limit`, and `before`; `POST` or
|
||||
`PATCH /_/api/v1/notifications/read` marks one entry read. Both routes are
|
||||
authenticated and domain/recipient scoped. Inserts are idempotent by
|
||||
`(domain, recipient, event, kind)`.
|
||||
|
||||
Suggested handler-owned routes under the existing scope's `.../governance/`:
|
||||
`approval-policy`, `approval-requests`, and request UUID `/decisions` and
|
||||
`/withdraw`. Recipient listing/read-state endpoints belong to the common
|
||||
`/_/api/v1/notifications` namespace, not City or adapter-specific plugins.
|
||||
Final route names must be registered and verified against the endpoint inventory
|
||||
at implementation time. GET never approves; mutations use POST/PATCH with the
|
||||
existing browser-origin guard and strict JSON limits.
|
||||
|
||||
## Implementation order / TODO
|
||||
|
||||
- [x] AP-0: durable recipient Inbox storage, scoped list/read API and keyset
|
||||
pagination.
|
||||
- [x] AP-0.5: immutable request subject/generation persistence and bounded
|
||||
expiry sweep. The scheduler expires only pending requests with an explicit
|
||||
deadline; reviewer eligibility and decisions are still handler-gated TODO.
|
||||
- [x] AP-0.75: authenticated request/decision API. `POST
|
||||
/_/api/v1/publication/requests` accepts a bounded subject manifest and
|
||||
idempotency key, validates Domain review authority, and optionally creates
|
||||
recipient-scoped Inbox notifications. `POST
|
||||
/_/api/v1/publication/requests/{uuid}/decisions` is Domain-scoped, checks the
|
||||
current reviewer authority, and enforces generation/state CAS. Full policy
|
||||
inheritance and quorum evaluation remain required before production use.
|
||||
- [ ] AP-1: schema, inheritance evaluator and scoped policy settings; superior
|
||||
required floors, reviewer delegation limits and backward-compatible defaults.
|
||||
- [ ] AP-2: immutable request/decision lifecycle, idempotency/CAS, transactional
|
||||
revalidation, stale-source handling and audited emergency/revocation rules.
|
||||
- [ ] AP-3: durable Domain outbox → scheduler queue → deduplicated recipient Inbox;
|
||||
live authorization checks, bounded fan-out, retention and retry visibility.
|
||||
- [ ] AP-4: topbar notification indicator, Inbox subpage, request impact/diff
|
||||
dialog, approve/reject/withdraw UI and Japanese/English strings.
|
||||
- [ ] AP-5: explicit `not_required` publication path through the same safety
|
||||
validation; migration must not publish old drafts or pending requests.
|
||||
- [ ] AP-6: managed-Campus policy inheritance and authoritative-instance routing;
|
||||
signed generations, unavailable-controller behavior and revocation propagation.
|
||||
- [ ] Tests: competing approvals/revocations, self-approval, reviewer/group removal,
|
||||
private Inbox counts/title/diff leakage, expiry, retry deduplication, policy
|
||||
tightening while queued, source changes, wrong Domain and cache invalidation.
|
||||
|
||||
Navigation-free single-document presentation is reserved for a future share URL
|
||||
projection (for example `/s/`), not ordinary public Pages. Share tokens remain
|
||||
purpose-bound credentials with separate scope, expiry and revocation checks;
|
||||
this design does not authorize a new share endpoint or widen an existing one.
|
||||
@@ -0,0 +1,310 @@
|
||||
{
|
||||
"date": "2026-09-19",
|
||||
"origin": "https://pages.anya.jp",
|
||||
"prefix": "/lab/pageswiki-dev",
|
||||
"domain_uuid": "cd659810-3f59-406e-8a57-fb545e82fc75",
|
||||
"language": "ja",
|
||||
"publication_policy_changed": false,
|
||||
"method": "trusted local data/pageswiki-cli; canonical HTML",
|
||||
"chapters": [
|
||||
{
|
||||
"chapter": "index",
|
||||
"source": "docs/design/ja/index.md",
|
||||
"file": "index.html",
|
||||
"path": "/lab/pageswiki-dev",
|
||||
"language": "ja",
|
||||
"source_sha256": "5f3eaf4df3e2091099f9ec9deedee3a71fa868322ecfcc67eb2af7219cc673f3",
|
||||
"html_sha256": "7ed8fc9f39aacbf22f430f3e9b203d6d98ac3db4973540392d759d17373bc5f0",
|
||||
"page_uuid": "dacbc4d0-9f0f-4443-8bbe-200770c70e0e",
|
||||
"revision_uuid": "df55d6d2-021c-4d7c-a497-24536047d532",
|
||||
"lang": "ja",
|
||||
"document_hash": "7ed8fc9f39aacbf22f430f3e9b203d6d98ac3db4973540392d759d17373bc5f0"
|
||||
},
|
||||
{
|
||||
"chapter": "principles",
|
||||
"source": "docs/design/ja/principles.md",
|
||||
"file": "principles.html",
|
||||
"path": "/lab/pageswiki-dev/principles",
|
||||
"language": "ja",
|
||||
"source_sha256": "131aca71e57097496bc2bed4e8b38d3dd015c64989924654f4561d2a1e5b3775",
|
||||
"html_sha256": "7cff0a79c875b0ff67a0d6469e68d83f47d8258b4b31d5a3e9fa0a82f5822848",
|
||||
"page_uuid": "cea8c4b3-045a-43e7-bbeb-5a3ce7a633e0",
|
||||
"revision_uuid": "dc4f3841-3867-4222-8f8d-bb53d31eeb24",
|
||||
"lang": "ja",
|
||||
"document_hash": "7cff0a79c875b0ff67a0d6469e68d83f47d8258b4b31d5a3e9fa0a82f5822848"
|
||||
},
|
||||
{
|
||||
"chapter": "address-storage",
|
||||
"source": "docs/design/ja/address-storage.md",
|
||||
"file": "address-storage.html",
|
||||
"path": "/lab/pageswiki-dev/address-storage",
|
||||
"language": "ja",
|
||||
"source_sha256": "e7598a970f9ab0719349d380ba080c9e7feb30b1f07d723293f3957854499db9",
|
||||
"html_sha256": "28741abccb1780e16c74d41932074c021a700bc1f5abc7a7a8e17196453dd698",
|
||||
"page_uuid": "9da51faf-10d6-4f7e-9747-6f6100295560",
|
||||
"revision_uuid": "d879d98d-d24f-46de-b78e-060558974230",
|
||||
"lang": "ja",
|
||||
"document_hash": "28741abccb1780e16c74d41932074c021a700bc1f5abc7a7a8e17196453dd698"
|
||||
},
|
||||
{
|
||||
"chapter": "campus-federation",
|
||||
"source": "docs/design/ja/campus-federation.md",
|
||||
"file": "campus-federation.html",
|
||||
"path": "/lab/pageswiki-dev/campus-federation",
|
||||
"language": "ja",
|
||||
"source_sha256": "2de24bc908528300c8765bc905234c8ff197a0d94297f345e971920d0bac0276",
|
||||
"html_sha256": "729986b336f8d5b758615d67fe52abf90fa5701af8f9d83abad3a0c6081c6c06",
|
||||
"page_uuid": "eaf3cf25-d730-4c94-bbff-1124789fda4a",
|
||||
"revision_uuid": "78929809-445b-4130-ae84-dbda89e8764f",
|
||||
"lang": "ja",
|
||||
"document_hash": "729986b336f8d5b758615d67fe52abf90fa5701af8f9d83abad3a0c6081c6c06"
|
||||
},
|
||||
{
|
||||
"chapter": "knowledge-city",
|
||||
"source": "docs/design/ja/knowledge-city.md",
|
||||
"file": "knowledge-city.html",
|
||||
"path": "/lab/pageswiki-dev/knowledge-city",
|
||||
"language": "ja",
|
||||
"source_sha256": "33f3eb7c3792033c87518235bb2b432a73d2baa8f74eb1d818514a9ce6d6fe86",
|
||||
"html_sha256": "3c84e7abd419bcd7e41f7f7588fcc4b587810a625c7ba0d7dbc414f9b6142f6f",
|
||||
"page_uuid": "9d4f04d9-b66d-44c7-88b8-5dd7917effa7",
|
||||
"revision_uuid": "6f16c576-1b63-4368-8634-2e6a7cd1c2ed",
|
||||
"lang": "ja",
|
||||
"document_hash": "3c84e7abd419bcd7e41f7f7588fcc4b587810a625c7ba0d7dbc414f9b6142f6f"
|
||||
},
|
||||
{
|
||||
"chapter": "auth-permissions",
|
||||
"source": "docs/design/ja/auth-permissions.md",
|
||||
"file": "auth-permissions.html",
|
||||
"path": "/lab/pageswiki-dev/auth-permissions",
|
||||
"language": "ja",
|
||||
"source_sha256": "92c8b58327538becd16517cb10db3dcfea53f291d98ac48484b0cf9c46796d9b",
|
||||
"html_sha256": "6bc3336ec466fc5ca2c050852765d1aa111248f39094740caaf4aeb40de60d1b",
|
||||
"page_uuid": "e646cf67-22d6-4a1f-897e-efe66fc242ad",
|
||||
"revision_uuid": "997dbb9d-7440-4890-9410-5bc8de1735a0",
|
||||
"lang": "ja",
|
||||
"document_hash": "6bc3336ec466fc5ca2c050852765d1aa111248f39094740caaf4aeb40de60d1b"
|
||||
},
|
||||
{
|
||||
"chapter": "publication",
|
||||
"source": "docs/design/ja/publication.md",
|
||||
"file": "publication.html",
|
||||
"path": "/lab/pageswiki-dev/publication",
|
||||
"language": "ja",
|
||||
"source_sha256": "a983580a95e275fade3ab257db2242135b3123a60ee1675f17b9b5500f7a5b5b",
|
||||
"html_sha256": "2ac390cf5997f8b069bc3479784c1b7eb3712092529f24d8f603a730dec94e82",
|
||||
"page_uuid": "d49455d2-0829-4ff2-b32a-0672035f2faf",
|
||||
"revision_uuid": "f22001a2-744c-4e43-ab08-b3c26bf7a8c9",
|
||||
"lang": "ja",
|
||||
"document_hash": "2ac390cf5997f8b069bc3479784c1b7eb3712092529f24d8f603a730dec94e82"
|
||||
},
|
||||
{
|
||||
"chapter": "viewer-editor",
|
||||
"source": "docs/design/ja/viewer-editor.md",
|
||||
"file": "viewer-editor.html",
|
||||
"path": "/lab/pageswiki-dev/viewer-editor",
|
||||
"language": "ja",
|
||||
"source_sha256": "9462bad53b14773f8b4813af291f99e7cdf4bb5f3f728089ed920dc709592ab1",
|
||||
"html_sha256": "f0e1649c72e9c0247ac09563808e09ebf76c252300f42cff14723079544beac5",
|
||||
"page_uuid": "6285267f-d17b-4b6b-93a5-af89c4b19f47",
|
||||
"revision_uuid": "42028860-7497-4888-9682-ca564432154a",
|
||||
"lang": "ja",
|
||||
"document_hash": "f0e1649c72e9c0247ac09563808e09ebf76c252300f42cff14723079544beac5"
|
||||
},
|
||||
{
|
||||
"chapter": "navigation-search",
|
||||
"source": "docs/design/ja/navigation-search.md",
|
||||
"file": "navigation-search.html",
|
||||
"path": "/lab/pageswiki-dev/navigation-search",
|
||||
"language": "ja",
|
||||
"source_sha256": "654a25a9f4f014c7a9b099cb484e41ee6839dbe0f25ed8a5d83539a18d3305c6",
|
||||
"html_sha256": "35a413681b27abd0bc26c3f9c7c363b688a4ab4b83a62c7ed403d75d7eaadcfe",
|
||||
"page_uuid": "0572ef6f-f00a-4565-90d5-c95197b769f4",
|
||||
"revision_uuid": "dfdc6851-3994-474a-b2f8-ac064c00c498",
|
||||
"lang": "ja",
|
||||
"document_hash": "35a413681b27abd0bc26c3f9c7c363b688a4ab4b83a62c7ed403d75d7eaadcfe"
|
||||
},
|
||||
{
|
||||
"chapter": "scheduler-resources",
|
||||
"source": "docs/design/ja/scheduler-resources.md",
|
||||
"file": "scheduler-resources.html",
|
||||
"path": "/lab/pageswiki-dev/scheduler-resources",
|
||||
"language": "ja",
|
||||
"source_sha256": "285f68793e793235fbd2cca0686b2f65c3bf7229034e2e6ae96893d41937c839",
|
||||
"html_sha256": "8fcb8de9379684dec1bb767ad8ac4b375fd2a25c42db79253f77d787e9e7d4d2",
|
||||
"page_uuid": "0cea3054-ed5a-4cf4-90af-e0abe904ff98",
|
||||
"revision_uuid": "4bf09501-b11b-4e2b-bc40-18570aa0c9b7",
|
||||
"lang": "ja",
|
||||
"document_hash": "8fcb8de9379684dec1bb767ad8ac4b375fd2a25c42db79253f77d787e9e7d4d2"
|
||||
},
|
||||
{
|
||||
"chapter": "blog-diary",
|
||||
"source": "docs/design/ja/blog-diary.md",
|
||||
"file": "blog-diary.html",
|
||||
"path": "/lab/pageswiki-dev/blog-diary",
|
||||
"language": "ja",
|
||||
"source_sha256": "5171bd1eda59328ac1ca62c3b43f2e150368684e1673328e96b31c1383255e17",
|
||||
"html_sha256": "8e884fd4bd442aa767da00eec2089d33f2bec529255e181562cabc5e3ab14a97",
|
||||
"page_uuid": "f6a7f22f-71f2-4e90-9c57-fd0cb32753ca",
|
||||
"revision_uuid": "49c6e99c-4e98-44f2-b137-5df33c9344d0",
|
||||
"lang": "ja",
|
||||
"document_hash": "8e884fd4bd442aa767da00eec2089d33f2bec529255e181562cabc5e3ab14a97"
|
||||
},
|
||||
{
|
||||
"chapter": "extensions",
|
||||
"source": "docs/design/ja/extensions.md",
|
||||
"file": "extensions.html",
|
||||
"path": "/lab/pageswiki-dev/extensions",
|
||||
"language": "ja",
|
||||
"source_sha256": "9c52fe9b8eba40e7b3eb42b679573e2582f001584b45d0d74a702ca00594f9c5",
|
||||
"html_sha256": "ab59105ecf94bfac7b754900de42619678e6f954103b0ffc7779afae67850012",
|
||||
"page_uuid": "e091c8d7-a14d-4e90-8fa1-1c22f5d352a6",
|
||||
"revision_uuid": "07f6a0c8-3321-4fef-9f62-33ca972cfe2a",
|
||||
"lang": "ja",
|
||||
"document_hash": "ab59105ecf94bfac7b754900de42619678e6f954103b0ffc7779afae67850012"
|
||||
},
|
||||
{
|
||||
"chapter": "organizer",
|
||||
"source": "docs/design/ja/organizer.md",
|
||||
"file": "organizer.html",
|
||||
"path": "/lab/pageswiki-dev/organizer",
|
||||
"language": "ja",
|
||||
"source_sha256": "00bb7751c085971a2baa157071da16c14b44030d93ee488d0af0521773e1a533",
|
||||
"html_sha256": "fcd4f31a7ee4da495492e6813c8d71c27a9f5efd5281f71776abd5d59c8a99aa",
|
||||
"page_uuid": "087c1163-cba7-4fef-8e97-c2df6ddc27a2",
|
||||
"revision_uuid": "efb6f683-31ca-4d59-a05e-d644f58ab49d",
|
||||
"lang": "ja",
|
||||
"document_hash": "fcd4f31a7ee4da495492e6813c8d71c27a9f5efd5281f71776abd5d59c8a99aa"
|
||||
},
|
||||
{
|
||||
"chapter": "tasks-tickets",
|
||||
"source": "docs/design/ja/tasks-tickets.md",
|
||||
"file": "tasks-tickets.html",
|
||||
"path": "/lab/pageswiki-dev/tasks-tickets",
|
||||
"language": "ja",
|
||||
"source_sha256": "00e9d81d1191124e43cc1cc9eb6664d5e4814901444260012d23d3316cea255e",
|
||||
"html_sha256": "2049a24fd7fac71e41e5c511c271b5f96346aaa16ea67679cf1502a2687a176a",
|
||||
"page_uuid": "576ca4d0-24d9-42e1-83eb-484d9f803f4f",
|
||||
"revision_uuid": "6cc03ec4-2185-4449-ae3a-ff604c9077b5",
|
||||
"lang": "ja",
|
||||
"document_hash": "2049a24fd7fac71e41e5c511c271b5f96346aaa16ea67679cf1502a2687a176a"
|
||||
},
|
||||
{
|
||||
"chapter": "calendar-contacts",
|
||||
"source": "docs/design/ja/calendar-contacts.md",
|
||||
"file": "calendar-contacts.html",
|
||||
"path": "/lab/pageswiki-dev/calendar-contacts",
|
||||
"language": "ja",
|
||||
"source_sha256": "6c8a5f246c613ea4b466326c8ab9194dd77614c532bea7ac778b60a5dbceea1f",
|
||||
"html_sha256": "f5581bf4436b3ae6df44fe1072f45c64721dd70fa2bfba606c8c785615db71f2",
|
||||
"page_uuid": "480da094-1850-47b0-8d39-f24a93011827",
|
||||
"revision_uuid": "49acfc6b-ba4b-4788-b7b4-6d6ea02db426",
|
||||
"lang": "ja",
|
||||
"document_hash": "f5581bf4436b3ae6df44fe1072f45c64721dd70fa2bfba606c8c785615db71f2"
|
||||
},
|
||||
{
|
||||
"chapter": "feeds",
|
||||
"source": "docs/design/ja/feeds.md",
|
||||
"file": "feeds.html",
|
||||
"path": "/lab/pageswiki-dev/feeds",
|
||||
"language": "ja",
|
||||
"source_sha256": "3c7e74a68c9e331fd35dd4e1373c5868096f7f55a0d3a7438dd47326fa3a399a",
|
||||
"html_sha256": "890ca59dbed768163bd91d989a70c836f43c898e387591aeb6d5a1691c6f7e35",
|
||||
"page_uuid": "7fc9f22e-a06a-4512-a720-1ededf162e4c",
|
||||
"revision_uuid": "61179145-b0a7-4a55-8e34-ca621b9a94fa",
|
||||
"lang": "ja",
|
||||
"document_hash": "890ca59dbed768163bd91d989a70c836f43c898e387591aeb6d5a1691c6f7e35"
|
||||
},
|
||||
{
|
||||
"chapter": "mail",
|
||||
"source": "docs/design/ja/mail.md",
|
||||
"file": "mail.html",
|
||||
"path": "/lab/pageswiki-dev/mail",
|
||||
"language": "ja",
|
||||
"source_sha256": "f0a912d5c073b68eed8a4dab09518028014ac0a3bd5afc8fe59cd655f9dc7c0b",
|
||||
"html_sha256": "18c860a0ca474a4318e225f8986811999abe6da7ddef3833cee403426c029ad2",
|
||||
"page_uuid": "4588ed2e-b87f-429b-b9f5-57bae3e67fdb",
|
||||
"revision_uuid": "7797181a-a6c8-4669-86fc-e8e908d025d1",
|
||||
"lang": "ja",
|
||||
"document_hash": "18c860a0ca474a4318e225f8986811999abe6da7ddef3833cee403426c029ad2"
|
||||
},
|
||||
{
|
||||
"chapter": "html-editor",
|
||||
"source": "docs/design/ja/html-editor.md",
|
||||
"file": "html-editor.html",
|
||||
"path": "/lab/pageswiki-dev/html-editor",
|
||||
"language": "ja",
|
||||
"source_sha256": "f5034521d8c50300afa42b26c29056c85656383ec1405eb8d7a272b331b0a723",
|
||||
"html_sha256": "7920a9350fd81bd746ac73dfa396e3a2e1ae3ed71c0d89c5e25f7d8299581e90",
|
||||
"page_uuid": "0ebab668-6176-450b-ab6b-ae2cec9e6d73",
|
||||
"revision_uuid": "2ed1c468-7664-4434-a610-6348afa08de5",
|
||||
"lang": "ja",
|
||||
"document_hash": "7920a9350fd81bd746ac73dfa396e3a2e1ae3ed71c0d89c5e25f7d8299581e90"
|
||||
},
|
||||
{
|
||||
"chapter": "operations",
|
||||
"source": "docs/design/ja/operations.md",
|
||||
"file": "operations.html",
|
||||
"path": "/lab/pageswiki-dev/operations",
|
||||
"language": "ja",
|
||||
"source_sha256": "53433c4a29875f53799a3900b2d1ba47acc4ff49a0af40453ef40f520d7022b5",
|
||||
"html_sha256": "0b01154d90e0946448bad3ccba54a17181ed67063934ba3d793b9061dd4fe382",
|
||||
"page_uuid": "85f484dc-f63a-41b1-8709-45242f5dec18",
|
||||
"revision_uuid": "1fb7aaa4-cbf6-4254-8a8f-d9256cbda2b5",
|
||||
"lang": "ja",
|
||||
"document_hash": "0b01154d90e0946448bad3ccba54a17181ed67063934ba3d793b9061dd4fe382"
|
||||
},
|
||||
{
|
||||
"chapter": "i18n",
|
||||
"source": "docs/design/ja/i18n.md",
|
||||
"file": "i18n.html",
|
||||
"path": "/lab/pageswiki-dev/i18n",
|
||||
"language": "ja",
|
||||
"source_sha256": "1ebbb2e2db6401d3889e3210fcd451c28e4fa7029e2c9bf67cc418660ebfd165",
|
||||
"html_sha256": "2ef7a464e71c1f3f89021daa559abd1fb95d5a9525c9578fd55bce4716954232",
|
||||
"page_uuid": "4d5182bd-cc5b-4fbc-8b2a-24c6b2f4906b",
|
||||
"revision_uuid": "d80b77a0-991b-4469-aa8d-96c19bda319b",
|
||||
"lang": "ja",
|
||||
"document_hash": "2ef7a464e71c1f3f89021daa559abd1fb95d5a9525c9578fd55bce4716954232"
|
||||
},
|
||||
{
|
||||
"chapter": "roadmap",
|
||||
"source": "docs/design/ja/roadmap.md",
|
||||
"file": "roadmap.html",
|
||||
"path": "/lab/pageswiki-dev/roadmap",
|
||||
"language": "ja",
|
||||
"source_sha256": "b9884594ad6889c3c6e9b078fe7ba3ac38d475bfb050b4d136f057678491ba7a",
|
||||
"html_sha256": "1e147c41aaf8f23dbe383601c5a19700a14632217b161809d50572fe2711123e",
|
||||
"page_uuid": "41ba50fa-7e50-4d9b-bb6e-783e9e696cf4",
|
||||
"revision_uuid": "2bb94ddc-7dfb-4a1b-94e4-8ced71142725",
|
||||
"lang": "ja",
|
||||
"document_hash": "1e147c41aaf8f23dbe383601c5a19700a14632217b161809d50572fe2711123e"
|
||||
},
|
||||
{
|
||||
"chapter": "decisions",
|
||||
"source": "docs/design/ja/decisions.md",
|
||||
"file": "decisions.html",
|
||||
"path": "/lab/pageswiki-dev/decisions",
|
||||
"language": "ja",
|
||||
"source_sha256": "2357efad3e3cdec1020e6b624c6c0a7ccf32fb9981784fd36be753bab39d3c1c",
|
||||
"html_sha256": "cb733228d0f5ac11a3b4f9972ae11ee27568d536c93436dc42268599c1bad9a4",
|
||||
"page_uuid": "6d8780e0-41ae-480b-8b51-0407420af7bb",
|
||||
"revision_uuid": "3c1e073e-908c-426d-afec-6fc481d424d8",
|
||||
"lang": "ja",
|
||||
"document_hash": "cb733228d0f5ac11a3b4f9972ae11ee27568d536c93436dc42268599c1bad9a4"
|
||||
},
|
||||
{
|
||||
"chapter": "sources",
|
||||
"source": "docs/design/ja/sources.md",
|
||||
"file": "sources.html",
|
||||
"path": "/lab/pageswiki-dev/sources",
|
||||
"language": "ja",
|
||||
"source_sha256": "3e11b06e33c031fb039eaed0d2c65cc897984c7a5ce3e8aedcf7c1f73b4f04e9",
|
||||
"html_sha256": "12cc7c61ba7ffabc8c4a712f74e4839931cb37ce28bc2cd9eed28d5ea17b6ea9",
|
||||
"page_uuid": "b8a630c6-355e-4f85-bd01-010b96b54dcf",
|
||||
"revision_uuid": "63d5c1ff-7a24-4508-b0b4-8a3a702cdf7c",
|
||||
"lang": "ja",
|
||||
"document_hash": "12cc7c61ba7ffabc8c4a712f74e4839931cb37ce28bc2cd9eed28d5ea17b6ea9"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,104 @@
|
||||
# Revision and Language Projection Detailed Design
|
||||
|
||||
## Status
|
||||
|
||||
Implemented. SQLite `body` remains a transitional compatibility cache while
|
||||
the canonical payload is read from `documents/sha256/`.
|
||||
|
||||
## Invariants
|
||||
|
||||
```text
|
||||
Semantic Path != Page UUID
|
||||
Page UUID != Revision UUID
|
||||
Revision UUID != Document SHA-256
|
||||
Language != Semantic Path
|
||||
```
|
||||
|
||||
- A Page is language-neutral.
|
||||
- A Revision is immutable and belongs to exactly one Page.
|
||||
- A Revision references exactly one immutable Document payload.
|
||||
- The same Document hash may be referenced by many Pages, languages, or
|
||||
Revisions.
|
||||
- Saving identical content may create a new Revision event without duplicating
|
||||
the Document payload.
|
||||
|
||||
## Metadata schema
|
||||
|
||||
### `revisions`
|
||||
|
||||
| Column | Constraint | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `uuid` | primary key | Revision UUID |
|
||||
| `object_uuid` | required | Parent Page UUID |
|
||||
| `document_hash` | required | Lowercase SHA-256 payload hash |
|
||||
| `lang` | required, default `und` | Canonical BCP 47 tag |
|
||||
| `body` | transitional | Compatibility copy until filesystem migration |
|
||||
| `message` | optional | Commit message |
|
||||
| `created_at_ms` | required | Ordering timestamp |
|
||||
| `created_at` | transitional | Legacy seconds timestamp |
|
||||
|
||||
`object_uuid` is retained during the broader Object-to-Page vocabulary
|
||||
migration. New code treats it as Page identity.
|
||||
|
||||
## Save transaction
|
||||
|
||||
1. Validate the Page UUID.
|
||||
2. Canonicalize the language tag; empty becomes `und`.
|
||||
3. Hash the canonical payload with SHA-256.
|
||||
4. Persist the immutable Document if absent.
|
||||
5. Generate a new Revision UUID.
|
||||
6. Insert Revision metadata referencing the Document hash.
|
||||
7. Commit metadata only after Document persistence succeeds.
|
||||
|
||||
During the compatibility phase, step 4 also stores `body` in SQLite. The
|
||||
content-addressed file under `documents/sha256/` is canonical; removing the compatibility column is a
|
||||
later schema cleanup and does not change Revision UUIDs or hashes.
|
||||
|
||||
## Language selection
|
||||
|
||||
Candidate order:
|
||||
|
||||
1. Explicit non-canonical language override
|
||||
2. `Accept-Language` tags in quality order
|
||||
3. Base tag for each regional tag
|
||||
4. Owning Campus default
|
||||
5. System default
|
||||
6. `und`
|
||||
|
||||
Candidates are canonical BCP 47 tags, deduplicated in order. Selection returns
|
||||
the newest Revision for the first candidate that exists.
|
||||
|
||||
## Compatibility migration
|
||||
|
||||
For every legacy Revision:
|
||||
|
||||
- preserve its existing `uuid`;
|
||||
- set `document_hash = sha256(body)`;
|
||||
- set `lang = und`;
|
||||
- set `created_at_ms = created_at * 1000`.
|
||||
|
||||
New Revision UUIDs are random UUIDs. Legacy hash-shaped Revision identifiers
|
||||
remain resolvable indefinitely.
|
||||
|
||||
## API
|
||||
|
||||
Revision save accepts:
|
||||
|
||||
```json
|
||||
{
|
||||
"object_uuid": "page UUID",
|
||||
"body": "canonical payload",
|
||||
"message": "manual-save",
|
||||
"lang": "ja-JP"
|
||||
}
|
||||
```
|
||||
|
||||
Responses include both the Revision UUID and Document hash.
|
||||
|
||||
## Failure behavior
|
||||
|
||||
- Invalid language tags return a client error.
|
||||
- Unknown Page UUIDs are rejected.
|
||||
- Missing requested languages fall through; they are not errors.
|
||||
- If no candidate exists, an empty `und` working projection may be returned by
|
||||
the Editor, while Viewer returns the existing not-found behavior.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Bounded Revision history
|
||||
|
||||
Implemented 2026-09-14 for `/_/api/v1/revisions/list?uuid=<Object UUID>` and
|
||||
`/r/history/<Object UUID>`. Both authorize the Object before loading metadata.
|
||||
Path-scoped users can use the API through the handler resolver; a Domain-wide
|
||||
read grant is not additionally required.
|
||||
|
||||
- Default 100, maximum 200 records per response; `limit` outside 1–200 is 400.
|
||||
- `before=<Revision UUID>` is an exclusive cursor in the same Object. A missing
|
||||
or foreign-Object cursor is 400 after Object authorization.
|
||||
- Order is `created_at_ms DESC, rowid DESC`, preserving insertion order when
|
||||
timestamps tie. The ascending `(object_uuid, created_at_ms)` index supports
|
||||
backward keyset scans. Newer writes do not shift subsequent pages.
|
||||
- Only metadata is selected, never Revision bodies. Message and filename
|
||||
previews are capped at 4,096 characters each. Queries have a two-second
|
||||
context and one read snapshot; at most 201 records are materialized.
|
||||
- The API retains its JSON-array shape. `Link: <...>; rel="next"` and
|
||||
`X-Next-Cursor` advertise continuation. An empty result is `[]`; HEAD returns
|
||||
headers without a JSON body. Responses are `private, no-store`.
|
||||
- History has localized older/newest navigation. Legacy editor history dialogs
|
||||
link to this browser when another page exists. Messages use DOM text nodes;
|
||||
they are never interpolated into markup or inline event handlers.
|
||||
|
||||
Restore accepts POST only, and checks source metadata authority before loading
|
||||
the body. The legacy dialog now uses POST. Reusing immutable Document hashes for
|
||||
restore without full payload hydration is a separate follow-up; no claim of
|
||||
streaming or constant-memory large-binary restore is made here.
|
||||
|
||||
Trusted Store/CLI `ListRevisions` remains available for explicit full exports.
|
||||
Clients that previously assumed the HTTP array contained all history must
|
||||
follow the next link. A cursor removed by retention expires rather than silently
|
||||
restarting at the newest revision. Tests cover equal timestamps, concurrent
|
||||
newer insertion, cancellation, foreign cursors, limits, HEAD, ACL revocation,
|
||||
localized navigation and escaped messages.
|
||||
@@ -0,0 +1,247 @@
|
||||
# Bounded, permission-filtered search results
|
||||
|
||||
Implemented: 2026-09-14.
|
||||
|
||||
## City-first results and search options
|
||||
|
||||
Search now places matching Quartiers, Streets and Spots above Page/file hits.
|
||||
The compact City section remains visible in list/detail/icon modes and shows
|
||||
the locality kind, highlighted title, literal boundary Path, readable ancestor
|
||||
context, a description excerpt, matching-source badges and update time. It is
|
||||
not a file-selection target: Page copy/rename/delete actions cannot accidentally
|
||||
operate on a City result. The title opens City details; the Path opens its portal
|
||||
boundary. Quartier/Spot links use their unique names. Street links use
|
||||
`/v/city/s/{quartier-name}/{street-name}` so repeated names remain unambiguous.
|
||||
Explicit `uuid:` selectors remain supported. Map locality search submits that
|
||||
explicit selector and requires read access to the locality and its ancestors.
|
||||
|
||||
`SearchCityInDomain` reads metadata from three bounded SQL streams; it never
|
||||
loads the full City model, expands Page placements or counts descendants.
|
||||
Only current-Domain, non-archived localities with valid absolute boundaries and
|
||||
active same-Domain ancestors are eligible. Scope contains the locality's own
|
||||
Path; ancestors outside a narrower scope are not added automatically. Every
|
||||
boundary in the parent chain must pass the same request-scoped read policy
|
||||
before names or descriptions are exposed. Limits are 1,000 candidates per kind
|
||||
and 30 readable City results. Ordering is Quartier, Street, Spot; within each
|
||||
kind name/title matches precede Path matches, followed by stable Path/UUID ties.
|
||||
Matching is literal substring search over name/title/description/Path, with
|
||||
SQLite ASCII case-folding and literal Unicode/punctuation handling.
|
||||
|
||||
The HTTP handler shares a two-second deadline between the City and Page queries;
|
||||
their internal snapshots remain separate read transactions. Existing bounded
|
||||
Page candidate and optional-excerpt behavior is retained. City/Page results may
|
||||
therefore observe separate commits during a concurrent edit, not a single
|
||||
cross-model snapshot.
|
||||
|
||||
Options are a collapsed, keyboard-accessible disclosure. Active/error filters
|
||||
open it. Inputs outside the topbar associate with the same GET form, so editing
|
||||
the keyword, pressing Enter or applying filters preserves one copy of each
|
||||
parameter, scope and locality. Clear filters retains the keyword/scope/locality;
|
||||
timeout retry retains the selected filters too. No new JavaScript/storage state
|
||||
or cookie is required for these shareable URL options.
|
||||
|
||||
| Parameter | Meaning |
|
||||
| --- | --- |
|
||||
| `file_type` | Empty for all, or `html`, `text`, `image`, `audio`, `video`, `pdf`, `archive`, `csv`, `json`, `code`, `office`, `other` |
|
||||
| `ext` | One extension, e.g. `py`, `.PDF`, `tar.gz`; normalized to lower case without the leading dot |
|
||||
| `date_field` | `updated` (default) or `created` |
|
||||
| `from` | Inclusive starting calendar date, `YYYY-MM-DD` |
|
||||
| `to` | Inclusive ending calendar date, `YYYY-MM-DD` |
|
||||
|
||||
Specific MIME metadata takes precedence over suffix guesses; generic MIME may
|
||||
use a known filename suffix, falling back to Path when filename is absent.
|
||||
Type and extension combine with AND. The classification never loads/sniffs the
|
||||
Document. Extension filtering uses the stored original filename when present:
|
||||
an HTML canonical Page with retained `notes.md` metadata can match `ext=md`,
|
||||
while its type is still HTML. Selecting a type is not selecting an editor mode.
|
||||
|
||||
Page update dates use the latest Revision timestamp, and creation dates use
|
||||
Object creation, not the time a Path alias was added. City dates use the locality's
|
||||
own timestamps, not descendant Page activity. Dates use the Domain timezone,
|
||||
shown alongside the inputs. The ending bound is the next local midnight using
|
||||
calendar arithmetic, including 23/25-hour daylight-saving dates. Invalid types,
|
||||
extensions, repeated filter parameters or invalid/reversed dates return a
|
||||
localized `400` without interpolating user input into SQL.
|
||||
|
||||
File type/extension filters exclude City elements (a Spot containing PDFs is
|
||||
not itself a PDF). Date filters apply to both classes. Keywords are optional
|
||||
when a type, extension or date boundary is supplied; selecting only a date-field
|
||||
kind does not enumerate everything. Every filter runs before each Page
|
||||
candidate LIMIT, rather than discarding already-limited results afterward.
|
||||
|
||||
Current limits remain deliberate: one file type and one extension at a time,
|
||||
metadata-based classification, no historical content search, no cross-Domain
|
||||
City search, and no derived descendant file-type/date facet on a City element.
|
||||
|
||||
## Presentation
|
||||
|
||||
`/v/search` retains the shared list / detail / icon controls, preference storage,
|
||||
Ctrl/Command selection, and file context menu. Each mode now presents the same
|
||||
information:
|
||||
|
||||
- Page display name: the current Revision filename's final component, falling
|
||||
back to the current Path's final component. There is no separate Page-title
|
||||
field in the current Object schema.
|
||||
- The complete matching semantic Path, with keywords emphasized independently
|
||||
of the display name. Link URLs encode literal spaces, `?`, `#`, and `%` as
|
||||
Path characters rather than treating them as query/fragment syntax.
|
||||
- Explicit Path / filename / body match-source labels. Multiple sources may
|
||||
apply to one result. Each readable alias remains a distinct navigable result.
|
||||
- A short contextual body excerpt for full-text matches. Name-only matches
|
||||
receive a bounded opening summary when the Revision contains textual data.
|
||||
- Large or expensive body matches retain their name, Path and match-source
|
||||
badge, with a localized explanation when the excerpt is omitted.
|
||||
- In detail mode, content type and update time. Unknown file sizes are no
|
||||
longer misleadingly displayed as zero.
|
||||
|
||||
List mode is a compact stacked overview; icon mode adds the existing cached /
|
||||
asynchronous preview; detail mode keeps the dense table. The search submit
|
||||
button is an accessible icon aligned with its input. Styles use existing theme
|
||||
variables and adapt to narrower viewports.
|
||||
|
||||
Keywords become typed text segments, rendered using `html/template`-owned
|
||||
`<mark>` elements. No search query, filename, Path, FTS marker, or excerpt is
|
||||
cast to trusted HTML. HTML excerpts are tokenized to plain text, excluding
|
||||
script/style content, before Unicode-safe windowing and highlighting.
|
||||
|
||||
## Query and authorization boundary
|
||||
|
||||
The handler builds one request-scoped Path-read filter and validates the scope
|
||||
with it. `SearchPathsInDomainWithOptions` (or its no-options compatibility wrapper
|
||||
`SearchPathsInDomainFiltered`) uses that immutable filter during
|
||||
candidate collection, before any excerpt lookup or preview construction.
|
||||
Global counts, denied Paths, denied filenames, and denied excerpts are never
|
||||
included in the rendered data. An all-denied candidate set uses the same empty
|
||||
state as an ordinary no-match query.
|
||||
|
||||
All search statements use one read-only SQLite transaction, preserving a
|
||||
consistent current Path / latest Revision snapshot. The three candidate streams
|
||||
are:
|
||||
|
||||
1. Literal substring matching against current Paths and current filenames.
|
||||
2. FTS5 body-prefix matching, joined to the latest Revision projection.
|
||||
3. FTS5 filename-prefix matching, joined to the same projection.
|
||||
|
||||
Each stream is limited to 1,000 candidate Paths in SQL. Full-text streams do not
|
||||
materialize an unbounded global `IN` list or globally sort all matching
|
||||
historical Revisions. An index on `latest_revision_index(revision_uuid)` supports
|
||||
the latest-only join. Explicit `CROSS JOIN` keeps FTS outermost: scan MATCH
|
||||
once, then seek current Revision metadata and Path bindings through B-tree
|
||||
indexes. An ordinary JOIN can instead put Paths first and repeat the entire
|
||||
FTS scan for every Path because the FTS UUID payload column is unindexed.
|
||||
Domain and segment-aware scope filtering precede each
|
||||
candidate limit. Prefix bounds use binary Path ranges, not wildcard `LIKE`;
|
||||
literal `%` and `_` in folder names and queries cannot widen the scope.
|
||||
|
||||
Authorized candidates are deduplicated by Path, then ordered with direct
|
||||
name/Path matches first and stable length/Path ties. The normal UI displays at
|
||||
most 100; trusted store callers may request up to 200. Only authorized displayed
|
||||
rows receive a byte-size preflight, using their FTS integer rowids from the same
|
||||
snapshot. `octet_length(body)` counts bytes, not Unicode characters; see
|
||||
[SQLite's function contract](https://www.sqlite.org/lang_corefunc.html#octet_length).
|
||||
Eligible body excerpts are fetched together with one FTS snippet query restricted
|
||||
by those rowids, not the unindexed UUID payload column. Name-only textual
|
||||
summaries use one additional bounded Revision-prefix query. There are no
|
||||
per-result authorization queries or Document-file stat calls. Existing preview
|
||||
cache checks run only for displayed authorized results, without scheduling
|
||||
foreground generation.
|
||||
|
||||
## Explicit bounds and failure behavior
|
||||
|
||||
- Query input: at most 512 bytes and 16 terms.
|
||||
- Search transaction: two-second context deadline; caller cancellation applies.
|
||||
- Candidate rows: at most 3,000 total; displayed rows: normally 100.
|
||||
- Snippet transport: at most 4,096 characters per body excerpt, 1,024 per
|
||||
name-only summary; display window: approximately 260 Unicode characters.
|
||||
- Snippet input: at most 64 KiB per document and 1 MiB across unique displayed
|
||||
Revisions. Multiple authorized aliases share an excerpt and consume its
|
||||
input budget only once. An oversized body still participates in MATCH.
|
||||
- Optional snippet time: 400 ms within the overall search context. If spent,
|
||||
omit the snippet batch but retain the already authorized results. Parent
|
||||
cancellation still aborts the search; unrelated SQL errors are not swallowed.
|
||||
These are cooperative SQLite deadlines, not hard process-kill guarantees.
|
||||
- No total-count query. The 100-result notice depends only on visible rows,
|
||||
not on hidden candidate counts. A general scope-narrowing hint is always
|
||||
shown for a submitted query.
|
||||
|
||||
A search-budget timeout returns a themed, localized `503` page with
|
||||
`Retry-After: 5` and a retry link preserving query/scope/locality. Unexpected
|
||||
database errors return a generic `500`, without SQL/schema/connection details.
|
||||
Canceled HTTP requests stop without further rendering. Snippet-only timeout
|
||||
is a successful results page with explicit omission, not a search failure.
|
||||
|
||||
## Timeout regression and correction (2026-09-14)
|
||||
|
||||
The initial small-fixture tests did not catch a production join-order problem.
|
||||
Read-only investigation of the current 943 Paths / 1,632 indexed Revisions
|
||||
reproduced it: a native SQLite body candidate query took 8.21 seconds with the
|
||||
old Path-first plan and 0.10 seconds with the FTS-first plan, returning the same
|
||||
36 candidates. Another common prefix exceeded a ten-second diagnostic bound.
|
||||
|
||||
There was a second bottleneck: FTS bodies reach tens of megabytes.
|
||||
`snippet(...,36)` and a `substr` on its output do **not** limit the tokenizer's
|
||||
input work. Even smaller documents can have costly prefix-position scans;
|
||||
the separate input and optional time budgets address both cases.
|
||||
|
||||
The read-only Go Store diagnostic reproduced all four initial query failures
|
||||
before the correction. With the final code the representative cases returned
|
||||
57 / 100 / 100 / 7 rows in approximately 86 / 128 / 506 / 72 ms, respectively.
|
||||
The short, broad prefix used the optional-excerpt fallback. Timings are local
|
||||
measurements, not service-level guarantees; no production content or credentials
|
||||
were printed or changed. No schema migration or index rebuild is required by
|
||||
this correction.
|
||||
|
||||
## Remaining work
|
||||
|
||||
These bounds intentionally trade exhaustive recall for predictable work. A
|
||||
broad search or many inaccessible leading candidates may omit readable hits
|
||||
beyond a stream's candidate budget; narrowing the scope is the current remedy.
|
||||
SQLite may still inspect many FTS postings / historical rows before locating
|
||||
current in-scope candidates, but the deadline bounds this work. A current-only,
|
||||
Domain-partitioned FTS projection with a persisted index watermark and genuine
|
||||
keyset pagination remains a future scaling step, not an implemented claim.
|
||||
|
||||
The current `unicode61` tokenizer and raw-HTML search index are unchanged:
|
||||
Japanese infix search and exclusion of markup-only matches need a separate
|
||||
plain-text / language-aware indexing migration. Excerpts already remove HTML
|
||||
markup safely, but an indexed markup token can still cause a body-source hit
|
||||
with no visible text excerpt. Independent Page titles and relevance tuning are
|
||||
also separate features.
|
||||
|
||||
## Regression coverage
|
||||
|
||||
Store tests cover latest-only bodies and current renamed Paths, literal scope
|
||||
and query punctuation, body/filename source distinction, Domain isolation,
|
||||
ACL-before-limit behavior, bounded candidates, query bounds, and cancellation.
|
||||
Query-plan tests require FTS-first candidate collection and rowid-constrained
|
||||
snippets. A 600-Page / 1,200-Revision fixture checks current-only results, both
|
||||
match sources and excerpt association under the real search budget. Input-budget
|
||||
tests cover Unicode byte lengths, total bytes, aliases and retained hits;
|
||||
deadline tests distinguish optional enrichment from parent cancellation/errors.
|
||||
Server tests cover hidden-only results, denied scopes, encoded Path links,
|
||||
Unicode keyword segments, contextual clipping, and malicious source HTML.
|
||||
An opt-in Chromium test exercises all three display modes, safe highlights,
|
||||
Ctrl selection, and absence of horizontal page overflow.
|
||||
HTTP tests also cover themed GET/HEAD failures, sanitized errors, retained retry
|
||||
parameters and a large-body match beyond the bounded prefix in Japanese/English.
|
||||
|
||||
City/filter regressions cover hidden/foreign/archived ancestors, duplicate Street
|
||||
names and encoded links, metadata-only single-connection reads, literal scopes,
|
||||
MIME priority/fallback, combined filters before all three candidate caps,
|
||||
Object-vs-alias creation times, inclusive millisecond bounds and Japanese/DST
|
||||
calendar conversion. Chromium checks desktop (1440px) and mobile (390px), with
|
||||
real City results above Pages, no file selection on City rows, and one set of
|
||||
form parameters while changing views/options.
|
||||
|
||||
Read-only verification against the existing main DB measured the additional
|
||||
filter-only cases at approximately 1–6 ms and City metadata lookup at 2 ms;
|
||||
representative keyword Page searches remained approximately 79–515 ms. These
|
||||
are local observations, not latency guarantees or authenticated HTTP timings.
|
||||
This feature adds no schema migration or index rebuild.
|
||||
|
||||
```sh
|
||||
go test -race ./internal/server ./internal/store -run '^TestSearch' -count=1
|
||||
PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run '^TestSearchResultsChromium$' -count=1
|
||||
# Optional: opens an existing DB with mode=ro and query_only, with no migrations.
|
||||
PAGESWIKI_SEARCH_DIAGNOSTIC_DB=/absolute/path/pages.db go test ./internal/store -run '^TestSearchReadOnlyDatabase$' -count=1 -v
|
||||
```
|
||||
@@ -0,0 +1,84 @@
|
||||
# SMTP magic-link delivery bounds
|
||||
|
||||
Implemented: 2026-09-14.
|
||||
|
||||
## Request and verification
|
||||
|
||||
`/_/auth/magic-link` accepts POST only and limits the form body to 64 KiB.
|
||||
Unknown accounts, malformed mailbox values, disabled providers, invalid mail
|
||||
configuration, and a full delivery queue all receive the same ordinary
|
||||
submitted-request page. Invalid/oversized form encoding is a generic 400.
|
||||
|
||||
Sender and recipient each pass single-mailbox parsing and explicit CR/LF/NUL
|
||||
rejection. SMTP envelope addresses use the parsed mailbox, while message
|
||||
headers use its safely serialized display form. Neither raw user input nor
|
||||
configured display names are concatenated directly into mail headers. The
|
||||
SMTP endpoint must be a host plus numeric TCP port; IPv6 brackets are supported.
|
||||
|
||||
The two existing delivery slots are acquired without waiting, before a new
|
||||
challenge is written. Accepted challenges remain Domain-scoped, hash-only,
|
||||
one-use tokens with fifteen-minute expiry. Their payload now records the
|
||||
current recipient email in addition to the safe return Path.
|
||||
|
||||
`/_/auth/magic-link/verify` accepts GET only, consumes the challenge once, and
|
||||
then checks that the provider remains enabled, the Principal is active or
|
||||
readonly, Domain membership is active, and the account email still matches
|
||||
the delivered challenge. Email changes, suspended/quarantined accounts,
|
||||
suspended/removed membership, disabled providers, and replay are rejected with
|
||||
one generic invalid/expired response. The common browser-session issuance path
|
||||
also checks Principal and membership state atomically when inserting a session.
|
||||
Pending links from the earlier email-unbound challenge format must be requested
|
||||
again after this change.
|
||||
|
||||
Both endpoints return `Cache-Control: no-store`. No raw SMTP response,
|
||||
recipient address, password, message body, or login URL is logged.
|
||||
|
||||
## Delivery
|
||||
|
||||
Delivery uses the existing Go SMTP client over an explicitly managed
|
||||
connection instead of the unbounded convenience `smtp.SendMail` call:
|
||||
|
||||
- Three-second context-aware dial timeout.
|
||||
- Ten-second total delivery deadline, covering greeting, EHLO, STARTTLS,
|
||||
authentication, envelope commands, DATA acknowledgement, and QUIT.
|
||||
- Context cancellation closes the underlying connection immediately.
|
||||
- At most 256 KiB of inbound connection data, including TLS negotiation,
|
||||
prevents a malicious multiline SMTP reply from growing without bound.
|
||||
- Every completion/error path closes the connection and releases the slot.
|
||||
- STARTTLS is used whenever advertised, with certificate/hostname verification
|
||||
and TLS 1.2 minimum. Failed advertised TLS never falls back to plaintext.
|
||||
- Password authentication requires TLS even for a localhost server. PLAIN
|
||||
authentication is not sent over an unencrypted channel.
|
||||
|
||||
Mailbox serialization and STARTTLS behavior use the Go standard library's
|
||||
[mail parser](https://pkg.go.dev/net/mail#ParseAddress) and
|
||||
[SMTP client](https://pkg.go.dev/net/smtp#Client.StartTLS); there is no new
|
||||
dependency or external mail-service integration.
|
||||
|
||||
## Remaining policy decisions
|
||||
|
||||
Unauthenticated relays without STARTTLS retain the earlier plaintext behavior.
|
||||
Deployments must provide a trusted local relay or a TLS-capable SMTP endpoint;
|
||||
transport-wide mandatory TLS / explicit relay exceptions are a future setting.
|
||||
Implicit SMTPS on port 465, custom CA configuration, OAuth SMTP authentication,
|
||||
durable retries, delivery status/audit UI, and per-account/source abuse quotas
|
||||
are not implemented by this hardening slice. Admission slots bound concurrent
|
||||
work, not request rates. A failed admitted delivery leaves an inaccessible
|
||||
hashed challenge until normal expiry/cleanup.
|
||||
|
||||
Magic links are bearer challenges intentionally usable on another device;
|
||||
browser-bound OIDC state cookies are not reused for this flow. A dedicated
|
||||
confirmation screen to mitigate link-scanner consumption is separate work.
|
||||
|
||||
## Tests
|
||||
|
||||
Local fake SMTP servers verify successful STARTTLS delivery and safe envelope
|
||||
serialization, refusal of plaintext credentials/untrusted certificates,
|
||||
timeouts at greeting/EHLO/DATA/QUIT, oversized responses, mailbox/header/link
|
||||
injection rejection, and background-slot release. HTTP/store fixtures cover
|
||||
generic request responses, form bounds, full queues, account/membership/email/
|
||||
provider changes, active/readonly success, and challenge replay.
|
||||
|
||||
```sh
|
||||
go test -race ./internal/server -run 'TestSMTP|TestMagicLink' -count=1
|
||||
```
|
||||
@@ -0,0 +1,87 @@
|
||||
# Social link cards (OGP / X)
|
||||
|
||||
Implemented 2026-09-14. This is metadata projection, not a public-share or
|
||||
anonymous-authorization implementation. No visibility settings are changed.
|
||||
|
||||
The next publication-policy design is
|
||||
[Quartier/Spot ownership and superior audience ceilings](locality-publication-ownership.md).
|
||||
Child settings may restrict but cannot override a superior restriction. This is
|
||||
not implemented yet; the current enforcing-domain metadata suppression remains.
|
||||
|
||||
## Supported projections
|
||||
|
||||
Semantic Page/file viewers, all three home layouts, City Map and City details
|
||||
emit server-rendered Open Graph and `twitter:*` tags in their HTML head. No
|
||||
JavaScript execution is required by crawlers. Editors, configuration, login,
|
||||
search, revision/raw endpoints and user-specific utility pages do not acquire
|
||||
social metadata through this feature.
|
||||
|
||||
- Title: first H1 in canonical HTML, otherwise the Page Path; home uses the
|
||||
Domain title, City detail uses its title.
|
||||
- Description: plain text from at most 64 KiB of canonical HTML, reduced to
|
||||
200 Unicode characters. Titles are limited to 90 characters. Scripts, styles,
|
||||
templates, iframes, SVG, noscript and macro syntax are excluded. Expanded
|
||||
children, bookmarks, private related pages and embedded documents are never
|
||||
used as description sources. Non-HTML files use filename / Content-Type.
|
||||
- Default image: `/static/social-card-v1.png`, a fixed 1200×630 PNG book/academy
|
||||
emblem. Generated once per process using Go primitives; no external service,
|
||||
native decoder, font download, scheduler or per-Page cache. GET/HEAD and ETag
|
||||
requests are supported. It contains no Domain or document data.
|
||||
- Original image documents: PNG/JPEG/GIF/WebP below 5 MiB use their semantic
|
||||
`/v/raw/path:{path}` image URL and the `summary` card. Other documents use the
|
||||
default `summary_large_image`. SVG, oversized images and PDFs use the default;
|
||||
no thumbnail generation is triggered by a crawler.
|
||||
- Canonical / image URLs: absolute URLs from the configured effective Domain
|
||||
FQDN (Domain hostname plus Campus FQDN where applicable), using HTTPS. Localhost
|
||||
and IP development hosts use the direct HTTP/TLS scheme and matching port.
|
||||
Forwarded Host/Proto and Origin headers are not canonical-identity sources.
|
||||
Query parameters/fragments, including tokens, never enter card URLs. Literal
|
||||
`?`, `#`, `%` and Unicode in Page Paths are URL-encoded exactly once. City
|
||||
details use their current name-based URL, including the parent for Streets.
|
||||
|
||||
## Privacy and operational limits
|
||||
|
||||
The existing authorization middleware applies unchanged, including for the
|
||||
`Twitterbot` User-Agent. With `authorization_mode=enforcing`, anonymous requests
|
||||
still redirect to authentication; even authenticated HTML contains no card
|
||||
metadata and adds `noindex, nofollow, noarchive`. Unknown/error authorization
|
||||
configuration fails closed. Only existing non-enforcing, anonymously readable
|
||||
deployments emit content cards. Do **not** disable authorization just to enable
|
||||
cards; narrower anonymous read policy and revocable shared links remain separate
|
||||
roadmap work. Existing private/no-store HTML response headers are retained.
|
||||
|
||||
Once a page has been public, a third party may already retain its metadata/image.
|
||||
Later revocation prevents new anonymous retrieval but cannot recall third-party
|
||||
caches. Card layout, refresh timing and final display are controlled by each
|
||||
sharing service. The application can validate its emitted HTML and image URLs,
|
||||
not guarantee a card in every post. Public DNS/TLS and reverse-proxy crawl access
|
||||
must also work. No X account posting/API integration is required or performed.
|
||||
|
||||
Canonical HTML is not modified or sanitized by metadata extraction. Normal
|
||||
document displays now use [inert HTML projections](html-projection-trust.md);
|
||||
explicit anonymous locality authorization and governance remain separate gates.
|
||||
|
||||
## Verification / next slices
|
||||
|
||||
`social_metadata_test.go` exercises real rendered heads, Japanese/entity-safe
|
||||
metadata, bounded extraction, Host spoofing, explicit URL encoding, token
|
||||
omission, private crawler/authenticated requests, policy revocation, every home
|
||||
layout, City UUID-to-name canonicalization, real raw image retrieval and the
|
||||
fallback PNG's dimensions/HEAD/ETag contract.
|
||||
|
||||
Future additions: explicit per-Page cover/description settings, approved
|
||||
Domain-default artwork, precomputed PDF/video/archive cover artifacts, share
|
||||
projection policy, and a settings preview/diagnostic panel. Do not automatically
|
||||
fetch arbitrary body image URLs or leak credentials into images.
|
||||
|
||||
Deployment follow-up: main `pages.anya.jp` currently redirects anonymous crawlers
|
||||
to login (303); its public fallback image is reachable via HTTPS. Managed
|
||||
`wiki.extpages.anya.jp` emits correct tags/image on its local Host-routed listener,
|
||||
but public HTTPS currently fails with TLS `unrecognized name`. Its certificate /
|
||||
reverse-proxy virtual host needs correction before external card retrieval can
|
||||
work. Neither visibility nor external TLS infrastructure was changed here.
|
||||
|
||||
Protocol reference: [Open Graph basic and structured metadata](https://ogp.me/).
|
||||
X compatibility uses the established `twitter:card`, `twitter:title`,
|
||||
`twitter:description`, `twitter:image` and `twitter:image:alt` fields; its old
|
||||
developer Cards documentation currently redirects to the general documentation.
|
||||
@@ -0,0 +1,208 @@
|
||||
# システム拡張の詳細設計
|
||||
|
||||
## 境界と今回の実装
|
||||
|
||||
連携アダプタはDocument/Revisionを特定のMIMEに応じて編集・表示する。
|
||||
システム拡張はナビゲーション、活動、通知、検索、ストレージ、テーマ、監視などの
|
||||
サービスを提供する。設定・API・実行権限をアダプタのURLテンプレートに混在させない。
|
||||
|
||||
実装済みの入口:
|
||||
|
||||
- `internal/extensions/registry.go`: バージョン付きの信頼済みビルトインmanifest。
|
||||
- `GET /_/api/v1/extension/`: 管理者向けcatalog。書き込み・インストールAPIは未公開。
|
||||
- `/-/sys/config?panel=extensions`: 連携アダプタとは独立したシステム拡張一覧。
|
||||
- `system.resources`: instanceスコープのバックグラウンド監視。
|
||||
- `navigation.bookmarks`: domainスコープのカードと子ページリンク。
|
||||
- `content.diary`/`content.blog`: Domain別に有効化する記事メタデータ、カレンダー、
|
||||
最近の記事、カテゴリ一覧。初期版はログイン必須・既存Page登録型。
|
||||
[実装範囲と後続タスク](diary-blog-plugins.md)を参照。
|
||||
|
||||
これは外部プラグインローダーではない。任意Go plugin、JS、シェル、URLからの実行、
|
||||
manifestアップロードによる権限付与は未実装・不許可。現在のcapabilities一覧はサービス
|
||||
境界の宣言であり、既存の認証を置換しない。実際のハンドラは既存のmanage/read権限と
|
||||
管理者グループを確認する。ビルトインの設定入口を分離した最初の実装である。
|
||||
|
||||
vim.wasmの動作改善はユーザー指示により保留。この変更でVim本体を変更しない。
|
||||
|
||||
## Manifest/ライフサイクル契約
|
||||
|
||||
将来の外部パッケージmanifestに必要な項目:
|
||||
|
||||
| 項目 | 意味 |
|
||||
| --- | --- |
|
||||
| id, version, api_version, compatibility | 安定ID、パッケージ版、ホスト契約との互換性 |
|
||||
| kind, scope | activity/comment/diary/theme/monitor/storage/search/bookmark-source、instance/domain/principal |
|
||||
| capabilities, outbound_hosts, secret_refs | 要求能力・送信先許可リスト・秘密参照。manifestのみでは許可しない |
|
||||
| config_schema, migrations | 型付き設定と設定版移行。未知フィールド拒否 |
|
||||
| events, hooks, checkpoints | 定期ジョブ・購読イベント・再実行位置 |
|
||||
| runtime, image_digest, signature | 分離プロセス/コンテナ、固定イメージ、署名 |
|
||||
| timeouts, concurrency, memory, payload_limit | リソース上限。前景処理をブロックしない |
|
||||
| health, export, retention | 健全性、移行・アンインストール時のデータ保護 |
|
||||
|
||||
設定は `(scope_type, scope_uuid, extension_id, schema_version)` で分離する。
|
||||
外部拡張導入時には `system_extension_installations` と `system_extension_config` を追加し、
|
||||
installed → configured → enabled → disabled/failed の状態遷移を監査する。
|
||||
署名・互換性・要求能力を確認するまで実行しない。アップグレード中は新しいジョブを
|
||||
止め、checkpointを保持して移行する。無効化はデータ削除を意味しない。
|
||||
|
||||
設定UIはホスト所有のschema rendererを基本とする。独自UIは固定originのsandbox iframe
|
||||
と型付きメッセージ契約に限定し、通常のログインBearer/Cookieを渡さない。
|
||||
第三者コードはホストプロセス内にロードせず、短命の委譲capabilityでAPIにアクセスする。
|
||||
|
||||
## ビルトインのリソース監視
|
||||
|
||||
- 定義ID `builtin.resource.sample`、イベント型 `resource.sample`。
|
||||
- 起動時に未登録の場合のみ追加。既定60秒、変更可能範囲30〜86400秒。
|
||||
- 既存キューのpriority=100、通常のclaim/履歴/ログ/キャンセルを利用する。
|
||||
CPU・メモリ・ファイルシステム情報だけを収集し、外部コマンドや再帰走査をしない。
|
||||
- `resource_samples(id, job_uuid UNIQUE, timestamp_ms, payload)` に永続化。
|
||||
同一jobの再実行は重複登録しない。書き込みと期限切れ削除は同一トランザクション。
|
||||
- 7日保持。期限切れ削除は収集時に実行する。停止中に過去データを捏造して補間しない。
|
||||
- `GET /_/api/v1/queue/resources/history?hours=1|24|168` は最大361点。
|
||||
timestamp索引で期間を絞り、バケット内の最終サンプルを返す。平均/最大値ではない。
|
||||
- 現在値APIと履歴を区別する。グラフの更新停止やブラウザを閉じる操作は収集を止めない。
|
||||
収集停止は監視イベントのenabledまたはキューのpausedによる。
|
||||
- ビルトイン定義は削除不可。無効化と間隔変更は再起動後も維持する。
|
||||
- データはこのSQLiteインスタンスのローカル監視。Campus全ノードの集約ではない。
|
||||
CPUはホストload average、メモリはGo heap、容量はDocument Storeファイルシステム。
|
||||
コンテナのCPU使用率/RSS/cgroup制限として表示しない。
|
||||
|
||||
既存運用APIと同じインスタンス全体の管理権限を利用する。複数管理主体での厳密な分離は
|
||||
`instance_operator` 相当の運用権限設計後に移行する。HAではinstance UUID/boot IDを追加し、
|
||||
各ノードの収集と中央集約・leaseを分ける。SQLiteファイルの共有マウントで代用しない。
|
||||
|
||||
### ディスクI/O
|
||||
|
||||
`queue/resources` と `resource.sample` の保存payloadへ
|
||||
`io: {scope:"process", available, process_id, read_bytes, write_bytes}` を追加。
|
||||
Linuxの `/proc/self/io` を読み取り、読み込み・書き込みの累積カウンタを保存する。
|
||||
HTTPハンドラで待機や外部コマンド実行、ディレクトリ走査は行わない。
|
||||
`process_id` はアプリプロセスごとのランダムUUIDで、コンテナでPIDが再利用されても区別できる。
|
||||
|
||||
表示速度は同一process_idの隣接サンプルの差分bytes/差分秒。最初のサンプル、
|
||||
旧履歴でI/Oフィールドがない場合、取得失敗、再起動、時刻逆転、カウンタ減少、
|
||||
JSの安全整数範囲外は欠測にし、0や巨大なスパイクで代用しない。
|
||||
ライブカードは画面取得間の速度、履歴は保存サンプル間の平均速度であり、ピーク値ではない。
|
||||
|
||||
[Linux kernelのproc仕様](https://docs.kernel.org/filesystems/proc.html#proc-pid-io-display-the-io-accounting-fields)
|
||||
に従うストレージ層の計上値。`rchar/wchar`(キャッシュ等を含むread/write呼び出しの量)
|
||||
とは区別する。write_bytesはページ変更時の計上で、実デバイスへのflush完了や
|
||||
cancelled_write_bytes差引後の正味書き込みを意味しない。
|
||||
ホスト全体・全コンテナ・外部アダプタ・全ワーカーの合算やデバイス利用率/レイテンシ/IOPS
|
||||
は今回の対象外。必要に応じてcgroup/デバイス別collectorを別スコープとして追加する。
|
||||
|
||||
### SNMPの将来オプション
|
||||
|
||||
`monitor.snmp` は別collectorとして設計する。初期候補はSNMPv3 authPriv、読み取り専用、
|
||||
対象FQDN/IP・OIDを管理者が許可し、秘密はsecret_refで参照する。SNMPv1/v2cは必要性と
|
||||
ネットワーク制約を確認するまで既定無効。到達先制限、タイムアウト、再試行間隔、
|
||||
最大varbind数、単位変換、Counter32/64の周回、再起動によるカウンタリセットを扱う。
|
||||
欠測/認証失敗を0使用率に変換しない。SNMPサーバーの公開やネットワーク探索は今回行わない。
|
||||
|
||||
## 各拡張のデータと処理
|
||||
|
||||
| 拡張 | 保存モデル・表示 | 実行・権限と最初の実装単位 |
|
||||
| --- | --- | --- |
|
||||
| ランキング/いいね | `page_metric_buckets(domain,page_uuid,bucket,metric)`、`page_reactions(domain,page_uuid,principal,reaction)` | 日別閲覧・いいねを集約。閲覧可能Pageだけ表示し、非公開Pageの件数や順位から漏らさない。bot・連打除外、期間と計算版を固定 |
|
||||
| 最新編集 | `page_activity_events` と日別/domain別projection | UUID/Revisionを軸に作成・編集・renameを表示。可視Pathを出力時に解決。bodyを再走査しない |
|
||||
| ユーザー別直近編集 | `(domain,principal,page_uuid,last_edit_at,revision)` projection | actorをクライアント申告にせずサーバーで記録。既定は本人のみ閲覧。現時点のPage権限で再検査 |
|
||||
| コメント | `comment_threads`、`comments`、`comment_anchors` | スレッドはPage UUID、インラインはRevision+範囲+周辺テキストhash。改訂後に再アンカー/孤立を区別。投稿・編集・モデレーション・通知を別capabilityにする |
|
||||
| 日記 | `diary_entries(domain,owner,local_date,page_uuid,timezone)` | 専用Pageを通常のRevisionとして作成。日付は設定timezone、同日作成は冪等。`/u/{name}/diary/YYYY/MM/DD` は初期Path案でありrename後もUUID保持 |
|
||||
| 条件付きテーマ | `theme_rules(domain/principal,priority,condition,theme_id)` | 時刻、曜日、経過時間、OS配色を型付き条件にする。日没はユーザー指定の緯度経度/timezoneで計算し、無断で位置情報を取得しない。CSSテーマIDのみ、任意JS条件は禁止 |
|
||||
| S3互換 | immutable Document Store provider+配置情報 | `PutIfAbsent/Stat/Open/ReadAt/Verify/DeleteUnreferenced` 契約。sha256 identityを維持し、ETagをhashと決めつけない。署名URLは短命、RangeとGC証明・失敗再試行を検証 |
|
||||
| WebDAV/SSHFS | external collection connector または検証済みDocument backend | 編集可能な外部ファイルと正本CASを区別。まずread-only参照/取り込み。WebDAVの条件付き更新・Range、SSHのhost key pinを設計。SSHFSマウント・FUSE権限は専用sidecarで管理しWeb要求からmountしない |
|
||||
| 外部検索 | `search_connectors`+正規化result | PagesWiki/GROWI/PukiWikiは機能検出とAPI契約確認後に個別connector。検索対象domain・資格情報・timeout・最大結果・URL allowlistを設定。外部の権限とローカル権限を混同しない |
|
||||
| Wikipedia/Google補助検索 | 外部検索リンクまたは契約済み検索API provider | ローカル0件でも自動送信しない。送信クエリを表示してユーザーが選択。まず外部検索リンクから開始し、APIは規約・課金・制限を確認して別実装。無許可スクレイピングはしない |
|
||||
| Linkding等のブックマーク引用 | `bookmark_sources`、`external_bookmark_items(source,remote_id,url,title,tags,updated_at)` | URL/タイトル/タグ/出典を同期。本文コピーは別の許可付きimport。個人tokenは個人スコープ、共有を明示。セクションsource providerとして注入し、手動リンクを消さない |
|
||||
|
||||
外部検索APIの共通結果は `provider_id, remote_id, title, canonical_url, snippet,
|
||||
updated_at, source_scope` とし、外部由来を常に表示する。HTMLはサニタイズし、検索結果URLを
|
||||
サーバー側で無制限にfetchしない。
|
||||
|
||||
## イベント/API設計
|
||||
|
||||
## Network and composition extensions (design TODO)
|
||||
|
||||
IPAM, DNS zone/record administration, and inventory/asset management are typed
|
||||
system extensions, not free-form editor adapters. Their records (`network_prefix`,
|
||||
`dns_zone`/`dns_record`, `asset_item`) retain ownership, audit history, soft-delete
|
||||
state, and references to Pages/Assets. Provider writes use dry-run, approval,
|
||||
idempotency keys, etag/revision checks, secret references, allowlisted origins,
|
||||
rate limits, and bounded queue jobs; DNS resolution or scanning never runs in a
|
||||
foreground Page request. Candidate API namespaces are
|
||||
`/_/api/v1/extension/network.ipam/*`, `network.dns/*`, and
|
||||
`inventory.assets/*`, pending schema and permission review.
|
||||
|
||||
The CSV macro is a read projection of an authorized immutable Revision, for
|
||||
example `{{csv:/data/items.csv range=A1:H200 header=true}}`. It must retain the
|
||||
source Path and Revision/hash in its cache key, cap rows/columns/cell size and
|
||||
nested macros, and never write rendered HTML back to the Page. RFC 4180-compatible
|
||||
UTF-8 CSV is the canonical interchange format; ODS is a separate adapter when
|
||||
multiple sheets, formulas, or styles are required. Malformed or oversized data
|
||||
falls back to the bounded text adapter.
|
||||
|
||||
Slide projection/editor support is also TODO. A Reveal-compatible adapter may
|
||||
host HedgeDoc or Slidev behind an explicitly configured origin, CSP, read-only
|
||||
preview, and explicit import/save operation. A CSS-only editor using scroll-snap,
|
||||
`:target`, and print CSS provides a JavaScript-free fallback. Remote scripts,
|
||||
imports, and iframe privileges are never inherited from document content.
|
||||
|
||||
### 日記拡張の追加要件(初期一覧を実装、移行・コメントは未実装)
|
||||
|
||||
日記は主要なシステム拡張として扱い、tDiaryからの移行と日記専用画面を提供する。
|
||||
|
||||
- カレンダーウィジェットから年月日を選択。最近の日記と最近のコメントを同じ画面に配置。
|
||||
個人日記/共有日記、公開/限定公開の範囲を明示し、各ウィジェットも閲覧権限で絞る。
|
||||
- tDiaryインポートは既存のimport session/journalを再利用し、事前解析・プレビュー・
|
||||
日付/タイトル/本文/セクション/コメント/添付画像の対応確認、修正、再実行を分ける。
|
||||
日付・タイムゾーン・旧URLの対応表とインポート元IDを保持し、重複取り込みを防ぐ。
|
||||
- 対応するtDiary版、データ形式、記法、添付・コメントの実際の形式は、実装着手時に
|
||||
公式仕様とユーザーのサンプルで確認する。Rubyファイルやプラグインをeval/実行せず、
|
||||
宣言的な安全な読み取りと変換のみを行う。対応範囲外はスキップ理由を表示する。
|
||||
- 移行コメントは元の著者名・日時を出典として保持し、認証済みローカルユーザーによる
|
||||
投稿と偽って結び付けない。非公開内容の公開、HTML由来XSS、通知の大量送信を防止する。
|
||||
- 順序は日記モデル+カレンダー/最近の日記 → コメント基盤との接続+最近のコメント
|
||||
→ tDiary取り込みの縦切り。実データを使う前に小規模fixtureでドライランと再実行を検証。
|
||||
|
||||
以下の共通outboxは日記・コメントの通知や一覧projectionにも利用する。
|
||||
|
||||
Pageの正本更新と `domain_event_outbox` へのイベント挿入を同一transactionで行う。
|
||||
型は `page.created.v1`, `revision.saved.v1`, `path.renamed.v1`, `page.deleted.v1`,
|
||||
`comment.created.v1`, `reaction.changed.v1` など。actor、domain、Page/Revision UUID、
|
||||
domain sequence、payload version、idempotency keyを含める。本文を無条件に複製しない。
|
||||
|
||||
subscriberごとにcheckpointを持ち、at-least-once配送に対して冪等に集計する。
|
||||
最近編集・ランキング・通知をPage表示ハンドラから同期再計算しない。
|
||||
イベント実行は `/_/api/v1/event/`、キュー状態は `/_/api/v1/queue/` を引き続き利用する。
|
||||
拡張API案は `/_/api/v1/extension/{id}/{operation}`。実装時はoperationごとにtyped policyを
|
||||
登録する。未知ID/operationをgeneric proxyしてはならない。
|
||||
|
||||
閲覧イベントは正本更新ではないため、dedupe/rate limit付きの軽量batch ingestionを
|
||||
分離する。ランキングには匿名化集計を用い、個人閲覧履歴を無期限に保存しない。
|
||||
|
||||
## Kill switch とリソース観測(設計・実装方針)
|
||||
|
||||
各Domain/instanceの `system_extension_states` に拡張IDごとの有効状態を保存し、未登録は有効と解釈する。設定画面または `POST /_/api/v1/extension/` の `{id, enabled}` で切り替え、反映は次の要求・次のジョブから行う。無効化はデータを削除せず、対応画面は安全な404または組み込みfallbackを返す。CLIにも `pageswiki-cli extension [ID] [on|off]` を用意し、DBのWeb UIが利用できない障害時にも切り戻せるようにする。
|
||||
|
||||
システム拡張と連携アダプタは、jobのextension ID、開始・終了時刻、CPU時間、最大RSS、読み書きバイト、待ち時間、出力件数、エラー/キャンセルを共通の実行メトリクスへ記録する。foregroundのProjectionはrequest IDとadapter IDをログへ付け、background処理はイベントキューのbounded jobとしてリソース画面へ集計する。上限超過・連続失敗・queue滞留は拡張単位で通知し、ページ表示のレイテンシーを拡張処理が奪わないことをDone条件にする。
|
||||
|
||||
## 次の実装順序と受入条件
|
||||
|
||||
以下は追加機能同士の順序。先に [実装状況の是正順序](implementation-status.md#ordered-next-work)
|
||||
にある認証・更新整合性・重い要求処理の是正を通す。監視画面統合の次の最初の是正として、
|
||||
ownerの通常更新による降格防止と、並行削除時の最後のowner保持を実装済み。
|
||||
|
||||
1. 今回:ビルトインcatalog、管理パネル、監視イベントと履歴、レスポンシブなカード。
|
||||
2. outboxと監査actorの統一、domain/principal別の最新編集projection。transaction rollback、
|
||||
rename追従、失効権限での非表示をテスト。これを最初の追加システム拡張にする。
|
||||
3. diary(カレンダー・最近の日記・tDiary移行設計)と時刻/OS条件テーマ。
|
||||
最近のコメントは次のコメント基盤に接続。日没計算はtimezone/DSTと位置情報同意を検証して追加。
|
||||
4. reactions・ランキング・コメント。モデレーション、消去/保持、通知契約を先に固める。
|
||||
5. Linkdingのread-only同期、明示操作の外部検索リンク、続いて各Wiki API connector。
|
||||
6. S3 Document Store、WebDAV/SSHのread-only collection、SNMP collectorを独立スライスで実装。
|
||||
7. 外部パッケージの署名・分離runtime・secret store・権限制限・upgrade/rollbackを備えてから
|
||||
第三者プラグインのインストールを公開する。
|
||||
|
||||
全スライスでdomain越境拒否、再実行の冪等性、入力/応答上限、キャンセル、負荷上限、
|
||||
秘密の非表示、停止時の既存Wiki表示への無影響を確認する。未実装機能を有効ボタンだけで
|
||||
動作済みに見せない。ロードマップの完了チェックは縦断した機能単位で付ける。
|
||||
@@ -0,0 +1,72 @@
|
||||
# URI Model
|
||||
|
||||
URI prefixes identify access surfaces, not object meaning. Semantic paths,
|
||||
Page UUIDs, Revisions, and projections remain separate.
|
||||
|
||||
## Canonical namespaces
|
||||
|
||||
| Prefix | Purpose | Status |
|
||||
| --- | --- | --- |
|
||||
| `/...` | Language-neutral semantic Viewer path | active |
|
||||
| `/e/-/...` | Editor for a semantic path | active |
|
||||
| `/o/uuid:<uuid>` | Page/Object access by stable UUID | active |
|
||||
| `/o/path:<path>` | Object resolver through a semantic path | active |
|
||||
| `/r/history/<uuid>` | Revision history for a Page UUID | active |
|
||||
| `/r/view/<revision-uuid>` | Immutable Revision view | active |
|
||||
| `/r/diff/<before>/<after>` | Revision comparison | active |
|
||||
| `/l/uuid:<uuid>` | Semantic path bindings for a Page UUID | active |
|
||||
| `/v/...` | Explicit non-canonical projection | active |
|
||||
| `/v/raw/path:/...` | Current Document payload selected through a semantic path | active |
|
||||
| `/v/raw/uuid:<uuid>` | Current Document payload selected through a Page UUID | active |
|
||||
| `/v/raw/rev:<revision-uuid>` | Immutable Document payload selected through a Revision | active |
|
||||
| `/v/raw/asset:<type>:<name>` | Administrator authoring projection of the current mutable Asset HEAD | active |
|
||||
| `/_/obj/sha256:<hash>` | Authorized immutable Document payload by content identity | active |
|
||||
| `/_/api/...` | Internal/API surface | active |
|
||||
| `/:/...` | System command and creation surface | active |
|
||||
| `/-/...` | System configuration surface | active |
|
||||
| `/s/...` | Delegated share projection | reserved |
|
||||
| `/a/...` | Alias projection | reserved |
|
||||
| `/u/{username}` | User profile and user-Wiki subtree | active |
|
||||
| `/g/{groupname}` | Group profile and group-Wiki subtree | designed |
|
||||
|
||||
## Rules
|
||||
|
||||
Task CalDAV uses `/_/api/v1/caldav/tasks/` (private home/principal),
|
||||
`/_/api/v1/caldav/tasks/default/` (fixed VTODO collection) and
|
||||
`/_/api/v1/caldav/tasks/default/{name}.ics` (resource). These are not Wiki Paths
|
||||
or VEVENT calendars. App credential management lives below
|
||||
`/_/api/v1/extension/organizer.tasks/dav-credentials`.
|
||||
See [scope and interoperability contract](ja/task-caldav.md).
|
||||
|
||||
1. `/...` is the canonical, language-neutral Viewer URL.
|
||||
2. Editing and projection prefixes must not become Page identity.
|
||||
3. `/e/foo` is legacy input and redirects to `/e/-/foo`.
|
||||
4. UUID routes must remain valid after path rename or removal.
|
||||
5. Revision routes address immutable Revision UUIDs.
|
||||
6. Explicit language projection, when implemented, uses a non-canonical
|
||||
namespace and must emit the semantic Viewer URL as canonical.
|
||||
7. Binary media embedded by Viewer uses the `/v/raw/` projection. It accepts
|
||||
an explicit internal address and must not invent a parallel `/raw/...`
|
||||
semantic namespace.
|
||||
8. `/u/` and `/g/` are reserved profile/Wiki namespaces before the semantic
|
||||
catch-all. Their immediate `/_/` child is control space, not semantic Page
|
||||
identity.
|
||||
9. `/_/obj/sha256:<hash>` is reachable only when that Document is referenced
|
||||
by a readable Path in the current Domain. The hash alone grants no access.
|
||||
10. Raw and immutable Document responses expose Object, Revision, and Document
|
||||
identities in `X-PagesWiki-Object-UUID`, `X-PagesWiki-Revision-UUID`, and
|
||||
`X-PagesWiki-Document-SHA256`; clients must not infer one identity from
|
||||
another or treat these descriptive headers as authorization.
|
||||
|
||||
## Internal address schemes
|
||||
|
||||
| Scheme | Identity |
|
||||
| --- | --- |
|
||||
| `path:` | Mutable semantic reachability |
|
||||
| `uuid:` | Stable Page/Object identity |
|
||||
| `rev:` | Immutable Revision identity |
|
||||
| `sha256:` | Immutable Document content identity |
|
||||
| `asset:` | Mutable authoring workspace |
|
||||
|
||||
The HTTP `/r/` namespace and internal `rev:` scheme are related but not
|
||||
interchangeable strings.
|
||||
@@ -0,0 +1,76 @@
|
||||
# User-space visibility and anonymous publication
|
||||
|
||||
Status: implemented for local `/u/{username}` namespaces. The feature is
|
||||
opt-in and defaults to the authenticated Domain audience. It does not add user
|
||||
namespaces to the global anonymous tree.
|
||||
|
||||
## Policy model
|
||||
|
||||
The owner configures the policy at `/u/{username}/_/edit`. Four independent
|
||||
audiences are stored:
|
||||
|
||||
- profile metadata (display name and profile-facing fields),
|
||||
- avatar,
|
||||
- the `/u/{username}` Wiki root document,
|
||||
- descendant Wiki documents.
|
||||
|
||||
Each audience is `private`, `domain`, or `public`. Descendant Paths can have an
|
||||
exact policy that narrows the descendant default to `domain` or `private`; an
|
||||
exact policy also restricts its subtree. It cannot broaden its parent default.
|
||||
The policy row has a compare-and-swap version, and each successful change is
|
||||
recorded as an append-only before/after event.
|
||||
|
||||
`public` is valid only while the Domain is enabled, its Campus is enabled,
|
||||
authorization is enforcing, and the Domain publication ceiling is `public`.
|
||||
Changing that ceiling to authenticated immediately closes the user-space
|
||||
projection. Saving an owner policy cannot raise the Domain ceiling.
|
||||
|
||||
## Projection contract
|
||||
|
||||
User-space publication is a deliberate live-head projection. Once the owner
|
||||
selects `public`, the current language head and future edits under that audience
|
||||
are visible without a separate immutable publication manifest. The settings UI
|
||||
therefore describes it as an automatic publication choice. This differs from
|
||||
the ordinary explicit-Revision approval flow and must not be inferred from a
|
||||
Domain ceiling alone.
|
||||
|
||||
Anonymous requests resolve through a user-space-specific reader. It:
|
||||
|
||||
1. resolves an active local username and re-evaluates the Domain ceiling;
|
||||
2. evaluates root/descendant/override visibility;
|
||||
3. requires one canonical Path binding for the Object;
|
||||
4. chooses a bounded current language head;
|
||||
5. builds a bounded navigation snapshot containing only visible user Paths;
|
||||
6. renders through the normal safe HTML/content projection.
|
||||
|
||||
The same snapshot supplies `/v/children`, `/v/tree/u/{username}` and
|
||||
`/v/browser/u/{username}`. User spaces remain excluded from the global
|
||||
anonymous tree. UUID, Revision, document-hash, aliases, reserved `/_/` routes,
|
||||
and ordinary City publication cannot be used to bypass this reader. The avatar
|
||||
has its own audience check and is returned with `private, no-store`.
|
||||
|
||||
Authenticated readers are also constrained by the user policy. The owner and a
|
||||
Domain administrator can recover the namespace; other members cannot read a
|
||||
`private` root, descendant, avatar, Object or Revision even when a broader
|
||||
Domain grant exists. Request-local policy caching is permitted, but there is no
|
||||
process-wide authorization cache, so revocation applies on the next request.
|
||||
|
||||
## Structural changes and bounds
|
||||
|
||||
Exact overrides follow an atomic Path rename, including recursive subtree
|
||||
rename. A protected override cannot be moved outside its owner's user
|
||||
namespace, and deleting its Path deletes the stale exact override. The current
|
||||
limits are 256 saved overrides, 512 rows in the edit listing, the common
|
||||
navigation entry budget, and the common projection input limit. Exceeding a
|
||||
bound fails closed.
|
||||
|
||||
## Remaining work
|
||||
|
||||
- Add a paginated override editor for user spaces larger than the current edit
|
||||
listing budget.
|
||||
- Decide whether administrators need an audited emergency policy editor; the
|
||||
current UI intentionally remains owner-only while the Domain ceiling is the
|
||||
superior control.
|
||||
- Connect user-space automatic publication to the future human approval policy
|
||||
without converting existing private/domain policies.
|
||||
- Add export/restore tooling for policy events and explicit policy-history UI.
|
||||
@@ -0,0 +1,104 @@
|
||||
# Zombie GC: 原子性・Domain 境界・instance maintenance
|
||||
|
||||
更新: 2026-09-14
|
||||
|
||||
## 修正した問題
|
||||
|
||||
旧実装は全インスタンスの候補を transaction 外で取得し、その UUID の
|
||||
Revision/Object を無条件に削除していた。WAL reader の候補取得後に別 connection
|
||||
が Path/Asset/本文 Revision を追加すると、その変更を無視して削除できた。
|
||||
また Domain 管理者の HTTP/config 操作が同じ global purge を呼び出していた。
|
||||
|
||||
## 候補の定義
|
||||
|
||||
Object の作成時刻が指定した猶予期間より古く、次の全条件を満たすものに限定する。
|
||||
|
||||
- **すべての Domain** において Path と Asset 所有者の参照がない。
|
||||
- Revision がない、または **全 Revision** の本文 bytes と Document hash が空である。
|
||||
空 Document の SHA-256 は空として扱うが、非空の inline body を上書きしない。
|
||||
NUL を含む本文も BLOB byte length で保護する。HEAD だけの判定は禁止する。
|
||||
- `revision_document_refs`、City の明示ページ参照・Street inbox・ページ配置 override、
|
||||
exact Object capability grant、未期限切れの連携エディタ ticket/session がない。
|
||||
|
||||
後半の参照は保守的に保護する。Path だけ消しても、意味的に保持している空ページや
|
||||
編集中のページを自動削除しない。期限切れ editor session の bookkeeping は削除時に清掃する。
|
||||
|
||||
## 権限境界
|
||||
|
||||
| 呼び出し元 | 範囲 |
|
||||
| --- | --- |
|
||||
| `GET /_/api/v1/gc/zombies/list` | current Domain の作成 provenance がある候補のみ |
|
||||
| `POST /_/api/v1/gc/zombies/purge` | current Domain の作成 provenance がある候補のみ |
|
||||
| 設定画面の一覧・`section=zombie-purge` | 同じ Domain 制約 |
|
||||
| ローカルの trusted CLI/store maintenance | インスタンス全体 |
|
||||
| ビルトイン 6 時間周期 GC worker | インスタンス全体 |
|
||||
|
||||
HTTP 呼び出しは `object_origins(object_uuid, domain_uuid)` が current Domain に一致する
|
||||
ことを必須とする。クエリ・フォームの `domain_uuid` で切り替えない。Campus 管理者でも
|
||||
HTTP から global maintenance に昇格しない。legacy/作成元不明 Object は一覧にも出さず、
|
||||
HTTP から削除しない。参照がないこと自体を所有権の証拠にはしない。
|
||||
|
||||
`CreateObjectInDomain` が記録した provenance を利用する。作成元を記録していない
|
||||
既存データや旧作成経路を、現在の default Domain に推測で backfill してはならない。
|
||||
こうしたデータの整理は trusted instance maintenance の範囲とする。
|
||||
|
||||
現在 `runEvent` に global GC の event type は登録しない。HTTP から任意の event type
|
||||
を保存・手動起動しても、`gc.purge` 等は worker で unknown type として失敗し、削除しない。
|
||||
将来 GC を scheduler に統合する場合、サーバー内部だけが設定できる trusted origin と、
|
||||
Domain provenance を持つ手動 payload の区別を先に設計する必要がある。
|
||||
|
||||
## 書き込み原子性と上限
|
||||
|
||||
`BeginTx(ctx)` の直後、`zombie_gc_maintenance` の一行を UPDATE し、SQLite の writer lock
|
||||
を取得してから候補を選ぶ。同じ write transaction 内で UUID ごとに全条件と provenance を
|
||||
再検証し、関連 bookkeeping/Revision/Object を削除する。候補抽出から commit まで他 connection
|
||||
の書き込みが入らない。失敗・キャンセル時にはバッチ全体を rollback し、成功件数を返さない。
|
||||
|
||||
Domain 一覧は indexed `object_origins(domain_uuid, object_uuid)` から検索を開始する。
|
||||
他 Domain の全 Object を走査しない。候補上限は SQL `LIMIT` に置き、Go の後処理 slice
|
||||
で制限してはならない。各参照検索には Object/Page UUID の lookup index を用意する。
|
||||
|
||||
- HTTP/config の既定バッチ: 100 件。
|
||||
- 最大: 1,000 件。HTTP の `limit=0`・負数・最大値超過は 400。
|
||||
- trusted store の旧 `limit=0` は無制限にせず既定 100 件とする。
|
||||
- trusted 一覧も最大 1,000 件。継続する purge はローカルから明示的に繰り返す。
|
||||
- 検索・削除の context は最長 5 秒。HTTP は request context のキャンセルを継承する。
|
||||
- SQLite writer の待機も既存 busy timeout の 5 秒内。重い history の走査が期限に
|
||||
達したときは、不完全な候補判定で削除せず失敗する。
|
||||
|
||||
Foreign key enforcement が無効な legacy connection でも整合性を保つよう、
|
||||
`object_origins` 等は明示的に清掃する。Revision の検索 index は既存の transaction 内
|
||||
trigger で追従する。CAS 本体のファイル削除はこの GC では行わない。
|
||||
|
||||
`BindPathInDomain` と Revision の INSERT も、同じ書き込み SQL に
|
||||
`WHERE EXISTS(SELECT ... FROM objects)` と `RowsAffected` の検証を置く。
|
||||
GC が先に commit した場合は `ErrPageNotFound` または安全な書き込み競合失敗となり、
|
||||
orphan Path/Revision を作らない。失敗した bind は既存 Path を置換しない。
|
||||
`PutAsset` は新規 Object と Asset を同じ transaction で作成しており、別途変更は不要。
|
||||
|
||||
## global worker の猶予期間
|
||||
|
||||
既定の **24 時間** と **6 時間ごとの実行** は維持する。今回の変更によって従来より
|
||||
短い猶予へ移行させない。
|
||||
|
||||
起動時に、従来の default Domain の `zombie_grace_hours`、24 時間、永続保持済み値、
|
||||
operator 環境変数 `PAGESWIKI_ZOMBIE_GC_GRACE_HOURS` の最大値を採用し、
|
||||
`zombie_gc_maintenance.grace_seconds` に high-water mark として保存する。
|
||||
Domain の UI 設定がその後短縮されても、再起動しても、この値は小さくならない。
|
||||
Domain の設定は Domain 内の手動 purge に適用され、稼働中の global worker は変更しない。
|
||||
|
||||
より長い operator 環境設定は再起動時に継承できる。短縮のための HTTP/API は提供しない。
|
||||
従来設定の読み込み失敗・不正な operator 環境設定では global worker を停止しログに残す。
|
||||
時間から秒への整数 overflow で削除が早まることも防止する。
|
||||
|
||||
## 回帰テスト
|
||||
|
||||
- WAL の別 connection が Path・Asset・非空 Revision を未 commit のまま追加し、
|
||||
GC を開始した後で commit しても Object が保持される。
|
||||
- 作成元が foreign/unknown の Object は管理画面/API から見えず、削除できない。
|
||||
- 他 Domain の Path/Asset、過去 Revision、NUL bytes、CAS hash、明示参照を保持する。
|
||||
- 既定/最大/不正 limit、キャンセル、途中 SQL failure の完全 rollback。
|
||||
- GC の commit 後の bind・Revision 保存は孤立データを作らない。Revision は
|
||||
テスト専用 SQLite view/scalar による制御で、存在確認直後の削除を時刻依存なく再現する。
|
||||
- 手動 event の偽装 type から global GC を実行できない。
|
||||
- 長い従来設定、Domain 設定変更、再起動、operator 設定、整数 overflow、設定 read failure。
|
||||
@@ -0,0 +1,54 @@
|
||||
# 本番反映:アクティブ通知・タスク一覧・スマホカレンダー
|
||||
|
||||
実施日:2026-09-25 JST。最終確認:06:00:52 JST。
|
||||
|
||||
## 対象と結果
|
||||
|
||||
- Compose `app` / `app2`(`pageswiki` / `pageswiki-ext`)を更新済み。
|
||||
- アクティブ通知/Web Push、タスクのインライン編集・サブタスク・日割り工程表、スマートフォン向けカレンダーUIを反映。
|
||||
- アダプタゲートウェイ、code-server、Excalidraw、Kroki関連は更新・再起動していない。
|
||||
- 新イメージ:`sha256:5e70e0d6789cfa2f558e9d8e3855095709068a023ef939b9bf54fe36846f79dc`
|
||||
- 旧イメージ:`sha256:2bfab91fe4f8712a25b8e5a6cdb1494b68ccdd9433609b35ce25ae391b98bfe6`
|
||||
- 旧イメージ保全タグ:`pageswiki-app:rollback-before-active-notifications-20260925`
|
||||
- app起動:05:59:21 JST。app2起動:05:59:49 JST。両方running・再起動回数0、appのDocker healthはhealthy。
|
||||
|
||||
## バックアップと反映手順
|
||||
|
||||
全Goテスト成功後、旧イメージに保全タグを付与。稼働中に `docker compose build app` を完了した。
|
||||
|
||||
その後2アプリを停止し、DB・WAL・Document Storeを含むdata/data2の停止時点スナップショットをtarへ保存した。外部取り込みカレンダーの本文は調査していない。
|
||||
|
||||
- 保存先:`.deployment-backups/20260925-active-notifications-calendar-mobile/`
|
||||
- `data-and-data2.tar`:12,067,358,720 bytes、2,414 entries。
|
||||
- ディレクトリ700、アーカイブ600。Compose設定・Dockerfile・.dockerignoreも保全。秘密情報を本記録に転記しない。
|
||||
- tar作成終了コード0、アーカイブ一覧の読み取り成功を確認。完全なリストア訓練は未実施。
|
||||
- Git/Docker buildからバックアップが除外されていることを確認。
|
||||
|
||||
バックアップ完了後、`docker compose up -d --no-deps --wait --wait-timeout 180 app app2` で再作成。停止を伴う更新であり、無停止デプロイではない。
|
||||
|
||||
## 確認結果
|
||||
|
||||
- ローカル3000/3001の `/health`:両方200。
|
||||
- `https://pages.anya.jp/health`、`/`、`/v/plan`:200。
|
||||
- 匿名の `/v/plan/tasks/schedule`:303、通知Push API:401。認証を迂回していない。
|
||||
- HTTPS配信した `notifications.js`、`notifications-worker.js`、`calendar.js`、`calendar-mobile.css`、`task-inline.js` のSHA-256が作業ツリーと一致。
|
||||
- 両DBにnotification_push関連3テーブル、organizer_itemsのparent_uuid/start_on/end_onを確認。
|
||||
- 両側の `builtin.notification.push` が有効、30秒間隔。`notification.push.deliver` が各3回成功。
|
||||
- 起動以降の確認区間で、fatal/初期化失敗/scheduler claim失敗/DB lock/失敗ジョブのログ該当件数は両方0。
|
||||
- Push購読件数は両側0。ジョブの正常実行は確認したが、実端末への配送成功を意味しない。
|
||||
- バックアップ後の作業ディスク空きは約72GB。今回バックアップの自動削除・期限設定は行っていない。
|
||||
|
||||
ユーザの代理ログイン、本番の予定・タスク作成、通知許可の代理操作、外部カレンダーの手動同期は実施していない。認証済みUIの操作検証は合成fixtureで実施済み。
|
||||
|
||||
## 利用開始・残確認
|
||||
|
||||
通知ベル →「⚙ 通知設定」でブラウザ通知を有効化し、利用者本人が通知許可を与える。選択した音はページ内通知用、背景/閉タブ時の音はOS設定に従う。タスク期限/計画日のリマインダーは個別タスク側でもONにする。
|
||||
|
||||
- [ ] Safari/iPhone SE実機:縦横切り替え、キーボード開閉、スクロール、編集操作切り替え。
|
||||
- [ ] 明示的に購読した実端末:Web Push受信、閉タブ/背景/前面、ログアウト後停止。
|
||||
|
||||
## 切り戻し
|
||||
|
||||
旧イメージと停止時点のデータを保全している。ただし旧バイナリで新しいサブタスク/工程日を編集すると、新フィールドを失う可能性がある。また旧バイナリは新Pushイベントを処理できない。単純なイメージ差し替えを自動実行せず、原則forward-fixを優先する。
|
||||
|
||||
データ復元は反映後の更新を失うため別途確認を得る。復元が必要なら現状態も保存し、全writer停止下でDBとDocument Storeを同じ時点にそろえる。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 本番反映:タスク一覧のコンパクトUI
|
||||
|
||||
実施日:2026-09-25 06:17 JST。
|
||||
|
||||
## 対象
|
||||
|
||||
- Compose `app` / `app2`(`pageswiki` / `pageswiki-ext`)を更新。
|
||||
- PCの1タスク1行表示、共通列見出し、インライン編集、サブタスクの列揃え、スマホのラベル付き入力・44px以上のタッチ領域を反映。
|
||||
- CSSは `tasks.css?v=7`、JavaScriptは `task-inline.js?v=2`。
|
||||
- 他のサービスは再作成していない。
|
||||
|
||||
## 差分と事前検証
|
||||
|
||||
稼働イメージ内と作業ツリーのファイルハッシュを比較。非テストのGoソース、go.mod、go.sum、Dockerfileは一致。static/templatesの差分は次の4ファイルのみ。
|
||||
|
||||
- `static/css/tasks.css`
|
||||
- `static/js/task-inline.js`
|
||||
- `templates/pages/tasks.gohtml`
|
||||
- `templates/pages/task_schedule.gohtml`
|
||||
|
||||
前段で全Goテスト成功。隔離した合成fixtureを用いたChromiumの1440px、1024px、390px、320px幅検証も成功。列揃え・行高・タッチ領域・子追加・保存競合時のエラー表示と入力保持を確認済み。実機Safariでの検証は別途必要。
|
||||
|
||||
## 反映手順と切り戻し
|
||||
|
||||
- 旧イメージ:`sha256:5e70e0d6789cfa2f558e9d8e3855095709068a023ef939b9bf54fe36846f79dc`
|
||||
- 保全タグ:`pageswiki-app:rollback-before-compact-task-ui-20260925`
|
||||
- 新イメージ:`sha256:e5a7b7877f7c8f8701d0152468b4ee818f9fcb181509f7d223d2c00678c80925`
|
||||
|
||||
旧イメージに保全タグを付け、稼働中に `docker compose build app`。その後 `docker compose up -d --no-deps --wait --wait-timeout 180 app app2` で更新した。
|
||||
|
||||
UIのみの更新であり、新たなDB migrationはない。data/data2は既存のマウントを保持し、削除・復元・手動編集はしていない。今回、新しいデータ全体バックアップは作成していない。直前の06:00前のデプロイ時バックアップは保全されているが、今回更新時点のスナップショットではない。
|
||||
|
||||
切り戻し時は上記の旧イメージを利用して2アプリを再作成する。バックエンドとDBモデルは同一のため、このUI変更の取り消しにデータ復元は不要。データ復元を自動実施しない。
|
||||
|
||||
## 稼働確認
|
||||
|
||||
- app起動:06:16:47 JST、app2起動:06:17:13 JST。両方running、再起動回数0。
|
||||
- appのDocker healthはhealthy。app2はDocker healthcheck未設定のため、HTTPで確認。
|
||||
- ローカル3000/3001と `https://pages.anya.jp/health`:すべて200。
|
||||
- HTTPSトップページ:200。
|
||||
- 未認証の `/v/plan/today`、`/v/plan/tasks`、`/v/plan/tasks/schedule`:303。認証制限を維持。
|
||||
- HTTPS配信のtasks.css / task-inline.jsのSHA-256がローカルと一致。両コンテナの対象4ファイルも一致。
|
||||
- 06:18:32 JST時点の起動後ログ集計:両方ともpanic/初期化失敗、DBロック/scheduler claim失敗、失敗ジョブの該当件数は0。
|
||||
- 再作成中の起動待ちで一時的にHTTPS 502を確認したが、起動完了後は200へ回復。無停止更新ではない。
|
||||
|
||||
本番ユーザへの代理ログインやタスク作成、外部取り込みカレンダーへのアクセスは行っていない。認証済み操作は合成fixtureで検証し、本番では起動・配信・未認証アクセス制限を確認した。
|
||||
@@ -0,0 +1,66 @@
|
||||
# 本番反映:日別計画・親子タスク・Wikiメモ
|
||||
|
||||
実施日:2026-09-25 07:07 JST。organizer.tasks 0.7.0。
|
||||
|
||||
## 対象と反映内容
|
||||
|
||||
Compose `app` / `app2`(`pageswiki` / `pageswiki-ext`)へ反映。
|
||||
|
||||
- 持ち越し・明日・任意の日付の計画、期限を変えない再割当て。
|
||||
- 親子順のcursorページング、フィルタ対象外の親の補足、別日付の子の展開。
|
||||
- 行内のWikiメモ閲覧・編集、プロジェクト配下への原子的な新規作成とUUID紐づけ。
|
||||
- 日別画面から作成するカレンダー時間枠の初期日付。
|
||||
- CSS v8、task-inline v3、tasks v6、task-planning v3。
|
||||
|
||||
アダプタゲートウェイ・code-server等の他サービスは再作成していない。
|
||||
|
||||
## 事前確認・テスト
|
||||
|
||||
稼働イメージとコードをハッシュ比較し、今回の差分がタスク関連バックエンド・UI・拡張バージョンであることを確認。go.mod、go.sum、Dockerfile、migrationは変更なし。
|
||||
|
||||
- 全Goテスト成功。
|
||||
- Chromium fixture(1440/1024/390/320px)の実操作テスト成功。
|
||||
- 外部取り込みカレンダーへのアクセス、本番ユーザへの代理ログイン、本番タスク/メモのテスト作成は行っていない。
|
||||
|
||||
## バックアップと反映
|
||||
|
||||
- 旧イメージ:`sha256:e5a7b7877f7c8f8701d0152468b4ee818f9fcb181509f7d223d2c00678c80925`
|
||||
- 保全タグ:`pageswiki-app:rollback-before-task-daily-notes-20260925`
|
||||
- 新イメージ:`sha256:911c5d4c425dd759bbdcb15b4a559e4160af09e1d92c7f604bbb057520c94acd`
|
||||
|
||||
稼働中に新イメージをビルド。2アプリを停止後、data/data2を同一停止時点でtarへ保存した。
|
||||
|
||||
- 保存先:`.deployment-backups/20260925-task-daily-notes/`
|
||||
- `data-and-data2.tar`:12,068,106,240 bytes、2,426 entries。
|
||||
- ディレクトリ700、アーカイブと保存したCompose設定等は600。
|
||||
- tar作成終了コード0、一覧読み取り終了コード0を確認。復元訓練は未実施。
|
||||
- 07:06:50 JSTバックアップ完了。バックアップ後のディスク空きは約60GB、使用率92%。既存バックアップの削除はしていない。
|
||||
|
||||
`docker compose up -d --no-deps --wait --wait-timeout 180 app app2` により更新。appは07:07:02、app2は07:07:30 JST起動。停止を伴うデプロイであり無停止ではない。
|
||||
|
||||
## 反映後確認
|
||||
|
||||
- 両アプリrunning、再起動回数0。appのDocker healthはhealthy、app2はhealthcheck未設定につきHTTPで確認。
|
||||
- ローカル3000/3001と本番HTTPSの `/health` は200、HTTPSトップページも200。
|
||||
- 未認証の今日・明日・持ち越し・日別画面は303、日別一覧APIとWikiメモAPIは401。
|
||||
- HTTPS配信のCSS・3つのJavaScriptが作業ツリーのSHA-256と一致。
|
||||
- 両コンテナの変更対象バックエンド・テンプレートのSHA-256も作業ツリーと一致。
|
||||
- 認証済みの編集・新規作成操作は合成fixtureで確認。本番では疎通・配信・アクセス制限を確認し、利用者データの変更を伴う試験はしていない。
|
||||
|
||||
### スケジューラの要フォロー事項
|
||||
|
||||
app側で07:07:29および07:09:29 JSTに `event scheduler claim failed: database is locked (SQLITE_BUSY)` を確認。app2では同時区間の該当なし。07:09:55 JST時点では両側の通知配信ジョブが複数回succeededとなり、キュー処理の継続を確認。重大な初期化エラー・panic・renderエラー・失敗ジョブのログは確認区間で0。
|
||||
|
||||
今回 `ClaimDueEvent` 自体は変更していない。この処理はdeferred transactionでSELECT後にUPDATEする既存実装であり、並行writerとのロック競合対策を次の品質改善候補として残す。デプロイ作業に含めて未検証のスケジューラ改修や設定変更は行っていない。単発の起動時だけとは断定しない。
|
||||
|
||||
- [ ] claim処理の競合を隔離fixtureで再現し、原子的claim/writer予約/限定retryを比較する。本文・外部カレンダーを参照せず、二重実行防止とforeground応答を検証する。
|
||||
|
||||
最終確認07:10:47 JST:2度目のロック以降もappで2件(最終07:10:29)、app2で3件(最終07:10:31)の通知配信ジョブが成功。HTTPS healthは200。ロックの再発対策は残件だが、スケジューラが停止した状態ではない。
|
||||
|
||||
## 切り戻しの注意
|
||||
|
||||
DBスキーマ変更はないが、プロジェクト正本へ `notes_subpath` が追加される。旧バイナリでプロジェクト設定を保存するとこの項目を落とすため、利用開始後はforward-fixを優先する。作成済みメモは通常のWiki Pageで、タスクのpage_uuid紐づけを利用する。
|
||||
|
||||
旧イメージは保全済み。データ復元は反映後の更新を失うため自動では実施しない。必要時は現状も保存し、全writer停止下でDBとDocument Storeを同じバックアップ時点へ戻すことについて確認を得る。
|
||||
|
||||
残確認:実機Safari/iPhoneでの入力・操作。バックアップ保持期間と空き容量の管理は別途検討する。
|
||||
@@ -0,0 +1,51 @@
|
||||
# 本番反映記録:タスク・時間枠・Pomodoro・Today
|
||||
|
||||
実施日:2026-09-25 JST(コンテナ起動時刻は2026-09-24 UTC)。
|
||||
|
||||
## 対象と結果
|
||||
|
||||
- Composeサービス `app` / `app2`(`pageswiki` / `pageswiki-ext`)を更新。
|
||||
- アダプタゲートウェイ、code-server、Excalidraw、Kroki関連は再起動していない。
|
||||
- 旧イメージ:`sha256:69d66a1501f88b57f8b570dad488fef2bae3e3a3183b1e5ef9b5faa69c0b54b7`
|
||||
- 新イメージ:`sha256:2bfab91fe4f8712a25b8e5a6cdb1494b68ccdd9433609b35ce25ae391b98bfe6`
|
||||
- 旧イメージ保全タグ:`pageswiki-app:rollback-before-task-today-20260925`
|
||||
- app起動:04:36:10 JST、app2起動:04:36:37 JST。両コンテナの再起動回数0。
|
||||
|
||||
## 保全と手順
|
||||
|
||||
切り替え前に `go test ./...` が成功。旧イメージをタグで保全し、稼働中に `docker compose build app` を完了。
|
||||
|
||||
切り替え時に両アプリを停止してから、dataとdata2を一緒に非圧縮tarへ保存した。DB・WAL・Document Store・その他のファイルを停止中の状態で保全し、予定の内容を調査したり外部カレンダーへ手動接続したりしていない。
|
||||
|
||||
- 保存先:プロジェクト直下 `.deployment-backups/20260925-task-today/`
|
||||
- データ:`data-and-data2.tar`(12,066,856,960 bytes)
|
||||
- ディレクトリ権限700、アーカイブ権限600。
|
||||
- Compose設定、Dockerfile、.dockerignoreも同じ保護ディレクトリに保存。設定の秘密を本書へ転記しない。
|
||||
- バックアップをGitとDockerビルドの対象から除外した。
|
||||
- tar終了コード正常、アーカイブ一覧を読み取れることを確認(2408 entries)。完全なリストア訓練やDB全件の整合性検査は今回実施していない。
|
||||
|
||||
保存後、`docker compose up -d --no-deps --wait --wait-timeout 180 app app2` で更新。停止を伴う反映であり、無停止デプロイではない。
|
||||
|
||||
## 本番で確認した項目
|
||||
|
||||
- ローカル3000/3001両方の `/health`:200。
|
||||
- `https://pages.anya.jp/health` と `/`:200。
|
||||
- 匿名の `/v/plan/today`:303。匿名のToday API:401。認証を迂回しない。
|
||||
- HTTPSで取得した `task-today.js?v=1` のSHA-256が作業ツリーのファイルと一致。
|
||||
- 両DBで `organizer_time_blocks` / `organizer_focus` / `organizer_focus_spans`、時間枠のtitle列を確認。
|
||||
- タスク通知・focus終了イベントの登録を確認(既定60秒)。
|
||||
- 両インスタンスで `task.activity.publish` / `task.focus.complete` / `task.reminders.deliver` が反映後に各3回成功していることを、ジョブ状態だけで確認。
|
||||
|
||||
本番で新規のタスク・予定・集中セッションを作成する書き込み試験や、利用者へのなりすましログインは実施していない。認証済みの操作・PC/モバイル表示は、反映前の隔離Chromiumテストで確認済み。
|
||||
|
||||
## 観測した注意事項
|
||||
|
||||
メインのイベント取得処理で、04:36:36 JSTにSQLite 517、04:37:36 JSTにSQLITE_BUSYが記録された。スケジューラは次回処理で継続し、04:38台に上記タスクジョブが成功。04:38以降の確認区間ではclaimエラー再発・起動失敗・panicはなし。恒久的に再発しないことを保証する確認ではない。
|
||||
|
||||
- [ ] 後続品質改善:`ClaimDueEvent`のread→write昇格時の競合、busy時の限定リトライ、claim待ち時間と失敗率を検証する。今回のデプロイ中にスケジューラの実装や運用設定は変更していない。
|
||||
|
||||
## 切り戻しの判断材料
|
||||
|
||||
旧イメージと停止時点のデータを保持している。必要時はまず新しい書き込みの有無と旧版のスキーマ/イベント互換性を確認し、切り戻し手順を選ぶ。旧タグを `pageswiki-app` に戻して対象2サービスだけを再作成する方法があるが、今回リハーサルしたものではない。
|
||||
|
||||
データの復元は切り替え以降の更新を失うため、自動実施しない。必要な場合は現状態も保全し、利用者の確認を得て、全writer停止下でDBとDocument Storeを一緒に扱う。バックアップの削除・自動期限設定も今回行っていない。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 本番修正:chroncalのタスクCalDAV互換性
|
||||
|
||||
2026-09-26 JST。organizer.tasks 0.8.1。01:00 JSTにapp/app2へ反映済み、事後確認完了。
|
||||
|
||||
## 原因
|
||||
|
||||
chroncal 0.10.0はaccount endpointの末尾slashを除去してprincipal探索する。
|
||||
タスクhomeのslashなし経路はServeMuxの301に入り、Go HTTPクライアントがPROPFINDをGETへ変えて再送し、home GETが405になった。
|
||||
前回の修正はslash付き経路の正規化循環のみを防ぎ、逆方向の301を防げていなかった。
|
||||
|
||||
## 修正
|
||||
|
||||
- slashなしhomeも明示登録し、home/collectionをslash有無どちらでも直接処理する。返却hrefは従来canonical URIを維持。
|
||||
- chroncal/go-webdavの`calendar-data/comp(name=VCALENDAR)/allprop+allcomp`を全件取得として受理。部分選択・expand・time-range制約は従来通り拒否。
|
||||
- getlastmodifiedを返す。
|
||||
- chroncalは新規PUTでIf-None-Matchを送らないため、完全な新規identityへの無条件作成のみ許可。既存上書きとアーカイブ復活は無条件では不可。transaction内のhref/UID一意性、ETag/CAS、認可は維持。
|
||||
- sync-collectionは引き続き未対応。chroncalの405→calendar-queryフォールバックで同期する。差分対応の偽装はしない。
|
||||
|
||||
## 検証
|
||||
|
||||
- chroncal 0.10.0実行ファイルで、探索・初回取得・作成・完了・Web側変更取得・削除→アーカイブ・無変更再同期を確認。
|
||||
- CLI試験は一時HOME/XDGディレクトリ・DB・fixture資格情報に限定し、ユーザーの既存chroncal設定やOS keyringを参照しない。
|
||||
- vdirsyncer/Todoman回帰、slash有無のPROPFIND、部分投影拒否、同時新規作成・無条件上書き拒否を検証。
|
||||
- 全Goテスト成功。`git diff --check`成功。
|
||||
- 本番ユーザーのタスクや外部カレンダー本文は取得しない。原因確認時の本番ログは探索メソッドとPathのみを参照。
|
||||
|
||||
## 反映
|
||||
|
||||
- 対象:app / app2のみ。他のサービスは再作成しない。
|
||||
- 旧:`sha256:02bb3d66973501804c6cbe3cd5b4ce7f644b148403eae98f88e5d9c837c667e3`
|
||||
- 保全:`pageswiki-app:rollback-before-chroncal-fix-20260926`
|
||||
- 新:`sha256:261e24eb1834454a9a47f70ee135269d465b3a4696048890afc492a332e32809`
|
||||
- コードのみの修正。DBスキーマ・データ形式は0.8.0と同じ。直前の[0.8.0反映時バックアップ](2026-09-26-task-caldav.md)を保持し、追加フルバックアップやデータ復元は行わない。
|
||||
- 旧イメージへ切り戻すとchroncalの互換不具合は再発するが、0.8.0とのデータ互換性は変わらない。
|
||||
|
||||
## 事後確認
|
||||
|
||||
- appは01:00:32 JST、app2は01:00:57 JSTに新イメージで起動。両方running、再起動回数0。appのDocker healthはhealthy、独立healthcheckのないapp2は正しいHostで`/health`の200を確認。
|
||||
- 公開HTTPSでtask home/default collectionそれぞれslash有無のPROPFINDが、リダイレクトなしの401を返すことを確認。認証前の応答として正常であり、実アカウントの内容は取得していない。
|
||||
- app2も`Host: wiki.extpages.anya.jp`でslashなしhomeのPROPFINDが401、リダイレクトなし。
|
||||
- 起動後の確認時点では、両コンテナともfatal/DB locked/event job failed/render errorのログ件数は0。過去の障害全般の解消を意味するものではない。
|
||||
- 認証付きの探索と変更操作は前述の隔離fixtureで検証。本番資格情報の再発行やクライアント設定の削除は不要。
|
||||
Loaded 100 of 699 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user