StorNet BeStMan-to-TeraPaths Interface Specification

• Oct 20, 2009, modified Aug 11, 2011
• Junmin Gu, Arie Shoshani, Alex Sim
• Support: srmlbl.gov

Introduction

The purpose if this interface is to specify the communication between BeStMan and TeraPaths when negotiating a bandwidth request. After BeStMan determines the maximum bandwidth it can use, it needs to communicate with TeraPaths, providing total volume, maximum bandwidth, and maximum completion time desired by the user. TeraPaths is expected to return with a bandwidth-time window if one can be found that terminate before the requested completion time, or return failure.

In case of a failure, BeStMan can request Terapaths to find a window that goes beyond the max completion time (by not specifying a max completion time), and this can be returned as an alternative to the user, who may accept or reject it. This possibility will not be exercised at first, but only as a second step of the implementation, but the interface is designed to accommodate that by allowing max completion time to be unspecified (i.e. open ended).

_DISCLAIMER_

Time

• Time is represented in long.

CompletionTime

• It is measured in seconds.
• A value that is equals to or less than zero implies no restriction on completion time.

Bandwidth

• Network bandwidth is measured in kbps (kilo bits per second).

Type Definitions

• Underlined attributes are REQUIRED. The required attributes must be parsed correctly and must give proper error messages when not supported.

ESchedulePreference

• enum:
• ANY
• EARLIEST_COMPLETION_TIME
• SHORTEST_TRANSFER_DURATION

• A user can indicate prefrence on how the requests shall be handled.

TRequestReference

• typedef struct
• String requestId,
• String userId

• This structure is used to refer to a request to TeraPaths. It is the input of the request handling functions like commitCommit(), cancelReqeust() etc.
• userId is a user-supplied id for authorization by TeraPaths.

TReserveRequest

• typedef struct
• String userId,
• TBandwidthRequestParameters desiredValues,
• long timeout,
• ESchedulePreference schedulePreference

• This structure is used to construct the reservation request to TeraPaths. It is the input of the function reserveRequest().
• userId is a user-supplied id for authorization by TeraPaths. The transfer related parameters are contained in the structure TBandwidthRequestParameters.
• The input value "timeout" is for client to specify how long the preferred wait time that the client needs upon knowing a temporary reservation being made to finally commit the reservation.

TResponse

• typedef struct
• TReturnStatus status,
• String requestId,
• long requestExpirationTime,
• TBandwidthRequestParameters[] arrayOfReservationData

• This structure is used by TeraPaths to respond to a reservation request. It is the output of the function cancelRequest(), commitRequest(), modifyRequest(), reserveRequest() and extendTimeoutRequest().
• TeraPaths server must return a status to all the function calls.
• Upon success for a reserveRequest(), TeraPaths must return:
• the values that are reserved for this client in arrayOfReservationData,
• a request id "requestId" if involved, so the client can later cancel this reservation (through BeStMan) if desired.
• If the request cannot be processed right away, TeraPaths must return
• a request id "rid" so the client can use it to check status (through BeStMan).

TReturnStatus

• typedef struct
• EStatusCode code,
• String explanation

• A return status is used for the status of a reservation request.
• return status consists of a code, which is described by TStatusCode, and the explanation.

E StatusCode

• enum
• ACTIVATED
• CANCELLED
• EXPIRED
• FAILURE
• NO_AUTHORIZATION,
• NO_SOLUTION
• NO_SUCH_REQUEST,
• NOT_SUPPORTED,
• QUEUED,
• RESERVED
• TEMPORARY
• TIMED_OUT

• If a reservation is made within the client's desired parameters, the status code is TEMPORARY. A request id is expected in this case. Client is expected to call commitRequest() within a given time to confirm with the reservation. Once committed successfully, the status is set to RESERVED. If commitRequest was not called timely, the status of the request will be TIMED_OUT.
• Once the status is RESERVED, client is advised to check status again, until, the status becomes ACTIVATED. This indicates the bandwidth reservation is materialized with the underlying system. Client can now use the bandwidth.
• If a reservation can not be processed right away, the status code shall set to be QUEUED and a request id is provided. Clients are expected to pull status periodically until a final status is reached.
• NO_SUCH_REQUEST is returned from getReservationStatus() for a request id that is not currently active (QUEUED or RESERVED).

TBAGInfo

• typedef struct
• long segmentBandwidth,
• long segmentEndTime,
• long segmentStartTime

TFlowInfo

• typedef struct
• String key,
• String value

TBandwidthRequestParameters

• typedef struct
• TBagInfo[] bagInfo
• long volumn,
• TFlowInfo[] flowInfo

• A client provides desired begin time (optional), volume in MB (required), max bandwidth (required), max completion time (optional) to TeraPaths along with source and destination hosts to get a reservation for file transfer.
• Bandwidth is measured in kbps (kilo bits per second). See Disclaimer.
• maxCompletionTime is measured in seconds. See Disclaimer.

TBandwidthResponseParameters

• typedef struct
• long availableBandwidth,
• long beginTime,
• long endTime,
• TFlowInfo[] flowInfo,
• String reservationId,
• String reservationStatus

TModifyRequest

• typedef struct
• String requestId,
• String uid,
• TReservationModifcationSet[] modificationSet

TReservationModificationSet

• typedef struct
• String reservationId,
• TReservationModificationParameters[] modificationParameters

TReservationModificationParameters

• typedef struct
• String modificationOperation,
• TModificationInfo modificationInfo

TModificationInfo

• typedef struct
• String key,
• String value

Function Definitions

reserveRequest

• in:
• TReserveRequest reserveRequest
• out:
• TResponse reserveResponse

• The output of this function contains: status code (mandatory), request id (if reservation were made) and reserved values (if reservation were made.)
• The status code NOT_SUPPORTED is not applicable here.
• The request id is expected if the status codes returned are one of QUEUED and TEPORARY.

commitRequest

• in:
• TRequestReference request
• out:
• TResponse response

• Client needs to call this function to confirm to TeraPath to reserve the solution provided by the outcome of reserveRequest().

modifyRequest

• in:
• TModifyRequest modifyRequest
• out:
• TResponse response

• The client uses this function to make changes to the reserved request.

extendTimeOutRequest

• in:
• TRequestReference request
• out:
• TResponse response

• If unable to call commitRequest() within the time specified from the outcome of resreveRequest(), client can use this function to extend the timeout.

statusRequest

• in:
• TRequestReference request
• out:
• TResponse status response

• The status of a reservation, as with the output of the reserveRequest() function, contains: status code (mandatory), request id (if reservation were made) and reserved values (if reservation were made.)
• All the status codes defined in TStatusCode are possible to be returned. Notice that if the reserveRequest() is implemented as a synchronized function in TeraPaths, then NOT_SUPPORTED can be returned for this function.
• If a reservation with the specified rid is expired, FAILURE can be returned with an explanation.

cancelRequest

• in:
• TRequestReference request
• out:
• TResponse status response

• Client calls this function to cancel a reservation with the specified rid (through BeSMan).
• If there is a valid reservation with this rid, TeraPaths is expected to honor the cancelation.
• If the request with this rid is still queued, TeraPaths shall stop processing the request.
• In other cases, for example, the request does not exist at all, or the reservation with this rid is already expired, TeraPaths takes no action.

Use Case Scenario

• Client calls reserveRequest() with uid, desired starting time (optional), data volume, maximum completion time (optional), source and target.
• TeraPaths tries to find a match and reply to the client. If it can not answer right away, it can choose to return QUEUED status with a request id "rid". User will poll status with getReservationStatus(rid) until request is processed.
• Possible outcomes are:
• If user is not authorized, NOT_AUTHORIZED is returned as status code
• If TeraPaths cannot honor the request for any other reasons, the status code to use is NO_SOLUTION and an explanation is encouraged to be included in the return status from TeraPaths.
• If a match is made that satisfies client's input parameters, TeraPaths reserves right away, with a rid assigned to the client, and this reservation will expired after a timeout. The corresponding status code is TEPORARY. The reservation details are returned to the client, along with a time within which commitRequest() shall be called. BeStMan will call commitRequest() and upon success, then continues with file transfer.
• Otherwise, BeStMan might try to reserve with alternative parameters (e.g. a later beginTime, and double the maxCompletionTime) and see if a reservation can be made. If so, it will get back to the user. Once the user acknowledges, the actual file transfer will then start. Otherwise, this reservation will be canceled by BeStMan.
• If a match can not be made for any other reason, TeraPaths returns with status code FAILURE with an explanation.