Update docs with info about state sessions (#548)

- Adds config section to describe how to set memory backend
- Update state management section to reference memory backend
- Update deployment section to include session affinity note

docs/api/config.md

@@ -0,0 +1,61 @@
+# Config
+
+## Overview
+
+Mesop is configured at the application level using environment variables.
+
+## Configuration values
+
+Mesop currently only has one configuration value, but more will be added in the future.
+
+### MESOP_STATE_SESSION_BACKEND
+
+Sets the backend to use for caching state data server-side. This makes it so state does
+not have to be sent to the server on every request, reducing bandwidth, especially if
+you have large state objects.
+
+The only backend option available at the moment is `memory`.
+
+Users should be careful when using the `memory` backend. Each Mesop process has their
+own RAM, which means cache misses will be common if there is no session affinity. In
+addition, the amount of RAM must be carefully specified per machine in accordance with
+the expected user traffic and state size.
+
+The safest option for using the `memory` backend is to use a single a process with a
+good amount of RAM. Python is not the most memory efficient, especially data structures
+such as dicts.
+
+The drawback of being limited to a single process is that requests will take longer to
+process since only one request can be handled at a time. This is especially problematic
+if your application contains long running API calls.
+
+If session affinity is available, you can scale up multiple machines, each running
+single processes.
+
+**Default:** `none`
+
+## Usage Examples
+
+### One-liner
+
+You can specify the environment variables before the mesop command.
+
+```sh
+MESOP_STATE_SESSION_BACKEND=memory mesop main.py
+```
+
+### Use a .env file
+
+Mesop also supports `.env` files. This is nice since you don't have to keep setting
+the environment variables. In addition, the variables are only set when the application
+is run.
+
+```sh title=".env"
+MESOP_STATE_SESSION_BACKEND=memory
+```
+
+When you run your Mesop app, the .env file will then be read.
+
+```sh
+mesop main.py
+```

docs/guides/deployment.md

@@ -76,6 +76,20 @@ gcloud run deploy
 
 Follow the instructions and then you should be able to access your deployed app.
 
+### Session Affinity
+
+If you're running Mesop with [MESOP_STATE_SESSION_BACKEND=memory](../api/config.md#mesop_state_session_backend),
+then you will want to enable [session affinity](https://cloud.google.com/run/docs/configuring/session-affinity) in order to utilize the `memory` backend efficiently.
+
+The command should be:
+
+```sh
+gcloud run services update $YOUR_SERVICE --session-affinity
+```
+
+By default gunicorn allocates one worker, but you should double check that gunicorn is
+configured correctly for the `memory` backend.
+
 ## App Engine
 
 This section describes deployment to [Google App Engine](https://cloud.google.com/appengine) using

docs/guides/state_management.md

@@ -134,3 +134,11 @@ class State:
 ### State performance issues
 
 Because the state class is serialized and sent back and forth between the client and server, you should try to keep the state class reasonably sized. For example, if you store a very large string (e.g. base64-encoded image) in state, then it will degrade performance of your Mesop app. Instead, you should try to store large data outside of the state class (e.g. in-memory, filesystem, database, external service) and retrieve the data as needed for rendering.
+
+#### Storing state in memory
+
+Mesop has a feature that allows you to store state in memory rather than passing the
+full state on every request. This may help improve performance when dealing with large
+state objects. The caveat is that storing state in memory contains its own set of
+problems that you must carefully consider. See the [config section](../api/config.md#mesop_state_session_backend)
+for details on how to use this feature.

mkdocs.yml

@@ -68,6 +68,7 @@ nav:
       - Commands:
           - Navigate: api/commands/navigate.md
           - Scroll into view: api/commands/scroll_into_view.md
+      - Config: api/config.md
   - FAQ: faq.md
   - Demo Gallery 🔗: demo.md
   - Blog: