Repository Public
1// Package spool is the agent's bounded on-disk buffer of undelivered reports.2//3// One report = one file, named <seq>-<unix ts>.rpt, written to a temporary4// name, fsynced and renamed: a crash leaves either the complete report or5// nothing. Bounds (age and total size) are enforced by dropping the oldest6// reports first. Replay is oldest first.7package spool89import (10 "errors"11 "fmt"12 "os"13 "path/filepath"14 "sort"15 "strconv"16 "strings"17 "sync"18 "time"19)2021const (22 // DefaultMaxAge and DefaultMaxBytes are the bounds of the design brief.23 DefaultMaxAge = 6 * time.Hour24 DefaultMaxBytes = 20 << 2025 ext = ".rpt"26)2728// Entry is one buffered report.29type Entry struct {30 Seq int6431 TS time.Time32 Size int6433 name string34}3536// Spool is safe for concurrent use.37type Spool struct {38 dir string39 maxAge time.Duration40 maxBytes int644142 mu sync.Mutex43 entries []Entry // ascending seq44 bytes int6445 dropped int6446}4748// Open loads the spool directory, discarding leftovers of interrupted writes.49func Open(dir string, maxAge time.Duration, maxBytes int64) (*Spool, error) {50 if maxAge <= 0 {51 maxAge = DefaultMaxAge52 }53 if maxBytes <= 0 {54 maxBytes = DefaultMaxBytes55 }56 if err := os.MkdirAll(dir, 0o700); err != nil {57 return nil, err58 }59 s := &Spool{dir: dir, maxAge: maxAge, maxBytes: maxBytes}60 des, err := os.ReadDir(dir)61 if err != nil {62 return nil, err63 }64 for _, de := range des {65 name := de.Name()66 if strings.HasPrefix(name, ".tmp-") {67 os.Remove(filepath.Join(dir, name)) // interrupted write68 continue69 }70 e, ok := parseName(name)71 if !ok {72 continue73 }74 info, err := de.Info()75 if err != nil || info.Size() == 0 {76 os.Remove(filepath.Join(dir, name))77 continue78 }79 e.Size = info.Size()80 s.entries = append(s.entries, e)81 s.bytes += e.Size82 }83 sort.Slice(s.entries, func(i, j int) bool { return s.entries[i].Seq < s.entries[j].Seq })84 return s, nil85}8687func parseName(name string) (Entry, bool) {88 if !strings.HasSuffix(name, ext) {89 return Entry{}, false90 }91 parts := strings.SplitN(strings.TrimSuffix(name, ext), "-", 2)92 if len(parts) != 2 {93 return Entry{}, false94 }95 seq, err1 := strconv.ParseInt(parts[0], 10, 64)96 ts, err2 := strconv.ParseInt(parts[1], 10, 64)97 if err1 != nil || err2 != nil || seq <= 0 {98 return Entry{}, false99 }100 return Entry{Seq: seq, TS: time.Unix(ts, 0), name: name}, true101}102103// Put durably appends a report, then enforces the bounds.104func (s *Spool) Put(seq int64, ts time.Time, data []byte, now time.Time) error {105 if len(data) == 0 {106 return errors.New("spool: empty report")107 }108 if int64(len(data)) > s.maxBytes {109 return errors.New("spool: report larger than the whole spool")110 }111 name := fmt.Sprintf("%020d-%d%s", seq, ts.Unix(), ext)112 f, err := os.CreateTemp(s.dir, ".tmp-*")113 if err != nil {114 return err115 }116 tmp := f.Name()117 cleanup := func() { f.Close(); os.Remove(tmp) }118 if err := f.Chmod(0o600); err != nil {119 cleanup()120 return err121 }122 if _, err := f.Write(data); err != nil {123 cleanup()124 return err125 }126 if err := f.Sync(); err != nil {127 cleanup()128 return err129 }130 if err := f.Close(); err != nil {131 os.Remove(tmp)132 return err133 }134 if err := os.Rename(tmp, filepath.Join(s.dir, name)); err != nil {135 os.Remove(tmp)136 return err137 }138 if d, err := os.Open(s.dir); err == nil {139 d.Sync()140 d.Close()141 }142 s.mu.Lock()143 e := Entry{Seq: seq, TS: ts, Size: int64(len(data)), name: name}144 i := sort.Search(len(s.entries), func(i int) bool { return s.entries[i].Seq >= seq })145 if i < len(s.entries) && s.entries[i].Seq == seq {146 s.bytes += e.Size - s.entries[i].Size147 s.entries[i] = e148 } else {149 s.entries = append(s.entries, Entry{})150 copy(s.entries[i+1:], s.entries[i:])151 s.entries[i] = e152 s.bytes += e.Size153 }154 s.enforceLocked(now)155 s.mu.Unlock()156 return nil157}158159// enforceLocked drops the oldest reports beyond the age or size bound.160func (s *Spool) enforceLocked(now time.Time) {161 cut := now.Add(-s.maxAge)162 n := 0163 for n < len(s.entries) && (s.entries[n].TS.Before(cut) || s.bytes > s.maxBytes) {164 os.Remove(filepath.Join(s.dir, s.entries[n].name))165 s.bytes -= s.entries[n].Size166 s.dropped++167 n++168 }169 if n > 0 {170 s.entries = append(s.entries[:0], s.entries[n:]...)171 }172}173174// Enforce applies the bounds without adding a report (reports age while offline).175func (s *Spool) Enforce(now time.Time) {176 s.mu.Lock()177 s.enforceLocked(now)178 s.mu.Unlock()179}180181// ErrEmpty is returned by Oldest when nothing is buffered.182var ErrEmpty = errors.New("spool: empty")183184// Oldest returns the oldest buffered report without removing it. An185// unreadable file is discarded and the next one is tried.186func (s *Spool) Oldest() (Entry, []byte, error) {187 for {188 s.mu.Lock()189 if len(s.entries) == 0 {190 s.mu.Unlock()191 return Entry{}, nil, ErrEmpty192 }193 e := s.entries[0]194 s.mu.Unlock()195 data, err := os.ReadFile(filepath.Join(s.dir, e.name))196 if err == nil && len(data) > 0 {197 return e, data, nil198 }199 s.Remove(e.Seq)200 }201}202203// Remove deletes a delivered (or permanently rejected) report.204func (s *Spool) Remove(seq int64) {205 s.mu.Lock()206 defer s.mu.Unlock()207 i := sort.Search(len(s.entries), func(i int) bool { return s.entries[i].Seq >= seq })208 if i >= len(s.entries) || s.entries[i].Seq != seq {209 return210 }211 os.Remove(filepath.Join(s.dir, s.entries[i].name))212 s.bytes -= s.entries[i].Size213 s.entries = append(s.entries[:i], s.entries[i+1:]...)214}215216// Stats returns the number of buffered reports, their size and how many217// were dropped by the bounds since Open.218func (s *Spool) Stats() (count int, bytes int64, dropped int64) {219 s.mu.Lock()220 defer s.mu.Unlock()221 return len(s.entries), s.bytes, s.dropped222}223