Remove names boilerplate.

Add more documentation.
Separate TCP vs Unix serving methods.

Signed-off-by: David Calavera <david.calavera@gmail.com>

Author: calavera

README.md

@@ -6,17 +6,27 @@ Go handler to create external volume extensions for Docker.
 
 This library is designed to be integrated in your program.
 
-1. Implement the `VolumeDriver` interface.
-2. Initialize a `VolumeHander` with your implementation.
-2. Call the method `ListenAndServe` from the `VolumeHandler`.
+1. Implement the `dkv.Driver` interface.
+2. Initialize a `dkv.Hander` with your implementation.
+3. Call either `ServeTCP` or `ServeUnix` from the `dkv.Handler`.
+
+### Example using TCP sockets:
+
+```go
+  d := MyVolumeDriver{}
+  h := dkv.NewHandler(d)
+  h.ServeTCP("test_volume", ":8080")
+```
+
+### Example using Unix sockets:
 
 ```go
   d := MyVolumeDriver{}
-  h := volumeapi.NewVolumeHandler(d)
-  h.ListenAndServe("tcp", ":8080", "")
+  h := dkv.NewHandler(d)
+  h.ServeUnix("root", "/usr/share/docker/plugins/test_volume.sock")
 ```
 
-See a full example in https://github.com/calavera/docker-volume-keywhiz-fs
+See a full example in https://github.com/calavera/docker-volume-glusterfs
 
 ## License
 

api.go

@@ -1,16 +1,22 @@
-package volumeapi
+package dkv
 
 import (
 	"encoding/json"
 	"fmt"
+	"io/ioutil"
 	"net"
 	"net/http"
+	"os"
+	"path/filepath"
 )
 
 const (
-	DefaultDockerRootDirectory    = "/var/lib/docker/volumes"
+	// DefaultDockerRootDirectory is the default directory where volumes will be created.
+	DefaultDockerRootDirectory = "/var/lib/docker/volumes"
+
 	defaultContentTypeV1          = "appplication/vnd.docker.plugins.v1+json"
 	defaultImplementationManifest = `{"Implements": ["VolumeDriver"]}`
+	pluginSpecDir                 = "/usr/share/docker/plugins"
 
 	activatePath    = "/Plugin.Activate"
 	createPath      = "/VolumeDriver.Create"
@@ -20,64 +26,69 @@ const (
 	unmountPath     = "/VolumeDriver.Unmount"
 )
 
-type VolumeRequest struct {
+// Request is the structure that docker's requests are deserialized to.
+type Request struct {
 	Name string
 }
 
-type VolumeResponse struct {
+// Response is the strucutre that the plugin's responses are serialized to.
+type Response struct {
 	Mountpoint string
 	Err        string
 }
 
-type VolumeDriver interface {
-	Create(VolumeRequest) VolumeResponse
-	Remove(VolumeRequest) VolumeResponse
-	Path(VolumeRequest) VolumeResponse
-	Mount(VolumeRequest) VolumeResponse
-	Unmount(VolumeRequest) VolumeResponse
+// Driver represent the interface a driver must fulfill.
+type Driver interface {
+	Create(Request) Response
+	Remove(Request) Response
+	Path(Request) Response
+	Mount(Request) Response
+	Unmount(Request) Response
 }
 
-type VolumeHandler struct {
-	handler VolumeDriver
-	mux     *http.ServeMux
+// Handler forwards requests and responses between the docker daemon and the plugin.
+type Handler struct {
+	driver Driver
+	mux    *http.ServeMux
 }
 
-type actionHandler func(VolumeRequest) VolumeResponse
+type actionHandler func(Request) Response
 
-func NewVolumeHandler(handler VolumeDriver) *VolumeHandler {
-	h := &VolumeHandler{handler, http.NewServeMux()}
+// NewHandler initializes the request handler with a driver implementation.
+func NewHandler(driver Driver) *Handler {
+	h := &Handler{driver, http.NewServeMux()}
 	h.initMux()
 	return h
 }
 
-func (h *VolumeHandler) initMux() {
+func (h *Handler) initMux() {
 	h.mux.HandleFunc(activatePath, func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", defaultContentTypeV1)
 		fmt.Fprintln(w, defaultImplementationManifest)
 	})
 
-	h.handle(createPath, func(req VolumeRequest) VolumeResponse {
-		return h.handler.Create(req)
+	h.handle(createPath, func(req Request) Response {
+		return h.driver.Create(req)
 	})
 
-	h.handle(remotePath, func(req VolumeRequest) VolumeResponse {
-		return h.handler.Remove(req)
+	h.handle(remotePath, func(req Request) Response {
+		return h.driver.Remove(req)
 	})
 
-	h.handle(hostVirtualPath, func(req VolumeRequest) VolumeResponse {
-		return h.handler.Path(req)
+	h.handle(hostVirtualPath, func(req Request) Response {
+		return h.driver.Path(req)
 	})
 
-	h.handle(mountPath, func(req VolumeRequest) VolumeResponse {
-		return h.handler.Mount(req)
+	h.handle(mountPath, func(req Request) Response {
+		return h.driver.Mount(req)
 	})
 
-	h.handle(unmountPath, func(req VolumeRequest) VolumeResponse {
-		return h.handler.Unmount(req)
+	h.handle(unmountPath, func(req Request) Response {
+		return h.driver.Unmount(req)
 	})
 }
 
-func (h *VolumeHandler) handle(name string, actionCall actionHandler) {
+func (h *Handler) handle(name string, actionCall actionHandler) {
 	h.mux.HandleFunc(name, func(w http.ResponseWriter, r *http.Request) {
 		req, err := decodeRequest(w, r)
 		if err != nil {
@@ -90,7 +101,19 @@ func (h *VolumeHandler) handle(name string, actionCall actionHandler) {
 	})
 }
 
-func (h *VolumeHandler) ListenAndServe(proto, addr, group string) error {
+// ServeTCP makes the handler to listen for request in a given TCP address.
+// It also writes the spec file on the right directory for docker to read.
+func (h *Handler) ServeTCP(pluginName, addr string) error {
+	return h.listenAndServe("tcp", addr, pluginName)
+}
+
+// ServeUnix makes the handler to listen for requests in a unix socket.
+// It also creates the socket file on the right directory for docker to read.
+func (h *Handler) ServeUnix(systemGroup, addr string) error {
+	return h.listenAndServe("unix", addr, systemGroup)
+}
+
+func (h *Handler) listenAndServe(proto, addr, group string) error {
 	server := http.Server{
 		Addr:    addr,
 		Handler: h.mux,
@@ -102,7 +125,10 @@ func (h *VolumeHandler) ListenAndServe(proto, addr, group string) error {
 	var err error
 	switch proto {
 	case "tcp":
-		l, err = newTcpSocket(addr, nil, start)
+		l, err = newTCPSocket(addr, nil, start)
+		if err == nil {
+			err = writeSpec(group, l.Addr().String())
+		}
 	case "unix":
 		l, err = newUnixSocket(addr, group, start)
 	}
@@ -114,17 +140,27 @@ func (h *VolumeHandler) ListenAndServe(proto, addr, group string) error {
 	return server.Serve(l)
 }
 
-func decodeRequest(w http.ResponseWriter, r *http.Request) (req VolumeRequest, err error) {
+func decodeRequest(w http.ResponseWriter, r *http.Request) (req Request, err error) {
 	if err = json.NewDecoder(r.Body).Decode(&req); err != nil {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 	}
 	return
 }
 
-func encodeResponse(w http.ResponseWriter, res VolumeResponse) {
+func encodeResponse(w http.ResponseWriter, res Response) {
 	w.Header().Set("Content-Type", defaultContentTypeV1)
 	if res.Err != "" {
 		w.WriteHeader(http.StatusInternalServerError)
 	}
 	json.NewEncoder(w).Encode(res)
 }
+
+func writeSpec(name, addr string) error {
+	if err := os.MkdirAll(pluginSpecDir, 0755); err != nil {
+		return err
+	}
+
+	spec := filepath.Join(pluginSpecDir, name+".spec")
+	url := "tcp://" + addr
+	return ioutil.WriteFile(spec, []byte(url), 0644)
+}

connection.go

@@ -1,4 +1,4 @@
-package volumeapi
+package dkv
 
 import (
 	"crypto/tls"
@@ -21,7 +21,8 @@ import (
 // https://github.com/docker/docker/blob/master/api/server/unix_socket.go
 // https://github.com/docker/docker/blob/master/api/server/tcp_socket.go
 
-type TlsConfig struct {
+// TLSConfig is the structure that represents the TLS configuration.
+type TLSConfig struct {
 	CA          string
 	Certificate string
 	Key         string
@@ -49,20 +50,20 @@ func newUnixSocket(path, group string, activate <-chan struct{}) (net.Listener,
 	return l, nil
 }
 
-func newTcpSocket(addr string, config *TlsConfig, activate <-chan struct{}) (net.Listener, error) {
+func newTCPSocket(addr string, config *TLSConfig, activate <-chan struct{}) (net.Listener, error) {
 	l, err := listenbuffer.NewListenBuffer("tcp", addr, activate)
 	if err != nil {
 		return nil, err
 	}
 	if config != nil {
-		if l, err = setupTls(l, config); err != nil {
+		if l, err = setupTLS(l, config); err != nil {
 			return nil, err
 		}
 	}
 	return l, nil
 }
 
-func setupTls(l net.Listener, config *TlsConfig) (net.Listener, error) {
+func setupTLS(l net.Listener, config *TLSConfig) (net.Listener, error) {
 	tlsCert, err := tls.LoadX509KeyPair(config.Certificate, config.Key)
 	if err != nil {
 		if os.IsNotExist(err) {