make-cloudflare 0.2.0__tar.gz → 0.4.0__tar.gz

{make_cloudflare-0.2.0 → make_cloudflare-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: make-cloudflare
-Version: 0.2.0
+Version: 0.4.0
 Summary: Cloudflare Pages direct upload for mkrun -- deploy a built site with no Node and no wrangler.
 Project-URL: Homepage, https://make.optersoft.com
 Author-email: "Optersoft, S.L." <david@optersoft.com>
@@ -21,7 +21,7 @@ in the pipeline.
 # Makefile.py in a consuming repo
 # /// script
 # requires-python = ">=3.11"
-# dependencies = ["mkrun>=0.4", "make-cloudflare>=0.1"]
+# dependencies = ["mkrun>=0.4.1", "make-cloudflare>=0.3"]
 # ///
 from make_cloudflare import cloudflare  # importing is what registers the group
 ```
@@ -29,6 +29,7 @@ from make_cloudflare import cloudflare  # importing is what registers the group
 ```console
 $ mk cloudflare.deploy site/dist --project mkrun     # production (branch main)
 $ mk cloudflare.deploy site/dist --branch try        # a preview, on its own URL
+$ mk cloudflare.deploy dist --functions functions    # with Pages Functions
 $ mk cloudflare.projects                             # what the account has
 $ mk cloudflare.deployments --limit 5                # one project's recent ones
 $ mk cloudflare.prune --keep 10                      # delete all but the newest ten
@@ -50,6 +51,24 @@ Python). Pages never deletes one by itself, and each stays reachable on its own
 never deleted, however old; a pruned preview that was still its branch's alias
 takes that branch URL with it.
 
+**Pages Functions go up with the deployment.** `--functions functions` (or
+`pages.deploy(..., functions=)`) names the tree. It sits **beside** the built
+directory, as wrangler expects, and `/api/...` answers from the same project and
+origin. Bundling it is a build step, not an upload, so that one step is
+`wrangler pages functions build --outfile` (from PATH, or through `npx`). It
+writes exactly the `_worker.bundle` the deployment takes, plus
+`functions-filepath-routing-config.json` and a generated `_routes.json`; the
+site's own `_routes.json` wins. Everything else is still the four calls below.
+Bindings (D1, KV) and secrets are settings on the Pages project, never part of
+the upload.
+
+**Those settings are one call.** `pages.configure(project, d1={"DB": "<id>"},
+vars={...}, compatibility_date="2026-10-01")` PATCHes the project's
+`production` (or `preview`) configuration. Only what you pass is sent, and
+Cloudflare merges it in. It takes effect on the **next** deployment. Secrets
+are not set this way: a plain variable is shown in the dashboard, so a secret
+goes through `wrangler pages secret put`.
+
 ## Why this exists
 
 `wrangler pages deploy` is four HTTPS calls and a hash. Reaching them through
@@ -80,9 +99,9 @@ call returns 200 and the site serves the old bytes, or none:
 
 ## What it does not do
 
-**Pages Functions.** A directory holding `_worker.js` or `functions/` is
-refused by name rather than half-deployed: bundling a Worker is a build step,
-not an upload, and wrangler should keep doing it.
+**Advanced-mode `_worker.js`.** A `_worker.js` (or a `functions/`) *inside*
+the built directory is refused by name: it would otherwise be served as a
+static file. Pages Functions go beside it, through `--functions`.
 
 **Steps 2 and 3 are undocumented.** They exist because wrangler uses them, and
 Cloudflare can change them without a changelog; the documented `deployments`

{make_cloudflare-0.2.0 → make_cloudflare-0.4.0}/README.md

@@ -8,7 +8,7 @@ in the pipeline.
 # Makefile.py in a consuming repo
 # /// script
 # requires-python = ">=3.11"
-# dependencies = ["mkrun>=0.4", "make-cloudflare>=0.1"]
+# dependencies = ["mkrun>=0.4.1", "make-cloudflare>=0.3"]
 # ///
 from make_cloudflare import cloudflare  # importing is what registers the group
 ```
@@ -16,6 +16,7 @@ from make_cloudflare import cloudflare  # importing is what registers the group
 ```console
 $ mk cloudflare.deploy site/dist --project mkrun     # production (branch main)
 $ mk cloudflare.deploy site/dist --branch try        # a preview, on its own URL
+$ mk cloudflare.deploy dist --functions functions    # with Pages Functions
 $ mk cloudflare.projects                             # what the account has
 $ mk cloudflare.deployments --limit 5                # one project's recent ones
 $ mk cloudflare.prune --keep 10                      # delete all but the newest ten
@@ -37,6 +38,24 @@ Python). Pages never deletes one by itself, and each stays reachable on its own
 never deleted, however old; a pruned preview that was still its branch's alias
 takes that branch URL with it.
 
+**Pages Functions go up with the deployment.** `--functions functions` (or
+`pages.deploy(..., functions=)`) names the tree. It sits **beside** the built
+directory, as wrangler expects, and `/api/...` answers from the same project and
+origin. Bundling it is a build step, not an upload, so that one step is
+`wrangler pages functions build --outfile` (from PATH, or through `npx`). It
+writes exactly the `_worker.bundle` the deployment takes, plus
+`functions-filepath-routing-config.json` and a generated `_routes.json`; the
+site's own `_routes.json` wins. Everything else is still the four calls below.
+Bindings (D1, KV) and secrets are settings on the Pages project, never part of
+the upload.
+
+**Those settings are one call.** `pages.configure(project, d1={"DB": "<id>"},
+vars={...}, compatibility_date="2026-10-01")` PATCHes the project's
+`production` (or `preview`) configuration. Only what you pass is sent, and
+Cloudflare merges it in. It takes effect on the **next** deployment. Secrets
+are not set this way: a plain variable is shown in the dashboard, so a secret
+goes through `wrangler pages secret put`.
+
 ## Why this exists
 
 `wrangler pages deploy` is four HTTPS calls and a hash. Reaching them through
@@ -67,9 +86,9 @@ call returns 200 and the site serves the old bytes, or none:
 
 ## What it does not do
 
-**Pages Functions.** A directory holding `_worker.js` or `functions/` is
-refused by name rather than half-deployed: bundling a Worker is a build step,
-not an upload, and wrangler should keep doing it.
+**Advanced-mode `_worker.js`.** A `_worker.js` (or a `functions/`) *inside*
+the built directory is refused by name: it would otherwise be served as a
+static file. Pages Functions go beside it, through `--functions`.
 
 **Steps 2 and 3 are undocumented.** They exist because wrangler uses them, and
 Cloudflare can change them without a changelog; the documented `deployments`

{make_cloudflare-0.2.0 → make_cloudflare-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "make-cloudflare"
-version = "0.2.0"
+version = "0.4.0"
 description = "Cloudflare Pages direct upload for mkrun -- deploy a built site with no Node and no wrangler."
 readme = "README.md"
 requires-python = ">=3.11"

{make_cloudflare-0.2.0 → make_cloudflare-0.4.0}/src/make_cloudflare/__init__.py

@@ -17,7 +17,7 @@ namespaces, and this package claims only the four names above.
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 __all__ = ["cloudflare", "pages"]
 

{make_cloudflare-0.2.0 → make_cloudflare-0.4.0}/src/make_cloudflare/cloudflare.py

@@ -24,15 +24,19 @@ def deploy(
     project: str | None = None,
     branch: Annotated[str, arg(help="the Pages branch; the production one publishes live")] = "main",
     keep: Annotated[int, arg(help="deployments to keep afterwards; 0 keeps every one")] = pages.KEEP,
+    functions: Annotated[str | None, arg(help="a Pages Functions tree to bundle and deploy with it")] = None,
 ) -> None:
     """Publish a built directory to Cloudflare Pages by direct upload.
 
-    No Node and no wrangler: four HTTPS calls. `--branch` is what decides
+    No Node and no wrangler: four HTTPS calls. (`--functions` is the exception:
+    wrangler bundles that tree, and only bundles it.) `--branch` is what decides
     production -- the project's production branch goes live, every other name
     lands as a preview on its own URL. Then the project is pruned to its
     newest `--keep` deployments; the live one always stays.
     """
-    url = pages.deploy(Path(directory), project=pages.project_name(project), branch=branch, keep=keep)
+    url = pages.deploy(
+        Path(directory), project=pages.project_name(project), branch=branch, keep=keep, functions=functions
+    )
     note(f"deployed -- {url}")
 
 

{make_cloudflare-0.2.0 → make_cloudflare-0.4.0}/src/make_cloudflare/pages.py

@@ -8,6 +8,7 @@ a built directory without installing a JavaScript toolchain to do it.
 
     pages.deploy("site/dist", project="mkrun")            # production
     pages.deploy("site/dist", project="mkrun", branch="x")  # a preview
+    pages.deploy("dist", project="name", functions="functions")  # with Pages Functions
 
 The flow, and the three things a naive port gets wrong:
 
@@ -30,6 +31,13 @@ reports success while the site's CSP quietly stops applying.
 **Steps 2 and 3 are undocumented.** They exist because wrangler uses them;
 Cloudflare can change them without a changelog. The documented `deployments`
 endpoint alone cannot upload a file.
+
+**Pages Functions are built by wrangler, and only built.** Bundling a
+`functions/` tree into a Worker is esbuild plus Cloudflare's routing glue, and
+`wrangler pages functions build --outfile` writes exactly the `_worker.bundle`
+the deployment takes. That one build step is the only thing wrangler does here;
+the upload is still these calls. Bindings (D1, KV) and secrets are settings on
+the Pages project, never part of the upload.
 """
 
 from __future__ import annotations
@@ -39,17 +47,21 @@ import json
 import mimetypes
 import os
 import secrets as _random
+import shutil
+import tempfile
 from collections.abc import Iterable, Iterator, Mapping
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from make import env, http, note, step
+from make import env, http, note, sh, step
 from make.context import mark_sensitive
 from make.errors import ConfigError, MakeError
 
 __all__ = [
     "Asset",
+    "build_functions",
+    "configure",
     "collect",
     "deploy",
     "deployments",
@@ -84,9 +96,10 @@ PER_PAGE = 25
 #: Handled by Pages itself, as fields on the deployment -- never as assets.
 SPECIAL_FILES = ("_headers", "_redirects", "_routes.json")
 
-#: Never uploaded. `_worker.js` and `functions/` are Pages Functions, which this
-#: module does not build: a directory that has them is a Functions project and
-#: belongs on wrangler until someone needs it here.
+#: Never uploaded. Pages Functions live *beside* the built directory and are
+#: handed to `deploy(functions=...)`; inside it they would be served as static
+#: files -- the source of the API, readable by anyone. An advanced-mode
+#: `_worker.js` is not built here at all.
 SKIP_NAMES = {".DS_Store", "Thumbs.db", ".gitkeep", *SPECIAL_FILES}
 SKIP_DIRS = {".git", "node_modules", "__pycache__", ".wrangler"}
 FUNCTIONS = ("_worker.js", "_worker.js.map", "_worker.bundle", "functions")
@@ -146,8 +159,9 @@ def collect(directory: str | Path) -> tuple[list[Asset], dict[str, str]]:
     for name in FUNCTIONS:
         if (root / name).exists():
             raise MakeError(
-                f"{root / name} is a Pages Functions project",
-                hint="this module uploads static assets only -- deploy it with wrangler",
+                f"{root / name} is Pages Functions code inside the built directory",
+                hint="keep `functions/` beside the built directory and pass `functions=`; "
+                "an advanced-mode `_worker.js` is not supported",
             )
 
     assets: list[Asset] = []
@@ -260,7 +274,9 @@ def _json_call(method: str, url: str, *, auth: str, payload: object, **kwargs: A
     )
 
 
-def _multipart(fields: Mapping[str, str], files: Mapping[str, str] | None = None) -> tuple[bytes, str]:
+def _multipart(
+    fields: Mapping[str, str], files: Mapping[str, str | bytes] | None = None
+) -> tuple[bytes, str]:
     """Encode a deployment's form: plain fields, then the special files as file parts.
 
     ⚠ `_headers` and `_redirects` must be FILE parts (a `filename=` on the part),
@@ -279,7 +295,7 @@ def _multipart(fields: Mapping[str, str], files: Mapping[str, str] | None = None
         chunks.append(f"--{boundary}\r\n".encode())
         chunks.append(f'Content-Disposition: form-data; name="{name}"; filename="{name}"\r\n'.encode())
         chunks.append(b"Content-Type: application/octet-stream\r\n\r\n")
-        chunks.append(value.encode())
+        chunks.append(value if isinstance(value, bytes) else value.encode())
         chunks.append(b"\r\n")
     chunks.append(f"--{boundary}--\r\n".encode())
     return b"".join(chunks), f"multipart/form-data; boundary={boundary}"
@@ -299,6 +315,55 @@ def _batches(assets: list[Asset]) -> Iterator[list[Asset]]:
         yield batch
 
 
+# -- Pages Functions -------------------------------------------------------
+
+
+def _wrangler() -> list[str]:
+    found = shutil.which("wrangler")
+    return [found] if found else ["npx", "--yes", "wrangler"]
+
+
+def build_functions(functions: str | Path, directory: str | Path, out: str | Path) -> dict[str, bytes]:
+    """Bundle a `functions/` tree; return the deployment's file parts.
+
+    `_worker.bundle` (the Worker, already in the upload form Pages takes),
+    `functions-filepath-routing-config.json`, and `_routes.json` unless the
+    built directory brings its own -- the same three `wrangler pages deploy`
+    sends. Empty under `--dry-run`, where nothing was built.
+    """
+    source = Path(functions).resolve()
+    root = Path(directory).resolve()
+    if not source.is_dir():
+        raise MakeError(f"{source} is not a directory", hint="`functions=` names the Pages Functions tree")
+    out = Path(out)
+    bundle, config, routes = out / "_worker.bundle", out / "routing-config.json", out / "_routes.json"
+    sh(
+        *_wrangler(),
+        "pages",
+        "functions",
+        "build",
+        source,
+        "--outfile",
+        bundle,
+        "--output-config-path",
+        config,
+        "--output-routes-path",
+        routes,
+        "--build-output-directory",
+        root,
+        cwd=source.parent,
+    )
+    if not bundle.is_file():
+        return {}
+    parts = {
+        "_worker.bundle": bundle.read_bytes(),
+        "functions-filepath-routing-config.json": config.read_bytes(),
+    }
+    if not (root / "_routes.json").is_file() and routes.is_file():
+        parts["_routes.json"] = routes.read_bytes()
+    return parts
+
+
 # -- the tasks' behaviour --------------------------------------------------
 
 
@@ -308,6 +373,7 @@ def deploy(
     project: str,
     branch: str = "main",
     keep: int = KEEP,
+    functions: str | Path | None = None,
     account: str | None = None,
     token: str | None = None,
 ) -> str:
@@ -318,11 +384,17 @@ def deploy(
     other name as a preview on its own URL. There is no `--production` flag to
     forget; there is a branch name to get right.
 
+    `functions` names a Pages Functions tree (`functions/`, beside the built
+    directory): it is bundled by `build_functions` and goes up with the
+    deployment, so `/api/...` answers from the same project.
+
     Afterwards the project is pruned to its newest `keep` deployments (see
     `prune`); `keep=0` leaves every one in place.
     """
     account, token = _credentials(account, token)
     assets, specials = collect(directory)
+    with tempfile.TemporaryDirectory(prefix="mk-pages-") as scratch:
+        worker = build_functions(functions, directory, scratch) if functions is not None else {}
     plural = "" if len(assets) == 1 else "s"
     step(f"{len(assets)} file{plural}, {sum(a.size for a in assets) / 1024:.0f} KiB -> {project} ({branch})")
 
@@ -377,7 +449,7 @@ def deploy(
     )
 
     fields = {"manifest": json.dumps(manifest_of(assets)), "branch": branch}
-    body, content_type = _multipart(fields, specials)
+    body, content_type = _multipart(fields, {**specials, **worker})
     created = _call(
         "POST",
         f"{API}/accounts/{account}/pages/projects/{project}/deployments",
@@ -385,8 +457,8 @@ def deploy(
         body=body,
         content_type=content_type,
     )
-    if specials:
-        note("as deployment files, not assets: " + ", ".join(sorted(specials)))
+    if specials or worker:
+        note("as deployment files, not assets: " + ", ".join(sorted({**specials, **worker})))
     url = created.get("url") if isinstance(created, dict) else None
     if keep:
         prune(project, keep=keep, account=account, token=token)
@@ -423,6 +495,53 @@ def create_project(
     return created if isinstance(created, dict) else {"name": project}
 
 
+def configure(
+    project: str,
+    *,
+    d1: Mapping[str, str] | None = None,
+    vars: Mapping[str, str] | None = None,
+    compatibility_date: str | None = None,
+    compatibility_flags: Iterable[str] | None = None,
+    environment: str = "production",
+    account: str | None = None,
+    token: str | None = None,
+) -> dict:
+    """Set what a project's Functions run with; return the project as Cloudflare now has it.
+
+    `d1` maps a binding name to a D1 database id (`{"DB": "<uuid>"}`), `vars` sets plain
+    environment variables, and the compatibility date and flags pick the runtime.
+    `environment` is `production` or `preview`. Only what is passed is sent, and
+    Cloudflare merges it into what the project already has -- nothing unnamed is removed.
+
+    ⚠ Settings take effect on the **next deployment**, never on the live one. Secrets are
+    not set here: a value sent this way is stored in plain text and shown in the dashboard,
+    so a secret goes through `wrangler pages secret put`.
+    """
+    if environment not in ("production", "preview"):
+        raise MakeError(f"no Pages environment {environment!r}", hint="production or preview")
+    settings: dict[str, Any] = {}
+    if d1:
+        settings["d1_databases"] = {name: {"id": ident} for name, ident in d1.items()}
+    if vars:
+        settings["env_vars"] = {name: {"type": "plain_text", "value": value} for name, value in vars.items()}
+    if compatibility_date:
+        settings["compatibility_date"] = compatibility_date
+    if compatibility_flags is not None:
+        settings["compatibility_flags"] = list(compatibility_flags)
+    if not settings:
+        raise MakeError(f"nothing to set on {project}", hint="pass d1=, vars= or a compatibility date")
+
+    account, token = _credentials(account, token)
+    step(f"{project} ({environment}): " + ", ".join(sorted(settings)))
+    result = _json_call(
+        "PATCH",
+        f"{API}/accounts/{account}/pages/projects/{project}",
+        auth=token,
+        payload={"deployment_configs": {environment: settings}},
+    )
+    return result if isinstance(result, dict) else {"name": project}
+
+
 def deployments(project: str, *, account: str | None = None, token: str | None = None) -> list[dict]:
     """A project's deployments, newest first -- every page of them.
 

{make_cloudflare-0.2.0 → make_cloudflare-0.4.0}/tests/test_pages.py

@@ -109,6 +109,13 @@ def test_a_functions_project_is_refused(tmp_path):
         pages.collect(tmp_path)
 
 
+def test_functions_inside_the_built_directory_are_refused(tmp_path):
+    """Served from there, the API's source would be a static file anyone can read."""
+    build(tmp_path, {"index.html": "x", "functions/api/x.ts": "export const onRequest = 1"})
+    with pytest.raises(MakeError, match="inside the built directory"):
+        pages.collect(tmp_path)
+
+
 def test_an_oversized_asset_is_named(tmp_path):
     (tmp_path / "big.bin").write_bytes(b"x" * (pages.MAX_ASSET_SIZE + 1))
     with pytest.raises(MakeError, match=r"big\.bin"):
@@ -360,3 +367,93 @@ def test_deploy_prunes_unless_told_to_keep_everything(monkeypatch, tmp_path):
     calls.clear()
     pages.deploy(tmp_path, project="demo", account="acct", token="tok", keep=0)
     assert deleted(calls) == [] and not any("/deployments?" in url for _, url in calls)
+
+
+# -- Pages Functions -------------------------------------------------------
+
+
+def fake_wrangler(monkeypatch):
+    """Stands in for `wrangler pages functions build`, writing the three outputs."""
+    seen = []
+
+    def run(*argv, cwd=None, **kwargs):
+        argv = [str(a) for a in argv]
+        seen.append(argv)
+        out = {
+            flag: argv[argv.index(flag) + 1]
+            for flag in ("--outfile", "--output-config-path", "--output-routes-path")
+        }
+        pages.Path(out["--outfile"]).write_bytes(b"--bundle--")
+        pages.Path(out["--output-config-path"]).write_text('{"routes": []}')
+        pages.Path(out["--output-routes-path"]).write_text('{"include": ["/api/*"]}')
+
+    monkeypatch.setattr(pages, "sh", run)
+    return seen
+
+
+def test_functions_go_up_as_file_parts_of_the_deployment(monkeypatch, tmp_path):
+    site = build(tmp_path / "dist", {"index.html": "x"})
+    functions = build(tmp_path / "functions", {"api/[[path]].ts": "export const onRequest = 1"})
+    seen = fake_wrangler(monkeypatch)
+    fake = FakeHTTP()
+    deploy(monkeypatch, site, fake, functions=functions)
+
+    assert seen[0][1:4] == ["pages", "functions", "build"] or seen[0][3:6] == ["pages", "functions", "build"]
+    body = fake.body("/deployments").decode()
+    assert 'name="_worker.bundle"; filename="_worker.bundle"' in body and "--bundle--" in body
+    assert 'name="functions-filepath-routing-config.json"; filename=' in body
+    assert 'name="_routes.json"; filename="_routes.json"' in body and "/api/*" in body
+    # The functions are never assets.
+    assert "[[path]]" not in fake.body("/check-missing").decode()
+
+
+def test_the_sites_own_routes_beat_the_generated_ones(monkeypatch, tmp_path):
+    site = build(tmp_path / "dist", {"index.html": "x", "_routes.json": '{"include": ["/mine/*"]}'})
+    functions = build(tmp_path / "functions", {"api/x.ts": "export const onRequest = 1"})
+    fake_wrangler(monkeypatch)
+    fake = FakeHTTP()
+    deploy(monkeypatch, site, fake, functions=functions)
+
+    body = fake.body("/deployments").decode()
+    assert body.count('filename="_routes.json"') == 1
+    assert "/mine/*" in body and "/api/*" not in body
+
+
+def test_a_missing_functions_tree_is_named(monkeypatch, tmp_path):
+    site = build(tmp_path / "dist", {"index.html": "x"})
+    with pytest.raises(MakeError, match="not a directory"):
+        deploy(monkeypatch, site, FakeHTTP(), functions=tmp_path / "nope")
+
+
+# -- project settings --------------------------------------------------------
+
+
+def test_configure_patches_only_what_it_is_given(monkeypatch):
+    fake = FakeHTTP()
+    monkeypatch.setattr(pages.http, "request", fake)
+    pages.configure(
+        "demo",
+        d1={"DB": "uuid-1"},
+        vars={"ZONE": "example.dev"},
+        compatibility_date="2026-10-01",
+        account="acct",
+        token="tok",
+    )
+    method, url, call = fake.calls[0]
+    assert (method, url) == ("PATCH", f"{pages.API}/accounts/acct/pages/projects/demo")
+    assert json.loads(call["data"]) == {
+        "deployment_configs": {
+            "production": {
+                "d1_databases": {"DB": {"id": "uuid-1"}},
+                "env_vars": {"ZONE": {"type": "plain_text", "value": "example.dev"}},
+                "compatibility_date": "2026-10-01",
+            }
+        }
+    }
+
+
+def test_configure_refuses_an_empty_or_unknown_request():
+    with pytest.raises(MakeError, match="nothing to set"):
+        pages.configure("demo", account="acct", token="tok")
+    with pytest.raises(MakeError, match="no Pages environment"):
+        pages.configure("demo", vars={"A": "1"}, environment="staging", account="acct", token="tok")