doc: add the documentation

Author: azmeuk

.readthedocs.yml

@@ -0,0 +1,15 @@
+---
+version: 2
+sphinx:
+  configuration: doc/conf.py
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.14"
+python:
+  install:
+    - method: uv
+      command: sync
+      groups:
+        - doc
+      extras: all

README.md

@@ -1,85 +1,98 @@
 # scim2-server
 
-This is an example WSGI-SCIM server using [scim2-models](https://github.com/python-scim/scim2-models).
-It utilizes [werkzeug](https://werkzeug.palletsprojects.com/) and keeps all resources in-memory,
-they are lost once the process exits.
+A Python library that serves the SCIM protocol over any storage, built upon
+[scim2-models](https://scim2-models.readthedocs.io), following the
+[RFC7643](https://datatracker.ietf.org/doc/html/rfc7643.html) and
+[RFC7644](https://datatracker.ietf.org/doc/html/rfc7644.html) specifications.
+It validates the requests, applies them to the resources and builds the responses.
+The application only reads and writes the resources.
+
+It comes with an in-memory storage, WSGI and ASGI applications with no dependency, and a
+`scim2-server` command that serves a test server.
+
+## Who is it for?
+
+scim2-server is for projects that need to:
+
+- serve a standalone SCIM server;
+- add SCIM to an existing application, with SCIM models that describe its data;
+- test a SCIM client against a working server, from the `scim2-server` command, a container, or
+  the [pytest-scim2-server](https://github.com/pytest-dev/pytest-scim2-server) fixture.
+
+## What's SCIM anyway?
+
+SCIM stands for System for Cross-domain Identity Management, and it is a provisioning protocol.
+Provisioning is the action of managing a set of resources across different services, usually users and groups.
+SCIM is often used between Identity Providers and applications in completion of standards like OAuth2 and OpenID Connect.
+It allows users and groups creations, modifications and deletions to be synchronized between applications.
 
 ## Features
 
-- [x] Discovery endpoints (`/v2/ServiceProviderConfig`, `/v2/ResourceTypes`, `/v2/Schemas`)
-- [x] Create/Read/Update/Delete resources (`POST`, `GET`, `PUT`, `DELETE`)
-- [x] Searching & Filtering
-- [x] Support for ETags
-- [x] Unique Constraints
-- [x] HTTP PATCH (Add/Remove/Replace)
-- [x] Sorting
-- [x] Bulk operations
-- [x] Multi-tenancy with a URL prefix
+- **Resources**: creation, read, replacement, PATCH and deletion
+- **Search**: filters, sorting, paging and attribute selection, on a resource type or at the root
+- **Bulk requests**: with `bulkId` references and `failOnErrors`
+- **ETags**: conditional requests and protection against concurrent writes
+- **Discovery**: `ServiceProviderConfig`, `ResourceTypes` and `Schemas`
+- **Storages**: an interface to implement, an in-memory storage, and a test suite that checks a storage
+- **Sync & Async**: a synchronous and an asynchronous handler, over the same rules
+- **Multi-tenancy**: one set of resources per URL prefix
 
-## Usage
+## Installation
 
 ```shell
-$ scim2-server [-h] [--schema SCHEMA] [--resource-type RESOURCE_TYPE] [--service-provider-config SERVICE_PROVIDER_CONFIG] [--bearer-token BEARER_TOKEN] [--hostname HOSTNAME] [--port PORT] [--reverse-proxy] [--dump-resources DUMP_RESOURCES] [--tenant TENANT] [--dynamic-tenants] [--debug]
+pip install scim2-server
 ```
 
-- `-h`/`--help`: Show help message
-- `--reverse-proxy`: Allow using the provider behind a Reverse Proxy (required for URL rewriting).
-- `--schema`: Register schemas from specified JSON file. If not provided, loads the default schemas from RFC 7643.
-- `--resource-type`: Register resource types from specified JSON file. If not provided, loads the default resource types from RFC 7643.
-- `--service-provider-config`: Load the service provider configuration from specified JSON file. If not provided, loads the default configuration.
-- `--bearer-token`: Registers a bearer token that can be used for accessing the service, and announces the bearer token authentication scheme. If no tokens are provided, anonymous access without authentication is allowed.
-- `--hostname`: The hostname to listen on. Defaults to `127.0.0.1`.
-- `--port`: The port to listen on. Defaults to `8080`.
-- `--dump-resources`: Dump a JSON document containing all resources when the provider exits normally. With tenants, the document has one entry per tenant.
-- `--tenant`: Serve a tenant under `/<tenant>`, for example `/<tenant>/v2/Users`. Can be repeated. See [Multi-tenancy](#multi-tenancy).
-- `--dynamic-tenants`: Create a tenant on the first request to `/<tenant>`. See [Multi-tenancy](#multi-tenancy).
-- `--debug`: Enable the interactive Werkzeug debugger, the reloader and the logging of the WSGI environment of each request. The debugger allows arbitrary code execution and the environment contains the bearer tokens, so never use this option on a server reachable by others.
-
-### Multi-tenancy
-
-With `--tenant` or `--dynamic-tenants`, the first segment of the URL path selects a tenant (RFC 7644 §6.1).
-Each tenant has its own resources: `/a/v2/Users` and `/b/v2/Users` are separate, and uniqueness, filters and pagination only consider the resources of the tenant.
-The schemas, the resource types and the service provider configuration are the same for every tenant, and so are the bearer tokens.
-A request without a known tenant gets a 404 answer, and `v2` cannot be a tenant name.
+## Usage
+
+Serve a test server from the command line:
 
 ```shell
-$ scim2-server --tenant a --tenant b
-$ curl http://localhost:8080/a/v2/Users
+scim2-server --port 8080
 ```
 
-With `--dynamic-tenants`, the first request to an unknown tenant creates it with no resources.
-This is useful for tests: each test can pick a random tenant and get an empty server.
-Any client can then create tenants, even without a valid bearer token, and every tenant stays in memory until the server exits.
-Do not use this option on a server reachable by untrusted clients.
+Or build the WSGI application in Python:
 
-In Python, `scim2_server.tenants.TenantDispatcher` builds one `SCIMApplication` per tenant from a factory, on the first request to the tenant.
-The factory gets the tenant name and returns `None` when the tenant does not exist.
-Override its `select_tenant` method to read the tenant from a header or a sub-domain instead.
+```python
+from scim2_server.applications.wsgi import WSGIApplication
+from scim2_server.memory import InMemoryStorage
+from scim2_server.utils import load_default_provider
 
-### Container
+app = WSGIApplication(InMemoryStorage(), load_default_provider())
+```
 
-A container image is published on the GitHub container registry for each release.
-The server listens on `0.0.0.0:8080` inside the container, and the command line arguments are passed to `scim2-server`:
+A container image is published on the GitHub container registry for each release:
 
 ```shell
-$ docker run --publish 8080:8080 ghcr.io/python-scim/scim2-server --bearer-token secret
+docker run --publish 8080:8080 ghcr.io/python-scim/scim2-server --bearer-token secret
 ```
 
-To build the image yourself, use `docker build --file Containerfile .` or `podman build .`.
+The server has been tested against a live
+[Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/scim-validator-tutorial)
+system and a live
+[Okta](https://developer.okta.com/docs/guides/scim-provisioning-integration-test/main/) system.
 
-## Notes
+## Documentation
 
-This provider can be used as a starting point if you want to implement a SCIM provider. You should probably change the following things, if you want to use it in production:
+- [Overview](https://scim2-server.readthedocs.io/en/latest/overview.html) introduces the parts of
+  a SCIM server, from the description of the service to the test server.
+- [How-to guides](https://scim2-server.readthedocs.io/en/latest/how-to/index.html) cover focused
+  tasks, such as writing a storage or integrating a web framework.
+- [Explanation](https://scim2-server.readthedocs.io/en/latest/explanation/index.html) covers the
+  layers of the server, the writes of resources and the bulk requests.
+- [Reference](https://scim2-server.readthedocs.io/en/latest/reference.html) lists the public API
+  and the options of the `scim2-server` command.
 
-- Use a proper production WSGI server instead of the one provided by Werkzeug
-- Implement your own storage as a subclass of `scim2_server.storage.ScimStorage`, and check it with `scim2_server.testing.ScimStorageContract`
-- Implement proper authorization with OAuth instead of public access or static bearer tokens
-- Support the `/Me` endpoint, if it applies in your use case
+## Contributing
 
-The provider in its current state has been tested successfully against a live
-[Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/scim-validator-tutorial)
-system as well as a live
-[Okta](https://developer.okta.com/docs/guides/scim-provisioning-integration-test/main/) system.
+The [contribution page](https://scim2-server.readthedocs.io/en/latest/contributing.html)
+describes how to run the tests, the style checks and the documentation build.
+
+scim2-server belongs in a collection of SCIM tools developed by [Yaal Coop](https://yaal.coop),
+with [scim2-models](https://github.com/python-scim/scim2-models),
+[scim2-client](https://github.com/python-scim/scim2-client),
+[scim2-tester](https://github.com/python-scim/scim2-tester) and
+[scim2-cli](https://github.com/python-scim/scim2-cli).
 
 ## Origins
 

doc/__init__.py

@@ -0,0 +1,55 @@
+import json
+from urllib.parse import parse_qsl
+
+from scim2_models import SCIMException
+
+from scim2_server.handler import AsyncScimHandler
+from scim2_server.memory import AsyncInMemoryStorage
+from scim2_server.requests import ScimRequest
+from scim2_server.responses import ScimResponse
+from scim2_server.service import ScimService
+from scim2_server.utils import load_default_provider
+
+service = ScimService(load_default_provider())
+handler = AsyncScimHandler(service, AsyncInMemoryStorage())
+
+
+async def asgi_to_scim_request(scope, receive):
+    """Turn an ASGI request into a SCIM request."""
+    headers = [(name.decode(), value.decode()) for name, value in scope["headers"]]
+    body = b""
+    while True:
+        message = await receive()
+        body += message.get("body", b"")
+        if not message.get("more_body"):
+            break
+    return ScimRequest(
+        method=scope["method"],
+        base_url=f"{scope['scheme']}://{dict(headers)['host']}{scope['root_path']}",
+        path=scope["path"],
+        query=dict(parse_qsl(scope["query_string"].decode())),
+        headers=headers,
+        body=body,
+    )
+
+
+async def scim_to_asgi_response(response: ScimResponse, send):
+    """Send a SCIM response as an ASGI response."""
+    body = b"" if response.body is None else json.dumps(response.body).encode()
+    await send(
+        {
+            "type": "http.response.start",
+            "status": response.status,
+            "headers": [(k.encode(), v.encode()) for k, v in response.headers.items()],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})
+
+
+async def application(scope, receive, send):
+    """Serve the SCIM endpoints at the root of the application."""
+    try:
+        response = await handler.handle(await asgi_to_scim_request(scope, receive))
+    except SCIMException as exception:
+        response = service.error_response(exception)
+    await scim_to_asgi_response(response, send)

doc/_examples/__init__.py

@@ -0,0 +1,142 @@
+import sqlite3
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import UTC
+from datetime import datetime
+from typing import Any
+
+import aiosqlite
+from scim2_models import NotFoundException
+from scim2_models import PreconditionFailedException
+from scim2_models import Resource
+from scim2_models import ResourceType
+from scim2_models import SearchRequest
+from scim2_models import UniquenessException
+
+from doc._examples.library_storage import TABLES
+from scim2_server.storage import AsyncScimStorage
+
+
+class AsyncLibraryStorage(AsyncScimStorage):
+    """Serve the members and the books of the library, with aiosqlite."""
+
+    def __init__(self, path: str):
+        self.path = path
+        self.connection: aiosqlite.Connection | None = None
+
+    async def connect(self) -> aiosqlite.Connection:
+        """Open the database on the first call."""
+        if self.connection is None:
+            self.connection = await aiosqlite.connect(self.path)
+            self.connection.row_factory = aiosqlite.Row
+        return self.connection
+
+    async def close(self) -> None:
+        """Close the database, when the application stops."""
+        if self.connection is not None:
+            await self.connection.close()
+            self.connection = None
+
+    async def get(self, resource_type: ResourceType, resource_id: str) -> Resource[Any]:
+        table = TABLES[resource_type.name]
+        connection = await self.connect()
+        row = None
+        if resource_id.isdigit():
+            cursor = await connection.execute(
+                f"SELECT * FROM {table.name} WHERE id = ?", (int(resource_id),)
+            )
+            row = await cursor.fetchone()
+        if row is None:
+            raise NotFoundException(
+                detail=f"{resource_type.name} {resource_id} not found"
+            )
+        return table.to_resource(row)
+
+    async def create(
+        self, resource_type: ResourceType, resource: Resource[Any]
+    ) -> Resource[Any]:
+        table = TABLES[resource_type.name]
+        now = datetime.now(UTC).isoformat()
+        row = {
+            **table.to_row(resource),
+            **table.assigned(),
+            "created_at": now,
+            "updated_at": now,
+        }
+        columns = ", ".join(row)
+        values = ", ".join(f":{column}" for column in row)
+        async with self.writing() as connection:
+            cursor = await connection.execute(
+                f"INSERT INTO {table.name} ({columns}) VALUES ({values})", row
+            )
+        return await self.get(resource_type, str(cursor.lastrowid))
+
+    async def update(
+        self,
+        resource_type: ResourceType,
+        resource: Resource[Any],
+        *,
+        expected_version: str | None = None,
+    ) -> Resource[Any]:
+        table = TABLES[resource_type.name]
+        row = {**table.to_row(resource), "updated_at": datetime.now(UTC).isoformat()}
+        assignments = ", ".join(f"{column} = :{column}" for column in row)
+        query = f"UPDATE {table.name} SET {assignments} WHERE id = :id"
+        parameters = {**row, "id": resource.id}
+        if expected_version is not None:
+            query += " AND updated_at = :version"
+            parameters["version"] = expected_version.removeprefix("W/").strip('"')
+        async with self.writing() as connection:
+            cursor = await connection.execute(query, parameters)
+        if cursor.rowcount == 0:
+            await self.get(resource_type, str(resource.id))
+            raise PreconditionFailedException
+        return await self.get(resource_type, str(resource.id))
+
+    async def delete(
+        self,
+        resource_type: ResourceType,
+        resource_id: str,
+        *,
+        expected_version: str | None = None,
+    ) -> None:
+        table = TABLES[resource_type.name]
+        query = f"DELETE FROM {table.name} WHERE id = :id"
+        parameters = {"id": resource_id}
+        if expected_version is not None:
+            query += " AND updated_at = :version"
+            parameters["version"] = expected_version.removeprefix("W/").strip('"')
+        async with self.writing() as connection:
+            cursor = await connection.execute(query, parameters)
+        if cursor.rowcount == 0:
+            await self.get(resource_type, resource_id)
+            raise PreconditionFailedException
+
+    @asynccontextmanager
+    async def writing(self) -> AsyncIterator[aiosqlite.Connection]:
+        """Commit a write, and refuse a value that a UNIQUE column already holds."""
+        connection = await self.connect()
+        try:
+            yield connection
+            await connection.commit()
+        except sqlite3.IntegrityError:
+            await connection.rollback()
+            raise UniquenessException from None
+
+    async def search(
+        self, resource_types: list[ResourceType], search_request: SearchRequest[Any]
+    ) -> tuple[int, list[Resource[Any]]]:
+        connection = await self.connect()
+        found: list[Resource[Any]] = []
+        for resource_type in resource_types:
+            table = TABLES[resource_type.name]
+            cursor = await connection.execute(f"SELECT * FROM {table.name} ORDER BY id")
+            found += [table.to_resource(row) for row in await cursor.fetchall()]
+        if search_request.filter is not None:
+            found = [
+                resource for resource in found if search_request.filter.match(resource)
+            ]
+        found = search_request.sort(found)
+        start = (search_request.start_index or 1) - 1
+        stop = None if search_request.count is None else start + search_request.count
+        return len(found), found[start:stop]