"""
Interfaces which are implemented by various classes within LBRYnet.
"""
from zope.interface import Interface


class IPeerFinder(Interface):
    """
    Used to find peers by sha384 hashes which they claim to be associated with.
    """
    def find_peers_for_blob(self, blob_hash):
        """
        Look for peers claiming to be associated with a sha384 hashsum.

        @param blob_hash: The sha384 hashsum to use to look up peers.
        @type blob_hash: string, hex encoded

        @return: a Deferred object which fires with a list of Peer objects
        @rtype: Deferred which fires with [Peer]
        """


class IRequestSender(Interface):
    """
    Used to connect to a peer, send requests to it, and return the responses to those requests.
    """
    def add_request(self, request):
        """
        Add a request to the next message that will be sent to the peer

        @param request: a request to be sent to the peer in the next message
        @type request: ClientRequest

        @return: Deferred object which will callback with the response to this request, a dict
        @rtype: Deferred which fires with dict
        """

    def add_blob_request(self, blob_request):
        """
        Add a request for a blob to the next message that will be sent to the peer.

        This will cause the protocol to call blob_request.write(data) for all incoming
        data, after the response message has been parsed out, until blob_request.finished_deferred fires.

        @param blob_request: the request for the blob
        @type blob_request: ClientBlobRequest

        @return: Deferred object which will callback with the response to this request
        @rtype: Deferred which fires with dict
        """


class IRequestCreator(Interface):
    """
    Send requests, via an IRequestSender, to peers.
    """

    def send_next_request(self, peer, protocol):
        """
        Create a Request object for the peer and then give the protocol that request.

        @param peer: the Peer object which the request will be sent to.
        @type peer: Peer

        @param protocol: the protocol to pass the request to.
        @type protocol: object which implements IRequestSender

        @return: Deferred object which will callback with True or False depending on whether a Request was sent
        @rtype: Deferred which fires with boolean
        """

    def get_new_peers(self):
        """
        Get some new peers which the request creator wants to send requests to.

        @return: Deferred object which will callback with [Peer]
        @rtype: Deferred which fires with [Peer]
        """


class IMetadataHandler(Interface):
    """
    Get metadata for the IDownloadManager.
    """
    def get_initial_blobs(self):
        """
        Return metadata about blobs that are known to be associated with the stream at the time that the
        stream is set up.

        @return: Deferred object which will call back with a list of BlobInfo objects
        @rtype: Deferred which fires with [BlobInfo]
        """

    def final_blob_num(self):
        """
        If the last blob in the stream is known, return its blob_num. Otherwise, return None.

        @return: integer representing the final blob num in the stream, or None
        @rtype: integer or None
        """


class IDownloadManager(Interface):
    """
    Manage the downloading of an associated group of blobs, referred to as a stream.

    These objects keep track of metadata about the stream, are responsible for starting and stopping
    other components, and handle communication between other components.
    """

    def start_downloading(self):
        """
        Load the initial metadata about the stream and then start the other components.

        @return: Deferred which fires when the other components have been started.
        @rtype: Deferred which fires with boolean
        """

    def resume_downloading(self):
        """
        Start the other components after they have been stopped.

        @return: Deferred which fires when the other components have been started.
        @rtype: Deferred which fires with boolean
        """

    def pause_downloading(self):
        """
        Stop the other components.

        @return: Deferred which fires when the other components have been stopped.
        @rtype: Deferred which fires with boolean
        """

    def add_blobs_to_download(self, blobs):
        """
        Add blobs to the list of blobs that should be downloaded

        @param blobs: list of BlobInfos that are associated with the stream being downloaded
        @type blobs: [BlobInfo]

        @return: DeferredList which fires with the result of adding each previously unknown BlobInfo
            to the list of known BlobInfos.
        @rtype: DeferredList which fires with [(boolean, Failure/None)]
        """

    def stream_position(self):
        """
        Returns the blob_num of the next blob needed in the stream.

        If the stream already has all of the blobs it needs, then this will return the blob_num
        of the last blob in the stream plus 1.

        @return: the blob_num of the next blob needed, or the last blob_num + 1.
        @rtype: integer
        """

    def needed_blobs(self):
        """
        Returns a list of BlobInfos representing all of the blobs that the stream still needs to download.

        @return: the list of BlobInfos representing blobs that the stream still needs to download.
        @rtype: [BlobInfo]
        """

    def final_blob_num(self):
        """
        If the last blob in the stream is known, return its blob_num. If not, return None.

        @return: The blob_num of the last blob in the stream, or None if it is unknown.
        @rtype: integer or None
        """

    def handle_blob(self, blob_num):
        """
        This function is called when the next blob in the stream is ready to be handled, whatever that may mean.

        @param blob_num: The blob_num of the blob that is ready to be handled.
        @type blob_num: integer

        @return: A Deferred which fires when the blob has been 'handled'
        @rtype: Deferred which can fire with anything
        """


class IConnectionManager(Interface):
    """
    Connects to peers so that IRequestCreators can send their requests.
    """
    def get_next_request(self, peer, protocol):
        """
        Ask all IRequestCreators belonging to this object to create a Request for peer and give it to protocol

        @param peer: the peer which the request will be sent to.
        @type peer: Peer

        @param protocol: the protocol which the request should be sent to by the IRequestCreator.
        @type protocol: IRequestSender

        @return: Deferred object which will callback with True or False depending on whether the IRequestSender
            should send the request or hang up
        @rtype: Deferred which fires with boolean
        """

    def protocol_disconnected(self, peer, protocol):
        """
        Inform the IConnectionManager that the protocol has been disconnected

        @param peer: The peer which the connection was to.
        @type peer: Peer

        @param protocol: The protocol which was disconnected.
        @type protocol: Protocol

        @return: None
        """


class IProgressManager(Interface):
    """
    Responsible for keeping track of the progress of the download.

    Specifically, it is their responsibility to decide which blobs need to be downloaded and keep track of
    the progress of the download
    """
    def stream_position(self):
        """
        Returns the blob_num of the next blob needed in the stream.

        If the stream already has all of the blobs it needs, then this will return the blob_num
        of the last blob in the stream plus 1.

        @return: the blob_num of the next blob needed, or the last blob_num + 1.
        @rtype: integer
        """

    def needed_blobs(self):
        """
        Returns a list of BlobInfos representing all of the blobs that the stream still needs to download.

        @return: the list of BlobInfos representing blobs that the stream still needs to download.
        @rtype: [BlobInfo]
        """

    def blob_downloaded(self, blob, blob_info):
        """
        Mark that a blob has been downloaded and does not need to be downloaded again

        @param blob: the blob that has been downloaded.
        @type blob: Blob

        @param blob_info: the metadata of the blob that has been downloaded.
        @type blob_info: BlobInfo

        @return: None
        """


class IBlobHandler(Interface):
    """
    Responsible for doing whatever should be done with blobs that have been downloaded.
    """
    def blob_downloaded(self, blob, blob_info):
        """
        Do whatever the downloader is supposed to do when a blob has been downloaded

        @param blob: The downloaded blob
        @type blob: Blob

        @param blob_info: The metadata of the downloaded blob
        @type blob_info: BlobInfo

        @return: A Deferred which fires when the blob has been handled.
        @rtype: Deferred which can fire with anything
        """


class IRateLimited(Interface):
    """
    Have the ability to be throttled (temporarily stopped).
    """
    def throttle_upload(self):
        """
        Stop uploading data until unthrottle_upload is called.

        @return: None
        """

    def throttle_download(self):
        """
        Stop downloading data until unthrottle_upload is called.

        @return: None
        """

    def unthrottle_upload(self):
        """
        Resume uploading data at will until throttle_upload is called.

        @return: None
        """

    def unthrottle_downlad(self):
        """
        Resume downloading data at will until throttle_download is called.

        @return: None
        """


class IRateLimiter(Interface):
    """
    Can keep track of download and upload rates and can throttle objects which implement the
    IRateLimited interface.
    """
    def report_dl_bytes(self, num_bytes):
        """
        Inform the IRateLimiter that num_bytes have been downloaded.

        @param num_bytes: the number of bytes that have been downloaded
        @type num_bytes: integer

        @return: None
        """

    def report_ul_bytes(self, num_bytes):
        """
        Inform the IRateLimiter that num_bytes have been uploaded.

        @param num_bytes: the number of bytes that have been uploaded
        @type num_bytes: integer

        @return: None
        """

    def register_protocol(self, protocol):
        """
        Register an IRateLimited object with the IRateLimiter so that the IRateLimiter can throttle it

        @param protocol: An object implementing the interface IRateLimited
        @type protocol: Object implementing IRateLimited

        @return: None
        """

    def unregister_protocol(self, protocol):
        """
        Unregister an IRateLimited object so that it won't be throttled any more.

        @param protocol: An object implementing the interface IRateLimited, which was previously registered with this
            IRateLimiter via "register_protocol"
        @type protocol: Object implementing IRateLimited

        @return: None
        """


class IRequestHandler(Interface):
    """
    Pass client queries on to IQueryHandlers
    """
    def register_query_handler(self, query_handler, query_identifiers):
        """
        Register a query handler, which will be passed any queries that
        match any of the identifiers in query_identifiers

        @param query_handler: the object which will handle queries matching the given query_identifiers
        @type query_handler: Object implementing IQueryHandler

        @param query_identifiers: A list of strings representing the query identifiers
            for queries that should be passed to this handler
        @type query_identifiers: [string]

        @return: None
        """

    def register_blob_sender(self, blob_sender):
        """
        Register a blob sender which will be called after the response has
        finished to see if it wants to send a blob

        @param blob_sender: the object which will upload the blob to the client.
        @type blob_sender: IBlobSender

        @return: None
        """


class IBlobSender(Interface):
    """
    Upload blobs to clients.
    """
    def send_blob_if_requested(self, consumer):
        """
        If a blob has been requested, write it to 'write' func of the consumer and then
        callback the returned deferred when it has all been written

        @param consumer: the object implementing IConsumer which the file will be written to
        @type consumer: object which implements IConsumer

        @return: Deferred which will fire when the blob sender is done, which will be
            immediately if no blob should be sent.
        @rtype: Deferred which fires with anything
        """


class IQueryHandler(Interface):
    """
    Respond to requests from clients.
    """
    def register_with_request_handler(self, request_handler, peer):
        """
        Register with the request handler to receive queries

        @param request_handler: the object implementing IRequestHandler to register with
        @type request_handler: object implementing IRequestHandler

        @param peer: the Peer which this query handler will be answering requests from
        @type peer: Peer

        @return: None
        """

    def handle_queries(self, queries):
        """
        Return responses to queries from the client.

        @param queries: a dict representing the query_identifiers:queries that should be handled
        @type queries: {string: dict}

        @return: a Deferred object which will callback with a dict of query responses
        @rtype: Deferred which fires with {string: dict}
        """


class IQueryHandlerFactory(Interface):
    """
    Construct IQueryHandlers to handle queries from each new client that connects.
    """
    def build_query_handler(self):
        """
        Create an object that implements the IQueryHandler interface

        @return: object that implements IQueryHandler
        """


class IStreamDownloaderOptions(Interface):
    def get_downloader_options(self, sd_validator, payment_rate_manager):
        """
        Return the list of options that can be used to modify IStreamDownloader behavior

        @param sd_validator: object containing stream metadata, which the options may depend on
        @type sd_validator: object which implements IStreamDescriptorValidator interface

        @param payment_rate_manager: The payment rate manager currently in effect for the downloader
        @type payment_rate_manager: PaymentRateManager

        @return: [DownloadOption]
        @rtype: [DownloadOption]
        """


class IStreamDownloaderFactory(Interface):
    """
    Construct IStreamDownloaders and provide options that will be passed to those IStreamDownloaders.
    """

    def can_download(self, sd_validator, payment_rate_manager):
        """
        Decide whether the downloaders created by this factory can download the stream described by sd_validator

        @param sd_validator: object containing stream metadata
        @type sd_validator: object which implements IStreamDescriptorValidator interface

        @param payment_rate_manager: The payment rate manager currently in effect for the downloader
        @type payment_rate_manager: PaymentRateManager

        @return: True if the downloaders can download the stream, False otherwise
        @rtype: bool
        """

    def make_downloader(self, sd_validator, options, payment_rate_manager):
        """
        Create an object that implements the IStreamDownloader interface

        @param sd_validator: object containing stream metadata which will be given to the IStreamDownloader
        @type sd_validator: object which implements IStreamDescriptorValidator interface

        @param options: a list of values that will be used by the IStreamDownloaderFactory to
            construct the IStreamDownloader. the options are in the same order as they were given
            by get_downloader_options.
        @type options: [Object]

        @param payment_rate_manager: the PaymentRateManager which the IStreamDownloader should use.
        @type payment_rate_manager: PaymentRateManager

        @return: a Deferred which fires with the downloader object
        @rtype: Deferred which fires with IStreamDownloader
        """

    def get_description(self):
        """
        Return a string detailing what this downloader does with streams

        @return: short description of what the IStreamDownloader does.
        @rtype: string
        """


class IStreamDownloader(Interface):
    """
    Use metadata and data from the network for some useful purpose.
    """
    def start(self):
        """
        start downloading the stream

        @return: a Deferred which fires when the stream is finished downloading, or errbacks when the stream is
            cancelled.
        @rtype: Deferred which fires with anything
        """

    def insufficient_funds(self, err):
        """
        this function informs the stream downloader that funds are too low to finish downloading.

        @return: None
        """


class IStreamDescriptorValidator(Interface):
    """
    Pull metadata out of Stream Descriptor Files and perform some
    validation on the metadata.
    """
    def validate(self):
        """
        @return: whether the stream descriptor passes validation checks
        @rtype: boolean
        """

    def info_to_show(self):
        """
        @return: A list of tuples representing metadata that should be presented to the user before starting the
            download
        @rtype: [(string, string)]
        """


class ILBRYWallet(Interface):
    """
    Send and receive payments.

    To send a payment, a payment reservation must be obtained first. This guarantees that a payment
    isn't promised if it can't be paid. When the service in question is rendered, the payment
    reservation must be given to the ILBRYWallet along with the final price. The reservation can also
    be canceled.
    """
    def stop(self):
        """
        Send out any unsent payments, close any connections, and stop checking for incoming payments.

        @return: None
        """

    def start(self):
        """
        Set up any connections and start checking for incoming payments

        @return: None
        """
    def get_info_exchanger(self):
        """
        Get the object that will be used to find the payment addresses of peers.

        @return: The object that will be used to find the payment addresses of peers.
        @rtype: An object implementing IRequestCreator
        """

    def get_wallet_info_query_handler_factory(self):
        """
        Get the object that will be used to give our payment address to peers.

        This must return an object implementing IQueryHandlerFactory. It will be used to
        create IQueryHandler objects that will be registered with an IRequestHandler.

        @return: The object that will be used to give our payment address to peers.
        @rtype: An object implementing IQueryHandlerFactory
        """

    def reserve_points(self, peer, amount):
        """
        Ensure a certain amount of points are available to be sent as payment, before the service is rendered

        @param peer: The peer to which the payment will ultimately be sent
        @type peer: Peer

        @param amount: The amount of points to reserve
        @type amount: float

        @return: A ReservedPoints object which is given to send_points once the service has been rendered
        @rtype: ReservedPoints
        """

    def cancel_point_reservation(self, reserved_points):
        """
        Return all of the points that were reserved previously for some ReservedPoints object

        @param reserved_points: ReservedPoints previously returned by reserve_points
        @type reserved_points: ReservedPoints

        @return: None
        """

    def send_points(self, reserved_points, amount):
        """
        Schedule a payment to be sent to a peer

        @param reserved_points: ReservedPoints object previously returned by reserve_points.
        @type reserved_points: ReservedPoints

        @param amount: amount of points to actually send, must be less than or equal to the
            amount reserved in reserved_points
        @type amount: float

        @return: Deferred which fires when the payment has been scheduled
        @rtype: Deferred which fires with anything
        """

    def get_balance(self):
        """
        Return the balance of this wallet

        @return: Deferred which fires with the balance of the wallet
        @rtype: Deferred which fires with float
        """

    def add_expected_payment(self, peer, amount):
        """
        Increase the number of points expected to be paid by a peer

        @param peer: the peer which is expected to pay the points
        @type peer: Peer

        @param amount: the amount of points expected to be paid
        @type amount: float

        @return: None
        """