doc.go + a few scope updates

Author: maxdml

README.md

@@ -12,9 +12,6 @@
 #### [Documentation](https://docs.dbos.dev/)   •    [Examples](https://docs.dbos.dev/examples)   •   [Github](https://github.com/dbos-inc)
 </div>
 
-#### This Golang version of DBOS Transact is in Alpha!
-For production ready Transacts, check our [Python](https://github.com/dbos-inc/dbos-transact-py) and [TypeScript](https://github.com/dbos-inc/dbos-transact-ts) versions.
-
 ---
 
 ## What is DBOS?
@@ -74,7 +71,7 @@ func stepTwo(ctx context.Context) (string, error) {
 }
 func main() {
     // Initialize a DBOS context
-	ctx, err := dbos.NewDBOSContext(dbos.Config{
+	ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
 		DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
 		AppName:     "myapp",
 	})
@@ -147,7 +144,7 @@ func task(ctx dbos.DBOSContext, i int) (int, error) {
 
 func main() {
     // Initialize a DBOS context
-    ctx, err := dbos.NewDBOSContext(dbos.Config{
+    ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
         DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
         AppName:     "myapp",
     })

cmd/dbos/cli_integration_test.go

@@ -693,6 +693,11 @@ func buildCLI(t *testing.T) string {
 	// Delete any existing binary before building
 	os.Remove(cliPath)
 
+	// Install Transact from main
+	installCmd := exec.Command("go", "get", "github.com/dbos-inc/dbos-transact-golang@main")
+	installOutput, installErr := installCmd.CombinedOutput()
+	require.NoError(t, installErr, "Failed to install Transact: %s", string(installOutput))
+
 	// Build the CLI from the cmd directory
 	buildCmd := exec.Command("go", "build", "-o", "dbos-cli-test", ".")
 	buildCmd.Dir = cmdDir

cmd/dbos/cli_test_app.go.test

@@ -86,7 +86,7 @@ func ScheduledWorkflow(ctx dbos.DBOSContext, scheduledTime time.Time) (string, e
 func main() {
 	// Create DBOS context
 	var err error
-	dbosCtx, err = dbos.NewDBOSContext(dbos.Config{
+	dbosCtx, err = dbos.NewDBOSContext(context.Background(), dbos.Config{
 		DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
 		AppName:     "cli-test",
 		AdminServer: true,

dbos/conductor.go

@@ -55,14 +55,14 @@ type Conductor struct {
 	pingCancel context.CancelFunc
 }
 
-// Launch starts the conductor main goroutine
-func (c *Conductor) Launch() {
+// launch starts the conductor main goroutine
+func (c *Conductor) launch() {
 	c.logger.Info("Launching conductor")
 	c.wg.Add(1)
 	go c.run()
 }
 
-func NewConductor(dbosCtx *dbosContext, config ConductorConfig) (*Conductor, error) {
+func newConductor(dbosCtx *dbosContext, config ConductorConfig) (*Conductor, error) {
 	if config.apiKey == "" {
 		return nil, fmt.Errorf("conductor API key is required")
 	}
@@ -96,7 +96,7 @@ func NewConductor(dbosCtx *dbosContext, config ConductorConfig) (*Conductor, err
 	return c, nil
 }
 
-func (c *Conductor) Shutdown(timeout time.Duration) {
+func (c *Conductor) shutdown(timeout time.Duration) {
 	c.stopOnce.Do(func() {
 		if c.pingCancel != nil {
 			c.pingCancel()

dbos/conductor_test.go

@@ -316,7 +316,7 @@ func TestConductorReconnection(t *testing.T) {
 		}
 
 		// Create conductor
-		conductor, err := NewConductor(dbosCtx, config)
+		conductor, err := newConductor(dbosCtx, config)
 		require.NoError(t, err)
 
 		// Speed up intervals for testing
@@ -325,7 +325,7 @@ func TestConductorReconnection(t *testing.T) {
 		conductor.reconnectWait = 100 * time.Millisecond
 
 		// Launch conductor
-		conductor.Launch()
+		conductor.launch()
 
 		// Wait for initial connection
 		assert.True(t, mockServer.waitForConnection(5*time.Second), "Should establish initial connection")
@@ -406,7 +406,7 @@ func TestConductorReconnection(t *testing.T) {
 		}
 
 		// Create conductor
-		conductor, err := NewConductor(dbosCtx, config)
+		conductor, err := newConductor(dbosCtx, config)
 		require.NoError(t, err)
 
 		// Speed up intervals for testing
@@ -415,7 +415,7 @@ func TestConductorReconnection(t *testing.T) {
 		conductor.reconnectWait = 100 * time.Millisecond
 
 		// Launch conductor
-		conductor.Launch()
+		conductor.launch()
 
 		// Wait for initial connection
 		assert.True(t, mockServer.waitForConnection(5*time.Second), "Should establish initial connection")
@@ -494,7 +494,7 @@ func TestConductorReconnection(t *testing.T) {
 		}
 
 		// Create conductor
-		conductor, err := NewConductor(dbosCtx, config)
+		conductor, err := newConductor(dbosCtx, config)
 		require.NoError(t, err)
 
 		// Speed up intervals for testing
@@ -503,7 +503,7 @@ func TestConductorReconnection(t *testing.T) {
 		conductor.reconnectWait = 100 * time.Millisecond
 
 		// Launch conductor
-		conductor.Launch()
+		conductor.launch()
 
 		// Wait for initial connection
 		assert.True(t, mockServer.waitForConnection(5*time.Second), "Should establish initial connection")
@@ -587,7 +587,7 @@ func TestConductorReconnection(t *testing.T) {
 		}
 
 		// Create conductor
-		conductor, err := NewConductor(dbosCtx, config)
+		conductor, err := newConductor(dbosCtx, config)
 		require.NoError(t, err)
 
 		// Speed up intervals for testing
@@ -596,7 +596,7 @@ func TestConductorReconnection(t *testing.T) {
 		conductor.reconnectWait = 100 * time.Millisecond
 
 		// Launch conductor
-		conductor.Launch()
+		conductor.launch()
 
 		// Wait for initial connection
 		assert.True(t, mockServer.waitForConnection(5*time.Second), "Should establish initial connection")

dbos/dbos.go

@@ -1,8 +1,3 @@
-// Package dbos provides a Go SDK for building durable applications with DBOS Transact.
-//
-// DBOS Transact enables developers to write resilient distributed applications using workflows
-// and steps backed by PostgreSQL. All application state is automatically persisted, providing
-// exactly-once execution guarantees and automatic recovery from failures.
 package dbos
 
 import (
@@ -44,7 +39,6 @@ type Config struct {
 	Context            context.Context // User Context
 }
 
-// processConfig enforces mandatory fields and applies defaults.
 func processConfig(inputConfig *Config) (*Config, error) {
 	// First check required fields
 	if len(inputConfig.DatabaseURL) == 0 {
@@ -103,8 +97,8 @@ type DBOSContext interface {
 	context.Context
 
 	// Context Lifecycle
-	Launch() error                  // Launch the DBOS runtime including system database, queues, admin server, and workflow recovery
-	Shutdown(timeout time.Duration) // Gracefully shutdown all DBOS runtime components with ordered cleanup sequence
+	Launch() error                  // Launch the DBOS runtime including system database, queues, and perform a workflow recovery for the local executor
+	Shutdown(timeout time.Duration) // Gracefully shutdown all DBOS resources
 
 	// Workflow operations
 	RunAsStep(_ DBOSContext, fn StepFunc, opts ...StepOption) (any, error)                                      // Execute a function as a durable step within a workflow
@@ -167,7 +161,6 @@ type dbosContext struct {
 	logger *slog.Logger
 }
 
-// Implement contex.Context interface methods
 func (c *dbosContext) Deadline() (deadline time.Time, ok bool) {
 	return c.ctx.Deadline()
 }
@@ -209,7 +202,7 @@ func WithValue(ctx DBOSContext, key, val any) DBOSContext {
 }
 
 // WithoutCancel returns a copy of the DBOS context that is not canceled when the parent context is canceled.
-// This is useful for operations that should continue even after a workflow is cancelled.
+// This can be used to detach a child workflow.
 // No-op if the provided context is not a concrete dbos.dbosContext.
 func WithoutCancel(ctx DBOSContext) DBOSContext {
 	if ctx == nil {
@@ -275,17 +268,16 @@ func (c *dbosContext) GetApplicationID() string {
 }
 
 // NewDBOSContext creates a new DBOS context with the provided configuration.
-// The context must be launched with Launch() before use and should be shut down with Shutdown().
-// This function initializes the DBOS system database, sets up the queue sub-system,
-// and prepares the workflow registry.
+// The context must be launched with Launch() for workflow execution and should be shut down with Shutdown().
+// This function initializes the DBOS system database, sets up the queue sub-system, and prepares the workflow registry.
 //
 // Example:
 //
 //	config := dbos.Config{
 //	    DatabaseURL: "postgres://user:pass@localhost:5432/dbname",
 //	    AppName:     "my-app",
 //	}
-//	ctx, err := dbos.NewDBOSContext(config)
+//	ctx, err := dbos.NewDBOSContext(context.Background(), config)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -355,7 +347,7 @@ func NewDBOSContext(ctx context.Context, inputConfig Config) (DBOSContext, error
 			apiKey:  config.ConductorAPIKey,
 			appName: config.AppName,
 		}
-		conductor, err := NewConductor(initExecutor, conductorConfig)
+		conductor, err := newConductor(initExecutor, conductorConfig)
 		if err != nil {
 			return nil, newInitializationError(fmt.Sprintf("failed to initialize conductor: %v", err))
 		}
@@ -367,9 +359,8 @@ func NewDBOSContext(ctx context.Context, inputConfig Config) (DBOSContext, error
 }
 
 // Launch initializes and starts the DBOS runtime components including the system database,
-// admin server (if configured), queue runner, workflow scheduler, and performs recovery
-// of any pending workflows on this executor. This method must be called before using the DBOS context
-// for workflow execution and should only be called once.
+// admin server (if enabled), queue runner, workflow scheduler, and performs recovery
+// of any pending workflows on this executor.
 //
 // Returns an error if the context is already launched or if any component fails to start.
 func (c *dbosContext) Launch() error {
@@ -380,7 +371,7 @@ func (c *dbosContext) Launch() error {
 	// Start the system database
 	c.systemDB.launch(c)
 
-	// Start the admin server if configured
+	// Start the admin server if enabled
 	if c.config.AdminServer {
 		adminServer := newAdminServer(c, c.config.AdminServerPort)
 		err := adminServer.Start()
@@ -407,7 +398,7 @@ func (c *dbosContext) Launch() error {
 
 	// Start the conductor if it has been initialized
 	if c.conductor != nil {
-		c.conductor.Launch()
+		c.conductor.launch()
 		c.logger.Debug("Conductor started")
 	}
 
@@ -459,7 +450,6 @@ func (c *dbosContext) Shutdown(timeout time.Duration) {
 	case <-done:
 		c.logger.Debug("All workflows completed")
 	case <-time.After(timeout):
-		// For now just log a warning: eventually we might want Cancel to return an error.
 		c.logger.Warn("Timeout waiting for workflows to complete", "timeout", timeout)
 	}
 
@@ -491,7 +481,7 @@ func (c *dbosContext) Shutdown(timeout time.Duration) {
 	// Shutdown the conductor
 	if c.conductor != nil {
 		c.logger.Debug("Shutting down conductor")
-		c.conductor.Shutdown(timeout)
+		c.conductor.shutdown(timeout)
 	}
 
 	// Shutdown the admin server

dbos/doc.go

@@ -0,0 +1,118 @@
+// Package dbos provides lightweight durable workflow orchestration with Postgres.
+//
+// DBOS Transact enables developers to write resilient distributed applications using workflows
+// and steps backed by PostgreSQL. All application state is automatically persisted, providing
+// exactly-once execution guarantees and automatic recovery from failures.
+//
+// # Getting Started
+//
+// Create a DBOS context to start building durable applications:
+//
+//	dbosContext, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
+//	    AppName:     "my-app",
+//	    DatabaseURL: os.Getenv("DATABASE_URL"),
+//	})
+//	defer dbosContext.Shutdown(5 * time.Second)
+//
+//	// Register workflows before launching
+//	dbos.RegisterWorkflow(dbosContext, myWorkflow)
+//
+//	// Launch the context to start processing
+//	err = dbosContext.Launch()
+//
+// # Workflows
+//
+// Workflows provide durable execution, automatically resuming from the last completed step
+// after any failure. Write workflows as normal Go functions that take a DBOSContext and
+// return serializable values:
+//
+//	func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+//	    // Workflow logic here
+//	    result, err := dbos.RunAsStep(ctx, someOperation)
+//	    if err != nil {
+//	        return "", err
+//	    }
+//	    return result, nil
+//	}
+//
+// Key workflow features:
+//   - Automatic recovery: Workflows resume from the last completed step after crashes
+//   - Idempotency: Assign workflow IDs to ensure operations run exactly once
+//   - Determinism: Workflow functions must be deterministic; use steps for non-deterministic operations
+//   - Timeouts: Set durable timeouts that persist across restarts
+//   - Events & messaging: Workflows can emit events and receive messages for coordination
+//
+// # Steps
+//
+// Steps wrap non-deterministic operations (API calls, random numbers, current time) within workflows.
+// If a workflow is interrupted, it resumes from the last completed step:
+//
+//	func fetchData(ctx context.Context) (string, error) {
+//	    resp, err := http.Get("https://api.example.com/data")
+//	    // Handle response...
+//	    return data, nil
+//	}
+//
+//	func workflow(ctx dbos.DBOSContext, input string) (string, error) {
+//	    data, err := dbos.RunAsStep(ctx, fetchData,
+//	        dbos.WithStepName("fetchData"),
+//	        dbos.WithStepMaxRetries(3))
+//	    if err != nil {
+//	        return "", err
+//	    }
+//	    return data, nil
+//	}
+//
+// Steps support configurable retries with exponential backoff for handling transient failures.
+//
+// # Queues
+//
+// Queues manage workflow concurrency and rate limiting:
+//
+//	queue := dbos.NewWorkflowQueue(dbosContext, "task_queue",
+//	    dbos.WithWorkerConcurrency(5),    // Max 5 concurrent workflows per process
+//	    dbos.WithRateLimiter(&dbos.RateLimiter{
+//	        Limit:  100,
+//	        Period: 60 * time.Second,  // 100 workflows per 60 seconds
+//	    }))
+//
+//	// Enqueue workflows with optional deduplication and priority
+//	handle, err := dbos.RunWorkflow(ctx, taskWorkflow, input,
+//	    dbos.WithQueue(queue.Name),
+//	    dbos.WithDeduplicationID("unique-id"),
+//	    dbos.WithPriority(10))
+//
+// # Workflow Management
+//
+// DBOS provides comprehensive workflow management capabilities:
+//
+//	// List workflows
+//	workflows, err := dbos.ListWorkflows(ctx)
+//
+//	// Cancel a running workflow
+//	err = dbos.CancelWorkflow(ctx, workflowID)
+//
+//	// Resume a cancelled workflow
+//	err = dbos.ResumeWorkflow(ctx, workflowID)
+//
+//	// Fork a workflow from a specific step
+//	newID, err := dbos.ForkWorkflow(ctx, originalID, stepNumber)
+//
+// Workflows can also be visualized and managed through the DBOS Console web UI.
+//
+// # Testing
+//
+// DBOSContext is fully mockable for unit testing:
+//
+//	func TestWorkflow(t *testing.T) {
+//	    mockCtx := mocks.NewMockDBOSContext(t)
+//	    mockCtx.On("RunAsStep", mockCtx, mock.Anything, mock.Anything).Return("result", nil)
+//
+//	    result, err := myWorkflow(mockCtx, "input")
+//	    assert.NoError(t, err)
+//	    assert.Equal(t, "expected", result)
+//	}
+//
+// For detailed documentation and examples, see https://docs.dbos.dev/golang
+
+package dbos