Refactor architecture into eight components and consolidate reliability work
Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
This commit is contained in:
1 parent
9dd425f765
commit
d5d21b7841
302 files changed
+20037
-3492
No files matched your search
@@ -0,0 +1,39 @@
|
||||
package seheweit
|
||||
|
||||
import "time"
|
||||
|
||||
const (
|
||||
ResourceEventID = "builtin.resource.sample"
|
||||
ResourceEventType = "resource.sample"
|
||||
RetentionDays = 7
|
||||
MaxHistoryPoints = 361
|
||||
)
|
||||
|
||||
// HistoryWindow describes the existing inclusive, epoch-aligned sample query.
|
||||
// Persistence chooses the most recently inserted sample in each bucket, not an
|
||||
// average, a peak or necessarily the largest timestamp in out-of-order data.
|
||||
type HistoryWindow struct {
|
||||
FromMS int64
|
||||
ToMS int64
|
||||
BucketMS int64
|
||||
}
|
||||
|
||||
func Window(hours int, now time.Time) HistoryWindow {
|
||||
if hours < 1 {
|
||||
hours = 1
|
||||
}
|
||||
if hours > RetentionDays*24 {
|
||||
hours = RetentionDays * 24
|
||||
}
|
||||
span := int64(time.Duration(hours) * time.Hour / time.Millisecond)
|
||||
bucket := span / (MaxHistoryPoints - 1)
|
||||
if bucket < int64(time.Minute/time.Millisecond) {
|
||||
bucket = int64(time.Minute / time.Millisecond)
|
||||
}
|
||||
return HistoryWindow{FromMS: now.UnixMilli() - span, ToMS: now.UnixMilli(), BucketMS: bucket}
|
||||
}
|
||||
|
||||
// RetentionCutoff is inclusive: only samples strictly older are expired.
|
||||
func RetentionCutoff(atMS int64) int64 {
|
||||
return atMS - int64(RetentionDays*24*time.Hour/time.Millisecond)
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
package seheweit
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestHistoryWindow(t *testing.T) {
|
||||
now := time.Date(2026, 11, 1, 12, 34, 56, 0, time.UTC)
|
||||
for _, tc := range []struct {
|
||||
hours, wantHours int
|
||||
bucket int64
|
||||
}{
|
||||
{-1, 1, 60000}, {0, 1, 60000}, {1, 1, 60000}, {24, 24, 240000}, {168, 168, 1680000}, {999, 168, 1680000},
|
||||
} {
|
||||
got := Window(tc.hours, now)
|
||||
if got.ToMS != now.UnixMilli() || got.FromMS != now.Add(-time.Duration(tc.wantHours)*time.Hour).UnixMilli() || got.BucketMS != tc.bucket {
|
||||
t.Fatalf("hours=%d %+v", tc.hours, got)
|
||||
}
|
||||
buckets := got.ToMS/got.BucketMS - got.FromMS/got.BucketMS + 1
|
||||
if buckets > MaxHistoryPoints {
|
||||
t.Fatalf("too many buckets: %d", buckets)
|
||||
}
|
||||
}
|
||||
if RetentionCutoff(now.UnixMilli()) != now.Add(-7*24*time.Hour).UnixMilli() {
|
||||
t.Fatal("retention changed")
|
||||
}
|
||||
if ResourceEventID != "builtin.resource.sample" || ResourceEventType != "resource.sample" {
|
||||
t.Fatal("persisted identifiers changed")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,177 @@
|
||||
// Package seheweit collects instance observations without controlling the
|
||||
// observed workload. Authorization, queue execution and persistence belong to
|
||||
// its callers. It does not inspect document contents or contact remote services.
|
||||
package seheweit
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"io"
|
||||
"math"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"runtime"
|
||||
"strconv"
|
||||
"strings"
|
||||
"syscall"
|
||||
"time"
|
||||
|
||||
"github.com/google/uuid"
|
||||
)
|
||||
|
||||
// Identity survives multiple collectors, but not a process restart/PID reuse.
|
||||
var processID = uuid.NewString()
|
||||
|
||||
type ProcessIO struct {
|
||||
Scope string `json:"scope"`
|
||||
Available bool `json:"available"`
|
||||
ProcessID string `json:"process_id"`
|
||||
ReadBytes uint64 `json:"read_bytes"`
|
||||
WriteBytes uint64 `json:"write_bytes"`
|
||||
}
|
||||
|
||||
type CPU struct {
|
||||
LogicalCPUs int `json:"logical_cpus"`
|
||||
LoadAverage string `json:"load_average"`
|
||||
}
|
||||
|
||||
type Memory struct {
|
||||
HeapBytes uint64 `json:"heap_bytes"`
|
||||
GoSystemBytes uint64 `json:"go_system_bytes"`
|
||||
GCCycles uint32 `json:"gc_cycles"`
|
||||
Goroutines int `json:"goroutines"`
|
||||
}
|
||||
|
||||
type Storage struct {
|
||||
Path string `json:"path"`
|
||||
TotalBytes uint64 `json:"total_bytes"`
|
||||
UsedBytes uint64 `json:"used_bytes"`
|
||||
AvailableBytes uint64 `json:"available_bytes"`
|
||||
}
|
||||
|
||||
// Queue contains observations supplied by the application, not execution hooks.
|
||||
type Queue struct {
|
||||
Stats QueueStats `json:"stats"`
|
||||
ActiveWorkers int64 `json:"active_workers"`
|
||||
Paused bool `json:"paused"`
|
||||
}
|
||||
|
||||
type QueueStats struct {
|
||||
Queued int `json:"queued"`
|
||||
Running int `json:"running"`
|
||||
}
|
||||
|
||||
// Snapshot preserves the resource API and history JSON field names.
|
||||
// Sources are sampled sequentially, not in an atomic cross-source transaction.
|
||||
type Snapshot struct {
|
||||
TimestampMS int64 `json:"timestamp_ms"`
|
||||
IO ProcessIO `json:"io"`
|
||||
CPU CPU `json:"cpu"`
|
||||
Memory Memory `json:"memory"`
|
||||
Storage Storage `json:"storage"`
|
||||
Queue Queue `json:"queue"`
|
||||
}
|
||||
|
||||
type sources struct {
|
||||
now func() time.Time
|
||||
readFile func(string) ([]byte, error)
|
||||
statfs func(string, *syscall.Statfs_t) error
|
||||
memory func(*runtime.MemStats)
|
||||
cpus func() int
|
||||
goroutines func() int
|
||||
}
|
||||
|
||||
// Collect reads Go runtime counters, two bounded proc files and Statfs on the
|
||||
// configured document root. No directory walk, shell or background loop.
|
||||
func Collect(root string, queue Queue) Snapshot {
|
||||
return collect(root, queue, sources{
|
||||
now: time.Now, readFile: readProcFile, statfs: syscall.Statfs,
|
||||
memory: runtime.ReadMemStats, cpus: runtime.NumCPU, goroutines: runtime.NumGoroutine,
|
||||
})
|
||||
}
|
||||
|
||||
func collect(root string, queue Queue, src sources) Snapshot {
|
||||
var mem runtime.MemStats
|
||||
src.memory(&mem)
|
||||
if root == "" {
|
||||
root = "."
|
||||
}
|
||||
if absolute, err := filepath.Abs(root); err == nil {
|
||||
root = absolute
|
||||
}
|
||||
storage := Storage{Path: root}
|
||||
var fs syscall.Statfs_t
|
||||
if err := src.statfs(root, &fs); err == nil {
|
||||
storage = storageCounters(root, fs.Blocks, fs.Bavail, fs.Bsize)
|
||||
}
|
||||
loadAverage := ""
|
||||
if data, err := src.readFile("/proc/loadavg"); err == nil {
|
||||
fields := strings.Fields(string(data))
|
||||
if len(fields) >= 3 {
|
||||
loadAverage = strings.Join(fields[:3], " ")
|
||||
}
|
||||
}
|
||||
var ioData []byte
|
||||
if data, err := src.readFile("/proc/self/io"); err == nil {
|
||||
ioData = data
|
||||
}
|
||||
return Snapshot{
|
||||
TimestampMS: src.now().UnixMilli(), IO: ParseProcessIO(string(ioData)),
|
||||
CPU: CPU{LogicalCPUs: src.cpus(), LoadAverage: loadAverage},
|
||||
Memory: Memory{HeapBytes: mem.HeapAlloc, GoSystemBytes: mem.Sys, GCCycles: mem.NumGC, Goroutines: src.goroutines()},
|
||||
Storage: storage, Queue: queue,
|
||||
}
|
||||
}
|
||||
|
||||
func storageCounters(path string, blocks, available uint64, blockSize int64) Storage {
|
||||
result := Storage{Path: path}
|
||||
// Preserve the existing zero fallback rather than wrapping unsigned values.
|
||||
if blockSize <= 0 || available > blocks || blocks > math.MaxUint64/uint64(blockSize) {
|
||||
return result
|
||||
}
|
||||
result.TotalBytes = blocks * uint64(blockSize)
|
||||
result.AvailableBytes = available * uint64(blockSize)
|
||||
result.UsedBytes = result.TotalBytes - result.AvailableBytes
|
||||
return result
|
||||
}
|
||||
|
||||
const maxProcBytes = 16 << 10
|
||||
|
||||
func readProcFile(path string) ([]byte, error) {
|
||||
f, err := os.Open(path)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer f.Close()
|
||||
data, err := io.ReadAll(io.LimitReader(f, maxProcBytes+1))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if len(data) > maxProcBytes {
|
||||
return nil, errors.New("resource counter file too large")
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
// ParseProcessIO uses actual storage bytes, not rchar/wchar (syscall traffic).
|
||||
// Partial, missing or invalid counters are unavailable, not a zero I/O rate.
|
||||
func ParseProcessIO(data string) ProcessIO {
|
||||
result := ProcessIO{Scope: "process", ProcessID: processID}
|
||||
read, write := false, false
|
||||
for _, line := range strings.Split(data, "\n") {
|
||||
fields := strings.Fields(line)
|
||||
if len(fields) != 2 || (fields[0] != "read_bytes:" && fields[0] != "write_bytes:") {
|
||||
continue
|
||||
}
|
||||
value, err := strconv.ParseUint(fields[1], 10, 64)
|
||||
if err != nil {
|
||||
return result
|
||||
}
|
||||
if fields[0] == "read_bytes:" {
|
||||
result.ReadBytes, read = value, true
|
||||
} else {
|
||||
result.WriteBytes, write = value, true
|
||||
}
|
||||
}
|
||||
result.Available = read && write
|
||||
return result
|
||||
}
|
||||
@@ -0,0 +1,171 @@
|
||||
package seheweit
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"math"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"reflect"
|
||||
"runtime"
|
||||
"strings"
|
||||
"syscall"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func fixtureSources(t *testing.T) sources {
|
||||
t.Helper()
|
||||
return sources{
|
||||
now: func() time.Time { return time.UnixMilli(123456789) },
|
||||
readFile: func(path string) ([]byte, error) {
|
||||
switch path {
|
||||
case "/proc/loadavg":
|
||||
return []byte("0.01 0.20 3.00 1/99 1\n"), nil
|
||||
case "/proc/self/io":
|
||||
return []byte("rchar: 999\nread_bytes: 10\nwrite_bytes: 20\n"), nil
|
||||
default:
|
||||
t.Fatalf("unexpected file read: %s", path)
|
||||
return nil, nil
|
||||
}
|
||||
},
|
||||
statfs: func(path string, fs *syscall.Statfs_t) error {
|
||||
if !filepath.IsAbs(path) {
|
||||
t.Fatalf("relative root %q", path)
|
||||
}
|
||||
fs.Blocks, fs.Bavail, fs.Bsize = 100, 30, 4096
|
||||
return nil
|
||||
},
|
||||
memory: func(m *runtime.MemStats) { m.HeapAlloc, m.Sys, m.NumGC = 1024, 4096, 9 },
|
||||
cpus: func() int { return 8 }, goroutines: func() int { return 17 },
|
||||
}
|
||||
}
|
||||
|
||||
func TestSnapshotWireCompatibility(t *testing.T) {
|
||||
queue := Queue{Stats: QueueStats{Queued: 2, Running: 1}, ActiveWorkers: 1, Paused: true}
|
||||
snapshot := collect(t.TempDir(), queue, fixtureSources(t))
|
||||
data, err := json.Marshal(snapshot)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
// Exact pre-extraction wire shape, including zeros/false (no omitempty).
|
||||
want := map[string]any{
|
||||
"timestamp_ms": int64(123456789),
|
||||
"io": map[string]any{"scope": "process", "available": true, "process_id": processID, "read_bytes": 10, "write_bytes": 20},
|
||||
"cpu": map[string]any{"logical_cpus": 8, "load_average": "0.01 0.20 3.00"},
|
||||
"memory": map[string]any{"heap_bytes": 1024, "go_system_bytes": 4096, "gc_cycles": 9, "goroutines": 17},
|
||||
"storage": map[string]any{"path": snapshot.Storage.Path, "total_bytes": 409600, "used_bytes": 286720, "available_bytes": 122880},
|
||||
"queue": map[string]any{"stats": map[string]int{"queued": 2, "running": 1}, "active_workers": 1, "paused": true},
|
||||
}
|
||||
wantData, _ := json.Marshal(want)
|
||||
var gotJSON, wantJSON any
|
||||
if err := json.Unmarshal(data, &gotJSON); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := json.Unmarshal(wantData, &wantJSON); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !reflect.DeepEqual(gotJSON, wantJSON) {
|
||||
t.Fatalf("wire changed: %s != %s", data, wantData)
|
||||
}
|
||||
zero, _ := json.Marshal(Snapshot{})
|
||||
if strings.Contains(string(zero), "null") || !strings.Contains(string(zero), `"paused":false`) {
|
||||
t.Fatalf("zero shape %s", zero)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCollectionFailureAndIsolation(t *testing.T) {
|
||||
src := fixtureSources(t)
|
||||
src.readFile = func(string) ([]byte, error) {
|
||||
return []byte("read_bytes: 5\nwrite_bytes: 6\n"), errors.New("unavailable")
|
||||
}
|
||||
src.statfs = func(_ string, fs *syscall.Statfs_t) error {
|
||||
fs.Blocks, fs.Bavail, fs.Bsize = 100, 20, 4096
|
||||
return errors.New("unavailable")
|
||||
}
|
||||
got := collect("", Queue{}, src)
|
||||
if !filepath.IsAbs(got.Storage.Path) || got.Storage.TotalBytes != 0 || got.IO.Available || got.IO.ReadBytes != 0 || got.CPU.LoadAverage != "" {
|
||||
t.Fatalf("failed source leaked partial values: %+v", got)
|
||||
}
|
||||
if got.Memory.HeapBytes != 1024 || got.CPU.LogicalCPUs != 8 || got.IO.ProcessID == "" {
|
||||
t.Fatalf("independent sources lost: %+v", got)
|
||||
}
|
||||
// Each call has independent values; the process identity alone is shared.
|
||||
for i := 0; i < 16; i++ {
|
||||
t.Run("parallel", func(t *testing.T) {
|
||||
t.Parallel()
|
||||
other := collect("", Queue{}, fixtureSources(t))
|
||||
if other.IO.ProcessID != got.IO.ProcessID || other.Storage.TotalBytes != 409600 {
|
||||
t.Fatalf("identity/isolation %+v", other)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestStorageInvalidCounters(t *testing.T) {
|
||||
for _, tc := range []struct {
|
||||
blocks, available uint64
|
||||
size int64
|
||||
}{
|
||||
{10, 11, 4096}, {10, 1, -1}, {10, 1, 0}, {math.MaxUint64, 1, 4096},
|
||||
} {
|
||||
if got := storageCounters("/root", tc.blocks, tc.available, tc.size); got != (Storage{Path: "/root"}) {
|
||||
t.Fatalf("invalid storage wrapped: %+v", got)
|
||||
}
|
||||
}
|
||||
if got := storageCounters("/root", math.MaxUint64, 0, 1); got.UsedBytes != math.MaxUint64 {
|
||||
t.Fatalf("valid boundary %+v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestProcessIOParser(t *testing.T) {
|
||||
for _, tc := range []struct {
|
||||
name, text string
|
||||
available bool
|
||||
read, write uint64
|
||||
}{
|
||||
{"valid", "read_bytes: 12\nwrite_bytes: 34\nrchar: 999\ncancelled_write_bytes: 99", true, 12, 34},
|
||||
{"zero", "read_bytes: 0\nwrite_bytes: 0", true, 0, 0},
|
||||
{"empty", "", false, 0, 0},
|
||||
{"partial", "read_bytes: 12", false, 12, 0},
|
||||
{"negative", "read_bytes: -1\nwrite_bytes: 34", false, 0, 0},
|
||||
{"overflow", "read_bytes: 18446744073709551616\nwrite_bytes: 0", false, 0, 0},
|
||||
{"invalid", "read_bytes: 12\nwrite_bytes: bad", false, 12, 0},
|
||||
{"max", "read_bytes: 18446744073709551615\nwrite_bytes: 0", true, math.MaxUint64, 0},
|
||||
} {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
got := ParseProcessIO(tc.text)
|
||||
if got.Available != tc.available || got.ReadBytes != tc.read || got.WriteBytes != tc.write || got.Scope != "process" || got.ProcessID != processID {
|
||||
t.Fatalf("%+v", got)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestProcFileBound(t *testing.T) {
|
||||
path := filepath.Join(t.TempDir(), "counters")
|
||||
for _, size := range []int{maxProcBytes, maxProcBytes + 1} {
|
||||
if err := os.WriteFile(path, []byte(strings.Repeat("x", size)), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
data, err := readProcFile(path)
|
||||
if size == maxProcBytes && (err != nil || len(data) != size) {
|
||||
t.Fatalf("limit rejected: %v", err)
|
||||
}
|
||||
if size > maxProcBytes && (err == nil || data != nil) {
|
||||
t.Fatal("oversize file accepted")
|
||||
}
|
||||
}
|
||||
if _, err := readProcFile(path + "-missing"); err == nil {
|
||||
t.Fatal("missing file accepted")
|
||||
}
|
||||
}
|
||||
|
||||
func TestCollectLocalRuntime(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
before := time.Now().UnixMilli()
|
||||
got := Collect(root, Queue{Paused: true})
|
||||
if got.TimestampMS < before || got.TimestampMS > time.Now().UnixMilli() || got.Storage.Path != root || got.CPU.LogicalCPUs < 1 || got.Memory.Goroutines < 1 || !got.Queue.Paused || got.IO.ProcessID != processID {
|
||||
t.Fatalf("runtime snapshot %+v", got)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user