feat: revision-check material writes

- add jz_bm_materials.revision (default 1), read-only for GORM
- bump it only on content changes (models.ReviseMaterial)
- PUT /materials/{id} locks the row and answers 409 to a stale revision
- management answers carry revision and updated_at, the student detail
  carries revision
This commit is contained in:
Jakub Zych
2026-11-08 23:33:34 +01:00
parent 94ca257c6f
commit 237069c827
12 changed files with 611 additions and 17 deletions

View File

@@ -36,6 +36,11 @@ type Material struct {
AuthorUserID *uint `gorm:"column:author_user_id"`
CreatedAt time.Time `gorm:"column:created_at"`
UpdatedAt time.Time `gorm:"column:updated_at"`
// Revision goes up by one on every content change (ReviseMaterial).
// It is read-only for GORM, so a full-row Save of a stale in-memory
// model never writes an old revision back; only ReviseMaterial changes
// it.
Revision uint `gorm:"column:revision;->"`
Tags []Tag `gorm:"many2many:jz_bm_material_tag;joinForeignKey:material_id;joinReferences:tag_id"`
}

114
models/material_revision.go Normal file
View File

@@ -0,0 +1,114 @@
package models
import (
"encoding/json"
"slices"
"strings"
"gorm.io/gorm"
)
// A material's revision counts changes to its content only (D-03): the
// title, type, body, source, url, course, zjazd (meeting) and tag set.
// Visibility, shares, publication, the author and attached files never bump
// it, so a writer holding an older revision is refused only when the note
// itself changed since.
// materialFingerprint is the content of a material that its revision
// counts, in a fixed key order.
type materialFingerprint struct {
CourseID *uint `json:"course_id"`
MeetingID *uint `json:"meeting_id"`
Title string `json:"title"`
Type string `json:"type"`
Body *string `json:"body"`
Source *string `json:"source"`
URL *string `json:"url"`
Tags []string `json:"tags"`
}
// MaterialFingerprint is the comparable form of m's content with the given
// tag slugs: two materials with the same fingerprint have the same content
// under D-03. Blank optional text counts as null, as BeforeSave stores it,
// and the tag order does not matter. published_at, is_private, the author
// and the shares are not inputs.
func MaterialFingerprint(m Material, tagSlugs []string) string {
body, source, url := m.Body, m.Source, m.URL
blank(&body, &source, &url)
tags := slices.Clone(tagSlugs)
if tags == nil {
tags = []string{}
}
slices.Sort(tags)
raw, _ := json.Marshal(materialFingerprint{
CourseID: m.CourseID,
MeetingID: m.MeetingID,
Title: m.Title,
Type: m.Type,
Body: body,
Source: source,
URL: url,
Tags: tags,
})
return string(raw)
}
// materialState reads the content fingerprint and the revision of material
// id through tx; a missing row is gorm.ErrRecordNotFound.
func materialState(tx *gorm.DB, id uint) (string, uint, error) {
db := tx.Session(&gorm.Session{NewDB: true})
var m Material
res := db.Select("id", "course_id", "meeting_id", "title", "type", "body", "source", "url", "revision").
Where("id = ?", id).Limit(1).Find(&m)
if res.Error != nil {
return "", 0, res.Error
}
if res.RowsAffected == 0 {
return "", 0, gorm.ErrRecordNotFound
}
var slugs []string
err := db.Table(Tag{}.TableName()).
Joins("JOIN "+MaterialTag{}.TableName()+" ON "+MaterialTag{}.TableName()+".tag_id = "+Tag{}.TableName()+".id").
Where(MaterialTag{}.TableName()+".material_id = ?", id).
Pluck(Tag{}.TableName()+".slug", &slugs).Error
if err != nil {
return "", 0, err
}
for i := range slugs {
slugs[i] = strings.TrimSpace(slugs[i])
}
return MaterialFingerprint(m, slugs), m.Revision, nil
}
// MaterialContent reads the content fingerprint (MaterialFingerprint) of
// material id and its tags through tx. A writer takes it before a write and
// hands it to ReviseMaterial after; a missing row is gorm.ErrRecordNotFound.
func MaterialContent(tx *gorm.DB, id uint) (string, error) {
fp, _, err := materialState(tx, id)
return fp, err
}
// ReviseMaterial bumps the revision of material id by one when its content
// read through tx differs from before (a MaterialContent taken before the
// write), and answers the revision the row has then and whether it went
// up. Only content counts (D-03): a write that changed only visibility,
// shares, publication or files, or that sent identical content, keeps the
// revision. It is the only writer of the revision column, which GORM treats
// as read-only.
func ReviseMaterial(tx *gorm.DB, id uint, before string) (uint, bool, error) {
after, current, err := materialState(tx, id)
if err != nil {
return 0, false, err
}
if after == before {
return current, false, nil
}
var revision uint
err = tx.Session(&gorm.Session{NewDB: true}).
Raw("UPDATE jz_bm_materials SET revision = revision + 1 WHERE id = ? RETURNING revision", id).
Scan(&revision).Error
if err != nil {
return 0, false, err
}
return revision, true, nil
}

View File

@@ -0,0 +1,63 @@
package models_test
import (
"testing"
"time"
"git.golem15.com/jakub/sm-bm-plugin/models"
)
func TestMaterialFingerprint(t *testing.T) {
str := func(s string) *string { return &s }
id := func(n uint) *uint { return &n }
base := func() models.Material {
return models.Material{
ID: 7, CourseID: id(1), MeetingID: id(2), Title: "Definicje", Type: "notatka",
Body: str("# Robertson\n"), Source: str("wykład"), URL: str("https://example.test/a"),
}
}
tags := []string{"globalizacja", "teoria-2"}
want := models.MaterialFingerprint(base(), tags)
if got := models.MaterialFingerprint(base(), []string{"teoria-2", "globalizacja"}); got != want {
t.Errorf("tag order changed the fingerprint: %s != %s", got, want)
}
changes := map[string]func(m *models.Material, tags *[]string){
"title": func(m *models.Material, _ *[]string) { m.Title = "Inne" },
"type": func(m *models.Material, _ *[]string) { m.Type = "link" },
"body": func(m *models.Material, _ *[]string) { m.Body = str("# Robertson\n\nwięcej\n") },
"source": func(m *models.Material, _ *[]string) { m.Source = str("seminarium") },
"url": func(m *models.Material, _ *[]string) { m.URL = str("https://example.test/b") },
"course": func(m *models.Material, _ *[]string) { m.CourseID = id(3) },
"no course": func(m *models.Material, _ *[]string) { m.CourseID = nil },
"meeting": func(m *models.Material, _ *[]string) { m.MeetingID = id(4) },
"tag": func(_ *models.Material, tags *[]string) { *tags = append(*tags, "nowy") },
"untag": func(_ *models.Material, tags *[]string) { *tags = (*tags)[:1] },
}
for name, change := range changes {
m, ts := base(), append([]string(nil), tags...)
change(&m, &ts)
if got := models.MaterialFingerprint(m, ts); got == want {
t.Errorf("a %s change kept the fingerprint", name)
}
}
empty, null := base(), base()
empty.Body, empty.Source, empty.URL = str(""), str(" "), str("")
null.Body, null.Source, null.URL = nil, nil, nil
if models.MaterialFingerprint(empty, tags) != models.MaterialFingerprint(null, tags) {
t.Error("blank and nil optional text give different fingerprints")
}
if models.MaterialFingerprint(base(), nil) != models.MaterialFingerprint(base(), []string{}) {
t.Error("nil and empty tag lists give different fingerprints")
}
now := time.Now()
other := base()
other.ID, other.PublishedAt, other.IsPrivate, other.AuthorUserID = 8, &now, true, id(9)
other.UpdatedAt, other.Revision = now, 5
if got := models.MaterialFingerprint(other, tags); got != want {
t.Errorf("published_at, is_private, author, id or revision changed the fingerprint: %s != %s", got, want)
}
}