Toward executor objects (#44)

This PR:
- Encapsulate the state of a "DBOS executor" in an interface exported by
the package. This must be typeless, hence:
- Preserves compile-time type checking by exposing package-level methods
that accept a DBOS executor interface
- Attempts to keep the programming interface reasonable by creating a
`DBOSContext` type which holds both DBOS executor functionalities and
extends the native `context.Context` interface.

The mirror functions are made with the same signature so it is more
intuitive for users when mocking.

Few things to note/improve/think about
- Workflow functions now require our `DBOSContext` instead of a
`context.Context`. This is because all operations need a context. Steps
on the other hand can accept a normal context.Context if they wish to,
and upcast it to `DBOSContext` if they need to do DBOS stuff.
- DBOSContext is local to a process. This means the user cannot expect a
context to: 1) be passed to the workflow at recovery 2) be passed to a
queued task by the queue runner. This is quite un-intuitive w.r.t native
Golang `context.Context`
- SetEvent / Send types are not greatly named
- We should find a way for library specific contexts to play together.
Right now a gin handler looks like: `func checkoutEndpoint(c
*gin.Context, dbosCtx dbos.DBOSContext, logger *logrus.Logger) {`

Another thing this PR does, on the path of improving the step interface,
is allowing users to pass step parameters through the context, using the
`WithValue` method. We'll have to improve on this as well: right now
`WithValue` does nothing if the provided interface is not a concrete
`dbosContext` (our internal struct implementing `DBOSContext`), so a
user cannot rely on this in their tests if they mock `DBOSContext`.

Immediate next PRs:
- Move logger, queue registry in DBOSContext
- Tighten usage of context to manage resources like queue runner
- Add tests running workflows inside goroutines
- Improve step UX


`DBOSContext` exposes all the DBOS methods an end-user is expected to
write in their code:

```golang
type DBOSContext interface {
	context.Context

	// Context Lifecycle
	Launch() error
	Shutdown()

	// Workflow operations
	RunAsStep(_ DBOSContext, fn StepFunc, input ...any) (any, error)
	RunAsWorkflow(_ DBOSContext, fn WorkflowFunc, input any, opts ...WorkflowOption) (WorkflowHandle[any], error)
	Send(_ DBOSContext, input WorkflowSendInputInternal) error
	Recv(_ DBOSContext, input WorkflowRecvInput) (any, error)
	SetEvent(_ DBOSContext, input WorkflowSetEventInput) error
	GetEvent(_ DBOSContext, input WorkflowGetEventInput) (any, error)
	Sleep(duration time.Duration) (time.Duration, error)
	GetWorkflowID() (string, error)

	// Workflow management
	RetrieveWorkflow(_ DBOSContext, workflowID string) (WorkflowHandle[any], error)

	// Accessors
	GetApplicationVersion() string
	GetExecutorID() string
	GetApplicationID() string
}
```

New library usage:
```golang
	dbosContext, err := dbos.NewDBOSContext(dbos.Config{
		AppName:     "widget_store_go",
		DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
	})
	if err != nil {
		logger.WithError(err).Fatal("DBOS initialization failed")
	}
	dbos.RegisterWorkflow(dbosContext, checkoutWorkflow)
	dbos.RegisterWorkflow(dbosContext, dispatchOrderWorkflow)

	err = dbosContext.Launch()
	if err != nil {
		logger.WithError(err).Fatal("DBOS service start failed")
	}
	defer dbosContext.Shutdown()
```

Starting workflows:
```golang
	handle, err := dbos.RunAsWorkflow(dbosCtx, checkoutWorkflow, "", dbos.WithWorkflowID(idempotencyKey))
```

The testing can be done as:
```golang
	dbosContextMock := mocks.NewMockDBOSContext(t)

	// Test running the wrapped workflow
	t.Run("Payment fails", func(t *testing.T) {
		wfID := "test-workflow-id"

		// Set expectations on what DBOS stuff that happens within the workflow
		dbosContextMock.On("GetWorkflowID").Return(wfID, nil)
		dbosContextMock.On("RunAsStep", dbosContextMock, mock.Anything, mock.Anything).Return(1, nil).Once()
		dbosContextMock.On("RunAsStep", dbosContextMock, mock.Anything, mock.Anything).Return(false, nil).Once()
		dbosContextMock.On("RunAsStep", dbosContextMock, mock.Anything, mock.Anything).Return("", nil).Once()
		dbosContextMock.On("SetEvent", dbosContextMock, mock.Anything).Return(nil).Once()

		res, err := checkoutWorkflow(dbosContextMock, "")
		if err != nil {
			t.Fatalf("checkout workflow failed: %v", err)
		}
		if res != "" {
			t.Fatalf("expected empty result, got %s", res)
		}

		dbosContextMock.AssertExpectations(t)
	})
```

Author: maxdml

dbos/admin_server.go

@@ -25,7 +25,7 @@ type queueMetadata struct {
 	RateLimit         *RateLimiter `json:"rateLimit,omitempty"`
 }
 
-func newAdminServer(port int) *adminServer {
+func newAdminServer(ctx *dbosContext, port int) *adminServer {
 	mux := http.NewServeMux()
 
 	// Health endpoint
@@ -50,7 +50,7 @@ func newAdminServer(port int) *adminServer {
 
 		getLogger().Info("Recovering workflows for executors", "executors", executorIDs)
 
-		handles, err := recoverPendingWorkflows(r.Context(), executorIDs)
+		handles, err := recoverPendingWorkflows(ctx, executorIDs)
 		if err != nil {
 			getLogger().Error("Error recovering workflows", "error", err)
 			http.Error(w, fmt.Sprintf("Recovery failed: %v", err), http.StatusInternalServerError)

dbos/admin_server_test.go

@@ -11,27 +11,27 @@ import (
 )
 
 func TestAdminServer(t *testing.T) {
-	databaseURL := getDatabaseURL(t)
+	databaseURL := getDatabaseURL()
 
 	t.Run("Admin server is not started by default", func(t *testing.T) {
-		// Ensure clean state
-		Shutdown()
 
-		err := Initialize(Config{
+		ctx, err := NewDBOSContext(Config{
 			DatabaseURL: databaseURL,
 			AppName:     "test-app",
 		})
 		if err != nil {
 			t.Skipf("Failed to initialize DBOS: %v", err)
 		}
-		err = Launch()
+		err = ctx.Launch()
 		if err != nil {
 			t.Skipf("Failed to initialize DBOS: %v", err)
 		}
 
 		// Ensure cleanup
 		defer func() {
-			Shutdown()
+			if ctx != nil {
+				ctx.Shutdown()
+			}
 		}()
 
 		// Give time for any startup processes
@@ -45,46 +45,48 @@ func TestAdminServer(t *testing.T) {
 		}
 
 		// Verify the DBOS executor doesn't have an admin server instance
-		if dbos == nil {
+		if ctx == nil {
 			t.Fatal("Expected DBOS instance to be created")
 		}
 
-		if dbos.adminServer != nil {
+		exec := ctx.(*dbosContext)
+		if exec.adminServer != nil {
 			t.Error("Expected admin server to be nil when not configured")
 		}
 	})
 
 	t.Run("Admin server endpoints", func(t *testing.T) {
-		Shutdown()
-
 		// Launch DBOS with admin server once for all endpoint tests
-		err := Initialize(Config{
+		ctx, err := NewDBOSContext(Config{
 			DatabaseURL: databaseURL,
 			AppName:     "test-app",
 			AdminServer: true,
 		})
 		if err != nil {
 			t.Skipf("Failed to initialize DBOS with admin server: %v", err)
 		}
-		err = Launch()
+		err = ctx.Launch()
 		if err != nil {
 			t.Skipf("Failed to initialize DBOS with admin server: %v", err)
 		}
 
 		// Ensure cleanup
 		defer func() {
-			Shutdown()
+			if ctx != nil {
+				ctx.Shutdown()
+			}
 		}()
 
 		// Give the server a moment to start
 		time.Sleep(100 * time.Millisecond)
 
 		// Verify the DBOS executor has an admin server instance
-		if dbos == nil {
+		if ctx == nil {
 			t.Fatal("Expected DBOS instance to be created")
 		}
 
-		if dbos.adminServer == nil {
+		exec := ctx.(*dbosContext)
+		if exec.adminServer == nil {
 			t.Fatal("Expected admin server to be created in DBOS instance")
 		}