Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix some links to DBOS docs #241

Merged
merged 1 commit into from
Jan 7, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions typescript/bank/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,7 @@ We can quickly review our assignment of roles to endpoints by reviewing the info
2024-06-27 14:15:23 [info]: Required Roles: ["appUser"]
```

If you are interested in learning more about declarative security in DBOS, please read our [Authentication and Authorization](https://docs.dbos.dev/tutorials/authentication-authorization) tutorial.
If you are interested in learning more about declarative security in DBOS, please read our [Authentication and Authorization](https://docs.dbos.dev/typescript/tutorials/crosscutting/authentication-authorization) tutorial.

## Deploying to DBOS Cloud
We can make some quick changes to deploy the DBOS Bank backend in the cloud, using the free "DBOS Starter" hosting tier.
Expand Down Expand Up @@ -444,12 +444,14 @@ This demo is time sensitive as you'll have a 10-second sleep window to crash Ban
5. In the log for the app, you should see the failed transfer. The 10 `Sleeping` statements, interrupted by a crash, then restart, workflow recovery and finally the "transaction reversed" error message.

## Further Reading
To get started with DBOS Transact, check out the [quickstart](https://docs.dbos.dev/getting-started/quickstart) and [docs](https://docs.dbos.dev/).
- To start a DBOS app from a template, visit our [quickstart](https://docs.dbos.dev/quickstart).
- For DBOS Transact programming tutorials, check out our [programming guide](https://docs.dbos.dev/typescript/programming-guide).
- To learn more about DBOS, take a look at [our documentation](https://docs.dbos.dev/) or our [source code](https://github.com/dbos-inc/dbos-transact).

DBOS [concepts](https://docs.dbos.dev/explanations/core-concepts) and their execution guarantees covered in depth in the [workflow tutorial](https://docs.dbos.dev/tutorials/workflow-tutorial).
DBOS [concepts](https://docs.dbos.dev/explanations/how-workflows-work) and their execution guarantees are covered in depth in the [workflow tutorial](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial).

For a quick introduction to [DBOS Cloud](https://www.dbos.dev/dbos-cloud), see [the tutorials](https://docs.dbos.dev/category/dbos-cloud-tutorials). Of particular interest is the [DBOS Cloud Monitoring Dashboard](https://docs.dbos.dev/cloud-tutorials/monitoring-dashboard).
For a quick introduction to [DBOS Cloud](https://www.dbos.dev/dbos-cloud), see [the tutorials](https://docs.dbos.dev/quickstart). Of particular interest is the [DBOS Cloud Monitoring Dashboard](https://docs.dbos.dev/cloud-tutorials/monitoring-dashboard).

For more information on [Prisma](https://www.prisma.io) as an ORM in DBOS, see [Using Prisma](https://docs.dbos.dev/tutorials/using-prisma).
For more information on [Prisma](https://www.prisma.io) as an ORM in DBOS, see [Using Prisma](https://docs.dbos.dev/typescript/tutorials/orms/using-prisma).

If you are interested in learning more about declarative security in DBOS, please read our [Authentication and Authorization](https://docs.dbos.dev/tutorials/authentication-authorization) tutorial.
If you are interested in learning more about declarative security in DBOS, please read our [Authentication and Authorization](https://docs.dbos.dev/typescript/tutorials/crosscutting/authentication-authorization) tutorial.
36 changes: 17 additions & 19 deletions typescript/e-commerce/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# DBOS E-Commerce Demo Apps

This demo is a pair of [DBOS](https://github.com/dbos-inc/dbos-transact) based systems demonstrating an
This demo is a pair of [DBOS](https://github.com/dbos-inc/dbos-transact-ts) based systems demonstrating an
e-commerce scenario with separate apps for the online shop and the payment provider.

## Demo Setup (local)
Expand Down Expand Up @@ -79,8 +79,7 @@ Pressing Submit Payment simulates entering your payment information, redirecting
When a payment is submitted, your shopping cart is cleared automatically.

## Deploying the Demo to the Cloud
> **💡 Tip:** If you have not yet read the [DBOS Cloud Quickstart](https://docs.dbos.dev/getting-started/quickstart-cloud) or the
> [DBOS Cloud Tutorials](https://docs.dbos.dev/category/dbos-cloud-tutorials) it may be a good idea to do so.
> **💡 Tip:** If you have not yet read the [DBOS Cloud Quickstart](https://docs.dbos.dev/quickstart) it may be a good idea to do so.

### Deploying the Payment Backend
The following steps are necessary to deploy the payment backend to the DBOS Cloud:
Expand Down Expand Up @@ -121,7 +120,7 @@ The Shop frontend can also be deployed to a Next.js hosting environment, such as

### Retrieving Status and Logs
Once you have deployed the shop to the cloud and placed a few orders, try out some of the cloud administration and monitoring commands.
(See the [tutorial](https://docs.dbos.dev/category/dbos-cloud-tutorials) or the [CLI reference](https://docs.dbos.dev/api-reference/cloud-cli) for more information.)
(See the [tutorial](https://docs.dbos.dev/quickstart) or the [CLI reference](https://docs.dbos.dev/cloud-tutorials/cloud-cli) for more information.)

Check the application status and logs from either the `e-commerce/payment-backend` or `e-commerce/shop-backend` directories by excuting DBOS Cloud CLI commands, such as:
* `npx dbos-cloud app status` - Provide a summary of the app, its database server, whether it is available, and if so, the app's URL
Expand Down Expand Up @@ -152,21 +151,21 @@ Provenance data is automatically captured by DBOS Cloud during workflow executio

> Tips:
> * The "DBOS Time Travel Debugger" extension must be installed. Sometimes restarting Visual Studio Code is necessary.
> * Detailed information and instructions can be found in the [Time Travel Debugger](https://docs.dbos.dev/api-reference/time-travel-debugger) reference.
> * Detailed information and instructions can be found in the [Time Travel Debugger](https://docs.dbos.dev/typescript/reference/tools/time-travel-debugger) reference.
> * Visual Studio Code should be open to the folder of the application you want to debug, not a child or parent folder. This allows the extension to find the application configuration and use the saved app credentials to access DBOS Cloud.
> * If the extension reports an error, review the logs that can be seen under "View"->"Output"->"DBOS" and "DBOS Debug Proxy".
> * The Debugger extension needs the database password to retrieve a snapshot of data for debugging. If the password needs to be changed, select "View"->"Command Palette..." and click "DBOS: Delete Stored Application Datbase Passwords" and try debugging again.
> * Debugging sessions are often more interesting if a breakpoint is set prior to launch. (Otherwise execution will replay and the debugging session will quickly end.)

## Under the Covers

> Note, this section assumes you have read at least the [DBOS Getting Started docs](https://docs.dbos.dev/category/getting-started).
> Note, this section assumes you have read at least the [DBOS Getting Started docs](https://docs.dbos.dev/quickstart).

Each backend package in this demo has a single [reliable workflow](https://docs.dbos.dev/tutorials/workflow-tutorial) at its core.
Each backend package in this demo has a single [reliable workflow](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial) at its core.
The following sections show the code for that workflow, along with detailed notes regarding how it works.
Each package also has [transaction](https://docs.dbos.dev/tutorials/transaction-tutorial),
[step](https://docs.dbos.dev/tutorials/step-tutorial)
and [handler](https://docs.dbos.dev/tutorials/http-serving-tutorial) functions.
Each package also has [transaction](https://docs.dbos.dev/typescript/tutorials/transaction-tutorial),
[step](https://docs.dbos.dev/typescript/tutorials/step-tutorial)
and [handler](https://docs.dbos.dev/typescript/tutorials/requestsandevents/http-serving-tutorial) functions.
These functions are fairly straightforward, please see the source code for more details.

### Shop paymentWorkflow
Expand Down Expand Up @@ -196,7 +195,7 @@ DBOS workflows must be decorated with `@DBOS.workflow()`.
```

The workflow starts off with some basic database operations.
Each of these database operations is implemented via a [transaction function](https://docs.dbos.dev/tutorials/transaction-tutorial).
Each of these database operations is implemented via a [transaction function](https://docs.dbos.dev/typescript/tutorials/transaction-tutorial).
The workflow retrieves the user's shopping cart, creates an order from cart items and subtracts the items from inventory.
If there are no items in the cart or there isn't sufficient inventory to fulfill the order, the workflow fails.
The `setEvent` call in the failure paths will be described shortly.
Expand All @@ -213,7 +212,7 @@ a payment session and get a payment redirection URL.
}
```

Assuming the order can be fulfilled, `paymentWorkflow` calls out to the payment provider via a [step](https://docs.dbos.dev/tutorials/communicator-tutorial).
Assuming the order can be fulfilled, `paymentWorkflow` calls out to the payment provider via a [step](https://docs.dbos.dev/typescript/tutorials/step-tutorial).
In a real-world shop using a real-world payment provider such as Stripe, `createPaymentSession` would likely use a client SDK from the payment provider.
Since this is a demo, raw `fetch` calls are used instead.

Expand All @@ -228,7 +227,7 @@ We do this by calling `setEvent` to communicate out to the host environment and
const notification = await DBOS.recv<string>(checkout_complete_topic, 60);
```

The `webCheckout` [Http handler](https://docs.dbos.dev/tutorials/http-serving-tutorial) function that called `paymentWorkflow`
The `webCheckout` [Http handler](https://docs.dbos.dev/typescript/tutorials/requestsandevents/http-serving-tutorial) function that called `paymentWorkflow`
uses `getEvent` to wait for the `paymentWorkflow` to provide the payment redirection URL.

```ts
Expand All @@ -248,7 +247,7 @@ If the payment session doesn't get created, `paymentWorkflow` sends a null value

Note that even though the `webCheckout` function will complete and return after receiving the event, the `paymentWorkflow` is still running.
It is waiting on a `checkout_complete_topic` message before continuing.
For more on events and messages, please see [Workflow Communications](https://docs.dbos.dev/tutorials/workflow-communication-tutorial)
For more on events and messages, please see [Workflow Communications](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial#workflow-events)

```ts
const notification = await DBOS.recv<string>(checkout_complete_topic, 60);
Expand Down Expand Up @@ -350,16 +349,15 @@ They also provide a [Docker image](https://openapi-generator.tech/docs/installat
## Unit Testing in DBOS

The e-commerce example application demonstrates a number of techniques for testing DBOS application logic before deployment.
For more information on testing in DBOS, see the [Testing and Debugging](https://docs.dbos.dev/tutorials/testing-tutorial) tutorial and [DBOS Testing Runtime](https://docs.dbos.dev/api-reference/testing-runtime) reference.
For more information on testing in DBOS, see the [Testing and Debugging](https://docs.dbos.dev/typescript/tutorials/development/testing-tutorial) tutorial.

### Testing Techniques

The `payment-backend` project uses:
* The [`jest`](https://jestjs.io/) testing framework for defining test suites (setup, teardown, and tests) and reporting test results.
* The [DBOS Testing Runtime](https://docs.dbos.dev/api-reference/testing-runtime), which permits "clear-box" testing of the application logic.
* [`supertest`](https://github.com/ladjs/supertest) executed against [`testRuntime.getHandlersCallback()`](https://docs.dbos.dev/api-reference/testing-runtime#runtimegethandlerscallback) to test HTTP handling logic in combination with the DBOS-based application code.
* `testRuntime.send` and `testRuntime.retrieveWorkflow` to examine and interact with the workflow under test.
* `testRuntime.setConfig` to set [application configuration](https://docs.dbos.dev/api-reference/configuration/#application) items, allowing the resulting behavior to be unit-tested.
* [`supertest`](https://github.com/ladjs/supertest) executed against [`DBOS.getHTTPHandlersCallback()`](https://docs.dbos.dev/typescript/reference/transactapi/dbos-class#http-testing) to test HTTP handling logic in combination with the DBOS-based application code.
* `DBOS.send` and `DBOS.retrieveWorkflow` to examine and interact with the workflow under test.
* `DBOS.setConfig` to set [application configuration](https://docs.dbos.dev/typescript/reference/configuration#application) items, allowing the resulting behavior to be unit-tested.

The `shop-backend` project uses a few additional testing techniques:
* Using `testRuntime.invoke` to call application functions without creating HTTP-style requests (via `supertest`).
Expand Down
4 changes: 2 additions & 2 deletions typescript/websockets/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Websockets samples

The sample takes the application generated in the [DBOS quick start](https://docs.dbos.dev/getting-started/quickstart) and adds a websocket endpoint to it.
The sample takes the application generated in the [DBOS quick start](https://docs.dbos.dev/quickstart) and adds a websocket endpoint to it.

## Code

Expand All @@ -18,7 +18,7 @@ to receive data from the server.

## Deploying the service

Follow the instructions in the [quickstart](https://docs.dbos.dev/getting-started/quickstart) to deploy the app either to the cloud or run locally.
Follow the instructions in the [quickstart](https://docs.dbos.dev/quickstart) to deploy the app either to the cloud or run locally.

On successful deployment, you will see a message

Expand Down
2 changes: 1 addition & 1 deletion typescript/widget-store/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The Server Tools section give you an opportunity to crash the app. After crashin

## Nightly Sales Reports (Optional)

As per [this blog post](https://www.dbos.dev/blog/how-to-build-cloud-cron-jobs), the DBOS Widget Store can send out nightly email sales reports, illustrating [scheduled workflows](https://docs.dbos.dev/typescript/tutorials/scheduled-workflows) and an [email library](https://www.npmjs.com/package/@dbos-inc/dbos-email-ses).
As per [this blog post](https://www.dbos.dev/blog/how-to-build-cloud-cron-jobs), the DBOS Widget Store can send out nightly email sales reports, illustrating [scheduled workflows](https://docs.dbos.dev/typescript/tutorials/requestsandevents/scheduled-workflows) and an [email library](https://www.npmjs.com/package/@dbos-inc/dbos-email-ses).

To enable the features, set up your email accounts in [SES](https://us-east-2.console.aws.amazon.com/ses/home) and then set the following environment variables before launching the widget store:

Expand Down
2 changes: 1 addition & 1 deletion typescript/yky-social/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# DBOS Social Demo App (YKY)

This demo shows a [DBOS](https://github.com/dbos-inc/dbos-transact) backend system coupled with a next.js frontend.
This demo shows a [DBOS](https://github.com/dbos-inc/dbos-transact-ts) backend system coupled with a next.js frontend.

It simulates a simple social network, and demonstrates:
* Use of DBOS workflows, transactions, and steps
Expand Down
Loading