Skip to content

mesh.build_cache.provision

The host layer of a cache provider as one declared policy: a disk guard on a timer, services that restart always and are last for the OOM killer, a bounded journal and container log, a private bucket with expiry and a hard quota beside the CI cache's own bound, one least-privilege identity per node whose credential is generated on the host into a mode 0600 file outside any repository, and the rustc wrapper that makes the node's own builds use the cache. Without `apply` it plans only: every file, edit and command still owed, from what the host holds, with no secret named. With `apply` it writes what is missing or drifted and runs the commands, as root, refusing without it before touching anything; a second apply changes nothing. A `root` other than `/` is a staging directory: files only, no privilege, no command. Offered on the command line only: it installs services and writes credentials, which nothing reachable over HTTP or MCP may do.

The host layer of a cache provider as one declared policy: a disk guard on a timer, services that restart always and are last for the OOM killer, a bounded journal and container log, a private bucket with expiry and a hard quota beside the CI cache's own bound, one least-privilege identity per node whose credential is generated on the host into a mode 0600 file outside any repository, and the rustc wrapper that makes the node's own builds use the cache. Without `apply` it plans only: every file, edit and command still owed, from what the host holds, with no secret named. With `apply` it writes what is missing or drifted and runs the commands, as root, refusing without it before touching anything; a second apply changes nothing. A `root` other than `/` is a staging directory: files only, no privilege, no command. Offered on the command line only: it installs services and writes credentials, which nothing reachable over HTTP or MCP may do.

  • command
  • experimental
  • module mesh
  • #mesh
  • #build-cache
  • #provisioning

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surfaceas
MCP—
HTTP—
command linemajordomus mesh build-cache provision

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · ProvisionInput

The input of mesh.build_cache.provision.
propertytyperequireddescription
apply boolean no Carry the plan out. Absent, the capability only plans and changes nothing. Under the default root / it needs root and refuses without it. default false
root string | null no The directory the host's paths are read from and written under; default /. Any other root is a staging directory: files only, no privilege, no command.
JSON Schema 
{
  "additionalProperties": false,
  "description": "The input of `mesh.build_cache.provision`.",
  "properties": {
    "apply": {
      "default": false,
      "description": "Carry the plan out. Absent, the capability only plans and changes nothing. Under the\ndefault root `/` it needs root and refuses without it.",
      "type": "boolean"
    },
    "root": {
      "description": "The directory the host's paths are read from and written under; default `/`. Any other\nroot is a staging directory: files only, no privilege, no command.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "ProvisionInput",
  "type": "object"
}

output · ProvisionReport

The answer: the plan against the host as observed, and the apply's report when asked.
propertytyperequireddescription
apply one of 2 no What the apply did; absent for a plan.
mode string yes plan or apply.
ok boolean yes A plan always holds; an apply holds when nothing failed and nothing is owed after it.
plan reference yes What the host owed when asked.
policy reference yes The policy in force: declared, not a secret.
root string yes The root read.
JSON Schema 
{
  "$defs": {
    "ApplyReport": {
      "description": "What an apply did.",
      "properties": {
        "after": {
          "anyOf": [
            {
              "$ref": "#/$defs/Plan"
            },
            {
              "type": "null"
            }
          ],
          "description": "The plan after the apply: `changes` is 0 when the host now holds the policy."
        },
        "generated": {
          "description": "Paths of credentials this run generated.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "ok": {
          "description": "Nothing failed and nothing was refused.",
          "type": "boolean"
        },
        "ran": {
          "description": "The command lines that ran, each with its outcome.",
          "items": {
            "$ref": "#/$defs/Ran"
          },
          "type": "array"
        },
        "refused": {
          "description": "Why nothing was done, when it was refused.",
          "type": [
            "string",
            "null"
          ]
        },
        "root": {
          "description": "The root the files were written under.",
          "type": "string"
        },
        "skipped": {
          "description": "Commands that did not run, and why.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "written": {
          "description": "Paths written or corrected, never their content.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "ok",
        "root",
        "written",
        "generated",
        "ran",
        "skipped"
      ],
      "type": "object"
    },
    "EditAction": {
      "description": "A line edit the plan owes: the cargo config of the build user.",
      "properties": {
        "from": {
          "description": "The line replaced.",
          "type": "string"
        },
        "owed": {
          "description": "The edit is still owed.",
          "type": "boolean"
        },
        "path": {
          "description": "The file edited.",
          "type": "string"
        },
        "to": {
          "description": "The line it becomes.",
          "type": "string"
        }
      },
      "required": [
        "path",
        "from",
        "to",
        "owed"
      ],
      "type": "object"
    },
    "FileAction": {
      "description": "One file of the plan.",
      "properties": {
        "mode": {
          "description": "The mode it must have, in octal.",
          "type": "string"
        },
        "owner": {
          "description": "The owner it must have, when not root.",
          "type": [
            "string",
            "null"
          ]
        },
        "path": {
          "description": "The path on the host.",
          "type": "string"
        },
        "source": {
          "description": "Where its content comes from: `declared`, `generated` or `copy:<path>`. Never the content.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/FileState",
          "description": "Where it stands."
        }
      },
      "required": [
        "path",
        "mode",
        "source",
        "state"
      ],
      "type": "object"
    },
    "FileState": {
      "description": "Where a file stands against what the policy wants.",
      "oneOf": [
        {
          "const": "missing",
          "description": "Absent.",
          "type": "string"
        },
        {
          "const": "different",
          "description": "Present with other content.",
          "type": "string"
        },
        {
          "const": "mode",
          "description": "Right content, wrong mode.",
          "type": "string"
        },
        {
          "const": "current",
          "description": "As wanted.",
          "type": "string"
        },
        {
          "const": "unobservable",
          "description": "Could not be observed by this process; apply as root decides.",
          "type": "string"
        }
      ]
    },
    "Plan": {
      "description": "The plan: every file, edit and command the host still owes.",
      "properties": {
        "changes": {
          "description": "How many files are missing, different or of the wrong mode, plus edits owed.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "edits": {
          "description": "The line edits.",
          "items": {
            "$ref": "#/$defs/EditAction"
          },
          "type": "array"
        },
        "files": {
          "description": "Every file the policy owns.",
          "items": {
            "$ref": "#/$defs/FileAction"
          },
          "type": "array"
        },
        "steps": {
          "description": "The commands, in the order they run.",
          "items": {
            "$ref": "#/$defs/Step"
          },
          "type": "array"
        },
        "unobservable": {
          "description": "How many files this process could not observe.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "files",
        "edits",
        "steps",
        "changes",
        "unobservable"
      ],
      "type": "object"
    },
    "Policy": {
      "additionalProperties": false,
      "description": "What the provisioning declares: who runs the builds, which store, how bounded, which\nnodes receive an identity.",
      "properties": {
        "alias": {
          "description": "The `mc` alias of the store.",
          "type": "string"
        },
        "bucket": {
          "description": "The cache bucket.",
          "type": "string"
        },
        "bucket_quota_gib": {
          "description": "The cache bucket's hard quota, in GiB.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "critical_services": {
          "description": "The services that restart always and are the last the OOM killer takes.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "expire_days": {
          "description": "Days after which an entry expires.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "gitlab_bucket": {
          "description": "The CI cache bucket this host already serves, bounded the same way.",
          "type": "string"
        },
        "gitlab_quota_gib": {
          "description": "Its quota, in GiB.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "home": {
          "description": "That user's home directory.",
          "type": "string"
        },
        "local_node": {
          "description": "The node this host is: its builds use the loopback endpoint.",
          "type": "string"
        },
        "nodes": {
          "description": "Every node that receives an identity.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "policy_name": {
          "description": "The name of the least-privilege policy every node identity carries.",
          "type": "string"
        },
        "port": {
          "description": "The store's port.",
          "format": "uint16",
          "maximum": 65535,
          "minimum": 0,
          "type": "integer"
        },
        "region": {
          "description": "The region sccache signs for.",
          "type": "string"
        },
        "tailnet_address": {
          "description": "The address other nodes reach the store at.",
          "type": "string"
        },
        "user": {
          "description": "The user whose builds use the cache on this host.",
          "type": "string"
        }
      },
      "required": [
        "user",
        "home",
        "alias",
        "tailnet_address",
        "port",
        "bucket",
        "region",
        "expire_days",
        "bucket_quota_gib",
        "gitlab_bucket",
        "gitlab_quota_gib",
        "policy_name",
        "local_node",
        "nodes",
        "critical_services"
      ],
      "type": "object"
    },
    "Ran": {
      "description": "One command that ran.",
      "properties": {
        "line": {
          "description": "The line, with a secret as a placeholder.",
          "type": "string"
        },
        "ok": {
          "description": "It exited zero.",
          "type": "boolean"
        },
        "output": {
          "description": "Its output when it failed (a secret removed).",
          "type": "string"
        }
      },
      "required": [
        "line",
        "ok",
        "output"
      ],
      "type": "object"
    },
    "Step": {
      "description": "A command the apply runs once the files are in place, as root.",
      "properties": {
        "id": {
          "description": "A stable name.",
          "type": "string"
        },
        "line": {
          "description": "The command as it is run; a node's secret appears only as `<secret of NODE>`.",
          "type": "string"
        },
        "when": {
          "description": "Run only when a file of the named group changed (`systemd`, `journald`, `docker`), or always.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "line",
        "when"
      ],
      "type": "object"
    }
  },
  "description": "The answer: the plan against the host as observed, and the apply's report when asked.",
  "properties": {
    "apply": {
      "anyOf": [
        {
          "$ref": "#/$defs/ApplyReport"
        },
        {
          "type": "null"
        }
      ],
      "description": "What the apply did; absent for a plan."
    },
    "mode": {
      "description": "`plan` or `apply`.",
      "type": "string"
    },
    "ok": {
      "description": "A plan always holds; an apply holds when nothing failed and nothing is owed after it.",
      "type": "boolean"
    },
    "plan": {
      "$ref": "#/$defs/Plan",
      "description": "What the host owed when asked."
    },
    "policy": {
      "$ref": "#/$defs/Policy",
      "description": "The policy in force: declared, not a secret."
    },
    "root": {
      "description": "The root read.",
      "type": "string"
    }
  },
  "required": [
    "mode",
    "root",
    "policy",
    "plan",
    "ok"
  ],
  "title": "ProvisionReport",
  "type": "object"
}

Policies

benchmark
waived — waived: destructive
cache
disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transportstatecasestargets
directwaived (destructive)0

Searches the titles and descriptions of every page this site publishes.