321 lines
13 KiB
Go
321 lines
13 KiB
Go
// Package versioning implementiert VER-01: jede Änderung erzeugt eine
|
|
// neue Revision, Ausleihen (Check-out) sperrt ein Dokument für andere,
|
|
// Einchecken (Check-in) gibt es mit Kommentar frei. Alte Revisionen
|
|
// bleiben unverändert abrufbar — dieses Paket fügt ausschließlich neue
|
|
// file_revisions-Zeilen an, es ändert nie eine bestehende.
|
|
package versioning
|
|
|
|
import (
|
|
"bytes"
|
|
"context"
|
|
"crypto/sha256"
|
|
"encoding/hex"
|
|
"errors"
|
|
"fmt"
|
|
"io"
|
|
"time"
|
|
|
|
"github.com/jackc/pgx/v5"
|
|
"github.com/jackc/pgx/v5/pgxpool"
|
|
|
|
"gitea.perlbach24.de/scripte/nexarch/dms/internal/audittrail"
|
|
dmscrypto "gitea.perlbach24.de/scripte/nexarch/dms/internal/crypto"
|
|
"gitea.perlbach24.de/scripte/nexarch/dms/internal/storage"
|
|
)
|
|
|
|
// ErrAlreadyLocked wird von CheckOut geliefert, wenn ein anderer Nutzer
|
|
// das Dokument bereits mit einer noch aktiven Sperre ausgeliehen hat
|
|
// (Akzeptanzkriterium 2 / Pflichtprüfung 1: bei zwei gleichzeitigen
|
|
// Ausleihversuchen gewinnt nur einer).
|
|
var ErrAlreadyLocked = errors.New("versioning: dokument ist bereits ausgeliehen")
|
|
|
|
// ErrNotLockedByUser wird von CheckIn geliefert, wenn der aufrufende
|
|
// Nutzer das Dokument nicht (mehr) ausgeliehen hat.
|
|
var ErrNotLockedByUser = errors.New("versioning: dokument ist nicht von diesem nutzer ausgeliehen")
|
|
|
|
// ErrNotLocked wird von ForceUnlock geliefert, wenn gar keine Sperre
|
|
// besteht.
|
|
var ErrNotLocked = errors.New("versioning: dokument ist nicht ausgeliehen")
|
|
|
|
// DefaultLeaseDuration ist die Standard-Sperrfrist, nach der eine nicht
|
|
// verlängerte Sperre als verwaist gilt und automatisch wieder frei wird.
|
|
const DefaultLeaseDuration = 30 * time.Minute
|
|
|
|
// Lock beschreibt eine aktive Ausleihe.
|
|
type Lock struct {
|
|
DocumentID string
|
|
LockedBy string
|
|
LockedAt time.Time
|
|
LeaseUntil time.Time
|
|
}
|
|
|
|
// CheckOut leiht ein Dokument aus (Akzeptanzkriterium 2). Atomar über
|
|
// INSERT ... ON CONFLICT ... WHERE lease_until < now(): eine bestehende,
|
|
// noch aktive Sperre eines ANDEREN Nutzers verhindert das Ausleihen, eine
|
|
// bereits abgelaufene (verwaiste) Sperre wird automatisch übernommen
|
|
// (Akzeptanzkriterium/Pflichtprüfung 2) — kein separater Aufräum-Job
|
|
// nötig. Der Datenbank-Constraint entscheidet bei gleichzeitigen
|
|
// Versuchen atomar, wer gewinnt (Pflichtprüfung 1).
|
|
func CheckOut(ctx context.Context, pool *pgxpool.Pool, documentID, userID string, leaseDuration time.Duration) (Lock, error) {
|
|
if leaseDuration <= 0 {
|
|
leaseDuration = DefaultLeaseDuration
|
|
}
|
|
var l Lock
|
|
l.DocumentID = documentID
|
|
err := pool.QueryRow(ctx, `
|
|
INSERT INTO document_locks (document_id, locked_by, locked_at, lease_until)
|
|
VALUES ($1, $2, now(), now() + $3::interval)
|
|
ON CONFLICT (document_id) DO UPDATE
|
|
SET locked_by = EXCLUDED.locked_by, locked_at = EXCLUDED.locked_at, lease_until = EXCLUDED.lease_until
|
|
WHERE document_locks.lease_until < now()
|
|
RETURNING locked_by, locked_at, lease_until
|
|
`, documentID, userID, fmt.Sprintf("%d seconds", int(leaseDuration.Seconds()))).Scan(&l.LockedBy, &l.LockedAt, &l.LeaseUntil)
|
|
if errors.Is(err, pgx.ErrNoRows) {
|
|
// WHERE-Klausel griff nicht (aktive Fremdsperre) -> kein Zeilen-
|
|
// Update, kein RETURNING-Ergebnis. Das ist der Normalfall bei
|
|
// einem verlorenen Ausleihversuch, kein technischer Fehler.
|
|
return Lock{}, ErrAlreadyLocked
|
|
}
|
|
if err != nil {
|
|
return Lock{}, fmt.Errorf("versioning: ausleihen: %w", err)
|
|
}
|
|
return l, nil
|
|
}
|
|
|
|
// GetLock liefert die aktuelle Sperre eines Dokuments, falls vorhanden
|
|
// (auch eine bereits abgelaufene — der Aufrufer entscheidet, ob das für
|
|
// seinen Zweck relevant ist).
|
|
func GetLock(ctx context.Context, pool *pgxpool.Pool, documentID string) (*Lock, error) {
|
|
var l Lock
|
|
l.DocumentID = documentID
|
|
err := pool.QueryRow(ctx, `
|
|
SELECT locked_by, locked_at, lease_until FROM document_locks WHERE document_id = $1
|
|
`, documentID).Scan(&l.LockedBy, &l.LockedAt, &l.LeaseUntil)
|
|
if errors.Is(err, pgx.ErrNoRows) {
|
|
return nil, nil
|
|
}
|
|
if err != nil {
|
|
return nil, fmt.Errorf("versioning: sperre lesen: %w", err)
|
|
}
|
|
return &l, nil
|
|
}
|
|
|
|
// ForceUnlock hebt eine Sperre unabhängig vom Inhaber auf
|
|
// (Akzeptanzkriterium 3: Sperre ist durch Administratoren aufhebbar). Die
|
|
// eigentliche Rollenprüfung ("ist adminUserID tatsächlich Administrator")
|
|
// ist Sache der RBAC-Schicht vor diesem Aufruf (noch keine HTTP-Schicht
|
|
// für diese Kachel, siehe VER-05-Präzedenzfall) — dieses Paket kennt nur
|
|
// die Fach-Operation selbst.
|
|
func ForceUnlock(ctx context.Context, pool *pgxpool.Pool, documentID string) error {
|
|
tag, err := pool.Exec(ctx, `DELETE FROM document_locks WHERE document_id = $1`, documentID)
|
|
if err != nil {
|
|
return fmt.Errorf("versioning: sperre aufheben: %w", err)
|
|
}
|
|
if tag.RowsAffected() == 0 {
|
|
return ErrNotLocked
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Revision ist EINE unveränderliche Datei-Revision.
|
|
type Revision struct {
|
|
ID string
|
|
DocumentID string
|
|
RevisionNumber int
|
|
ChecksumSHA256 string
|
|
SizeBytes int64
|
|
MimeType string
|
|
Comment *string
|
|
CreatedBy string
|
|
CreatedAt time.Time
|
|
}
|
|
|
|
// CheckIn prüft, dass documentID tatsächlich von userID ausgeliehen ist
|
|
// (Akzeptanzkriterium 2), verschlüsselt und speichert plaintext als NEUE
|
|
// Revision (nie eine bestehende überschreibend, Akzeptanzkriterium 1) und
|
|
// gibt die Sperre danach frei. Scheitert ein Schritt, bleibt die Sperre
|
|
// bestehen — kein halb eingecheckter Zustand ohne erkennbaren Besitzer.
|
|
func CheckIn(
|
|
ctx context.Context, pool *pgxpool.Pool, storageSvc *storage.Service, cryptoSvc *dmscrypto.Service, tenantSlug string,
|
|
documentID, userID, comment, mimeType string, plaintext io.Reader,
|
|
) (Revision, error) {
|
|
r, err := checkIn(ctx, pool, storageSvc, cryptoSvc, tenantSlug, documentID, userID, comment, mimeType, plaintext)
|
|
if err != nil {
|
|
return Revision{}, err
|
|
}
|
|
if err := audittrail.Record(ctx, pool, userID, "revision_created", "document", documentID, map[string]any{
|
|
"revision_id": r.ID, "revision_number": r.RevisionNumber, "checksum_sha256": r.ChecksumSHA256,
|
|
}); err != nil {
|
|
return r, err
|
|
}
|
|
return r, nil
|
|
}
|
|
|
|
func checkIn(
|
|
ctx context.Context, pool *pgxpool.Pool, storageSvc *storage.Service, cryptoSvc *dmscrypto.Service, tenantSlug string,
|
|
documentID, userID, comment, mimeType string, plaintext io.Reader,
|
|
) (Revision, error) {
|
|
lock, err := GetLock(ctx, pool, documentID)
|
|
if err != nil {
|
|
return Revision{}, err
|
|
}
|
|
if lock == nil || lock.LockedBy != userID || lock.LeaseUntil.Before(time.Now()) {
|
|
return Revision{}, ErrNotLockedByUser
|
|
}
|
|
|
|
hasher := sha256.New()
|
|
tee := io.TeeReader(plaintext, hasher)
|
|
env, err := cryptoSvc.Seal(ctx, tenantSlug, tee)
|
|
if err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: verschluesseln: %w", err)
|
|
}
|
|
ciphertext, err := io.ReadAll(env.Ciphertext)
|
|
if err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: chiffretext lesen: %w", err)
|
|
}
|
|
checksumHex := hex.EncodeToString(hasher.Sum(nil))
|
|
|
|
tx, err := pool.Begin(ctx)
|
|
if err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: transaktion starten: %w", err)
|
|
}
|
|
defer func() { _ = tx.Rollback(ctx) }()
|
|
|
|
var nextNumber int
|
|
if err := tx.QueryRow(ctx, `
|
|
SELECT COALESCE(max(revision_number), 0) + 1 FROM file_revisions WHERE document_id = $1
|
|
`, documentID).Scan(&nextNumber); err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: naechste revisionsnummer ermitteln: %w", err)
|
|
}
|
|
|
|
var r Revision
|
|
r.DocumentID, r.RevisionNumber, r.ChecksumSHA256, r.SizeBytes, r.MimeType, r.CreatedBy = documentID, nextNumber, checksumHex, int64(len(ciphertext)), mimeType, userID
|
|
commentPtr := &comment
|
|
r.Comment = commentPtr
|
|
tempKey := storage.ObjectKey(documentID, "pending")
|
|
if err := tx.QueryRow(ctx, `
|
|
INSERT INTO file_revisions (document_id, revision_number, storage_key, checksum_sha256, size_bytes, mime_type, created_by, wrapped_dek, comment)
|
|
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
|
|
RETURNING id, created_at
|
|
`, documentID, nextNumber, tempKey, checksumHex, len(ciphertext), mimeType, userID, env.WrappedDEK, commentPtr).Scan(&r.ID, &r.CreatedAt); err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: revision anlegen: %w", err)
|
|
}
|
|
|
|
finalKey := storage.ObjectKey(documentID, r.ID)
|
|
if _, err := tx.Exec(ctx, `UPDATE file_revisions SET storage_key = $2 WHERE id = $1`, r.ID, finalKey); err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: storage-key aktualisieren: %w", err)
|
|
}
|
|
if _, err := tx.Exec(ctx, `UPDATE documents SET current_revision_id = $2, updated_at = now() WHERE id = $1`, documentID, r.ID); err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: aktuelle revision setzen: %w", err)
|
|
}
|
|
if _, err := tx.Exec(ctx, `DELETE FROM document_locks WHERE document_id = $1 AND locked_by = $2`, documentID, userID); err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: sperre freigeben: %w", err)
|
|
}
|
|
|
|
if _, err := storageSvc.Put(ctx, finalKey, bytes.NewReader(ciphertext), int64(len(ciphertext)), "application/octet-stream"); err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: objekt ablegen: %w", err)
|
|
}
|
|
|
|
if err := tx.Commit(ctx); err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: einchecken committen: %w", err)
|
|
}
|
|
return r, nil
|
|
}
|
|
|
|
// ListRevisions liefert ALLE Revisionen eines Dokuments, älteste zuerst —
|
|
// Akzeptanzkriterium 1 / Pflichtprüfung 3: alte Revisionen bleiben
|
|
// unverändert abrufbar. Nie nil.
|
|
func ListRevisions(ctx context.Context, pool *pgxpool.Pool, documentID string) ([]Revision, error) {
|
|
rows, err := pool.Query(ctx, `
|
|
SELECT id, document_id, revision_number, checksum_sha256, size_bytes, mime_type, comment, created_by, created_at
|
|
FROM file_revisions WHERE document_id = $1 ORDER BY revision_number ASC
|
|
`, documentID)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("versioning: revisionen abfragen: %w", err)
|
|
}
|
|
defer rows.Close()
|
|
|
|
revisions := []Revision{}
|
|
for rows.Next() {
|
|
var r Revision
|
|
if err := rows.Scan(&r.ID, &r.DocumentID, &r.RevisionNumber, &r.ChecksumSHA256, &r.SizeBytes, &r.MimeType, &r.Comment, &r.CreatedBy, &r.CreatedAt); err != nil {
|
|
return nil, fmt.Errorf("versioning: revisions-zeile lesen: %w", err)
|
|
}
|
|
revisions = append(revisions, r)
|
|
}
|
|
return revisions, rows.Err()
|
|
}
|
|
|
|
// ErrRevisionNotFound wird geliefert, wenn eine angefragte Revision nicht
|
|
// existiert (oder nicht zum angegebenen Dokument gehört).
|
|
var ErrRevisionNotFound = errors.New("versioning: revision nicht gefunden")
|
|
|
|
// GetRevisionContent lädt und entschlüsselt den Inhalt EINER bestimmten,
|
|
// beliebigen Revision (nicht nur der aktuellen) — Akzeptanzkriterium 3:
|
|
// jede Revision ist einzeln herunterladbar.
|
|
func GetRevisionContent(ctx context.Context, pool *pgxpool.Pool, storageSvc *storage.Service, cryptoSvc *dmscrypto.Service, tenantSlug, documentID, revisionID string) ([]byte, string, error) {
|
|
var storageKey, mimeType string
|
|
var wrappedDEK []byte
|
|
err := pool.QueryRow(ctx, `
|
|
SELECT storage_key, mime_type, wrapped_dek FROM file_revisions WHERE id = $1 AND document_id = $2
|
|
`, revisionID, documentID).Scan(&storageKey, &mimeType, &wrappedDEK)
|
|
if errors.Is(err, pgx.ErrNoRows) {
|
|
return nil, "", ErrRevisionNotFound
|
|
}
|
|
if err != nil {
|
|
return nil, "", fmt.Errorf("versioning: revision lesen: %w", err)
|
|
}
|
|
|
|
cipherReader, err := storageSvc.Get(ctx, storageKey)
|
|
if err != nil {
|
|
return nil, "", fmt.Errorf("versioning: original aus storage laden: %w", err)
|
|
}
|
|
defer func() { _ = cipherReader.Close() }()
|
|
plainReader, err := cryptoSvc.Open(ctx, tenantSlug, wrappedDEK, cipherReader)
|
|
if err != nil {
|
|
return nil, "", fmt.Errorf("versioning: original entschluesseln: %w", err)
|
|
}
|
|
plaintext, err := io.ReadAll(plainReader)
|
|
if err != nil {
|
|
return nil, "", fmt.Errorf("versioning: original lesen: %w", err)
|
|
}
|
|
return plaintext, mimeType, nil
|
|
}
|
|
|
|
// Restore stellt eine frühere Revision wieder her, indem ihr Inhalt als
|
|
// NEUE Revision eingecheckt wird (Akzeptanzkriterium 2: Wiederherstellung
|
|
// erzeugt eine neue Revision statt zu überschreiben — die Historie bleibt
|
|
// dadurch vollständig unverändert, Pflichtprüfung 1). Nutzt intern
|
|
// denselben CheckOut/CheckIn-Mechanismus wie ein regulärer Check-in, das
|
|
// Dokument darf daher nicht bereits von einem ANDEREN Nutzer ausgeliehen
|
|
// sein.
|
|
func Restore(
|
|
ctx context.Context, pool *pgxpool.Pool, storageSvc *storage.Service, cryptoSvc *dmscrypto.Service, tenantSlug string,
|
|
documentID, sourceRevisionID, userID string,
|
|
) (Revision, error) {
|
|
plaintext, mimeType, err := GetRevisionContent(ctx, pool, storageSvc, cryptoSvc, tenantSlug, documentID, sourceRevisionID)
|
|
if err != nil {
|
|
return Revision{}, err
|
|
}
|
|
|
|
var sourceNumber int
|
|
if err := pool.QueryRow(ctx, `SELECT revision_number FROM file_revisions WHERE id = $1`, sourceRevisionID).Scan(&sourceNumber); err != nil {
|
|
return Revision{}, fmt.Errorf("versioning: quell-revisionsnummer lesen: %w", err)
|
|
}
|
|
|
|
if _, err := CheckOut(ctx, pool, documentID, userID, DefaultLeaseDuration); err != nil {
|
|
return Revision{}, err
|
|
}
|
|
comment := fmt.Sprintf("Wiederhergestellt aus Revision %d", sourceNumber)
|
|
r, err := checkIn(ctx, pool, storageSvc, cryptoSvc, tenantSlug, documentID, userID, comment, mimeType, bytes.NewReader(plaintext))
|
|
if err != nil {
|
|
return Revision{}, err
|
|
}
|
|
if err := audittrail.Record(ctx, pool, userID, "revision_restored", "document", documentID, map[string]any{
|
|
"revision_id": r.ID, "revision_number": r.RevisionNumber, "source_revision_id": sourceRevisionID, "source_revision_number": sourceNumber,
|
|
}); err != nil {
|
|
return r, err
|
|
}
|
|
return r, nil
|
|
}
|