krpc-0.5.0.0: KRPC protocol implementation

Portabilityportable
Stabilityexperimental
Maintainerpxqr.sta@gmail.com
Safe HaskellSafe-Inferred

Network.KRPC.Message

Contents

Description

KRPC messages types used in communication. All messages are encoded as bencode dictionary.

Normally, you don't need to import this module.

See http://www.bittorrent.org/beps/bep_0005.html#krpc-protocol

Synopsis

Transaction

type TransactionId = B.ByteStringSource

This transaction ID is generated by the querying node and is echoed in the response, so responses may be correlated with multiple queries to the same node. The transaction ID should be encoded as a short string of binary numbers, typically 2 characters are enough as they cover 2^16 outstanding queries.

Error

data ErrorCode Source

Types of RPC errors.

Constructors

GenericError

Some error doesn't fit in any other category.

ServerError

Occur when server fail to process procedure call.

ProtocolError

Malformed packet, invalid arguments or bad token.

MethodUnknown

Occur when client trying to call method server don't know.

Instances

data KError Source

Errors are sent when a query cannot be fulfilled. Error message can be send only from server to client but not in the opposite direction.

Constructors

KError 

Fields

errorCode :: !ErrorCode

the type of error;

errorMessage :: !B.ByteString

human-readable text message;

errorId :: !TransactionId

match to the corresponding queryId.

Instances

Eq KError 
Ord KError 
Read KError 
Show KError 
Typeable KError 
Exception KError 
BEncode KError

Errors, or KRPC message dictionaries with a "y" value of "e", contain one additional key "e". The value of "e" is a list. The first element is an integer representing the error code. The second element is a string containing the error message.

Example Error Packet: 

 { "t": "aa", "y":"e", "e":[201, "A Generic Error Ocurred"]}

or bencoded: 

 d1:eli201e23:A Generic Error Ocurrede1:t2:aa1:y1:ee

serverError :: SomeException -> TransactionId -> KErrorSource

Happen when some query handler fail.

decodeError :: String -> TransactionId -> KErrorSource

Received queryArgs or respVals can not be decoded.

unknownMethod :: MethodName -> TransactionId -> KErrorSource

If remote node send query this node doesn't know about then this error message should be sent in response.

unknownMessage :: String -> KErrorSource

A remote node has send some KMessage this node is unable to decode.

timeoutExpired :: TransactionId -> KErrorSource

A remote node is not responding to the our request the for specified period of time.

Query

data KQuery Source

Query used to signal that caller want to make procedure call to callee and pass arguments in. Therefore query may be only sent from client to server but not in the opposite direction.

Constructors

KQuery 

Fields

queryArgs :: !BValue

values to be passed to method;

queryMethod :: !MethodName

method to call;

queryId :: !TransactionId

one-time query token.

Instances

Eq KQuery 
Ord KQuery 
Read KQuery 
Show KQuery 
Typeable KQuery 
BEncode KQuery

Queries, or KRPC message dictionaries with a "y" value of "q", contain two additional keys; "q" and "a". Key "q" has a string value containing the method name of the query. Key "a" has a dictionary value containing named arguments to the query.

Example Query packet: 

 { "t" : "aa", "y" : "q", "q" : "ping", "a" : { "msg" : "hi!" } }

type MethodName = B.ByteStringSource

Response

data KResponse Source

Response messages are sent upon successful completion of a query:

  • KResponse used to signal that callee successufully process a procedure call and to return values from procedure.
  • KResponse should not be sent if error occurred during RPC, KError should be sent instead.
  • KResponse can be only sent from server to client.

Constructors

KResponse 

Fields

respVals :: BValue

BDict containing return values;

respId :: TransactionId

match to the corresponding queryId.

Instances

Eq KResponse 
Ord KResponse 
Read KResponse 
Show KResponse 
Typeable KResponse 
BEncode KResponse

Responses, or KRPC message dictionaries with a "y" value of "r", contain one additional key "r". The value of "r" is a dictionary containing named return values.

Example Response packet: 

 { "t" : "aa", "y" : "r", "r" : { "msg" : "you've sent: hi!" } }

Message

data KMessage Source

Generic KRPC message.

Constructors

Q KQuery 
R KResponse 
E KError 

Instances