bacommon.bacloud

21def asset_file_cache_path(filehash: str) -> str:
22    """Given a sha256 hex file hash, return a storage path."""
23
24    # We expect a 64 byte hex str with only lowercase letters and
25    # numbers. Note to self: I considered base64 hashes to save space
26    # but then remembered that lots of filesystems out there ignore case
27    # so that would not end well.
28    assert len(filehash) == 64
29    assert filehash.islower()
30    assert filehash.isalnum()
31
32    # Split into a few levels of directories to keep directory listings
33    # and operations reasonable. This will give 256 top level dirs, each
34    # with 256 subdirs. So if we have 65,536 files in our cache then
35    # dirs will average 1 file each. That seems like a reasonable spread
36    # I think.
37    return f'{filehash[:2]}/{filehash[2:4]}/{filehash[4:]}'

40@ioprepped
41@dataclass
42class RequestData:
43    """Request sent to bacloud server."""
44
45    command: Annotated[str, IOAttrs('c')]
46    token: Annotated[str | None, IOAttrs('t')]
47    payload: Annotated[dict, IOAttrs('p')]
48    tzoffset: Annotated[float, IOAttrs('z')]
49    isatty: Annotated[bool, IOAttrs('y')]

 52@ioprepped
 53@dataclass
 54class ResponseData:
 55    """Response sent from the bacloud server to the client."""
 56
 57    @ioprepped
 58    @dataclass
 59    class Downloads:
 60        """Info about downloads included in a response."""
 61
 62        @ioprepped
 63        @dataclass
 64        class Entry:
 65            """Individual download."""
 66
 67            path: Annotated[str, IOAttrs('p')]
 68
 69            #: Args include with this particular request (combined with
 70            #: baseargs).
 71            args: Annotated[dict[str, str], IOAttrs('a')]
 72
 73            # TODO: could add a hash here if we want the client to
 74            # verify hashes.
 75
 76        #: If present, will be prepended to all entry paths via os.path.join.
 77        basepath: Annotated[str | None, IOAttrs('p')]
 78
 79        #: Server command that should be called for each download. The
 80        #: server command is expected to respond with a downloads_inline
 81        #: containing a single 'default' entry. In the future this may
 82        #: be expanded to a more streaming-friendly process.
 83        cmd: Annotated[str, IOAttrs('c')]
 84
 85        #: Args that should be included with all download requests.
 86        baseargs: Annotated[dict[str, str], IOAttrs('a')]
 87
 88        #: Everything that should be downloaded.
 89        entries: Annotated[list[Entry], IOAttrs('e')]
 90
 91    #: If present, client should print this message before any other
 92    #: response processing (including error handling) occurs.
 93    message: Annotated[str | None, IOAttrs('m', store_default=False)] = None
 94
 95    #: End arg for message print() call.
 96    message_end: Annotated[str, IOAttrs('m_end', store_default=False)] = '\n'
 97
 98    #: If present, client should abort with this error message.
 99    error: Annotated[str | None, IOAttrs('e', store_default=False)] = None
100
101    #: How long to wait before proceeding with remaining response (can
102    #: be useful when waiting for server progress in a loop).
103    delay_seconds: Annotated[float, IOAttrs('d', store_default=False)] = 0.0
104
105    #: If present, a token that should be stored client-side and passed
106    #: with subsequent commands.
107    login: Annotated[str | None, IOAttrs('l', store_default=False)] = None
108
109    #: If True, any existing client-side token should be discarded.
110    logout: Annotated[bool, IOAttrs('lo', store_default=False)] = False
111
112    #: If present, client should generate a manifest of this dir.
113    #: It should be added to end_command args as 'manifest'.
114    dir_manifest: Annotated[str | None, IOAttrs('man', store_default=False)] = (
115        None
116    )
117
118    #: If present, client should upload the requested files (arg1)
119    #: individually to a server command (arg2) with provided args (arg3).
120    uploads: Annotated[
121        tuple[list[str], str, dict] | None, IOAttrs('u', store_default=False)
122    ] = None
123
124    #: If present, a list of pathnames that should be gzipped
125    #: and uploaded to an 'uploads_inline' bytes dict in end_command args.
126    #: This should be limited to relatively small files.
127    uploads_inline: Annotated[
128        list[str] | None, IOAttrs('uinl', store_default=False)
129    ] = None
130
131    #: If present, file paths that should be deleted on the client.
132    deletes: Annotated[
133        list[str] | None, IOAttrs('dlt', store_default=False)
134    ] = None
135
136    #: If present, describes files the client should individually
137    #: request from the server if not already present on the client.
138    downloads: Annotated[
139        Downloads | None, IOAttrs('dl', store_default=False)
140    ] = None
141
142    #: If present, pathnames mapped to gzipped data to
143    #: be written to the client. This should only be used for relatively
144    #: small files as they are all included inline as part of the response.
145    downloads_inline: Annotated[
146        dict[str, bytes] | None, IOAttrs('dinl', store_default=False)
147    ] = None
148
149    #: If present, all empty dirs under this one should be removed.
150    dir_prune_empty: Annotated[
151        str | None, IOAttrs('dpe', store_default=False)
152    ] = None
153
154    #: If present, url to display to the user.
155    open_url: Annotated[str | None, IOAttrs('url', store_default=False)] = None
156
157    #: If present, a line of input is read and placed into
158    #: end_command args as 'input'. The first value is the prompt printed
159    #: before reading and the second is whether it should be read as a
160    #: password (without echoing to the terminal).
161    input_prompt: Annotated[
162        tuple[str, bool] | None, IOAttrs('inp', store_default=False)
163    ] = None
164
165    #: If present, a message that should be printed after all other
166    #: response processing is done.
167    end_message: Annotated[str | None, IOAttrs('em', store_default=False)] = (
168        None
169    )
170
171    #: End arg for end_message print() call.
172    end_message_end: Annotated[str, IOAttrs('eme', store_default=False)] = '\n'
173
174    #: If present, this command is run with these args at the end
175    #: of response processing.
176    end_command: Annotated[
177        tuple[str, dict] | None, IOAttrs('ec', store_default=False)
178    ] = None

57    @ioprepped
58    @dataclass
59    class Downloads:
60        """Info about downloads included in a response."""
61
62        @ioprepped
63        @dataclass
64        class Entry:
65            """Individual download."""
66
67            path: Annotated[str, IOAttrs('p')]
68
69            #: Args include with this particular request (combined with
70            #: baseargs).
71            args: Annotated[dict[str, str], IOAttrs('a')]
72
73            # TODO: could add a hash here if we want the client to
74            # verify hashes.
75
76        #: If present, will be prepended to all entry paths via os.path.join.
77        basepath: Annotated[str | None, IOAttrs('p')]
78
79        #: Server command that should be called for each download. The
80        #: server command is expected to respond with a downloads_inline
81        #: containing a single 'default' entry. In the future this may
82        #: be expanded to a more streaming-friendly process.
83        cmd: Annotated[str, IOAttrs('c')]
84
85        #: Args that should be included with all download requests.
86        baseargs: Annotated[dict[str, str], IOAttrs('a')]
87
88        #: Everything that should be downloaded.
89        entries: Annotated[list[Entry], IOAttrs('e')]

62        @ioprepped
63        @dataclass
64        class Entry:
65            """Individual download."""
66
67            path: Annotated[str, IOAttrs('p')]
68
69            #: Args include with this particular request (combined with
70            #: baseargs).
71            args: Annotated[dict[str, str], IOAttrs('a')]
72
73            # TODO: could add a hash here if we want the client to
74            # verify hashes.