godoc run

blobstore/store.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package blobstore implements the filesystem storage and simpathy/want managment for ssb-blobs.
 package blobstore
 
 import (
@@ -15,31 +16,18 @@ import (
 	"time"
 
 	"github.com/pkg/errors"
-	refs "go.mindeco.de/ssb-refs"
-
 	"go.cryptoscope.co/luigi"
-	"go.cryptoscope.co/ssb"
-)
 
-var (
-	ErrNoSuchBlob = stderr.New("no such blob")
+	"go.cryptoscope.co/ssb"
+	refs "go.mindeco.de/ssb-refs"
 )
 
-func parseBlobRef(refStr string) (*refs.BlobRef, error) {
-	ref, err := refs.ParseRef(refStr)
-	if err != nil {
-		return nil, err
-	}
-
-	br, ok := ref.(*refs.BlobRef)
-
-	if !ok {
-		return nil, fmt.Errorf("ref is not a %T but a %T", br, ref)
-	}
-
-	return br, nil
-}
+// ErrNoSuchBlob is returned if the requested blob isn't available
+var ErrNoSuchBlob = stderr.New("ssb: no such blob")
 
+// New creates a new BlobStore, storing it's blobs at the given path.
+// This store is functionally equivalent to the javascript implementation and thus can share it's path.
+// ie: 'ln -s ~/.ssb/blobs ~/.ssb-go/blobs' works to deduplicate the storage.
 func New(basePath string) (ssb.BlobStore, error) {
 	err := os.MkdirAll(filepath.Join(basePath, "sha256"), 0700)
 	if err != nil {

blobstore/want_options.go

@@ -7,31 +7,37 @@ import (
 	"github.com/go-kit/kit/metrics"
 )
 
+// WantManagerOption is used to tune different aspects of the WantManager.
 type WantManagerOption func(*wantManager) error
 
+// WantWithContext supplies a context to cancel its operations.
 func WantWithContext(ctx context.Context) WantManagerOption {
 	return func(mgr *wantManager) error {
 		mgr.longCtx = ctx
 		return nil
 	}
 }
 
+// DefaultMaxSize is 5 megabyte. Blobs that are biggere are not fetched.
 const DefaultMaxSize = 5 * 1024 * 1024
 
+// WantWithMaxSize can be used to change DefaultMaxSize
 func WantWithMaxSize(sz uint) WantManagerOption {
 	return func(mgr *wantManager) error {
 		mgr.maxSize = sz
 		return nil
 	}
 }
 
+// WantWithLogger sets up the logger which is used for debug and info output.
 func WantWithLogger(l log.Logger) WantManagerOption {
 	return func(mgr *wantManager) error {
 		mgr.info = l
 		return nil
 	}
 }
 
+// WantWithMetrics setup the metrics counters and gauges to monitor the want manager.
 func WantWithMetrics(g metrics.Gauge, ctr metrics.Counter) WantManagerOption {
 	return func(mgr *wantManager) error {
 		mgr.gauge = g

blobstore/wants.go

@@ -16,13 +16,15 @@ import (
 	"github.com/pkg/errors"
 	"go.cryptoscope.co/luigi"
 	"go.cryptoscope.co/muxrpc"
-	refs "go.mindeco.de/ssb-refs"
 
 	"go.cryptoscope.co/ssb"
+	refs "go.mindeco.de/ssb-refs"
 )
 
-var ErrBlobBlocked = errors.New("blobstore: unable to receive blob")
+// ErrBlobBlocked is returned if the want manager is unable to receive a blob after multiple tries
+var ErrBlobBlocked = errors.New("ssb: unable to receive blob correctly")
 
+// NewWantManager returns the configured WantManager, using bs for storage and opts to configure it.
 func NewWantManager(bs ssb.BlobStore, opts ...WantManagerOption) ssb.WantManager {
 	wmgr := &wantManager{
 		bs:        bs,
@@ -413,6 +415,8 @@ func (proc *wantProc) updateWants(ctx context.Context, v interface{}, err error)
 	return proc.out.Pour(ctx, newW)
 }
 
+// GetWithSize is a muxrpc argument helper.
+// It can be used to request a blob named _key_ with a different maximum size than the default.
 type GetWithSize struct {
 	Key *refs.BlobRef `json:"key"`
 	Max uint          `json:"max"`
@@ -488,24 +492,21 @@ func (proc *wantProc) Pour(ctx context.Context, v interface{}) error {
 	return errors.Wrap(err, "error responding to wants")
 }
 
+// WantMsg is an array of _wants_, a blob reference with a distance.
 type WantMsg []ssb.BlobWant
 
-/* turns a blobwant array into one object ala
-{
-	ref1:dist1,
-	ref2:dist2,
-	...
-}
-*/
+// MarshalJSON turns a BlobWant slice into one object.
+// for example: { ref1:dist1, ref2:dist2, ... }
 func (msg WantMsg) MarshalJSON() ([]byte, error) {
 	wantsMap := make(map[*refs.BlobRef]int64, len(msg))
 	for _, want := range msg {
 		wantsMap[want.Ref] = want.Dist
 	}
 	data, err := json.Marshal(wantsMap)
-	return data, errors.Wrap(err, "WantMsg: error marshalling map?")
+	return data, errors.Wrap(err, "WantMsg: error marshalling map")
 }
 
+// UnmarshalJSON turns an object of {ref:dist, ...} relations into a slice of BlobWants.
 func (msg *WantMsg) UnmarshalJSON(data []byte) error {
 	var directWants []ssb.BlobWant
 	err := json.Unmarshal(data, &directWants)

blobstore/wants_test.go

@@ -103,22 +103,22 @@ func TestWantManager(t *testing.T) {
 			}
 
 			for refStr, dist := range tc.localWants {
-				ref, err := parseBlobRef(refStr)
+				ref, err := refs.ParseBlobRef(refStr)
 				r.NoError(err, "error parsing ref %q", ref)
 
 				a.NoError(wmgr.WantWithDist(ref, dist), "error wanting local ref")
 			}
 
 			for refStr := range tc.localWants {
-				ref, err := parseBlobRef(refStr)
+				ref, err := refs.ParseBlobRef(refStr)
 				r.NoError(err, "error parsing ref %q", ref)
 
 				a.Equal(true, wmgr.Wants(ref), "expected want manager to want ref %q, but it doesn't", ref.Ref())
 			}
 
 			var wmsg WantMsg
 			for refStr, dist := range tc.remoteWants {
-				ref, err := parseBlobRef(refStr)
+				ref, err := refs.ParseBlobRef(refStr)
 				r.NoError(err, "error parsing ref %q", ref)
 
 				wmsg = append(wmsg, ssb.BlobWant{Ref: ref, Dist: dist})

client/client.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package client is a a simple muxrpc interface to common ssb methods, similar to npm:ssb-client
 package client
 
 import (

cmd/go-sbot/main.go

@@ -1,5 +1,8 @@
 // SPDX-License-Identifier: MIT
 
+// go-sbot hosts the database and p2p server for replication.
+// It supplies various flags to contol options.
+// See 'go-sbot -h' for a list and their usage.
 package main
 
 import (

graph/graph.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package graph derives trust/block relations by consuming type:contact message and offers lookup APIs between two feeds.
 package graph
 
 import (

indexes/get.go

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: MIT
 
+// Package indexes contains functions to create indexing for 'get(%ref) -> message'.
+// Also contains a utility to open the contact trust graph using the repo and graph packages.
 package indexes
 
 import (
@@ -19,26 +21,28 @@ const FolderNameGet = "get"
 
 // OpenGet supplies the get(msgRef) -> rootLogSeq idx
 func OpenGet(r repo.Interface) (librarian.Index, librarian.SinkIndex, error) {
-	_, idx, sinkIdx, err := repo.OpenBadgerIndex(r, FolderNameGet, updateFn)
+	_, idx, sinkIdx, err := repo.OpenBadgerIndex(r, FolderNameGet, createFn)
 	if err != nil {
 		return nil, nil, errors.Wrap(err, "error getting get() index")
 	}
 	return idx, sinkIdx, nil
 }
 
-func updateFn(db *badger.DB) (librarian.SeqSetterIndex, librarian.SinkIndex) {
+func createFn(db *badger.DB) (librarian.SeqSetterIndex, librarian.SinkIndex) {
 	idx := libbadger.NewIndex(db, margaret.BaseSeq(0))
-	sink := librarian.NewSinkIndex(func(ctx context.Context, seq margaret.Seq, val interface{}, idx librarian.SetterIndex) error {
-		msg, ok := val.(refs.Message)
-		if !ok {
-			err, ok := val.(error)
-			if ok && margaret.IsErrNulled(err) {
-				return nil
-			}
-			return errors.Errorf("index/get: unexpected message type: %T", val)
-		}
-		err := idx.Set(ctx, librarian.Addr(msg.Key().Hash), seq.Seq())
-		return errors.Wrapf(err, "index/get: failed to update message %s (seq: %d)", msg.Key().Ref(), seq.Seq())
-	}, idx)
+	sink := librarian.NewSinkIndex(updateFn, idx)
 	return idx, sink
 }
+
+func updateFn(ctx context.Context, seq margaret.Seq, val interface{}, idx librarian.SetterIndex) error {
+	msg, ok := val.(refs.Message)
+	if !ok {
+		err, ok := val.(error)
+		if ok && margaret.IsErrNulled(err) {
+			return nil
+		}
+		return errors.Errorf("index/get: unexpected message type: %T", val)
+	}
+	err := idx.Set(ctx, librarian.Addr(msg.Key().Hash), seq.Seq())
+	return errors.Wrapf(err, "index/get: failed to update message %s (seq: %d)", msg.Key().Ref(), seq.Seq())
+}

internal/extra25519/convert.go

@@ -1,4 +1,6 @@
-// blatent grep of github.com/agl/ed25519/extra25519 until we have a better solution
+// Package extra25519 is blatent grep of github.com/agl/ed25519/extra25519 until we have a better solution
+//
+// See https://github.com/cryptoscope/ssb/issues/44 for more.
 package extra25519
 
 import (

internal/mutil/indirect.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package mutil offers some margaret utilities.
 package mutil
 
 import (
@@ -15,6 +16,8 @@ type indirectLog struct {
 	root, indirect margaret.Log
 }
 
+// Indirect returns a new Log uses the "indirection Log" to lookup entries in the "root log".
+// This helps with the existing database abstraction where indexes just point to entries in the root log by sequence numbers.
 func Indirect(root, indirect margaret.Log) margaret.Log {
 	il := indirectLog{
 		root:     root,

internal/muxmux/new_mux.go

@@ -1,3 +1,7 @@
+// Package muxmux offers an improved muxrpc.HandlerMux (think HTTP router).
+// compared to the first draft, this one offers specialed handler functions for the different call types (async, source, sink)
+// to reduce boilerplate in handlers.
+// TODO: if this shows itselv to be worthwhile, it should be moved to go-muxrpc.
 package muxmux
 
 import (

invite/legacy.go

@@ -1,3 +1,5 @@
+// Package invite contains functions for parsing invite codes and dialing a pub as a guest to redeem a token.
+// The muxrpc handlers and storage are found in plugins/legacyinvite.
 package invite
 
 import (

message/drains.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package message contains abstract verification and publish helpers.
 package message
 
 import (

message/legacy/verify.go

@@ -1,5 +1,9 @@
 // SPDX-License-Identifier: MIT
 
+// Package legacy how to encode and verify the current ssb messages.
+// You most likely want to use legacy.Verify() in most cases.
+//
+// See https://spec.scuttlebutt.nz/feed/messages.html for more encoding details.
 package legacy
 
 import (

message/multimsg/multimsg.go

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: MIT
 
+// Package multimsg implements a margaret codec to encode multiple kinds of messages to disk.
+// Currently _legacy_ and _gabbygrove_ but should be easily extendable.
 package multimsg
 
 import (

message/requests.go

@@ -37,9 +37,7 @@ func NewCreateHistArgsFromMap(argMap map[string]interface{}) (*CreateHistArgs, e
 				qry.AsJSON = b
 			}
 
-		case "type":
-			fallthrough
-		case "id":
+		case "type", "id":
 			val, ok := v.(string)
 			if !ok {
 				return nil, errors.Errorf("ssb/message: not string (but %T) for %s", v, k)

multilogs/private_readidx.go

@@ -24,7 +24,7 @@ import (
 
 const IndexNamePrivates = "privates"
 
-/* legacy
+/* deprecated
 // not strictly a multilog but allows multiple keys and gives us the good resumption
 func NewPrivateRead(log kitlog.Logger, kps ...*ssb.KeyPair) *Private {
 	return &Private{

multilogs/userfeeds.go

@@ -13,7 +13,7 @@ import (
 
 const IndexNameFeeds = "userFeeds"
 
-/* legacy
+/* deprecated
 func OpenUserFeeds(r repo.Interface) (*roaring.MultiLog, librarian.SinkIndex, error) {
 	return repo.OpenFileSystemMultiLog(r, IndexNameFeeds, UserFeedsUpdate)
 }

network/network.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package network implements utilities for dialing and listening to secret-handshake powered muxrpc connections.
 package network
 
 import (

plugins/blobs/blob.go

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: MIT
 
+// Package blobs implements the muxrpc handlers for npm:ssb-blobs.
+// The storage and want-managment is found in the blobstore package.
 package blobs
 
 import (

plugins/control/handler.go

@@ -1,5 +1,8 @@
 // SPDX-License-Identifier: MIT
 
+// Package control offers muxrpc helpers to connect to remote peers.
+//
+// TODO: this is a naming hack, supplies ctrl.connect which should actually be gossip.connect.
 package control
 
 import (

plugins/friends/handler.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package friends supplies some of npm:ssb-friends, namly isFollowing, isBlocking and hops but not hopStream, onEdge or createLayer.
 package friends
 
 import (
@@ -17,11 +18,7 @@ import (
 
   isFollowing: 'async',
   isBlocking: 'async',
-  hops: 'async',
-
-extra:
-
-  follows: 'source',
+  hops: 'source',
   blocks: 'source',
 
 */

plugins/get/get.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package get is just a muxrpc wrapper around sbot.Get
 package get
 
 import (

plugins/gossip/handler.go

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 
+// Package gossip implements the createHistoryStream muxrpc call. Legacy (non-EBT) Replication of fetching and verifying the selected feeds is found here.
 package gossip
 
 import (

plugins/legacyinvites/service.go

@@ -1,3 +1,4 @@
+// Package legacyinvites supplies the follow-back sub protocol for new users. Translates to npm:ssb-invite.
 package legacyinvites
 
 import (