(* O'Caml Freenet Client Protocol client module                     *)
(* by Travis Bemann and Eric Norige                                 *)
(*                                                                  *)
(* This program is free software; you can redistribute it and/or    *)
(* modify it under the terms of the GNU Lesser General Public       *)
(* License as published by the Free Software Foundation; either     *)
(* version 2 of the License, or (at your option) any later version. *)
(*                                                                  *)
(* This program is distributed in the hope that it will be useful,  *)
(* but WITHOUT ANY WARRANTY; without even the implied warranty of   *)
(* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the    *)
(* GNU Lesser General Public License for more details.              *)

type fcp_value = 
    VString of string 
  | VInt of int

type fcp_param = string * fcp_value

type fcp_mesg = 
    Small of string * fcp_param list  
        (* Small messages don't have a trailing data field *)
  | Large of string * fcp_param list * string
	(* FOr messages that have a trailing data field *)
  | Large_no_data of string * fcp_param list

(* Raised if connection has been closed and sending or receiving any
   any sort of data is attempted. *)
exception Closed

(* Raised if a manual download is restarted. *)
exception Restarted

(* Raised if a manual operation is completed. *)
exception Finished

(* Raised if a URI is invalid in format; returns the invalid URI*)
exception Uri_error of string

(* Raised if data in Freenet cannot be found *)
exception Data_not_found

(* Raised if a route in Freenet cannot be found *)
exception Route_not_found of fcp_mesg

(* Raised if inserted data collides with a preexisting key *)
exception Key_collision of string

(* Raised if data is over 32K in length of any non-CHK key *)
exception Size_error

(* Raised if connecting to node fails. *)
exception Connect_error

(* Raised if sending or receiving data to or from node fails. *)
exception Io_error

(* Raised if a node message has an improper format *)
exception Node_format_error of string

(* Raised if the node signals that a client message has an improper
   format - indicative of either the version of FCP implemented is
   obsolete or there is a bug in the Freenet node, or there is a bug
   in this module *)
exception Format_error of string

(* Raised if the node signals that it has had a major internal
   error *)
exception Node_error of string

(* Raised if a message of a type that is not expected is received
   from the node - indicative of either the version of FCP implemented
   is obsolete or there is a bug in the Freenet node, or there is a
   bug in this module *)
exception Unexpected_message of string

(* FCP request transaction object                                   *)
(*                                                                  *)
(* Do not directly instantiate a request_transact object - always   *)
(* use a node object's request method to create a request_transact  *)
(* object.  Doing otherwise will result in any program that uses    *)
(* this module breaking if persistent FCP connections or some other *)
(* major change is introduced in the future.                        *)

class request_transact : Unix.file_descr -> string -> int -> object
    
  (* Cancel request - at the present unnecessary, but may be
     necessary if connection pools are introduced at some future
     date *)
  method cancel : unit

  (* Get hops to live *)
  method htl : int

  (* Get data + metadata length *)
  method len : int

  (* Get metadata length *)
  method metadata_len : int

  (* Get length of data + metadata currently downloaded *)
  method read_len : int

  (* Manually download and get a block of data and or metadata;
     close connection if request is complete and then raise
     Finished; raise Restarted if the node signals that the request
     has been restarted *)
  method recv_block : string

  (* Get data already downloaded *)
  method recv_data_prev : string

  (* Get metadata, download if not already downloaded, close
     connection if request is complete *)
  method recv_metadata : string

  (* Get URI *)
  method uri : string

end

(* FCP insert transaction object                                    *)
(*                                                                  *)
(* Do not directly instantiate an insert_transact object - always   *)
(* use a node object's insert method to create an insert_transact   *)
(* object.  Doing otherwise will result in any program that uses    *)
(* this module breaking if persistent FCP connections or some other *)
(* major change is introduced in the future.                        *)

class insert_transact : Unix.file_descr -> string -> int -> int -> int ->
  object

    (* Append string to data to insert *)
    method block : string -> unit

    (* Cancel insert - at the present unnecessary, but may be
       necessary if connection pools are introduced at some future
       date *)
    method cancel : unit

    (* Get hops to live *)
    method htl : int

    (* Append string to metadata to insert *)
    method metadata_block : string -> unit

    (* Get URI *)
    method uri : string

    (* Wait for a single insertion response message; return a string
       option containing the original, or generated in the case of 
       CHK@ and freenet:CHK@, URI if a Success message is received,
       otherwise return the string option None *)
    method wait : string option

    (* Wait for insertion response messages until completion; return
       URI returned by Success message, which is a generated URI in
       the case of CHK@ and freenet:CHK@ *)
    method wait_all : string

  end

(* FCP CHK generation transaction object                            *)
(*                                                                  *)
(* Do not directly instantiate a gen_chk_transact object - always   *)
(* use a node object's generate_chk method to create a              *)
(* gen_chk_transact object.  Doing otherwise will result in any     *)
(* program that uses this module breaking if persistent FCP         *)
(* connections or some other major change is introduced in the      *)
(* future.                                                          *)

class gen_chk_transact :
  Unix.file_descr -> int -> int ->
  object

    (* Append string to data to generate CHK from *)
    method block : string -> unit

    (* Cancel CHK generation - at the present unnecessary, but may be
       necessary if connection pools are introduced at some future
       date *)
    method cancel : unit

    (* Get generated CHK; note that the first time this is executed
       the connection must be open; if connection is open, close
       connection *)
    method generate_chk : string

    (* Append string to metadata to generate CHK from *)
    method metadata_block : string -> unit

  end

(* FCP SVK pair generation connection object                        *)
(*                                                                  *)
(* This class is used by node objects' generate_svk method, and     *)
(* there is no real reason to use this directly.  Also note that    *)
(* using the generate_svk method is more likely to be backwards     *)
(* compatible in future versions of this module than using this     *)
(* directly.                                                        *)

class gen_svk_pair_transact :
  Unix.file_descr ->
  object
(*    val connect : Unix.file_descr *)
    val mutable opened : bool
    val mutable prk : string option
    val mutable pbk : string option

    (* Cancel SVK generation - at the present unnecessary, but may be
       necessary if connection pools are introduced at some future
       date - but then, one shouldn't be directly calling this,
       anyways *)
    method cancel : unit

    (* Get generated SVK private key; note that the first time this or
       public_key is executed the connection must be open; if
       connection is open, close connection *)
    method private_key : string

    (* Get generated SVK public key; note that this first time this or
       private_key is executed the connection must be open; if
       connection is open, close connection *)
    method public_key : string
  end

class node :
  string ->
  int ->
  object

    (* Create a CHK generation transaction for a given metadata and *)
    (* data length *)
    method generate_chk : metadata_len:int -> data_len:int ->
      gen_chk_transact

    (* Create an SVK pair (private, public) - NOT an SVK pair
       generation transaction, although one of these is used in the
       implementation of this method *)
    method generate_svk : string * string

    (* Create an insert transaction from a URI, a hops to live *)
    (* value, a metadata length, and a data length. *)
    method insert : uri:string -> htl:int -> metadata_len:int ->
       data_len:int -> insert_transact

    (* Create a request transaction from a URI and a hops to live *)
    (* value. *)
    method request : uri:string -> htl:int -> request_transact
  end