From a26abc9843db7a718c84102990cc0995947a290b Mon Sep 17 00:00:00 2001 From: rderbier Date: Wed, 9 Oct 2024 10:30:10 -0700 Subject: [PATCH 1/4] Update error-handling.mdx add draft --- modus/error-handling.mdx | 125 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/modus/error-handling.mdx b/modus/error-handling.mdx index f5e1f0c1..241c1050 100644 --- a/modus/error-handling.mdx +++ b/modus/error-handling.mdx @@ -2,3 +2,128 @@ title: Error Handling description: "" --- + +### Error Handling Guide for Modus Framework + +In this guide, we'll explore best practices for handling errors in the **Modus framework** using both **AssemblyScript** and **Go**. + +**Modus framework** leverages the **Console API** and **GraphQL error responses**. + +### Error reporting in GraphQL + +GraphQL responses have a standard structure that includes both a `data` and an `errors` section. Errors should returned either: +Modus facilitates the inclusion of error codes or messages within the `errors` section, enhancing how errors are communicated to the front end. + +#### Example (AssemblyScript): + +```typescript +throw new Error("Invalid input provided."); +``` + +This will return an error that appears in the `errors` section of the GraphQL response. + +--- + +### Leveraging the Console API + +The **Console API** in Modus is globally available in all functions. It allows developers to capture log messages and errors, which are automatically shown in the Hypermode UI under the "Function Runs" section. + +**Console logging levels**: + +- `console.log()`: Basic log messages. +- `console.debug()`: Debug-level messages. +- `console.info()`: Informational messages. +- `console.warn()`: Warning messages. +- `console.error()`: Logs error messages and sends them to the GraphQL response. + +All log messages are stored in structured logs, which means additional fields like "text", "message", and others are captured for each log. + +#### Example (AssemblyScript): + +```typescript +console.log("This is a simple log message."); +console.error("This is an error message."); +``` + +#### Example (Go): + +```go +func TestNormalError(input string) (string, error) { + if input == "" { + return "", errors.New("input is empty") + } + return "You said: " + input, nil +} +``` + +--- + +### Error handling in AssemblyScript + +In AssemblyScript, you can handle errors using `console.error` for non-fatal errors and the `throw` keyword for critical errors that stop the function's execution. + +#### Logging and throwing errors (AssemblyScript): + +```typescript +export function testErrors(): void { + console.log("This is a log message."); + console.error("This is an error message."); + + // Throwing an error stops the function. + throw new Error("This is a fatal error."); +} +``` + +Using `console.error` logs the message while allowing the function to continue. `throw` immediately halts execution and logs the error in the GraphQL response. + +--- + +### Error handling in Go + +In Go, error handling is typically done by returning an `error` object as the last result of a function. Modus transforms this into logging and error handling automatically, ensuring all errors are logged before being sent to the response. + +#### Example (Go): + +```go +func TestNormalError(input string) (string, error) { + if input == "" { + return "", errors.New("input is empty") + } + return "You said: " + input, nil +} +``` + +You can also log errors directly without returning them by using `console.Error`: + +```go +func TestAlternativeError(input string) string { + if input == "" { + console.Error("input is empty") + return "" + } + return "You said: " + input +} +``` + +This is less idiomatic in Go, but it allows for handling non-fatal errors and logging them without interrupting the function flow. + +--- + +### Structured logging + +Structured logging in Modus separates the log message and additional fields for better clarity. This allows you to distinguish between different levels of severity and categories of errors in a systematic way. + +In the **Console UI**, the message itself is stored in a field called `text`, while other fields such as `user_visible`, `execution_id`, and `plugin` help filter or categorize logs. + +### Best practices for error handling + +- **Use Console API for logging**: All levels of logs should be captured with appropriate severity (`info`, `warn`, `error`). +- **Return clear error messages**: When returning errors, include concise and informative error messages that help diagnose the issue. +- **Leverage structured logs**: Take advantage of Modus's structured logging to include context and metadata in your error reports. +- **Use GraphQL's error sections effectively**: Add relevant information to the `errors` section when working with GraphQL, ensuring clear communication to the client. + +--- + +### Conclusion + +Error handling in Modus combines the power of **structured logging**, **GraphQL error sections**, and the **Console API** to provide both a clear debugging process for developers and informative responses for end-users. Whether you're working in **AssemblyScript** or **Go**, implementing these best practices will ensure your application is resilient and easy to maintain. From a0a256ad951a158636bdb6f5e49db7f254e1b159 Mon Sep 17 00:00:00 2001 From: rderbier Date: Wed, 9 Oct 2024 11:01:36 -0700 Subject: [PATCH 2/4] Update error-handling.mdx clean drafy --- modus/error-handling.mdx | 114 +++++++++++++-------------------------- 1 file changed, 38 insertions(+), 76 deletions(-) diff --git a/modus/error-handling.mdx b/modus/error-handling.mdx index 241c1050..d0a23ad7 100644 --- a/modus/error-handling.mdx +++ b/modus/error-handling.mdx @@ -3,51 +3,23 @@ title: Error Handling description: "" --- -### Error Handling Guide for Modus Framework - -In this guide, we'll explore best practices for handling errors in the **Modus framework** using both **AssemblyScript** and **Go**. - -**Modus framework** leverages the **Console API** and **GraphQL error responses**. +In this guide, we'll explore best practices for handling errors in the **Modus framework** leveraging the **Console API** and **GraphQL error responses**. ### Error reporting in GraphQL GraphQL responses have a standard structure that includes both a `data` and an `errors` section. Errors should returned either: Modus facilitates the inclusion of error codes or messages within the `errors` section, enhancing how errors are communicated to the front end. -#### Example (AssemblyScript): + -```typescript +```ts AssemblyScript throw new Error("Invalid input provided."); ``` -This will return an error that appears in the `errors` section of the GraphQL response. - ---- - -### Leveraging the Console API - -The **Console API** in Modus is globally available in all functions. It allows developers to capture log messages and errors, which are automatically shown in the Hypermode UI under the "Function Runs" section. - -**Console logging levels**: - -- `console.log()`: Basic log messages. -- `console.debug()`: Debug-level messages. -- `console.info()`: Informational messages. -- `console.warn()`: Warning messages. -- `console.error()`: Logs error messages and sends them to the GraphQL response. - -All log messages are stored in structured logs, which means additional fields like "text", "message", and others are captured for each log. - -#### Example (AssemblyScript): - -```typescript -console.log("This is a simple log message."); -console.error("This is an error message."); -``` - -#### Example (Go): - -```go +```ts Go +// In Go, error handling is typically done by returning an `error` object as the last result of a function. +// Modus transforms this into logging and error handling automatically, +// ensuring all errors are logged before being sent to the response. func TestNormalError(input string) (string, error) { if input == "" { return "", errors.New("input is empty") @@ -56,58 +28,43 @@ func TestNormalError(input string) (string, error) { } ``` ---- - -### Error handling in AssemblyScript - -In AssemblyScript, you can handle errors using `console.error` for non-fatal errors and the `throw` keyword for critical errors that stop the function's execution. - -#### Logging and throwing errors (AssemblyScript): - -```typescript -export function testErrors(): void { - console.log("This is a log message."); - console.error("This is an error message."); + - // Throwing an error stops the function. - throw new Error("This is a fatal error."); -} -``` - -Using `console.error` logs the message while allowing the function to continue. `throw` immediately halts execution and logs the error in the GraphQL response. +The error automatically appears in the `errors` section of the GraphQL response and in Modus runtime execution logs. ---- +### Leveraging the Console API -### Error handling in Go +The **Console API** in Modus is globally available in all functions. It allows developers to capture log messages and errors, which are automatically included in Modus runtime execution logs. Logs are visible in Hypermode UI under the [Function Runs](../observe-functions#function-runs) section. -In Go, error handling is typically done by returning an `error` object as the last result of a function. Modus transforms this into logging and error handling automatically, ensuring all errors are logged before being sent to the response. +**Console logging levels**: -#### Example (Go): + -```go -func TestNormalError(input string) (string, error) { - if input == "" { - return "", errors.New("input is empty") - } - return "You said: " + input, nil -} +```typescript index.ts +console.log("This is a simple log message."); +console.debug("This is a debug message."); +console.info("This is an info message."); +console.warn("This is a warning message."); +console.error("This is an error message."); ``` -You can also log errors directly without returning them by using `console.Error`: +```go main.go +package main -```go -func TestAlternativeError(input string) string { - if input == "" { - console.Error("input is empty") - return "" - } - return "You said: " + input -} +import ( + "github.com/hypermodeinc/modus/sdk/go/pkg/console" +) + +console.Log("This is a simple log message.") +console.Debug("This is a debug message.") +console.Info("This is an info message.") +console.Warn("This is a warning message.") +console.Error("This is an error message.") ``` -This is less idiomatic in Go, but it allows for handling non-fatal errors and logging them without interrupting the function flow. + ---- +`console.error()` also sends the message to the GraphQL response. ### Structured logging @@ -117,9 +74,14 @@ In the **Console UI**, the message itself is stored in a field called `text`, wh ### Best practices for error handling -- **Use Console API for logging**: All levels of logs should be captured with appropriate severity (`info`, `warn`, `error`). +- **Handle non-fatal errors** using `console.error` for , allowing the function to continue. The GraphQL response may have both a `data` section and an `errors` section. + +- **Handle critical errors** using AssemblyScript `throw` keyword or the Go idiomatic error object to stop the function's execution. + - **Return clear error messages**: When returning errors, include concise and informative error messages that help diagnose the issue. + - **Leverage structured logs**: Take advantage of Modus's structured logging to include context and metadata in your error reports. + - **Use GraphQL's error sections effectively**: Add relevant information to the `errors` section when working with GraphQL, ensuring clear communication to the client. --- From 42b94e71219db62d50378c37e6cf9c6a3ef20b87 Mon Sep 17 00:00:00 2001 From: rderbier Date: Wed, 9 Oct 2024 11:05:58 -0700 Subject: [PATCH 3/4] Update error-handling.mdx corrections. --- modus/error-handling.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/modus/error-handling.mdx b/modus/error-handling.mdx index d0a23ad7..8aef9a13 100644 --- a/modus/error-handling.mdx +++ b/modus/error-handling.mdx @@ -7,7 +7,7 @@ In this guide, we'll explore best practices for handling errors in the **Modus f ### Error reporting in GraphQL -GraphQL responses have a standard structure that includes both a `data` and an `errors` section. Errors should returned either: +GraphQL responses have a standard structure that includes both a `data` and an `errors` section. Modus facilitates the inclusion of error codes or messages within the `errors` section, enhancing how errors are communicated to the front end. @@ -52,7 +52,7 @@ console.error("This is an error message."); package main import ( - "github.com/hypermodeinc/modus/sdk/go/pkg/console" + "github.com/hypermodeinc/modus/sdk/go/pkg/console" ) console.Log("This is a simple log message.") @@ -70,8 +70,6 @@ console.Error("This is an error message.") Structured logging in Modus separates the log message and additional fields for better clarity. This allows you to distinguish between different levels of severity and categories of errors in a systematic way. -In the **Console UI**, the message itself is stored in a field called `text`, while other fields such as `user_visible`, `execution_id`, and `plugin` help filter or categorize logs. - ### Best practices for error handling - **Handle non-fatal errors** using `console.error` for , allowing the function to continue. The GraphQL response may have both a `data` section and an `errors` section. @@ -88,4 +86,4 @@ In the **Console UI**, the message itself is stored in a field called `text`, wh ### Conclusion -Error handling in Modus combines the power of **structured logging**, **GraphQL error sections**, and the **Console API** to provide both a clear debugging process for developers and informative responses for end-users. Whether you're working in **AssemblyScript** or **Go**, implementing these best practices will ensure your application is resilient and easy to maintain. +Error handling in Modus combines the power of **structured logging**, **GraphQL error sections**, and the **Console API** to provide both a clear debugging process for developers and informative responses for end-users. Whether you're working in **AssemblyScript** or **Go**, implementing these best practices ensures your app is resilient and easy to maintain. From ba70a4d81e688e80a83ae119b460df2f7e7ba367 Mon Sep 17 00:00:00 2001 From: rderbier Date: Wed, 9 Oct 2024 12:04:22 -0700 Subject: [PATCH 4/4] Update error-handling.mdx ckarify AS code for fatal and non fatal. --- modus/error-handling.mdx | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/modus/error-handling.mdx b/modus/error-handling.mdx index 8aef9a13..2e50c856 100644 --- a/modus/error-handling.mdx +++ b/modus/error-handling.mdx @@ -13,14 +13,32 @@ Modus facilitates the inclusion of error codes or messages within the `errors` s ```ts AssemblyScript -throw new Error("Invalid input provided."); +export function TestError(input: string): string { + if (input == "") { + console.error("input is empty"); + // this is a non-fatal error reported in GraphQL response. + // the function continues + return "Can't process your input"; + // GraphQL response contains both a data section and an errors section with all reported errors + } + if (input == "error") { + throw new Error(`This is a fatal error.`); + // a fatal error appears in the log + // the errors section in GraphQL responses contains only one entry with + // "message": "error calling function" + // the function does not continue + // the data section in GraphQL response is empty + } + + return "You said: " + input; +} ``` ```ts Go // In Go, error handling is typically done by returning an `error` object as the last result of a function. // Modus transforms this into logging and error handling automatically, // ensuring all errors are logged before being sent to the response. -func TestNormalError(input string) (string, error) { +func TestError(input string) (string, error) { if input == "" { return "", errors.New("input is empty") } @@ -72,7 +90,7 @@ Structured logging in Modus separates the log message and additional fields for ### Best practices for error handling -- **Handle non-fatal errors** using `console.error` for , allowing the function to continue. The GraphQL response may have both a `data` section and an `errors` section. +- **Handle non-fatal errors** using `console.error`, allowing the function to continue. The GraphQL response may have both a `data` section and an `errors` section. - **Handle critical errors** using AssemblyScript `throw` keyword or the Go idiomatic error object to stop the function's execution.