gitdan-actions/cargo-cache/action.yml

name: 'Cargo cache (consume)'
description: >-
  Per-ref Cargo target-dir cache for Gitea Actions runners: hardlink-clones
  this ref's target directory from its base branch's published, immutable
  snapshot, restores git-history file mtimes, and prunes the volume.
author: 'gitdan'

inputs:
  cache-root:
    description: 'Mount point of the persistent cache volume inside the job container.'
    required: false
    default: '/cache'
  cache-lineage:
    description: >-
      Distinguishes two jobs that build the SAME ref for different targets or
      profiles (a host build and a wasm32 build, say) and would otherwise
      resolve to one CARGO_TARGET_DIR and serialise on Cargo's exclusive
      build-directory lock. Names one directory level under cache-root:
      <cache-root>/<lineage>/target-<key>. Must be a single path component;
      several names are refused outright because a reader elsewhere would stop
      seeing the caches under them (see validate_cache_lineage in
      scripts/cache-lib.sh). Pass the same value to cargo-cache-publish.
    required: false
    default: ''
  protected-branches:
    description: >-
      Space-separated refs that publish snapshots and are never evicted.
      These are the branches PR caches layer over.
    required: false
    default: 'dev main'
  min-free-percent:
    description: 'Prune when free space on the cache volume drops below this percentage.'
    required: false
    default: '10'
  restore-mtimes:
    description: >-
      Restore every tracked file's mtime from git history. Requires a
      full-history checkout (fetch-depth: 0). Set to false only if the build
      does not use Cargo's mtime-based freshness at all.
    required: false
    default: 'true'
  prune:
    description: 'Run the eviction pass (dead-branch liveness + disk pressure).'
    required: false
    default: 'true'
  liveness-prune:
    description: >-
      Within the prune pass, remove caches for branches that no longer exist
      on origin. Set to false on a runner that cannot reach origin.
    required: false
    default: 'true'
  own-ref:
    description: 'Override this run''s ref. Defaults to github.head_ref, else github.ref_name.'
    required: false
    default: ''
  base-ref:
    description: 'Override the ref to layer over. Defaults to github.base_ref (empty on push).'
    required: false
    default: ''
  seed-fallback-dir:
    description: >-
      Absolute path to seed from when no snapshot exists yet — a pre-existing
      flat cache directory during a migration. Optional.
    required: false
    default: ''
  watermark-file:
    description: >-
      Name of this job's build-watermark file inside the target dir. MUST be
      distinct per job when two jobs share one target directory — which two
      jobs no longer need to do; cache-lineage gives them separate ones.
      Defaults to .ci-watermark-<job>-sha, already distinct per job.
    required: false
    default: ''
  lock-id:
    description: 'Identifier for this job''s cache lock. Defaults to <job>-<run_id>.'
    required: false
    default: ''
  stale-lock-seconds:
    description: 'Age past which another job''s cache lock is treated as abandoned.'
    required: false
    default: '7200'

outputs:
  target-dir:
    description: 'Resolved CARGO_TARGET_DIR. Also exported to the job environment.'
    value: ${{ steps.resolve.outputs.target-dir }}
  cache-key:
    description: 'Sanitized cache key for this run''s own ref.'
    value: ${{ steps.resolve.outputs.cache-key }}
  cache-root:
    description: >-
      Resolved cache root — cache-root, plus the lineage directory when one is
      set. Every directory this action reads or writes is under it. Also
      exported as CARGO_CACHE_ROOT.
    value: ${{ steps.resolve.outputs.cache-root }}
  seeded-from:
    description: 'Where the target dir came from: own | base-snapshot | own-snapshot | fallback-dir | concurrent-peer | cold.'
    value: ${{ steps.seed.outputs.seeded-from }}

runs:
  using: 'composite'
  steps:
    # Resolves both cache keys and exports the environment every later step
    # (and the consuming job's own build steps) reads. Must run before
    # anything that touches CARGO_TARGET_DIR, which is why it is first.
    #
    # `head_ref || ref_name` rather than `ref_name` alone: on a pull_request
    # event `ref_name` is a synthetic merge-ref name that changes on every
    # push to the PR, so keying on it would give the same PR a different cache
    # directory every time — defeating the reuse this action exists to
    # provide. On a push event `head_ref` is empty and `ref_name` is the real
    # branch, which is what we want there.
    #
    # `base_ref` is populated only for pull_request events. A push run has
    # nothing to layer over: its own ref IS the reference branch. It
    # publishes, it does not consume.
    #
    # The cache root is resolved first because every path below hangs off it.
    # A lineage nests one directory level (`<root>/<lineage>/target-<key>`),
    # which is what lets two jobs on ONE ref hold two build directories and so
    # not serialise on Cargo's exclusive lock. It is resolved through
    # cache-root.sh rather than interpolated here so the name is validated —
    # several otherwise-reasonable lineage names put their whole subtree out of
    # reach of a pass that has to see it. Everything downstream reads the
    # resolved value, and it is exported as CARGO_CACHE_ROOT so the publish
    # action can check it agrees with its own inputs.
    - id: resolve
      shell: bash
      run: |
        set -euo pipefail
        SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
        [ -d "$SCRIPTS" ] || { echo "::error::cargo-cache: scripts/ not found at $SCRIPTS"; exit 1; }
        echo "CARGO_CACHE_SCRIPTS=${SCRIPTS}" >> "$GITHUB_ENV"
        CACHE_ROOT=$(bash "${SCRIPTS}/cache-root.sh" resolve \
          "${{ inputs.cache-root }}" "${{ inputs.cache-lineage }}")
        OWN_REF="${{ inputs.own-ref }}"
        [ -n "$OWN_REF" ] || OWN_REF="${{ github.head_ref || github.ref_name }}"
        BASE_REF="${{ inputs.base-ref }}"
        [ -n "$BASE_REF" ] || BASE_REF="${{ github.base_ref }}"

        OWN_KEY=$(bash "${SCRIPTS}/branch-cache-key.sh" "$OWN_REF")
        BASE_KEY=""
        if [ -n "$BASE_REF" ]; then
          BASE_KEY=$(bash "${SCRIPTS}/branch-cache-key.sh" "$BASE_REF")
          echo "cache: own ref '${OWN_REF}' -> ${OWN_KEY}; layering over base ref '${BASE_REF}' -> ${BASE_KEY}"
        else
          echo "cache: own ref '${OWN_REF}' -> ${OWN_KEY} (no base ref — this ref publishes, it does not consume)"
        fi

        TARGET_DIR="${CACHE_ROOT}/target-${OWN_KEY}"
        WATERMARK="${{ inputs.watermark-file }}"
        [ -n "$WATERMARK" ] || WATERMARK=".ci-watermark-${{ github.job }}-sha"
        LOCK_ID="${{ inputs.lock-id }}"
        [ -n "$LOCK_ID" ] || LOCK_ID="${{ github.job }}-${{ github.run_id }}"

        {
          echo "target-dir=${TARGET_DIR}"
          echo "cache-key=${OWN_KEY}"
          echo "base-key=${BASE_KEY}"
          echo "lock-id=${LOCK_ID}"
          echo "watermark-file=${WATERMARK}"
          echo "cache-root=${CACHE_ROOT}"
        } >> "$GITHUB_OUTPUT"
        {
          echo "CARGO_TARGET_DIR=${TARGET_DIR}"
          echo "CARGO_CACHE_ROOT=${CACHE_ROOT}"
          echo "CARGO_CACHE_KEY=${OWN_KEY}"
          echo "CARGO_CACHE_LOCK_ID=${LOCK_ID}"
          echo "CI_WATERMARK_FILE=${WATERMARK}"
        } >> "$GITHUB_ENV"

    # Seeds this ref's target dir from the base's published snapshot. See
    # scripts/seed-target-dir.sh — the staging-then-atomic-rename is what
    # makes concurrent jobs sharing one cache key safe by construction rather
    # than by the runner happening to have a single execution slot, and the
    # clone's own consistency check plus the publish side's reader interlock
    # are what make it safe against the base republishing MID-CLONE.
    #
    # The lock id is passed here as well as acquired in the next step: the
    # seed writes it into the staging tree, so the directory carries a lock
    # the instant it appears under its final name rather than a step later.
    - id: seed
      shell: bash
      run: |
        set -euo pipefail
        SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
        bash "${SCRIPTS}/seed-target-dir.sh" \
          "${{ steps.resolve.outputs.cache-key }}" \
          "${{ steps.resolve.outputs.base-key }}" \
          "${{ steps.resolve.outputs.cache-root }}" \
          "${{ github.job }}-${{ github.run_id }}-$$" \
          "${{ inputs.seed-fallback-dir }}" \
          "${{ steps.resolve.outputs.lock-id }}"

    # Re-stamps the lock the seed step already wrote (acquiring is idempotent
    # — it rewrites the timestamp) and stamps the LRU marker. The marker is
    # touched unconditionally every run: a run that hits the cache for every
    # crate may write nothing at all inside the tree, which would make a
    # just-used directory look stale to the eviction pass.
    #
    # `.cache-last-used` IS A CROSS-REPO CONTRACT NAME with daniel/gitdan's
    # `scripts/ci-cache-reclaim.sh`, which reads this exact marker for its own
    # LRU ordering and to recognise a directory as a cache dir at all. Rename
    # it here without a matching change there and that script silently falls
    # back to directory mtime for both — see README.md's "Scratch names in a
    # cache root" section and the `DEPENDED-UPON NAMES CONTRACT` block in
    # gitdan's script.
    - shell: bash
      run: |
        set -euo pipefail
        SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
        bash "${SCRIPTS}/cache-lock.sh" acquire \
          "${{ steps.resolve.outputs.target-dir }}" "${{ steps.resolve.outputs.lock-id }}"
        touch "${{ steps.resolve.outputs.target-dir }}/.cache-last-used"

    # Runs AFTER seeding, deliberately: restore-mtimes.sh reads the build
    # watermark out of the target dir, so that directory has to be in its
    # final form for this run (reused, seeded, or freshly created) before the
    # watermark it may carry can be read.
    # CARGO_TARGET_DIR and CI_WATERMARK_FILE are passed explicitly rather
    # than read from the job environment the resolve step exported: the export
    # is what the consuming workflow's own build steps rely on, but a step
    # inside this action should not depend on cross-step propagation working
    # when it can just be handed the value.
    - if: ${{ inputs.restore-mtimes == 'true' }}
      shell: bash
      env:
        CARGO_TARGET_DIR: ${{ steps.resolve.outputs.target-dir }}
        CI_WATERMARK_FILE: ${{ steps.resolve.outputs.watermark-file }}
      run: bash "$(cd "${{ github.action_path }}/.." && pwd)/scripts/restore-mtimes.sh"

    - if: ${{ inputs.prune == 'true' }}
      shell: bash
      env:
        STALE_LOCK_SECONDS: ${{ inputs.stale-lock-seconds }}
        CACHE_LIVENESS: ${{ inputs.liveness-prune }}
      run: |
        set -euo pipefail
        SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
        bash "${SCRIPTS}/prune-cache.sh" \
          "${{ steps.resolve.outputs.cache-root }}" \
          "${{ steps.resolve.outputs.target-dir }}" \
          "${{ inputs.protected-branches }}" \
          "${{ inputs.min-free-percent }}"