py-serverless-kit 0.1.0__py3-none-any.whl

py_serverless_kit/providers/digitalocean.py

@@ -0,0 +1,211 @@
+"""DigitalOcean Functions.
+
+The DigitalOcean Terraform provider has no resource for Functions, so pskit
+renders a standard ``doctl serverless`` project (``do_project/project.yml`` +
+``packages/<service>-<stage>/<fn>/``) and deploys it from a ``terraform_data``
+resource with ``local-exec`` provisioners. Terraform therefore tracks *when*
+to redeploy (artifact hash) while ``doctl`` does the upload.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from ..config.schema import ServiceConfig
+from ..runtime.adapters.base import envelope
+from . import schedule as sched
+from .base import HTTP, SCHEDULE, Issue, Provider, RenderContext
+from .terraform_doc import TerraformDoc
+
+PROJECT_DIR = "do_project"
+
+
+class DigitalOceanProvider(Provider):
+    name = "digitalocean"
+    display_name = "DigitalOcean Functions"
+    tier = "beta"
+    terraform_source = "terraform.io/builtin/terraform"  # terraform_data + doctl, no cloud provider plugin
+    default_region = ""
+    capabilities = frozenset({HTTP, SCHEDULE})
+    max_name_length = 63
+    runtimes = {"python3.9": "python:3.9", "python3.11": "python:3.11"}
+    vendor_dependencies = True
+    max_timeout = 900
+    notes = (
+        "Deployed with `doctl serverless deploy` (doctl must be installed and authenticated: "
+        "`doctl auth init`). Requires options.namespace (fn-...); set options.api_host to get URLs. "
+        "Supports http (web: raw, public) and schedule triggers only. Runtimes: python3.9 / python3.11."
+    )
+
+    # ------------------------------------------------------------------ terraform header
+    def init_doc(self, ctx: RenderContext) -> TerraformDoc:
+        doc = TerraformDoc()
+        doc.required_version(ctx.config.provider.terraform.required_version)
+        state = ctx.config.provider.state
+        if state.backend:
+            doc.backend(state.backend, state.config)
+        return doc
+
+    def provider_block(self, ctx: RenderContext) -> Optional[Dict[str, Any]]:
+        return None
+
+    def region(self, config: ServiceConfig) -> str:
+        return config.provider.region or str(config.provider.options.get("region", ""))
+
+    # ------------------------------------------------------------------ bundle
+    def shim_files(self, config: ServiceConfig) -> Dict[str, str]:
+        return {
+            "__main__.py": (
+                "# Generated by py-serverless-kit. DigitalOcean entrypoint: main(event, context)\n"
+                "from py_serverless_kit.runtime.adapters.digitalocean import main  # noqa: F401\n"
+            )
+        }
+
+    def extra_validation(self, config: ServiceConfig) -> List[Issue]:
+        issues: List[Issue] = []
+        if not config.provider.options.get("namespace"):
+            issues.append(
+                Issue(
+                    "error",
+                    "options.namespace is required (see `doctl serverless namespaces list`)",
+                    "provider.options.namespace",
+                )
+            )
+        if shutil.which("doctl") is None:
+            issues.append(
+                Issue(
+                    "warning",
+                    "`doctl` is not on PATH; deploy will fail until it is installed and "
+                    "authenticated (`doctl auth init`)",
+                    "provider",
+                )
+            )
+        for name, fn in config.functions.items():
+            mem = config.memory_of(fn)
+            if not 128 <= mem <= 1024:
+                issues.append(
+                    Issue(
+                        "error",
+                        f"memory {mem} MB is outside DigitalOcean's 128-1024 MB range",
+                        f"functions.{name}.memory",
+                    )
+                )
+            for ev in fn.events_of("http"):
+                if ev.auth != "none":
+                    issues.append(
+                        Issue(
+                            "error",
+                            f"auth `{ev.auth}` is not supported; DigitalOcean web functions "
+                            "are public - validate tokens in the handler",
+                            f"functions.{name}",
+                        )
+                    )
+        return issues
+
+    # ------------------------------------------------------------------ render
+    def package_name(self, ctx: RenderContext) -> str:
+        return ctx.prefix
+
+    def project_spec(self, ctx: RenderContext) -> Dict[str, Any]:
+        cfg = ctx.config
+        functions = []
+        for name, fn in ctx.function_items():
+            spec: Dict[str, Any] = {
+                "name": name,
+                "runtime": self.runtime_id(cfg.runtime_of(fn)),
+                "main": "main",
+                "web": "raw" if fn.events_of("http") else False,
+                "limits": {"timeout": cfg.timeout_of(fn) * 1000, "memory": cfg.memory_of(fn)},
+                "environment": ctx.environment(name, fn),
+            }
+            triggers = []
+            for i, ev in enumerate(fn.events_of("schedule")):
+                if not ev.enabled:
+                    continue
+                triggers.append(
+                    {
+                        "name": f"{name}-{ev.name or i}",
+                        "sourceType": "scheduler",
+                        "sourceDetails": {
+                            "cron": sched.to_cron5(ev),
+                            "withBody": envelope("schedule", ev.input, source="digitalocean.scheduler"),
+                        },
+                    }
+                )
+            if triggers:
+                spec["triggers"] = triggers
+            spec.update(fn.options)
+            functions.append(spec)
+        return {"packages": [{"name": self.package_name(ctx), "functions": functions}]}
+
+    def write_project(self, ctx: RenderContext) -> str:
+        """Materialise the doctl project next to main.tf.json; return a content hash."""
+        root = ctx.work_dir / PROJECT_DIR
+        if root.exists():
+            shutil.rmtree(root)
+        spec = self.project_spec(ctx)
+        build = ctx.artifact.build_dir
+        pkg = self.package_name(ctx)
+        for fn in spec["packages"][0]["functions"]:
+            dest = root / "packages" / pkg / fn["name"]
+            if build is not None and Path(build).is_dir():
+                shutil.copytree(build, dest)
+            else:  # pragma: no cover - build_dir is always set by the packager
+                dest.mkdir(parents=True)
+        text = yaml.safe_dump(spec, sort_keys=False)
+        (root / "project.yml").write_text(text, "utf-8")
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+    def render_resources(self, doc: TerraformDoc, ctx: RenderContext) -> None:
+        cfg = ctx.config
+        namespace = str(ctx.opt("namespace", ""))
+        pkg = self.package_name(ctx)
+        project_hash = self.write_project(ctx)
+        doc.resource(
+            "terraform_data",
+            "deploy",
+            {
+                "triggers_replace": [ctx.artifact.sha256, project_hash],
+                "input": {"namespace": namespace, "package": pkg},
+                "provisioner": [
+                    {
+                        "local-exec": {
+                            "working_dir": "${path.module}",
+                            "command": f"doctl serverless connect {namespace} && doctl serverless deploy {PROJECT_DIR}",
+                        }
+                    },
+                    {
+                        "local-exec": {
+                            "when": "destroy",
+                            "command": "doctl serverless connect ${self.input.namespace} && "
+                            "doctl serverless undeploy --packages ${self.input.package}",
+                        }
+                    },
+                ],
+            },
+        )
+        api_host = str(ctx.opt("api_host", "")).rstrip("/")
+        fn_out: Dict[str, Dict[str, Any]] = {}
+        endpoint: Optional[str] = None
+        for name, fn in ctx.function_items():
+            url = f"{api_host}/api/v1/web/{namespace}/{pkg}/{name}" if api_host and fn.events_of("http") else None
+            out: Dict[str, Any] = {
+                "id": f"{pkg}/{name}",
+                "url": url,
+                "console": "https://cloud.digitalocean.com/functions",
+            }
+            if url:
+                out["base_url"] = url
+                endpoint = endpoint or f"{api_host}/api/v1/web/{namespace}/{pkg}"
+            fn_out[name] = out
+        wf_out = {n: {"id": f"{pkg}/{n}-orchestrator"} for n in cfg.workflows}
+        doc.output(
+            "pskit",
+            {"functions": fn_out, "workflows": wf_out, "endpoint": endpoint},
+            description="py-serverless-kit deployment summary",
+        )