mainframe.scan_cache
====================

.. py:module:: mainframe.scan_cache

.. autoapi-nested-parse::

   Optional cache storage: bounded batches, immutable results, isolated DB pool.



Attributes
----------

.. autoapisummary::

   mainframe.scan_cache.quarantined_entries
   mainframe.scan_cache.requests
   mainframe.scan_cache.latency
   mainframe.scan_cache.rows_written
   mainframe.scan_cache.rows_renewed
   mainframe.scan_cache.cache_size
   mainframe.scan_cache.cache_entries
   mainframe.scan_cache.cache_payload
   mainframe.scan_cache.rows_expired
   mainframe.scan_cache.admission_skips
   mainframe.scan_cache._gate
   mainframe.scan_cache._rate_lock
   mainframe.scan_cache._recent_requests
   mainframe.scan_cache.MAX_REQUESTS_PER_SECOND
   mainframe.scan_cache.MAX_NAMESPACES
   mainframe.scan_cache.CLEANUP_BATCH


Functions
---------

.. autoapisummary::

   mainframe.scan_cache.cache_engine
   mainframe.scan_cache.require_cache
   mainframe.scan_cache.cache_session
   mainframe.scan_cache.configure_transaction
   mainframe.scan_cache.rules_digest
   mainframe.scan_cache.validate_context
   mainframe.scan_cache.validate_lease
   mainframe.scan_cache.lookup
   mainframe.scan_cache.renew_hits
   mainframe.scan_cache.quarantine
   mainframe.scan_cache.writer_lock
   mainframe.scan_cache.generation_for_write
   mainframe.scan_cache.store
   mainframe.scan_cache.expire_entries
   mainframe.scan_cache.maintain_cache


Module Contents
---------------

.. py:data:: quarantined_entries

.. py:data:: requests

.. py:data:: latency

.. py:data:: rows_written

.. py:data:: rows_renewed

.. py:data:: cache_size

.. py:data:: cache_entries

.. py:data:: cache_payload

.. py:data:: rows_expired

.. py:data:: admission_skips

.. py:data:: _gate

.. py:data:: _rate_lock

.. py:data:: _recent_requests
   :type:  collections.deque[float]

.. py:data:: MAX_REQUESTS_PER_SECOND
   :value: 10


.. py:data:: MAX_NAMESPACES
   :value: 8


.. py:data:: CLEANUP_BATCH
   :value: 1000


.. py:function:: cache_engine() -> sqlalchemy.Engine

   Reserve at most one connection per API process, outside the queue pool.


.. py:function:: require_cache() -> None

.. py:function:: cache_session() -> collections.abc.Generator[sqlalchemy.orm.Session, None, None]

.. py:function:: configure_transaction(session: sqlalchemy.orm.Session) -> None

.. py:function:: rules_digest(corpus: dict[str, str]) -> str

.. py:function:: validate_context(context: mainframe.models.scan_cache.CacheContext, rules: mainframe.rules.Rules) -> None

.. py:function:: validate_lease(session: sqlalchemy.orm.Session, scanner: str, lease: mainframe.models.scan_cache.CacheLease, subject: str) -> None

.. py:function:: lookup(session: sqlalchemy.orm.Session, request: mainframe.models.scan_cache.CacheLookup) -> mainframe.models.scan_cache.CacheReply

.. py:function:: renew_hits(session: sqlalchemy.orm.Session, context: mainframe.models.scan_cache.CacheContext, rows: list[mainframe.models.orm.ScanCacheEntry], now: datetime.datetime) -> None

   Coalesce hot-key writes to hourly batches without reviving invalid entries.


.. py:function:: quarantine(session: sqlalchemy.orm.Session, context: mainframe.models.scan_cache.CacheContext, keys: list[mainframe.models.scan_cache.CacheKey]) -> mainframe.models.scan_cache.CacheWriteReply

   Retain evidence and quota accounting; isolate only existing suspect keys.


.. py:function:: writer_lock(session: sqlalchemy.orm.Session, scanner: Literal['yara', 'opengrep']) -> bool

.. py:function:: generation_for_write(session: sqlalchemy.orm.Session, context: mainframe.models.scan_cache.CacheContext) -> mainframe.models.orm.ScanCacheNamespace | None

.. py:function:: store(session: sqlalchemy.orm.Session, context: mainframe.models.scan_cache.CacheContext, values: list[mainframe.models.scan_cache.CacheValue]) -> mainframe.models.scan_cache.CacheWriteReply

.. py:function:: expire_entries(session: sqlalchemy.orm.Session, scanner: Literal['yara', 'opengrep'], current_rules: str) -> int

.. py:function:: maintain_cache(current_rules: str) -> None

   Bound cleanup work per tick; idle caches remain physically bounded too.