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

py_serverless_kit/providers/oracle.py

@@ -0,0 +1,304 @@
+"""Oracle Cloud Infrastructure: OCI Functions (container images) + API Gateway + Events.
+
+OCI Functions only run container images. pskit writes ``Dockerfile``,
+``func.yaml`` and ``func.py`` into the bundle and either
+
+* uses a pre-built image (``options.image``), or
+* builds and pushes one with your local Docker (``options.image_repository``),
+  tagged with the artifact hash, from a ``terraform_data`` resource.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from ..config.schema import ServiceConfig
+from .base import HTTP, STORAGE, Issue, Provider, RenderContext
+from .terraform_doc import TerraformDoc, escape, ref, tf_id
+
+FUNCTION = "oci_functions_function"
+_EVENT_TYPES = {
+    "created": ["com.oraclecloud.objectstorage.createobject", "com.oraclecloud.objectstorage.updateobject"],
+    "deleted": ["com.oraclecloud.objectstorage.deleteobject"],
+}
+
+
+def oci_path(path: str) -> str:
+    """``/files/{path+}`` -> ``/files/{path*}`` (OCI's greedy wildcard)."""
+    return path.replace("+}", "*}")
+
+
+class OracleProvider(Provider):
+    name = "oracle"
+    display_name = "Oracle Cloud Functions"
+    tier = "experimental"
+    terraform_source = "oracle/oci"
+    terraform_version = ">= 6.0"
+    terraform_local_name = "oci"
+    default_region = "us-ashburn-1"
+    capabilities = frozenset({HTTP, STORAGE})
+    max_name_length = 100
+    runtimes = {"python3.9": "3.9", "python3.11": "3.11"}
+    vendor_dependencies = False  # dependencies are installed inside the Docker build
+    extra_requirements = ["fdk>=0.1.71"]
+    max_timeout = 300
+    notes = (
+        "Functions run as container images: set options.image (pre-built) or options.image_repository "
+        "(pskit runs docker build/push). Needs options.compartment_id and options.subnet_ids. HTTP via API "
+        "Gateway, object-storage triggers via Events rules. No schedule/queue/topic triggers. You must add IAM "
+        "policies letting API Gateway and Events invoke functions."
+    )
+
+    # ------------------------------------------------------------------ bundle
+    def shim_files(self, config: ServiceConfig) -> Dict[str, str]:
+        version = self.runtimes.get(config.provider.runtime, "3.11")
+        return {
+            "func.py": (
+                "# Generated by py-serverless-kit. FDK entrypoint: func.handler\n"
+                "from py_serverless_kit.runtime.adapters.oracle import handler  # noqa: F401\n"
+            ),
+            "func.yaml": (
+                "schema_version: 20180708\n"
+                f"name: {config.service}\n"
+                "version: 0.0.1\n"
+                "runtime: python\n"
+                f"build_image: fnproject/python:{version}-dev\n"
+                f"run_image: fnproject/python:{version}\n"
+                "entrypoint: /python/bin/fdk /function/func.py handler\n"
+                f"memory: {config.provider.memory}\n"
+            ),
+            "Dockerfile": (
+                "# Generated by py-serverless-kit\n"
+                f"FROM fnproject/python:{version}-dev AS build-stage\n"
+                "WORKDIR /function\n"
+                "COPY requirements.txt /function/\n"
+                "RUN pip3 install --target /python/ --no-cache-dir -r requirements.txt && chmod -R o+r /python\n"
+                "COPY . /function/\n"
+                f"FROM fnproject/python:{version}\n"
+                "WORKDIR /function\n"
+                "COPY --from=build-stage /python /python\n"
+                "COPY --from=build-stage /function /function\n"
+                "RUN chmod -R o+r /function\n"
+                "ENV PYTHONPATH=/function:/python\n"
+                'ENTRYPOINT ["/python/bin/fdk", "/function/func.py", "handler"]\n'
+            ),
+        }
+
+    def provider_block(self, ctx: RenderContext) -> Dict[str, Any]:
+        block: Dict[str, Any] = {"region": ctx.region}
+        for key in ("config_file_profile", "auth", "tenancy_ocid", "user_ocid", "fingerprint", "private_key_path"):
+            if ctx.opt(key):
+                block[key] = ctx.opt(key)
+        return block
+
+    def extra_validation(self, config: ServiceConfig) -> List[Issue]:
+        opts = config.provider.options
+        issues: List[Issue] = []
+        if not opts.get("compartment_id"):
+            issues.append(Issue("error", "options.compartment_id is required", "provider.options"))
+        if not opts.get("subnet_ids"):
+            issues.append(Issue("error", "options.subnet_ids (list of subnet OCIDs) is required", "provider.options"))
+        if not opts.get("image") and not opts.get("image_repository"):
+            issues.append(
+                Issue(
+                    "error",
+                    "OCI Functions need a container image. Either set options.image_repository "
+                    "(e.g. iad.ocir.io/<namespace>/<repo>) and pskit runs `docker build` + `docker push` for you, "
+                    "or build it yourself and set options.image:\n"
+                    "    docker login <region-key>.ocir.io\n"
+                    "    docker build -t <image> .pskit/oracle-<stage>/build\n"
+                    "    docker push <image>",
+                    "provider.options.image",
+                )
+            )
+        has_http = False
+        for name, fn in config.functions.items():
+            for ev in fn.events_of("http"):
+                has_http = True
+                if ev.auth != "none":
+                    issues.append(
+                        Issue(
+                            "error",
+                            f"auth `{ev.auth}` is not wired up for OCI API Gateway yet; "
+                            "use options to add an authentication policy",
+                            f"functions.{name}",
+                        )
+                    )
+            for ev in fn.events_of("storage"):
+                if ev.prefix or ev.suffix:
+                    issues.append(
+                        Issue(
+                            "warning",
+                            "OCI Events rules cannot filter by prefix/suffix; filter in the handler",
+                            f"functions.{name}",
+                        )
+                    )
+                if ev.existing:
+                    issues.append(
+                        Issue(
+                            "warning", f"bucket {ev.bucket} must have 'Emit Object Events' enabled", f"functions.{name}"
+                        )
+                    )
+        if has_http:
+            issues.append(
+                Issue(
+                    "warning",
+                    "API Gateway needs an IAM policy to call functions, e.g. `ALLOW any-user to use functions-family "
+                    "in compartment <name> where ALL {request.principal.type = 'ApiGateway'}`",
+                    "provider",
+                )
+            )
+        return issues
+
+    # ------------------------------------------------------------------ render
+    def _image(self, doc: TerraformDoc, ctx: RenderContext) -> tuple[str, List[str]]:
+        if ctx.opt("image"):
+            return str(ctx.opt("image")), []
+        repo = str(ctx.opt("image_repository", "")).rstrip("/")
+        image = f"{repo}:{ctx.artifact.sha256[:16]}"
+        platform = "linux/arm64" if ctx.config.provider.architecture == "arm64" else "linux/amd64"
+        build = doc.resource(
+            "terraform_data",
+            "image",
+            {
+                "triggers_replace": [image],
+                "provisioner": [
+                    {
+                        "local-exec": {
+                            "working_dir": "${path.module}",
+                            "command": f"docker build --platform {platform} -t {image} build && docker push {image}",
+                        }
+                    }
+                ],
+            },
+        )
+        return image, [build]
+
+    def render_resources(self, doc: TerraformDoc, ctx: RenderContext) -> None:
+        cfg = ctx.config
+        compartment = str(ctx.opt("compartment_id", ""))
+        subnets = list(ctx.opt("subnet_ids") or [])
+        image, depends = self._image(doc, ctx)
+        app = doc.resource(
+            "oci_functions_application",
+            "app",
+            {
+                "compartment_id": compartment,
+                "display_name": ctx.prefix,
+                "subnet_ids": subnets,
+                "shape": "GENERIC_ARM" if cfg.provider.architecture == "arm64" else "GENERIC_X86",
+                "freeform_tags": ctx.tags(),
+            },
+        )
+        fns: Dict[str, str] = {}
+        for name, fn in ctx.function_items():
+            body: Dict[str, Any] = {
+                "application_id": ref(app, "id"),
+                "display_name": ctx.physical_name(name),
+                "image": image,
+                "memory_in_mbs": str(cfg.memory_of(fn)),
+                "timeout_in_seconds": cfg.timeout_of(fn),
+                "config": {k: escape(v) for k, v in ctx.environment(name, fn).items()},
+                "freeform_tags": ctx.tags(fn),
+            }
+            if depends:
+                body["depends_on"] = depends
+            body.update(fn.options)
+            fns[name] = doc.resource(FUNCTION, name, body)
+
+        deployment = self._http(doc, ctx, compartment, subnets, fns)
+        self._storage(doc, ctx, compartment, fns)
+
+        fn_out: Dict[str, Dict[str, Any]] = {}
+        for name, fn in ctx.function_items():
+            out: Dict[str, Any] = {
+                "id": ref(fns[name], "id"),
+                "console": f"https://cloud.oracle.com/functions/apps/{ref(app, 'id')}/fn/{ref(fns[name], 'id')}"
+                f"?region={ctx.region}",
+            }
+            if deployment and fn.events_of("http"):
+                out["base_url"] = ref(deployment, "endpoint")
+            fn_out[name] = out
+        wf_out = {n: {"id": ref(FUNCTION, tf_id(f"{n}-orchestrator"), "id")} for n in cfg.workflows}
+        doc.output(
+            "pskit",
+            {"functions": fn_out, "workflows": wf_out, "endpoint": ref(deployment, "endpoint") if deployment else None},
+            description="py-serverless-kit deployment summary",
+        )
+
+    def _http(
+        self, doc: TerraformDoc, ctx: RenderContext, compartment: str, subnets: List[str], fns: Dict[str, str]
+    ) -> Optional[str]:
+        routes = []
+        for name, fn in ctx.function_items():
+            for ev in fn.events_of("http"):
+                methods = [ev.method]
+                if ev.cors_config is not None and ev.method not in ("ANY", "OPTIONS"):
+                    methods.append("OPTIONS")
+                routes.append(
+                    {
+                        "path": oci_path(ev.path),
+                        "methods": methods,
+                        "backend": {"type": "ORACLE_FUNCTIONS_BACKEND", "function_id": ref(fns[name], "id")},
+                    }
+                )
+        if not routes:
+            return None
+        subnet = ctx.opt("gateway_subnet_id") or (subnets[0] if subnets else "")
+        gw = doc.resource(
+            "oci_apigateway_gateway",
+            "gateway",
+            {
+                "compartment_id": compartment,
+                "display_name": ctx.prefix,
+                "endpoint_type": str(ctx.opt("gateway_endpoint_type", "PUBLIC")),
+                "subnet_id": subnet,
+                "freeform_tags": ctx.tags(),
+            },
+        )
+        return doc.resource(
+            "oci_apigateway_deployment",
+            "http",
+            {
+                "compartment_id": compartment,
+                "gateway_id": ref(gw, "id"),
+                "display_name": ctx.prefix,
+                "path_prefix": f"/{ctx.service}",
+                "specification": {"routes": routes},
+                "freeform_tags": ctx.tags(),
+            },
+        )
+
+    def _storage(self, doc: TerraformDoc, ctx: RenderContext, compartment: str, fns: Dict[str, str]) -> None:
+        for name, fn in ctx.function_items():
+            for ev in fn.events_of("storage"):
+                label = f"b-{ev.bucket}"
+                if not ev.existing and not doc.has_resource("oci_objectstorage_bucket", label):
+                    ns = doc.data("oci_objectstorage_namespace", "ns", {"compartment_id": compartment})
+                    doc.resource(
+                        "oci_objectstorage_bucket",
+                        label,
+                        {
+                            "compartment_id": compartment,
+                            "name": ev.bucket,
+                            "namespace": ref(ns, "namespace"),
+                            "object_events_enabled": True,
+                            "freeform_tags": ctx.tags(),
+                        },
+                    )
+                types = [t for e in ev.events for t in _EVENT_TYPES[e]]
+                condition = {"eventType": types, "data": {"additionalDetails": {"bucketName": ev.bucket}}}
+                body: Dict[str, Any] = {
+                    "compartment_id": compartment,
+                    "display_name": ctx.physical_name(f"{name}-{ev.bucket}"),
+                    "is_enabled": True,
+                    "condition": escape(json.dumps(condition)),
+                    "actions": {
+                        "actions": [{"action_type": "FAAS", "is_enabled": True, "function_id": ref(fns[name], "id")}]
+                    },
+                    "freeform_tags": ctx.tags(),
+                }
+                if not ev.existing:
+                    body["depends_on"] = [f"oci_objectstorage_bucket.{tf_id(label)}"]
+                doc.resource("oci_events_rule", f"{name}-{ev.bucket}", body)

py_serverless_kit/providers/registry.py

@@ -0,0 +1,60 @@
+"""Provider registry. Third-party providers can register through the
+``py_serverless_kit.providers`` entry-point group."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Dict, List, Type
+
+from .base import Provider, ProviderError
+
+BUILTIN: Dict[str, str] = {
+    "aws": "py_serverless_kit.providers.aws:AwsProvider",
+    "azure": "py_serverless_kit.providers.azure:AzureProvider",
+    "gcp": "py_serverless_kit.providers.gcp:GcpProvider",
+    "alibaba": "py_serverless_kit.providers.alibaba:AlibabaProvider",
+    "oracle": "py_serverless_kit.providers.oracle:OracleProvider",
+    "ibm": "py_serverless_kit.providers.ibm:IbmProvider",
+    "digitalocean": "py_serverless_kit.providers.digitalocean:DigitalOceanProvider",
+    "tencent": "py_serverless_kit.providers.tencent:TencentProvider",
+    "huawei": "py_serverless_kit.providers.huawei:HuaweiProvider",
+    "cloudflare": "py_serverless_kit.providers.cloudflare:CloudflareProvider",
+}
+
+_CACHE: Dict[str, Provider] = {}
+
+
+def _load(target: str) -> Type[Provider]:
+    module, _, attr = target.partition(":")
+    return getattr(importlib.import_module(module), attr)
+
+
+def _entry_points() -> Dict[str, str]:
+    try:
+        from importlib.metadata import entry_points
+    except ImportError:  # pragma: no cover
+        return {}
+    try:
+        eps = entry_points(group="py_serverless_kit.providers")  # type: ignore[call-arg]
+    except TypeError:  # pragma: no cover - Python 3.9
+        eps = entry_points().get("py_serverless_kit.providers", [])  # type: ignore[attr-defined,arg-type]
+    return {ep.name: ep.value for ep in eps}
+
+
+def available() -> List[str]:
+    return sorted(set(BUILTIN) | set(_entry_points()))
+
+
+def get_provider(name: str) -> Provider:
+    if name in _CACHE:
+        return _CACHE[name]
+    target = BUILTIN.get(name) or _entry_points().get(name)
+    if target is None:
+        raise ProviderError(f"unknown provider {name!r}; available: {', '.join(available())}")
+    provider = _load(target)()
+    _CACHE[name] = provider
+    return provider
+
+
+def all_providers() -> List[Provider]:
+    return [get_provider(n) for n in available()]

py_serverless_kit/providers/schedule.py

@@ -0,0 +1,153 @@
+"""Convert the portable schedule syntax into each provider's dialect.
+
+The config accepts:
+
+* ``rate: "<n> minutes|hours|days"``
+* ``cron: "<min> <hour> <day-of-month> <month> <day-of-week>"`` (standard 5-field unix cron)
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Tuple
+
+from ..config.schema import ScheduleEvent
+
+_RATE = re.compile(r"^\s*(\d+)\s+(minute|minutes|hour|hours|day|days)\s*$", re.I)
+
+
+class ScheduleError(ValueError):
+    pass
+
+
+def parse_rate(rate: str) -> Tuple[int, str]:
+    m = _RATE.match(rate)
+    if not m:
+        raise ScheduleError(f"invalid rate {rate!r}")
+    value, unit = int(m.group(1)), m.group(2).lower().rstrip("s")
+    if value <= 0:
+        raise ScheduleError("rate must be positive")
+    return value, unit  # unit in minute|hour|day
+
+
+def rate_to_cron(rate: str) -> str:
+    """Best-effort conversion of a rate to standard 5-field cron."""
+    value, unit = parse_rate(rate)
+    if unit == "minute":
+        if value < 60 and 60 % value == 0:
+            return "* * * * *" if value == 1 else f"*/{value} * * * *"
+        if value % 60 == 0:
+            return rate_to_cron(f"{value // 60} hours")
+        raise ScheduleError(f"rate {rate!r} is not expressible as cron; use a divisor of 60 minutes")
+    if unit == "hour":
+        if value < 24 and 24 % value == 0:
+            return "0 * * * *" if value == 1 else f"0 */{value} * * *"
+        if value % 24 == 0:
+            return rate_to_cron(f"{value // 24} days")
+        raise ScheduleError(f"rate {rate!r} is not expressible as cron; use a divisor of 24 hours")
+    if value == 1:
+        return "0 0 * * *"
+    if value <= 31:
+        return f"0 0 */{value} * *"
+    raise ScheduleError(f"rate {rate!r} is too long for cron")
+
+
+def to_cron5(ev: ScheduleEvent) -> str:
+    return ev.cron.strip() if ev.cron else rate_to_cron(ev.rate or "")
+
+
+def to_seconds(ev: ScheduleEvent) -> int:
+    value, unit = parse_rate(ev.rate or "")
+    return value * {"minute": 60, "hour": 3600, "day": 86400}[unit]
+
+
+# ----------------------------------------------------------------- dialects
+
+
+def _aws_dow(field: str) -> str:
+    """unix 0-6 (Sun=0) -> AWS 1-7 (Sun=1). Names pass through."""
+
+    def conv(token: str) -> str:
+        if token.isdigit():
+            return str(int(token) % 7 + 1)
+        return token
+
+    out = []
+    for part in field.split(","):
+        step = ""
+        if "/" in part:
+            part, step = part.split("/", 1)
+            step = "/" + step
+        if "-" in part:
+            a, b = part.split("-", 1)
+            out.append(f"{conv(a)}-{conv(b)}{step}")
+        else:
+            out.append(conv(part) + step)
+    return ",".join(out)
+
+
+def aws_expression(ev: ScheduleEvent) -> str:
+    if ev.rate:
+        value, unit = parse_rate(ev.rate)
+        return f"rate({value} {unit}{'' if value == 1 else 's'})"
+    minute, hour, dom, month, dow = ev.cron.split()  # type: ignore[union-attr]
+    if dow != "*" and dom == "*":
+        dom = "?"
+        dow = _aws_dow(dow)
+    elif dow != "*" and dom != "*":
+        raise ScheduleError("AWS cron cannot restrict both day-of-month and day-of-week")
+    else:
+        dow = "?"
+    return f"cron({minute} {hour} {dom} {month} {dow} *)"
+
+
+def ncrontab(ev: ScheduleEvent) -> str:
+    """Azure Functions timer trigger: 6 fields, seconds first."""
+    if ev.rate:
+        value, unit = parse_rate(ev.rate)
+        if unit == "minute" and value < 60:
+            return f"0 */{value} * * * *"
+    return "0 " + to_cron5(ev)
+
+
+def cron_with_seconds(ev: ScheduleEvent) -> str:
+    """Alibaba / Huawei style 6-field cron (seconds first)."""
+    return "0 " + to_cron5(ev)
+
+
+def tencent_cron(ev: ScheduleEvent) -> str:
+    """Tencent SCF: 7 fields, seconds first, year last."""
+    return "0 " + to_cron5(ev) + " *"
+
+
+def every_expression(ev: ScheduleEvent) -> str:
+    """``@every 5m`` style used by Alibaba FC and Huawei FunctionGraph."""
+    if not ev.rate:
+        raise ScheduleError("@every expressions require `rate`")
+    value, unit = parse_rate(ev.rate)
+    return f"@every {value}{unit[0]}"
+
+
+_DOW_NAMES = ("SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT")
+
+
+def named_cron5(ev: ScheduleEvent) -> str:
+    """Standard 5-field cron with numeric day-of-week replaced by SUN..SAT.
+
+    Clouds disagree on numeric weekdays (0=Sun vs 1=Sun); names are unambiguous.
+    """
+    minute, hour, dom, month, dow = to_cron5(ev).split()
+
+    def conv(token: str) -> str:
+        return _DOW_NAMES[int(token) % 7] if token.isdigit() else token
+
+    parts = []
+    for part in dow.split(","):
+        base, slash, step = part.partition("/")
+        if "-" in base:
+            a, b = base.split("-", 1)
+            base = f"{conv(a)}-{conv(b)}"
+        else:
+            base = conv(base)
+        parts.append(base + slash + step)
+    return " ".join([minute, hour, dom, month, ",".join(parts)])