stuff

Author: maxdml

docs/golang/reference/dbos-context.md

@@ -4,13 +4,14 @@ title: DBOS Context
 pagination_prev: null
 ---
 
-A DBOS Context is at the center of a DBOS-enabled application. Use it to register [workflows](./workflow-tutorial.md), [queues](./queue-tutorial.md) and perform [workflow management](./workflow-management.md) tasks.
+A DBOS Context is at the center of a DBOS-enabled application. Use it to register [workflows](../tutorials/workflow-tutorial.md), [queues](../tutorials/queue-tutorial.md) and perform [workflow management](../tutorials/workflow-management.md) tasks.
 
-[`DBOSContext`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#DBOSContext) extends Go's [`context.Context`](https://pkg.go.dev/context#Context) interface and carries essential state across workflow execution. Workflows and steps receive a new `DBOSContext` spun out of the root `DBOSContext` you manage. In addition, a `DBOSContext` can be used to set [workflow timeouts](./workflow-tutorial.md#workflow-timeouts).
+`DBOSContext` extends Go's [`context.Context`](https://pkg.go.dev/context#Context) interface and carries essential state across workflow execution. Workflows and steps receive a new `DBOSContext` spun out of the root `DBOSContext` you manage. In addition, a `DBOSContext` can be used to set [workflow timeouts](../tutorials/workflow-tutorial.md#workflow-timeouts).
 
+## Lifecycle
 ### Initialization
 
-You can create a DBOS context using [`NewDBOSContext`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#NewDBOSContext), which takes a [`Config`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#Config) object where `AppName` and `DatabaseURL` are mandatory.
+You can create a DBOS context using `NewDBOSContext`, which takes a `Config` object where `AppName` and `DatabaseURL` are mandatory.
 
 ```go
 func NewDBOSContext(inputConfig Config) (DBOSContext, error)
@@ -49,8 +50,8 @@ DBOSContext.Launch() error
 
 Launch the following resources managed by a `DBOSContext`:
 - A [system database connection pool](../../explanations/system-tables.md)
-- A [workflow scheduler](./workflow-tutorial.md#scheduled-workflows)
-- A [workflow queue runner](./queue-tutorial.md)
+- A [workflow scheduler](../tutorials/workflow-tutorial.md#scheduled-workflows)
+- A [workflow queue runner](../tutorials/queue-tutorial.md)
 - (Optionally) an admin server
 - (Optionally) a conductor connection
 
@@ -66,14 +67,15 @@ Gracefully shutdown the DBOS runtime, waiting for workflows to complete and clea
 **Parameters:**
 - **timeout**: The time to wait for workflows to complete. After the timeout elapses, execution of incomplete workflows is terminated (the workflows may then be recovered by other processes).
 
+## Context management
 
 ### WithTimeout
 
 ```go
 func WithTimeout(ctx DBOSContext, timeout time.Duration) (DBOSContext, context.CancelFunc)
 ```
 
-WithTimeout returns a copy of the DBOS context with a timeout. The returned context will be canceled after the specified duration. See [workflow timeouts](./workflow-tutorial.md#workflow-timeouts) for usage.
+WithTimeout returns a copy of the DBOS context with a timeout. The returned context will be canceled after the specified duration. See [workflow timeouts](../tutorials/workflow-tutorial.md#workflow-timeouts) for usage.
 
 ### WithoutCancel
 
@@ -99,6 +101,7 @@ func GetStepID(ctx DBOSContext) (int, error)
 
 GetStepID retrieves the current step ID from the context if called within a DBOS workflow. Returns -1 and an error if not called from within a workflow context.
 
+## Context metadata
 ### GetApplicationVersion
 
 ```go

docs/golang/reference/methods.md

@@ -288,16 +288,23 @@ Resume a workflow. This immediately starts it from its last completed step. You
 ### ForkWorkflow
 
 ```go
-func ForkWorkflow[R any](ctx DBOSContext, workflowID string, startStep int, opts ...WorkflowOptions) (*WorkflowHandle[R], error)
+func ForkWorkflow[R any](ctx DBOSContext, input ForkWorkflowInput) (WorkflowHandle[R], error)
 ```
 
 Start a new execution of a workflow from a specific step. The input step ID (`startStep`) must match the step number of the step returned by workflow introspection. The specified `startStep` is the step from which the new workflow will start, so any steps whose ID is less than `startStep` will not be re-executed.
 
 **Parameters:**
 - **ctx**: The DBOS context.
-- **workflowID**: The ID of the workflow to fork.
-- **startStep**: The ID of the step from which to start the forked workflow.
-- **opts**: Optional workflow configuration options (documented [here](./workflows-steps.md#dbosrunworkflow)).
+- **input**: A `ForkWorkflowInput` struct where `OriginalWorkflowID` is mandatory.
+
+```go
+type ForkWorkflowInput struct {
+    OriginalWorkflowID string // Required: The UUID of the original workflow to fork from
+    ForkedWorkflowID   string // Optional: Custom workflow ID for the forked workflow (auto-generated if empty)
+    StartStep          uint   // Optional: Step to start the forked workflow from (default: 0)
+    ApplicationVersion string // Optional: Application version for the forked workflow (inherits from original if empty)
+}
+```
 
 ### Workflow Status
 

docs/golang/tutorials/queue-tutorial.md

@@ -7,14 +7,14 @@ toc_max_heading_level: 3
 You can use queues to run many workflows at once with managed concurrency.
 Queues provide _flow control_, letting you manage how many workflows run at once or how often workflows are started.
 
-To create a queue, use [`NewWorkflowQueue`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#NewWorkflowQueue)
+To create a queue, use [`NewWorkflowQueue`](../reference/queues#newworkflowqueue)
 
 ```go
 queue := dbos.NewWorkflowQueue(dbosContext, "example_queue")
 ```
 
-You can then enqueue any workflow using [`WithQueue`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithQueue) when calling `RunWorkflow`.
-Enqueuing a function submits it for execution and returns a [handle](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WorkflowHandle) to it.
+You can then enqueue any workflow using [`WithQueue`](../reference/workflows-steps#withqueue) when calling `RunWorkflow`.
+Enqueuing a function submits it for execution and returns a [handle](../reference/workflows-steps#workflowhandle) to it.
 Queued tasks are started in first-in, first-out (FIFO) order.
 
 ```go
@@ -144,7 +144,7 @@ Rate limits are especially useful when working with a rate-limited API, such as
 
 ### Deduplication
 
-You can set a deduplication ID for an enqueued workflow using [`WithDeduplicationID`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithDeduplicationID) when calling `RunWorkflow`.
+You can set a deduplication ID for an enqueued workflow using [`WithDeduplicationID`](../reference/workflows-steps#withdeduplicationid) when calling `RunWorkflow`.
 At any given time, only one workflow with a specific deduplication ID can be enqueued in the specified queue.
 If a workflow with a deduplication ID is currently enqueued or actively executing (status `ENQUEUED` or `PENDING`), subsequent workflow enqueue attempts with the same deduplication ID in the same queue will return an error.
 
@@ -183,9 +183,9 @@ func example(dbosContext dbos.DBOSContext, queue dbos.WorkflowQueue) error {
 
 ### Priority
 
-You can set a priority for an enqueued workflow using [`WithPriority`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithPriority) when calling `RunWorkflow`.
+You can set a priority for an enqueued workflow using [`WithPriority`](../reference/workflows-steps#withpriority) when calling `RunWorkflow`.
 Workflows with the same priority are dequeued in **FIFO (first in, first out)** order. Priority values can range from `1` to `2,147,483,647`, where **a low number indicates a higher priority**.
-If using priority, you must set [`WithPriorityEnabled`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithPriorityEnabled) on your queue.
+If using priority, you must set [`WithPriorityEnabled`](../reference/queues#withpriorityenabled) on your queue.
 
 :::tip
 Workflows without assigned priorities have the highest priority and are dequeued before workflows with assigned priorities.

docs/golang/tutorials/step-tutorial.md

@@ -6,7 +6,7 @@ title: Steps
 When using DBOS workflows, you should call any function that performs complex operations or accesses external APIs or services as a _step_.
 If a workflow is interrupted, upon restart it automatically resumes execution from the **last completed step**.
 
-You can use [`RunAsStep`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#RunAsStep) to call a function as a step.
+You can use [`RunAsStep`](../reference/workflows-steps#runasstep) to call a function as a step.
 For a function to be used as a step, it should return a serializable ([gob-encodable](https://pkg.go.dev/encoding/gob)) value and an error and have this signature:
 
 ```go
@@ -50,11 +50,11 @@ This is useful for automatically handling transient failures, like making reques
 Retries are configurable through step options that can be passed to `RunAsStep`.
 
 Available retry configuration options include:
-- [`WithStepName`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithStepName) - Custom name for the step (default to the [Go runtime reflection value](https://pkg.go.dev/runtime#FuncForPC))
-- [`WithStepMaxRetries`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithStepMaxRetries) - Maximum number of times this step is automatically retried on failure (default 0)
-- [`WithMaxInterval`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithMaxInterval) - Maximum delay between retries (default 5s)
-- [`WithBackoffFactor`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithBackoffFactor) - Exponential backoff multiplier between retries (default 2.0)
-- [`WithBaseInterval`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#WithBaseInterval) - Initial delay between retries (default 100ms)
+- [`WithStepName`](../reference/workflows-steps#withstepname) - Custom name for the step (default to the [Go runtime reflection value](https://pkg.go.dev/runtime#FuncForPC))
+- [`WithStepMaxRetries`](../reference/workflows-steps#withstepmaxretries) - Maximum number of times this step is automatically retried on failure (default 0)
+- [`WithMaxInterval`](../reference/workflows-steps#withmaxinterval) - Maximum delay between retries (default 5s)
+- [`WithBackoffFactor`](../reference/workflows-steps#withbackofffactor) - Exponential backoff multiplier between retries (default 2.0)
+- [`WithBaseInterval`](../reference/workflows-steps#withbaseinterval) - Initial delay between retries (default 100ms)
 
 For example, let's configure this step to retry failures (such as if `example.com` is temporarily down) up to 10 times:
 

docs/golang/tutorials/testing.md

@@ -4,12 +4,40 @@ title: Testing & Mocking
 ---
 
 
-[`DBOSContext`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#DBOSContext) is a fully mockable interface, which you manually mock, or can generate mocks using tools like [mockery](https://github.com/vektra/mockery).
+[`DBOSContext`](../reference/dbos-context) is a fully mockable interface, which you manually mock, or can generate mocks using tools like [mockery](https://github.com/vektra/mockery).
+
+<details>
+<summary>Sample .mockery.yml configuration</summary>
+
+You can use this configuration file to generate mocks by running `mockery`:
+
+```yaml
+all: false
+dir: './mocks'
+filename: '{{.InterfaceName}}_mock.go'
+force-file-write: true
+formatter: goimports
+include-auto-generated: false
+log-level: info
+structname: 'Mock{{.InterfaceName}}'
+pkgname: 'mocks'
+recursive: false
+require-template-schema-exists: true
+template: testify
+template-schema: '{{.Template}}.schema.json'
+packages:
+  github.com/dbos-inc/dbos-transact-golang/dbos:
+    interfaces:
+      DBOSContext:
+      WorkflowHandle:
+```
+
+</details>
 
 Here is an example workflow which:
 - Calls a step
 - Spawns a child workflow
-- Calls a workflow management operation, [ListWorkflows](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#ListWorkflows)
+- Calls a workflow management operation, [ListWorkflows](../reference/methods#listworkflows)
 
 
 ```go
@@ -89,13 +117,14 @@ func workflow(ctx dbos.DBOSContext, i int) ([]dbos.WorkflowStatus, error) {
 }
 
 func TestMocks(t *testing.T) {
+    // Create a mock DBOSContext
     mockCtx := mocks.NewMockDBOSContext(t)
 
     // Step
     mockCtx.On("RunAsStep", mockCtx, mock.Anything, mock.Anything).Return(1, nil)
 
     // Child workflow
-    mockChildHandle := mocks.NewMockWorkflowHandle[any](t)
+    mockChildHandle := mocks.NewMockWorkflowHandle[any](t) // mock WorkflowHandle
     mockCtx.On("RunWorkflow", mockCtx, mock.Anything, 2, mock.Anything).Return(mockChildHandle, nil).Once()
     mockChildHandle.On("GetResult").Return(1, nil)
 

docs/golang/tutorials/workflow-management.md

@@ -7,7 +7,7 @@ You can view and manage your durable workflow executions via a web UI ([self-hos
 
 ## Listing Workflows
 
-You can list your application's workflows programmatically via [`ListWorkflows`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#ListWorkflows).
+You can list your application's workflows programmatically via [`ListWorkflows`](../reference/methods#listworkflows).
 
 You can also view a searchable and expandable list of your application's workflows from its page on the DBOS Console (either [self-hosted](../../production/self-hosting/workflow-management.md) or on [DBOS Cloud](../../production/dbos-cloud/workflow-management.md)).
 
@@ -22,14 +22,14 @@ For example, here is the graph of a workflow that processes multiple tasks concu
 
 ## Cancelling Workflows
 
-You can cancel the execution of a workflow from the web UI or programmatically via [`CancelWorkflow`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#CancelWorkflow).
+You can cancel the execution of a workflow from the web UI or programmatically via [`CancelWorkflow`](../reference/methods#cancelworkflow).
 
 If the workflow is currently executing, cancelling it preempts its execution (interrupting it at the beginning of its next step).
 If the workflow is enqueued, cancelling removes it from the queue.
 
 ## Resuming Workflows
 
-You can resume a workflow from its last completed step from the web UI or programmatically via [`ResumeWorkflow`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#ResumeWorkflow).
+You can resume a workflow from its last completed step from the web UI or programmatically via [`ResumeWorkflow`](../reference/methods#resumeworkflow).
 
 You can use this to resume workflows that are cancelled or that have exceeded their maximum recovery attempts.
 You can also use this to start an enqueued workflow immediately, bypassing its queue.
@@ -41,7 +41,7 @@ When you fork a workflow, DBOS generates a new workflow with a new workflow ID,
 
 Forking a workflow is useful for recovering from outages in downstream services (by forking from the step that failed after the outage is resolved) or for "patching" workflows that failed due to a bug in a previous application version (by forking from the bugged step to an appliation version on which the bug is fixed).
 
-You can fork a workflow programmatically using [`ForkWorkflow`](https://pkg.go.dev/github.com/dbos-inc/dbos-transact-golang/dbos#ForkWorkflow).
+You can fork a workflow programmatically using [`ForkWorkflow`](../reference/methods#forkworkflow).
 You can also fork a workflow from a step from the web UI by clicking on that step in the workflow's graph visualization:
 
 <img src={require('@site/static/img/workflow-management/workflow-fork.png').default} alt="Workflow List" width="800" className="custom-img"/>