Contributing (#67)

- Add `CONTRIBUTING.md`
- Add licence badge in `README.md`
- Privatize a few types
- Fix package level `RetrieveWorkflow` (now calls interface
`RetrieveWorkflow`)
- Few type casting checks & a fix (in `RunAsWorkflow` we shouldn't cast
to the concrete type)
- Clean up all options names and visibility (option structs are public,
fields are private. Harmonize names across the board)

Author: maxdml

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to DBOS Transact Python
+
+Thank you for considering contributing to DBOS Transact. We welcome contributions from everyone, including bug fixes, feature enhancements, documentation improvements, or any other form of contribution.
+
+## How to Contribute
+
+To get started with DBOS Transact, please read the [README](README.md).
+
+You can contribute in many ways. Some simple ways are:
+* Use the SDK and open issues to report any bugs, questions, concern with the SDK, samples or documentation.
+* Respond to issues with advice or suggestions.
+* Participate in discussions in our [Discord](https://discord.gg/fMwQjeW5zg) channel.
+* Contribute fixes and improvement to code, samples or documentation.
+
+### To contribute code, please follow these steps:
+
+1. Fork this github repository to your own account.
+
+2. Clone the forked repository to your local machine.
+
+3. Create a branch.
+
+4. Make the necessary change to code, samples or documentation.
+
+5. Write tests.
+
+6. Commit the changes to your forked repository.
+
+7. Submit a pull request to this repository.
+In the PR description please include:
+* Description of the fix/feature.
+* Brief description of implementation.
+* Description of how you tested the fix.
+
+## Requesting features
+
+If you have a feature request or an idea for an enhancement, feel free to open an issue on GitHub. Describe the feature or enhancement you'd like to see and why it would be valuable. Discuss it with the community on the [Discord](https://discord.gg/fMwQjeW5zg) channel.
+
+## Discuss with the community
+
+If you are stuck, need help, or wondering if a certain contribution will be welcome, please ask! You can reach out to us on  [Discord](https://discord.gg/fMwQjeW5zg) or Github discussions.
+
+## Code of conduct
+
+It is important to us that contributing to DBOS will be a pleasant experience, if necessary, please refer to our [code of conduct](CODE_OF_CONDUCT.md) for participation guidelines.

README.md

@@ -4,6 +4,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/dbos-inc/dbos-transact-go)](https://goreportcard.com/report/github.com/dbos-inc/dbos-transact-go)
 [![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/dbos-inc/dbos-transact-go?sort=semver)](https://github.com/dbos-inc/dbos-transact-go/releases)
 [![Join Discord](https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/jsmC6pXGgX)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 
 # DBOS Transact: Lightweight Durable Workflow Orchestration with Postgres

dbos/admin_server.go

@@ -287,7 +287,7 @@ func newAdminServer(ctx *dbosContext, port int) *adminServer {
 			}
 		}
 
-		workflows, err := ctx.ListWorkflows(req.toListWorkflowsOptions()...)
+		workflows, err := ListWorkflows(ctx, req.toListWorkflowsOptions()...)
 		if err != nil {
 			ctx.logger.Error("Failed to list workflows", "error", err)
 			http.Error(w, fmt.Sprintf("Failed to list workflows: %v", err), http.StatusInternalServerError)
@@ -313,7 +313,7 @@ func newAdminServer(ctx *dbosContext, port int) *adminServer {
 
 		// Use ListWorkflows with the specific workflow ID filter
 		opts := []ListWorkflowsOption{WithWorkflowIDs([]string{workflowID})}
-		workflows, err := ctx.ListWorkflows(opts...)
+		workflows, err := ListWorkflows(ctx, opts...)
 		if err != nil {
 			ctx.logger.Error("Failed to get workflow", "workflow_id", workflowID, "error", err)
 			http.Error(w, fmt.Sprintf("Failed to get workflow: %v", err), http.StatusInternalServerError)
@@ -346,7 +346,7 @@ func newAdminServer(ctx *dbosContext, port int) *adminServer {
 			}
 		}
 
-		workflows, err := ctx.ListWorkflows(req.toListWorkflowsOptions()...)
+		workflows, err := ListWorkflows(ctx, req.toListWorkflowsOptions()...)
 		if err != nil {
 			ctx.logger.Error("Failed to list queued workflows", "error", err)
 			http.Error(w, fmt.Sprintf("Failed to list queued workflows: %v", err), http.StatusInternalServerError)

dbos/admin_server_test.go

@@ -44,7 +44,8 @@ func TestAdminServer(t *testing.T) {
 		// Verify the DBOS executor doesn't have an admin server instance
 		require.NotNil(t, ctx, "Expected DBOS instance to be created")
 
-		exec := ctx.(*dbosContext)
+		exec, ok := ctx.(*dbosContext)
+		require.True(t, ok, "Expected ctx to be of type *dbosContext")
 		require.Nil(t, exec.adminServer, "Expected admin server to be nil when not configured")
 	})
 

dbos/client_test.go

@@ -68,12 +68,8 @@ func TestEnqueue(t *testing.T) {
 
 	t.Run("EnqueueAndGetResult", func(t *testing.T) {
 		// Client enqueues a task using the new Enqueue method
-		handle, err := Enqueue[wfInput, string](clientCtx, GenericEnqueueOptions[wfInput]{
-			WorkflowName:       "ServerWorkflow",
-			QueueName:          queue.Name,
-			WorkflowInput:      wfInput{Input: "test-input"},
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle, err := Enqueue[wfInput, string](clientCtx, queue.Name, "ServerWorkflow", wfInput{Input: "test-input"},
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err)
 
 		// Verify we got a polling handle
@@ -102,12 +98,8 @@ func TestEnqueue(t *testing.T) {
 		customWorkflowID := "custom-client-workflow-id"
 
 		// Client enqueues a task with a custom workflow ID
-		_, err := Enqueue[wfInput, string](clientCtx, GenericEnqueueOptions[wfInput]{
-			WorkflowName:  "ServerWorkflow",
-			QueueName:     queue.Name,
-			WorkflowID:    customWorkflowID,
-			WorkflowInput: wfInput{Input: "test-input"},
-		})
+		_, err := Enqueue[wfInput, string](clientCtx, queue.Name, "ServerWorkflow", wfInput{Input: "test-input"},
+			WithEnqueueWorkflowID(customWorkflowID))
 		require.NoError(t, err)
 
 		// Verify the workflow ID is what we set
@@ -123,12 +115,8 @@ func TestEnqueue(t *testing.T) {
 	})
 
 	t.Run("EnqueueWithTimeout", func(t *testing.T) {
-		handle, err := Enqueue[string, string](clientCtx, GenericEnqueueOptions[string]{
-			WorkflowName:    "BlockingWorkflow",
-			QueueName:       queue.Name,
-			WorkflowInput:   "blocking-input",
-			WorkflowTimeout: 500 * time.Millisecond,
-		})
+		handle, err := Enqueue[string, string](clientCtx, queue.Name, "BlockingWorkflow", "blocking-input",
+			WithEnqueueTimeout(500*time.Millisecond))
 		require.NoError(t, err)
 
 		// Should timeout when trying to get result
@@ -154,32 +142,20 @@ func TestEnqueue(t *testing.T) {
 		mu.Unlock()
 
 		// Enqueue workflow without priority (will use default priority of 0)
-		handle1, err := Enqueue[string, string](clientCtx, GenericEnqueueOptions[string]{
-			WorkflowName:       "PriorityWorkflow",
-			QueueName:          priorityQueue.Name,
-			WorkflowInput:      "abc",
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle1, err := Enqueue[string, string](clientCtx, priorityQueue.Name, "PriorityWorkflow", "abc",
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue workflow without priority")
 
 		// Enqueue with a lower priority (higher number = lower priority)
-		handle2, err := Enqueue[string, string](clientCtx, GenericEnqueueOptions[string]{
-			WorkflowName:       "PriorityWorkflow",
-			QueueName:          priorityQueue.Name,
-			WorkflowInput:      "def",
-			Priority:           5,
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle2, err := Enqueue[string, string](clientCtx, priorityQueue.Name, "PriorityWorkflow", "def",
+			WithEnqueuePriority(5),
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue workflow with priority 5")
 
 		// Enqueue with a higher priority (lower number = higher priority)
-		handle3, err := Enqueue[string, string](clientCtx, GenericEnqueueOptions[string]{
-			WorkflowName:       "PriorityWorkflow",
-			QueueName:          priorityQueue.Name,
-			WorkflowInput:      "ghi",
-			Priority:           1,
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle3, err := Enqueue[string, string](clientCtx, priorityQueue.Name, "PriorityWorkflow", "ghi",
+			WithEnqueuePriority(1),
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue workflow with priority 1")
 
 		// Get results
@@ -212,25 +188,17 @@ func TestEnqueue(t *testing.T) {
 		wfid2 := "client-dedup-wf2"
 
 		// First workflow with deduplication ID - should succeed
-		handle1, err := Enqueue[wfInput, string](clientCtx, GenericEnqueueOptions[wfInput]{
-			WorkflowName:       "ServerWorkflow",
-			QueueName:          queue.Name,
-			WorkflowID:         wfid1,
-			DeduplicationID:    dedupID,
-			WorkflowInput:      wfInput{Input: "test-input"},
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle1, err := Enqueue[wfInput, string](clientCtx, queue.Name, "ServerWorkflow", wfInput{Input: "test-input"},
+			WithEnqueueWorkflowID(wfid1),
+			WithEnqueueDeduplicationID(dedupID),
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue first workflow with deduplication ID")
 
 		// Second workflow with same deduplication ID but different workflow ID - should fail
-		_, err = Enqueue[wfInput, string](clientCtx, GenericEnqueueOptions[wfInput]{
-			WorkflowName:       "ServerWorkflow",
-			QueueName:          queue.Name,
-			WorkflowID:         wfid2,
-			DeduplicationID:    dedupID,
-			WorkflowInput:      wfInput{Input: "test-input"},
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		_, err = Enqueue[wfInput, string](clientCtx, queue.Name, "ServerWorkflow", wfInput{Input: "test-input"},
+			WithEnqueueWorkflowID(wfid2),
+			WithEnqueueDeduplicationID(dedupID),
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.Error(t, err, "expected error when enqueueing workflow with same deduplication ID")
 
 		// Check that it's the correct error type and message
@@ -242,22 +210,14 @@ func TestEnqueue(t *testing.T) {
 		assert.Contains(t, err.Error(), expectedMsgPart, "expected error message to contain deduplication information")
 
 		// Third workflow with different deduplication ID - should succeed
-		handle3, err := Enqueue[wfInput, string](clientCtx, GenericEnqueueOptions[wfInput]{
-			WorkflowName:       "ServerWorkflow",
-			QueueName:          queue.Name,
-			DeduplicationID:    "different-dedup-id",
-			WorkflowInput:      wfInput{Input: "test-input"},
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle3, err := Enqueue[wfInput, string](clientCtx, queue.Name, "ServerWorkflow", wfInput{Input: "test-input"},
+			WithEnqueueDeduplicationID("different-dedup-id"),
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue workflow with different deduplication ID")
 
 		// Fourth workflow without deduplication ID - should succeed
-		handle4, err := Enqueue[wfInput, string](clientCtx, GenericEnqueueOptions[wfInput]{
-			WorkflowName:       "ServerWorkflow",
-			QueueName:          queue.Name,
-			WorkflowInput:      wfInput{Input: "test-input"},
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle4, err := Enqueue[wfInput, string](clientCtx, queue.Name, "ServerWorkflow", wfInput{Input: "test-input"},
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue workflow without deduplication ID")
 
 		// Wait for all successful workflows to complete
@@ -274,14 +234,10 @@ func TestEnqueue(t *testing.T) {
 		assert.Equal(t, "processed: test-input", result4)
 
 		// After first workflow completes, we should be able to enqueue with same deduplication ID
-		handle5, err := Enqueue[wfInput, string](clientCtx, GenericEnqueueOptions[wfInput]{
-			WorkflowName:       "ServerWorkflow",
-			QueueName:          queue.Name,
-			WorkflowID:         wfid2,   // Reuse the workflow ID that failed before
-			DeduplicationID:    dedupID, // Same deduplication ID as first workflow
-			WorkflowInput:      wfInput{Input: "test-input"},
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle5, err := Enqueue[wfInput, string](clientCtx, queue.Name, "ServerWorkflow", wfInput{Input: "test-input"},
+			WithEnqueueWorkflowID(wfid2),   // Reuse the workflow ID that failed before
+			WithEnqueueDeduplicationID(dedupID), // Same deduplication ID as first workflow
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue workflow with same dedup ID after completion")
 
 		result5, err := handle5.GetResult()
@@ -366,13 +322,9 @@ func TestCancelResume(t *testing.T) {
 		workflowID := "test-cancel-resume-workflow"
 
 		// Start the workflow - it will execute step one and then wait
-		handle, err := Enqueue[int, int](clientCtx, GenericEnqueueOptions[int]{
-			WorkflowName:       "CancelResumeWorkflow",
-			QueueName:          queue.Name,
-			WorkflowID:         workflowID,
-			WorkflowInput:      input,
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle, err := Enqueue[int, int](clientCtx, queue.Name, "CancelResumeWorkflow", input,
+			WithEnqueueWorkflowID(workflowID),
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue workflow from client")
 
 		// Wait for workflow to signal it has started and step one completed
@@ -435,14 +387,10 @@ func TestCancelResume(t *testing.T) {
 		workflowTimeout := 2 * time.Second
 
 		// Start the workflow with a 2-second timeout
-		handle, err := Enqueue[string, string](clientCtx, GenericEnqueueOptions[string]{
-			WorkflowName:       "TimeoutBlockingWorkflow",
-			QueueName:          queue.Name,
-			WorkflowID:         workflowID,
-			WorkflowInput:      "timeout-test",
-			WorkflowTimeout:    workflowTimeout,
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle, err := Enqueue[string, string](clientCtx, queue.Name, "TimeoutBlockingWorkflow", "timeout-test",
+			WithEnqueueWorkflowID(workflowID),
+			WithEnqueueTimeout(workflowTimeout),
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue timeout blocking workflow")
 
 		// Wait 500ms (well before the timeout expires)
@@ -615,13 +563,9 @@ func TestForkWorkflow(t *testing.T) {
 		originalWorkflowID := "original-workflow-fork-test"
 
 		// 1. Run the entire workflow first and check counters are 1
-		handle, err := Enqueue[string, string](clientCtx, GenericEnqueueOptions[string]{
-			WorkflowName:       "ParentWorkflow",
-			QueueName:          queue.Name,
-			WorkflowID:         originalWorkflowID,
-			WorkflowInput:      "test",
-			ApplicationVersion: serverCtx.GetApplicationVersion(),
-		})
+		handle, err := Enqueue[string, string](clientCtx, queue.Name, "ParentWorkflow", "test",
+			WithEnqueueWorkflowID(originalWorkflowID),
+			WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 		require.NoError(t, err, "failed to enqueue original workflow")
 
 		// Wait for the original workflow to complete
@@ -758,27 +702,19 @@ func TestListWorkflows(t *testing.T) {
 			if i < 5 {
 				// First 5 workflows: use prefix "test-batch-" and succeed
 				workflowID = fmt.Sprintf("test-batch-%d", i)
-				handle, err = Enqueue[testInput, string](clientCtx, GenericEnqueueOptions[testInput]{
-					WorkflowName:       "SimpleWorkflow",
-					QueueName:          queue.Name,
-					WorkflowID:         workflowID,
-					WorkflowInput:      testInput{Value: i, ID: fmt.Sprintf("success-%d", i)},
-					ApplicationVersion: serverCtx.GetApplicationVersion(),
-				})
+				handle, err = Enqueue[testInput, string](clientCtx, queue.Name, "SimpleWorkflow", testInput{Value: i, ID: fmt.Sprintf("success-%d", i)},
+					WithEnqueueWorkflowID(workflowID),
+					WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 			} else {
 				// Last 5 workflows: use prefix "test-other-" and some will fail
 				workflowID = fmt.Sprintf("test-other-%d", i)
 				value := i
 				if i >= 8 {
 					value = -i // These will fail
 				}
-				handle, err = Enqueue[testInput, string](clientCtx, GenericEnqueueOptions[testInput]{
-					WorkflowName:       "SimpleWorkflow",
-					QueueName:          queue.Name,
-					WorkflowID:         workflowID,
-					WorkflowInput:      testInput{Value: value, ID: fmt.Sprintf("test-%d", i)},
-					ApplicationVersion: serverCtx.GetApplicationVersion(),
-				})
+				handle, err = Enqueue[testInput, string](clientCtx, queue.Name, "SimpleWorkflow", testInput{Value: value, ID: fmt.Sprintf("test-%d", i)},
+					WithEnqueueWorkflowID(workflowID),
+					WithEnqueueApplicationVersion(serverCtx.GetApplicationVersion()))
 			}
 
 			require.NoError(t, err, "failed to enqueue workflow %d", i)