nandi/frq · _loader.py

nandi/frqpublic⑂ Fork 0
⑂ claude/ci-image-modal-deploy-f0f1d9
_loader.py · 439 lines · 19.7 KBPython    Blame HistoryRaw
Build the window somewhere with room for it   1"""Turn a `container.toml` into a `modal.Image` and a `modal.App`.
Carry the loader's .git fix over   3Every container -- under `containers/` here, `.modal/` in a repo that merely
4builds itself on Modal -- is a directory with a `container.toml` and
Six verbs, and the last of the nix   5a stub `container.py`. The keys are documented by the comments below, which
6is the whole of the spec. Nothing here is Modal-specific configuration in its
7own right -- each
Build the window somewhere with room for it   8spec key maps onto a documented Modal argument, and the mapping is meant to
9stay boring enough to read straight through.
12
13import subprocess
14import tomllib
16import modal
19class SpecError(Exception):
  """The container.toml says something that cannot be built."""
23def _running_in_modal() -> bool:
  """True inside a Modal container, false on the machine that launched it."""
  return bool(os.environ.get("MODAL_TASK_ID"))
28class Container:
  """One container: its spec, its image, its app, and how to run it."""
  def __init__(self, spec: dict, directory: str):
      self.is_remote = _running_in_modal()
      self.dir = directory
      self.spec = spec
      self.name = self._require("container", "name")
      self.description = spec.get("container", {}).get("description", "")
      run = spec.get("run", {})
      self.workdir = run.get("workdir", "/app")
      self.command = run.get("command", "")
      self.env = dict(run.get("env", {}))
CI builds the image, Modal serves it   43        # "function" (the default), "sandbox" or "web". Sandboxes can run on
      # a real VM, which Functions cannot -- see ../README.md. A "web"
      # container is a Function that serves [network] ports at a URL and
      # stays deployed, rather than a run that ends.
Build the window somewhere with room for it   47        self.runtime = spec.get("container", {}).get("runtime", "function")
      # name -> mount path. Modal Volumes, mounted while the container runs
      # and NOT while its image is built: a volume mount is not part of the
      # resulting image, so anything written to one during a build step is
      # gone by the time the container starts. Persist across runs is the
Six verbs, and the last of the nix   53        # whole point -- a toolchain too big to fetch every run, a build
      # tree an incremental compile reuses, a dataset too big to bake in.
Build the window somewhere with room for it   55        self.volume_spec = dict(spec.get("volumes", {}))
A third target, and the seam that was already waiting for it   57        # Ports to tunnel out of a Sandbox, from [network] ports. Encrypted,
      # which is Modal's own word for "the tunnel terminates TLS and speaks
      # plain HTTP to your process" -- so the thing listening inside is an
      # ordinary http.server and not something holding a certificate.
CI builds the image, Modal serves it   62        # Not for a plain Function: it has no long-lived process to tunnel
      # into, and `modal run` on one would hand back a URL for a container
      # that has already exited. A "web" container has exactly one, and
      # Modal fronts it with a stable https:// URL instead of a tunnel.
A third target, and the seam that was already waiting for it   66        self.ports = [int(p) for p in spec.get("network", {}).get("ports", [])]
Build the window somewhere with room for it   68        # Modal re-imports this module inside the container, so everything
      # below runs twice: once here, once out there. Out there the local
Six verbs, and the last of the nix   70        # tree does not exist -- no repo to copy from -- and
Build the window somewhere with room for it   71        # the image is already built, so validating and rebuilding it would
      # only fail. The App still has to exist for the decorators to bind.
      if self.is_remote:
          self.image = None
          self.app = modal.App(self.name)
      else:
          self._validate()
          self.image = self._build_image()
          self.app = modal.App(self.name, image=self.image)
  # -- spec reading ----------------------------------------------------
  @classmethod
  def from_toml(cls, container_py: str) -> "Container":
      """Load the container.toml sitting next to the given container.py."""
      directory = os.path.dirname(os.path.abspath(container_py))
      path = os.path.join(directory, "container.toml")
      if not os.path.exists(path):
          raise SpecError(f"no container.toml in {directory}")
      with open(path, "rb") as f:
          return cls(tomllib.load(f), directory)
  def _require(self, table: str, key: str):
      try:
          return self.spec[table][key]
      except KeyError:
          raise SpecError(f"container.toml needs [{table}] {key}") from None
  def _validate(self):
      c = self.spec.get("container", {})
CI builds the image, Modal serves it   101        if self.runtime not in ("function", "sandbox", "web"):
Build the window somewhere with room for it   102            raise SpecError(
CI builds the image, Modal serves it   103                f'[container] runtime must be "function", "sandbox" or "web",'
Build the window somewhere with room for it   104                f" not {self.runtime!r}"
      if bool(c.get("base")) == bool(c.get("registry")):
          raise SpecError("set exactly one of [container] base or registry")
CI builds the image, Modal serves it   108        if self.ports and self.runtime == "function":
A third target, and the seam that was already waiting for it   109            raise SpecError(
CI builds the image, Modal serves it   110                "[network] ports needs [container] runtime = \"sandbox\""
              " or \"web\" -- a Function has no process to tunnel into"
      if self.runtime == "web" and len(self.ports) != 1:
          raise SpecError(
              "[container] runtime = \"web\" needs exactly one"
              " [network] ports entry -- a URL fronts one listener"
A third target, and the seam that was already waiting for it   117
Build the window somewhere with room for it   118        for name, mount in self.volume_spec.items():
          if not isinstance(mount, str) or not mount.startswith("/"):
              raise SpecError(
                  f"[volumes] {name} must be an absolute path, not {mount!r}"
          # Mounting over one of these hides what the image already has
Six verbs, and the last of the nix   124            # there: an empty volume would shadow what the image's own build
          # put in its place.
          if mount.rstrip("/") in ("", "/usr", "/etc", "/bin", "/lib"):
Build the window somewhere with room for it   127                raise SpecError(
                  f"[volumes] {name} may not mount over {mount} --"
                  " it would hide what the image has there"
          if mount.rstrip("/") == self.workdir.rstrip("/"):
              raise SpecError(
                  f"[volumes] {name} may not mount over the workdir"
                  f" ({mount}) -- [build] include copies land there"
  # -- image -----------------------------------------------------------
  def _build_image(self) -> modal.Image:
      c = self.spec["container"]
      build = self.spec.get("build", {})
      if c.get("base"):
          image = modal.Image.from_name(c["base"])
      else:
CI builds the image, Modal serves it   146            # `${VAR}` in a registry reference is expanded here, so a tag that
          # CI computes -- a commit sha -- can be passed in rather than
          # committed. A private registry needs credentials, and Modal wants
          # them as a Secret holding REGISTRY_USERNAME / REGISTRY_PASSWORD:
          # name it with [container] registry_secret.
          ref = os.path.expandvars(c["registry"])
          if "$" in ref:
              raise SpecError(
                  f"[container] registry has an unset variable: {ref}"
          if secret := c.get("registry_secret"):
              image = modal.Image.from_registry(
                  ref, secret=modal.Secret.from_name(secret)
          else:
              image = modal.Image.from_registry(ref)
Build the window somewhere with room for it   162
      # copy=True throughout: later run_commands need these files present.
      # `context` is what include paths are relative to, and it may sit above
      # the container directory -- a container that builds the repo it lives
      # in sets context = "../..", so include = ["."] means the whole repo.
      context = os.path.normpath(os.path.join(self.dir, build.get("context", ".")))
A third target, and the seam that was already waiting for it   168
      # Image building and program building, kept apart.
Six verbs, and the last of the nix   171        # `[build] commands` run AFTER the source copy, so any edit anywhere
      # in the tree invalidates them. `warm` + `setup` are the same step
      # moved in front of the source: `warm` names only the files the step
      # actually reads, and `setup` runs against those alone, so editing
      # `flutter/src` invalidates nothing above the final copy. A container
      # whose setup is an `apt-get` needs no `warm` at all -- it reads
      # nothing out of the tree, so nothing in the tree can invalidate it.
A third target, and the seam that was already waiting for it   178        for rel in build.get("warm", []):
          src = os.path.normpath(os.path.join(context, rel))
          dest = f"{self.workdir}/{rel}"
          if os.path.isdir(src):
              image = image.add_local_dir(src, dest, copy=True)
          else:
              image = image.add_local_file(src, dest, copy=True)
      if setup := build.get("setup", []):
          image = image.run_commands(*setup, volumes=self.volumes)
Stop shipping the build tree, and let a shell be the devShell   187        # `ignore` is what keeps a build tree out of the image. A checkout that
      # has been built in locally carries its output -- flutter/build and the
      # caches beside it were 395MB of a 441MB repo -- and all of it would be
      # uploaded on every start only to be thrown away, since the container
      # builds into a volume of its own. Patterns are relative to the copied
      # directory, as in .dockerignore.
      ignore = list(build.get("ignore", []))
CI builds the image, Modal serves it   194        includes = build.get("include", ["."])
      for rel in includes:
Build the window somewhere with room for it   196            src = os.path.normpath(os.path.join(context, rel))
          dest = self.workdir if rel == "." else f"{self.workdir}/{rel}"
          if os.path.isdir(src):
Stop shipping the build tree, and let a shell be the devShell   199                image = image.add_local_dir(src, dest, copy=True, ignore=ignore)
Build the window somewhere with room for it   200            else:
              image = image.add_local_file(src, dest, copy=True)
Six verbs, and the last of the nix   203        # A repo copied in brings its `.git` along, and in a worktree that is
      # a *file* holding `gitdir: <path on the machine that copied it>` --
      # which points at nothing out here, so any tool that follows it fails
      # in a way that has nothing to do with what it was asked to do.
      # Nothing in a container wants the git metadata, so it goes.
CI builds the image, Modal serves it   208        # ...but only if a copy happened. `include = []` is how a container
      # built elsewhere -- by CI, into a registry -- says the image is
      # already what it should be, and adding a layer to it would rebuild
      # and re-push something nobody asked to change.
      if includes:
          image = image.run_commands(f"rm -rf {self.workdir}/.git")
Carry the loader's .git fix over   214
Build the window somewhere with room for it   215        if commands := build.get("commands", []):
Six verbs, and the last of the nix   216            # Volumes mounted for the build too, not just the run, so a step
          # can read a cache the last run filled. The mount is not part of
          # the resulting image; only what the step writes outside it is.
A shell that is already the devShell, and two recipes to reach it   219            image = image.run_commands(*commands, volumes=self.volumes)
Build the window somewhere with room for it   220
      # container.py does `from _loader import Container`, and Modal mounts
      # the entrypoint file alone -- so without this the import that works
      # locally fails in the container. copy=False adds it at startup rather
      # than baking a layer, so it invalidates nothing above it, and it must
      # therefore come after every build step.
      image = image.add_local_python_source("_loader")
      # ...and container.py reads its spec at import time, so the spec has to
      # be there too. Modal re-imports the entrypoint at /root, which is the
      # one directory that gets none of the workdir copies above.
      image = image.add_local_file(
          os.path.join(self.dir, "container.toml"), "/root/container.toml"
      return image
  # -- volumes ---------------------------------------------------------
  @property
  def volumes(self) -> dict:
      """{mount path: Volume}, as both Sandbox.create and @app.function want.
      `from_name` is lazy, so this is safe to evaluate on the re-import
      inside the container as well as out here. create_if_missing means a
      spec naming a volume that does not exist yet makes it rather than
      failing -- the first run of a cache is the one that fills it.
      """
      return {
          mount: modal.Volume.from_name(name, create_if_missing=True)
          for name, mount in self.volume_spec.items()
  # -- function --------------------------------------------------------
  @property
  def function_kwargs(self) -> dict:
      """Everything `@app.function` should be given, from [resources]."""
      r = self.spec.get("resources", {})
      kwargs: dict = {"timeout": int(r.get("timeout", 900))}
      if r.get("cpu"):
          kwargs["cpu"] = float(r["cpu"])
      if r.get("memory"):
          kwargs["memory"] = int(r["memory"])
      if r.get("gpu"):
          kwargs["gpu"] = r["gpu"]
CI builds the image, Modal serves it   265        # Containers kept warm. Zero -- the default -- means a served URL
      # pays a cold start on the first request after it goes quiet, which
      # for a static bundle is a second or two.
      if r.get("min_containers"):
          kwargs["min_containers"] = int(r["min_containers"])
Build the window somewhere with room for it   270        # Deliberately NOT self.experimental_options: that fills in the
      # sandbox default, and vm_runtime on a Function is refused by the
      # server. A sandbox container's @app.function is vestigial anyway.
CI builds the image, Modal serves it   273        if self.runtime != "sandbox":
Build the window somewhere with room for it   274            if experimental := dict(self.spec.get("experimental", {})):
              kwargs["experimental_options"] = experimental
      if volumes := self.volumes:
          kwargs["volumes"] = volumes
      return kwargs
  @property
  def experimental_options(self) -> dict:
      """Experimental options, with the sandbox default filled in.
      `vm_runtime` is Sandbox-only: the server rejects it on a Function
      outright. So it is defaulted on for sandboxes and never for functions,
      and an explicit [experimental] table always wins.
      """
      explicit = dict(self.spec.get("experimental", {}))
      if explicit:
          return explicit
      if self.runtime == "sandbox":
          return {"vm_runtime": True}
      return {}
  @property
  def sandbox_kwargs(self) -> dict:
      """Everything `Sandbox.create` should be given, from [resources]."""
      r = self.spec.get("resources", {})
      kwargs: dict = {"timeout": int(r.get("timeout", 900))}
      if r.get("cpu"):
          kwargs["cpu"] = float(r["cpu"])
      if r.get("memory"):
          # A VM sandbox gets exactly this much and cannot grow into more.
          kwargs["memory"] = int(r["memory"])
      if opts := self.experimental_options:
          kwargs["experimental_options"] = dict(opts)
      if volumes := self.volumes:
          kwargs["volumes"] = volumes
A third target, and the seam that was already waiting for it   309        if self.ports:
          kwargs["encrypted_ports"] = list(self.ports)
Build the window somewhere with room for it   311        return kwargs
  def shell_command(self, override: str = "") -> str:
Six verbs, and the last of the nix   314        """The full shell line the container runs."""
Build the window somewhere with room for it   315        command = override or self.command
      if not command:
          raise SpecError("container.toml has no [run] command")
      return f"cd {self.workdir} && {command}"
CI builds the image, Modal serves it   320    # -- web -------------------------------------------------------------
  def register_web(self):
      """Serve the [run] command's process at a URL, for `modal deploy`.
      A web container's command is a server, not a build: it listens on the
      one [network] port and Modal fronts it with https. `web_server` waits
      for that port to accept a connection and then proxies to it, so the
      command has to keep running -- Popen and return, rather than the
      `subprocess.run` that `execute` uses for a job that ends.
      Registered by calling this at import time, which happens twice: once
      here, to define the Function, and once inside the container, where
      `self.image` is None and the App has no image of its own.
      """
      kwargs = dict(self.function_kwargs)
      if self.image is not None:
          kwargs["image"] = self.image
      line = self.shell_command()
      env = {k: str(v) for k, v in self.env.items()}
      port = self.ports[0]
      # One container answering many requests. A static bundle costs
      # nothing per request, so scaling out on concurrency would only buy
      # cold starts.
      # serialized=True because this body is defined in here rather than at
      # a module's top level: Modal pickles it instead of importing it by
      # name, which is also why a web container needs nothing of its own
      # beyond the stub that calls this.
      @self.app.function(name="serve", serialized=True, **kwargs)
      @modal.concurrent(max_inputs=100)
      @modal.web_server(port=port, startup_timeout=self.startup_timeout)
      def serve():
          subprocess.Popen(line, shell=True, env={**os.environ, **env})
      return serve
  @property
  def startup_timeout(self) -> int:
      """How long Modal waits for the port to answer, from [network]."""
      return int(self.spec.get("network", {}).get("startup_timeout", 60))
Build the window somewhere with room for it   363    def run_sandbox(self, override: str = "") -> str:
      """Run one command in a Sandbox that dies when the command does.
      The command IS the sandbox's process, rather than something exec'd
      into a `sleep infinity` box that then has to be torn down. There is no
      idle window to pay for and nothing to leak if this script is killed;
      the [resources] timeout is a backstop, not the mechanism.
      Modal streams a Sandbox's output into the app log as it runs -- which
      is what you want for a build -- so this returns "" rather than handing
      back a copy for the caller to print underneath it.
      """
      line = self.shell_command(override)
      sb = modal.Sandbox.create(
          "sh", "-c", line,
          app=self.app,
          image=self.image,
          workdir=self.workdir,
          env={k: str(v) for k, v in self.env.items()},
          **self.sandbox_kwargs,
A third target, and the seam that was already waiting for it   384        self._print_tunnels(sb)
Build the window somewhere with room for it   385        sb.wait()
      if sb.returncode != 0:
          raise RuntimeError(
              f"{self.name}: command failed ({sb.returncode})\n"
              f"$ {line}\n{sb.stderr.read()}"
      return ""
A third target, and the seam that was already waiting for it   393    def _print_tunnels(self, sb: "modal.Sandbox") -> None:
      """Say where a tunnelled port can be reached, once the sandbox is up.
      `tunnels()` blocks until the Sandbox is scheduled, which is why this
      is called after create and not folded into it. Nothing prints when
      [network] ports is empty, which is every container but the serving
      ones.
      """
      if not self.ports:
          return
      for port, tunnel in sb.tunnels().items():
          print(f"  :{port} -> {tunnel.url}")
Build the window somewhere with room for it   406    def open_sandbox(self) -> "modal.Sandbox":
Stop shipping the build tree, and let a shell be the devShell   407        """Start a Sandbox and leave it running, for `scripts/shell`.
      Same workdir and the same [run] env as the real thing: a shell opened
      to debug a container that does not have the container's environment is
      a shell that reproduces something else. `command` is the one part left
      out, because not running it is the point.
      """
Build the window somewhere with room for it   414        return modal.Sandbox.create(
          "sleep",
          "infinity",
          app=self.app,
          image=self.image,
Stop shipping the build tree, and let a shell be the devShell   419            workdir=self.workdir,
          env={k: str(v) for k, v in self.env.items()},
Build the window somewhere with room for it   421            **self.sandbox_kwargs,
  def execute(self, override: str = "") -> str:
      """Run the command in this container. Called remotely, not locally."""
      line = self.shell_command(override)
      result = subprocess.run(
          line,
          shell=True,
          capture_output=True,
          text=True,
          env={**os.environ, **{k: str(v) for k, v in self.env.items()}},
      if result.returncode != 0:
          raise RuntimeError(
              f"{self.name}: command failed ({result.returncode})\n"
              f"$ {line}\n{result.stderr}"
      return result.stdout