Skip to main content
Ask your AI

File

Server Source code Package

Serves static files from a store backend. Reads the file by ingest.path, derives the Content-Type from the file extension, and responds directly. Returns false to stop the transformer chain so no further transformers or destinations run for the request. A step with a prefix owns every path inside it: a file that is not there answers 404. A store read that fails answers 503, with or without a prefix.

Installation​

npm install @walkeros/server-transformer-file
import { startFlow } from '@walkeros/collector';
import { sourceExpress } from '@walkeros/server-source-express';
import { transformerFile } from '@walkeros/server-transformer-file';
import { storeFsInit } from '@walkeros/server-store-fs';

// Reference this same object in stores and in env: the collector swaps it
// for the initialized store instance at startup.
const files = {
  code: storeFsInit,
  config: { settings: { basePath: './public' }, file: true },
};

await startFlow({
  stores: { files },
  sources: {
    http: {
      code: sourceExpress,
      config: {
        settings: { port: 8080, paths: ['/collect', '/static/*path'] },
        ingest: { map: { path: { key: 'path' } } },
      },
      next: 'file',
    },
  },
  transformers: {
    file: {
      code: transformerFile,
      config: {
        settings: { prefix: '/static' },
      },
      env: { store: files },
    },
  },
});

The '$store.files' string only works in a bundled flow.json, where the CLI resolves it. In startFlow it stays a string, and the flow stops at startup with a config error.

The source maps the request path into ingest.path, which the transformer reads, and runs the transformer in its next chain. file: true on the store makes it hand back each file's raw bytes. Without it every read fails with the decode code (one ERROR line per cause and minute) and the step answers 503 instead of the file; walkeros validate warns about the missing flag.

Configuration​

This transformer uses the standard transformer config wrapper (consent, data, env, id, ...). For the shared fields see transformer configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
prefixstringURL prefix the step owns, stripped before store lookup. E.g., "/static" → /static/walker.js looks up "walker.js". A missing file inside the prefix answers 404, a path outside it passes on, "/" owns every routed path. Without a prefix a missing file passes on.
headersRecord<string, string>Default response headers (e.g., Cache-Control, X-Frame-Options)
mimeTypesRecord<string, string>Extension → Content-Type overrides. Keys include dot: { ".wasm": "application/wasm" }

Mapping​

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Examples

Serve static file

Serve a static JavaScript file from store. Config: prefix: "/static", headers: { "Cache-Control": "public, max-age=3600" }

Event
{
  "name": "page view",
  "data": {
    "path": "/static/walker.js"
  },
  "id": "ev-1700000600",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000600000,
  "source": {
    "type": "express",
    "platform": "server"
  }
}
Out
respond({
  "status": 200,
  "headers": {
    "Content-Type": "application/javascript",
    "Cache-Control": "public, max-age=3600"
  }
})

When it fails

  • Store unavailable: The store read fails: the request is answered 503 with Cache-Control no-store and the push fails with the store error. Reported as failed with code transport.

How it works​

  1. Reads ingest.path from the request context
  2. Strips the configured prefix (if set), e.g. /static/image.png becomes image.png
  3. Looks up the remaining path in the store via store.get(key)
  4. If found, derives the Content-Type from the file extension, sets Content-Length for string and Buffer content, and responds with the content
  5. Returns false to stop the chain. No further transformers or destinations run.
  6. The step owns the paths inside settings.prefix. "prefix": "/" owns every path routed to the step. Route only file requests to a step that owns /, as flow-complete does with a .js case: any other path routed to it answers 404 and its event stops there. A path outside the prefix goes on unchanged like any other request on the source. Without a prefix the step owns no path, and a file that is not found goes on unchanged too.
  7. A file that is not found inside the prefix answers 404 with { "success": false, "error": "Not found" } and Cache-Control: no-store. The headers setting is not applied to it.
  8. A store read that fails answers 503 with { "success": false, "error": "Service unavailable" } and Cache-Control: no-store. The cause is logged at ERROR and the push counts as failed.

Environment​

KeyTypeRequiredDescription
storeStore.InstanceYesStore providing file content. Without a usable store (missing, or without a get function) the flow stops at startup with a config error.

Cache and file chain​

Put a cache on the source to answer repeated file requests from memory, without reading the store again. A cache on the file transformer itself never stores an entry, because the transformer stops the chain once it responds:

"stores": {
  "files": {
    "package": "@walkeros/server-store-fs",
    "config": { "settings": { "basePath": "./public" }, "file": true }
  }
},
"sources": {
  "http": {
    "package": "@walkeros/server-source-express",
    "config": {
      "settings": { "paths": ["/collect", "/static/*path"] },
      "ingest": {
        "map": {
          "method": { "key": "method" },
          "path": { "key": "path" }
        }
      }
    },
    "cache": {
      "rules": [
        {
          "match": {
            "and": [
              { "key": "ingest.method", "operator": "eq", "value": "GET" },
              { "key": "ingest.path", "operator": "prefix", "value": "/static" }
            ]
          },
          "key": ["ingest.method", "ingest.path"],
          "ttl": 300
        }
      ]
    },
    "next": [
      {
        "match": { "key": "ingest.method", "operator": "eq", "value": "GET" },
        "next": "file"
      }
    ]
  }
},
"transformers": {
  "file": {
    "package": "@walkeros/server-transformer-file",
    "config": { "settings": { "prefix": "/static" } },
    "env": { "store": "$store.files" }
  }
}

The source cache keeps a 404 for the ttl, like any answer. It never keeps a 5xx answer, so a store that fails for a moment is not served as 503 for the whole ttl.

Custom MIME types​

{
  settings: {
    mimeTypes: {
      '.wasm': 'application/wasm',
      '.mjs': 'application/javascript',
    },
  },
}

In the complete example​

The server flow of flow-complete.json, the tested example flow, serves the web bundle walker.js first party from an fs store. The step stops after serving, so a script request never becomes an event:

/flows/server/transformers/file
{
  "package": "@walkeros/server-transformer-file",
  "env": {
    "store": "$store.assets"
  },
  "config": {
    "settings": {
      "prefix": "/",
      "headers": {
        "Cache-Control": "public, max-age=300",
        "Cross-Origin-Resource-Policy": "same-site"
      }
    }
  },
  "next": {
    "stop": true
  }
}
walker.js is served first party from the server flow. Guide chapter state-stores
/flows/server/transformers/file/config/settings/headers
{
  "Cache-Control": "public, max-age=300",
  "Cross-Origin-Resource-Policy": "same-site"
}
Default response headers for served files: caching and resource policy. Guide chapter state-stores

Next steps​

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)