Renew return code when multiple sliver arguments

[wvdemeer]

Renew

Problem

The Renew call has an urns arguments, which can take one or more URNs. These can be slice or sliver URNs.

Note that there can be more than 1 sliver in the same slice, on the same AM. That is one of the more common reasons why this call will renew multiple slivers.
In that case, you specify the URNs if all the slivers in the slice, or you specify the slice URN itself in urns.

But the Renew call allows more than this. It allows you to specify only some of the slivers in a slice.
This is probably also a useful case.

It goes further however, you can specify slivers from different slices, multiples slices, or even a mix of slice and sliver URNs.
It is an option to forbid this, or at least not require AMs to support this. That would probably simplify things. However, the 2 previous cases still require this call to work on more than 1 sliver.

Question: Do we forbid this?

When working on more than 1 sliver, it is always possible that one sliver can
be renewed, and another can not. What to do in that case is determined by the
option geni_best_effort (new name: :best_effort). That option is false when it is omitted.

• When :best_effort is false, if any sliver cannot be renewed, no slivers will be renewed at all. (So the call is an `atomic transaction')
• When :best_effort is true, all slivers that can be renewed will be renewed. All slivers that cannot be renewed, will not be renewed. (so the call is the same as multiple independent calls)

So far, there is no problem. The problem is that is is unclear what exactly to return in such cases. Currently, a single error code is returned (just like in any call), as well as a list with a hashmap for each sliver which contains information:

AMv3 API result:

[
  {
   geni_sliver_urn: <string>,
   geni_allocation_status: <string>,
   geni_operational_status: <string>,
   geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>,
   geni_error: <optional string. The field may be omitted entirely but may not be null/None, explaining any renewal failure for this sliver>
  },
  ...
]

Proposed Solution 1

Keep output as it currently is, so do not return all information available.

Specify exactly what error code is returned when:

• When :best_effort is false, and at least one sliver failed to Renew, return ERROR (generic error code)
• When :best_effort is true, and at least one sliver succeeded to Renew, return SUCCESS
• When all slivers fail to Renew, return ERROR (generic error code)
• When all slivers succeed to Renew, return SUCCESS

Proposed Solution 2

In addition to specifying what error code is returned when, as in proposal 1, add an AM code to each sliver info in the returned hashtable. This code can be interpreted as the code that would have been returned when the Renew call had called on the sliver and nothing else.
Also, when the call returns an ERROR code, because one or all slivers cannot Renew, the value of the call should be still filled in, so that maximum info is available to the client.

Proposal 2 example (TODO: geni_ to be replaced later):

[
  {
   geni_sliver_urn: <string>,
   geni_allocation_status: <string>,
   geni_operational_status: <string>,
   geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>,
   geni_code: <code specifically for this sliver>
   geni_error: <optional string. The field may be omitted entirely but may not be null/None, explaining any renewal failure for this sliver>
  },
  ...
]

Question: Do we need a separate ERROR code for the call, which indicates
that there are multiple sub-error codes involved?

Possible extra error codes:

30 PARTIAL_SUCCESS:
This call had the :best_effort option set, and
required multiple actions. At least one action has failed, but not all. See
the result in the `value' field of this method for details on which action
was successful and which failed, including error code for each action.

31 FAILED_TRANSACTION:
This call required multiple actions and either does
not have the :best_effort set while having at least one failed action, or
it has the :best_effort set but all actions failed. Due to this, all actions
that would have been successful have been cancelled and did not occur. See
the result in the `value' field of this method for details on which actions
would have been successful and which have failed, including error code for each action.

Question: Are these error codes sufficient? Is the name ok? Is the
description ok?

[bvermeul]

I think better errors are needed ?