diff --git a/docs/06-concepts/07-configuration.md b/docs/06-concepts/07-configuration.md index 8fee9281..ffc8f927 100644 --- a/docs/06-concepts/07-configuration.md +++ b/docs/06-concepts/07-configuration.md @@ -35,44 +35,46 @@ flowchart TB These can be separately declared for each run mode in the corresponding yaml file (`development.yaml`,`staging.yaml`, `production.yaml` and `testing.yaml`) or as environment variables. -| Environment variable | Config file | Default | Description | -| ---------------------------------------- | ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| SERVERPOD_API_SERVER_PORT | apiServer.port | 8080 | The port number for the API server | -| SERVERPOD_API_SERVER_PUBLIC_HOST | apiServer.publicHost | localhost | The public host address of the API server | -| SERVERPOD_API_SERVER_PUBLIC_PORT | apiServer.publicPort | 8080 | The public port number for the API server | -| SERVERPOD_API_SERVER_PUBLIC_SCHEME | apiServer.publicScheme | http | The public scheme (http/https) for the API server | -| SERVERPOD_INSIGHTS_SERVER_PORT | insightsServer.port | - | The port number for the Insights server | -| SERVERPOD_INSIGHTS_SERVER_PUBLIC_HOST | insightsServer.publicHost | - | The public host address of the Insights server | -| SERVERPOD_INSIGHTS_SERVER_PUBLIC_PORT | insightsServer.publicPort | - | The public port number for the Insights server | -| SERVERPOD_INSIGHTS_SERVER_PUBLIC_SCHEME | insightsServer.publicScheme | - | The public scheme (http/https) for the Insights server | -| SERVERPOD_WEB_SERVER_PORT | webServer.port | - | The port number for the Web server | -| SERVERPOD_WEB_SERVER_PUBLIC_HOST | webServer.publicHost | - | The public host address of the Web server | -| SERVERPOD_WEB_SERVER_PUBLIC_PORT | webServer.publicPort | - | The public port number for the Web server | -| SERVERPOD_WEB_SERVER_PUBLIC_SCHEME | webServer.publicScheme | - | The public scheme (http/https) for the Web server | -| SERVERPOD_DATABASE_HOST | database.host | - | The host address of the database | -| SERVERPOD_DATABASE_PORT | database.port | - | The port number for the database connection | -| SERVERPOD_DATABASE_NAME | database.name | - | The name of the database | -| SERVERPOD_DATABASE_USER | database.user | - | The user name for database authentication | -| SERVERPOD_DATABASE_SEARCH_PATHS | database.searchPaths | - | The search paths used for all database connections | -| SERVERPOD_DATABASE_REQUIRE_SSL | database.requireSsl | false | Indicates if SSL is required for the database | -| SERVERPOD_DATABASE_IS_UNIX_SOCKET | database.isUnixSocket | false | Specifies if the database connection is a Unix socket | -| SERVERPOD_DATABASE_MAX_CONNECTION_COUNT | database.maxConnectionCount | 10 | The maximum number of connections in the database pool. Set to 0 or a negative value for unlimited connections. | -| SERVERPOD_REDIS_HOST | redis.host | - | The host address of the Redis server | -| SERVERPOD_REDIS_PORT | redis.port | - | The port number for the Redis server | -| SERVERPOD_REDIS_USER | redis.user | - | The user name for Redis authentication | -| SERVERPOD_REDIS_ENABLED | redis.enabled | false | Indicates if Redis is enabled | -| SERVERPOD_REDIS_REQUIRE_SSL | redis.requireSsl | false | Indicates if SSL is required for the Redis connection | -| SERVERPOD_MAX_REQUEST_SIZE | maxRequestSize | 524288 | The maximum size of requests allowed in bytes | -| SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED | sessionLogs.persistentEnabled | - | Enables or disables logging session data to the database. Defaults to `true` if a database is configured, otherwise `false`. | -| SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL | sessionLogs.cleanupInterval | 24h | How often to run the log cleanup job. Duration string (e.g. `24h`, `2d`). Set to null to disable automated purging. | -| SERVERPOD_SESSION_LOG_RETENTION_PERIOD | sessionLogs.retentionPeriod | 90d | How long to keep session log entries. Duration string (e.g. `30d`, `60d`). Set to null to disable time-based cleanup. | -| SERVERPOD_SESSION_LOG_RETENTION_COUNT | sessionLogs.retentionCount | 100000 | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. | -| SERVERPOD_SESSION_CONSOLE_LOG_ENABLED | sessionLogs.consoleEnabled | - | Enables or disables logging session data to the console. Defaults to `true` if no database is configured, otherwise `false`. | -| SERVERPOD_SESSION_CONSOLE_LOG_FORMAT | sessionLogs.consoleLogFormat | json | The format for console logging of session data. Valid options are `text` and `json`. Defaults to `text` for run mode `development`, otherwise `json`. | -| SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED | futureCallExecutionEnabled | true | Enables or disables the execution of future calls. | -| SERVERPOD_FUTURE_CALL_CONCURRENCY_LIMIT | futureCall.concurrencyLimit | 1 | The maximum number of concurrent future calls allowed. If the value is negative or null, no limit is applied. | -| SERVERPOD_FUTURE_CALL_SCAN_INTERVAL | futureCall.scanInterval | 5000 | The interval in milliseconds for scanning future calls | -| SERVERPOD_WEBSOCKET_PING_INTERVAL | websocketPingInterval | 30 | The interval in seconds between WebSocket ping messages sent to keep streaming connections alive. Must be a positive integer. | +| Environment variable | Config file | Default | Description | +| ----------------------------------------- | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| SERVERPOD_API_SERVER_PORT | apiServer.port | 8080 | The port number for the API server | +| SERVERPOD_API_SERVER_PUBLIC_HOST | apiServer.publicHost | localhost | The public host address of the API server | +| SERVERPOD_API_SERVER_PUBLIC_PORT | apiServer.publicPort | 8080 | The public port number for the API server | +| SERVERPOD_API_SERVER_PUBLIC_SCHEME | apiServer.publicScheme | http | The public scheme (http/https) for the API server | +| SERVERPOD_INSIGHTS_SERVER_PORT | insightsServer.port | - | The port number for the Insights server | +| SERVERPOD_INSIGHTS_SERVER_PUBLIC_HOST | insightsServer.publicHost | - | The public host address of the Insights server | +| SERVERPOD_INSIGHTS_SERVER_PUBLIC_PORT | insightsServer.publicPort | - | The public port number for the Insights server | +| SERVERPOD_INSIGHTS_SERVER_PUBLIC_SCHEME | insightsServer.publicScheme | - | The public scheme (http/https) for the Insights server | +| SERVERPOD_WEB_SERVER_PORT | webServer.port | - | The port number for the Web server | +| SERVERPOD_WEB_SERVER_PUBLIC_HOST | webServer.publicHost | - | The public host address of the Web server | +| SERVERPOD_WEB_SERVER_PUBLIC_PORT | webServer.publicPort | - | The public port number for the Web server | +| SERVERPOD_WEB_SERVER_PUBLIC_SCHEME | webServer.publicScheme | - | The public scheme (http/https) for the Web server | +| SERVERPOD_DATABASE_HOST | database.host | - | The host address of the database | +| SERVERPOD_DATABASE_PORT | database.port | - | The port number for the database connection | +| SERVERPOD_DATABASE_NAME | database.name | - | The name of the database | +| SERVERPOD_DATABASE_USER | database.user | - | The user name for database authentication | +| SERVERPOD_DATABASE_SEARCH_PATHS | database.searchPaths | - | The search paths used for all database connections | +| SERVERPOD_DATABASE_REQUIRE_SSL | database.requireSsl | false | Indicates if SSL is required for the database | +| SERVERPOD_DATABASE_IS_UNIX_SOCKET | database.isUnixSocket | false | Specifies if the database connection is a Unix socket | +| SERVERPOD_DATABASE_MAX_CONNECTION_COUNT | database.maxConnectionCount | 10 | The maximum number of connections in the database pool. Set to 0 or a negative value for unlimited connections. | +| SERVERPOD_REDIS_HOST | redis.host | - | The host address of the Redis server | +| SERVERPOD_REDIS_PORT | redis.port | - | The port number for the Redis server | +| SERVERPOD_REDIS_USER | redis.user | - | The user name for Redis authentication | +| SERVERPOD_REDIS_ENABLED | redis.enabled | false | Indicates if Redis is enabled | +| SERVERPOD_REDIS_REQUIRE_SSL | redis.requireSsl | false | Indicates if SSL is required for the Redis connection | +| SERVERPOD_MAX_REQUEST_SIZE | maxRequestSize | 524288 | The maximum size of requests allowed in bytes | +| SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED | sessionLogs.persistentEnabled | - | Enables or disables logging session data to the database. Defaults to `true` if a database is configured, otherwise `false`. | +| SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL | sessionLogs.cleanupInterval | 24h | How often to run the log cleanup job. Duration string (e.g. `24h`, `2d`). Set to null to disable automated purging. | +| SERVERPOD_SESSION_LOG_RETENTION_PERIOD | sessionLogs.retentionPeriod | 90d | How long to keep session log entries. Duration string (e.g. `30d`, `60d`). Set to null to disable time-based cleanup. | +| SERVERPOD_SESSION_LOG_RETENTION_COUNT | sessionLogs.retentionCount | 100000 | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. | +| SERVERPOD_SESSION_CONSOLE_LOG_ENABLED | sessionLogs.consoleEnabled | - | Enables or disables logging session data to the console. Defaults to `true` if no database is configured, otherwise `false`. | +| SERVERPOD_SESSION_CONSOLE_LOG_FORMAT | sessionLogs.consoleLogFormat | json | The format for console logging of session data. Valid options are `text` and `json`. Defaults to `text` for run mode `development`, otherwise `json`. | +| SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED | futureCallExecutionEnabled | true | Enables or disables the execution of future calls. | +| SERVERPOD_FUTURE_CALL_CONCURRENCY_LIMIT | futureCall.concurrencyLimit | 1 | The maximum number of concurrent future calls allowed. If the value is negative or null, no limit is applied. | +| SERVERPOD_FUTURE_CALL_SCAN_INTERVAL | futureCall.scanInterval | 5000 | The interval in milliseconds for scanning future calls | +| SERVERPOD_FUTURE_CALL_CHECK_BROKEN_CALLS | futureCall.checkBrokenCalls | - | Enables or disables the automatic check for broken future calls on startup. By default, the server performs an automatic check if there are less than 1000 calls in the database. | +| SERVERPOD_FUTURE_CALL_DELETE_BROKEN_CALLS | futureCall.deleteBrokenCalls | false | Enables or disables the deletion of broken future calls when running the check on startup. | +| SERVERPOD_WEBSOCKET_PING_INTERVAL | websocketPingInterval | 30 | The interval in seconds between WebSocket ping messages sent to keep streaming connections alive. Must be a positive integer. | ### Secrets diff --git a/docs/06-concepts/14-scheduling/04-configuration.md b/docs/06-concepts/14-scheduling/04-configuration.md index afb7d137..5db4d347 100644 --- a/docs/06-concepts/14-scheduling/04-configuration.md +++ b/docs/06-concepts/14-scheduling/04-configuration.md @@ -45,3 +45,45 @@ Example configuration: futureCall: scanInterval: 2000 # Adjust this value based on your server's responsiveness needs ``` + +## Managing broken future calls + +Scheduled future calls can become broken if, before they run, the server is restarted and: + +- The method of a future call spec class is removed, leading to the removal of the previous generated future call execution class. +- The signature of a future call method is changed in a way that will lead to a generated model that fails to deserialize the stored JSON. +- The model that is used as a parameter to a future call method is changed in a way that will lead to failure in the stored JSON deserialization. + +The above cases will lead to runtime errors when trying to execute the future call. Although ensuring backwards compatibility is the responsibility of the developer, Serverpod exposes tools to prevent or remove broken future calls. + +### Check broken calls + +By default, the server will perform a check for broken future calls on startup if there are less than 1000 future calls scheduled in the database. + +This check can be controlled using the `checkBrokenCalls` configuration option. If it is set to `true`, the server will perform a check for broken future calls on startup regardless of the number of calls. If it is set to `false`, the server will not perform a check for broken future calls on startup. + +Example configuration: + +```yaml +checkBrokenCalls: false +``` + +:::tip +The future calls check can be used with the maintenance role to programmatically validate that the server can be restarted without breaking future calls. The process will exit normally, but logs can be inspected to verify that no broken future calls were found. + +```bash +$ dart run bin/main.dart --role maintenance +``` +::: + +### Delete broken calls + +When detecting broken future calls, the server will log a warning, but will not delete them by default. This behavior can be changed by setting the `deleteBrokenCalls` configuration option to `true` (default is `false`). + +This configuration is only valid if the check is executed (either automatically or through explicitly enabling `checkBrokenCalls`). + +Example configuration: + +```yaml +deleteBrokenCalls: false +```