Plugins
=======

flarchitect supports a lightweight plugin system for observing and customising
behaviour at well-defined hook points. Use plugins for cross-cutting concerns
such as auditing, metrics, tenant scoping, or output shaping that shouldn’t
live in route handlers.

Quick start
-----------

1. Implement a plugin by subclassing ``flarchitect.plugins.PluginBase``::

    from flarchitect.plugins import PluginBase

    class AuditPlugin(PluginBase):
        def before_model_op(self, context):
            # e.g. attach actor/tenant to the payload
            data = context.get("deserialized_data") or {}
            if isinstance(data, dict):
                data = {**data, "actor": context.get("request_id")}
                return {"deserialized_data": data}

        def after_model_op(self, context, output):
            # e.g. emit an audit log
            print("AUDIT:", context.get("method"), context.get("model"), output)

2. Register your plugin via Flask config::

    app.config["API_PLUGINS"] = [AuditPlugin()]

Hook reference
--------------

Stable hook signatures (kwargs may grow over time):

- request_started(request: flask.Request) -> None
    Called at the beginning of each request.

- request_finished(request: flask.Request, response: flask.Response) -> flask.Response | None
    Called after a response is created. Return a replacement Response to override.

- before_authenticate(context: dict) -> dict | None
    Runs prior to authentication (for non-schema routes and schema routes alike).
    May return a dict of updates to merge into the context.

- after_authenticate(context: dict, success: bool, user: Any | None) -> None
    Runs after authentication attempt.

- before_model_op(context: dict) -> dict | None
    Runs before a CRUD action. Context includes keys such as ``model``, ``method``,
    ``many``, ``id``, ``field``, ``join_model``, ``output_schema`` and (for POST/PATCH)
    ``deserialized_data``. Return a dict to update the call-time kwargs (e.g., mutate
    ``deserialized_data``).

- after_model_op(context: dict, output: Any) -> Any | None
    Runs after a CRUD action. Return a value to replace the output before serialisation.

- spec_build_started(spec: apispec.APISpec) -> None
    Called when building the OpenAPI specification.

- spec_build_completed(spec_dict: dict) -> dict | None
    Called after the spec is converted to a dictionary. Return a dict to replace it.

Notes
-----

- Plugins are additive: multiple plugins can be installed; they are called in order.
- Returning ``None`` means "no change". Where supported, the first non-``None`` return
  value wins (e.g., response replacement).
- Existing callback config keys (e.g., ``API_SETUP_CALLBACK``) continue to work and
  compose with plugins.