pim: personal information management, starting with a calendar

A calendar as a file tree, and tools that only know the tree:

	events/date/yyyy/mm/dd/hhmm-summary	as lived
	events/uuid/<uid>/			as stored
	ctl query alarm changed

lib/cal owns all of that. A backend supplies events and, where its
protocol allows, takes changes back -- six methods. cmd/icalfs is the
first: it reads .ics files from a directory and nothing else, because
fetching is rc/fetch's job and hget already exists. That keeps
net/http out of the binary and makes a subscribed calendar and a local
one the same thing.

The tools are rc on purpose. If the tree needs a compiled program to be
useful, the tree is the wrong shape. Three things were added to the
tree because the rc port needed them: a path from an occurrence to its
event, epoch seconds beside RFC3339, and a numeric slot for all-day
events so test(1) can compare it.

ctl reports caps, so a tool can say "read only" instead of trying and
failing. A published .ics is read only: nowhere to PUT, and no
METHOD:REQUEST to reply to. CalDAV would be read write rsvp schedule,
and that is the next backend.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 41 insertions, 0 deletions

diff --git a/pim/lib/cal/backend.go b/pim/lib/cal/backend.go
new file mode 100644
index 0000000..6dcacc2
--- /dev/null
+++ b/pim/lib/cal/backend.go
@@ -0,0 +1,41 @@
+package cal
+
+import "time"
+
+// A Backend supplies a calendar's events and, where the protocol allows
+// it, accepts changes back.
+//
+// Everything above this line -- the tree, recurrence expansion, ctl,
+// query, alarm, changed, the 9p service -- is the same whether the
+// events arrived as a published .ics, over CalDAV or over JMAP. Only
+// fetching and writing differ, so only fetching and writing live here.
+type Backend interface {
+	// Name of the calendar, as it appears in ctl.
+	Name() string
+
+	// Caps says what this backend can do, so that a tool can report
+	// "read only" rather than trying and failing. The vocabulary is
+	// read, write, rsvp, schedule; see pim/doc/design.md.
+	Caps() string
+
+	// Refresh is how often to poll. Zero means never.
+	Refresh() time.Duration
+
+	// Status reports when the backend last synced and the error, if
+	// any, from that attempt.
+	Status() (time.Time, string)
+
+	// Sync brings the backend up to date and reports whether anything
+	// actually changed. A backend that cannot tell should say true --
+	// the cost is a needless rebuild, not a wrong answer.
+	Sync() (bool, error)
+
+	// Events returns the calendar as it now stands.
+	Events() ([]*Event, error)
+}
+
+// Describer is implemented by backends with more to say in ctl: the
+// source directory, the url, whatever identifies where events came from.
+type Describer interface {
+	Describe() string
+}