pansy/internal/service/journal.go

package service

import (
	"context"
	"strings"

	"gitea.stevedudenhoeffer.com/steve/pansy/internal/domain"
	"gitea.stevedudenhoeffer.com/steve/pansy/internal/store"
)

// The grow journal (#52): what happened, and when. Distinct from the mutable
// `notes` on a garden/object/plant, which says what the thing IS — a new note
// overwrites the old one, while entries accumulate across a season.
//
// Deliberately NOT wired into the revision history (#48). Entries are already
// append-shaped and individually versioned, and undoing a note is just deleting
// it; running them through change sets would add a layer that buys nothing.

const (
	maxJournalBodyLen      = 10_000
	maxJournalPageSize     = 200
	defaultJournalPageSize = 50
)

// JournalInput is the payload for writing an entry. ObjectID/PlantingID are
// optional and narrow the target; ObservedAt defaults to today.
type JournalInput struct {
	ObjectID   *int64
	PlantingID *int64
	Body       string
	ObservedAt *string
}

// JournalPatch is a partial update. Only the text and the date it describes are
// editable — see UpdateJournalEntry.
type JournalPatch struct {
	Body       *string
	ObservedAt *string
}

// JournalQuery narrows a garden's journal for reading.
type JournalQuery struct {
	ObjectID   *int64
	PlantingID *int64
	From       *string
	To         *string
	Limit      int
	Offset     int
}

// ListJournal returns a garden's entries, most recently observed first, for an
// actor who can at least view the garden.
func (s *Service) ListJournal(ctx context.Context, actorID, gardenID int64, q JournalQuery) ([]domain.JournalEntry, bool, error) {
	if _, err := s.requireGardenRole(ctx, actorID, gardenID, roleViewer); err != nil {
		return nil, false, err
	}
	if !validDatePtr(q.From) || !validDatePtr(q.To) {
		return nil, false, domain.ErrInvalidInput
	}
	limit := q.Limit
	if limit <= 0 {
		limit = defaultJournalPageSize
	}
	if limit > maxJournalPageSize {
		limit = maxJournalPageSize
	}
	offset := q.Offset
	if offset < 0 {
		offset = 0
	}
	// One row past the page answers hasMore without a second COUNT (same shape as
	// GardenHistory).
	entries, err := s.store.ListJournalEntries(ctx, gardenID, store.JournalFilter{
		ObjectID: q.ObjectID, PlantingID: q.PlantingID, From: q.From, To: q.To,
		Limit: limit + 1, Offset: offset,
	})
	if err != nil {
		return nil, false, err
	}
	if len(entries) > limit {
		return entries[:limit], true, nil
	}
	return entries, false, nil
}

// CreateJournalEntry writes an entry against a garden the actor can edit.
//
// An entry may target the garden, one of its beds, or one plop in it — and the
// target is checked to actually belong to this garden. Without that, a valid
// object id from someone else's garden would be accepted and then leak through
// the list read, since the garden anchors the permission check.
func (s *Service) CreateJournalEntry(ctx context.Context, actorID, gardenID int64, in JournalInput) (*domain.JournalEntry, error) {
	if _, err := s.requireGardenRole(ctx, actorID, gardenID, roleEditor); err != nil {
		return nil, err
	}
	if err := s.checkJournalTarget(ctx, gardenID, in.ObjectID, in.PlantingID); err != nil {
		return nil, err
	}

	e := &domain.JournalEntry{
		GardenID:   gardenID,
		ObjectID:   in.ObjectID,
		PlantingID: in.PlantingID,
		AuthorID:   actorID,
		Body:       strings.TrimSpace(in.Body),
	}
	if in.ObservedAt != nil {
		e.ObservedAt = *in.ObservedAt
	} else {
		e.ObservedAt = s.now().UTC().Format(dateLayout)
	}
	if err := finalizeJournalEntry(e); err != nil {
		return nil, err
	}
	return s.store.CreateJournalEntry(ctx, e)
}

// checkJournalTarget verifies that an object/planting an entry points at really
// lives in this garden.
func (s *Service) checkJournalTarget(ctx context.Context, gardenID int64, objectID, plantingID *int64) error {
	if objectID != nil {
		o, err := s.store.GetObject(ctx, *objectID)
		if err != nil || o.GardenID != gardenID {
			return domain.ErrInvalidInput
		}
	}
	if plantingID != nil {
		pl, err := s.store.GetPlanting(ctx, *plantingID)
		if err != nil {
			return domain.ErrInvalidInput
		}
		o, err := s.store.GetObject(ctx, pl.ObjectID)
		if err != nil || o.GardenID != gardenID {
			return domain.ErrInvalidInput
		}
		// A plop-level entry that also names an object must name the RIGHT one,
		// or the two filters would disagree about which entries are about what.
		if objectID != nil && *objectID != pl.ObjectID {
			return domain.ErrInvalidInput
		}
	}
	return nil
}

// journalEntryForWrite loads an entry and enforces who may change it: the author
// may edit their own, and the garden's OWNER may delete any — the same shape as
// sharing, where the owner is the backstop for content in their garden. A
// non-editor of the garden can't reach it at all, and an entry in a garden the
// actor can't see is ErrNotFound (existence masked, as everywhere else).
func (s *Service) journalEntryForWrite(ctx context.Context, actorID, entryID int64, ownerMayAct bool) (*domain.JournalEntry, error) {
	e, err := s.store.GetJournalEntry(ctx, entryID)
	if err != nil {
		return nil, err // ErrNotFound
	}
	g, err := s.requireGardenRole(ctx, actorID, e.GardenID, roleEditor)
	if err != nil {
		return nil, err
	}
	if e.AuthorID == actorID {
		return e, nil
	}
	if ownerMayAct && g.OwnerID == actorID {
		return e, nil
	}
	// Visible (they can edit this garden) but not theirs to change.
	return nil, domain.ErrForbidden
}

// UpdateJournalEntry edits the text or the observed date of the actor's OWN
// entry. Deliberately author-only, including for the garden owner: rewriting
// somebody else's observation under their name is a different thing from
// removing it.
func (s *Service) UpdateJournalEntry(ctx context.Context, actorID, entryID int64, patch JournalPatch, version int64) (*domain.JournalEntry, error) {
	e, err := s.journalEntryForWrite(ctx, actorID, entryID, false)
	if err != nil {
		return nil, err
	}
	if patch.Body != nil {
		e.Body = strings.TrimSpace(*patch.Body)
	}
	if patch.ObservedAt != nil {
		e.ObservedAt = *patch.ObservedAt
	}
	if err := finalizeJournalEntry(e); err != nil {
		return nil, err
	}
	e.Version = version
	return s.store.UpdateJournalEntry(ctx, e)
}

// DeleteJournalEntry removes an entry. The author may delete their own; the
// garden's owner may delete any entry in their garden.
func (s *Service) DeleteJournalEntry(ctx context.Context, actorID, entryID int64) error {
	e, err := s.journalEntryForWrite(ctx, actorID, entryID, true)
	if err != nil {
		return err
	}
	return s.store.DeleteJournalEntry(ctx, e.ID)
}

// finalizeJournalEntry validates a built/merged entry. Shared by create and
// update so both enforce the same invariants.
func finalizeJournalEntry(e *domain.JournalEntry) error {
	if e.Body == "" || len(e.Body) > maxJournalBodyLen {
		return domain.ErrInvalidInput
	}
	if !validDatePtr(&e.ObservedAt) {
		return domain.ErrInvalidInput
	}
	return nil
}