0030: Tutor Implementation for Authorization Schema Discovery
##############################################################

Status
******

**Draft**

Context
*******

`ADR 0019`_ defines two ways to contribute a static authorization schema. An installed Python package registers an ``authz.schema`` entry point whose callable returns the package directories holding its YAML files. Alternatively, a deployment lists directories in the ``OPENEDX_AUTHZ_SCHEMA_DIRECTORIES`` Django setting; the directories listed must be anchored on an installed Python package.

Both `ADR 0019`_ §1 and `ADR 0023`_ §4 describe a third route for site operators: a Tutor plugin that uses an ``openedx-authz-schema`` patch:

.. code-block:: python

   from tutor import hooks

   hooks.Filters.ENV_PATCHES.add_item((
       "openedx-authz-schema",
       """
   schema_version: "1.0"
   priority: 200

   role_extensions:
     - role_id: course_editor
       add_permissions:
         - courses.export_course
   """,
   ))

1. How Tutor renders a patch
============================

Tutor's ``Renderer.patch()`` joins every plugin's contribution to a patch name into a single string and renders it to exactly one file. When two plugins contribute to ``openedx-authz-schema``, their contributions arrive concatenated.

2. Where a rendered file can land
=================================

Tutor mounts three directories into the LMS and CMS containers and their initialisation jobs: the two settings packages at ``lms/envs/tutor`` and ``cms/envs/tutor``, and ``/openedx/config``.

``/openedx/config`` is the directory Tutor already uses for rendered configuration, including ``lms.env.yml`` and ``cms.env.yml``.

Under Kubernetes these directories are ConfigMap mounts. Keys are derived from file basenames, so a subdirectory is flattened. A layout that relies on a subdirectory therefore behaves differently under ``k8s`` than under ``local`` and ``dev``.

Decision
********

1. Discover schema files by filesystem path
============================================

We will add an ``OPENEDX_AUTHZ_SCHEMA_FILES`` Django setting: a list of absolute filesystem paths, each naming one schema file. Discovery will read each listed file directly.

This will require ``src/openedx_authz/engine/schema/discovery.py`` to read from absolute filesystem paths.

2. Read each schema resource as a YAML document stream
======================================================

We will treat every schema resource as a multi-document YAML stream rather than as exactly one document. Each ``---``-separated document is a complete, independent contribution carrying its own ``schema_version`` and ``priority``, exactly as a separate file would.

This keeps a deployment system free to concatenate contributions into one file without their definitions colliding, and preserves the priority arbitration in `ADR 0023`_ §3 when several plugins contribute to the same patch. Empty documents — from empty contributions, trailing separators, or duplicated ``---`` markers — parse as ``None`` via ``yaml.safe_load_all()`` and can be skipped silently.

This will require an update to ``src/openedx_authz/engine/schema/loading.py`` to operate on multi-document streams.

3. Ship the Tutor integration as a plugin
==========================================

We will implement the Tutor integration as a new plugin inside a tutor subfolder in the ``openedx-authz`` repo. The plugin will:

* define the ``openedx-authz-schema`` patch and render its content to a single YAML file. The plugin is responsible for inserting ``---`` separators between contributions — patch authors contribute only their YAML block. The plugin can render the patch with: ``{{ patch('openedx-authz-schema', separator='\n---\n') }}``;
* append that file's path to ``OPENEDX_AUTHZ_SCHEMA_FILES`` through Tutor's Open edX settings patches; and
* ensure the rendered file is present in the LMS and CMS containers and in their initialisation jobs for ``local``, ``dev``, and ``k8s`` deployments.

Example rendered file with two plugin contributions:

.. code-block:: yaml

   schema_version: "1.0"
   priority: 200

   role_extensions:
     - role_id: course_editor
       add_permissions:
         - courses.export_course
       display_name: Course author
       description: Creates and exports course content.
   ---
   schema_version: "1.0"
   priority: 100

   role_extensions:
     - role_id: course_editor
       remove_permissions:
         - courses.manage_tags
       display_name: Course author
       description: Creates and exports course content.

4. Source tracking for filesystem-contributed schemas
=====================================================

Schemas discovered through ``OPENEDX_AUTHZ_SCHEMA_FILES`` have no Python package or module. To satisfy the source-tracking requirements of `ADR 0025`_, their source record uses:

* ``distribution`` = ``<tutor-patch>`` — a sentinel value that is an invalid Python package name, guaranteeing no collision with any installed distribution.
* ``module`` = the absolute filesystem path of the schema file (e.g. ``/openedx/config/authz-schema.yml``). Filesystem sources have no owning Python module, but reusing the path here keeps the ``(distribution, module)`` unique constraint enforceable and avoids the ``NULL``-handling complications that a ``null`` value would introduce across the ORM, migrations, and source-identity logic.
* ``resource_path`` = the absolute filesystem path of the schema file (e.g. ``/openedx/config/authz-schema.yml``).
* ``distribution_version`` = ``0.0.0`` — a sentinel value, since filesystem sources carry no package version.

If multiple files are listed in ``OPENEDX_AUTHZ_SCHEMA_FILES``, they share the same ``(distribution, module)`` identity.

Consequences
************

* Site operators can contribute an authorization schema through Tutor configuration alone, the route `ADR 0019`_ §1 and `ADR 0023`_ §4 describe.
* Contributions from several plugins are preserved with their individual priorities.
* ``openedx-authz`` gains a second discovery path format.

Rejected Alternatives
*********************

Anchor on the Tutor settings package
=====================================

Render the file into the mounted settings directory and list ``lms/envs/tutor`` or ``cms/envs/tutor`` in ``OPENEDX_AUTHZ_SCHEMA_DIRECTORIES``.

* Pros: needs no change to ``openedx-authz``.
* Cons: attributes an operator override to the distribution that ships ``lms``; places non-Python data in a Django settings package.

Point the setting at a filesystem directory
===========================================

Accept filesystem *directories* rather than files, and list ``/openedx/config`` or a subdirectory of it.

* Pros: matches the existing directory-shaped contract more closely.
* Cons: scanning ``/openedx/config`` reads ``lms.env.yml`` and ``cms.env.yml``, which are not authorization schemas and fail validation. A dedicated subdirectory is flattened under Kubernetes ConfigMap mounts, so it works under ``local`` and ``dev`` but not under ``k8s``.

References
**********

* `ADR 0019`_
* `ADR 0023`_
* `ADR 0025`_

.. _ADR 0019: 0019-authorization-schema-discovery.rst
.. _ADR 0023: 0023-extend-static-roles.rst
.. _ADR 0025: 0025-authorization-schema-source-tracking.rst
