plugin XEP-0363, upload: compute hash on file upload:

- Hash (SHA-256) is now automacally computed when a file is uploaded via XEP-0363, and
  used if no hash has been specified by frontend already.
- Use named tuples (`UploadTracking` and `UploadResult`) to handle callback values.
- upload: fix a bug (missing variable) in `unregister` (which is not used yet anyway).
- usual docstring/type hints improvements
This commit is contained in:
Goffi 2026-07-09 13:07:01 +02:00
commit 92cb52dd04

View file

@ -19,7 +19,7 @@
import os
import os.path
from pathlib import Path
from typing import Optional, Tuple, Union
from typing import Callable, NamedTuple, TYPE_CHECKING
from twisted.internet import defer
from twisted.words.protocols.jabber import jid
@ -33,6 +33,25 @@ from libervia.backend.core.log import getLogger
from libervia.backend.tools import xml_tools
from libervia.backend.tools.common import data_format
if TYPE_CHECKING:
from libervia.backend.core.main import LiberviaBackend
class UploadTracking(NamedTuple):
"""Tracking data for an ongoing file upload"""
progress_id: str
download_d: defer.Deferred
class UploadResult(NamedTuple):
"""Result of a completed file upload"""
url: str
hash: str | None = None
hash_algo: str | None = None
log = getLogger(__name__)
@ -54,7 +73,7 @@ UPLOADING_TITLE = D_("File upload")
class UploadPlugin(object):
# TODO: plugin unload
def __init__(self, host):
def __init__(self, host: "LiberviaBackend") -> None:
log.info(_("plugin Upload initialization"))
self.host = host
host.bridge.add_method(
@ -68,27 +87,49 @@ class UploadPlugin(object):
self._upload_callbacks = []
def _file_upload(
self, filepath, filename, upload_jid_s="", options="", profile=C.PROF_KEY_NONE
):
self,
filepath: str,
filename: str,
upload_jid_s: str,
options_s: str,
profile: str = C.PROF_KEY_NONE,
) -> defer.Deferred:
"""Bridge method to upload a file.
@param filepath: absolute path to the file
@param filename: name to use for the upload
@param upload_jid_s: upload capable entity jid as string
@param options_s: serialised upload options
@param profile: profile key
@return: Deferred which fires with progress id or error
"""
client = self.host.get_client(profile)
upload_jid = jid.JID(upload_jid_s) if upload_jid_s else None
options = data_format.deserialise(options)
options: dict = data_format.deserialise(options_s)
return defer.ensureDeferred(
self.file_upload(client, filepath, filename or None, upload_jid, options)
)
async def file_upload(self, client, filepath, filename, upload_jid, options):
"""Send a file using best available method
async def file_upload(
self,
client: SatXMPPEntity,
filepath: Path | str,
filename: str | None,
upload_jid: jid.JID | None,
options: dict,
) -> dict[str, str]:
"""Send a file using best available method.
parameters are the same as for [upload]
@return (dict): action dictionary, with progress id in case of success, else xmlui
message
@param client: XMPP client
@param filepath: absolute path to the file
@param filename: name to use for the upload
@param upload_jid: upload capable entity jid
@param options: upload options
@return: action dictionary with progress id in case of success, else xmlui message
"""
try:
progress_id, __ = await self.upload(
client, filepath, filename, upload_jid, options
)
result = await self.upload(client, filepath, filename, upload_jid, options)
except Exception as e:
if (
isinstance(e, jabber_error.StanzaError)
@ -105,16 +146,16 @@ class UploadPlugin(object):
).toXml()
}
else:
return {"progress": progress_id}
return {"progress": result.progress_id}
async def upload(
self,
client: SatXMPPEntity,
filepath: Union[Path, str],
filename: Optional[str] = None,
upload_jid: Optional[jid.JID] = None,
extra: Optional[dict] = None,
) -> Tuple[str, defer.Deferred]:
filepath: Path | str,
filename: str | None = None,
upload_jid: jid.JID | None = None,
extra: dict | None = None,
) -> UploadTracking:
"""Send a file using best available method
@param filepath: absolute path to the file
@ -127,9 +168,8 @@ class UploadPlugin(object):
used only if HTTPS transport is needed
- progress_id(str): id to use for progression
if not specified, one will be generated
@param profile: %(doc_profile)s
@return: progress_id and a Deferred which fire download URL when upload is
finished
@return: UploadTracking with progress_id and deferred which fires download URL
when upload is finished
"""
if extra is None:
extra = {}
@ -145,27 +185,36 @@ class UploadPlugin(object):
log.info(
"{name} method will be used to upload the file".format(name=method_name)
)
progress_id, download_d = await upload_cb(
client, filepath, filename, upload_jid, extra
result = await upload_cb(client, filepath, filename, upload_jid, extra)
return UploadTracking(
progress_id=result.progress_id,
download_d=result.download_d,
)
return progress_id, download_d
raise exceptions.NotFound("Can't find any method to upload a file")
def register(self, method_name, available_cb, upload_cb, priority=0):
"""Register a fileUploading method
def register(
self,
method_name: str,
available_cb: Callable[[SatXMPPEntity, jid.JID | None], defer.Deferred[jid.JID]],
upload_cb: Callable[
[SatXMPPEntity, Path | str, str | None, jid.JID, dict],
UploadTracking,
],
priority: int = 0,
) -> None:
"""Register a file uploading method.
@param method_name(unicode): short name for the method, must be unique
@param available_cb(callable): method to call to check if this method is usable
the callback must take two arguments: upload_jid (can be None) and profile
the callback must return the first entity found (being upload_jid or one of its
components)
exceptions.NotFound must be raised if no entity has been found
@param upload_cb(callable): method to upload a file
must have the same signature as [file_upload]
must return a tuple with progress_id and a Deferred which fire download URL
when upload is finished
@param priority(int): pririoty of this method, the higher available will be used
@param method_name: short name for the method, must be unique
@param available_cb: method to call to check if this method is usable
must take two arguments: client and upload_jid (can be None)
must return the first entity found (being upload_jid or one of its components)
exceptions.NotFound must be raised if no entity has been found
@param upload_cb: method to upload a file
must have the same signature as [upload]
must return an UploadTracking with progress_id and deferred which fires
download URL when upload is finished
@param priority: priority of this method, the higher available will be used
"""
assert method_name
for data in self._upload_callbacks:
@ -176,9 +225,14 @@ class UploadPlugin(object):
self._upload_callbacks.append((method_name, available_cb, upload_cb, priority))
self._upload_callbacks.sort(key=lambda data: data[3], reverse=True)
def unregister(self, method_name):
def unregister(self, method_name: str) -> None:
"""Unregister a previously registered upload method.
@param method_name: name of the method to unregister
@raise NotFound: if the method is not registered
"""
for idx, data in enumerate(self._upload_callbacks):
if data[0] == method_name:
del [idx]
del self._upload_callbacks[idx]
return
raise exceptions.NotFound("The name to unregister doesn't exist")