asyagent 0.1.0__py3-none-any.whl

asyagent/__init__.py

@@ -0,0 +1,10 @@
+"""asyagent — an HTTP service that compiles Asymptote (*.asy) sources and
+returns the rendered output either inline (binary/base64) or as an
+object-storage URL.
+
+Pure Python 3.10+ standard library. No third-party dependencies.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

asyagent/__main__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sys
+
+from .config import Settings
+from .server import run
+
+
+def main() -> int:
+    settings = Settings.from_env()
+    try:
+        run(settings)
+    except OSError as e:
+        print(f"asyagent: failed to start server: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

asyagent/compiler.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+import uuid
+import zipfile
+from dataclasses import dataclass
+
+from .errors import CompileError, CompileTimeout, RasterError, UnsupportedFormat
+
+NATIVE_FORMATS = ("pdf", "svg", "eps")
+RASTER_FORMATS = ("png", "jpg", "jpeg")
+SUPPORTED_FORMATS = NATIVE_FORMATS + RASTER_FORMATS
+
+MIME_BY_EXT = {
+    "pdf": "application/pdf",
+    "svg": "image/svg+xml",
+    "eps": "application/postscript",
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "zip": "application/zip",
+}
+
+GS_DEVICE = {
+    "png": "pngalpha",
+    "jpg": "jpeg",
+    "jpeg": "jpeg",
+}
+
+OUTPUT_EXTS = set(NATIVE_FORMATS)
+
+
+@dataclass
+class CompiledFile:
+    name: str
+    ext: str
+    mime: str
+    data: bytes
+
+    @property
+    def size(self) -> int:
+        return len(self.data)
+
+
+def validate_format(fmt: str) -> str:
+    fmt = fmt.lower()
+    if fmt not in SUPPORTED_FORMATS:
+        raise UnsupportedFormat(
+            f"unsupported format: {fmt!r}",
+            detail=f"supported: {', '.join(SUPPORTED_FORMATS)}",
+        )
+    return fmt
+
+
+def _snapshot(workdir: str) -> set[str]:
+    names = set()
+    for entry in os.listdir(workdir):
+        if os.path.isfile(os.path.join(workdir, entry)):
+            names.add(entry)
+    return names
+
+
+def _run(cmd, *, cwd, timeout, label) -> subprocess.CompletedProcess:
+    env = dict(os.environ)
+    env.setdefault("HOME", os.path.expanduser("~"))
+    try:
+        return subprocess.run(
+            cmd,
+            cwd=cwd,
+            env=env,
+            capture_output=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as e:
+        out = (e.stdout or b"") + b"\n" + (e.stderr or b"")
+        raise CompileTimeout(
+            f"{label} timed out after {timeout}s",
+            detail=out.decode("utf-8", "replace")[-2000:],
+        ) from e
+
+
+def _rasterize(pdf_path, *, workdir, stem, ext, device, dpi, gs_bin, timeout) -> list[str]:
+    pattern = os.path.join(workdir, f"{stem}_{ext}_%d.{ext}")
+    cmd = [
+        gs_bin,
+        "-q",
+        "-dNOPAUSE",
+        "-dBATCH",
+        "-dSAFER",
+        f"-sDEVICE={device}",
+        f"-r{dpi}",
+        "-dTextAlphaBits=4",
+        "-dGraphicsAlphaBits=4",
+        f"-sOutputFile={pattern}",
+        pdf_path,
+    ]
+    try:
+        result = subprocess.run(
+            cmd, cwd=workdir, capture_output=True, timeout=timeout
+        )
+    except subprocess.TimeoutExpired as e:
+        raise RasterError(
+            f"ghostscript timed out after {timeout}s",
+            detail=(e.stderr or b"").decode("utf-8", "replace")[-2000:],
+        ) from e
+    if result.returncode != 0:
+        raise RasterError(
+            "ghostscript rasterization failed",
+            detail=result.stderr.decode("utf-8", "replace")[-2000:],
+        )
+
+    produced = sorted(
+        f for f in os.listdir(workdir) if f.startswith(f"{stem}_{ext}_") and f.endswith(f".{ext}")
+    )
+    if not produced:
+        raise RasterError("ghostscript produced no output", detail=pdf_path)
+    return produced
+
+
+def compile_source(
+    source: str,
+    *,
+    fmt: str,
+    dpi: int,
+    timeout: int,
+    asy_bin: str,
+    gs_bin: str,
+    tmp_dir: str | None,
+) -> list[CompiledFile]:
+    fmt = validate_format(fmt)
+    native = fmt if fmt in NATIVE_FORMATS else "pdf"
+
+    workdir = tempfile.mkdtemp(prefix="asyagent_", dir=tmp_dir)
+    try:
+        input_path = os.path.join(workdir, "input.asy")
+        with open(input_path, "w", encoding="utf-8") as f:
+            f.write(source)
+            if not source.endswith("\n"):
+                f.write("\n")
+
+        before = _snapshot(workdir)
+        cmd = [asy_bin, "-f", native, "-o", "out", "input.asy"]
+        result = _run(cmd, cwd=workdir, timeout=timeout, label="asy")
+
+        if result.returncode != 0:
+            stderr = result.stderr.decode("utf-8", "replace")
+            stdout = result.stdout.decode("utf-8", "replace")
+            detail = (stderr + "\n" + stdout).strip()[-4000:]
+            raise CompileError("asymptote compilation failed", detail=detail)
+
+        after = _snapshot(workdir)
+        new_outputs = sorted(
+            n for n in (after - before) if n.rsplit(".", 1)[-1].lower() in OUTPUT_EXTS
+        )
+
+        if not new_outputs:
+            listing = sorted(after - before)
+            raise CompileError(
+                "compilation produced no output",
+                detail=f"files produced: {listing}",
+            )
+
+        if fmt in NATIVE_FORMATS:
+            chosen = new_outputs
+        else:
+            device = GS_DEVICE[fmt]
+            chosen = []
+            for pdf_name in new_outputs:
+                stem = pdf_name.rsplit(".", 1)[0]
+                raster_names = _rasterize(
+                    os.path.join(workdir, pdf_name),
+                    workdir=workdir,
+                    stem=stem,
+                    ext=fmt,
+                    device=device,
+                    dpi=dpi,
+                    gs_bin=gs_bin,
+                    timeout=timeout,
+                )
+                chosen.extend(raster_names)
+
+        chosen = sorted(set(chosen))
+        files: list[CompiledFile] = []
+        for name in chosen:
+            ext = name.rsplit(".", 1)[-1].lower()
+            if ext == "jpeg":
+                ext = "jpg"
+            with open(os.path.join(workdir, name), "rb") as f:
+                data = f.read()
+            files.append(
+                CompiledFile(name=name, ext=ext, mime=MIME_BY_EXT.get(ext, "application/octet-stream"), data=data)
+            )
+        return files
+    finally:
+        shutil.rmtree(workdir, ignore_errors=True)
+
+
+def select_or_bundle(files: list[CompiledFile]) -> CompiledFile:
+    if not files:
+        raise CompileError("no output to return")
+    if len(files) == 1:
+        return files[0]
+
+    import io
+
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for f in files:
+            zf.writestr(f.name, f.data)
+    return CompiledFile(
+        name="asyagent-output.zip",
+        ext="zip",
+        mime=MIME_BY_EXT["zip"],
+        data=buf.getvalue(),
+    )

asyagent/config.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _env(name: str, default: str = "") -> str:
+    return os.environ.get(name, default)
+
+
+def _env_or_none(name: str) -> str | None:
+    v = os.environ.get(name)
+    return v if v not in (None, "") else None
+
+
+def _int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def _bool(name: str, default: bool) -> bool:
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+@dataclass
+class Settings:
+    host: str
+    port: int
+    max_workers: int
+    compile_timeout: int
+    max_timeout: int
+    fetch_timeout: int
+    max_source_bytes: int
+    max_fetch_bytes: int
+    asy_bin: str
+    gs_bin: str
+    default_format: str
+    default_mode: str
+    default_encoding: str
+    default_dpi: int
+    tmp_dir: str | None
+
+    storage_backend: str
+    local_dir: str
+    local_base_url: str | None
+
+    s3_endpoint: str | None
+    s3_region: str
+    s3_bucket: str | None
+    s3_prefix: str
+    s3_access_key: str | None
+    s3_secret_key: str | None
+    s3_security_token: str | None
+    s3_url_style: str
+    s3_public_base_url: str | None
+    s3_presign: bool
+    s3_presign_expires: int
+    s3_use_tls: bool
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        host = _env("ASYAGENT_HOST", "0.0.0.0")
+        port = _int("ASYAGENT_PORT", 8787)
+        default_format = _env("ASYAGENT_DEFAULT_FORMAT", "pdf").lower()
+        default_mode = _env("ASYAGENT_DEFAULT_MODE", "inline").lower()
+        default_encoding = _env("ASYAGENT_DEFAULT_ENCODING", "binary").lower()
+
+        backend = _env("ASYAGENT_STORAGE", "local").lower()
+        s3_endpoint = _env_or_none("S3_ENDPOINT") or _env_or_none("AWS_ENDPOINT_URL")
+        s3_region = _env("AWS_REGION", _env("AWS_DEFAULT_REGION", "us-east-1"))
+        s3_url_style = _env("S3_URL_STYLE", _env("S3_PATH_STYLE", "path")).lower()
+        if s3_url_style not in ("path", "virtual"):
+            s3_url_style = "path"
+
+        local_base_url = _env_or_none("ASYAGENT_LOCAL_BASE_URL")
+        if local_base_url is None:
+            local_base_url = f"http://{host if host != '0.0.0.0' else '127.0.0.1'}:{port}"
+
+        return cls(
+            host=host,
+            port=port,
+            max_workers=_int("ASYAGENT_MAX_WORKERS", 16),
+            compile_timeout=_int("ASYAGENT_COMPILE_TIMEOUT", 60),
+            max_timeout=_int("ASYAGENT_MAX_TIMEOUT", 300),
+            fetch_timeout=_int("ASYAGENT_FETCH_TIMEOUT", 20),
+            max_source_bytes=_int("ASYAGENT_MAX_SOURCE_BYTES", 1_048_576),
+            max_fetch_bytes=_int("ASYAGENT_MAX_FETCH_BYTES", 5_242_880),
+            asy_bin=_env("ASYAGENT_ASY_BIN", "asy"),
+            gs_bin=_env("ASYAGENT_GS_BIN", "gs"),
+            default_format=default_format,
+            default_mode=default_mode,
+            default_encoding=default_encoding,
+            default_dpi=_int("ASYAGENT_DEFAULT_DPI", 150),
+            tmp_dir=_env_or_none("ASYAGENT_TMP_DIR"),
+            storage_backend=backend,
+            local_dir=_env("ASYAGENT_LOCAL_DIR", "./storage"),
+            local_base_url=local_base_url,
+            s3_endpoint=s3_endpoint,
+            s3_region=s3_region,
+            s3_bucket=_env_or_none("S3_BUCKET"),
+            s3_prefix=_env("S3_PREFIX", "asyagent/"),
+            s3_access_key=_env_or_none("AWS_ACCESS_KEY_ID"),
+            s3_secret_key=_env_or_none("AWS_SECRET_ACCESS_KEY"),
+            s3_security_token=_env_or_none("AWS_SESSION_TOKEN")
+            or _env_or_none("AWS_SECURITY_TOKEN"),
+            s3_url_style=s3_url_style,
+            s3_public_base_url=_env_or_none("S3_PUBLIC_BASE_URL"),
+            s3_presign=_bool("S3_PRESIGN", False),
+            s3_presign_expires=_int("S3_PRESIGN_EXPIRES", 3600),
+            s3_use_tls=_bool("S3_USE_TLS", True),
+        )
+
+    def with_overrides(
+        self,
+        *,
+        storage_prefix: str | None = None,
+        storage_bucket: str | None = None,
+    ) -> "Settings":
+        return Settings(
+            host=self.host,
+            port=self.port,
+            max_workers=self.max_workers,
+            compile_timeout=self.compile_timeout,
+            max_timeout=self.max_timeout,
+            fetch_timeout=self.fetch_timeout,
+            max_source_bytes=self.max_source_bytes,
+            max_fetch_bytes=self.max_fetch_bytes,
+            asy_bin=self.asy_bin,
+            gs_bin=self.gs_bin,
+            default_format=self.default_format,
+            default_mode=self.default_mode,
+            default_encoding=self.default_encoding,
+            default_dpi=self.default_dpi,
+            tmp_dir=self.tmp_dir,
+            storage_backend=self.storage_backend,
+            local_dir=self.local_dir,
+            local_base_url=self.local_base_url,
+            s3_endpoint=self.s3_endpoint,
+            s3_region=self.s3_region,
+            s3_bucket=storage_bucket or self.s3_bucket,
+            s3_prefix=storage_prefix or self.s3_prefix,
+            s3_access_key=self.s3_access_key,
+            s3_secret_key=self.s3_secret_key,
+            s3_security_token=self.s3_security_token,
+            s3_url_style=self.s3_url_style,
+            s3_public_base_url=self.s3_public_base_url,
+            s3_presign=self.s3_presign,
+            s3_presign_expires=self.s3_presign_expires,
+            s3_use_tls=self.s3_use_tls,
+        )

asyagent/errors.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+
+class AsyAgentError(Exception):
+    status: int = 500
+    code: str = "internal_error"
+
+    def __init__(self, message: str, *, detail: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+
+    def to_dict(self) -> dict:
+        body = {"error": {"code": self.code, "message": self.message}}
+        if self.detail:
+            body["error"]["detail"] = self.detail
+        return body
+
+
+class BadRequest(AsyAgentError):
+    status = 400
+    code = "bad_request"
+
+
+class UnsupportedFormat(BadRequest):
+    code = "unsupported_format"
+
+
+class EmptyInput(BadRequest):
+    code = "empty_input"
+
+
+class InvalidInput(BadRequest):
+    code = "invalid_input"
+
+
+class InputTooLarge(BadRequest):
+    code = "input_too_large"
+
+
+class MissingStorage(BadRequest):
+    status = 409
+    code = "storage_unavailable"
+
+
+class FetchError(AsyAgentError):
+    status = 502
+    code = "fetch_failed"
+
+
+class CompileError(AsyAgentError):
+    status = 422
+    code = "compile_failed"
+
+
+class RasterError(AsyAgentError):
+    status = 502
+    code = "raster_failed"
+
+
+class CompileTimeout(AsyAgentError):
+    status = 504
+    code = "timeout"
+
+
+class StorageError(AsyAgentError):
+    status = 502
+    code = "storage_failed"
+
+
+class ServerBusy(AsyAgentError):
+    status = 503
+    code = "server_busy"

asyagent/fetcher.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import urllib.request
+import urllib.error
+
+from .errors import FetchError
+
+
+def fetch_source(url: str, *, timeout: int, max_bytes: int) -> str:
+    scheme = url.split("://", 1)[0].lower() if "://" in url else ""
+    if scheme not in ("http", "https"):
+        raise FetchError(f"unsupported URL scheme: {scheme!r}")
+
+    req = urllib.request.Request(url, headers={"User-Agent": "asyagent/0.1"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            content_type = (resp.headers.get("Content-Type") or "").split(";")[0].strip().lower()
+            declared = resp.headers.get("Content-Length")
+            if declared and declared.isdigit() and int(declared) > max_bytes:
+                raise FetchError(
+                    f"remote file too large ({int(declared)} > {max_bytes} bytes)",
+                    detail=url,
+                )
+            data = resp.read(max_bytes + 1)
+            if len(data) > max_bytes:
+                raise FetchError(
+                    f"remote file too large (> {max_bytes} bytes)", detail=url
+                )
+    except urllib.error.HTTPError as e:
+        raise FetchError(f"remote returned HTTP {e.code}", detail=str(e.reason)) from e
+    except urllib.error.URLError as e:
+        raise FetchError(f"failed to fetch URL: {e.reason}", detail=url) from e
+    except TimeoutError as e:
+        raise FetchError(f"fetch timed out after {timeout}s", detail=url) from e
+
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        try:
+            text = data.decode("latin-1")
+        except Exception as e:
+            raise FetchError("remote file is not valid text", detail=url) from e
+
+    if content_type and content_type not in (
+        "",
+        "text/plain",
+        "text/x-asy",
+        "text/y-asy",
+        "application/octet-stream",
+        "text/markdown",
+    ) and not content_type.startswith("text/"):
+        raise FetchError(
+            f"unexpected remote content-type: {content_type}", detail=url
+        )
+
+    return text