repo-ng

Watched Prefix Insertion Protocol

=================================

Watched Prefix is a new protocol for repo insertion. By using this protocol, repo keep sending interests to request the data with same prefix. When a data packet is received, repo will update selectors (exclude selector in most cases) to exclude the received data and request new one. Repo will stop watching the prefix until a command interest in tell it to stop, the total amount of sent interests reaches a specific number or time out.

## Basic operations

### Start watched prefix insertion

Command verb: **watch start**

The name semantics follows the format of the [[Repo Command]]. The <command verb> is defined as ``watch``.

For example, for ``<repo prefix>`` as ``/ucla/cs/repo``, the following is an example:

    /ucla/cs/repo/watch/start/<RepoCommandParameter>/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>

The command is using the following parameters:

* ``Name`` (required)

* ``InterestLifetime`` (optional)

* ``MaxInterestNum`` (optional)

* ``WatchTimeout`` (optional)

* ``Selectors`` (optional)

Detailed description of the parameters:

* **`Name`** is the prefix that will be watched.

* **`InterestLifetime`** is the maximum latency between interest sent and data received. If the time duration is larger than interest timeout, the same interest will be resent. If data is received within the Interest timeout, the selectors of the interest will be updated and sent to request new data. If it is not specified, a default value(4000 millisecond) will be set. 

* **`MaxInterestNum`** is the maximum of total interests that can be sent. The process will stop if the total number of interests reaches this limit. If it is not specified, MaxInterestNum will be set as -1, means infinity.

* **`WatchTimeout`** is the time duration of this process. Repo will keep watching the prefix until it times out. If it is not specified, WatchTimeout will be set as 0, means this process will run forever.

* **`Selectors`** are used to exclude the received data and request new data.

### Watch status check

Command verb: **watch check**

During the watched prefix progress, requester could send watch status check command to check the status of the progress. This status check command is also [[Repo Command]]. The semantics of watch status check command is shown as follows:

    /ucla/cs/repo/watch/check/<RepoCommandParameter>/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>

The command is using the following parameters:

* ``Name`` (required)

Detailed description of the parameters:

* **`Name`**  is the prefix which is being watched.

### Stop watched prefix insertion

Command verb: **watch stop**

During the watched prefix progress, requester could send watch stop command to stop the watched prefix insertion. The stop command is also a [[Repo Command]].

    /ucla/cs/repo/watch/stop/<RepoCommandParameter>/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>

## RepoCommandResponse

This watch status data object could be the response data object of both watch command and watchCheck command. It will follow the format of repo command response.

Response has two part:InsertNumber, indicates how many data packets under the watched prefix has been inserted into repo; 

StatusCode, indicates the status of the process.

StatusCode Definition:

``StatusCode`` | Description

-------------- | ----------------------------------------------

``100``        | The command is OK. Start to watch the prefix

``101``        | Watched Prefix Insertion is stop.

``300``        | This watched prefix Insertion is in progress

``401``        | This watch command or watchCheck command is invalidated

``402``        | BlockId present. BlockId is not supported in this protocol

``403``        | Malformed Command

``404``        | No such this process is in progress

## Protocol Process

### Repo watch start command process:

1. Start to validate the command. If it is validated, go to Step 3, otherwise go to Step 2.

2. Send a negative response indicating validation failure, and abort these steps, process ends (StatusCode: 401).

3. Check parameters. If it cannot be extracted from interest, send a negative response(StatusCode: 403) and stop process.

4. If it has BlockId, send a negative response(StatusCode: 402) and stop process.

5. Use parameter of the command interest to construct interest. Set the Rightmost Child Selector.

6. Send the interest and start timer. The number of sent interest plus 1(the initial value is 0).

7. If received a data, go to Step 8, if times out, go to Step 17.

8. If data is validated, go to Step 9, otherwise, go to Step 15.

9. Check whether the watched prefix insertion is still running. If it does not, process ends.

10. If the process times out(exceed watch timeout) or if total number of sent interest reaches limit, go to Step 11, otherwise go to Step 12.

11. Clear all the variables(the number of sent interest, watch timeout, interest lifetime), abort these steps, process ends.

12. Store the data into repo.

13. Update selectors, exclude from min to the received one and use the updated selectors construct new interest. 

14. Send new interest and the number of sent interest plus 1, and then go to Step 7.

15. Repeat Step 9 to 11 and skip Step 12.

16. Update selectors, only exclude the received data(since other data whose name is smaller may be satisfied), then go to Step 14.

17. Repeat Step 9 to 11 and skip Step 12.

18. Send the interest again and the number of sent interest plus 1, and then go to Step 7.

### Repo watch check command process:

1. Start to validate the check command. If it is validated, go to Step 3, otherwise, go to Step 2.

2. Send a negative response indicating validation failure, and abort these steps, process ends (StatusCode: 401).

3. Check parameter. If it cannot extracted from interest or if it does not have the name to be checked, send a negative reply(StatusCode: 403).

4. Check whether the process is existed. If it does, go to Step 5, otherwise, send a negative reply(StatusCode: 404).

5. Use the processId to find the response and send the response back.

### Repo watch stop command process:

1. Start to validate the stop command. If it is validated, go to Step 3, otherwise, go to Step 2.

2. Send a negative response indicating validation failure, and abort these steps, process ends (StatusCode: 401).

3. Check parameter. If it cannot extracted from interest, send a negative reply(StatusCode: 403).

4. Stop the process and send a negative reply (StatusCode: 101).