Files
An actor that declares fs owns a private directory of POSIX files. Its commands and jobs read and write that directory through the Effect FileSystem service. Its queries read the directory and never write to it.
Declare files, write them in turns and stream them from jobs
- Declare
fswith the callers that may read and write the files from a client inreport.contract.ts.
import { Schema } from "effect"
import { Akter } from "@akterjs/effect/contract"
export const Editor = Akter.caller("editor", Schema.Struct({ id: Akter.PrincipalId }))
export const Drafting = Schema.TaggedStruct("Drafting", {})
export const Report = Akter.make("Report", {
callers: [Editor],
commands: {
export: Akter.command({
callers: [Editor],
errors: [],
from: [Drafting],
input: Schema.Struct({ rows: Schema.Int }),
output: Schema.String,
to: [Drafting],
}),
publish: Akter.command({
callers: [Editor],
errors: [],
from: [Drafting],
input: Schema.Struct({ text: Schema.String }),
output: Schema.Void,
to: [Drafting],
}),
},
fs: Akter.fs({ callers: [Editor] }),
initial: { input: Schema.Void, to: Drafting },
jobs: {
exporting: Akter.job({
errors: [],
from: [Drafting],
input: Schema.Struct({ rows: Schema.Int }),
output: Schema.Void,
patches: [],
to: [Drafting],
}),
},
key: Schema.String,
parent: Akter.Root,
queries: {
summary: Akter.query({
callers: [Editor],
errors: [],
input: Schema.Void,
output: Schema.String,
states: [Drafting],
}),
},
states: [Drafting],
tables: [],
})- Write a draft and rename it into place inside a command in
report.actor.ts. Read the file in a query.
import { Effect, FileSystem } from "effect"
import { Akter } from "@akterjs/effect/contract"
import { Drafting, Report } from "./report.contract.ts"
export const ReportLive = Report.toLayer({
commands: {
export: (report, { rows }) =>
Effect.map(Akter.start(Report.jobs.exporting, { rows }), (job) => ({ next: report, output: job })),
publish: (report, { text }) =>
Effect.gen(function* () {
const files = yield* FileSystem.FileSystem
yield* files.makeDirectory("drafts", { recursive: true })
yield* files.writeFileString("drafts/summary.txt", text)
yield* files.rename("drafts/summary.txt", "summary.txt")
return { next: report }
}),
},
initial: () => ({ next: Drafting.make({}) }),
queries: {
summary: () => FileSystem.FileSystem.use((files) => files.readFileString("summary.txt")),
},
results: {
exporting: (report) => Effect.succeed({ next: report }),
},
})- Stream a file larger than 1 MiB from a job through
files.sinkinexport.job.ts.
import { Effect, FileSystem, Stream } from "effect"
import { Report } from "./report.contract.ts"
const encoder = new TextEncoder()
export const ExportLive = Report.jobs.exporting.toLayer(({ rows }) =>
Effect.gen(function* () {
const files = yield* FileSystem.FileSystem
const lines = Stream.map(Stream.range(1, rows), (row) => encoder.encode(`row ${row}\n`))
yield* Effect.orDie(Stream.run(lines, files.sink("export.csv")))
}),
)- Upload and download files from a client with
Report.files.writeandReport.files.readinreport-files.ts.
import { Effect, Stream } from "effect"
import { Report } from "./report.contract.ts"
const encoder = new TextEncoder()
export const uploaded = Report.files.write("q4", "notes.txt", Stream.make(encoder.encode("hello")))
export const downloaded = Effect.map(Stream.runCollect(Report.files.read("q4", "export.csv")), (chunks) =>
chunks.reduce((total, chunk) => total + chunk.length, 0),
)- Test the files with
Story.runinreport.story.ts.
import { Effect, Layer } from "effect"
import { Akter } from "@akterjs/effect/contract"
import { Story } from "@akterjs/effect/testing"
import { Editor, Report } from "./report.contract.ts"
import { ReportLive } from "./report.actor.ts"
import { ExportLive } from "./export.job.ts"
const as = { caller: Editor, principal: { id: Akter.PrincipalId.make("ada") } }
const program = Story.run(Layer.mergeAll(ReportLive, ExportLive), function* (story) {
const report = yield* story.actor(Report, "q4", { as })
yield* report.publish({ text: "revenue grew" })
console.log(yield* report.summary())
})
Effect.runPromise(program)revenue grewWhy turn writes commit with the turn and job writes do not
A command or a job’s <Actor>.turn writes files inside the turn’s transaction. The host stages each write and commits the files together with the state and the SQL rows. A handler that fails, dies or is cancelled leaves no file and no rename behind. A crash before the commit has the same effect.
A query reads the committed files only. A write inside a query fails, so a query can never change the actor.
A job runs outside any turn, so its writes land at once under the job’s run. A job writes in chunks at fixed offsets, so a replayed run writes the same bytes again. This lets a job stream files far larger than one turn may hold, while queries of the same actor keep answering.
Inside <Actor>.turn, a job uses the turn’s own FileSystem. A call through the job’s FileSystem there stops the job with a defect, and the actor keeps answering.
A job write and a client file call wait while a turn of the same actor runs. Each one lands after that turn commits or rolls back. A turn’s staged files therefore never overwrite a job’s bytes, and a job never writes into a directory that the turn moves.
Why uploads and downloads never show a partial file
A client upload writes to a temporary file in 256 KiB chunks and then renames the file into place. A reader sees the old file or the complete new file, never a partial one. A download reads the whole file when it starts and streams that content. A write during the download does not change the bytes it returns.
The temporary file sits beside the target, and its name starts with .akter-upload.. The host leaves these upload files out of readDirectory and out of the usage that stat(".") reports. A client that stops in the middle of an upload leaves its upload file behind. The host removes every upload file when it revives the actor’s record after a restart. A new upload to a path also removes each upload file for that path that got no chunk for 10 minutes. A chunk for a removed upload file fails with notFound, so an interrupted upload never lands a partial file.
The host reserves the .akter-upload. prefix for upload files. An upload file name is the prefix, the upload’s UUIDv7 id, a dot and the target name. A turn or a job fails with BadArgument on any path segment that starts with the prefix. A client file call accepts a prefixed name only in that exact upload form. Any other prefixed name fails with invalidPath.
File limits, paths and failures
- Directory. Each actor key has its own directory. The path
.is the root of that directory. - Paths. A path is relative. A leading
/, an empty segment, a.or..segment, or a NUL byte fails withBadArgument. In a turn or a job, a segment that starts with.akter-upload.fails the same way. The path.alone names the root. - Turn size. A command, a query or a job’s
<Actor>.turnmoves at most 1 MiB of file bytes in total. EveryreadFile,writeFile, chunk read and chunk write counts toward that limit. A call past the limit fails withInvalidData. - Chunks.
open,streamandsinkmove files in chunks of at most 256 KiB. A larger chunk fails withInvalidData. A job is not bound by the turn size. - File size. A file holds at most 256 MiB. A chunk that starts before offset 0 or ends past 256 MiB fails with
InvalidData. - Handles. A
seekor a readpositionbefore the start of the file fails withBadArgument. A read at apositionleaves the cursor in place. A handle opened withrrefuses writes withPermissionDenied. A handle opened witha,ax,a+orax+writes at the current end of the file and leaves the cursor in place. On a job handle, an append reads the file size and then writes at that offset. A client rename or a turn commit between the two calls can move the end of the file. - Rename.
renameis atomic. A file replaces an existing target file. A directory moves to a missing path or onto an empty directory. A directory that holds only upload files counts as empty, and the rename removes those upload files. A target directory with entries fails withnotEmpty. A directory onto a file fails withnotDirectory. A file onto a directory fails withisDirectory. - Usage.
stat(".")returns the total bytes of the actor’s files assize. - Modified time.
mtimeis the wall time of the turn or job run that last wrote the file. - Client access.
Report.filesexists only on actors that declarefs. A caller thatfs.callersomits fails withCallerNotAllowedError. A call to an actor that needs explicit creation and was never created fails withActorNotCreatedError. - Unsupported calls.
chmod,chown,copy,link,readLink,realPath,symlink,truncate,utimes,watchand temporary files fail withBadArgument. AwriteFilewith a flag other thanwfails the same way.
| Host failure | PlatformError reason | Cause |
|---|---|---|
alreadyExists | AlreadyExists | The path exists, and the call needs a new one. |
invalidPath | BadArgument | The path breaks the path rules. |
isDirectory | BadResource | The call needs a file, and the path is a directory. |
notDirectory | BadResource | The call needs a directory, and the path is a file. |
notEmpty | Busy | A remove without recursive or a rename found entries other than upload files in the target directory. |
notFound | NotFound | The path does not exist. |
readOnly | PermissionDenied | A query tried to write. |
tooLarge | InvalidData | A turn moved more than 1 MiB, a chunk moved more than 256 KiB, or a chunk fell outside the 256 MiB file size. |
A client call fails with FileFailedError, which carries the host failure code, a message and the path.
Hosts that serve files
The in-memory test host behind akter dev and Story serves every fs host call. Akter Cloud’s akterd answers fs host calls with unsupported.