diff --git a/lbrynet/interfaces.py b/lbrynet/interfaces.py deleted file mode 100644 index 5b5e75d13..000000000 --- a/lbrynet/interfaces.py +++ /dev/null @@ -1,722 +0,0 @@ -""" -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 IWallet(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 IWallet 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 - """ - - -class IBlobPriceModel(Interface): - """ - A blob price model - - Used by INegotiationStrategy classes - """ - - def calculate_price(self, blob): - """ - Calculate the price for a blob - - @param blob: a blob hash - @type blob: str - - @return: blob price target - @type: Decimal - """ - - -class INegotiationStrategy(Interface): - """ - Strategy to negotiate download payment rates - """ - - def make_offer(self, peer, blobs): - """ - Make a rate offer for the given peer and blobs - - @param peer: peer to make an offer to - @type: str - - @param blobs: blob hashes to make an offer for - @type: list - - @return: rate offer - @rtype: Offer - """ - - def respond_to_offer(self, offer, peer, blobs): - """ - Respond to a rate offer given by a peer - - @param offer: offer to reply to - @type: Offer - - @param peer: peer to make an offer to - @type: str - - @param blobs: blob hashes to make an offer for - @type: list - - @return: accepted, rejected, or unset offer - @rtype: Offer - """