package sd (take 2)

[peterbourgon]

Iteration on #235.

Package loadbalancer is deleted, replaced by package sd. What was previously loadbalancer.Publisher becomes sd.Subscriber, which I believe better reflects its purpose. That is, the sd/consul.Subscriber is subscribing to updates from Consul.

// Subscriber listens to a service discovery system and yields a set of
// identical endpoints on demand. An error indicates a problem with connectivity
// to the service discovery system, or within the system itself; a subscriber
// may yield no endpoints without error.
type Subscriber interface {
    Endpoints() ([]endpoint.Endpoint, error)
}

Additionally, we introduce a new type, sd.Registrar, responsible for advertising the lifecycle of the Go kit service into the corresponding service discovery system. That is, sd/consul.Registrar registers instances to Consul.

// Registrar registers instance information to a service discovery system when
// an instance becomes alive and healthy, and deregisters that information when
// the service becomes unhealthy or goes away.
//
// Registrar implementations exist for various service discovery systems. Note
// that identifying instance information (e.g. host:port) must be given via the
// concrete constructor; this interface merely signals lifecycle changes.
type Registrar interface {
    Register()
    Deregister()
}

This is optional, as many users prefer to or must have their orchestration system manage entries in their service discovery system. But for those users who do self-registration, this will be useful. Addresses #167.

A few additional changes:

• The Consul implementation was refactored, and sd/consul.Publisher added
• The endpoint cache was simplified and moved to sd/cache
• Load balancers and helpers are moved to package sd/lb

The checklist before this PR is mergeable:

• Refactor sd.Subscriber to yield individual endpoint.Endpoints
• Port sd.Registrar + implementations
• Use new endpoint cache, Consul subscriber implementation, and other mechanical bits
• Refactor addsvc example
• Refactor profilesvc example, adding a client package
• Refactor apigateway example
• Make minimum changes necessary to shipping example
• Update examples/README + refactor stringsvc examples
• Delete package loadbalancer

Once this is merged I will file issues for:

• Add sd/etcd.Publisher
• Add sd/zk.Publisher

[basvanbeek]

maybe we should test for a "real" error (overflow) to signal people that even the simplest method probably has real exceptions / error conditions so they don't think to lightly about proper error handling for every method

[basvanbeek]

something quick I came up with for the above mentioned comments...

const (
    intMax = 1<<31 - 1
    intMin = -(intMax + 1)
    maxLen = 102400
)

// Service Method Errors
var (
    ErrIntOverflow     = errors.New("integer overflow")
    ErrMaxSizeExceeded = errors.New("result exceeds maximum size")
)

// Sum implements Service.
func (s basicService) Sum(_ context.Context, a, b int) (int, error) {
    if (b > 0 && a > (intMax-b)) || (b < 0 && a < (intMin-b)) {
        return 0, ErrIntOverflow
    }
    return a + b, nil
}

// Concat implements Service.
func (s basicService) Concat(_ context.Context, a, b string) (string, error) {
    if len(a)+len(b) > maxLen {
        return "", ErrMaxSizeExceeded
    }
    return a + b, nil
}

[ChrisHines]

Can you use endpoint.Chain to compose this sequence?

[peterbourgon]

Absolutely, but I find this way — working from the inside out, with multiple expressions — more intuitive. (I added endpoint.Chain by request, at some point.)

[ChrisHines]

I also find using multiple expressions more intuitive. I argued for simplifying our APIs in that direction way back in ancient history (#14 (comment)). I wonder if the middleware abstraction has really proved worth it if the only real use of it (endpoint.Chain) is avoided because it is less intuitive.

For reference: endpoint.Chain was designed in the discussion on #95 and implemented in it's current form in #96.

[peterbourgon]

This is now ready for review, if anyone would care to give it a look. Refactoring addsvc and profilesvc took much longer than anticipated; the upside is I'm very happy with the state of those examples, now, and I think they will be very educating, especially to new users.