nmdc-runtime 1.3.1__py3-none-any.whl → 2.12.0__py3-none-any.whl

nmdc_runtime/api/swagger_ui/assets/style.css

@@ -0,0 +1,155 @@
+.nmdc-info {
+    padding: 1em;
+    background-color: #448aff1a;
+    border: .075rem solid #448aff;
+    border-radius: 4px;
+}
+.nmdc-info-token code {
+    font-size: x-small;
+}
+.nmdc-success {
+    color: green;
+}
+.nmdc-error {
+    color: red;
+}
+
+/**
+ * Style the NMDC logo we add to the top of the Swagger UI page via JavaScript.
+ *
+ * Notes:
+ * - We set the background size larger than the element size, and then offset
+ *   the background a small amount, so that we do not display the thin border
+ *   that is baked into this SVG image.
+ * - On wide screens, we set the heading group (which contains the logo, and a
+ *   wrapper element—introduced via JavaScript—containing the normal API title
+ *   and link to the OpenAPI schema) to use `display: flex`, so that the logo
+ *   appears next to that wrapper element. On narrow screens, we allow them
+ *   to stack like they normally would.
+ */
+@media screen and (min-width: 768px) {
+    .nmdc-heading-group {
+        display: flex;
+    }
+}
+.nmdc-heading-group .nmdc-logo {
+    width: 64px;
+    height: 64px;
+    margin-right: 16px;
+    background-image: url("/static/NMDC_logo.svg");
+    background-repeat: no-repeat;
+    background-size: 68px 68px;
+    background-position: -2px -2px;
+    border-radius: 4px;
+}
+
+/** 
+ * Hides the following text from the Swagger UI modal login form:
+ *
+ * > Scopes are used to grant an application different levels of
+ * > access to data on behalf of the end user. Each API may declare
+ * > one or more scopes.
+ * > 
+ * > API requires the following scopes. Select which ones you want
+ * > to grant to Swagger UI.
+ *
+ * TODO: Check whether this text can be hidden via standard
+ *       Swagger UI configuration, rather than custom CSS.
+ */
+.auth-wrapper .modal-ux-content .auth-container .scope-def {
+    display: none;
+}
+
+/** 
+ * Hides the following text from the Swagger UI modal login form:
+ *
+ * > Scopes are used to grant an application different levels of
+ * > access to data on behalf of the end user. Each API may declare
+ * > one or more scopes.
+ * > 
+ * > API requires the following scopes. Select which ones you want
+ * > to grant to Swagger UI.
+ *
+ * TODO: Check whether this text can be hidden via standard
+ *       Swagger UI configuration, rather than custom CSS.
+ */
+.auth-wrapper .modal-ux-content .auth-container .scope-def {
+    display: none;
+}
+
+/**
+ * Style the ORCID Login widget we inject via JavaScript into the
+ * Swagger UI modal login form.
+ */
+.auth-container.nmdc-orcid-login {
+    padding-bottom: 20px;
+    font-size: 14px;
+ }
+.auth-container.nmdc-orcid-login .nmdc-orcid-login-icon-link {
+    display: flex;
+    align-items: center;
+    gap: 0.5em;
+}
+.auth-container.nmdc-orcid-login .nmdc-orcid-login-icon-link > a {
+    color: #4990e2;
+    text-decoration: none;
+}
+.auth-container.nmdc-orcid-login .nmdc-orcid-login-icon-link > a:hover {
+    color: #1f69c0;
+}
+
+/**
+ * In the tag description, hide the details portion (i.e. the portion the user
+ * can toggle the visibility of), and color the hyperlinks the same as in
+ * the overall introductory text at the top of the Swagger UI page.
+ */
+.tag-description-details.hidden {
+    display: none;
+}
+ .tag-description-details a {
+    color: #4990e2;
+}
+.tag-description-details a:hover {
+    color: #1f69c0;
+}
+
+/*****************************************************************************
+ * Customize Swagger UI's default elements.
+ *****************************************************************************/
+
+ /* Standardize the line height of the description in the top section of the page. */
+.swagger-ui .information-container .info__description {
+    line-height: 1em;
+}
+/* Slightly deemphasize the version numbers in the description. */
+.swagger-ui .information-container .info__description code {
+    font-weight: normal;
+}
+
+/* Remove the box shadow from the top section of the page. */
+.swagger-ui .scheme-container {
+    box-shadow: none;
+}
+/* Draw a border around each section. */
+.swagger-ui div.opblock-tag-section {
+    border: 1px solid rgba(59,65,81,.3);
+    border-radius: 4px;
+    padding-top: 15px;
+    padding-left: 15px;
+    padding-right: 15px;
+    margin-bottom: 15px;
+}
+/* Stack the elements of each section header vertically. */
+.swagger-ui .opblock-tag {
+    flex-direction: column;
+    align-items: stretch;
+    border-bottom: none;
+}
+.swagger-ui .opblock-tag:hover {
+    background-color: transparent;
+}
+/* Remove the left margin from the description and chevron icon rows. */
+.swagger-ui .opblock-tag > small,
+.swagger-ui .opblock-tag > button {
+    padding-left: 0;
+}

nmdc_runtime/api/swagger_ui/swagger_ui.py

@@ -0,0 +1,34 @@
+"""Constants related to configuring Swagger UI."""
+
+# Reference: https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/#parameters
+base_swagger_ui_parameters: dict = {
+    "withCredentials": True,
+    # Collapse the "Schemas" section by default.
+    # Note: `-1` would omit the section entirely.
+    "defaultModelsExpandDepth": 0,
+    # Display the response times of the requests performed via "Try it out".
+    # Note: In my local testing, the response times reported by this
+    #       are about 50-100ms longer than the response times reported
+    #       by Chrome DevTools. That is the case whether the actual
+    #       response time is short (e.g. 100ms) or long (e.g. 60s);
+    #       i.e. not proportional to the actual response time.
+    "displayRequestDuration": True,
+    # Expand all tag sections (i.e. groups of endpoints) by default.
+    # Note: `"list"` expands them, and `"none"` collapses them.
+    "docExpansion": "list",
+    # Make it so a logged-in user remains logged in even after reloading
+    # the web page (or leaving the web page and revisiting it later).
+    "persistAuthorization": True,
+    # Specify the Swagger UI plugins we want to use (see note below).
+    #
+    # Note: FastAPI's `get_swagger_ui_html` function always serializes
+    #       the value of this property as a _string_, while the Swagger UI
+    #       JavaScript code requires it to be an _array_. To work around that,
+    #       we just add a placeholder string here; then, after we pass this
+    #       dictionary to FastAPI's `get_swagger_ui_html` function and get the
+    #       returned HTML for the web page, we replace this placeholder string
+    #       (within the returned HTML) with the JavaScript array we wanted
+    #       the "plugins" property to contain all along.
+    #
+    "plugins": r"{{ NMDC_SWAGGER_UI_PARAMETERS_PLUGINS_PLACEHOLDER }}",
+}

nmdc_runtime/config.py

@@ -0,0 +1,56 @@
+"""
+This module acts as a unified interface between the codebase and the environment.
+We will eventually move all of the Runtime's environment variables reads into this
+module, instead of leaving them sprinkled throughout the codebase.
+
+TODO: Move all environment variable reads into this module and update references accordingly.
+"""
+
+from typing import Set
+import os
+
+
+def is_env_var_true(name: str, default: str = "false") -> bool:
+    r"""
+    Checks whether the value of the specified environment variable
+    meets our criteria for true-ness.
+
+    Reference: https://docs.python.org/3/library/os.html#os.environ
+
+    Run doctests via: $ python -m doctest nmdc_runtime/config.py
+
+    >>> import os
+    >>> name = "EXAMPLE_ENV_VAR"
+    >>> os.unsetenv(name)  # Undefined
+    >>> is_env_var_true(name)
+    False
+    >>> is_env_var_true(name, "true")  # Undefined, overridden default
+    True
+    >>> os.environ[name] = "false"  # Defined as false
+    >>> is_env_var_true(name)
+    False
+    >>> os.environ[name] = "true"  # Defined as true
+    >>> is_env_var_true(name)
+    True
+    >>> os.environ[name] = "TRUE"  # Case-insensitive
+    >>> is_env_var_true(name)
+    True
+    >>> os.environ[name] = "potato"  # Non-boolean string
+    >>> is_env_var_true(name)
+    False
+    """
+    lowercase_true_strings: Set[str] = {"true"}
+    return os.environ.get(name, default).lower() in lowercase_true_strings
+
+
+# Feature flag to enable/disable the `/nmdcschema/linked_instances` endpoint and the tests that target it.
+IS_LINKED_INSTANCES_ENDPOINT_ENABLED: bool = is_env_var_true(
+    "IS_LINKED_INSTANCES_ENDPOINT_ENABLED", default="true"
+)
+
+# Feature flag that can be used to enable/disable the `/scalar` endpoint.
+IS_SCALAR_ENABLED: bool = is_env_var_true("IS_SCALAR_ENABLED", default="true")
+
+# Feature flag that can be used to enable/disable performance profiling,
+# which can be activated via the `?profile=true` URL query parameter.
+IS_PROFILING_ENABLED: bool = is_env_var_true("IS_PROFILING_ENABLED", default="false")

nmdc_runtime/minter/adapters/repository.py

@@ -2,9 +2,8 @@ import abc
 import re
 from typing import Union
 
-from fastapi import HTTPException
 from pymongo import ReturnDocument
-from toolz import merge, dissoc
+from toolz import merge
 from pymongo.database import Database as MongoDatabase
 
 
@@ -137,6 +136,10 @@ class MongoIDStore(abc.ABC):
         self.db = mdb
 
     def mint(self, req_mint: MintingRequest) -> list[Identifier]:
+        """
+        TODO: Document this method.
+        """
+
         if not self.db["minter.services"].find_one({"id": req_mint.service.id}):
             raise MinterError(f"Unknown service {req_mint.service.id}")
         if not self.db["minter.requesters"].find_one({"id": req_mint.requester.id}):
@@ -191,6 +194,10 @@ class MongoIDStore(abc.ABC):
         return collected
 
     def bind(self, req_bind: BindingRequest) -> Identifier:
+        """Associate the specified arbitrary metadata with the specified ID.
+
+        TODO: Do not allow users to bind identifiers minted by _other_ users.
+        """
         id_stored = self.resolve(req_bind)
         if id_stored is None:
             raise MinterError(f"ID {req_bind.id_name} is unknown")
@@ -208,15 +215,28 @@ class MongoIDStore(abc.ABC):
                 )
 
     def resolve(self, req_res: ResolutionRequest) -> Union[Identifier, None]:
+        """Get the metadata that is bound to the specified identifier."""
         match re.match(r"nmdc:([^-]+)-([^-]+)-.*", req_res.id_name).groups():
             case (_, _):
                 doc = self.db["minter.id_records"].find_one({"id": req_res.id_name})
                 # TODO if draft ID, check requester
+                #
+                #      Note: The above "TODO" comment is about checking whether the user that wants to
+                #            resolve the identifier, is the same user that minted the identifier. If
+                #            it isn't, then... what? (i.e. allow resolution, or deny resolution)?
+                #
                 return Identifier(**doc) if doc else None
             case _:
                 raise MinterError("Invalid ID name")
 
     def delete(self, req_del: DeleteRequest):
+        """Delete an identifier that is still in the draft state.
+
+        Note: You can mint (draft) as many IDs as you want. As long as you don't bind them
+              (i.e. as long as they are still in the draft state), you can still delete them.
+
+        TODO: Do not allow users to delete identifiers minted by _other_ users.
+        """
         id_stored = self.resolve(req_del)
         if id_stored is None:
             raise MinterError(f"ID {req_del.id_name} is unknown")

nmdc_runtime/minter/config.py

@@ -1,8 +1,10 @@
 import os
 from functools import lru_cache
+from typing import List
 
-from nmdc_runtime.util import get_nmdc_jsonschema_dict
+from nmdc_schema.id_helpers import get_typecode_for_future_ids
 
+from nmdc_runtime.util import get_nmdc_jsonschema_dict
 from nmdc_runtime.api.db.mongo import get_mongo_db
 
 
@@ -12,17 +14,41 @@ def minting_service_id() -> str | None:
 
 
 @lru_cache()
-def typecodes():
+def typecodes() -> List[dict]:
+    r"""
+    Returns a list of dictionaries containing typecodes and associated information derived from the schema.
+
+    Note: In this function, we rely on a helper function provided by the `nmdc-schema` package to extract—from a given
+          class's `id` slot's pattern—the typecode that the minter would use when generating an ID for an instance of
+          that class _today_; regardless of what it may have used in the past.
+
+    >>> typecode_descriptors = typecodes()
+
+    # Test #1: We get the typecode we expect, for a class whose pattern contains only one typecode.
+    >>> any((td["name"] == "sty" and td["schema_class"] == "nmdc:Study") for td in typecode_descriptors)
+    True
+
+    # Tests #2 and #3: We get only the typecode we expect, for a class whose pattern contains multiple typecodes.
+    >>> any((td["name"] == "dgms" and td["schema_class"] == "nmdc:MassSpectrometry") for td in typecode_descriptors)
+    True
+    >>> any((td["name"] == "omprc" and td["schema_class"] == "nmdc:MassSpectrometry") for td in typecode_descriptors)
+    False
+    """
+    id_pattern_prefix = r"^(nmdc):"
+
     rv = []
     schema_dict = get_nmdc_jsonschema_dict()
     for cls_name, defn in schema_dict["$defs"].items():
         match defn.get("properties"):
-            case {"id": {"pattern": p}} if p.startswith("^(nmdc):"):
+            case {"id": {"pattern": p}} if p.startswith(id_pattern_prefix):
+                # Extract the typecode from the pattern.
+                typecode_for_future_ids = get_typecode_for_future_ids(slot_pattern=p)
+
                 rv.append(
                     {
                         "id": "nmdc:" + cls_name + "_" + "typecode",
                         "schema_class": "nmdc:" + cls_name,
-                        "name": p.split(":", maxsplit=1)[-1].split("-", maxsplit=1)[0],
+                        "name": typecode_for_future_ids,
                     }
                 )
             case _:

nmdc_runtime/minter/domain/model.py

@@ -1,9 +1,11 @@
 from enum import Enum
+import re
 from typing import Optional
 
+from base32_lib import base32
 from pydantic import BaseModel, PositiveInt
 
-from nmdc_runtime.minter.config import schema_classes
+from nmdc_runtime.minter.config import schema_classes, typecodes
 
 
 class Entity(BaseModel):
@@ -20,9 +22,29 @@ class ValueObject(BaseModel):
 
 
 class Status(str, Enum):
+    """Status of an identifier.
+
+    Note: These state values were chosen in an attempt to mirror those that DataCite uses for DOIs,
+          which are (currently) "Draft", "Registered", and "Findable" (we use "Indexed" instead).
+          Reference: https://support.datacite.org/docs/doi-states
+    """
+
     draft = "draft"
+    """
+    Draft; i.e., the identifier is reserved for potential use. The identifier can still be deleted.
+    """
+
     registered = "registered"
+    """
+    Registered; i.e., the identifier is in use, but the resource it identifies is not publicly accessible
+    (yet, or anymore). The identifier cannot be deleted.
+    """
+
     indexed = "indexed"
+    """
+    Indexed; i.e., the resource identified by the identifier is publicly accessible (i.e. in the
+    production database). The identifier cannot be deleted.
+    """
 
 
 class MintingRequest(ValueObject):
@@ -71,3 +93,35 @@ class Identifier(Entity):
 class Typecode(Entity):
     schema_class: str
     name: str
+
+
+id_prefix_pattern = rf"(?P<prefix>nmdc)"
+id_typecode_pattern = rf"(?P<typecode>[a-z]{{1,6}})"
+id_shoulder_pattern = rf"(?P<shoulder>[0-9][a-z]{{0,6}}[0-9])"
+id_blade_pattern = rf"(?P<blade>[A-Za-z0-9]+)"
+id_version_pattern = rf"(?P<version>(\.[A-Za-z0-9]+)*)"
+id_locus_pattern = rf"(?P<locus>_[A-Za-z0-9_\.-]+)?"
+id_pattern = (
+    rf"^{id_prefix_pattern}:{id_typecode_pattern}-{id_shoulder_pattern}-"
+    rf"{id_blade_pattern}{id_version_pattern}{id_locus_pattern}$"
+)
+ID_TYPECODE_VALUES = [t["name"] for t in typecodes()]
+id_typecode_pattern_strict = rf"(?P<typecode_strict>({'|'.join(ID_TYPECODE_VALUES)}))"
+id_blade_pattern_strict = rf"(?P<blade_strict>[{base32.ENCODING_CHARS}]+)"
+id_pattern_strict = (
+    rf"^{id_prefix_pattern}:{id_typecode_pattern_strict}-{id_shoulder_pattern}-"
+    rf"{id_blade_pattern_strict}{id_version_pattern}{id_locus_pattern}$"
+)
+id_pattern_strict_compiled = re.compile(id_pattern_strict)
+
+
+def check_valid_ids(ids: list[str]):
+    for id_ in ids:
+        if not re.match(id_pattern, id_):
+            raise ValueError(
+                (
+                    f"Invalid ID format for given ID: '{id_}'.\n\nAn ID must match the pattern: '{id_pattern}'.\n\n"
+                    "See: <https://microbiomedata.github.io/nmdc-schema/identifiers/#ids-minted-for-use-within-nmdc>"
+                )
+            )
+    return ids

nmdc_runtime/minter/entrypoints/fastapi_app.py

@@ -8,7 +8,7 @@ from nmdc_runtime.api.core.util import raise404_if_none
 from nmdc_runtime.api.db.mongo import get_mongo_db
 from nmdc_runtime.api.models.site import get_current_client_site, Site
 from nmdc_runtime.minter.adapters.repository import MongoIDStore, MinterError
-from nmdc_runtime.minter.config import minting_service_id, schema_classes
+from nmdc_runtime.minter.config import minting_service_id
 from nmdc_runtime.minter.domain.model import (
     Identifier,
     AuthenticatedMintingRequest,

nmdc_runtime/mongo_util.py

@@ -0,0 +1,89 @@
+from pymongo.database import Database
+from pymongo.collection import Collection
+from typing import Any, Optional
+from pymongo.client_session import ClientSession
+import inspect
+
+
+def _wrap_with_session(obj: Any, name: str, session: Optional[ClientSession]) -> Any:
+    """
+    Wraps a callable attribute of an object to automatically include a session
+    if the callable accepts a 'session' keyword argument.
+    """
+    attr = getattr(obj, name)
+    if callable(attr):
+        signature = inspect.signature(attr)
+        parameters = signature.parameters
+        accepts_session = any(
+            param.name == "session"
+            for param in parameters.values()
+            if param.kind
+            in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+        )
+
+        def wrapper(*args, **kwargs):
+            if session is not None and accepts_session and "session" not in kwargs:
+                kwargs["session"] = session
+            return attr(*args, **kwargs)
+
+        return wrapper
+    return attr
+
+
+class SessionBoundCollection:
+    """
+    A wrapper around pymongo.collection.Collection that automatically passes a session
+    to methods that accept it.
+    """
+
+    def __init__(self, collection: Collection, session: Optional[ClientSession] = None):
+        self._collection = collection
+        self._session = session
+
+    def __getattr__(self, name: str):
+        return _wrap_with_session(self._collection, name, self._session)
+
+    def __getitem__(self, name: str) -> "SessionBoundCollection":
+        return SessionBoundCollection(self._collection[name], self._session)
+
+
+class SessionBoundDatabase(Database):
+    """
+    A wrapper around pymongo.database.Database that automatically passes a session
+    to methods that accept it.
+    """
+
+    def __init__(self, database: Database, session: Optional[ClientSession] = None):
+        super().__init__(
+            database.client,
+            database.name,
+            database.codec_options,
+            database.read_preference,
+            database.write_concern,
+            database.read_concern,
+        )
+        self._database = database
+        self._session = session
+
+    def __getattr__(self, name: str):
+        return _wrap_with_session(self._database, name, self._session)
+
+    def __getitem__(self, name: str) -> SessionBoundCollection:
+        return SessionBoundCollection(self._database[name], self._session)
+
+    def get_collection(self, name: str, **kwargs) -> SessionBoundCollection:
+        """Get a :class:`~pymongo.collection.Collection` with the given name and options."""
+        collection = super().get_collection(name, **kwargs)
+        return SessionBoundCollection(collection, self._session)
+
+    @property
+    def client(self):
+        return self._database.client
+
+    @property
+    def unbounded(self):
+        return self._database
+
+    @property
+    def name(self):
+        return self._database.name

nmdc_runtime/site/backup/nmdcdb_mongodump.py

@@ -6,7 +6,7 @@ $ nmdcdb-mongodump
 
 import os
 import subprocess
-from datetime import datetime, timezone
+from datetime import datetime
 from pathlib import Path
 from zoneinfo import ZoneInfo
 

nmdc_runtime/site/backup/nmdcdb_mongoexport.py

@@ -16,9 +16,7 @@ from toolz import assoc
 
 from nmdc_runtime.api.core.util import pick
 from nmdc_runtime.api.db.mongo import get_mongo_db
-from nmdc_runtime.site.repository import run_config_frozen__normal_env
-from nmdc_runtime.site.resources import get_mongo
-from nmdc_runtime.util import nmdc_jsonschema, schema_collection_names_with_id_field
+from nmdc_runtime.util import schema_collection_names_with_id_field
 
 
 def collection_stats(mdb: MongoDatabase):