name_manager

type Backend struct {
	// Protocol is the protocol for the backend.  If the protocol is "foo",
	// backend URLs starting with "foo://", such as "foo://bar", will give
	// `NameManager` instances created with the `CreateNameManager`
	// associated with this backend.
	Protocol string

	// Description holds a human-readable description of the backend.
	// This description should specify, among other things, the format
	// for the URL.
	Description string

	// CreateNameManager creates a `NameManager` from a URL, stripped
	// of the protocol.  For instance, if `CreateFromURL("foo://bar")` is
	// called, the URL passed to this function is "bar".
	CreateNameManager func(backendURL string) (NameManager, error)
}

type Name struct {
	// Name is the name.
	Name string

	// Family is the name family the name belongs to.  Names are unique
	// within the same family.
	Family string

	// CreatedAt is the timestamp at which the name was first registered.
	CreatedAt time.Time

	// UpdatedAt is the timestamp at which the name was last acquired.
	UpdatedAt time.Time

	// Free is whether the name is free, or it was acquired but not
	// yet released.
	Free bool
}

type NameManager interface {
	// Hold acquires a name for the given family, returns it, and keep
	// it alive until the release function is called (this call also
	// releases the name).  Thanks to a global lock, a given name cannot
	// be acquired twice for the same family without having been released
	// first.  Using Hold in the background is almost always preferable
	// to calling directly Acquire, KeepAlive, and Release, which are
	// low-level.  Errors occurring during the keep-alive are sent to
	// an error channel.
	Hold(family string) (string, <-chan error, ReleaseFunc, error)

	// Acquire acquires a name for the given family, and returns it.
	// Thanks to a global lock, a given name cannot be acquired twice for
	// the same family without having been released first.  After being
	// acquired, a name must be kept alive, otherwise it can automatically
	// released after a certain time.  The automatic release is
	// backend-specific.
	Acquire(family string) (string, error)

	// KeepAlive produces a heart beat to avoid a name being automatically
	// released after a certain time.  KeepAlive helps to avoid zombies.
	// Note that automatic release does NOT have to be implemented by a
	// backend.
	KeepAlive(family, name string) error

	// Release releases a name previously registered for a family.
	// It is not an error to release a name that has already been released,
	// or that was never acquired in the first place.  A name that has
	// be released can be acquired again.
	Release(family, name string) error

	// TryAcquire tries to hold a specific name.  It fails with ErrInUse
	// if the name has already been acquired and not yet released.
	// Errors occurring during the keep-alive are sent to
	// an error channel.
	TryHold(family, name string) (<-chan error, ReleaseFunc, error)

	// TryAcquire tries to acquire a specific name.  It fails with
	// ErrInUse if the name has already been acquired and not yet released.
	// It fails with ErrNotExist if the name has not already been acquired
	// at least once.
	//
	// A name acquired through TryAcquire should be kept alive with
	// KeepAlive, then released with Release, the same way it is done
	// with Acquire.
	//
	// TryAcquire can be useful, e.g., for garbage collection.
	// (Just combine List with TryAcquire).
	TryAcquire(family, name string) error

	// List lists the names that are currently registered, either marked as
	// `free` or not.
	List() ([]Name, error)

	// Reset deregister all the names.  After this call, `List` returns
	// `nil`.
	Reset() error
}

type ReleaseFunc func() error