lightweb-adapter-sdk 0.1.0__py3-none-any.whl

LICENSE

@@ -0,0 +1,197 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions to
+that Work or Derivative Works thereof, that is intentionally submitted
+to Licensor for inclusion in the Work by the copyright owner or by an
+individual or Legal Entity authorized to submit on behalf of the
+copyright owner. For the purposes of this definition, "submitted" means
+any form of electronic, verbal, or written communication sent to the
+Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work
+and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated
+in this section) patent license to make, have made, use, offer to sell,
+sell, import, and otherwise transfer the Work, where such license
+applies only to those patent claims licensable by such Contributor that
+are necessarily infringed by their Contribution(s) alone or by
+combination of their Contribution(s) with the Work to which such
+Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within
+the Work constitutes direct or contributory patent infringement, then
+any patent licenses granted to You under this License for that Work
+shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work
+or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You meet the
+following conditions:
+
+  (a) You must give any other recipients of the Work or Derivative
+  Works a copy of this License; and
+
+  (b) You must cause any modified files to carry prominent notices
+  stating that You changed the files; and
+
+  (c) You must retain, in the Source form of any Derivative Works that
+  You distribute, all copyright, patent, trademark, and attribution
+  notices from the Source form of the Work, excluding those notices
+  that do not pertain to any part of the Derivative Works; and
+
+  (d) If the Work includes a "NOTICE" text file as part of its
+  distribution, then any Derivative Works that You distribute must
+  include a readable copy of the attribution notices contained within
+  such NOTICE file, excluding those notices that do not pertain to any
+  part of the Derivative Works, in at least one of the following
+  places: within a NOTICE text file distributed as part of the
+  Derivative Works; within the Source form or documentation, if
+  provided along with the Derivative Works; or, within a display
+  generated by the Derivative Works, if and wherever such third-party
+  notices normally appear. The contents of the NOTICE file are for
+  informational purposes only and do not modify the License. You may
+  add Your own attribution notices within Derivative Works that You
+  distribute, alongside or as an addendum to the NOTICE text from the
+  Work, provided that such additional attribution notices cannot be
+  construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated
+in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work by
+You to the Licensor shall be under the terms and conditions of this
+License, without any additional terms or conditions. Notwithstanding the
+above, nothing herein shall supersede or modify the terms of any
+separate license agreement you may have executed with the Licensor
+regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed
+to in writing, Licensor provides the Work (and each Contributor
+provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied, including, without
+limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your
+exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise, unless
+required by applicable law (such as deliberate and grossly negligent
+acts) or agreed to in writing, shall any Contributor be liable to You
+for damages, including any direct, indirect, special, incidental, or
+consequential damages of any character arising as a result of this
+License or out of the use or inability to use the Work (including but
+not limited to damages for loss of goodwill, work stoppage, computer
+failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility
+of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the
+Work or Derivative Works thereof, You may choose to offer, and charge a
+fee for, acceptance of support, warranty, indemnity, or other liability
+obligations and/or rights consistent with this License. However, in
+accepting such obligations, You may act only on Your own behalf and on
+Your sole responsibility, not on behalf of any other Contributor, and
+only if You agree to indemnify, defend, and hold each Contributor
+harmless for any liability incurred by, or claims asserted against, such
+Contributor by reason of your accepting any such warranty or additional
+liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include the
+brackets!)  The text should be enclosed in the appropriate comment
+syntax for the file format. We also recommend that a file or class name
+and description of purpose be included on the same "printed page" as the
+copyright notice for easier identification within third-party archives.
+
+Copyright 2025 Lightweb
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,106 @@
+# Lightweb adapter SDK
+
+The published Python SDK for the Lightweb adapter contract.
+
+> **Status: pre-1.0, under active development.** The SDK is not yet released to PyPI. The first 0.1.0 release will follow once initial implementation rounds are complete. See [`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+## What this is
+
+[Lightweb](https://github.com/lightweb/platform) is a community-owned, deployable platform template for hosting self-hosted alternatives to common web services — files, chat, code, meetings. The platform separates *what a member is entitled to* (the entitlements service, source of truth) from *how those entitlements are provisioned into specific apps* (one adapter per app: NextCloud, Matrix, Gitea, Jitsi, and others).
+
+This SDK publishes the contract those adapters implement. It's six methods, a handful of shared types, an event envelope, and a conformance suite that every adapter is expected to pass.
+
+If you want to build an adapter for a new app, this is the library you depend on. If you want to understand how the platform's adapter layer works without writing one, [`docs/contract.md`](docs/contract.md) is the canonical specification.
+
+## The contract, briefly
+
+Every adapter implements six methods:
+
+- `capabilities()` — declares which feature keys this adapter handles and what enforcement it offers.
+- `apply(member, entitlements)` — idempotent; makes the target app's state match the desired entitlements.
+- `disable(member)` — soft-disable; blocks access while preserving data.
+- `reconcile(member, entitlements)` — read-only; returns a drift report comparing app state to desired state.
+- `health()` — the adapter and its target app are reachable.
+- `list_accounts(cursor)` — optional; pages through every account in the app for whole-system reconciliation.
+
+There is no `delete`. Deletion is destructive, asymmetric, and out of the contract by design; it's handled separately as a gated, human-approved workflow in the platform's reconciler.
+
+The full specification is in [`docs/contract.md`](docs/contract.md).
+
+## Quick start
+
+Install:
+
+```bash
+pip install lightweb-adapter-sdk
+```
+
+A minimal adapter:
+
+```python
+from lightweb_adapter_sdk.adapter import Adapter
+from lightweb_adapter_sdk.types import (
+    Member, Entitlement, AppAccount, DriftReport,
+    Capabilities, HealthStatus, AccountListPage,
+)
+
+
+class MyAdapter:
+    """Adapter for MyApp."""
+
+    def capabilities(self) -> Capabilities:
+        ...
+
+    def apply(self, member: Member, entitlements: list[Entitlement]) -> AppAccount:
+        ...
+
+    def disable(self, member: Member) -> None:
+        ...
+
+    def reconcile(self, member: Member) -> DriftReport:
+        ...
+
+    def health(self) -> HealthStatus:
+        ...
+
+    def list_accounts(self, cursor: str | None = None) -> AccountListPage:
+        ...
+
+
+# Verify the adapter satisfies the contract structurally:
+adapter: Adapter = MyAdapter()
+```
+
+The `Adapter` is a `typing.Protocol`; your class doesn't have to inherit from it. If it has the right method signatures, it satisfies the contract.
+
+The conformance suite verifies your adapter meets the contract's *behavioral* requirements (not just its structural ones). See [`docs/conformance.md`](docs/conformance.md) for how to run it against your adapter.
+
+## Documentation
+
+- [`docs/contract.md`](docs/contract.md) — the canonical contract specification. The authority on what an adapter must do.
+- [`docs/conformance.md`](docs/conformance.md) — how to wire the conformance suite into your adapter's CI.
+- [`docs/event-consumer.md`](docs/event-consumer.md) — JetStream event consumer conventions.
+- [`docs/testkit.md`](docs/testkit.md) — the testkit for adapter authors.
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — repository orientation; what's where and why.
+
+For the broader architectural context — *why* the adapter contract exists in this shape — see the Lightweb HLD in the platform monorepo at `lightweb/platform`'s `docs/hld.md`, especially §4.
+
+## Status
+
+The SDK is pre-1.0. The current implementation is structured as a sequence of rounds, with Round 5 targeting the first 0.1.0 release. 1.0 follows once the contract has been validated by at least one production adapter.
+
+## Relationship to the Lightweb platform
+
+The platform monorepo (`lightweb/platform`) is AGPLv3 and contains the bespoke spine services and first-party adapters that ship with Lightweb. The platform's first-party adapters consume this SDK the same way third-party adapters do — as a pinned PyPI dependency, not as a source-level inclusion.
+
+This SDK is Apache 2.0. The license boundary is structural: the SDK is the *contract* third parties implement against, and a permissive license is appropriate for a contract definition.
+
+The SDK has no code-level dependency on the platform monorepo. It does mirror some platform-side artifacts (event envelope schemas, the entitlements service's API shape), but those are vendored as generated bindings, not pulled dynamically.
+
+## License
+
+Apache License 2.0. See [`LICENSE`](LICENSE) for the full text.
+
+## Code of conduct
+
+Project participants are expected to follow the [Contributor Covenant](https://www.contributor-covenant.org/).

lightweb_adapter_sdk/adapter/__init__.py

@@ -0,0 +1,133 @@
+"""The adapter contract as a structural Protocol.
+
+Every adapter must implement the six methods declared here.
+See docs/contract.md for the prose specification.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from lightweb_adapter_sdk.types import (
+    AccountListPage,
+    AppAccount,
+    Capabilities,
+    DriftReport,
+    Entitlement,
+    HealthStatus,
+    Member,
+)
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """Protocol defining the six-method adapter contract.
+
+    This is a structural Protocol, not a base class.  Adapter authors
+    are not required to inherit from this class; any class that
+    implements the six methods with matching signatures satisfies
+    the contract.
+    """
+
+    def capabilities(self) -> Capabilities:
+        """Declare which feature keys this adapter handles and its limits.
+
+        Returns static metadata describing the adapter's scope: the app
+        it targets, the feature keys it enforces, and any operational
+        constraints (e.g. maximum concurrent applies).  Called once at
+        adapter registration.
+
+        Idempotent: repeated calls with no intervening configuration
+        changes return an equivalent result.
+
+        Error modes: should not raise.  All required information is
+        static configuration available at adapter startup.
+        """
+
+    def apply(self, member: Member, entitlements: list[Entitlement]) -> AppAccount:
+        """Idempotently make the target app's state match the desired entitlements.
+
+        Creates accounts that should exist; updates quotas that have
+        changed; adjusts feature flags.  Returns the resulting
+        ``AppAccount`` data (``external_id`` and current state) so the
+        entitlements service can record the provisioned reality.
+
+        When called with an empty ``entitlements`` list, ensures the
+        account exists with status ``"active"`` and ``current_state``
+        reflecting no entitlements.  (Distinct from ``disable`` which
+        sets status to ``"disabled"``.)
+
+        Error modes: should raise on target-app unreachable or
+        authentication failure.  Partial application is acceptable only
+        if the adapter's internal state remains consistent for a retry.
+        """
+
+    def disable(self, member: Member) -> None:
+        """Soft-disable a member's access while preserving data.
+
+        Blocks the member from using the target app without destroying
+        the account or its data.  Reversible by a subsequent ``apply``.
+
+        Idempotent: calling disable multiple times has the same effect
+        as calling it once.  A no-op if the member is already disabled
+        or has no account in this app.
+
+        Error modes: should raise on target-app unreachable.  Should
+        NOT raise when the member has no account.
+        """
+
+    def reconcile(self, member: Member, entitlements: list[Entitlement]) -> DriftReport:
+        """Read-only drift detection: compare app state to desired state.
+
+        Compares the target app's current state for ``member`` against
+        the desired state described by ``entitlements``.  Returns a
+        structured ``DriftReport`` enumerating each discrepancy as a
+        ``DriftFinding``.  An empty ``findings`` list means no drift.
+        Never mutates the target app.
+
+        The ``entitlements`` argument is the same shape passed to
+        ``apply`` — current desired state, not deltas.  The reconciler
+        passes the entitlements it currently knows for the member; the
+        adapter does not fetch them on its own.
+
+        Four cases by (account-presence x entitlements-presence):
+        account-exists & entitlements-non-empty is the expected case
+        (compare and report mismatches); account-exists & entitlements-empty
+        means correct no-entitlements state (no drift); account-absent &
+        entitlements-non-empty produces a ``missing_in_app`` finding;
+        account-absent & entitlements-empty is correct no-account state
+        (no drift).
+
+        A return with empty findings means the adapter was able to
+        contact the target app and found no drift; it is not a fallback
+        for unreachability.  When the target app is unreachable, raises
+        an adapter-specific exception rather than returning a
+        misleadingly empty report.
+
+        Idempotent: repeated calls with unchanged inputs return the
+        same report (modulo clock drift in ``reconciled_at``).
+        """
+
+    def health(self) -> HealthStatus:
+        """Report adapter and target-app reachability.
+
+        Returns a ``HealthStatus`` with two boolean signals:
+          - ``healthy``: ``True`` only when the adapter is responding AND
+            ``app_reachable`` is ``True`` (strict conjunction).
+          - ``app_reachable``: the target app's API responded.
+
+        The method itself must not raise.  If the adapter cannot perform
+        the health check, return ``healthy=False`` with
+        ``app_reachable=False`` and use ``details`` to explain.
+        """
+
+    def list_accounts(self, cursor: str | None = None) -> AccountListPage:
+        """Page through every account in the target app.
+
+        Used by the reconciler for whole-system drift detection.
+        Returns a window of accounts and a ``next_cursor`` for
+        pagination (``None`` when no more pages).
+
+        An expired or invalid cursor returns an empty page with
+        ``next_cursor=None`` rather than raising.
+
+        Error modes: should raise on target-app unreachable.
+        """

lightweb_adapter_sdk/conformance/__init__.py

@@ -0,0 +1,94 @@
+"""Conformance test suite for the Lightweb adapter contract.
+
+Every adapter must pass these tests to be considered conformant.
+The suite is the mechanical expression of ``docs/contract.md``.
+
+Adapter authors import these test functions in their own
+``tests/test_conformance.py`` and provide the required fixtures
+in their ``conftest.py``. See ``docs/conformance.md`` for usage
+instructions.
+"""
+
+from lightweb_adapter_sdk.conformance.test_apply import (
+    test_apply_creates_account_on_first_call,
+    test_apply_empty_entitlements_creates_active_account,
+    test_apply_idempotent,
+    test_apply_replaces_state_rather_than_merging,
+    test_apply_raises_when_unreachable,
+)
+from lightweb_adapter_sdk.conformance.test_capabilities import (
+    test_capabilities_idempotent,
+    test_capabilities_schema_version_declared,
+)
+from lightweb_adapter_sdk.conformance.test_disable import (
+    test_disable_idempotent,
+    test_disable_noop_for_missing_account,
+    test_disable_sets_status_disabled,
+)
+from lightweb_adapter_sdk.conformance.test_health import (
+    test_health_never_raises,
+    test_health_strict_conjunction_when_app_reachable,
+    test_health_strict_conjunction_when_app_unreachable,
+)
+from lightweb_adapter_sdk.conformance.test_identity_mapping import (
+    test_external_id_immutable_across_apply,
+    test_external_id_immutable_across_reconcile,
+)
+from lightweb_adapter_sdk.conformance.test_list_accounts import (
+    test_list_accounts_invalid_cursor_returns_empty,
+    test_list_accounts_paginates,
+    test_list_accounts_preserves_member_id,
+    test_list_accounts_raises_when_unreachable,
+)
+from lightweb_adapter_sdk.conformance.test_reconcile import (
+    test_reconcile_account_absent_entitlements_empty,
+    test_reconcile_account_absent_entitlements_non_empty,
+    test_reconcile_account_exists_entitlements_differ,
+    test_reconcile_account_exists_entitlements_match,
+    test_reconcile_raises_when_unreachable_not_vacuous_empty,
+)
+from lightweb_adapter_sdk.conformance.test_event_consumer import (
+    test_consumer_satisfies_protocol,
+    test_consume_invokes_apply_for_change_events,
+    test_consume_is_idempotent_at_event_level,
+    test_consume_handles_non_change_events_gracefully,
+)
+
+__all__ = [
+    # capabilities
+    "test_capabilities_idempotent",
+    "test_capabilities_schema_version_declared",
+    # apply
+    "test_apply_creates_account_on_first_call",
+    "test_apply_empty_entitlements_creates_active_account",
+    "test_apply_idempotent",
+    "test_apply_replaces_state_rather_than_merging",
+    "test_apply_raises_when_unreachable",
+    # disable
+    "test_disable_idempotent",
+    "test_disable_noop_for_missing_account",
+    "test_disable_sets_status_disabled",
+    # reconcile
+    "test_reconcile_account_exists_entitlements_match",
+    "test_reconcile_account_exists_entitlements_differ",
+    "test_reconcile_account_absent_entitlements_non_empty",
+    "test_reconcile_account_absent_entitlements_empty",
+    "test_reconcile_raises_when_unreachable_not_vacuous_empty",
+    # health
+    "test_health_never_raises",
+    "test_health_strict_conjunction_when_app_reachable",
+    "test_health_strict_conjunction_when_app_unreachable",
+    # list_accounts
+    "test_list_accounts_paginates",
+    "test_list_accounts_invalid_cursor_returns_empty",
+    "test_list_accounts_preserves_member_id",
+    "test_list_accounts_raises_when_unreachable",
+    # identity_mapping
+    "test_external_id_immutable_across_apply",
+    "test_external_id_immutable_across_reconcile",
+    # event_consumer
+    "test_consumer_satisfies_protocol",
+    "test_consume_invokes_apply_for_change_events",
+    "test_consume_is_idempotent_at_event_level",
+    "test_consume_handles_non_change_events_gracefully",
+]

lightweb_adapter_sdk/conformance/fault_control.py

@@ -0,0 +1,54 @@
+"""Fault injection abstraction for the conformance suite.
+
+Adapter authors provide an implementation of this Protocol via the
+``adapter_fault_control`` conftest fixture, scoped to a single test's
+lifetime. Conformance tests call methods on this fixture to inject
+fault conditions; each adapter author decides which fault modes their
+fake server supports.
+
+Methods declare named fault modes. Implementations either inject the
+fault (returning normally) or raise ``NotImplementedError`` if the
+fault mode is not supported. Conformance tests that require a fault
+mode the adapter doesn't support should skip via a helper.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class FaultControl(Protocol):
+    """Adapter authors provide an implementation via the
+    ``adapter_fault_control`` conftest fixture, scoped to a single
+    test's lifetime.
+    """
+
+    def inject_unreachable(self) -> None:
+        """Inject a fault condition where the target app is unreachable.
+
+        Subsequent calls to adapter methods that make HTTP requests
+        should raise the adapter's unreachable exception (see
+        ``lightweb_adapter_sdk.types.AdapterUnreachable``).
+        """
+
+    def inject_rate_limit(self) -> None:
+        """Inject a fault condition where the target app returns 429.
+
+        Subsequent calls to adapter methods should raise the adapter's
+        rate-limit exception.
+        """
+
+    def inject_auth_failure(self) -> None:
+        """Inject a fault condition where the target app returns 401/403.
+
+        Subsequent calls to adapter methods should raise the adapter's
+        authentication-failure exception.
+        """
+
+    def reset(self) -> None:
+        """Reset the adapter's fake server to normal operating mode.
+
+        Called automatically in fixture teardown so individual tests
+        don't need to.
+        """