Write each line to the OS without an fsync

[onechat] / log.go

package main

import (
        "context"
        "encoding/json"
        "errors"
        "fmt"
        "os"
        "path/filepath"
        "syscall"
        "time"
        "unicode/utf8"
)

// errLocked tells that another process owns the chat.
var errLocked = errors.New("another process owns the chat")

// kinds holds the kinds that a message can have.
var kinds = map[string]bool{
        "user":  true,
        "reply": true,
        "tool":  true,
        "echo":  true,
        "work":  true,
        "note":  true,
}

// Message is one entry of the chat log. ID is the permanent position of the
// message in the chat, from 0. Size is the UTF-8 byte length of Text. Date is
// the time of the write in RFC 3339 format.
type Message struct {
        ID   int    `json:"i"`
        Kind string `json:"kind"`
        Text string `json:"text"`
        Size int    `json:"size"`
        Date string `json:"date"`
}

// Log is the append-only message log of one chat. It writes one JSON line for
// each message to main/YYYY-MM-DD.jsonl, named for the local day of the write.
// It never edits or deletes a line. Each line goes to the operating system
// before Append returns, so a crash of the process loses no message. An
// exclusive lock on the lock file makes sure that only one process writes the
// log. After a failed write, the end of the file is not known, so the log
// refuses all writes until it is opened again. The caller serializes all calls.
type Log struct {
        clock    func() time.Time
        lock     *os.File
        journal  journal
        messages []Message
        failure  error
}

// openLog locks the chat in root and loads all of its messages. The clock gives
// the date of each new message.
func openLog(ctx context.Context, root string, clock func() time.Time) (*Log, error) {
        err := os.MkdirAll(filepath.Join(root, "main"), 0o700)
        if err != nil {
                return nil, fmt.Errorf("create message directory: %w", err)
        }

        lock, err := lockFile(filepath.Join(root, "lock"))
        if err != nil {
                return nil, err
        }

        l := &Log{
                clock: clock,
                lock:  lock,
                journal: journal{
                        dir: filepath.Join(root, "main"),
                },
        }

        err = l.load(ctx)
        if err != nil {
                return nil, errors.Join(fmt.Errorf("load message log: %w", err), l.Close())
        }

        return l, nil
}

func (l *Log) load(ctx context.Context) error {
        return readLines(ctx, l.journal.dir, func(message Message) error {
                if message.ID != len(l.messages) {
                        return fmt.Errorf("expected message %d, found %d", len(l.messages), message.ID)
                }

                err := validateMessage(message)
                if err != nil {
                        return fmt.Errorf("message %d: %w", message.ID, err)
                }

                l.messages = append(l.messages, message)

                return nil
        })
}

// Close releases the lock. The log refuses all calls after Close.
func (l *Log) Close() error {
        err := l.journal.Close()
        if l.lock != nil {
                err = errors.Join(err, l.lock.Close())
                l.lock = nil
        }

        return err
}

// Append writes a new message to the log and returns it with its ID, size, and
// date.
func (l *Log) Append(kind, text string) (Message, error) {
        if l.lock == nil {
                return Message{}, os.ErrClosed
        }

        if l.failure != nil {
                return Message{}, fmt.Errorf("log needs a reopen after a failed write: %w", l.failure)
        }

        now := l.clock()
        message := Message{
                ID:   len(l.messages),
                Kind: kind,
                Text: text,
                Size: len(text),
                Date: now.Format(time.RFC3339Nano),
        }

        err := validateMessage(message)
        if err != nil {
                return Message{}, err
        }

        line, err := json.Marshal(message)
        if err != nil {
                return Message{}, fmt.Errorf("encode message: %w", err)
        }

        err = l.journal.Write(now.Format(time.DateOnly), append(line, '\n'))
        if err != nil {
                l.failure = err
                return Message{}, fmt.Errorf("write message %d: %w", message.ID, err)
        }

        l.messages = append(l.messages, message)

        return message, nil
}

// Len returns the number of messages in the log.
func (l *Log) Len() int {
        return len(l.messages)
}

// Message returns the message with the given ID.
func (l *Log) Message(id int) Message {
        return l.messages[id]
}

// validateMessage makes sure that a message has a known kind, valid UTF-8 text,
// the size of its text, and a valid date.
func validateMessage(message Message) error {
        if !kinds[message.Kind] {
                return fmt.Errorf("unknown message kind %q", message.Kind)
        }

        if !utf8.ValidString(message.Text) {
                return errors.New("message text is not valid UTF-8")
        }

        if message.Size != len(message.Text) {
                return fmt.Errorf("message size %d is not the text size %d", message.Size, len(message.Text))
        }

        _, err := time.Parse(time.RFC3339Nano, message.Date)
        if err != nil {
                return fmt.Errorf("parse message date: %w", err)
        }

        return nil
}

// lockFile opens the file at path and takes an exclusive lock on it. The lock
// stays until the file closes or the process ends.
func lockFile(path string) (*os.File, error) {
        file, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600)
        if err != nil {
                return nil, fmt.Errorf("open lock file: %w", err)
        }

        err = syscall.Flock(int(file.Fd()), syscall.LOCK_EX|syscall.LOCK_NB)
        if errors.Is(err, syscall.EWOULDBLOCK) {
                err = errLocked
        }

        if err != nil {
                return nil, errors.Join(fmt.Errorf("lock chat: %w", err), file.Close())
        }

        return file, nil
}