Skip to content

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⁠

  1. Declare fs with the callers that may read and write the files from a client in report.contract.ts.
report.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: [],
})
  1. Write a draft and rename it into place inside a command in report.actor.ts. Read the file in a query.
report.actor.ts
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 }),
  },
})
  1. Stream a file larger than 1 MiB from a job through files.sink in export.job.ts.
export.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")))
  }),
)
  1. Upload and download files from a client with Report.files.write and Report.files.read in report-files.ts.
report-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),
)
  1. Test the files with Story.run in report.story.ts.
report.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)
Text
revenue grew

Why 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 with BadArgument. 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>.turn moves at most 1 MiB of file bytes in total. Every readFile, writeFile, chunk read and chunk write counts toward that limit. A call past the limit fails with InvalidData.
  • Chunks. open, stream and sink move files in chunks of at most 256 KiB. A larger chunk fails with InvalidData. 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 seek or a read position before the start of the file fails with BadArgument. A read at a position leaves the cursor in place. A handle opened with r refuses writes with PermissionDenied. A handle opened with a, ax, a+ or ax+ 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. rename is 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 with notEmpty. A directory onto a file fails with notDirectory. A file onto a directory fails with isDirectory.
  • Usage. stat(".") returns the total bytes of the actor’s files as size.
  • Modified time. mtime is the wall time of the turn or job run that last wrote the file.
  • Client access. Report.files exists only on actors that declare fs. A caller that fs.callers omits fails with CallerNotAllowedError. A call to an actor that needs explicit creation and was never created fails with ActorNotCreatedError.
  • Unsupported calls. chmod, chown, copy, link, readLink, realPath, symlink, truncate, utimes, watch and temporary files fail with BadArgument. A writeFile with a flag other than w fails the same way.
Host failurePlatformError reasonCause
alreadyExistsAlreadyExistsThe path exists, and the call needs a new one.
invalidPathBadArgumentThe path breaks the path rules.
isDirectoryBadResourceThe call needs a file, and the path is a directory.
notDirectoryBadResourceThe call needs a directory, and the path is a file.
notEmptyBusyA remove without recursive or a rename found entries other than upload files in the target directory.
notFoundNotFoundThe path does not exist.
readOnlyPermissionDeniedA query tried to write.
tooLargeInvalidDataA 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.