File
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- Integrated
- Bundled
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.
Add to your flow.json:
"stores": {
"files": {
"package": "@walkeros/server-store-fs",
"config": { "settings": { "basePath": "./public" }, "file": true }
}
},
"sources": {
"http": {
"package": "@walkeros/server-source-express",
"config": {
"settings": { "port": 8080, "paths": ["/collect", "/static/*path"] },
"ingest": { "map": { "path": { "key": "path" } } }
},
"next": "file"
}
},
"transformers": {
"file": {
"package": "@walkeros/server-transformer-file",
"config": { "settings": { "prefix": "/static" } },
"env": { "store": "$store.files" }
}
}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
| Property | Type | Description | More |
|---|---|---|---|
prefix | string | URL 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. | |
headers | Record<string, string> | Default response headers (e.g., Cache-Control, X-Frame-Options) | |
mimeTypes | Record<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" }
{
"name": "page view",
"data": {
"path": "/static/walker.js"
},
"id": "ev-1700000600",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000600000,
"source": {
"type": "express",
"platform": "server"
}
}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
failedwith codetransport.
How it works
- Reads
ingest.pathfrom the request context - Strips the configured
prefix(if set), e.g./static/image.pngbecomesimage.png - Looks up the remaining path in the store via
store.get(key) - If found, derives the Content-Type from the file extension, sets Content-Length for string and Buffer content, and responds with the content
- Returns
falseto stop the chain. No further transformers or destinations run. - 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.jscase: 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 aprefixthe step owns no path, and a file that is not found goes on unchanged too. - A file that is not found inside the prefix answers 404 with
{ "success": false, "error": "Not found" }andCache-Control: no-store. Theheaderssetting is not applied to it. - A store read that fails answers 503 with
{ "success": false, "error": "Service unavailable" }andCache-Control: no-store. The cause is logged atERRORand the push counts as failed.
Environment
| Key | Type | Required | Description |
|---|---|---|---|
store | Store.Instance | Yes | Store 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:
{
"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
}
}state-stores{
"Cache-Control": "public, max-age=300",
"Cross-Origin-Resource-Policy": "same-site"
}state-storesNext steps
- Cache - Add response caching before file serving
- Stores - Configure store backends
- Runtime: serving files - Bake files into the flow image