Global state to `app.state` to enable multiple APIs in a single process #2313

eimrek · 2025-09-22T14:13:56Z

This PR moves the global CONFIG singleton and ENTRY_COLLECTIONS to the Fastapi app.state. This required quite a large refactor, but the default functionality should be retained (so it's fully backwards compatible).

Now, there is the create_app function that allows to create multiple apps with different configs. So one could use something like

from fastapi import FastAPI

from optimade.server.config import ServerConfig
from optimade.server.create_app import create_app

app = FastAPI()


@app.get("/")
def read_main():
   return {"message": "Hello World from main app"}


base_url = "http://127.0.0.1:8000"

conf1 = ServerConfig()
conf1.base_url = f"{base_url}/app1"
app1 = create_app(conf1)
app.mount("/app1", app1)

conf2 = ServerConfig()
conf2.base_url = f"{base_url}/app2"
app2 = create_app(conf2)
app.mount("/app2", app2)

conf3 = ServerConfig()
conf3.base_url = f"{base_url}/ind"
app3 = create_app(conf3, index=True)
app.mount("/ind", app3)

which starts two different optimade APIs and an index metadb API.

codecov · 2025-09-22T21:39:55Z

Codecov Report

❌ Patch coverage is 85.41667% with 63 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.65%. Comparing base (1d2add7) to head (287ef4e).

Files with missing lines	Patch %	Lines
optimade/server/routers/landing.py	13.33%	26 Missing ⚠️
optimade/server/create_app.py	90.29%	13 Missing ⚠️
optimade/server/entry_collections/mongo.py	75.60%	10 Missing ⚠️
optimade/server/logger.py	79.48%	8 Missing ⚠️
optimade/server/entry_collections/elasticsearch.py	91.30%	2 Missing ⚠️
optimade/server/mappers/entries.py	97.10%	2 Missing ⚠️
optimade/server/routers/utils.py	94.11%	1 Missing ⚠️
optimade/utils.py	85.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2313      +/-   ##
==========================================
- Coverage   90.66%   90.65%   -0.01%     
==========================================
  Files          75       75              
  Lines        4980     5021      +41     
==========================================
+ Hits         4515     4552      +37     
- Misses        465      469       +4

Flag	Coverage Δ
project	`90.65% <85.41%> (-0.01%)`	⬇️
validator	`90.65% <85.41%> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

eimrek · 2025-09-22T21:59:39Z

@ml-evs i think this is ready for review. The only thing failing is the build of optimade-validator-action, which should not really be related to this PR. Initially it failed due to missing pyyaml, now it's not building because of something else. I wonder how it build in the previous commits to this repo. any ideas?

ml-evs · 2025-09-23T08:34:15Z

You should be able to ignore the validator action errors, I'll make an effort to merge some thing on that end today and we'll see if this turns green.

ml-evs · 2025-09-23T08:44:01Z

(Just rebased with the changes from #2308)

ml-evs · 2025-09-23T13:04:12Z

@ml-evs i think this is ready for review. The only thing failing is the build of optimade-validator-action, which should not really be related to this PR. Initially it failed due to missing pyyaml, now it's not building because of something else. I wonder how it build in the previous commits to this repo. any ideas?

Somehow the validator now touches the server config when called via the validator action, whereas before it didn't (and thus didnt need yaml). Might have to be careful when unpicking that one...

ml-evs · 2025-09-23T13:06:07Z

optimade/server/mappers/entries.py

+from typing import Any, Literal

 from optimade.models.entries import EntryResource
+from optimade.server.config import ServerConfig


here's what was causing the validator failures

Ok, thanks! i'm not fully understanding why but i guess it's not important.

Previously the config import was nested under the methods that needed it, so even if the validator-action imported the mappers, it never used them so it didn't import the config. Now just importing the config class triggers import yaml at the top of server.config so we hit issues. I'm not against just making yaml required for non-server stuff

Ok, I see. yep, i don't really feel strongly about this, so we can maybe keep it as it's now.

I think likely this can even be removed from the validator as part of a future separation, so yeah don't think there's anything to change here. Generally, I can't see anything obviously wrong with this PR but will need to test.

Would you able to try this out on your end with MCA on this before we merge?

ok, sure, yes, I can test it out a bit more for MC deployments.

ml-evs

Hi @eimrek, got about halfway through a review.

Some general comments:

The mapper stuff is definitely a breaking change (at least for my usage in odbx etc.) and I'd want to double-check the effect on performance before merging (i.e., needing to create a mapper instance every request just to parse the query params). If its minimal (likely it is) then I'm happy to include this as it does simplify things.
This PR removes the functionality for CONFIG.VALIDATE_API_RESPONSE, which was added to allow non-compliant databases to still host their best guess at OPTIMADE data, for example NOMAD including a "D" in chemical formulae. I'm not sure if its possible to override this in a way that works with the new config (e.g., if there's a FastAPI-native setting we can use to disable validation on a per API basis) but I think this is still required.
Can you also write a little docs page about this under the "Deployment" section for running multiple APIs that use different dbs/collections?

optimade/server/config.py

optimade/server/create_app.py

optimade/server/entry_collections/elasticsearch.py

ml-evs · 2025-09-24T12:50:33Z

optimade/server/logger.py

 LOGGER = logging.getLogger("optimade")
 LOGGER.setLevel(logging.DEBUG)

+CONFIG = ServerConfig()


Presumably this means you can't define per-API log config? I guess the import error stuff will never trigger either. I'm not against simplifying all this by not exposing LOGGER

Right, this probably should be improved. it would be great to have a per-api log. I am not fully sure how to do this the best way, i can look into it.

ml-evs · 2025-09-24T12:53:34Z

optimade/server/query_params.py

+                    if prefix in BaseResourceMapper().SUPPORTED_PREFIXES:
                        errors.append(param)
-                    elif prefix not in BaseResourceMapper.KNOWN_PROVIDER_PREFIXES:
+                    elif prefix not in BaseResourceMapper().KNOWN_PROVIDER_PREFIXES:


I don't like that we have to initialize a class per request just to check query parameters, I'd probably prefer needing to pass the app config into this method instead

whoops, yes, this doesn't look correct either... i'll pass in the BaseResourceMapper instance perhaps?

ended up storing the base_resource_mapper in app.state. so that the cache is used as well.

ml-evs · 2025-09-24T12:55:16Z

optimade/server/query_params.py

                ge=0,
            ),
-        ] = CONFIG.page_limit,
+        ] = 20,


Fine, as long as the configured default page limit is enforced elsewhere

ml-evs · 2025-09-24T12:58:23Z

optimade/server/routers/references.py

-    if CONFIG.validate_api_response
-    else dict[str, Any],
+    response_model=ReferenceResponseMany,


This is actually quite important to keep, not sure how to approach it with the new config mechanism

I think I could retain this by doing CONFIG = ServerConfig() at the start of this module. This basically means that you take the default config (as before) for these global settings. But allow to override (other things) per-api config, if needed.

eimrek · 2025-09-29T13:28:38Z

@ml-evs I think now it's in a better shape. Would be great to have another review.

The idea is that the main way of using is still the same - config is read either from the ENV variables or the JSON file. However, now, with the create_app function, one can, if they want to, override config for any specific app, allowing to set different base urls and optimade db that at crucial for serving multiple APIs.

I also re-did logging such that you can specify a tag that allows one to differentiate logs from different apps.

Finally, I also updates a bit the docs and added some description on how to run multiple apps.

This reverts commit 92fd22d.

Co-authored-by: Matthew Evans <[email protected]>

…fixes

eimrek requested review from CasperWA and ml-evs as code owners September 22, 2025 14:13

eimrek force-pushed the cfg-to-app-state branch from cc34495 to 2ade55d Compare September 22, 2025 21:45

ml-evs force-pushed the cfg-to-app-state branch from aa93eac to 64ee79e Compare September 23, 2025 08:43

ml-evs mentioned this pull request Sep 23, 2025

Upcoming releases #2314

Open

ml-evs force-pushed the cfg-to-app-state branch from 55a8f62 to 01fbae2 Compare September 23, 2025 12:39

ml-evs reviewed Sep 23, 2025

View reviewed changes

ml-evs reviewed Sep 24, 2025

View reviewed changes

eimrek force-pushed the cfg-to-app-state branch from 84205f9 to 65c5b64 Compare September 28, 2025 18:40

eimrek force-pushed the cfg-to-app-state branch from 0c50466 to 699e6f4 Compare September 29, 2025 13:29

eimrek and others added 14 commits October 1, 2025 12:51

mv global singletons to app.state

0c08f51

fix tests

4f0e0ec

fix tests for real mongodb

5821b6f

fix tests for elasticsearch

04959a8

ci: update optimade-validator-action

c08240d

Revert "ci: update optimade-validator-action"

0ac3e17

This reverts commit 92fd22d.

Unpin validator-action

128dd39

Promote pyyaml back to core dep

6c15eaa

Update optimade/server/config.py

1d3999f

Co-authored-by: Matthew Evans <[email protected]>

Update optimade/server/create_app.py

e252e3e

Co-authored-by: Matthew Evans <[email protected]>

Update optimade/server/create_app.py

55b2055

Co-authored-by: Matthew Evans <[email protected]>

dont import elasticsearch; tiny fix

8232840

rm unused variable

61fc577

store base_resource_mapper in app.state

454e580

eimrek added 9 commits October 1, 2025 12:51

restore CONFIG.validate_api_response

738a419

restore config.debug tests

728cc79

skip data inject if data already exists

fb1739c

add a test for mounting subapis

60984f4

elasticsearch len 0 if collection doesn't exist

f28bd86

app-specific logger

caa7bcc

docs: update materials cloud use case

af6e0dc

docs: create_app docstring, multiple_apps section, and integrated.md …

a49ea1a

…fixes

reduce landing.py verbosity

287ef4e

eimrek force-pushed the cfg-to-app-state branch from db845b3 to 287ef4e Compare October 1, 2025 10:51

Uh oh!

Global state to app.state to enable multiple APIs in a single process #2313

Are you sure you want to change the base?

Global state to app.state to enable multiple APIs in a single process #2313

Uh oh!

Conversation

eimrek commented Sep 22, 2025

Uh oh!

codecov bot commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

eimrek commented Sep 22, 2025

Uh oh!

ml-evs commented Sep 23, 2025

Uh oh!

ml-evs commented Sep 23, 2025

Uh oh!

ml-evs commented Sep 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ml-evs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eimrek Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eimrek commented Sep 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Global state to `app.state` to enable multiple APIs in a single process #2313

Global state to `app.state` to enable multiple APIs in a single process #2313

codecov bot commented Sep 22, 2025 •

edited

Loading

eimrek Sep 24, 2025 •

edited

Loading