239 lines
8.5 KiB
Go
239 lines
8.5 KiB
Go
package httpapi
|
|
|
|
import (
|
|
"net/http"
|
|
"time"
|
|
|
|
"textmachine/platform/internal/ingest"
|
|
)
|
|
|
|
// reading.go: the chapter tree, its pairs, the book's notes and its memory bank.
|
|
//
|
|
// One rule shapes all four: a collection answers ONE page and the revision that page is a picture
|
|
// of, read in the same transaction. The client stamps a multi-page WALK with the lowest revision it
|
|
// saw and uses that as the watermark of its next delta read (canon §Revision) — server-side that
|
|
// means every page carries its own number and none of them carries a promise about the others.
|
|
|
|
type wireChapter struct {
|
|
ID string `json:"id"`
|
|
Number *int `json:"number"`
|
|
// Heading is the chapter's label as it comes from the DATA of the book, or null. A deployment
|
|
// whose parser does not extract labels answers null and MUST NOT put a rendered ordinal here.
|
|
Heading *string `json:"heading"`
|
|
UnitsTotal int `json:"units_total"`
|
|
UnitsDone int `json:"units_done"`
|
|
NoteCount int `json:"note_count"`
|
|
}
|
|
|
|
type wireChapterPage struct {
|
|
Revision int64 `json:"revision"`
|
|
NextCursor *string `json:"next_cursor"`
|
|
StructureVersion int `json:"structure_version"`
|
|
Chapters []wireChapter `json:"chapters"`
|
|
}
|
|
|
|
type wireUnit struct {
|
|
ID string `json:"id"`
|
|
Source string `json:"source"`
|
|
// Target is non-empty exactly when State is `translated`, the empty string otherwise — never
|
|
// absent, never null.
|
|
Target string `json:"target"`
|
|
State string `json:"state"`
|
|
Notes []wireNote `json:"notes"`
|
|
}
|
|
|
|
type wireUnitPage struct {
|
|
Revision int64 `json:"revision"`
|
|
NextCursor *string `json:"next_cursor"`
|
|
StructureVersion int `json:"structure_version"`
|
|
Units []wireUnit `json:"units"`
|
|
}
|
|
|
|
type wireNote struct {
|
|
ID string `json:"id"`
|
|
CreatedAt time.Time `json:"created_at"`
|
|
Severity string `json:"severity"`
|
|
Code string `json:"code"`
|
|
ChapterID string `json:"chapter_id"`
|
|
// UnitID is optional and for one reason only: a note is about a pair, or about a whole chapter.
|
|
UnitID *string `json:"unit_id,omitempty"`
|
|
}
|
|
|
|
type wireNotePage struct {
|
|
Revision int64 `json:"revision"`
|
|
NextCursor *string `json:"next_cursor"`
|
|
StructureVersion int `json:"structure_version"`
|
|
Notes []wireNote `json:"notes"`
|
|
}
|
|
|
|
type wireTerm struct {
|
|
ID string `json:"id"`
|
|
Src string `json:"src"`
|
|
Dst string `json:"dst"`
|
|
Kind *string `json:"kind"`
|
|
Status string `json:"status"`
|
|
Origin string `json:"origin"`
|
|
Sense string `json:"sense"`
|
|
// The window is in chapter NUMBERS, which are not keys: it lives in the coordinates of the
|
|
// current structure_version. null means "no boundary".
|
|
SinceChapter *int `json:"since_chapter"`
|
|
UntilChapter *int `json:"until_chapter"`
|
|
}
|
|
|
|
// wireBankPage carries the whole-bank aggregates on the FIRST page only — any response to a request
|
|
// with no cursor, a delta read included. They are `omitempty` for that reason and for no other:
|
|
// absence here means "does not apply to this page", one of the two places on this surface where it
|
|
// does (canon §BankPage).
|
|
type wireBankPage struct {
|
|
Revision int64 `json:"revision"`
|
|
NextCursor *string `json:"next_cursor"`
|
|
StructureVersion int `json:"structure_version"`
|
|
Total *int `json:"total,omitempty"`
|
|
Signed *int `json:"signed,omitempty"`
|
|
PendingDecisions *int `json:"pending_decisions,omitempty"`
|
|
Complete *bool `json:"complete,omitempty"`
|
|
Terms []wireTerm `json:"terms"`
|
|
}
|
|
|
|
func (h *v0) listChapters(w http.ResponseWriter, r *http.Request) {
|
|
user, ok := principal(w, r)
|
|
if !ok {
|
|
return
|
|
}
|
|
page, err := h.lib.ListChapters(r.Context(), user, r.PathValue("bookId"), h.pageLimit(r), r.URL.Query().Get("cursor"))
|
|
if err != nil {
|
|
h.fail(w, r, err)
|
|
return
|
|
}
|
|
out := wireChapterPage{
|
|
Revision: page.Revision, StructureVersion: page.StructureVersion,
|
|
Chapters: make([]wireChapter, 0, len(page.Chapters)),
|
|
}
|
|
if page.NextCursor != "" {
|
|
out.NextCursor = &page.NextCursor
|
|
}
|
|
for _, c := range page.Chapters {
|
|
out.Chapters = append(out.Chapters, projectChapter(c))
|
|
}
|
|
h.writeJSON(w, r, http.StatusOK, out)
|
|
}
|
|
|
|
// listUnits answers the pairs of ONE chapter.
|
|
//
|
|
// Per chapter and only per chapter: a book-wide pairs endpoint is never introduced, and the client's
|
|
// whole memory model stands on that (canon §listUnits). A chapter that existed and no longer does is
|
|
// `410`, so a client re-reads the tree rather than checking the address.
|
|
func (h *v0) listUnits(w http.ResponseWriter, r *http.Request) {
|
|
user, ok := principal(w, r)
|
|
if !ok {
|
|
return
|
|
}
|
|
page, err := h.lib.ListUnits(r.Context(), user, r.PathValue("bookId"), r.PathValue("chapterId"),
|
|
h.pageLimit(r), r.URL.Query().Get("cursor"))
|
|
if err != nil {
|
|
h.fail(w, r, err)
|
|
return
|
|
}
|
|
out := wireUnitPage{
|
|
Revision: page.Revision, StructureVersion: page.StructureVersion,
|
|
Units: make([]wireUnit, 0, len(page.Units)),
|
|
}
|
|
if page.NextCursor != "" {
|
|
out.NextCursor = &page.NextCursor
|
|
}
|
|
for _, u := range page.Units {
|
|
out.Units = append(out.Units, projectUnit(u))
|
|
}
|
|
h.writeJSON(w, r, http.StatusOK, out)
|
|
}
|
|
|
|
func (h *v0) listNotes(w http.ResponseWriter, r *http.Request) {
|
|
user, ok := principal(w, r)
|
|
if !ok {
|
|
return
|
|
}
|
|
after, ok := h.afterVersion(w, r)
|
|
if !ok {
|
|
return
|
|
}
|
|
page, err := h.lib.ListNotes(r.Context(), user, r.PathValue("bookId"), h.pageLimit(r),
|
|
r.URL.Query().Get("cursor"), after)
|
|
if err != nil {
|
|
h.fail(w, r, err)
|
|
return
|
|
}
|
|
out := wireNotePage{
|
|
Revision: page.Revision, StructureVersion: page.StructureVersion,
|
|
Notes: make([]wireNote, 0, len(page.Notes)),
|
|
}
|
|
if page.NextCursor != "" {
|
|
out.NextCursor = &page.NextCursor
|
|
}
|
|
unnamed := 0
|
|
for _, n := range page.Notes {
|
|
note := projectNote(n)
|
|
if note.Code == ingest.NoteCodeUnspecified {
|
|
unnamed++
|
|
}
|
|
out.Notes = append(out.Notes, note)
|
|
}
|
|
if unnamed > 0 {
|
|
// A flag reason the contract's map does not name. Loud, because the answer is a line in that
|
|
// map rather than a change here — and silent, it would look like a note the engine produced
|
|
// without a reason.
|
|
h.log.ErrorContext(r.Context(), "notes carry a flag reason this build cannot name; the contract's map needs a line",
|
|
"notes", unnamed)
|
|
}
|
|
h.writeJSON(w, r, http.StatusOK, out)
|
|
}
|
|
|
|
// listBank answers the memory bank, and it is also the STATE of a signing stop — informationally,
|
|
// never as a gate. Signing is ONE act over the whole bank: `resume` lifts the stop with the
|
|
// decisions as they stand, and no counter here decides whether continuing may be offered (D39.144).
|
|
func (h *v0) listBank(w http.ResponseWriter, r *http.Request) {
|
|
user, ok := principal(w, r)
|
|
if !ok {
|
|
return
|
|
}
|
|
after, ok := h.afterVersion(w, r)
|
|
if !ok {
|
|
return
|
|
}
|
|
page, err := h.lib.ListBank(r.Context(), user, r.PathValue("bookId"), h.pageLimit(r),
|
|
r.URL.Query().Get("cursor"), after)
|
|
if err != nil {
|
|
h.fail(w, r, err)
|
|
return
|
|
}
|
|
out := wireBankPage{
|
|
Revision: page.Revision, StructureVersion: page.StructureVersion,
|
|
Terms: make([]wireTerm, 0, len(page.Terms)),
|
|
}
|
|
if page.NextCursor != "" {
|
|
out.NextCursor = &page.NextCursor
|
|
}
|
|
if page.First {
|
|
c := page.Counts
|
|
out.Total, out.Signed = &c.Total, &c.Signed
|
|
out.PendingDecisions, out.Complete = &c.PendingDecisions, &c.Complete
|
|
}
|
|
for _, t := range page.Terms {
|
|
out.Terms = append(out.Terms, projectTerm(t))
|
|
}
|
|
h.writeJSON(w, r, http.StatusOK, out)
|
|
}
|
|
|
|
// ⚠ THE WRITE HALF OF THE BANK IS GONE, AND WHAT REPLACES IT IS NOT BUILT — for a future session.
|
|
//
|
|
// What stood here: `POST /books/{bookId}/bank/decisions`, taking a per-term verb `approve|decline`.
|
|
// D39.144 (16.08) abolished that model — the bank is signed as ONE act over the whole of it, and a
|
|
// per-term verb was never the unit of signing. What the same note DID keep per-term is an EDIT:
|
|
// correct a term's rendering, or add one, before the signing resume. That handle does not exist on
|
|
// any surface, here or in the canon, and this removal does not create it.
|
|
//
|
|
// For whoever builds it: `bank_decisions` already holds (term_id, dst), but not for free — `action`
|
|
// is NOT NULL with a check constraint on the abolished verb (migrations 00002/00016, both released),
|
|
// so an edit needs either a migration or a filler value. The engine's side is a file the platform
|
|
// does not write yet: `mined_delta` (a seed YAML, backend/internal/seed) carries corrected and added
|
|
// terms, and the engine reads it only if `book.yaml` declares the path — which is the ownership
|
|
// fork of unified backlog row 199(a), unratified. Signing itself needs nothing: it is `resume`.
|