DBOS Transact (#95)

Signed-off-by: Qian Li <[email protected]>
Signed-off-by: Peter Kraft <[email protected]>
Co-authored-by: maxdml <[email protected]>
Co-authored-by: Qian Li <[email protected]>
Co-authored-by: Max dml <[email protected]>

Author: 3 people

CONTRIBUTING.md

@@ -7,7 +7,7 @@ Thank you for considering contributing to the DBOS Documentation. We welcome con
 To get started with DBOS-Docs, please read the [README](README.md).
 
 You can contribute in many ways. Some simple ways are:
-* Open issues to report any bugs, questions, concern with the SDK, samples or documentation.
+* Open issues to report any bugs, questions, concern with DBOS Transact, 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.

README.md

@@ -1,4 +1,4 @@
-# DBOS SDK Documentation
+# DBOS Documentation
 
 ### Local Development
 

docs/api-reference/_category_.json

@@ -3,6 +3,6 @@
   "position": 4,
   "link": {
     "type": "generated-index",
-    "description": "A complete reference for the DBOS SDK."
+    "description": "A complete reference for DBOS."
   }
 }

docs/api-reference/cli.md

@@ -1,19 +1,19 @@
 ---
 sidebar_position: 1
-title: SDK CLI
-description: DBOS CLI reference
+title: DBOS Transact CLI
+description: DBOS Transact CLI reference
 ---
 
-The DBOS SDK CLI helps you run DBOS applications locally.
+The DBOS Transact CLI helps you run applications locally.
 
 ## Commands
 
 ---
 
-### `npx dbos-sdk start`
+### `npx dbos start`
 
 **Description:**  
-This command launches the DBOS runtime and HTTP server to serve an application.
+This command launches the DBOS Transact runtime and HTTP server to serve an application.
 It registers all functions and serves all endpoints in classes exported from the specified entrypoint file (typically `src/operations.ts`).
 Parameters set from the command line take precedence over parameters set in the [configuration file](./configuration).
 You must compile your code (`npm run build`) before running this command.
@@ -40,25 +40,25 @@ This command initializes a new DBOS application from a template into a target di
 
 ---
 
-### `npx dbos-sdk migrate`
+### `npx dbos migrate`
 
 **Description:**
 Run all migration commands specified in your [configuration file](./configuration) to apply your application's schema to the database.
 
 ---
 
-### `npx dbos-sdk rollback`
+### `npx dbos rollback`
 
 **Description:**
 Run all rollback commands specified in your [configuration file](./configuration) to roll back the last batch of schema migrations.
 
 ---
 
-### `npx dbos-sdk debug`
+### `npx dbos debug`
 
 **Description:**
 This command launches the DBOS runtime in debug mode to replay a specified workflow.
-It is similar to `dbos-sdk start`, but instead of starting an HTTP server, it replays a single workflow and connects to a locally running DBOS [time travel debug proxy](../cloud-tutorials/timetravel-debugging.md#time-travel-with-dbos-sdk-cli-non-vs-code-users).
+It is similar to `dbos start`, but instead of starting an HTTP server, it replays a single workflow and connects to a locally running DBOS [time travel debug proxy](../cloud-tutorials/timetravel-debugging.md#time-travel-with-dbos-cli-non-vs-code-users).
 You must compile your code (`npm run build`) and start the debug proxy before running this command.
 
 **Parameters:**

docs/api-reference/cloud-cli.md

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-title: Cloud CLI
+title: DBOS Cloud CLI
 description: DBOS Cloud CLI reference
 ---
 

docs/api-reference/configuration.md

@@ -54,8 +54,8 @@ database:
 
 This section is used to specify DBOS runtime parameters.
 
-- **port** (optional): The port from which to serve your functions. Defaults to `3000`. Using [`npx dbos-sdk start -p <port>`](./cli#npx-dbos-sdk-start) overrides this config parameter.
-- **entrypoint** (optional): The compiled Javascript file where DBOS looks for your application's code. At startup, the DBOS runtime automatically loads all classes exported from this file, serving their endpoints and registering their decorated functions.  Defaults to `dist/operations.js`. Using [`npx dbos-sdk start -e <entrypoint-file>`](./cli#npx-dbos-sdk-start) overrides this config parameter.
+- **port** (optional): The port from which to serve your functions. Defaults to `3000`. Using [`npx dbos start -p <port>`](./cli#npx-dbos-start) overrides this config parameter.
+- **entrypoint** (optional): The compiled Javascript file where DBOS looks for your application's code. At startup, the DBOS runtime automatically loads all classes exported from this file, serving their endpoints and registering their decorated functions.  Defaults to `dist/operations.js`. Using [`npx dbos start -e <entrypoint-file>`](./cli#npx-dbos-start) overrides this config parameter.
 
 **Example**:
 
@@ -85,7 +85,7 @@ You can use the configuration file to tune the behavior of DBOS logging facility
 Note all options in this section are optional and will, if not specified, use the default values indicated in the example below.
 
 #### Logs
-- **logLevel**: Filters, by severity, what logs should be printed. Defaults to `'info'`. Using [`npx dbos-sdk start -l <logLevel>`](./cli#npx-dbos-sdk-start) overrides this config parameter.
+- **logLevel**: Filters, by severity, what logs should be printed. Defaults to `'info'`. Using [`npx dbos start -l <logLevel>`](./cli#npx-dbos-start) overrides this config parameter.
 - **addContextMetadata**: Enables the addition of contextual information, such as workflow identity UUID, to each log entry. Defaults to `true`.
 - **silent**: Silences the logger. Defaults to `false`.
 

docs/api-reference/contexts.md

@@ -32,6 +32,7 @@ Many contexts inherit from `DBOSContext` and share its properties and methods.
 - [authenticatedRoles](#ctxtauthenticatedroles)
 - [assumedRole](#ctxtassumedrole)
 - [logger](#ctxtlogger)
+- [span](#ctxtspan)
 
 ### Methods
 
@@ -106,6 +107,16 @@ readonly logger: DBOSLogger
 A reference to DBOS's logger.
 Please see our [logging tutorial](../tutorials/logging.md) for more information.
 
+#### `ctxt.span`
+
+```typescript
+readonly span: Span
+```
+
+An [OpenTelemetry Span](https://opentelemetry.io/docs/concepts/signals/traces/#spans) associated with this context.
+You can assign custom trace attributes to this span.
+Please see the [Span API](https://github.com/open-telemetry/opentelemetry-js/blob/main/api/src/trace/span.ts) for more information.
+
 #### `ctxt.getConfig(key, [defaultValue])`
 
 ```typescript
@@ -429,6 +440,7 @@ getConfig<T>(key: string, defaultValue?: T): T | undefined;
 #### Properties and Methods
 
 - [logger](#middlewarecontextlogger)
+- [span](#middlewarecontextspan)
 - [koaContext](#middlewarecontextkoacontext)
 - [name](#middlewarecontextname)
 - [requiredRole](#middlewarecontextrequiredrole)
@@ -443,6 +455,12 @@ readonly logger: DBOSLogger;
 
 `logger` is available to record any interesting successes, failures, or diagnostic information that occur during middleware processing.
 
+#### `MiddlewareContext.span`
+```typescript
+readonly span: Span;
+```
+`span` is the tracing span in which the middleware is being executed.
+
 #### `MiddlewareContext.koaContext`
 
 ```typescript

docs/api-reference/decorators.md

@@ -456,7 +456,7 @@ DBOS allows applications to supply functions to be invoked at points in the appl
 #### `@DBOSInitializer`
 This decorator is used to specify functions to be run at application instance initialization time.
 `@DBOSInitializer` is intended for uses such as validating configuration, establishing connections to external (non-database) services, and so on.
-It is not a good place for database schema migration, for that see our [migration commands](cli.md#npx-dbos-sdk-migrate).
+It is not a good place for database schema migration, for that see our [migration commands](cli.md#npx-dbos-migrate).
 
 The argument to `@DBOSInitializer` should be of type [`InitContext`](contexts.md#initcontext).
 

docs/api-reference/static-analysis.md

@@ -15,9 +15,8 @@ While the list of "gotchas" is long and easily neglected, the good news is that
 DBOS recommends using static analysis as an ingredient in a comprehensive security strategy.  As adding rule enforcement to a large, established codebase can be a hassle, DBOS recommends using tools from the beginning of a project, and therefore includes tool configuration in its [demo applications](https://github.com/dbos-inc/dbos-demo-apps) and [quickstart templates](../getting-started/quickstart.md).
 
 DBOS uses several techniques to ensure that static analysis is as productive as possible, with minimal hassle:
-* DBOS builds on popular frameworks, thereby leveraging community best-practices and tools integration.
+* DBOS Transact builds on popular frameworks, thereby leveraging community best-practices and tools integration.
 * DBOS focuses on analysis rules that detect incorrect API usage and potential security vulnerabilities, rather than nitpicking on coding style.
-* The DBOS SDK is designed for straightforward analysis, reporting, and suggestion of superior alternatives.
 
 ---
 
@@ -30,7 +29,7 @@ Many DBOS=suggested coding practices can be enforced by a combination of `eslint
 ### Installing And Configuring `eslint`
 
 ::::tip
-If you got started with the [DBOS SDK Quickstart](../getting-started/quickstart.md), `eslint` and required plugins are already installed.
+If you got started with the [quickstart](../getting-started/quickstart.md), `eslint` and required plugins are already installed.
 Plugins to support TypeScript and detect common vulerabilities are automatically installed with `@dbos-inc/eslint-plugin` as dependencies and do not need to be installed separately.
 ::::
 
@@ -91,7 +90,7 @@ Many programmers use `console` statements during the development and debugging p
 
 The `no-console` rule, provided by the primary `eslint` package, is automatically enabled in all configs of the DBOS plugin.
 
-Use of `console` should be removed from code prior to use in production.  Activities such as logging should use [SDK logging facilities](../tutorials/logging.md), so that data remains structured and can be automatically collected in a central database.
+Use of `console` should be removed from code prior to use in production.  Activities such as logging should use [DBOS Transact logging facilities](../tutorials/logging.md), so that data remains structured and can be automatically collected in a central database.
 
 #### `no-eval`
 Interpreted languages like JavaScript support the ability to treat data directly as executable code.  If arbitrary user data can become code, many of the negative security implications are obvious.
@@ -126,15 +125,15 @@ Some DBOS lint rules are provided in the [`@dbos-inc/eslint-plugin`](https://git
 
 Calls to functions such as `Math.random()` are [nondeterministic](../tutorials/workflow-tutorial#determinism), and may interfere with consistent workflow results or the debugger.
 
-Such operations should use functions provided by the SDK, or at a minimum, be encapsulated in a [Communicator](../tutorials/communicator-tutorial).
+Such operations should use functions provided by DBOS Transact, or at a minimum, be encapsulated in a [Communicator](../tutorials/communicator-tutorial).
 
 This rule is enabled by default in all `@dbos-inc/eslint-plugin` configurations.
 
 #### `@dbos-inc/detect-new-date`
 
 Calls to functions such as `new Date()` are [nondeterministic](../tutorials/workflow-tutorial#determinism), and may interfere with transactional data, consistent workflow execution, or the debugger.
 
-Such operations should use functions provided by the SDK, or at a minimum, be encapsulated in a [Communicator](../tutorials/communicator-tutorial).
+Such operations should use functions provided by DBOS Transact, or at a minimum, be encapsulated in a [Communicator](../tutorials/communicator-tutorial).
 
 This rule is enabled by default in all `@dbos-inc/eslint-plugin` configurations.
 

docs/api-reference/time-travel-debugger.md

@@ -64,7 +64,7 @@ The default DBOS launch configuration includes both of these commands in the Tim
     "type": "node-terminal",
     "request": "launch",
     "name": "Time Travel Debug",
-    "command": "npx dbos-sdk debug -x ${command:dbos-ttdbg.get-proxy-url} -u ${command:dbos-ttdbg.pick-workflow-id}",
+    "command": "npx dbos debug -x ${command:dbos-ttdbg.get-proxy-url} -u ${command:dbos-ttdbg.pick-workflow-id}",
     "preLaunchTask": "npm: build"
 }
 ```

docs/cloud-tutorials/application-management.md

@@ -43,7 +43,7 @@ Run this command in your application root directory:
 npx dbos-cloud app deploy
 ```
 
-When you deploy an application, DBOS Cloud first runs [`npx dbos-sdk migrate`](../api-reference/cli.md#npx-dbos-sdk-migrate) on your application database to apply all schema migrations you've defined.
+When you deploy an application, DBOS Cloud first runs [`npx dbos migrate`](../api-reference/cli.md#npx-dbos-migrate) on your application database to apply all schema migrations you've defined.
 It then starts your application.
 After your application is deployed, DBOS Cloud hosts it at this URL, which is also printed by the deploy command:
 
@@ -64,7 +64,7 @@ Be careful making breaking schema changes such as deleting or renaming a column&
 ### Rolling Back Application Databases
 
 To [roll back your application database](./database-management.md#database-schema-management), run `npx dbos-cloud app rollback`.
-This command works analagously to `deploy`, but instead of running `npx dbos-sdk migrate`, it runs [`npx dbos-sdk rollback`](../api-reference/cli.md#npx-dbos-sdk-rollback) to execute the rollback commands defined in your [configuration file](../api-reference/configuration.md#database).
+This command works analagously to `deploy`, but instead of running `npx dbos migrate`, it runs [`npx dbos rollback`](../api-reference/cli.md#npx-dbos-rollback) to execute the rollback commands defined in your [configuration file](../api-reference/configuration.md#database).
 It then updates your application code.
 
 ### Monitoring and Debugging Applications

docs/cloud-tutorials/database-management.md

@@ -69,10 +69,10 @@ database:
   rollback: ['npx knex migrate:down']
 ```
 
-To run your migrations locally, run `npx dbos-sdk migrate` or `npx dbos-sdk rollback`.
+To run your migrations locally, run `npx dbos migrate` or `npx dbos rollback`.
 
-When you [deploy](./application-management.md#registering-and-deploying-applications) an application to DBOS Cloud it runs `npx dbos-sdk migrate` to apply all schema changes before starting your application or updating its code.
-When you [roll back](./application-management.md#rolling-back-application-databases) an application on DBOS Cloud, it runs `npx dbos-sdk rollback` to roll back schema changes before updating your application's code.
+When you [deploy](./application-management.md#registering-and-deploying-applications) an application to DBOS Cloud it runs `npx dbos migrate` to apply all schema changes before starting your application or updating its code.
+When you [roll back](./application-management.md#rolling-back-application-databases) an application on DBOS Cloud, it runs `npx dbos rollback` to roll back schema changes before updating your application's code.
 
 :::info
 Be careful making breaking schema changes such as deleting or renaming a column—they may break active workflows running on a previous application version.

docs/cloud-tutorials/timetravel-debugging.md

@@ -31,7 +31,7 @@ inside VS Code for "DBOS"
 Once installed, the DBOS Time Travel Extension will automatically update as new releases are published to the VS Code Marketplace.
 
 :::info
-If you're not a VS Code user, please see the section below on [Time Travel Debugging with the DBOS SDK CLI](#time-travel-with-dbos-sdk-cli-non-vs-code-users) below.
+If you're not a VS Code user, please see the section below on [Time Travel Debugging with the DBOS CLI](#time-travel-with-dbos-cli-non-vs-code-users) below.
 :::
 
 ### Launching a Debug Session
@@ -186,9 +186,9 @@ Currently, the time travel debugger supports stepping through any past workflows
 
 For more information, please read the [debugger extension reference](../api-reference/time-travel-debugger).
 
-## Time Travel with DBOS SDK CLI (Non-VS Code Users)
+## Time Travel with DBOS CLI (Non-VS Code Users)
 
-For non-VS Code users, you can run the time-travel debugger manually through the DBOS SDK CLI.
+For non-VS Code users, you can run the time-travel debugger manually through the DBOS CLI.
 
 ### Manual Setup
 
@@ -219,11 +219,11 @@ Open another terminal window, enter your application folder, compile your code,
 ```bash
 cd <Your App Folder>/
 npm run build
-npx dbos-sdk debug -u <workflow UUID>
+npx dbos debug -u <workflow UUID>
 ```
 
 :::info
-Every time you modify your code, you need to recompile it before running the `dbos-sdk debug` command again.
+Every time you modify your code, you need to recompile it before running the `dbos debug` command again.
 :::
 
-For more information on the debug command, please see our [references](../api-reference/cli.md#npx-dbos-sdk-debug)
+For more information on the debug command, please see our [references](../api-reference/cli.md#npx-dbos-debug)

docs/explanations/application-structure-explanation.md

@@ -103,4 +103,4 @@ Once you've written your functions, there are two basic ways to call them:
 1.  Any function (not just handlers) can be called from HTTP if it's annotated with the [`GetApi`](../api-reference/decorators#getapi) or [`PostApi`](../api-reference/decorators#postapi) decorators.  See our [HTTP serving tutorial](../tutorials/http-serving-tutorial) for details.
 2. Handlers and workflows can invoke other functions via their contexts' `invoke` ([workflow](../api-reference/contexts#workflowctxtinvoketargetclass), [handler](../api-reference/contexts#handlerctxtinvoketargetclass-workflowuuid)) method.
 
-To learn more about each individual type of function and what it can do, see our [tutorials](../category/dbos-sdk-tutorials/).
+To learn more about each individual type of function and what it can do, see our [tutorials](../category/dbos-transact-tutorials/).

docs/explanations/core-concepts.md

@@ -1,11 +1,11 @@
 ---
 sidebar_position: 2
-description: Learn the core ideas underlying the DBOS SDK
+description: Learn the core ideas underlying DBOS Transact
 ---
 
-# SDK Core Concepts
+# DBOS Transact Core Concepts
 
-The DBOS SDK is a transactional serverless TypeScript framework that helps you develop stateful applications that work right by default.
+DBOS Transact is a transactional serverless TypeScript framework that helps you develop stateful applications that work right by default.
 Its two main principles are inspired by the [DBOS research project from Stanford and MIT](https://dbos-project.github.io/):
 
 1. **Store all application state in the database.** By managing database connections and transactions, DBOS makes it easy for you to store all your app state in the database so it can be safe, consistent, and durable.  Under the hood, we use the database to manage the state of workflow execution as well as all [messages](../tutorials/workflow-communication-tutorial#messages-api) and [events](../tutorials/workflow-communication-tutorial#events-api).