diff --git a/docs/06-concepts/04-exceptions.md b/docs/06-concepts/04-exceptions.md index f84e8379..b5214de3 100644 --- a/docs/06-concepts/04-exceptions.md +++ b/docs/06-concepts/04-exceptions.md @@ -1,6 +1,10 @@ +--- +description: Handle server errors in Serverpod by defining serializable exceptions that are thrown on the server and caught in your Flutter app. +--- + # Error handling and exceptions -Handling errors well is essential when you are building your server. To simplify things, Serverpod allows you to throw an exception on the server, serialize it, and catch it in your client app. +Serverpod allows you to throw an exception on the server, serialize it, and catch it in your client app. If you throw a normal exception that isn't caught by your code, it will be treated as an internal server error. The exception will be logged together with its stack trace, and a 500 HTTP status (internal server error) will be sent to the client. On the client side, this will throw a non-specific ServerpodException, which provides no more data than a session id number which can help identify the call in your logs. @@ -14,7 +18,7 @@ Uncaught exceptions thrown in endpoints are logged in the `serverpod_session_log ## Serializable exceptions -Serverpod allows adding data to an exception you throw on the server and extracting that data in the client. This is useful for passing error messages back to the client when a call fails. You use the same YAML-files to define the serializable exceptions as you would with any serializable model (see [serialization](serialization) for details). The only difference is that you use the keyword `exception` instead of `class`. +Serverpod allows adding data to an exception you throw on the server and extracting that data in the client. You use the same YAML files to define the serializable exceptions as you would with any serializable model (see [serialization](serialization) for details). The only difference is that you use the keyword `exception` instead of `class`. ```yaml exception: MyException @@ -43,7 +47,7 @@ In your app, catch the exception as you would catch any exception. ```dart try { - client.example.doThingy(); + await client.example.doThingy(); } on MyException catch(e) { print(e.message); @@ -61,16 +65,9 @@ Serverpod allows you to specify default values for fields in exceptions, similar Since exceptions are not persisted in the database, the `defaultPersist` keyword is not supported. If both `default` and `defaultModel` are specified, `defaultModel` will always take precedence, making it unnecessary to use both. ::: -**Example:** - ```yaml exception: MyException fields: message: String, default="An error occurred" errorCode: int, default=1001 ``` - -In this example: - -- The `message` field will default to `"An error occurred"` if not provided. -- The `errorCode` field will default to `1001`. diff --git a/docs/06-concepts/05-sessions.md b/docs/06-concepts/05-sessions.md index 8555f895..9398ed87 100644 --- a/docs/06-concepts/05-sessions.md +++ b/docs/06-concepts/05-sessions.md @@ -1,12 +1,14 @@ -# Sessions +--- +description: Understand Serverpod sessions, which provides access to the database, cache, storage, and messaging for every endpoint call. +--- -A Session in Serverpod is a request-scoped context object that exists for the duration of a single client request or connection. It provides access to server resources and maintains state during request processing. +# Sessions -Sessions are the gateway to Serverpod's functionality - every interaction with the database, cache, file storage, or messaging system happens through a session. The framework automatically creates the appropriate session type when a client makes a request, manages its lifecycle, and ensures proper cleanup when the request completes. For special cases like background tasks or system operations, you can also create and manage sessions manually. +Every endpoint method receives a `Session` object. It is the entry point for the database, cache, file storage, and messaging system. Serverpod creates and closes sessions automatically for endpoint calls; for background tasks you create and close them manually. :::note -A Serverpod Session should not be confused with the concept of "web sessions" or "user sessions" which persist over multiple API calls. See the [Authentication documentation](./11-authentication/01-setup.md) for managing persistent authentication. +A Serverpod Session should not be confused with the concept of "web sessions" or "user sessions" which persist over multiple API calls. See the [Authentication documentation](./authentication/setup) for managing persistent authentication. ::: @@ -14,12 +16,12 @@ A Serverpod Session should not be confused with the concept of "web sessions" or ### Essential properties -- **`db`** - Database access. [See database docs](./06-database/01-connection.md) -- **`caches`** - Local and distributed caching. [See caching docs](./08-caching.md) -- **`storage`** - File storage operations. [See file uploads](./12-file-uploads.md) -- **`messages`** - Server events for real-time communication within and across servers. [See server events docs](./16-server-events.md) -- **`passwords`** - Credentials from config and environment. [See configuration](./07-configuration.md) -- **`authenticated`** - Current user authentication info. [See authentication docs](./11-authentication/02-basics.md) +- **`db`** - Database access. [See database docs](./database/connection) +- **`caches`** - Local and distributed caching. [See caching docs](./caching) +- **`storage`** - File storage operations. [See file uploads](./file-uploads) +- **`messages`** - Server events for real-time communication within and across servers. [See server events docs](./server-events) +- **`passwords`** - Credentials from config and environment. [See configuration](./configuration) +- **`authenticated`** - Current user authentication info. [See authentication docs](./authentication/basics) ### Key methods @@ -82,9 +84,7 @@ flowchart TB Close --> End([Request Complete]) ``` -Sessions follow a predictable lifecycle from creation to cleanup. When a client makes a request, Serverpod automatically creates the appropriate session type (see table above), initializes it with a unique ID, and sets up access to resources like the database, cache, and file storage. - -During the active phase, your operation executes with full access to Serverpod resources through the session. You can query the database, write logs, send messages, and access storage - all operations are tracked and tied to this specific session. When the operation completes, most sessions close automatically, writing any accumulated logs to the database and releasing all resources. +When a client makes a request, Serverpod creates the appropriate session type (see table above) and tears it down when the operation completes. Most sessions close automatically; `InternalSession` is the exception. ### Internal Sessions @@ -116,7 +116,7 @@ Cleanup callbacks run in the order they were registered and are called for all s ## Logging -Serverpod batches log entries for performance. During normal operations, logs accumulate in memory and are written to the database in a single batch when the session closes. This includes all your `session.log()` calls, database query timings, and session metadata. The exception is streaming sessions (`MethodStreamSession` and `StreamingSession`), which write logs continuously by default to avoid memory buildup during long connections. +Log entries are written to the database when the session closes. Streaming sessions (`MethodStreamSession` and `StreamingSession`) write logs continuously to avoid memory buildup during long connections. :::warning @@ -300,4 +300,4 @@ withServerpod('test group', (sessionBuilder, endpoints) { }); ``` -For detailed testing strategies, see the [testing documentation](./19-testing/01-get-started.md). +For detailed testing strategies, see the [testing documentation](./testing/get-started).