API: Allow user to set peer allocations for pinning

[kishansagathiya]

Added support for allocations query value in POST /pins/<cid>
endpoint
allocations will be a comma-separated list of peer ids to which we want
to pin.
allocations will be prioritized over other query values of similar
effect such as replication factor, replication factor min and
replication factor max

• support this in command as well
• tests

Fixes #646

[coveralls]

Coverage decreased (-0.6%) to 65.049% when pulling 336e639 on issue_646 into a244af9 on master.

[hsanjuan]

Will need client and api tests (I don't remember if ipfscluster_test.go does something with priority allocations, but I would expect so since I think they are used in sharding.

[hsanjuan]

Move flag after replication factor.

[hsanjuan]

Per the PinPath PR, I'm thinking how to best integrate Allocations as part of PinOptions.

One way would be to move Allocations to PinOptions. Since it's an array of peer IDs, we will want to have PinOptionsSerial in which it becomes an array of strings. As with other types, we will need methods to convert between them. This will cascade to api.PinSerial (which will need to carry PinOptionsSerial instead of PinOptions), and eventually will need a PinPathSerial in the same way.

Another way would be to add a UserAllocations []peer.ID field. peer.ID are actually a string (a byte slice casted into a string actually). This is perfectly serializable, however we cannot spit it out of the API without calling something like PeersToStrings() first. We could however, have PinOptions implement json.Marshaler and json.Unmarshaler interface and this will make sure it spitted out correctly out of the API. This is similar to what we started doing with the Metric type.

Therefore, for the moment, I'm leaning towards the latter option. Also, keeping separate user-selected allocations and system-given ones seems useful as it allows us to compare if the requested ones were fulfilled.

[hsanjuan]

I just checked and peer.ID implements JSON marshable interfaces, so it may work "as is", leaving UserAllocations as []peer.ID, but needs testing.

[lanzafame]

@hsanjuan has already said all that needs to be said at this point.

[kishansagathiya]

@hsanjuan
In situations when replication factor and allocations don't match, say replication factor is 2, but allocations have more than 2 peers, which one should take priority? Allocations? or error out?

[hsanjuan]

@hsanjuan
In situations when replication factor and allocations don't match, say replication factor is 2, but allocations have more than 2 peers, which one should take priority? Allocations? or error out?

The allocator code will choose enough allocations to satisfy the replication factor. Replication factor has priority.

[hsanjuan]

LGTM. Thanks!

[hsanjuan]

Let's wait for #681 to be merged.