# Cache de dependências (Fast Cache)

> O Latchkey Fast Cache salva e restaura caches de dependências em uma única requisição de streaming, com armazenamento na mesma região do seu runner e configuração zero.

Source: https://latchkey.dev/pt/documentation/dependency-caching

## Summary

- Troque `actions/cache` por `latchkey-dev/cache-action@v1`; suas entradas `path`, `key` e `restore-keys` existentes continuam funcionando.
- Uma requisição de streaming por save ou restore, compressão zstd multi-thread, armazenamento na região do runner.
- Configuração zero: armazenamento e credenciais já vêm provisionados em cada runner Latchkey.
- Um problema de cache pode deixar um build mais lento, mas nunca o faz falhar; falhas de restore geram um aviso e continuam.

O Latchkey Fast Cache (`latchkey-dev/cache-action@v1`) é uma GitHub Action leve para salvar e restaurar caches de dependências (node_modules, registros de pacotes, artefatos de build) em runners gerenciados Latchkey. Runs repetidos pulam instalações que seu pipeline já fez.

## Por que é rápido

- Os dados do cache trafegam em uma **única requisição HTTP de streaming** em vez do padrão serial de chunks que o `actions/cache@v4` usa: sem round trips por chunk, sem arquivos temporários.
- Compressão e descompressão são **multi-thread (zstd)**, e uploads e downloads rodam como transferências paralelas.
- O armazenamento fica **na mesma região do seu runner**, então os bytes nunca viajam longe.
- Cada save e restore imprime seu tempo no log do job, então você pode medir a diferença nos seus próprios builds.

## Quanto vale o cache: um exemplo prático

Os números abaixo são ilustrativos, não um benchmark medido: eles mostram o formato do ganho, e seus próprios builds vão diferir. Imagine um app Node.js no `latchkey-medium` com um `node_modules` de ~400 MB. Sem cache, o `npm ci` resolve e baixa tudo a cada run: digamos ~3 minutos (180 s). Com um acerto de cache, o restore é um único download em streaming descomprimido em tempo real, chegando em segundos (digamos ~10 s), e se você pular o passo de instalação em um acerto (o exemplo de workflow abaixo faz exatamente isso) a instalação de 3 minutos desaparece; equipes que rodam `npm ci` mesmo assim o veem terminar em dezenas de segundos contra o `node_modules` aquecido. Considere o caminho do acerto como ~30 s de trabalho com dependências em vez de 180.

Com essas premissas, isso dá aproximadamente **2,5 minutos economizados por run** e, com 100 runs por semana, resulta em cerca de **250 minutos de runner por semana**, um pouco mais de quatro horas. O cache não ajuda todo run: uma key fria após uma mudança de lockfile ainda paga a instalação completa mais o save (~195 s aqui), um pouco pior do que sem cache algum; o retorno vem de cada acerto que se segue.

> **Meça nos seus próprios builds**
> Seus números dependem do tamanho das dependências, da rotatividade do lockfile e das condições de rede. A forma honesta de descobri-los: rode o mesmo workflow duas vezes e compare os tempos de passo que o GitHub mostra. O primeiro run é uma falha de cache mais um save; o segundo é um acerto. As linhas de log `Cache restored in {N}ms` e `Cache saved in {N}ms` lhe dão diretamente o lado do cache no balanço.

## Adicione a um workflow

Adicione dois passos: um com `action: restore` e outro com `action: save`. Cada um recebe um `key` e uma ou mais entradas `path` (separadas por quebra de linha ou espaço; `~` é suportado). O passo de restore expõe uma saída `cache-hit` para que você possa pular passos de instalação quando o cache é encontrado.

```.github/workflows/ci.yml
jobs:
  build:
    runs-on: latchkey-medium
    steps:
      - uses: actions/checkout@v4

      - name: Restore dependencies
        id: cache
        uses: latchkey-dev/cache-action@v1
        with:
          action: restore
          key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
          path: node_modules

      - name: Install dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: npm ci

      - name: Save dependencies
        uses: latchkey-dev/cache-action@v1
        with:
          action: save
          key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
          path: node_modules
```

## Migrando do actions/cache

> **Apenas runners Latchkey**
> O Fast Cache roda em runners gerenciados Latchkey (`latchkey-small` até `latchkey-xlarge` e labels customizados). Em outros runners a action não funciona; mantenha o `actions/cache@v4` lá.

## Padrões seguros

- Uma **falha de restore nunca faz o job falhar**: você recebe um aviso, `cache-hit` fica como `false` e o run continua.
- O save é **pulado automaticamente quando a key já existe**, então caches idênticos nunca são reenviados.
- Caches são **isolados por organização** e versionados automaticamente por sistema operacional; codifique isolamentos mais finos (como versões de OS) na sua chave de cache.
- As entradas de cache são armazenadas no lado do servidor com **retenção de 14 dias**, então caches obsoletos expiram sozinhos.

## O que você vê nos logs do job

| Linha de log | O que ela indica |
| --- | --- |
| `Cache restored in {N}ms` | O restore terminou, e quanto tempo levou |
| `Cache saved in {N}ms` | O save terminou, e quanto tempo levou |
| `Cache miss` | Não existia cache para a key; `cache-hit` é `false` e o job continua |
| `Cache already exists for key=..., skipping save` | O save foi pulado porque uma key idêntica já está armazenada |

## Cache que você não precisa procurar

O [AI Scan](/documentation/custom-runners) detecta de quais caches seu projeto precisa e os lista na configuração de runner proposta. A seção "Get more from Latchkey" do [AI Insight](/documentation/optimization-insights) pode propor a adição do cache do Latchkey a um workflow como um PR "Add Latchkey caching" de um clique, e a ferramenta Migrate Runners pode injetar passos de cache ao migrar os workflows. Times que nunca ajustam cache na mão mesmo assim o obtêm.

Para o ofício mais amplo - reduzir tempo de instalação, dividir suítes lentas, paralelizar - a biblioteca Learn tem um [hub de otimização de CI](/learn/optimize-ci) prático com guias que você pode aplicar em qualquer runner.

### Como migro do actions/cache para o Fast Cache?

Substitua `actions/cache` por `latchkey-dev/cache-action@v1`. Suas entradas `path`, `key` e `restore-keys` continuam iguais, então o diff é de uma linha e a semântica de cache que você já conhece permanece a mesma.

### O que torna o Fast Cache mais rápido que o actions/cache?

Uma requisição em streaming por save ou restore em vez de um upload em várias etapas, compressão zstd multi-thread e armazenamento na mesma região do runner. O ganho está na transferência e na descompressão, que é onde vai a maior parte do tempo de um passo de cache.

### O que acontece se o cache falhar?

O build continua. Uma falha de restore emite um aviso no log e o passo segue para uma instalação normal, então um problema de cache pode deixar o build mais lento, mas nunca o quebra. Isso é proposital: cache é otimização, e uma otimização que derruba o pipeline é um risco.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt