Driver api refactor

Refactored the driver api so that is aligns well with the design
of endpoint lifecycle becoming decoupled from the container lifecycle.
Introduced go interfaces to obtain address information during CreateEndpoint.
Go interfaces are also used to get data from driver during join.
This sort of deisgn hides the libnetwork specific type details from drivers.

Another adjustment is to provide a list of interfaces during CreateEndpoint. The
goal of this is many-fold:
     * To indicate to the driver that IP address has been assigned by some other
       entity (like a user wanting to use their own static IP for an endpoint/container)
       and asking the driver to honor this. Driver may reject this configuration
       and return an error but it may not try to allocate an IP address and override
       the passed one.
     * To indicate to the driver that IP address has already been allocated once
       for this endpoint by an instance of the same driver in some docker host
       in the cluster and this is merely a notification about that endpoint and the
       allocated resources.
     * In case the list of interfaces is empty the driver is required to allocate and
       assign IP addresses for this endpoint.

Signed-off-by: Jana Radhakrishnan <mrjana@docker.com>

driverapi/driverapi.go

@@ -3,8 +3,8 @@ package driverapi
 import (
 	"errors"
 	"fmt"
+	"net"
 
-	"github.com/docker/libnetwork/sandbox"
 	"github.com/docker/libnetwork/types"
 )
 
@@ -37,32 +37,91 @@ type Driver interface {
 	DeleteNetwork(nid types.UUID) error
 
 	// CreateEndpoint invokes the driver method to create an endpoint
-	// passing the network id, endpoint id and driver
-	// specific config. The config mechanism will eventually be replaced
-	// with labels which are yet to be introduced.
-	CreateEndpoint(nid, eid types.UUID, options map[string]interface{}) (*sandbox.Info, error)
+	// passing the network id, endpoint id endpoint information and driver
+	// specific config. The endpoint information can be either consumed by
+	// the driver or populated by the driver. The config mechanism will
+	// eventually be replaced with labels which are yet to be introduced.
+	CreateEndpoint(nid, eid types.UUID, epInfo EndpointInfo, options map[string]interface{}) error
 
 	// DeleteEndpoint invokes the driver method to delete an endpoint
 	// passing the network id and endpoint id.
 	DeleteEndpoint(nid, eid types.UUID) error
 
-	// EndpointInfo retrieves from the driver the operational data related to the specified endpoint
-	EndpointInfo(nid, eid types.UUID) (map[string]interface{}, error)
+	// EndpointOperInfo retrieves from the driver the operational data related to the specified endpoint
+	EndpointOperInfo(nid, eid types.UUID) (map[string]interface{}, error)
 
 	// Join method is invoked when a Sandbox is attached to an endpoint.
-	Join(nid, eid types.UUID, sboxKey string, options map[string]interface{}) (*JoinInfo, error)
+	Join(nid, eid types.UUID, sboxKey string, jinfo JoinInfo, options map[string]interface{}) error
 
 	// Leave method is invoked when a Sandbox detaches from an endpoint.
-	Leave(nid, eid types.UUID, options map[string]interface{}) error
+	Leave(nid, eid types.UUID) error
 
 	// Type returns the the type of this driver, the network type this driver manages
 	Type() string
 }
 
+// EndpointInfo provides a go interface to fetch or populate endpoint assigned network resources.
+type EndpointInfo interface {
+	// Interfaces returns a list of interfaces bound to the endpoint.
+	// If the list is not empty the driver is only expected to consume the interfaces.
+	// It is an error to try to add interfaces to a non-empty list.
+	// If the list is empty the driver is expected to populate with 0 or more interfaces.
+	Interfaces() []InterfaceInfo
+
+	// AddInterface is used by the driver to add an interface to the interface list.
+	// This method will return an error if the driver attempts to add interfaces
+	// if the Interfaces() method returned a non-empty list.
+	// ID field need only have significance within the endpoint so it can be a simple
+	// monotonically increasing number
+	AddInterface(ID int, mac net.HardwareAddr, ipv4 net.IPNet, ipv6 net.IPNet) error
+}
+
+// InterfaceInfo provides a go interface for drivers to retrive
+// network information to interface resources.
+type InterfaceInfo interface {
+	// MacAddress returns the MAC address.
+	MacAddress() net.HardwareAddr
+
+	// Address returns the IPv4 address.
+	Address() net.IPNet
+
+	// AddressIPv6 returns the IPv6 address.
+	AddressIPv6() net.IPNet
+
+	// ID returns the numerical id of the interface and has significance only within
+	// the endpoint.
+	ID() int
+}
+
+// InterfaceNameInfo provides a go interface for the drivers to assign names
+// to interfaces.
+type InterfaceNameInfo interface {
+	// SetNames method assigns the srcName and dstName for the interface.
+	SetNames(srcName, dstName string) error
+
+	// ID returns the numerical id that was assigned to the interface by the driver
+	// CreateEndpoint.
+	ID() int
+}
+
 // JoinInfo represents a set of resources that the driver has the ability to provide during
 // join time.
-type JoinInfo struct {
-	HostsPath string
+type JoinInfo interface {
+	// InterfaceNames returns a list of InterfaceNameInfo go interface to facilitate
+	// setting the names for the interfaces.
+	InterfaceNames() []InterfaceNameInfo
+
+	// SetGateway sets the default IPv4 gateway when a container joins the endpoint.
+	SetGateway(net.IP) error
+
+	// SetGatewayIPv6 sets the default IPv6 gateway when a container joins the endpoint.
+	SetGatewayIPv6(net.IP) error
+
+	// SetHostsPath sets the overriding /etc/hosts path to use for the container.
+	SetHostsPath(string) error
+
+	// SetResolvConfPath sets the overriding /etc/resolv.conf path to use for the container.
+	SetResolvConfPath(string) error
 }
 
 // ErrActiveRegistration represents an error when a driver is registered to a networkType that is previously registered