jbenet · July 11, 2018 00:46 · Jul 11, 2018
diff --git a/dht-interface.go b/dht-interface.go
@@ -0,0 +1,64 @@
+import "context"
+
+type Key interface {}
+// concrete type likely a []byte or string
+
+type Record interface {}
+// concrete type is a struct
+// (in libp2p, will be ipld -- see iprs)
+// mitting here for clairty and avoiding distraction
+// for now, let's assume it's an opaque value.
+
+type DHT interface {
+  // Put sets record r as the latest value for key k.
+  Put(k Key, r Record) error
+
+  // Get retrieves the latest record value for key k in the DHT
+  Get(k Key) (Record, error)
+
+  // PutSloppy sets a record in a DHT, with sloppy semantics.
+  // A sloppy put is like adding to a set. See GetSloppy.
+  PutSloppy(k Key, Record) error
+
+  // GetSloppy retrieves a subset of records for key k
+  // Sloppy DHTs (DSHTs) don't try to get a single record value for a key
+  // Rather, GetSloppy returns a subset of the record in the dht
+  // This is useful for multiple writer environments, and maintaining sets.
+  // See https://www.coralcdn.org/docs/coral-iptps03.pdf for more.
+  GetSloppy(k Key) ([]Record, error)
+}
+
+// Arguably, we could really split it into two interfaces as below,
+// but the benefits are pretty limited, and most DHTs can operate
+// as DSHTs.
+type DHT interface {
+  Put(k Key, r Record) error
+  Get(k Key) (Record, error)
+}
+
+type DSHT interface {
+  Put(k Key, r Record) error
+  Get(k Key) ([]Record, error)
+}
+
+// maybe we could avoid the "sloppy" wording and use set wording:
+type DHT interface {
+  Put(k Key, r Record) error
+  Get(k Key) (Record, error)
+
+  SetAdd(k Key, Record) error
+  GetSubset(k Key) ([]Record, error)
+}
+
+
+// in practice, in our go implementation, we'll likely use 
+// an interface like the one below, which:
+// - uses context.Context (idiomatic to Go) to handle canccellation
+// - uses channels (idiomatic to Go) for async record return
+type DHT interface {
+  Put(ctx context.Context, k Key, r Record) error
+  Get(ctx context.Context, k Key) (Record, error)
+
+  PutSloppy(ctx context.Context, k Key, Record) error
+  GetSloppy(ctx context.Context, k Key) (<-Record, error)
+}