Repository: moby/moby
File: libnetwork/driverapi/driverapi.go (Go)

Code before:
	// can be presented to the user.
	// For example: overlay driver returns the VTEP IP of the host that has the endpoint
	// which is shown in 'network inspect --verbose'
	DecodeTableEntry(tablename string, key string, value []byte) (string, map[string]string)

	// Type returns the type of this driver, the network type this driver manages
	Type() string

	// IsBuiltIn returns true if it is a built-in driver
	IsBuiltIn() bool
}

// ExtConner is an optional interface for a network driver.
type ExtConner interface {
	// ProgramExternalConnectivity tells the driver the ids of the endpoints
	// currently acting as the container's default gateway for IPv4 and IPv6 are
	// passed as gw4Id/gw6Id. (Those endpoints may be managed by different network
	// drivers. If there is no gateway, the id will be the empty string.)
	//
	// This method is called after Driver.Join, before Driver.Leave, and when eid
	// is or was equal to gw4Id or gw6Id, and there's a change. It may also be
	// called when the gateways have not changed.
	//
	// When an endpoint acting as a gateway is deleted, this function is called
	// with that endpoint's id, and empty gateway ids (even if another endpoint
	// is present and will shortly be selected as the gateway).
	ProgramExternalConnectivity(ctx context.Context, nid, eid string, gw4Id, gw6Id string) error
}

// GwAllocChecker is an optional interface for a network driver.
type GwAllocChecker interface {
	// GetSkipGwAlloc returns true if the opts describe a network
	// that does not need a gateway IPv4/IPv6 address, else false.
	GetSkipGwAlloc(opts options.Generic) (skipIPv4, skipIPv6 bool, err error)
}

// NetworkInfo provides a go interface for drivers to provide network
// specific information to libnetwork.
type NetworkInfo interface {
	// TableEventRegister registers driver interest in a given
	// table name.
	TableEventRegister(tableName string, objType ObjectType) error

	// UpdateIpamConfig updates the networks IPAM configuration
	// based on information from the driver.  In windows, the OS (HNS) chooses
	// the IP address space if the user does not specify an address space.
	UpdateIpamConfig(ipV4Data []IPAMData)
}

// InterfaceInfo provides a go interface for drivers to retrieve
// network information to interface resources.

Review comment (suggestion):
The fact that the gateway IDs may be for endpoints belonging to other drivers makes this statement ambiguous. What happens if the endpoint for `gw4Id`, belonging to another driver, is deleted? I would intuitively expect libnetwork to call `ProgramExternalConnectivity(ctx, nid, eid, "", "")` but the interface contract reads like libnetwork would be expected to pass `gw4Id` as the `eid` parameter!

How helpful are these semantics in the case where the endpoint being deleted is the gateway: `eid == gw4Id || eid == gw6Id`? `DeleteEndpoint(nid, eid)` will be invoked in the driver regardless. What are drivers expected to do if `DeleteEndpoint` is called on an endpoint that is the default gateway for a network of the driver's type?

Are atomic swaps of the gateways permitted? E.g.
```go
ProgramExternalConnectivity(ctx, nid, eid, "gateway1", "")
ProgramExternalConnectivity(ctx, nid, eid, "gateway2", "")
```

Code after:
	// can be presented to the user.
	// For example: overlay driver returns the VTEP IP of the host that has the endpoint
	// which is shown in 'network inspect --verbose'
	DecodeTableEntry(tablename string, key string, value []byte) (string, map[string]string)

	// Type returns the type of this driver, the network type this driver manages
	Type() string

	// IsBuiltIn returns true if it is a built-in driver
	IsBuiltIn() bool
}

// ExtConner is an optional interface for a network driver.
type ExtConner interface {
	// ProgramExternalConnectivity tells the driver the ids of the endpoints
	// currently acting as the container's default gateway for IPv4 and IPv6,
	// passed as gw4Id/gw6Id. (Those endpoints may be managed by different network
	// drivers. If there is no gateway, the id will be the empty string.)
	//
	// This method is called after Driver.Join, before Driver.Leave, and when eid
	// is or was equal to gw4Id or gw6Id, and there's a change. It may also be
	// called when the gateways have not changed.
	//
	// When an endpoint acting as a gateway is deleted, this function is called
	// with that endpoint's id in eid, and empty gateway ids (even if another
	// is present and will shortly be selected as the gateway).
	ProgramExternalConnectivity(ctx context.Context, nid, eid string, gw4Id, gw6Id string) error
}

// GwAllocChecker is an optional interface for a network driver.
type GwAllocChecker interface {
	// GetSkipGwAlloc returns true if the opts describe a network
	// that does not need a gateway IPv4/IPv6 address, else false.
	GetSkipGwAlloc(opts options.Generic) (skipIPv4, skipIPv6 bool, err error)
}

// NetworkInfo provides a go interface for drivers to provide network
// specific information to libnetwork.
type NetworkInfo interface {
	// TableEventRegister registers driver interest in a given
	// table name.
	TableEventRegister(tableName string, objType ObjectType) error

	// UpdateIpamConfig updates the networks IPAM configuration
	// based on information from the driver.  In windows, the OS (HNS) chooses
	// the IP address space if the user does not specify an address space.
	UpdateIpamConfig(ipV4Data []IPAMData)
}

// InterfaceInfo provides a go interface for drivers to retrieve
// network information to interface resources.