# Mushiny requirements

> The document contains overall structure of the protocol. Implementation MAY deviate from them within reason, i.e. changing transfer encoding to e.g. protobuf, adding additional fields, is explicitly allowed. However, your implementation MUST transfer the listed fields its semantically equivalent messages.

----

# Definitions
- Sorter is the device that sorts postings into Chutes.
- Driver is our server application that communicates with the sorter, responsible for controlling the sorter to route postings to required chutes
- Chute is a sorting destination for dropping off an item.
- Posting is a product unit moving and sorting on the sorter.

## Communication
- Bidirectional streaming protocol. e.g. GRPC streaming or [JSON streaming](https://en.wikipedia.org/wiki/JSON_streaming#Newline-delimited_JSON)

## Messages

### ChuteRequest
> Batch request Request for a Chute ID for a given posting. Contains a list of all scanned barcodes on the Posting, expects the ID of destination Chute. The message must be issued immediately after completing scanning of all Posting barcodes prior to entering it into sorting.

Fields:
- `type` (string) – MUST be `"ChuteRequest"`.
- `pid` (string) – locally unique ID of the posting, should be generated by the Sorter and used to label to all messages regarding this Posting regardless of its different barcodes.
- `barcodes` (string array) – list of barcodes scanned from the Posting.
- `tray_id` (string) – optional, identifier of the tray currently holding the Posting.

Example (json):

{
    "message_type": "ChuteRequest",
    "pid" : "61686",
    "barcodes" : ["bc0001", "-", "bc0002"],
    "tray_id": "1"
}

### ChuteReply
> Reply to `ChuteRequest`, contains the information on which Chute to drop the Parcel off to.

Fields:
- `message_type` (string) - MUST be `"ChuteReply"`.
- `pid` (integer) - as described above.
- `chute` (string) - ID of the destination chute.

Message example:

{
    "message_type": "DestReply",
    "pid": 61686,
    "chute": "1337"
}

### Sorting Outcome Report
> This report is generated by the Sorter to convey the outcome of the sorting.

Fields:

- `message_type` (string): MUST be `"SortReport"`.
- `pid` (integer): as described above.
- `chute` (string): Designates the chute where the item was deposited.
- `report` (integer): Represents the sorting status using codes from the manufacturer-provided reference, e.g.`1`: success, `2`:unknown failure, `4`: chute overcapacity, etc.

Example of the message:

{
  "message_type": "SortReport",
  "pid": 61686,
  "chute": "1337",
  "report": 1
}

### KeepAliveReq
This message is sent periodically to indicate that the TCP connection is active and the sorter is ready for operation. The sorter MUST await a corresponding response from the driver. Interval of this message CAN be set by the customer on the order of 10-15 seconds).

Fields:
- `message_type` (string) – MUST be `"KeepAliveReq"`.

Message example (json):

{
    "message_type": "KeepAliveRequest"
}

### KeepAliveReply
> Driver response to `KeepAliveReq` from the sorter.

Fields:
- `message_type` (string) – MUST be `"KeepAliveReply"`.

Message example (json):

{
    "message_type": "KeepAliveReply"
}

### ChuteState
> A message that MAY be sent to report the condition and capacity of a Chute. Manufacturer SHOULD define the possible states and how often to transmit this information. Common states might include: chute is empty (normal operation), chute is full (requires attention). This message is intended to aid in troubleshooting sorting issues.

Possible fields:

- `message_type` (string) – MUST be `"ChuteState"`.
- `chute` (string) – ID of the Chute this message describes.
- `state` (integer) – current state of the Chute.

Message example:

{
    "message_type": "ChuteState",
    "chute": "1337",
    "state": 1
}

### SorterState
A message that MAY be sent to report the condition of the Sorter. If used, the manufacturer SHOULD define the possible states and the interval at which these messages are sent. For instance, possible states may indicate that the sorter is operational, stopped, or in another state.

Possible fields:
- `message_type` (string) – MUST be `"SorterState"`.
- `state` (integer) – a number representing the sorter's current state.

Example of the message:

{
    "message_type": "SorterState",
    "state": 1 // For example, "ok" indicates everything is functioning normally.
}