Changeset 9c20ac8 in trunk


Ignore:
Timestamp:
2022-01-05T21:06:29Z (3 years ago)
Author:
Itamar Turner-Trauring <itamar@…>
Branches:
master
Children:
90a25d0
Parents:
5f4db487
Message:

Client API sketch for basic immutable interactions.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • TabularUnified src/allmydata/storage/http_client.py

    r5f4db487 r9c20ac8  
    1717    # typing module not available in Python 2, and we only do type checking in
    1818    # Python 3 anyway.
    19     from typing import Union
     19    from typing import Union, Set, List
    2020    from treq.testing import StubTreq
    2121
    2222from base64 import b64encode
     23
     24import attr
    2325
    2426# TODO Make sure to import Python version?
     
    2729
    2830from twisted.web.http_headers import Headers
    29 from twisted.internet.defer import inlineCallbacks, returnValue, fail
     31from twisted.internet.defer import inlineCallbacks, returnValue, fail, Deferred
    3032from hyperlink import DecodedURL
    3133import treq
     
    4648    """Return value for ``Authentication`` header."""
    4749    return b"Tahoe-LAFS " + b64encode(swissnum).strip()
     50
     51
     52@attr.s
     53class ImmutableCreateResult(object):
     54    """Result of creating a storage index for an immutable."""
     55
     56    already_have = attr.ib(type=Set[int])
     57    allocated = attr.ib(type=Set[int])
     58
     59
     60class StorageClientImmutables(object):
     61    """
     62    APIs for interacting with immutables.
     63    """
     64
     65    def __init__(self, client):  # type: (StorageClient) -> None
     66        self._client = client
     67
     68    @inlineCallbacks
     69    def create(
     70        self,
     71        storage_index,
     72        share_numbers,
     73        allocated_size,
     74        upload_secret,
     75        lease_renew_secret,
     76        lease_cancel_secret,
     77    ):  # type: (bytes, List[int], int, bytes, bytes, bytes) -> Deferred[ImmutableCreateResult]
     78        """
     79        Create a new storage index for an immutable.
     80
     81        TODO retry internally on failure, to ensure the operation fully
     82        succeeded.  If sufficient number of failures occurred, the result may
     83        fire with an error, but there's no expectation that user code needs to
     84        have a recovery codepath; it will most likely just report an error to
     85        the user.
     86
     87        Result fires when creating the storage index succeeded, if creating the
     88        storage index failed the result will fire with an exception.
     89        """
     90
     91    @inlineCallbacks
     92    def write_share_chunk(
     93        self, storage_index, share_number, upload_secret, offset, data
     94    ):  # type: (bytes, int, bytes, int, bytes) -> Deferred[bool]
     95        """
     96        Upload a chunk of data for a specific share.
     97
     98        TODO The implementation should retry failed uploads transparently a number
     99        of times, so that if a failure percolates up, the caller can assume the
     100        failure isn't a short-term blip.
     101
     102        Result fires when the upload succeeded, with a boolean indicating
     103        whether the _complete_ share (i.e. all chunks, not just this one) has
     104        been uploaded.
     105        """
     106
     107    @inlineCallbacks
     108    def read_share_chunk(
     109        self, storage_index, share_number, offset, length
     110    ):  # type: (bytes, int, int, int) -> Deferred[bytes]
     111        """
     112        Download a chunk of data from a share.
     113
     114        TODO Failed downloads should be transparently retried and redownloaded
     115        by the implementation a few times so that if a failure percolates up,
     116        the caller can assume the failure isn't a short-term blip.
     117
     118        NOTE: the underlying HTTP protocol is much more flexible than this API,
     119        so a future refactor may expand this in order to simplify the calling
     120        code and perhaps download data more efficiently.  But then again maybe
     121        the HTTP protocol will be simplified, see
     122        https://tahoe-lafs.org/trac/tahoe-lafs/ticket/3777
     123        """
    48124
    49125
     
    78154            headers.addRawHeader(
    79155                "X-Tahoe-Authorization",
    80                 b"%s %s" % (key.value.encode("ascii"), b64encode(value).strip())
     156                b"%s %s" % (key.value.encode("ascii"), b64encode(value).strip()),
    81157            )
    82158        return self._treq.request(method, url, headers=headers, **kwargs)
Note: See TracChangeset for help on using the changeset viewer.