Caller.ts overview

Caller identity brands and schemas: credentials, root caller options, and the settings and results of the operations a caller performs.

Since v0.6.0

models

DirectoryChange (type alias)

A directory's revision before and after a change.

Signature

export type DirectoryChange = { readonly before: bigint; readonly after: bigint }

Source

Since v0.6.0

Identity (type alias)

A caller's credentials.

Signature

export type Identity = {
  readonly uid: number
  readonly gid: number
  readonly groups: readonly number[]
  readonly privileged: boolean
}

Source

Since v0.6.0

MkdirOptions (type alias)

Options of mkdir.

Signature

export type MkdirOptions = {
  readonly mode?: number
  readonly exactMode?: boolean
  readonly times?: {
    readonly access:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
    readonly modification:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
  }
  readonly recursive?: boolean
}

Source

Since v0.6.0

OpenEntryOptions (type alias)

Options of open on an entry.

Signature

export type OpenEntryOptions = {
  readonly access: "read" | "write" | "readWrite"
  readonly expected?: ObjectReference | null
  readonly mode?: number
  readonly create?: "never" | "ifMissing" | "exclusive"
  readonly append?: boolean
  readonly truncate?: boolean
  readonly exactMode?: boolean
  readonly times?: {
    readonly access:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
    readonly modification:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
  }
  readonly owner?: { readonly uid?: number; readonly gid?: number }
  readonly followFinalSymlink?: boolean
  readonly initialSize?: bigint
  readonly expectedChild?: {
    readonly reference: ObjectReference
    readonly revision: bigint
    readonly atimeNs: bigint
    readonly mtimeNs: bigint
  } | null
}

Source

Since v0.6.0

OpenOptions (type alias)

Options of open on a target.

Signature

export type OpenOptions = {
  readonly access: "read" | "write" | "readWrite"
  readonly mode?: number
  readonly create?: "never" | "ifMissing" | "exclusive"
  readonly append?: boolean
  readonly truncate?: boolean
}

Source

Since v0.6.0

RemoveOptions (type alias)

Options of remove.

Signature

export type RemoveOptions = {
  readonly expected?: ObjectReference
  readonly recursive?: boolean
  readonly force?: boolean
}

Source

Since v0.6.0

RenameReferenceResult (type alias)

The result of rename.

Signature

export type RenameReferenceResult =
  | {
      readonly _tag: "DifferentDirectories"
      readonly sourceDirectory: { readonly before: bigint; readonly after: bigint }
      readonly destinationDirectory: { readonly before: bigint; readonly after: bigint }
    }
  | {
      readonly _tag: "SameDirectory"
      readonly directory: { readonly before: bigint; readonly after: bigint }
    }

Source

Since v0.6.0

RootCallerOptions (type alias)

Options of a root caller.

Signature

export type RootCallerOptions = {
  readonly identity?: {
    readonly uid: number
    readonly gid: number
    readonly groups: readonly number[]
    readonly privileged: boolean
  }
  readonly umask?: number
}

Source

Since v0.6.0

SetattrOptions (type alias)

Attributes of setattr.

Signature

export type SetattrOptions = {
  readonly expected?: { readonly revision: bigint }
  readonly size?: bigint
  readonly mode?: number
  readonly times?: {
    readonly access:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
    readonly modification:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
  }
  readonly owner?: { readonly uid?: number; readonly gid?: number }
}

Source

Since v0.6.0

SymlinkOptions (type alias)

Options of symlink.

Signature

export type SymlinkOptions = {
  readonly times?: {
    readonly access:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
    readonly modification:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
  }
}

Source

Since v0.6.0

WalkOptions (type alias)

Options of walk.

Signature

export type WalkOptions = {
  readonly maxEntries?: number
  readonly maxDepth?: number
  readonly maxBytes?: ByteSize.ByteSize
  readonly order?: "pre" | "post"
}

Source

Since v0.6.0

WriteFileOptions (type alias)

Options of writeFile.

Signature

export type WriteFileOptions = {
  readonly access: "read" | "write" | "readWrite"
  readonly mode?: number
  readonly create?: "never" | "ifMissing" | "exclusive"
  readonly append?: boolean
  readonly truncate?: boolean
  readonly followFinalSymlink?: boolean
  readonly replaceFinalSymlink?: boolean
  readonly finalMode?: number
}

Source

Since v0.6.0

schemas

DirectoryChange

Schema for a directory's revision before and after a change.

Signature

declare const DirectoryChange: Schema.Struct<{ readonly before: Schema.BigInt; readonly after: Schema.BigInt }>

Source

Since v0.6.0

Identity

Schema for a caller's credentials. privileged is explicit; uid zero alone grants nothing.

Signature

declare const Identity: Schema.Struct<{
  readonly uid: Schema.Natural
  readonly gid: Schema.Natural
  readonly groups: Schema.$Array<Schema.Natural>
  readonly privileged: Schema.Boolean
}>

Source

Since v0.6.0

MkdirOptions

Schema for the options of mkdir. exactMode skips the caller's umask for an explicit creation mode; permission policy still applies. recursive creates every missing directory on the path in one change, as mkdir -p does, and succeeds when the final directory already exists; the mode applies to every directory it creates and the times to the final one.

Signature

declare const MkdirOptions: Schema.Struct<{
  readonly mode: Schema.optionalKey<Schema.Natural>
  readonly exactMode: Schema.optionalKey<Schema.Boolean>
  readonly times: Schema.optionalKey<
    Schema.Struct<{
      readonly access: Schema.Union<
        readonly [
          Schema.Struct<{ readonly kind: Schema.Literal<"now"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"omit"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"value">; readonly nanoseconds: Schema.BigInt }>
        ]
      >
      readonly modification: Schema.Union<
        readonly [
          Schema.Struct<{ readonly kind: Schema.Literal<"now"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"omit"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"value">; readonly nanoseconds: Schema.BigInt }>
        ]
      >
    }>
  >
  readonly recursive: Schema.optionalKey<Schema.Boolean>
}>

Source

Since v0.6.0

OpenEntryOptions

Schema for the options of open on an entry, a lookup-or-create-and-open in one gate hold. expected pins the child the caller last observed under the name (or null for none) and fails as VolumeBusy when another has appeared; expectedChild pins its revision and times as well and fails as StaleReference when they moved.

Signature

declare const OpenEntryOptions: Schema.Struct<{
  readonly access: Schema.Literals<readonly ["read", "write", "readWrite"]>
  readonly create: Schema.optionalKey<Schema.Literals<readonly ["never", "ifMissing", "exclusive"]>>
  readonly mode: Schema.optionalKey<Schema.Natural>
  readonly append: Schema.optionalKey<Schema.Boolean>
  readonly truncate: Schema.optionalKey<Schema.Boolean>
  readonly followFinalSymlink: Schema.optionalKey<Schema.Boolean>
  readonly times: Schema.optionalKey<
    Schema.Struct<{
      readonly access: Schema.Union<
        readonly [
          Schema.Struct<{ readonly kind: Schema.Literal<"now"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"omit"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"value">; readonly nanoseconds: Schema.BigInt }>
        ]
      >
      readonly modification: Schema.Union<
        readonly [
          Schema.Struct<{ readonly kind: Schema.Literal<"now"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"omit"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"value">; readonly nanoseconds: Schema.BigInt }>
        ]
      >
    }>
  >
  readonly initialSize: Schema.optionalKey<Schema.BigInt>
  readonly exactMode: Schema.optionalKey<Schema.Boolean>
  readonly owner: Schema.optionalKey<
    Schema.Struct<{
      readonly uid: Schema.optionalKey<Schema.Natural>
      readonly gid: Schema.optionalKey<Schema.Natural>
    }>
  >
  readonly expected: Schema.optionalKey<Schema.NullOr<Schema.declare<ObjectReference, ObjectReference>>>
  readonly expectedChild: Schema.optionalKey<
    Schema.NullOr<
      Schema.Struct<{
        readonly reference: Schema.declare<ObjectReference, ObjectReference>
        readonly revision: Schema.BigInt
        readonly atimeNs: Schema.BigInt
        readonly mtimeNs: Schema.BigInt
      }>
    >
  >
}>

Source

Since v0.6.0

OpenOptions

Schema for the options of open on a target: the access mode, whether a missing file is created, the creation mode, and append and truncate flags.

Signature

declare const OpenOptions: Schema.Struct<{
  readonly access: Schema.Literals<readonly ["read", "write", "readWrite"]>
  readonly create: Schema.optionalKey<Schema.Literals<readonly ["never", "ifMissing", "exclusive"]>>
  readonly mode: Schema.optionalKey<Schema.Natural>
  readonly append: Schema.optionalKey<Schema.Boolean>
  readonly truncate: Schema.optionalKey<Schema.Boolean>
}>

Source

Since v0.6.0

RemoveOptions

Schema for the options of remove. recursive removes a directory and everything under it; force succeeds when the target itself is missing. expected pins object identity at each coordinated removal stage. A replacement fails VolumeBusy.

Signature

declare const RemoveOptions: Schema.Struct<{
  readonly recursive: Schema.optionalKey<Schema.Boolean>
  readonly force: Schema.optionalKey<Schema.Boolean>
  readonly expected: Schema.optionalKey<Schema.suspend<Schema.declare<ObjectReference, ObjectReference>>>
}>

Source

Since v0.6.0

RenameReferenceResult

Schema for the result of rename.

Signature

declare const RenameReferenceResult: Schema.TaggedUnion<{
  readonly DifferentDirectories: Schema.TaggedStruct<
    "DifferentDirectories",
    {
      readonly sourceDirectory: Schema.Struct<{ readonly before: Schema.BigInt; readonly after: Schema.BigInt }>
      readonly destinationDirectory: Schema.Struct<{ readonly before: Schema.BigInt; readonly after: Schema.BigInt }>
    }
  >
  readonly SameDirectory: Schema.TaggedStruct<
    "SameDirectory",
    { readonly directory: Schema.Struct<{ readonly before: Schema.BigInt; readonly after: Schema.BigInt }> }
  >
}>

Source

Since v0.6.0

RootCallerOptions

Schema for the options of a root caller.

Signature

declare const RootCallerOptions: Schema.Struct<{
  readonly identity: Schema.optionalKey<
    Schema.Struct<{
      readonly uid: Schema.Natural
      readonly gid: Schema.Natural
      readonly groups: Schema.$Array<Schema.Natural>
      readonly privileged: Schema.Boolean
    }>
  >
  readonly umask: Schema.optionalKey<Schema.Natural>
}>

Source

Since v0.6.0

SetattrOptions

Schema for the attributes setattr changes together: a regular file's size, the permission mode, the owner, and the access and modification times. An omitted attribute keeps its current value. expected pins the target's revision the caller last observed, checked inside the same change, and fails as StaleReference naming expected when the target has moved on, so a change decided from that observation never applies to a newer one.

Signature

declare const SetattrOptions: Schema.Struct<{
  readonly size: Schema.optionalKey<Schema.BigInt>
  readonly mode: Schema.optionalKey<Schema.Natural>
  readonly owner: Schema.optionalKey<
    Schema.Struct<{
      readonly uid: Schema.optionalKey<Schema.Natural>
      readonly gid: Schema.optionalKey<Schema.Natural>
    }>
  >
  readonly times: Schema.optionalKey<
    Schema.Struct<{
      readonly access: Schema.Union<
        readonly [
          Schema.Struct<{ readonly kind: Schema.Literal<"now"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"omit"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"value">; readonly nanoseconds: Schema.BigInt }>
        ]
      >
      readonly modification: Schema.Union<
        readonly [
          Schema.Struct<{ readonly kind: Schema.Literal<"now"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"omit"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"value">; readonly nanoseconds: Schema.BigInt }>
        ]
      >
    }>
  >
  readonly expected: Schema.optionalKey<Schema.Struct<{ readonly revision: Schema.BigInt }>>
}>

Source

Since v0.6.0

SymlinkOptions

Schema for the options of symlink.

Signature

declare const SymlinkOptions: Schema.Struct<{
  readonly times: Schema.optionalKey<
    Schema.Struct<{
      readonly access: Schema.Union<
        readonly [
          Schema.Struct<{ readonly kind: Schema.Literal<"now"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"omit"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"value">; readonly nanoseconds: Schema.BigInt }>
        ]
      >
      readonly modification: Schema.Union<
        readonly [
          Schema.Struct<{ readonly kind: Schema.Literal<"now"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"omit"> }>,
          Schema.Struct<{ readonly kind: Schema.Literal<"value">; readonly nanoseconds: Schema.BigInt }>
        ]
      >
    }>
  >
}>

Source

Since v0.6.0

WalkOptions

Schema for the options of walk: the order entries arrive in and the optional bounds on how deep, how many, and how many bytes the walk may reach. order defaults to "pre", each directory before its entries; a "post" walk reports each directory after them. Every bound defaults to unbounded, and a walk that would pass one fails with LimitExceeded naming the bound in field.

Signature

declare const WalkOptions: Schema.Struct<{
  readonly order: Schema.optionalKey<Schema.Literals<readonly ["pre", "post"]>>
  readonly maxDepth: Schema.optionalKey<Schema.Natural>
  readonly maxEntries: Schema.optionalKey<Schema.Natural>
  readonly maxBytes: Schema.optionalKey<Schema.ByteSize>
}>

Source

Since v0.6.0

WriteFileOptions

Schema for the options of writeFile: the open options plus whether a final symbolic link is replaced or followed and the mode the file ends with.

Signature

declare const WriteFileOptions: Schema.Struct<{
  readonly access: Schema.Literals<readonly ["read", "write", "readWrite"]>
  readonly create: Schema.optionalKey<Schema.Literals<readonly ["never", "ifMissing", "exclusive"]>>
  readonly mode: Schema.optionalKey<Schema.Natural>
  readonly append: Schema.optionalKey<Schema.Boolean>
  readonly truncate: Schema.optionalKey<Schema.Boolean>
  readonly followFinalSymlink: Schema.optionalKey<Schema.Boolean>
  readonly replaceFinalSymlink: Schema.optionalKey<Schema.Boolean>
  readonly finalMode: Schema.optionalKey<Schema.Natural>
}>

Source

Since v0.6.0

type IDs

CallerId

Brand key that marks a caller.

Signature

declare const CallerId: unique symbol

Source

Since v0.6.0

CallerId (type alias)

Brand key that marks a caller.

Signature

export type CallerId = typeof CallerId

Source

Since v0.6.0

ObjectReferenceId

Brand key that marks an object reference.

Signature

declare const ObjectReferenceId: unique symbol

Source

Since v0.6.0

ObjectReferenceId (type alias)

Brand key that marks an object reference.

Signature

export type ObjectReferenceId = typeof ObjectReferenceId

Source

Since v0.6.0