Using servers

As we explain in the system abstraction section, the first level of anchors below the root (those that have paths like /Xf1c8d96119cc6919) correspond to live hosts and we call them server anchors.

Server anchors are automatically created and removed by the circuit system to reflect the addition and removal (or death) of hosts.

Every server anchors has a permanently attached server element. Server elements are objects whose methods allow you to retrieve some basic information about the underlying host as well as the circuit daemon the manages the host.

The server element for a given path can be accessed like any other element. For instance,

	srv := root.Walk([]string{"Xf1c8d96119cc6919"})

Server elements implement the Server interface:

	type Server interface {
		Profile(string) (io.ReadCloser, error)
		Peek() ServerStat
		Rejoin(string) error
		Suicide()
	}

Retrieving server information

The Peek method will return a structure containing the circuit address of this server (which is a string of the form circuit://…), and the time the server was launched according to the host's clock.

	type ServerStat struct {
		Addr   string
		Joined time.Time
	}

Server elements cannot be scrubbed.

Merging circuit clusters

The method Rejoin takes one argument which is expected to be a target circuit address—i.e. a string of the form circuit://…. Circuit addresses are a way of connecting to a circuit daemon directly.

Rejoin will cause the circuit daemon (underlying the server element) to perform a join procedure with the target circuit daemon, specified by a circuit address. This will result in merging this entire circuit cluster with the circuit cluster of the target. If the target is already part of the same circuit cluster, no change will occur.

Miscellaneous

The method Suicide will cause the circuit daemon, at the host corresponding to the server element, to terminate itself.

The method Profile will return profiling information for the circuit daemon itself. Its argument specifies the name of the desired profile in the sense of the Go package runtime/pprof.