From f1dc3423672b4f4798aea40961c0bf513e44776c Mon Sep 17 00:00:00 2001 From: xM1haix <100999607+xM1haix@users.noreply.github.com> Date: Wed, 17 Dec 2025 23:05:40 +0200 Subject: [PATCH 1/4] Fix import path for authUserId example Updated import statement for user ID retrieval example. --- .../06-concepts/11-authentication/03-working-with-users.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md b/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md index 788f2d66..1b674436 100644 --- a/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md +++ b/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md @@ -8,7 +8,7 @@ All authenticated users have an authentication identifier, that uniquely identif ```dart var userIdString = session.authenticated?.userIdentifier; -// requires `import 'package:serverpod_auth_idp_server/serverpod_auth_idp_server.dart';` +// requires `import 'package:serverpod_auth_idp_server/core.dart';` var userIdUuidValue = session.authenticated?.authUserId; ``` From 300a78257fe60ca821058093d1dc290461582e30 Mon Sep 17 00:00:00 2001 From: xM1haix <100999607+xM1haix@users.noreply.github.com> Date: Wed, 17 Dec 2025 23:34:40 +0200 Subject: [PATCH 2/4] Rename 'Client-side configuration' to 'Flutter-side configuration' The "client" keyword is confusing because there is actually a client in the serverpod, so it's better to keep the same name across all docs --- .../11-authentication/04-providers/01-email/01-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-3.1.0/06-concepts/11-authentication/04-providers/01-email/01-setup.md b/versioned_docs/version-3.1.0/06-concepts/11-authentication/04-providers/01-email/01-setup.md index de59331d..33c3453f 100644 --- a/versioned_docs/version-3.1.0/06-concepts/11-authentication/04-providers/01-email/01-setup.md +++ b/versioned_docs/version-3.1.0/06-concepts/11-authentication/04-providers/01-email/01-setup.md @@ -90,7 +90,7 @@ For more details on configuration options, such as customizing password requirem If you are using the `config/passwords.yaml` file or environment variables, you can use the `EmailIdpConfigFromPasswords` constructor to automatically load the secret pepper. It will expect the `emailSecretHashPepper` key or the `SERVERPOD_PASSWORD_emailSecretHashPepper` environment variable to be set with the secret pepper value. ::: -## Client-side configuration +## Flutter-side configuration If you have configured the `SignInWidget` as described in the [setup section](../../setup#present-the-authentication-ui), the Email identity provider will be automatically detected and displayed in the sign-in widget. From 567a2c2cb975db8db27365db98657fa010147943 Mon Sep 17 00:00:00 2001 From: xM1haix <100999607+xM1haix@users.noreply.github.com> Date: Wed, 17 Dec 2025 23:50:51 +0200 Subject: [PATCH 3/4] Clarify setup instructions for Flutter app Updated references from 'App' to 'Flutter app' for clarity. --- .../version-3.1.0/06-concepts/11-authentication/01-setup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versioned_docs/version-3.1.0/06-concepts/11-authentication/01-setup.md b/versioned_docs/version-3.1.0/06-concepts/11-authentication/01-setup.md index 5bc4f982..0757eaed 100644 --- a/versioned_docs/version-3.1.0/06-concepts/11-authentication/01-setup.md +++ b/versioned_docs/version-3.1.0/06-concepts/11-authentication/01-setup.md @@ -189,9 +189,9 @@ dependencies: serverpod_auth_idp_client: 3.x.x ``` -## App setup +## Flutter setup -First, add dependencies to your app's `pubspec.yaml` file for the methods of signing in that you want to support. +First, add dependencies to your flutter app's `pubspec.yaml` file for the methods of signing in that you want to support. ```yaml dependencies: @@ -238,7 +238,7 @@ In case you have an endpoint called `AuthEndpoint` - that will generate the `aut ### Initialize authentication -The `initialize()` method restores any existing session from storage and validates it with the server. It should be called when your app starts: +The `initialize()` method restores any existing session from storage and validates it with the server. It should be called when your flutter app starts: ```dart await client.auth.initialize(); From 88bdc45855d49419c4ce87bc1863745c2c6c6e0d Mon Sep 17 00:00:00 2001 From: xM1haix Date: Sun, 21 Dec 2025 07:53:47 +0200 Subject: [PATCH 4/4] Refactor documentation to emphasize Flutter app terminology and improve clarity - Updated references from "client" to "Flutter app" across multiple documents to enhance consistency and clarity. - Revised sections on endpoint creation, error handling, pagination, caching, and authentication to reflect the Flutter context. - Improved explanations regarding server interactions, emphasizing the role of the Flutter app in various scenarios. - Enhanced descriptions of streaming methods and file uploads to align with Flutter app usage. - Clarified security configuration instructions specific to Flutter apps. --- docs/01-get-started/01-creating-endpoints.md | 8 ++--- .../03-working-with-the-database.md | 2 +- docs/01-get-started/04-deployment.md | 2 +- docs/02-overview.md | 10 +++---- .../02-real-time-communication.md | 4 +-- docs/06-concepts/01-working-with-endpoints.md | 8 ++--- docs/06-concepts/04-exceptions.md | 8 ++--- docs/06-concepts/06-database/09-pagination.md | 6 ++-- docs/06-concepts/08-caching.md | 4 +-- docs/06-concepts/10-modules.md | 2 +- .../06-concepts/11-authentication/01-setup.md | 2 +- .../04-providers/01-email/01-setup.md | 2 +- .../04-providers/01-email/02-configuration.md | 2 +- .../04-providers/02-google/01-setup.md | 2 +- .../04-providers/03-apple/01-setup.md | 2 +- .../04-providers/04-passkey/01-setup.md | 6 ++-- .../05-token-managers/02-jwt-token-manager.md | 4 +-- .../03-server-side-sessions-token-manager.md | 4 +-- .../11-authentication/10-custom-overrides.md | 2 +- .../11-authentication/11-legacy/01-setup.md | 2 +- .../11-legacy/04-providers/02-google.md | 10 +++---- .../11-legacy/05-custom-overrides.md | 2 +- docs/06-concepts/12-file-uploads.md | 2 +- docs/06-concepts/15-streams.md | 30 +++++++++---------- docs/06-concepts/17-backward-compatibility.md | 2 +- docs/06-concepts/20-security-configuration.md | 4 +-- 26 files changed, 66 insertions(+), 66 deletions(-) diff --git a/docs/01-get-started/01-creating-endpoints.md b/docs/01-get-started/01-creating-endpoints.md index 934784aa..d343d299 100644 --- a/docs/01-get-started/01-creating-endpoints.md +++ b/docs/01-get-started/01-creating-endpoints.md @@ -103,13 +103,13 @@ $ cd magic_recipe_server $ serverpod generate ``` -`serverpod generate` will create bindings for the endpoint and register them in the server's `generated/protocol.dart` file. It will also generate the required client code so that you can call your new `generateRecipe` method from your app. +`serverpod generate` will create bindings for the endpoint and register them in the server's `generated/protocol.dart` file. It will also generate the required Flutter app code so that you can call your new `generateRecipe` method from your app. :::note -When writing server-side code, in most cases, you want it to be _stateless_. This means you avoid using global or static variables. Instead, think of each endpoint method as a function that does stuff in a sub-second timeframe and returns data or a status messages to your client. If you want to run more complex computations, you can return a `Stream` to yield progress updates as your task progresses. +When writing server-side code, in most cases, you want it to be _stateless_. This means you avoid using global or static variables. Instead, think of each endpoint method as a function that does stuff in a sub-second timeframe and returns data or a status messages to your Flutter app. If you want to run more complex computations, you can return a `Stream` to yield progress updates as your task progresses. ::: -## Call the endpoint from the client +## Call the endpoint from the Flutter app Now that you have created the endpoint, you can call it from the Flutter app. Do this in the `magic_recipe_flutter/lib/main.dart` file. Rename the `_callHello` method to `_callGenerateRecipe` and modify it to do the following (feel free to just copy and paste): @@ -231,4 +231,4 @@ Try out the app by clicking the button to get a new recipe. The app will call th ## Next steps -For now, you are just returning a `String` to the client. In the next section, you will create a custom data model to return structured data. Serverpod makes it easy by handling all the serialization and deserialization for you. +For now, you are just returning a `String` to the app. In the next section, you will create a custom data model to return structured data. Serverpod makes it easy by handling all the serialization and deserialization for you. diff --git a/docs/01-get-started/03-working-with-the-database.md b/docs/01-get-started/03-working-with-the-database.md index 51034f07..b5ba65e2 100644 --- a/docs/01-get-started/03-working-with-the-database.md +++ b/docs/01-get-started/03-working-with-the-database.md @@ -193,7 +193,7 @@ $ cd magic_recipe_server $ serverpod generate ``` -## Call the endpoint from the app +## Call the endpoint from the Flutter app Now that we have updated the endpoint, we can call it from the app. We do this in the `magic_recipe_flutter/lib/main.dart` file. We will call the `getRecipes` method when the app starts and store the result in a list of `Recipe` objects. We will also update the UI to show the list of recipes. diff --git a/docs/01-get-started/04-deployment.md b/docs/01-get-started/04-deployment.md index b8521553..2df619ff 100644 --- a/docs/01-get-started/04-deployment.md +++ b/docs/01-get-started/04-deployment.md @@ -16,7 +16,7 @@ For non-Docker deployments, you'll need to [compile the Dart code](https://dart. By default Serverpod is active on three ports: -- **8080**: The main port for the server - this is where the generated client will connect to. +- **8080**: The main port for the server - this is where the generated Flutter app will connect to. - **8081**: The port for connecting with the [Serverpod Insights](../09-tools/01-insights.md) tooling. You may want to restrict which IP addresses can connect to this port. - **8082**: The built in webserver is running on this port. diff --git a/docs/02-overview.md b/docs/02-overview.md index 37a40325..6782f05e 100644 --- a/docs/02-overview.md +++ b/docs/02-overview.md @@ -4,7 +4,7 @@ sidebar_label: 🧭 Overview # Overview -Serverpod is an open-source backend framework for Flutter applications written in Dart. It aims to minimize boilerplate and integrate many common backend tasks out of the box. With Serverpod, Flutter developers can build secure, scalable server applications using the same language and tools as their client apps, benefiting from seamless code generation and a rich set of built-in capabilities. +Serverpod is an open-source backend framework for Flutter applications written in Dart. It aims to minimize boilerplate and integrate many common backend tasks out of the box. With Serverpod, Flutter developers can build secure, scalable server applications using the same language and tools as their Flutter apps, benefiting from seamless code generation and a rich set of built-in capabilities. ## Key capabilities @@ -22,7 +22,7 @@ Serverpod is an open-source backend framework for Flutter applications written i ## Defining Endpoints -In Serverpod, endpoints are the entry points that clients call to execute server-side logic. An endpoint is defined by creating a class that extends the Endpoint class and adding asynchronous methods to it. Each endpoint method must return a `Future` and take a `Session` object as its first parameter. The `Session` provides context about the call and gives access to server resources like the database or cache. +In Serverpod, endpoints are the entry points that Flutter app call to execute server-side logic. An endpoint is defined by creating a class that extends the Endpoint class and adding asynchronous methods to it. Each endpoint method must return a `Future` and take a `Session` object as its first parameter. The `Session` provides context about the call and gives access to server resources like the database or cache. For example, here's a simple endpoint definition with a single method: @@ -36,9 +36,9 @@ class GreetingEndpoint extends Endpoint { } ``` -You can place your endpoints anywhere in your server package. After adding or modifying endpoints, you run the Serverpod code generator (`serverpod generate`) to update the client interface. The generator produces a Dart client library that mirrors your server API. +You can place your endpoints anywhere in your server package. After adding or modifying endpoints, you run the Serverpod code generator (`serverpod generate`) to update the Flutter interface. The generator produces a Dart client library that mirrors your server API. -On the Flutter client side, calling the endpoint is as straightforward as calling a local function. For instance, using the generated client, you can invoke the above hello method like this: +On the Flutter side, calling the endpoint is as straightforward as calling a local function. For instance, using the generated client, you can invoke the above hello method like this: ```dart final result = await client.greeting.hello('World'); @@ -59,7 +59,7 @@ fields: foundedDate: DateTime? ``` -This defines a `Company` class with two fields. When you run `serverpod generate`, Serverpod creates a Dart class named `Company` (with a `name` and `foundedDate` property) that can be used in your endpoint methods and in the client code. +This defines a `Company` class with two fields. When you run `serverpod generate`, Serverpod creates a Dart class named `Company` (with a `name` and `foundedDate` property) that can be used in your endpoint methods and in the Flutter app code. By default, model classes are plain data holders that can be sent over the network. Serverpod supports most basic types, including `bool`, `int`, `double`, `String`, `Duration`, `DateTime`, `ByteData`, `UuidValue`, `Uri`, and `BigInt`. You can also use `List`, `Map`, `Set`, and other custom serializable objects. Null safety is supported, and the models can be nested with each other as needed. diff --git a/docs/05-tutorials/02-tutorials/02-real-time-communication.md b/docs/05-tutorials/02-tutorials/02-real-time-communication.md index a390008f..40e893ec 100644 --- a/docs/05-tutorials/02-tutorials/02-real-time-communication.md +++ b/docs/05-tutorials/02-tutorials/02-real-time-communication.md @@ -34,7 +34,7 @@ We begin by creating a new project with the `serverpod create` command. Since we serverpod create pixorama --mini ``` -Now, let's open the project in VS Code and explore the structure. The server code resides in the `pixorama_server` package. We'll start by creating models - classes that we can serialize and pass between the client and server. Our models will be placed in the `lib/src/models` directory. +Now, let's open the project in VS Code and explore the structure. The server code resides in the `pixorama_server` package. We'll start by creating models - classes that we can serialize and pass between the Flutter app and server. Our models will be placed in the `lib/src/models` directory. ## Creating models @@ -72,7 +72,7 @@ serverpod generate ## Building the server -Next, we'll build the server. We need to create a new endpoint. An endpoint is a connection point for the client to interact with the server. In Serverpod, you create endpoints by extending the `Endpoint` class and placing it in the `lib/src/endpoints` directory. The endpoint will manage our pixel data and handle client updates. +Next, we'll build the server. We need to create a new endpoint. An endpoint is a connection point for the Flutter app to interact with the server. In Serverpod, you create endpoints by extending the `Endpoint` class and placing it in the `lib/src/endpoints` directory. The endpoint will manage our pixel data and handle client updates. We will start by creating a `PixoramaEndpoint` class, which we place in a file called `pixorama_endpoint.dart` in the `lib/src/endpoints` directory. diff --git a/docs/06-concepts/01-working-with-endpoints.md b/docs/06-concepts/01-working-with-endpoints.md index 8c48278b..200e1c9d 100644 --- a/docs/06-concepts/01-working-with-endpoints.md +++ b/docs/06-concepts/01-working-with-endpoints.md @@ -1,6 +1,6 @@ # Working with endpoints -Endpoints are the connection points to the server from the client. With Serverpod, you add methods to your endpoint, and your client code will be generated to make the method call. For the code to be generated, you need to place the endpoint file anywhere under the `lib` directory of your server. Your endpoint should extend the `Endpoint` class. For methods to be generated, they need to return a typed `Future`, and its first argument should be a `Session` object. The `Session` object holds information about the call being made and provides access to the database. +Endpoints are the connection points to the server from the Flutter app. With Serverpod, you add methods to your endpoint, and your client code will be generated to make the method call. For the code to be generated, you need to place the endpoint file anywhere under the `lib` directory of your server. Your endpoint should extend the `Endpoint` class. For methods to be generated, they need to return a typed `Future`, and its first argument should be a `Session` object. The `Session` object holds information about the call being made and provides access to the database. ```dart import 'package:serverpod/serverpod.dart'; @@ -14,7 +14,7 @@ class ExampleEndpoint extends Endpoint { The above code will create an endpoint called `example` (the Endpoint suffix will be removed) with the single `hello` method. To generate the client-side code run `serverpod generate` in the home directory of the server. -On the client side, you can now call the method by calling: +On the Flutter side, you can now call the method by calling: ```dart var result = await client.example.hello('World'); @@ -305,9 +305,9 @@ abstract class AdminEndpoint extends Endpoint { Again, just have your custom endpoint extend `AdminEndpoint` and you can be sure that the user has the appropriate permissions. -## Client-side endpoint inheritance +## Flutter-side endpoint inheritance -When you use endpoint inheritance on the server, Serverpod generates matching client-side classes that mirror your inheritance hierarchy. This allows you to write type-safe client code that works with abstract endpoint types. +When you use endpoint inheritance on the server, Serverpod generates matching Flutter-side classes that mirror your inheritance hierarchy. This allows you to write type-safe client code that works with abstract endpoint types. ### Abstract endpoint client generation diff --git a/docs/06-concepts/04-exceptions.md b/docs/06-concepts/04-exceptions.md index e4baa660..5ab50c10 100644 --- a/docs/06-concepts/04-exceptions.md +++ b/docs/06-concepts/04-exceptions.md @@ -1,8 +1,8 @@ # 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. +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 Flutter 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 identifiy the call in your logs. +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 Flutter side, this will throw a non-specific ServerpodException, which provides no more data than a session id number which can help identifiy the call in your logs. :::tip @@ -12,7 +12,7 @@ Use the Serverpod Insights app to view your logs. It will show any failed or slo ## 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 Flutter app. 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`. ```yaml exception: MyException @@ -37,7 +37,7 @@ class ExampleEndpoint extends Endpoint { } ``` -In your app, catch the exception as you would catch any exception. +In your Flutter app, catch the exception as you would catch any exception. ```dart try { diff --git a/docs/06-concepts/06-database/09-pagination.md b/docs/06-concepts/06-database/09-pagination.md index fecd3965..83861ef3 100644 --- a/docs/06-concepts/06-database/09-pagination.md +++ b/docs/06-concepts/06-database/09-pagination.md @@ -61,7 +61,7 @@ Cursor-based pagination is an alternative method to the traditional limit-offset ### How it works -In cursor-based pagination, the client provides a cursor as a reference point, and the server returns data relative to that cursor. This cursor is usually an `id`. +In cursor-based pagination, the Flutter app provides a cursor as a reference point, and the server returns data relative to that cursor. This cursor is usually an `id`. ### Implementing cursor-based pagination @@ -82,7 +82,7 @@ In cursor-based pagination, the client provides a cursor as a reference point, a For the subsequent requests, use the cursor (for example, the last `id` from the previous result) to fetch the next set of records: ```dart - int cursor = lastCompanyIdFromPreviousPage; // This is typically sent by the client + int cursor = lastCompanyIdFromPreviousPage; // This is typically sent by the Flutter app var companies = await Company.db.find( session, @@ -93,7 +93,7 @@ In cursor-based pagination, the client provides a cursor as a reference point, a ``` 3. **Returning the cursor**: - When returning data to the client, also return the cursor, so it can be used to compute the starting point for the next page. + When returning data to the Flutter app, also return the cursor, so it can be used to compute the starting point for the next page. ```dart return { diff --git a/docs/06-concepts/08-caching.md b/docs/06-concepts/08-caching.md index 2fe38e6d..cfe44205 100644 --- a/docs/06-concepts/08-caching.md +++ b/docs/06-concepts/08-caching.md @@ -19,7 +19,7 @@ Future getUserData(Session session, int userId) async { await session.caches.local.put(cacheKey, userData!, lifetime: Duration(minutes: 5)); } - // Return the user data to the client + // Return the user data to the Flutter app return userData; } ``` @@ -50,7 +50,7 @@ Future getUserData(Session session, int userId) async { ), ); - // Return the user data to the client + // Return the user data to the Flutter app return userData; } ``` diff --git a/docs/06-concepts/10-modules.md b/docs/06-concepts/10-modules.md index 442b0747..dc853c36 100644 --- a/docs/06-concepts/10-modules.md +++ b/docs/06-concepts/10-modules.md @@ -8,7 +8,7 @@ Examples of modules are the `serverpod_auth_core` and `serverpod_auth_idp` modul ### Server setup -To add a module to your project, you must include the server and client/Flutter packages in your project's `pubspec.yaml` files. +To add a module to your project, you must include the server, client and Flutter packages in your project's `pubspec.yaml` files. For example, to add the `serverpod_auth_idp` module to your project, you need to add `serverpod_auth_idp_server` to your server's `pubspec.yaml`: diff --git a/docs/06-concepts/11-authentication/01-setup.md b/docs/06-concepts/11-authentication/01-setup.md index 5bc4f982..478599d5 100644 --- a/docs/06-concepts/11-authentication/01-setup.md +++ b/docs/06-concepts/11-authentication/01-setup.md @@ -189,7 +189,7 @@ dependencies: serverpod_auth_idp_client: 3.x.x ``` -## App setup +## Flutter setup First, add dependencies to your app's `pubspec.yaml` file for the methods of signing in that you want to support. diff --git a/docs/06-concepts/11-authentication/04-providers/01-email/01-setup.md b/docs/06-concepts/11-authentication/04-providers/01-email/01-setup.md index de59331d..33c3453f 100644 --- a/docs/06-concepts/11-authentication/04-providers/01-email/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/01-email/01-setup.md @@ -90,7 +90,7 @@ For more details on configuration options, such as customizing password requirem If you are using the `config/passwords.yaml` file or environment variables, you can use the `EmailIdpConfigFromPasswords` constructor to automatically load the secret pepper. It will expect the `emailSecretHashPepper` key or the `SERVERPOD_PASSWORD_emailSecretHashPepper` environment variable to be set with the secret pepper value. ::: -## Client-side configuration +## Flutter-side configuration If you have configured the `SignInWidget` as described in the [setup section](../../setup#present-the-authentication-ui), the Email identity provider will be automatically detected and displayed in the sign-in widget. diff --git a/docs/06-concepts/11-authentication/04-providers/01-email/02-configuration.md b/docs/06-concepts/11-authentication/04-providers/01-email/02-configuration.md index 91fc89e9..cfd18253 100644 --- a/docs/06-concepts/11-authentication/04-providers/01-email/02-configuration.md +++ b/docs/06-concepts/11-authentication/04-providers/01-email/02-configuration.md @@ -46,7 +46,7 @@ final emailIdpConfig = EmailIdpConfigFromPasswords( ``` :::tip -This is useful to ensure password policies on the server-side. It is a best practice to pair it with a configuration on the client-side to provide a better UX when creating a new password. The `EmailSignInWidget` and `EmailAuthController` have a `passwordRequirements` parameter that can be used to configure the password requirements. +This is useful to ensure password policies on the server-side. It is a best practice to pair it with a configuration on the Flutter-side to provide a better UX when creating a new password. The `EmailSignInWidget` and `EmailAuthController` have a `passwordRequirements` parameter that can be used to configure the password requirements. ::: ### Custom Verification Code Generation diff --git a/docs/06-concepts/11-authentication/04-providers/02-google/01-setup.md b/docs/06-concepts/11-authentication/04-providers/02-google/01-setup.md index 88138546..c768f00c 100644 --- a/docs/06-concepts/11-authentication/04-providers/02-google/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/02-google/01-setup.md @@ -99,7 +99,7 @@ The `google_client_secret.json` contains a private key and should not be version ## Client-side configuration -For our client-side configurations, we have to first create client-side credentials and include the credentials files in our projects. The Android and iOS integrations use the [google_sign_in](https://pub.dev/packages/google_sign_in) package under the hood, so any documentation there should also apply to this setup. +For our Flutter-side configurations, we have to first create Flutter-side credentials and include the credentials files in our projects. The Android and iOS integrations use the [google_sign_in](https://pub.dev/packages/google_sign_in) package under the hood, so any documentation there should also apply to this setup. ### iOS diff --git a/docs/06-concepts/11-authentication/04-providers/03-apple/01-setup.md b/docs/06-concepts/11-authentication/04-providers/03-apple/01-setup.md index 621430b0..cfbfba16 100644 --- a/docs/06-concepts/11-authentication/04-providers/03-apple/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/03-apple/01-setup.md @@ -129,7 +129,7 @@ Finally, run `serverpod generate` to generate the client code and create a migra For more details on configuration options, see the [configuration section](./configuration). -## Client-side configuration +## Flutter-side configuration The `serverpod_auth_idp_flutter` package implements the sign-in logic using [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple). The documentation for this package should in most cases also apply to the Serverpod integration. diff --git a/docs/06-concepts/11-authentication/04-providers/04-passkey/01-setup.md b/docs/06-concepts/11-authentication/04-providers/04-passkey/01-setup.md index cdc43d4a..8e0302cf 100644 --- a/docs/06-concepts/11-authentication/04-providers/04-passkey/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/04-passkey/01-setup.md @@ -3,7 +3,7 @@ Passkeys provide a passwordless authentication method using WebAuthn/FIDO2 standards. They offer a secure, phishing-resistant way for users to sign in using biometric authentication, security keys, or device PINs. :::caution -This provider is currently experimental and implemented only on the server-side. Flutter client-side UI components are not yet available, but you can build custom UI using the generated client endpoints. +This provider is currently experimental and implemented only on the server-side. Flutter-side UI components are not yet available, but you can build custom UI using the generated client endpoints. ::: :::caution @@ -71,10 +71,10 @@ Finally, run `serverpod generate` to generate the client code and create a migra -## Client-side implementation +## Flutter-side implementation :::info -Flutter UI components for passkeys are not yet available. You'll need to implement the client-side passkey flow using the WebAuthn API directly or use a Flutter package that supports WebAuthn/FIDO2. +Flutter UI components for passkeys are not yet available. You'll need to implement the Flutter-side passkey flow using the WebAuthn API directly or use a Flutter package that supports WebAuthn/FIDO2. ::: ### Using the generated endpoints diff --git a/docs/06-concepts/11-authentication/05-token-managers/02-jwt-token-manager.md b/docs/06-concepts/11-authentication/05-token-managers/02-jwt-token-manager.md index 2082a80d..6c31316e 100644 --- a/docs/06-concepts/11-authentication/05-token-managers/02-jwt-token-manager.md +++ b/docs/06-concepts/11-authentication/05-token-managers/02-jwt-token-manager.md @@ -106,6 +106,6 @@ final jwtConfig = JwtConfigFromPasswords( ); ``` -## Client-side configuration +## Flutter-side configuration -When using the `JwtTokenManager` in the server, no extra configuration is needed on the client. It will automatically include the access token in requests to the server and eagerly refresh the token when it is 30 seconds away from expiring. In case the refresh token expires, the client will automatically sign the user out and redirect to the login page. +When using the `JwtTokenManager` in the server, no extra configuration is needed on the Flutter. It will automatically include the access token in requests to the server and eagerly refresh the token when it is 30 seconds away from expiring. In case the refresh token expires, the client will automatically sign the user out and redirect to the login page. diff --git a/docs/06-concepts/11-authentication/05-token-managers/03-server-side-sessions-token-manager.md b/docs/06-concepts/11-authentication/05-token-managers/03-server-side-sessions-token-manager.md index 5fb59f45..76fa4e40 100644 --- a/docs/06-concepts/11-authentication/05-token-managers/03-server-side-sessions-token-manager.md +++ b/docs/06-concepts/11-authentication/05-token-managers/03-server-side-sessions-token-manager.md @@ -52,6 +52,6 @@ final serverSideSessionsConfig = ServerSideSessionsConfigFromPasswords( ); ``` -## Client-side configuration +## Flutter-side configuration -When using the `ServerSideSessionsTokenManager` in the server, no extra configuration is needed on the client. It will automatically include the session token in requests to the server. In case the session expires or is revoked, the client will automatically sign the user out and redirect to the login page. +When using the `ServerSideSessionsTokenManager` in the server, no extra configuration is needed on the Flutter. It will automatically include the session token in requests to the server. In case the session expires or is revoked, the client will automatically sign the user out and redirect to the login page. diff --git a/docs/06-concepts/11-authentication/10-custom-overrides.md b/docs/06-concepts/11-authentication/10-custom-overrides.md index 5d9341ff..0eb490b3 100644 --- a/docs/06-concepts/11-authentication/10-custom-overrides.md +++ b/docs/06-concepts/11-authentication/10-custom-overrides.md @@ -84,7 +84,7 @@ There are three types of `RevokedAuthentication` messages that are used to speci Each message type provides a tailored approach to revoke authentication based on different needs. -### Send token to client +### Send token to Flutter app You are responsible for implementing the endpoints to authenticate/authorize the user. But as an example such an endpoint could look like the following. diff --git a/docs/06-concepts/11-authentication/11-legacy/01-setup.md b/docs/06-concepts/11-authentication/11-legacy/01-setup.md index 677ac269..c998a70e 100644 --- a/docs/06-concepts/11-authentication/11-legacy/01-setup.md +++ b/docs/06-concepts/11-authentication/11-legacy/01-setup.md @@ -130,7 +130,7 @@ dependencies: serverpod_auth_client: ^1.x.x ``` -## App setup +## Flutter setup First, add dependencies to your app's `pubspec.yaml` file for the methods of signing in that you want to support. diff --git a/docs/06-concepts/11-authentication/11-legacy/04-providers/02-google.md b/docs/06-concepts/11-authentication/11-legacy/04-providers/02-google.md index 7b52c420..b80c5ea1 100644 --- a/docs/06-concepts/11-authentication/11-legacy/04-providers/02-google.md +++ b/docs/06-concepts/11-authentication/11-legacy/04-providers/02-google.md @@ -50,9 +50,9 @@ The `google_client_secret.json` contains a private key and should not be version ![Google credentials](/img/6-google-credentials.jpg) -## Client-side configuration +## Flutter-side configuration -For our client-side configurations, we have to first create client-side credentials and include the credentials files in our projects. The Android and iOS integrations use the [google_sign_in](https://pub.dev/packages/google_sign_in) package under the hood, any documentation there should also apply to this setup. +For our Flutter-side configurations, we have to first create Flutter-side credentials and include the credentials files in our projects. The Android and iOS integrations use the [google_sign_in](https://pub.dev/packages/google_sign_in) package under the hood, any documentation there should also apply to this setup. :::info Rather than using the credentails file for iOS and Android, you can pass the `clientId` and the `serverClientId` to the `signInWithGoogle` method or the `SignInWithGoogleButton` widget. The `serverClientId` is the client ID from the server credentials. @@ -60,7 +60,7 @@ Rather than using the credentails file for iOS and Android, you can pass the `cl ### iOS -Create the client credentials. Navigate to _Credentials_ under _APIs & Services_. Click _Create Credentials_ and select _OAuth client ID_. Configure the OAuth client as Application type _**iOS**_. +Create the Flutter credentials. Navigate to _Credentials_ under _APIs & Services_. Click _Create Credentials_ and select _OAuth client ID_. Configure the OAuth client as Application type _**iOS**_. Fill in all the required information, and create the credentials. Then download the `plist` file rename it to `GoogleService-Info.plist` and put it inside your ios project folder. Then drag and drop it into your XCode project to include the file in your build. @@ -109,7 +109,7 @@ If you have any social logins in your app you also need to integrate "Sign in wi ### Android -Create the client credentials. Navigate to _Credentials_ under _APIs & Services_. Click _Create Credentials_ and select _OAuth client ID_. Configure the OAuth client as Application type _**Android**_. +Create the Flutter credentials. Navigate to _Credentials_ under _APIs & Services_. Click _Create Credentials_ and select _OAuth client ID_. Configure the OAuth client as Application type _**Android**_. Fill in all required information, you can get the debug SHA-1 hash by running `./gradlew signingReport` in your Android project directory. Create the credentials and download the JSON file. @@ -126,7 +126,7 @@ $ keytool -list -v -keystore /path/to/keystore ### Web -There is no need to create any client credentials for the web we will simply pass the `serverClientId` to the sign-in button. +There is no need to create any Flutter credentials for the web we will simply pass the `serverClientId` to the sign-in button. However, we have to modify the server credentials inside the google cloud console. Navigate to _Credentials_ under _APIs & Services_ and select the server credentials. Under `Authorized JavaScript origins` and `Authorized redirect URIs` add the domain for your Flutter app, for development, this is `http://localhost:port` where the port is the port you are using. diff --git a/docs/06-concepts/11-authentication/11-legacy/05-custom-overrides.md b/docs/06-concepts/11-authentication/11-legacy/05-custom-overrides.md index c51eeaeb..7e0d3e18 100644 --- a/docs/06-concepts/11-authentication/11-legacy/05-custom-overrides.md +++ b/docs/06-concepts/11-authentication/11-legacy/05-custom-overrides.md @@ -84,7 +84,7 @@ There are three types of `RevokedAuthentication` messages that are used to speci Each message type provides a tailored approach to revoke authentication based on different needs. -### Send token to client +### Send token to Flutter app You are responsible for implementing the endpoints to authenticate/authorize the user. But as an example such an endpoint could look like the following. diff --git a/docs/06-concepts/12-file-uploads.md b/docs/06-concepts/12-file-uploads.md index bbb788ab..746c0b37 100644 --- a/docs/06-concepts/12-file-uploads.md +++ b/docs/06-concepts/12-file-uploads.md @@ -30,7 +30,7 @@ Future verifyUpload(Session session, String path) async { } ``` -### Client-side code +### Flutter-side code To upload a file from the app side, first request the upload description. Next, upload the file. You can upload from either a `Stream` or a `ByteData` object. If you are uploading a larger file, using a `Stream` is better because not all of the data must be held in RAM memory. Finally, you should verify the upload with the server. diff --git a/docs/06-concepts/15-streams.md b/docs/06-concepts/15-streams.md index 9030f842..89ef61a0 100644 --- a/docs/06-concepts/15-streams.md +++ b/docs/06-concepts/15-streams.md @@ -1,6 +1,6 @@ # Streams -For some applications, it's not enough to be able to call server-side methods. You may also want to push data from the server to the client or send data two-way. Examples include real-time games or chat applications. Luckily, Serverpod supports a framework for streaming data. It's possible to stream any serialized objects to or from any endpoint. +For some applications, it's not enough to be able to call server-side methods. You may also want to push data from the server to the Flutter app or send data two-way. Examples include real-time games or chat applications. Luckily, Serverpod supports a framework for streaming data. It's possible to stream any serialized objects to or from any endpoint. Serverpod supports streaming data through [streaming methods](#streaming-methods), which imitate how `Streams` work in Dart and offer a simple interface that automatically handles the connection with the server. @@ -59,21 +59,21 @@ Note that we can mix different types in the stream. This stream is defined as dy ### Lifecycle of a streaming method -Each time the client calls a streaming method, a new `Session` is created, and a call with that `Session` is made to the method endpoint on the server. The `Session` is automatically closed when the streaming method call is over. +Each time the Flutter app calls a streaming method, a new `Session` is created, and a call with that `Session` is made to the method endpoint on the server. The `Session` is automatically closed when the streaming method call is over. -If the web socket connection is lost, all streaming methods are closed on the server and the client. +If the web socket connection is lost, all streaming methods are closed on the server and the Flutter app. -When the streaming method is defined with a returning `Stream`, the method is kept alive until the stream subscription is canceled on the client or the method returns. +When the streaming method is defined with a returning `Stream`, the method is kept alive until the stream subscription is canceled on the Flutter app or the method returns. When the streaming method returns a `Future`, the method is kept alive until the method returns. -Streams in parameters are closed when the stream is closed. This can be done by either closing the stream on the client or canceling the subscription on the server. +Streams in parameters are closed when the stream is closed. This can be done by either closing the stream on the Flutter app or canceling the subscription on the server. All streams in parameters are closed when the method call is over. ### Authentication -Authentication is seamlessly integrated into streaming method calls. When a client initiates a streaming method, the server automatically authenticates the session. +Authentication is seamlessly integrated into streaming method calls. When a Flutter app initiates a streaming method, the server automatically authenticates the session. Authentication is validated when the stream is first established, utilizing the authentication data stored in the `Session` object. If a user's authentication is subsequently revoked—requiring denial of access to the stream—the stream will be promptly closed, and an exception will be thrown. @@ -83,7 +83,7 @@ For more details on handling revoked authentication, refer to the section on [ha Error handling works just like in regular endpoint methods in Serverpod. If an exception is thrown on a stream, the stream is closed with an exception. If the exception thrown is a serializable exception, the exception is first serialized and passed over the stream before it is closed. -This is supported in both directions; stream parameters can pass exceptions to the server, and return streams can pass exceptions to the client. +This is supported in both directions; stream parameters can pass exceptions to the server, and return streams can pass exceptions to the Flutter app. ```dart class ExampleEndpoint extends Endpoint { @@ -104,17 +104,17 @@ var outStream = client.example.echoStream(inStream.stream); outStream.listen((message) { // Do nothing }, onError: (error) { - print('Client received error: $error'); + print('Flutter app received error: $error'); }); -inStream.addError(SerializableException('Error from client')); +inStream.addError(SerializableException('Error from Flutter app')); // This will print -// Server received error: Error from client -// Client received error: Error from server +// Server received error: Error from Flutter app +// Flutter app received error: Error from server ``` -In the example above, the client sends an error to the server, which then throws an exception back to the client. And since the exception is serializable, it is passed over the stream before the stream is closed. +In the example above, the Flutter app sends an error to the server, which then throws an exception back to the Flutter app. And since the exception is serializable, it is passed over the stream before the stream is closed. Read more about serializable exceptions here: [Serializable exceptions](exceptions). @@ -132,9 +132,9 @@ The Endpoint class has three methods you override to work with streams. - `streamOpened` is called when a user connects to a stream on the Endpoint. - `streamClosed` is called when a user disconnects from a stream on the Endpoint. -- `handleStreamMessage` is called when a serialized message is received from a client. +- `handleStreamMessage` is called when a serialized message is received from a Flutter app. -To send a message to a client, call the `sendStreamMessage` method. You will need to include the session associated with the user. +To send a message to a Flutter app, call the `sendStreamMessage` method. You will need to include the session associated with the user. #### The user object @@ -150,7 +150,7 @@ You can access the user object at any time by calling the `getUserObject` method ### Handling streams in your app -Before you can access streams in your client, you need to connect to the server's web socket. You do this by calling connectWebSocket on your client. +Before you can access streams in your Flutter app, you need to connect to the server's web socket. You do this by calling connectWebSocket on your client. ```dart await client.openStreamingConnection(); diff --git a/docs/06-concepts/17-backward-compatibility.md b/docs/06-concepts/17-backward-compatibility.md index 8e1f3597..c5ee5b01 100644 --- a/docs/06-concepts/17-backward-compatibility.md +++ b/docs/06-concepts/17-backward-compatibility.md @@ -43,7 +43,7 @@ In the above example, we created a new `TeamV2` endpoint, which hides the `join` While we may have liked to re-use the `join` method name, Dart inheritance rules do not allow doing so. Otherwise, we would have to write the endpoint from scratch, meaning without inheritance, and re-implement all methods we would like to keep. -In your client, you could then move all usages from `client.team` to `client.teamV2` and eventually (after all clients have upgraded) remove the old endpoint on the server. That means either marking the old endpoint with `@doNotGenerate` on the class or deleting it and moving the re-used method implementations you want to keep to the new V2 endpoint class. +In your Flutter app, you could then move all usages from `client.team` to `client.teamV2` and eventually (after all clients have upgraded) remove the old endpoint on the server. That means either marking the old endpoint with `@doNotGenerate` on the class or deleting it and moving the re-used method implementations you want to keep to the new V2 endpoint class. An alternative pattern to consider would be to move all the business logic for an endpoint into a helper class and then call into that from the endpoint. In case you want to create a V2 version later, you might be able to reuse most of the underlying business logic through that helper class, and don't have to subclass the old endpoint. This has the added benefit of the endpoint class clearly listing all exposed methods, and you don't have to wonder what you inherit from the base class. diff --git a/docs/06-concepts/20-security-configuration.md b/docs/06-concepts/20-security-configuration.md index 84e2b27f..3fff6bd6 100644 --- a/docs/06-concepts/20-security-configuration.md +++ b/docs/06-concepts/20-security-configuration.md @@ -33,9 +33,9 @@ Serverpod( ); ``` -## Client Security Configuration +## Flutter app Security Configuration -When connecting to a **Serverpod server over HTTPS**, the client must be configured to trust the server's certificate. +When connecting to a **Serverpod server over HTTPS**, the Flutter app must be configured to trust the server's certificate. ### Dart Configuration Example