Expose consistent client method set

[eapache]

The Client object has basically no public methods right now, it is just a place to dump methods (mostly broker and metadata tracking) that are shared by the Consumer and the Producer. Its primary functions should have specific semantics defined and then be published so other people can make use of them.

Probably depends on getting #15 right first...

I'm thinking (as a rough first draft):

• Leader(topic, partition) returns the broker object leading the topic/partition
• Topics() returns the list of topics for the cluster
• Partitions(topic) returns the list of partitions for the topic
• RefreshMetadata(topics[])

Open Questions:

• Does it make sense to store/return other metadata (replicas or ISRs, for example)? Does any of this provide benefit beyond just sending a MetadataRequest using the low-level Broker object?
• How are brokers returned to the client when no longer needed? (the current disconnectBroker feels hacky, this really depends on Better Broker Connection Management #15)
• Do we want to provide RefreshTopic(topic) or RefreshAllTopics() helper functions or something like that?
• Does it make sense to expose any()? It's only useful for metadata, so this probably depends if we expose all metadata or if a user might want to get it themselves.

[eapache]

While poking around various implementations of #18 I finally figured out what I want to do with disconnectBroker (ie how to get rid of it). It really has two purposes:

• it forces a metadata refresh to happen on the next client request for that broker (ie call to Leader or similar)
• even if the metadata isn't stale, it bounces the broker connection so that (for example) a stale connection to the correct broker is put back in a good state

The metadata refresh we can already force with a call to one of the public Refresh methods. The connection bounce is interesting, because I originally added this comment to the client.update method: "[if the broker hasn't changed] ignore it, replacing our existing one would just bounce the connection". However if we make the metadata refresh safely bounce connections for any broker that isn't stale we could in principle replace all "public" calls to disconnectBroker with straight calls to RefreshTopicMetadata.

We still have one internal call to it that would need dealing with (perhaps it just gets folded into the any method?) and parts of it are still tangled up in #15 but I think I've made progress in at least understanding the problem space.

[eapache]

All of the methods I started this ticket for have been created (a while ago, in most cases). The only open question is broker disconnection, which is still better-tracked by #15. This can be closed.