FluentCI Cache #
PureScript native Wasm component for FluentCI cache setup, watched Nix builds,
and streaming generic HTTP cache save/restore. Requires FluentCI 0.17.8+ and
Node.js 24+. The component embeds its compiled host helper; consumers need only
plugin.wasm, without this checkout, node_modules, or sibling files.
Building and publishing #
npm run build installs this module's dependencies from package-lock.json
with npm ci --include=dev before packaging. FluentCI publishing invokes this
same build, so esbuild and tar do not need a separate manual installation.
The development dependencies are needed even when NODE_ENV=production is set.
Required credentials #
Set FLUENTCI_CACHE_TOKEN through your CI secret provider. It is required for
every operation, environment-only, and never included in returned records or
generated configuration. Provide --url or FLUENTCI_CACHE_URL; the argument
wins. There is no implicit account or URL. DID, handle with or without @, and
legacy /accounts/<hash> URLs are accepted. Omit protocol suffixes such as /nix.
export FLUENTCI_CACHE_URL=https://cache.fluentci.io/@example.com
# Configure FLUENTCI_CACHE_TOKEN through your secret provider.
fluentci run cache setup --protocol sccache
fluentci run cache save --key dependencies/linux --path node_modules --compression zstd
fluentci run cache restore --key dependencies/linux --path node_modules
Generic HTTP cache #
save accepts a file or directory. Compression choices are zstd (default,
level 3), gzip, and none. Directories are tar archives. restore detects the
recorded compression automatically, validates the payload checksum, rejects
unsafe archive paths, symlinks and special entries, then stages replacement on
the destination filesystem. A download or extraction failure preserves the
existing destination. Unsupported formats fail explicitly. Archives use this
module's versioned envelope; raw files uploaded by other clients are not silently
interpreted as archives. The current expanded-size limit is 20 GiB.
A missing key returns hit=false; --required makes a miss fail. Authentication,
backend errors and corrupt archives always fail. Uploads and transient downloads
retry at most three times. No shell expansion is performed on keys or paths.
Protocol setup #
| Protocol | Setup result |
|---|---|
nix |
Publishes NIX_CONFIG with FluentCI substitution and trust settings |
sccache |
Installs pinned checksum-verified sccache on Linux/macOS x64 and ARM64 (plus Windows assets when supported by the FluentCI host); activates WebDAV and disables directory creation |
bazel |
Generates bazelrc and environment-backed credential helper |
bazel-grpc |
Generates gRPC endpoint, canonical account instance and credential helper |
turbo |
Publishes API URL, owner team and token binding |
nx |
Publishes self-hosted endpoint and token binding |
buildkit |
Generates Docker login/build wrapper and account-scoped registry reference |
go |
Publishes GOCACHEPROG; install the fluentci-cache helper and Go 1.24+ first |
gradle |
Generates an init script; invoke Gradle using the generated instructions |
maven |
Generates extension, cache configuration and settings fragments to merge |
generic |
Configures generic HTTP cache access for save/restore |
Setup writes a fresh .fluentci/cache/PROTOCOL directory by default; use
--config-dir to choose another directory. Existing directories are rejected.
It returns generated paths and public environment values, activates credentials
in the FluentCI engine, and creates env.sh for external shell workflows. For
separate GitHub Actions steps, supply the relevant token variable from the same
secret; secret values are deliberately absent from the setup result.
On systems without a supported sccache binary (including BSD), setup selects
FLUENTCI_RUST_CACHE_BACKEND=generic. Restore/save the Cargo target directory
around the build using cache restore and cache save. Use keys including OS,
architecture, Rust version, target and Cargo.lock hash. The manual FluentCI cache build workflow uses this fallback for BSD artifacts.
Other client tools are not installed automatically. Node and Nix are declared setup dependencies; the Go helper, Gradle, Maven, Bazel, Nx, Turbo and Docker remain client prerequisites. BuildKit login writes Docker's normal credentials. Public CDN reads do not need the upload token; this module intentionally requires it to configure an authenticated cache consistently.
Nix build #
# Also configure FLUENTCI_NIX_PUBLIC_KEY and FLUENTCI_NIX_SIGNING_KEY as appropriate.
fluentci run cache nix-build --flake .#my-package
Requires the complete Nix public/private signing keys in the environment. It restores exact available outputs, watches new store paths while Nix builds, reuses upstream/FluentCI metadata, exports signed Zstd NARs, uploads payloads before narinfo with 16 workers, retries transient errors and drains uploads before success. No keys are generated. Temporary private key files are removed. Nix sandboxed derivations use this binary cache rather than remote sccache.
Generic restore follows HTTPS CDN redirects and strips the upload token when crossing origins. Public S3-backed artifact reads go directly to the CDN; uploads continue through the authenticated cache service.
Validation #
Builds, tests and generated-file checks run in CI. No local runtime validation was performed for this extraction. See COMPONENT.md.
Compose this module from code #
Requires FluentCI 0.17.6 or newer for generated pipeline bindings. From your caller module's directory, add the dependency:
fluentci add cache --path /path/to/fluentci-modules/caching/cache
For a published module, use fluentci add @fluentci.io/cache@VERSION with an
available version. Commit the caller's manifest and lockfile. FluentCI generates
named bindings from the installed component's WIT; no handwritten FFI or CLI
subprocess is needed. Include generated source directories in the caller's SDK
project. The callee can use a different SDK from the caller.
Configure authenticated FluentCI caching; URL and token are supplied through CI environment variables.
Replace the sample organization, paths and identifiers with your own. Configure credentials through your CI secret provider before running authenticated operations. Optional arguments use the callee's defaults, and public list fields use comma-separated strings. See COMPONENT.md for argument descriptions and return types.
These examples use the generated composition API and builder chaining in FluentCI 0.17.6; full cross-SDK compilation and execution coverage is still pending. See composition support and limitations.
PureScript #
module Main where
import Prelude
import Effect (Effect)
import FluentCI.Flow as Flow
import FluentCI.Modules.Cache as Cache
run :: Effect String
run =
Flow.pipeline "cache-setup"
# Flow.workdir "."
# Cache.setup (Cache.setupArgs { "protocol": "sccache" })
# Flow.map (\result -> result.binDir)
# Flow.run
Gleam #
import fluentci/flow
import fluentci_modules/cache
pub fn run() -> String {
flow.pipeline("cache-setup")
|> flow.workdir(".")
|> cache.setup(cache.setup_args("sccache"))
|> flow.map(fn(result) { result.bin_dir })
|> flow.run
}
Use Gleam's JavaScript target for the Wasm guest. BEAM escripts used for repository automation are separate from component guests.
Elixir #
defmodule Main do
use FluentCI.Plugin
alias FluentCI.Flow
alias FluentCI.Modules.Cache
defplugin run do
Flow.pipeline("cache-setup")
|> Flow.workdir(".")
|> Cache.setup(%{"protocol" => "sccache"})
|> Flow.stdout()
end
end
Elixir compiles this sequence to Rust/Wasm. Its initial Flow API does not yet provide the typed result callbacks or cleanup combinators of the other examples.
ClojureScript #
(ns main.plugin
(:require [fluentci.flow :as flow]
[fluentci-modules.cache :as cache]))
(defn run []
(-> (flow/pipeline "cache-setup")
(flow/workdir ".")
(cache/setup {:protocol "sccache"})
flow/run!))
ReScript #
let run = (): string =>
Flow.pipeline("cache-setup")
->Flow.workdir(".")
->FluentciModulesCache.setup(FluentciModulesCache.setupArgs(~protocol="sccache"))
->Flow.map(result => result.binDir)
->Flow.run
Python #
from fluentci.flow import pipeline
from fluentci_modules import cache
def run() -> str:
return (
pipeline("cache-setup")
.workdir(".")
.pipe(cache.setup, {"protocol": "sccache"})
.map(lambda result: result.bin_dir)
.run()
)
TypeScript #
import * as flow from "./fluentci_modules/flow";
import * as cache from "./fluentci_modules/cache/index";
export function run(): string {
return flow.pipeline("cache-setup")
.workdir(".")
.pipe(cache.setup, {"protocol":"sccache"})
.map(result => result.binDir)
.run();
}
Python and TypeScript use FluentCI builder chains: .pipe(module.function, args)
composes generated module functions with .workdir, .env, and .exec.
Functions return a pipeline carrying their typed result. Use a generated result
callback (With/_with, or a callback argument in TypeScript/Python) when a later
module needs a preceding result; use Flow's map operation to select a result field.
Execution begins at run (or the Elixir plugin terminal), in declared order.
Exported functions #
| Function | Purpose |
|---|---|
setup |
Configure a FluentCI cache protocol using required environment credentials. |
nixBuild |
Build a Nix installable while reusing and publishing signed FluentCI cache outputs. |
save |
Compress and upload a file or directory to the generic HTTP cache. |
restore |
Download, verify and restore a generic HTTP cache entry without replacing files on failure. |