effect 4.0.0-rc.112 → 4.0.0-rc.113

package/src/unstable/socket/SocketServer.ts

@@ -3,15 +3,16 @@
  *
  * `SocketServer` exposes the bound server `address` and a long-running `run`
  * loop that hands each accepted connection to a handler as a `Socket.Socket`.
- * The module also defines TCP and Unix socket address models plus the
- * server-level errors reported while opening or running a server. Platform
- * layers provide concrete implementations of this service.
+ * Bound addresses use the shared `NetAddress.SocketAddress` model. This module also
+ * defines server-level errors reported while opening or running a server.
+ * Platform layers provide concrete implementations of this service.
  *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
 import * as Data from "../../Data.ts"
 import type * as Effect from "../../Effect.ts"
+import type * as NetAddress from "../net/NetAddress.ts"
 import type * as Socket from "./Socket.ts"
 
 /**
@@ -22,7 +23,7 @@ import type * as Socket from "./Socket.ts"
  * @since 4.0.0
  */
 export class SocketServer extends Context.Service<SocketServer, {
-  readonly address: Address
+  readonly address: NetAddress.SocketAddress
   readonly run: <R, E, _>(
     handler: (socket: Socket.Socket) => Effect.Effect<_, E, R>
   ) => Effect.Effect<never, SocketServerError, R>
@@ -114,34 +115,3 @@ export class SocketServerError extends Data.TaggedError("SocketServerError")<{
     return this.reason.message
   }
 }
-
-/**
- * Socket server address, either a TCP host and port or a Unix socket path.
- *
- * @category models
- * @since 4.0.0
- */
-export type Address = UnixAddress | TcpAddress
-
-/**
- * TCP socket server address with hostname and port.
- *
- * @category models
- * @since 4.0.0
- */
-export interface TcpAddress {
-  readonly _tag: "TcpAddress"
-  readonly hostname: string
-  readonly port: number
-}
-
-/**
- * Unix socket server address identified by a filesystem path.
- *
- * @category models
- * @since 4.0.0
- */
-export interface UnixAddress {
-  readonly _tag: "UnixAddress"
-  readonly path: string
-}

package/src/unstable/sql/SqlClient.ts

@@ -110,10 +110,30 @@ export declare namespace SqlClient {
    */
   export interface MakeOptions {
     readonly acquirer: Connection.Acquirer
+    /**
+     * Lends a connection for one statement instead of leasing one into a
+     * scope. A client that can do this saves the scope and finalizer per
+     * statement; `stream`, transactions, and `reserve` keep the `acquirer`,
+     * whose lease outlives the effect that starts it.
+     */
+    readonly borrower?: Connection.Borrower | undefined
     readonly compiler: Compiler
     readonly transactionAcquirer?: Connection.Acquirer
     readonly spanAttributes: ReadonlyArray<readonly [string, unknown]>
     readonly transactionService?: Context.Service<TransactionConnection, TransactionConnection.Service>
+    /**
+     * Whether the transaction control statements - `BEGIN`, `COMMIT`,
+     * `ROLLBACK`, and the savepoint pair - can be prepared like any other
+     * statement.
+     *
+     * **Details**
+     *
+     * They run on every transaction and never change, so a database that can
+     * prepare them stops parsing them again each time. Off by default,
+     * because several databases refuse to prepare transaction control at all;
+     * a driver has to say that its own does not.
+     */
+    readonly prepareTransactionControls?: boolean | undefined
     readonly beginTransaction?: string | undefined
     readonly rollback?: string | undefined
     readonly commit?: string | undefined
@@ -154,6 +174,9 @@ export const make = Effect.fnUntraced(function*(options: SqlClient.MakeOptions)
   const rollback = options.rollback ?? "ROLLBACK"
   const rollbackSavepoint = options.rollbackSavepoint ?? ((name: string) => `ROLLBACK TO SAVEPOINT ${name}`)
   const transactionAcquirer = options.transactionAcquirer ?? options.acquirer
+  const control = options.prepareTransactionControls === true
+    ? (conn: Connection.Connection, sql: string) => conn.execute(sql, [], undefined)
+    : (conn: Connection.Connection, sql: string) => conn.executeUnprepared(sql, [], undefined)
   const withTransaction = makeWithTransaction({
     transactionService,
     spanAttributes: options.spanAttributes,
@@ -161,16 +184,27 @@ export const make = Effect.fnUntraced(function*(options: SqlClient.MakeOptions)
       Scope.make(),
       (scope) => Effect.map(Scope.provide(transactionAcquirer!, scope), (conn) => [scope, conn] as const)
     ),
-    begin: (conn) => conn.executeUnprepared(beginTransaction, [], undefined),
-    savepoint: (conn, id) => conn.executeUnprepared(savepoint(`effect_sql_${id}`), [], undefined),
-    commit: (conn) => conn.executeUnprepared(commit, [], undefined),
-    rollback: (conn) => conn.executeUnprepared(rollback, [], undefined),
-    rollbackSavepoint: (conn, id) => conn.executeUnprepared(rollbackSavepoint(`effect_sql_${id}`), [], undefined)
+    begin: (conn) => control(conn, beginTransaction),
+    savepoint: (conn, id) => control(conn, savepoint(`effect_sql_${id}`)),
+    commit: (conn) => control(conn, commit),
+    rollback: (conn) => control(conn, rollback),
+    rollbackSavepoint: (conn, id) => control(conn, rollbackSavepoint(`effect_sql_${id}`))
   })
 
   const reactivity = yield* Reactivity
+  // A statement inside a transaction has to run on that transaction's
+  // connection, so borrowing is only for statements that reach the pool.
+  const borrower: Connection.Borrower | undefined = options.borrower === undefined ? undefined : (f) =>
+    Effect.flatMap(
+      Effect.serviceOption(transactionService),
+      Option.match({
+        onNone: () => options.borrower!(f),
+        onSome: ([conn]) => f(conn)
+      })
+    )
+
   const client: SqlClient = Object.assign(
-    Statement.make(getConnection, options.compiler, options.spanAttributes, options.transformRows),
+    Statement.make(getConnection, options.compiler, options.spanAttributes, options.transformRows, borrower),
     {
       [TypeId]: TypeId as typeof TypeId,
       safe: undefined as any,
@@ -185,7 +219,8 @@ export const make = Effect.fnUntraced(function*(options: SqlClient.MakeOptions)
           getConnection,
           options.compiler.withoutTransform,
           options.spanAttributes,
-          undefined
+          undefined,
+          borrower
         )
         const client = Object.assign(statement, {
           ...this,

package/src/unstable/sql/SqlConnection.ts

@@ -71,6 +71,24 @@ export interface Connection {
  */
 export type Acquirer = Effect<Connection, SqlError, Scope>
 
+/**
+ * Lends a connection for the duration of one effect and takes it back on any
+ * exit, without the caller opening a scope for it.
+ *
+ * **Details**
+ *
+ * A client that can do this offers it alongside its `Acquirer`, for statements
+ * that finish with the effect that runs them. Long-lived work such as `stream`
+ * still goes through the `Acquirer`, whose lease has to outlive the effect
+ * that starts it.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type Borrower = <A, E, R>(
+  f: (connection: Connection) => Effect<A, E, R>
+) => Effect<A, E | SqlError, R>
+
 /**
  * Service tag for a low-level SQL `Connection`.
  *

package/src/unstable/sql/SqlModel.ts

@@ -246,7 +246,7 @@ export const makeResolvers = <
         S["insert"]["Type"],
         S["Type"],
         ResultLengthMismatch | SqlError,
-        S["insert"]["EncodingServices"]
+        S["DecodingServices"] | S["insert"]["EncodingServices"]
       >
     >
     readonly insertVoid: RequestResolver.RequestResolver<

package/src/unstable/sql/Statement.ts

@@ -21,11 +21,11 @@ import * as InternalRecord from "../../internal/record.ts"
 import { hasProperty } from "../../Predicate.ts"
 import { TracerTimingEnabled } from "../../References.ts"
 import * as Stream from "../../Stream.ts"
-import type * as Tracer from "../../Tracer.ts"
-import type { Acquirer, Connection, Row } from "./SqlConnection.ts"
+import * as Tracer from "../../Tracer.ts"
+import type { Acquirer, Borrower, Connection, Row } from "./SqlConnection.ts"
 import type { SqlError } from "./SqlError.ts"
 
-const FragmentTypeId = "~effect/sql/Fragment"
+const FragmentTypeId = "~effect/sql/Statement/Fragment"
 
 /**
  * Composable SQL fragment represented as low-level segments that can be
@@ -106,6 +106,17 @@ export const CurrentTransformer = Context.Reference<Transformer | undefined>("ef
   defaultValue: constUndefined
 })
 
+/**
+ * Parents driver spans under `sql.execute` for every client in the current scope,
+ * including acquisition and stream pulls. Defaults to `false`; ignored when tracing is disabled.
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export const SpanPropagationEnabled = Context.Reference<boolean>("effect/sql/SpanPropagationEnabled", {
+  defaultValue: () => false
+})
+
 /**
  * Returns `true` when a value is a SQL `Fragment`.
  *
@@ -256,7 +267,7 @@ const RecordInsertHelperProto = {
   returning(this: RecordInsertHelper, sql: string | Identifier | Fragment) {
     const self = Object.create(Object.getPrototypeOf(this))
     Object.assign(self, this, {
-      returningIdentifier: sql
+      returningIdentifier: typeof sql === "string" || isFragment(sql) ? sql : fragment([sql])
     })
     return self
   }
@@ -533,7 +544,8 @@ export const make = (
   acquirer: Acquirer,
   compiler: Compiler,
   spanAttributes: ReadonlyArray<readonly [string, unknown]>,
-  transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
+  transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined,
+  borrower?: Borrower | undefined
 ): Constructor => {
   const cache = transformRows === undefined ? constructorCache.noTransforms : constructorCache.transforms
   if (cache.has(acquirer)) {
@@ -550,7 +562,8 @@ export const make = (
           strings as TemplateStringsArray,
           args,
           spanAttributes,
-          transformRows
+          transformRows,
+          borrower
         )
       }
 
@@ -566,7 +579,8 @@ export const make = (
           acquirer,
           compiler,
           spanAttributes,
-          transformRows
+          transformRows,
+          borrower
         )
       },
       literal(sql: string) {
@@ -621,7 +635,8 @@ export const statement = <A = Row>(
   strings: TemplateStringsArray,
   args: Array<any>,
   spanAttributes: ReadonlyArray<readonly [string, unknown]>,
-  transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
+  transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined,
+  borrower?: Borrower | undefined
 ): Statement<A> => {
   const segments: Array<Segment> = strings[0].length > 0 ? [literal(strings[0])] : []
 
@@ -641,7 +656,7 @@ export const statement = <A = Row>(
     }
   }
 
-  return makeUnsafe(segments, acquirer, compiler, spanAttributes, transformRows)
+  return makeUnsafe(segments, acquirer, compiler, spanAttributes, transformRows, borrower)
 }
 
 /**
@@ -843,7 +858,7 @@ const CompilerProto = {
     withoutTransform = withoutTransform || this.disableTransforms
     const cache = withoutTransform ? this.statementCacheNoTransform : this.statementCache
     const cached = cache.get(statement)
-    if (cached !== undefined) {
+    if (cached !== undefined && placeholderOverride === undefined) {
       return cached
     }
 
@@ -1230,6 +1245,7 @@ interface StatementImpl<A> extends Statement<A> {
   readonly compiler: Compiler
   readonly spanAttributes: ReadonlyArray<readonly [string, unknown]>
   readonly transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
+  readonly borrower: Borrower | undefined
 
   withConnection<XA, E>(
     operation: string,
@@ -1257,7 +1273,8 @@ const makeUnsafe = <A = Row>(
   acquirer: Acquirer,
   compiler: Compiler,
   spanAttributes: ReadonlyArray<readonly [string, unknown]>,
-  transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
+  transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined,
+  borrower: Borrower | undefined
 ): StatementImpl<A> => {
   const self = Object.create(StatementProto)
   self.segments = segments
@@ -1265,13 +1282,14 @@ const makeUnsafe = <A = Row>(
   self.compiler = compiler
   self.spanAttributes = spanAttributes
   self.transformRows = transformRows
+  self.borrower = borrower
   return self
 }
 
 // TODO: figure out why these diagnostics are emitted
 const StatementProto: Omit<
   StatementImpl<any>,
-  "segments" | "acquirer" | "compiler" | "spanAttributes" | "transformRows"
+  "segments" | "acquirer" | "compiler" | "spanAttributes" | "transformRows" | "borrower"
 > = {
   [FragmentTypeId]: FragmentTypeId,
   withConnection<XA, E>(
@@ -1307,14 +1325,19 @@ const StatementProto: Omit<
     withoutTransform: boolean,
     span: Tracer.Span
   ): Effect.Effect<XA, E | SqlError> {
-    return withStatement(this, span, (statement) => {
+    return withStatement(this, span, (statement, fiber) => {
       const [sql, params] = statement.compile(withoutTransform)
       for (const [key, value] of this.spanAttributes) {
         span.attribute(key, value)
       }
       span.attribute(ATTR_DB_OPERATION_NAME, operation)
       span.attribute(ATTR_DB_QUERY_TEXT, sql)
-      return Effect.scoped(Effect.flatMap(this.acquirer, (_) => f(_, sql, params)))
+      const execute = this.borrower === undefined
+        ? Effect.scoped(Effect.flatMap(this.acquirer, (_) => f(_, sql, params)))
+        : this.borrower((connection: Connection) => f(connection, sql, params))
+      return fiber.cache.tracerEnabled && fiber.getRef(SpanPropagationEnabled)
+        ? Effect.provideService(execute, Tracer.ParentSpan, span)
+        : execute
     })
   },
 
@@ -1339,14 +1362,17 @@ const StatementProto: Omit<
     return Stream.unwrap(Effect.flatMap(
       Effect.makeSpanScoped("sql.execute", { kind: "client" }),
       (span) =>
-        withStatement(self, span, (statement) => {
+        withStatement(self, span, (statement, fiber) => {
           const [sql, params] = statement.compile()
           for (const [key, value] of self.spanAttributes) {
             span.attribute(key, value)
           }
           span.attribute(ATTR_DB_OPERATION_NAME, "executeStream")
           span.attribute(ATTR_DB_QUERY_TEXT, sql)
-          return Effect.map(self.acquirer, (_) => _.executeStream(sql, params, self.transformRows))
+          const acquire = Effect.map(self.acquirer, (_) => _.executeStream(sql, params, self.transformRows))
+          return fiber.cache.tracerEnabled && fiber.getRef(SpanPropagationEnabled)
+            ? Effect.succeed(Stream.provideService(Stream.unwrap(acquire), Tracer.ParentSpan, span))
+            : acquire
         })
     ))
   },
@@ -1414,21 +1440,21 @@ const StatementProto: Omit<
 const withStatement = <A, X, E, R>(
   self: StatementImpl<A>,
   span: Tracer.Span,
-  f: (statement: StatementImpl<A>) => Effect.Effect<X, E, R>
+  f: (statement: StatementImpl<A>, fiber: Fiber.Fiber<unknown, unknown>) => Effect.Effect<X, E, R>
 ) =>
   Effect.withFiber<X, E, R>((fiber) => {
     const transform = fiber.getRef(CurrentTransformer)
     if (transform === undefined) {
-      return f(self)
+      return f(self, fiber)
     }
     return Effect.flatMap(
       transform(
         self,
-        make(self.acquirer, self.compiler, self.spanAttributes, self.transformRows),
+        make(self.acquirer, self.compiler, self.spanAttributes, self.transformRows, self.borrower),
         fiber,
         span
       ) as Effect.Effect<StatementImpl<A>>,
-      f
+      (statement) => f(statement, fiber)
     )
   })
 

package/src/unstable/workers/Transferable.ts

@@ -98,7 +98,7 @@ export const addAll = (
 export const getterAddAll = <A>(
   f: (_: A) => Iterable<globalThis.Transferable>
 ): SchemaGetter.Getter<A, A> =>
-  SchemaGetter.transformOrFail((e: A) =>
+  SchemaGetter.transformEffect((e: A) =>
     Effect.contextWith((services) => {
       const collector = Context.getOrUndefined(services, Collector)
       if (!collector) return Effect.succeed(e)

package/src/unstable/workers/Worker.ts

@@ -216,7 +216,9 @@ export const makePlatform = <W>() =>
                   },
                   deferred: fiberSet.deferred as any
                 })
-                yield* ready.await
+                // Fail fast if the worker dies before signalling readiness,
+                // and allow interruption while waiting for the handshake.
+                yield* restore(Effect.raceFirst(ready.await, FiberSet.join(fiberSet)))
                 currentPort = port
                 if (buffer.length > 0) {
                   for (const [message, transfers] of buffer) {

package/src/unstable/workflow/Activity.ts

@@ -117,6 +117,13 @@ export interface AnyWithProps {
  * Creates a workflow activity from an effect, using the provided schemas to
  * encode successes and failures for durable execution.
  *
+ * **Gotchas**
+ *
+ * Only completed activity results are memoized. If the activity suspends while
+ * awaiting child workflows or a durable clock, its body runs again when the
+ * parent workflow replays. Side effects before the suspension can repeat;
+ * make those side effects idempotent.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -190,15 +197,19 @@ const retryOnInterrupt = (
   name: string,
   policy: Schedule.Schedule<any, Cause.Cause<unknown>> = interruptRetryPolicy
 ) =>
-<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
-  effect.pipe(
-    Effect.sandbox,
-    Effect.retry(policy),
-    Effect.catch((cause) => {
-      if (!Cause.hasInterrupts(cause)) return Effect.failCause(cause)
-      return Effect.die(`Activity "${name}" interrupted and retry attempts exhausted`)
-    })
-  )
+<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | WorkflowInstance> =>
+  Effect.flatMap(InstanceTag, (instance) =>
+    effect.pipe(
+      Effect.sandbox,
+      // A suspension interrupts the activity body on purpose and must surface
+      // as a suspended result instead of being retried.
+      Effect.retry({ schedule: policy, while: () => !instance.suspended }),
+      Effect.catch((cause) =>
+        Cause.hasInterrupts(cause) && !instance.suspended
+          ? Effect.die(`Activity "${name}" interrupted and retry attempts exhausted`)
+          : Effect.failCause(cause)
+      )
+    ))
 
 /**
  * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for

package/src/unstable/workflow/DurableClock.ts

@@ -93,7 +93,7 @@ export const sleep: (
     return
   }
 
-  const inMemoryThreshold = options.inMemoryThreshold
+  const inMemoryThreshold = options.inMemoryThreshold !== undefined
     ? Duration.fromInputUnsafe(options.inMemoryThreshold)
     : defaultInMemoryThreshold
 

package/src/unstable/workflow/DurableDeferred.ts

@@ -192,6 +192,8 @@ export const into: {
     | WorkflowInstance
     | Success["DecodingServices"]
     | Error["DecodingServices"]
+    | Success["EncodingServices"]
+    | Error["EncodingServices"]
   >
   /**
    * Runs an effect and records its exit into the durable deferred, resuming
@@ -211,6 +213,8 @@ export const into: {
     | WorkflowInstance
     | Success["DecodingServices"]
     | Error["DecodingServices"]
+    | Success["EncodingServices"]
+    | Error["EncodingServices"]
   >
 } = dual(
   2,
@@ -225,6 +229,8 @@ export const into: {
     | WorkflowInstance
     | Success["DecodingServices"]
     | Error["DecodingServices"]
+    | Success["EncodingServices"]
+    | Error["EncodingServices"]
   > =>
     Effect.contextWith(
       (context: Context.Context<WorkflowEngine | WorkflowInstance>) => {

package/src/unstable/workflow/DurableQueue.ts

@@ -8,6 +8,14 @@
  * records the handler's `Exit` through that token so the original workflow can
  * continue with the typed success or error.
  *
+ * Delivery is at-least-once: a crash between handler success and the
+ * acknowledgement redelivers the item, so handlers must be idempotent. When an
+ * item exhausts its persisted queue attempts it is dead-lettered: the
+ * `DurableDeferred` never resolves and the workflow stays parked until the
+ * item is requeued out of band, while the id-based de-duplication prevents
+ * replays from resurrecting the failed item. Deployments should run
+ * `PersistedQueue.layerCleanup` in one instance to prune old completed items.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"