xta-tool 0.1.0__py3-none-any.whl

xta_tool/__init__.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from .client import XtaClient
+from .config import Config, get_config, init_global_config
+from .main import main as cli
+from .model import (
+    BASE64_PREFIX,
+    XtaCode,
+    XtaFile,
+    XtaIdentifier,
+    XtaMessage,
+    XtaMetadata,
+    XtaTransportReport,
+)
+
+_ = (
+    get_config,
+    Config,
+    init_global_config,
+    XtaClient,
+    XtaFile,
+    XtaCode,
+    XtaIdentifier,
+    XtaMetadata,
+    XtaMessage,
+    XtaTransportReport,
+    BASE64_PREFIX,
+    cli,
+)

xta_tool/client.py

@@ -0,0 +1,198 @@
+# SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import click
+import httpx
+from click import ClickException
+
+from . import config as cfg
+from . import file, soap
+from .model import (
+    XtaFile,
+    XtaMessage,
+    XtaMetadata,
+    XtaTransportReport,
+)
+
+
+@dataclass
+class XtaClient:
+    client: httpx.Client
+    config: cfg.Config
+    output_directory: Optional[Path]
+
+    def new(self) -> str:
+        resp = self._request(self._prepare_new())
+        return resp.text("{*}Body/{*}MessageID")
+
+    def _prepare_new(self) -> soap.XtaSoapRequest:
+        return soap.XtaSoapRequest(
+            url=self.config.management_port_url,
+            action="http://www.xta.de/XTA/CreateMessageID",
+            header_template="Author.xml",
+            context=self._config_context(),
+        )
+
+    def send(self, message: XtaMessage):
+        self._request(self._prepare_send(message))
+
+    def _prepare_send(self, message: XtaMessage) -> soap.XtaSoapRequest:
+        context = self._prepare_send_context(message)
+        return soap.XtaSoapRequest(
+            url=self.config.send_port_url,
+            action="http://www.xta.de/XTA/SendMessage",
+            header_template="MessageMetaData.xml",
+            body_template="GenericContentContainer.xml",
+            attachments=self._prepare_send_attachments(message, context),
+            context=context,
+        )
+
+    def _prepare_send_attachments(
+        self, message: XtaMessage, context: dict
+    ) -> list[soap.AttachmentResource]:
+        return [
+            self._prepare_file(xta_file, message.source_directory, context)
+            for xta_file in [message.message] + message.attachments
+        ]
+
+    def _prepare_file(
+        self, xta_file: XtaFile, source_directory: Optional[Path], context: dict
+    ) -> soap.AttachmentResource:
+        return soap.AttachmentResource(
+            content_id=xta_file.content_id,
+            content=file.load_xta_file_content(
+                xta_file.content, source_directory, context
+            ),
+        )
+
+    def _prepare_send_context(self, message: XtaMessage) -> dict:
+        return {**message.model_dump(), **self._config_context()}
+
+    def get(self, message_id: str) -> XtaMessage:
+        resp = self._request(self._prepare_get(message_id))
+        xta_message = self._map_xta_message(resp)
+        return file.save_xta_message(
+            xta_message, resp.attachments, self.config.max_save_base64_size
+        )
+
+    def _prepare_get(self, message_id: str) -> soap.XtaSoapRequest:
+        return soap.XtaSoapRequest(
+            url=self.config.msg_box_port_url,
+            action="http://www.osci.eu/ws/2008/05/transport/urn/messageTypes/MsgBoxFetchRequest",
+            header_template="Author.xml",
+            body_template="MsgBoxFetchRequest.xml",
+            context=self._prepare_get_context(message_id),
+        )
+
+    def _prepare_get_context(self, message_id: str):
+        return {"config": cfg.get_config(), "message_id": message_id}
+
+    def _map_xta_message(self, resp: soap.IncomingSoapMessage) -> XtaMessage:
+        return XtaMessage.from_xml(
+            resp.select("{*}Header/{*}MessageMetaData"),
+            resp.select("{*}Body/{*}GenericContentContainer"),
+            (
+                self.output_directory / "xta-message.yaml"
+                if self.output_directory
+                else None
+            ),
+        )
+
+    def ls(self) -> list[XtaMetadata]:
+        resp = self._request(self._prepare_ls())
+        body = resp.select("{*}Body/{*}MsgStatusList")
+        return [
+            XtaMetadata.from_xml(metadata_element)
+            for metadata_element in body.findall("{*}MessageMetaData")
+        ]
+
+    def _prepare_ls(self):
+        return soap.XtaSoapRequest(
+            url=self.config.msg_box_port_url,
+            action="http://www.osci.eu/ws/2008/05/transport/urn/messageTypes/MsgBoxStatusListRequest",
+            header_template="Author.xml",
+            body_template="MsgBoxStatusListRequest.xml",
+            context=self._prepare_ls_context(),
+        )
+
+    def _prepare_ls_context(self):
+        return {"config": cfg.get_config()}
+
+    def inspect(self, message_id: str) -> XtaTransportReport:
+        resp = self._request(self._prepare_inspect(message_id))
+        report_element = resp.select("{*}Body/{*}TransportReport")
+        return XtaTransportReport.from_xml(report_element)
+
+    def _prepare_inspect(self, message_id: str) -> soap.XtaSoapRequest:
+        return soap.XtaSoapRequest(
+            url=self.config.management_port_url,
+            action="http://www.xta.de/XTA/GetTransportReport",
+            header_template="Author.xml",
+            body_template="MessageID.xml",
+            context=self._config_and_message_id_context(message_id),
+        )
+
+    def close(self, message_id: str):
+        self._request(self._prepare_close(message_id))
+
+    def _prepare_close(self, message_id: str) -> soap.XtaSoapRequest:
+        return soap.XtaSoapRequest(
+            url=self.config.msg_box_port_url,
+            action="http://www.osci.eu/ws/2008/05/transport/urn/messageTypes/MsgBoxCloseRequest",
+            header_template="Author.xml",
+            body_template="MsgBoxCloseRequest.xml",
+            context=self._config_and_message_id_context(message_id),
+        )
+
+    def _config_and_message_id_context(self, message_id):
+        return {**self._config_context(), "message_id": message_id}
+
+    def _config_context(self):
+        return {"config": self.config}
+
+    def _request(self, soap_request: soap.XtaSoapRequest) -> soap.IncomingSoapMessage:
+        request = soap_request.prepare()
+        request.headers["User-Agent"] = self.config.user_agent
+
+        # send request
+        try:
+            http_response = self.client.send(request, stream=True)
+        except httpx.RequestError as e:
+            raise ClickException(f"{e} - [{request.method}] {request.url}")
+
+        # process response
+        if self.config.verbose:
+            header_lines = "\n".join(
+                f"{key}: {value}" for key, value in http_response.headers.items()
+            )
+            click.echo(f"{header_lines}\n", err=True)
+        soap_response = soap.receive(
+            http_response.headers.get("content-type", ""),
+            http_response.iter_bytes(),
+            self.config.max_response_envelope_size,
+        )
+
+        if self.config.verbose:
+            click.echo(soap_response.envelope_xml + "\n", err=True)
+
+        # handle fault response
+        if soap_response.fault:
+            raise soap.SoapError(soap_response.fault)
+        try:
+            http_response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise ClickException(f"{e} - [{request.method}] {request.url}")
+
+        return soap_response
+
+
+@contextmanager
+def create_xta_client(output_directory: Optional[Path] = None):
+    with cfg.create_http_client() as client:
+        yield XtaClient(client, cfg.get_config(), output_directory)

xta_tool/config.py

@@ -0,0 +1,123 @@
+# SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import ssl
+import tomllib
+from contextlib import contextmanager
+from pathlib import Path
+
+import httpx
+from click import ClickException
+from pydantic import BaseModel
+
+from . import util
+from .model import XtaIdentifier
+
+DEFAULT_CONFIG_PATH = Path.home() / ".xta" / "config.toml"
+
+
+class Config(BaseModel):
+    base_url: str = "https://localhost:8443"
+    management_port_path: str = "/services/XTAService/ManagementPort"
+    msg_box_port_path: str = "/services/XTAService/MsgBoxPort"
+    send_port_path: str = "/services/XTAService/SendXtaPort"
+    verify: bool = True
+    cafile: str = "~/.xta/ca.crt"
+    certfile: str = "~/.xta/tls.crt"
+    keyfile: str = "~/.xta/tls.key"
+    self_identifier: XtaIdentifier = XtaIdentifier(value="*")
+    user_agent: str = "Apache-CXF/4.0.7"
+    verbose: bool = False
+    max_save_base64_size: int = 1 << 20  # 1 MiB
+    max_response_envelope_size: int = 10 << 20  # 10 MiB
+    max_list_items: int = 100
+
+    @property
+    def management_port_url(self):
+        return self.base_url + self.management_port_path
+
+    @property
+    def msg_box_port_url(self):
+        return self.base_url + self.msg_box_port_path
+
+    @property
+    def send_port_url(self):
+        return self.base_url + self.send_port_path
+
+
+CONFIG: Config | None = None
+
+LOADED_CONFIG_FILES = []
+
+
+def get_config() -> Config:
+    if CONFIG is None:
+        raise RuntimeError("init_global_config not called?")
+    return CONFIG
+
+
+def init_global_config(config_path: Path, profiles: str):
+    global CONFIG
+    LOADED_CONFIG_FILES.clear()
+    config_dict = _load_default_toml_config(config_path)
+    for profile_str in profiles.split(","):
+        profile = profile_str.strip()
+        if profile:
+            config_dict = util.merge_dict(
+                config_dict,
+                _load_profile_toml_config(config_path, profile),
+            )
+    CONFIG = Config(**config_dict)
+
+
+def _load_default_toml_config(config_path: Path):
+    if config_path.is_file():
+        return _load_toml_config(config_path)
+    elif config_path.absolute() != DEFAULT_CONFIG_PATH.absolute():
+        raise ClickException("Config file '{config_path}' does not exist!")
+    return dict()
+
+
+def _load_profile_toml_config(config_path: Path, profile: str):
+    profile_config_path = _to_profile_path(config_path, profile)
+    if profile_config_path.is_file():
+        return _load_toml_config(profile_config_path)
+    else:
+        raise ClickException(
+            f"Profile config file '{profile_config_path}' does not exist!"
+        )
+
+
+def _load_toml_config(config_path: Path):
+    LOADED_CONFIG_FILES.append(config_path)
+    with open(config_path, "rb") as file:
+        return util.translate_dict_to_snake_case(tomllib.load(file))
+
+
+def _to_profile_path(config_path: Path, profile: str) -> Path:
+    name = config_path.name
+    suffix = ""
+    parts = name.rsplit(".", 1)
+    if len(parts) == 2:
+        name, extension = parts
+        suffix = f".{extension}"
+    return config_path.parent / f"{name}-{profile}{suffix}"
+
+
+@contextmanager
+def create_http_client():
+    cfg = get_config()
+    ctx = ssl.create_default_context(
+        cafile=Path(cfg.cafile).expanduser() if cfg.cafile else None
+    )
+    ctx.verify_mode = (
+        ssl.VerifyMode.CERT_REQUIRED if cfg.verify else ssl.VerifyMode.CERT_NONE
+    )
+    if cfg.certfile:
+        ctx.load_cert_chain(
+            certfile=Path(cfg.certfile).expanduser(),
+            keyfile=Path(cfg.keyfile).expanduser() if cfg.keyfile else None,
+        )
+    with httpx.Client(verify=ctx) as client:
+        yield client

xta_tool/file/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+
+from .load import load_xta_file_content, load_xta_message
+from .save import save_xta_message
+
+_ = (load_xta_message, load_xta_file_content, save_xta_message)

xta_tool/file/load.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import base64
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from click import ClickException
+from pydantic import ValidationError
+
+from ..model import BASE64_PREFIX, XtaMessage
+from ..util import (
+    Chunks,
+    merge_dict,
+    translate_dict_to_snake_case,
+)
+from . import template
+from .zip import create_zip_content
+
+
+def load_xta_file_content(
+    file_content: str, source_directory: Optional[Path], context: dict
+) -> Chunks:
+    if file_content.startswith(BASE64_PREFIX):
+        return lambda: iter([base64.b64decode(file_content[len(BASE64_PREFIX) :])])
+    else:
+        if source_directory is None or not source_directory.is_dir():
+            raise ClickException(
+                f"Source directory '{source_directory}' of '{file_content}' does not exist!"
+            )
+        content_path = source_directory / file_content
+        if content_path.is_dir():
+            return lambda: create_zip_content(content_path, context)
+        if not content_path.is_file():
+            raise ClickException(f"Content file '{content_path}' does not exist!")
+
+        return lambda: template.load_file_content(content_path, context)
+
+
+def load_xta_message(message_id: str, message_path: Path) -> XtaMessage:
+    message_file_path = _get_yaml_message_file_path(message_path)
+    message_dict = _load_yaml_message_file(message_file_path)
+    try:
+        return XtaMessage(
+            **merge_dict(
+                message_dict,
+                dict(
+                    metadata=dict(message_id=message_id), source_path=message_file_path
+                ),
+            ),
+        )
+    except ValidationError as e:
+        raise ClickException(f"{message_path} invalid!\n{e}")
+
+
+def _get_yaml_message_file_path(path: Path) -> Path:
+    return path / "xta-message.yaml" if path.is_dir() else path
+
+
+def _load_yaml_message_file(file_path: Path) -> dict:
+    with file_path.open() as file:
+        try:
+            message = yaml.safe_load(file)
+        except yaml.YAMLError as e:
+            raise ClickException(f"yaml message '{file_path}' invalid! {e}")
+        if not isinstance(message, dict):
+            raise ClickException(
+                f"yaml message '{file_path}' must contain key-value pairs!"
+            )
+        return translate_dict_to_snake_case(message)

xta_tool/file/save.py

@@ -0,0 +1,95 @@
+# SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import base64
+import io
+from pathlib import Path
+from typing import Callable, Iterator
+
+from click import ClickException
+
+from ..model import BASE64_PREFIX, XtaFile, XtaMessage
+from ..soap import mtom
+
+
+def save_xta_message(
+    xta_message: XtaMessage,
+    soap_attachments: Iterator[mtom.ReadablePart],
+    max_base64_size: int,
+) -> XtaMessage:
+    output_directory = (
+        xta_message.source_path.parent if xta_message.source_path else None
+    )
+
+    def download_content(xta_file: XtaFile, chunks: Iterator[bytes]) -> str:
+        return (
+            _download_to_output_directory(xta_file, chunks, output_directory)
+            if output_directory is not None
+            else _download_to_base64_string(xta_file, chunks, max_base64_size)
+        )
+
+    return _with_downloaded_file_content(
+        xta_message, soap_attachments, download_content
+    )
+
+
+def _with_downloaded_file_content(
+    xta_message: XtaMessage,
+    soap_attachments: Iterator[mtom.ReadablePart],
+    download_content: Callable[[XtaFile, Iterator[bytes]], str],
+) -> XtaMessage:
+    xta_files = {
+        file.content_id: file
+        for file in [xta_message.message] + xta_message.attachments
+    }
+    for soap_attachment in soap_attachments:
+        xta_file = xta_files.get(soap_attachment.content_id)
+        if xta_file:
+            xta_files[soap_attachment.content_id] = xta_file.model_copy(
+                update=(
+                    dict(content=download_content(xta_file, soap_attachment.chunks))
+                )
+            )
+    return xta_message.model_copy(
+        update=dict(
+            message=xta_files[xta_message.message.content_id],
+            attachments=[
+                xta_files[xta_file.content_id] for xta_file in xta_message.attachments
+            ],
+        )
+    )
+
+
+def _download_to_output_directory(
+    xta_file: XtaFile, chunks: Iterator[bytes], output_directory: Path
+) -> str:
+    output_path = output_directory / xta_file.safe_file_name
+    with open(output_path, "wb") as file:
+        for chunk in chunks:
+            file.write(chunk)
+    return str(output_path.relative_to(output_directory))
+
+
+def _download_to_base64_string(
+    xta_file: XtaFile, chunks: Iterator[bytes], max_size: int
+) -> str:
+    base64_str = io.StringIO()
+
+    def write_as_base64(chunk):
+        base64_str.write(base64.b64encode(chunk).decode())
+
+    size = 0
+    chunk_residual = b""
+    for new_chunk in chunks:
+        size += len(new_chunk)
+        if size > max_size:
+            raise ClickException(
+                f"Received file '{xta_file.file_name}' is too large! download_base64_size_limit={max_size}"
+            )
+        chunk = chunk_residual + new_chunk
+        base64_encodable_size = 3 * (len(chunk) // 3)
+        chunk_residual = chunk[base64_encodable_size:]
+        write_as_base64(chunk[:base64_encodable_size])
+    write_as_base64(chunk_residual)
+    return BASE64_PREFIX + base64_str.getvalue()

xta_tool/file/template.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import io
+from pathlib import Path
+from typing import Iterator
+
+import jinja2
+from click import ClickException
+
+ENV = jinja2.Environment(loader=jinja2.FileSystemLoader("/"))
+
+JINJA_FILE_NAME_EXTENSION = ".jinja"
+
+
+def remove_jinja_extension(content_path: Path) -> Path:
+    return content_path.with_name(
+        content_path.name.removesuffix(JINJA_FILE_NAME_EXTENSION)
+    )
+
+
+def load_file_content(content_path: Path, context: dict) -> Iterator[bytes]:
+    if content_path.name.endswith(JINJA_FILE_NAME_EXTENSION):
+        return _render_template_content(content_path, context)
+    return _load_direct_file_contents(content_path)
+
+
+def _render_template_content(template_path: Path, context: dict) -> Iterator[bytes]:
+    try:
+        for part in ENV.get_template(str(template_path.absolute())).stream(**context):
+            yield part.encode()
+    except jinja2.TemplateError as e:
+        raise ClickException(f"[Template {template_path}] {e}")
+
+
+def _load_direct_file_contents(path: Path) -> Iterator[bytes]:
+    with open(path, "rb") as file:
+        while chunk := file.read(io.DEFAULT_BUFFER_SIZE):
+            yield chunk

xta_tool/file/zip.py

@@ -0,0 +1,46 @@
+# SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import atexit
+import io
+import zipfile
+from pathlib import Path
+from tempfile import SpooledTemporaryFile
+from typing import Iterator
+
+from . import template
+
+ZIP_BUFFER_SIZE = 1 << 20  # 1 MiB
+
+
+def create_zip_content(source_directory: Path, context: dict) -> Iterator[bytes]:
+    with SpooledTemporaryFile(max_size=ZIP_BUFFER_SIZE) as file:
+        with zipfile.ZipFile(file, "w") as archive:
+            _write_zip_content(archive, source_directory, context)
+        file.seek(0)
+
+        def close():
+            file.close()
+
+        atexit.register(close)
+        while chunk := file.read(io.DEFAULT_BUFFER_SIZE):
+            yield chunk
+        atexit.unregister(close)
+
+
+def _write_zip_content(archive: zipfile.ZipFile, source_directory: Path, context: dict):
+    for entry_path in source_directory.glob("**/*"):
+        if entry_path.is_file():
+            _write_zip_entry(archive, entry_path, source_directory, context)
+
+
+def _write_zip_entry(
+    archive: zipfile.ZipFile, entry_path: Path, source_directory: Path, context: dict
+):
+    entry_name = str(
+        template.remove_jinja_extension(entry_path).relative_to(source_directory)
+    )
+    with archive.open(entry_name, "w") as entry:
+        for chunk in template.load_file_content(entry_path, context):
+            entry.write(chunk)