From 62ad21ff2e64f7af7bb33864c8c04d145c4c2120 Mon Sep 17 00:00:00 2001
From: Brad Fitzpatrick <brad@danga.com>
Date: Sun, 7 Jul 2013 16:09:17 -0700
Subject: [PATCH] Docs and minor cleanups

Change-Id: Ibf1d69c21f53cf4b5b576a0dfefa5d0e7b26264d
---
 TESTS                             |  1 +
 old/camwebdav/main.go             |  6 ++++++
 pkg/atomics/atomics.go            |  1 +
 pkg/auth/auth.go                  |  1 +
 pkg/blobref/blobref.go            |  2 ++
 pkg/blobserver/cond/cond.go       | 21 +++++++++++++++++++++
 pkg/blobserver/doc.go             | 18 ++++++++++++++++++
 pkg/blobserver/encrypt/encrypt.go | 13 +++++++++++++
 pkg/blobserver/gethandler/get.go  | 20 ++++++++++----------
 pkg/blobserver/interface.go       | 10 ++++++----
 pkg/blobserver/noimpl.go          |  5 +++--
 pkg/blobserver/registry.go        | 15 +++++++++++++++
 pkg/index/doc.go                  |  3 +--
 pkg/index/index.go                |  3 +++
 pkg/serverconfig/serverconfig.go  |  2 +-
 15 files changed, 102 insertions(+), 19 deletions(-)
 create mode 100644 pkg/blobserver/doc.go

diff --git a/TESTS b/TESTS
index 4b0bf98f2..5b2ab49a5 100644
--- a/TESTS
+++ b/TESTS
@@ -3,3 +3,4 @@ Tests needed
 -cmd/camput/
 	-verify that stat caching works. verify that -filenodes does create the permanode even if the file was already uploaded (and cached) in a previous run.
 
+-- blobserver/cond has no tests.
diff --git a/old/camwebdav/main.go b/old/camwebdav/main.go
index b127b4e6b..8209138fd 100644
--- a/old/camwebdav/main.go
+++ b/old/camwebdav/main.go
@@ -1,5 +1,11 @@
 // +build THIS_IS_BROKEN
 
+// The camwebdav binary is a WebDAV server to expose Camlistore as a
+// filesystem that can be mounted from Windows (or other operating
+// systems).
+//
+// It is currently broken and needs to be updated to use
+// camlistore.org/pkg/fs.
 package main
 
 import (
diff --git a/pkg/atomics/atomics.go b/pkg/atomics/atomics.go
index ed9401cf4..8f6ffedd1 100644
--- a/pkg/atomics/atomics.go
+++ b/pkg/atomics/atomics.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package atomics provides atomic types.
 package atomics
 
 import (
diff --git a/pkg/auth/auth.go b/pkg/auth/auth.go
index 034276224..1bb6f06dd 100644
--- a/pkg/auth/auth.go
+++ b/pkg/auth/auth.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package auth implements Camlistore authentication.
 package auth
 
 import (
diff --git a/pkg/blobref/blobref.go b/pkg/blobref/blobref.go
index 0e9634d20..276d272e0 100644
--- a/pkg/blobref/blobref.go
+++ b/pkg/blobref/blobref.go
@@ -14,6 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package blobref provides the BlobRef type and associate types and parsers.
+// A blobref is the immutable reference to an individual blob.
 package blobref
 
 import (
diff --git a/pkg/blobserver/cond/cond.go b/pkg/blobserver/cond/cond.go
index ea7087890..1ba6cd02b 100644
--- a/pkg/blobserver/cond/cond.go
+++ b/pkg/blobserver/cond/cond.go
@@ -14,6 +14,27 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+/*
+Package cond registers the "cond" conditional blobserver storage type
+to select routing of get/put operations on blobs to other storage
+targets as a function of their content.
+
+Currently only the "isSchema" predicate is defined.
+
+Example usage:
+
+  "/bs-and-maybe-also-index/": {
+	"handler": "storage-cond",
+	"handlerArgs": {
+		"write": {
+			"if": "isSchema",
+			"then": "/bs-and-index/",
+			"else": "/bs/"
+		},
+		"read": "/bs/"
+	}
+  }
+*/
 package cond
 
 import (
diff --git a/pkg/blobserver/doc.go b/pkg/blobserver/doc.go
new file mode 100644
index 000000000..f2b2e20d4
--- /dev/null
+++ b/pkg/blobserver/doc.go
@@ -0,0 +1,18 @@
+/*
+Copyright 2013 Google Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package blobserver defines how raw blobs are stored and accessed.
+package blobserver
\ No newline at end of file
diff --git a/pkg/blobserver/encrypt/encrypt.go b/pkg/blobserver/encrypt/encrypt.go
index 2154d6816..a534ad8a3 100644
--- a/pkg/blobserver/encrypt/encrypt.go
+++ b/pkg/blobserver/encrypt/encrypt.go
@@ -14,6 +14,19 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package encrypt registers the "encrypt" blobserver storage type
+// which stores all blobs and metadata with AES encryption into other
+// wrapped storage targets (e.g. localdisk, s3, remote, google).
+//
+// An encrypt storage target is configured with two other storage targets:
+// one to hold encrypted blobs, and one to hold encrypted metadata about
+// the encrypted blobs. On start-up, all the metadata blobs are read
+// to discover the plaintext blobrefs.
+//
+// Encryption is currently always AES-128.  See code for metadata formats
+// and configuration details, which are currently subject to change.
+//
+// WARNING: work in progress as of 2013-07-13.
 package encrypt
 
 import (
diff --git a/pkg/blobserver/gethandler/get.go b/pkg/blobserver/gethandler/get.go
index 932d0c649..d4b4b8a0f 100644
--- a/pkg/blobserver/gethandler/get.go
+++ b/pkg/blobserver/gethandler/get.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package gethandler implements the HTTP handler for fetching blobs.
 package gethandler
 
 import (
@@ -38,19 +39,18 @@ type Handler struct {
 	Fetcher blobref.StreamingFetcher
 }
 
-func CreateGetHandler(fetcher blobref.StreamingFetcher) func(http.ResponseWriter, *http.Request) {
-	gh := &Handler{Fetcher: fetcher}
-	return func(conn http.ResponseWriter, req *http.Request) {
-		if req.URL.Path == "/camli/sha1-deadbeef00000000000000000000000000000000" {
-			// Test handler.
-			simulatePrematurelyClosedConnection(conn, req)
-			return
-		}
-		gh.ServeHTTP(conn, req)
-	}
+// CreateGetHandler returns an http Handler for serving blobs from fetcher.1
+func CreateGetHandler(fetcher blobref.StreamingFetcher) http.Handler {
+	return &Handler{Fetcher: fetcher}
 }
 
 func (h *Handler) ServeHTTP(conn http.ResponseWriter, req *http.Request) {
+	if req.URL.Path == "/camli/sha1-deadbeef00000000000000000000000000000000" {
+		// Test handler.
+		simulatePrematurelyClosedConnection(conn, req)
+		return
+	}
+
 	blobRef := blobFromUrlPath(req.URL.Path)
 	if blobRef == nil {
 		http.Error(conn, "Malformed GET URL.", 400)
diff --git a/pkg/blobserver/interface.go b/pkg/blobserver/interface.go
index 0e660668a..a6129e1e3 100644
--- a/pkg/blobserver/interface.go
+++ b/pkg/blobserver/interface.go
@@ -163,18 +163,20 @@ type Generationer interface {
 	ResetStorageGeneration() error
 }
 
+// Storage is the interface that must be implemented by a blobserver
+// storage type. (e.g. localdisk, s3, encrypt, shard, replica, remote)
 type Storage interface {
 	blobref.StreamingFetcher
 	BlobReceiver
 	BlobStatter
 	BlobEnumerator
 
-	// Remove 0 or more blobs.  Removal of non-existent items
-	// isn't an error.  Returns failure if any items existed but
-	// failed to be deleted.
+	// RemoveBlobs removes 0 or more blobs.  Removal of
+	// non-existent items isn't an error.  Returns failure if any
+	// items existed but failed to be deleted.
 	RemoveBlobs(blobs []*blobref.BlobRef) error
 
-	// Returns the blob notification bus
+	// GetBlobHub returns the blob notification bus.
 	GetBlobHub() BlobHub
 }
 
diff --git a/pkg/blobserver/noimpl.go b/pkg/blobserver/noimpl.go
index 1aa732fd4..80fac8e38 100644
--- a/pkg/blobserver/noimpl.go
+++ b/pkg/blobserver/noimpl.go
@@ -25,8 +25,9 @@ import (
 	"camlistore.org/pkg/blobref"
 )
 
-type NoImplStorage struct {
-}
+// NoImplStorage is an implementation of Storage that return a not
+// implemented error for all operations.
+type NoImplStorage struct{}
 
 var _ Storage = (*NoImplStorage)(nil)
 
diff --git a/pkg/blobserver/registry.go b/pkg/blobserver/registry.go
index 8c1b1d3fc..85faad318 100644
--- a/pkg/blobserver/registry.go
+++ b/pkg/blobserver/registry.go
@@ -69,7 +69,12 @@ type Loader interface {
 	GetRequestContext() (ctx *http.Request, ok bool)
 }
 
+// A StorageConstructor returns a Storage implementation from a Loader
+// environment and a configuration.
 type StorageConstructor func(Loader, jsonconfig.Obj) (Storage, error)
+
+// A HandlerConstructor returns an http.Handler from a Loader
+// environment and a configuration.
 type HandlerConstructor func(Loader, jsonconfig.Obj) (http.Handler, error)
 
 var mapLock sync.Mutex
@@ -95,6 +100,10 @@ func CreateStorage(typ string, loader Loader, config jsonconfig.Obj) (Storage, e
 	return ctor(loader, config)
 }
 
+// RegisterHandlerConstructor registers an http Handler constructor function
+// for a given handler type.
+//
+// It is an error to register the same handler type twice.
 func RegisterHandlerConstructor(typ string, ctor HandlerConstructor) {
 	mapLock.Lock()
 	defer mapLock.Unlock()
@@ -104,6 +113,12 @@ func RegisterHandlerConstructor(typ string, ctor HandlerConstructor) {
 	handlerConstructors[typ] = ctor
 }
 
+// CreateHandler instantiates an http Handler of type 'typ' from the
+// provided JSON configuration, and finding peer handlers and
+// configuration from the environment in 'loader'.
+//
+// The handler 'typ' must have bee previously registered with
+// RegisterHandlerConstructor.
 func CreateHandler(typ string, loader Loader, config jsonconfig.Obj) (http.Handler, error) {
 	mapLock.Lock()
 	ctor, ok := handlerConstructors[typ]
diff --git a/pkg/index/doc.go b/pkg/index/doc.go
index fc107a420..246ad4569 100644
--- a/pkg/index/doc.go
+++ b/pkg/index/doc.go
@@ -15,8 +15,7 @@ limitations under the License.
 */
 
 /*
-Package index provides a generic indexing system on top of an abstract
-index storage system (Storage).
+Package index provides a generic indexing system on top of the abstract Storage interface.
 
 The following keys & values are populated by receiving blobs and queried
 for search operations:
diff --git a/pkg/index/index.go b/pkg/index/index.go
index 1575693ed..fdcde9f7c 100644
--- a/pkg/index/index.go
+++ b/pkg/index/index.go
@@ -34,6 +34,9 @@ import (
 
 var ErrNotFound = errors.New("index: key not found")
 
+// Storage is the minimal interface that must be implemented by index
+// storage implementations. (e.g. mysql, postgres, mongo, sqlite,
+// leveldb, dynamo)
 type Storage interface {
 	// Get gets the value for the given key. It returns ErrNotFound if the DB
 	// does not contain the key.
diff --git a/pkg/serverconfig/serverconfig.go b/pkg/serverconfig/serverconfig.go
index bd82afd6c..b0c49955c 100644
--- a/pkg/serverconfig/serverconfig.go
+++ b/pkg/serverconfig/serverconfig.go
@@ -120,7 +120,7 @@ func camliHandlerUsingStorage(req *http.Request, action string, storage blobserv
 		case "stat":
 			handler = handlers.CreateStatHandler(storage)
 		default:
-			handler = gethandler.CreateGetHandler(storage)
+			handler = gethandler.CreateGetHandler(storage).ServeHTTP
 			op = auth.OpGet
 		}
 	case "POST":