queue

package

v0.1.1 Latest Latest Go to latest Published: Nov 8, 2026 License: MIT Imports: 10 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/8thlyr/nod

Links

Open Source Insights

Documentation ¶

Rendered for

Overview ¶

Package queue reads and writes a nod queue: a markdown file of approval requests that agents add to and humans resolve.

Index ¶

Constants
Variables
func Clean(s string) string
func NormalizeID(id string) string
type Item
type Queue
- func Parse(text string) (*Queue, error)
type Store
type Verdict
- func ParseVerdict(s string) (Verdict, bool)
- func (v Verdict) Positive() bool

Constants ¶

View Source

const TimeLayout = "2006-01-02 15:04"

TimeLayout is the minute-precision local timestamp used in the file.

Variables ¶

View Source

var (
	ErrNotFound = errors.New("not found")
	ErrConflict = errors.New("already resolved with a different verdict")
)

Functions ¶

func Clean ¶

func Clean(s string) string

Clean makes a value safe to store in a field: one line, no separators.

func NormalizeID ¶

func NormalizeID(id string) string

NormalizeID turns "7", "n-7" or "N-7" into "N-7".

Types ¶

type Item ¶

type Item struct {
	ID         string    `json:"id"`
	Agent      string    `json:"agent"`
	Summary    string    `json:"summary"`
	Action     string    `json:"action"`
	Ref        string    `json:"ref"`
	Key        string    `json:"key,omitempty"`
	Asked      time.Time `json:"asked"`
	Verdict    Verdict   `json:"verdict,omitempty"`
	ResolvedAt time.Time `json:"resolved_at,omitzero"`
	By         string    `json:"by,omitempty"`
	Note       string    `json:"note,omitempty"`
}

Item is one approval request.

func (Item) Line ¶

func (i Item) Line() string

Line renders the item as its markdown list line.

func (Item) Num ¶

func (i Item) Num() int

Num is the numeric part of the ID (N-7 -> 7), or 0.

func (Item) Open ¶

func (i Item) Open() bool

Open reports whether the item still waits on a human.

func (Item) State ¶

func (i Item) State() string

State is "open" or the verdict.

type Queue ¶

type Queue struct {
	// contains filtered or unexported fields
}

Queue is a parsed nod file. Unknown lines survive a round trip.

func Parse ¶

func Parse(text string) (*Queue, error)

Parse reads a nod file. It never fails on unknown content; lines it doesn't understand are kept as-is.

func (*Queue) Add ¶

func (q *Queue) Add(it Item) Item

Add stores a new open item at the end of the Open section and returns it with its assigned ID. Fields are cleaned; Asked must be set by the caller.

func (*Queue) FindKey ¶

func (q *Queue) FindKey(key string) (Item, bool)

FindKey finds an item (open or resolved) by idempotency key.

func (*Queue) Get ¶

func (q *Queue) Get(id string) (Item, bool)

Get finds an item by ID (case-insensitive, "7" works for "N-7").

func (*Queue) Items ¶

func (q *Queue) Items() []Item

Items returns open items in file order, then resolved ones in file order.

func (*Queue) Render ¶

func (q *Queue) Render() string

Render writes the queue back to markdown.

func (*Queue) Resolve ¶

func (q *Queue) Resolve(id string, v Verdict, by, note string, at time.Time) (Item, error)

Resolve sets a verdict on an open item and moves it to the top of the Resolved section. Resolving again with the same verdict is a no-op; a different verdict returns ErrConflict.

type Store ¶

type Store struct {
	Path string
}

Store is a nod file on disk. Update is safe across goroutines and processes.

func (Store) Load ¶

func (s Store) Load() (*Queue, error)

Load reads the queue without locking. A missing file is an empty queue. Writers replace the file atomically, so readers never see a torn write.

func (Store) LockPath ¶

func (s Store) LockPath() string

LockPath is the sidecar lock file next to the queue.

func (Store) Update ¶

func (s Store) Update(fn func(*Queue) error) error

Update takes an exclusive lock, loads the queue, runs fn, and writes the result atomically if it changed. If fn returns an error nothing is written.

type Verdict ¶

type Verdict string

Verdict is how a request was resolved. The empty verdict means still open.

const (
	Open     Verdict = ""
	Approved Verdict = "approved"
	Declined Verdict = "declined"
	Done     Verdict = "done"
	Dropped  Verdict = "dropped"
)

func ParseVerdict ¶

func ParseVerdict(s string) (Verdict, bool)

ParseVerdict accepts approved/declined/done/dropped in any case.

func (Verdict) Positive ¶

func (v Verdict) Positive() bool

Positive reports whether the verdict lets the agent go ahead.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL