From f41ec867d77c4a35e991b71f45cb2391a5c7bfba Mon Sep 17 00:00:00 2001 From: Peter Kraft Date: Mon, 9 Oct 2023 15:27:21 -0700 Subject: [PATCH] fixes --- docs/tutorials/handlers-tutorial.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/tutorials/handlers-tutorial.md b/docs/tutorials/handlers-tutorial.md index f1103d87..807ce681 100644 --- a/docs/tutorials/handlers-tutorial.md +++ b/docs/tutorials/handlers-tutorial.md @@ -20,13 +20,13 @@ Each associates a function with an HTTP URL. ### Handlers -A function annotated with an endpoint decorator but no other decorators like is called a _handler_ and must take a [`HandlerContext`](..) as its first argument, like in the example above. +A function annotated with an endpoint decorator but no other decorators is called a _handler_ and must take a [`HandlerContext`](..) as its first argument, like in the example above. Handlers can invoke other functions and directly access HTTP requests and responses. However, Operon makes no guarantees about handler execution: if a handler fails, it is not automatically retried. You should use handlers when you need to access HTTP responses directly or when you're doing a lightweight task that doesn't need the strong guarantees of transactions and workflows. -You don't need a handler to serve a transaction, workflow, or communicator from an HTTP URL. -You can also annotate your function with an endpoint decorator in addition to its [`@OperonTransaction`](../api-reference/decorators#operontransaction), [`@OperonWorkflow`](../api-reference/decorators#operonworkflow), or [`@OperonCommunicator`](../api-reference/decorators#operoncommunicator) decorator. +You don't need a handler function to serve a transaction, workflow, or communicator from an HTTP URL. +You can also annotate your existing function with an endpoint decorator in addition to its [`@OperonTransaction`](../api-reference/decorators#operontransaction), [`@OperonWorkflow`](../api-reference/decorators#operonworkflow), or [`@OperonCommunicator`](../api-reference/decorators#operoncommunicator) decorator. For example (from our [quickstart](..)): ```javascript @@ -48,24 +48,25 @@ Any Operon method invoked via HTTP request can access the raw request from its ` If a function has arguments other than its context, Operon attempts to automatically parse them from the HTTP request. Arguments can be parsed from three places: -1. From a URL query string parameter with the same name. -2. From an HTTP body field with the same name. -3. From an HTTP path parameter, if one is specified in the decorated URL. +1. From a URL query string parameter with the same name (by default, only for `GET`). +2. From an HTTP body field with the same name (by default, only for `POST`). +3. From an URL path parameter, if one is specified in the decorated URL. Input parsing can be configured using the [`@ArgSource`](../api-reference/decorators#argsource) parameter decorator. -By default, Operon automatically validates parsed inputs, returning an error if a function is missing required inputs or if the input received is of a different type than specified in the method signature. +By default, Operon automatically validates parsed inputs, throwing an error if a function is missing required inputs or if the input received is of a different type than specified in the method signature. Validation can be turned off at the class level using [`@DefaultArgOptional`](..) or controlled at the parameter level using [`@ArgRequired`](..) and [`@ArgOptional`](..). ### Outputs and HTTP Responses -By default, if an Operon function invoked via HTTP request returns successfuly, its return value is sent in the body of the HTTP response with status code `200`. +By default, if an Operon function invoked via HTTP request returns successfuly, its return value is sent in the HTTP response body with status code `200` (or `204` if nothing is returned). If the function throws an exception, the error message is sent in the response body with a `400` or `500` status code. +If the error contains a `status` field (we provide [`OperonResponseError`](..) for this purpose), Operon uses that status code instead. If you need custom HTTP response behavior, you can use a handler to access the HTTP response directly. -Operon uses [Koa](https://koajs.com/) for HTTP serving internally, so the raw response can be accessed via the `.koaContext.response` field of [`HandlerContext`](..), which returns a [Koa response](https://koajs.com/#response). +Operon uses [Koa](https://koajs.com/) for HTTP serving internally, so the raw response can be accessed via the `.koaContext.response` field of [`HandlerContext`](..), which provides a [Koa response](https://koajs.com/#response). ### Middleware Operon supports running custom [Koa](https://koajs.com/) middleware for serving HTTP requests. -Middleware is configured at the class level through the [`@KoaMiddleware`](../api-reference/decorators@koamiddleware) decorator. \ No newline at end of file +Middleware is configured at the class level through the [`@KoaMiddleware`](../api-reference/decorators#koamiddleware) decorator. \ No newline at end of file