Skip to content

Plugins Overview

AMSDAL provides the ability to extend the functionality of AMSDAL by using existing plugin packages or by creating your own one.

A plugin can be used for:

  • Custom connection implementations
  • Custom locking implementation
  • REST API (amsdal_server) functionality such as: authorization, extending response data, custom routes, middleware

AMSDAL includes several built-in plugins:

AppConfig

AppConfig is the main class of a plugin. Inherit from amsdal.contrib.app_config.AppConfig and implement the on_setup() method:

from amsdal.contrib.app_config import AppConfig


class MyPluginAppConfig(AppConfig):
    def on_setup(self) -> None:
        # Register event listeners here
        ...

To include your plugin, add the full path to your AppConfig class to the AMSDAL_CONTRIBS environment variable:

AMSDAL_CONTRIBS="amsdal.contrib.auth.app.AuthAppConfig,amsdal.contrib.frontend_configs.app.FrontendConfigAppConfig,my_plugin.app.MyPluginAppConfig"

Events System

Plugins interact with the application lifecycle through the Events System. Events are emitted at key points (server startup, authentication, authorization, route setup, etc.) and plugins subscribe listeners to react to them.

To subscribe a listener, use EventBus.subscribe() in your on_setup() method:

from amsdal.contrib.app_config import AppConfig
from amsdal_utils.events import EventBus


class AuthAppConfig(AppConfig):
    def on_setup(self) -> None:
        from amsdal_server.apps.common.events.server import ServerStartupEvent
        from amsdal_server.apps.common.events.auth import AuthenticateEvent
        from amsdal_server.apps.common.events.authorize import ClassAuthorizeEvent, ObjectAuthorizeEvent

        from amsdal.contrib.auth.event_handlers import (
            CheckAndCreateSuperUserListener,
            AuthenticateUserListener,
            ClassAuthorizeListener,
            ObjectAuthorizeListener,
        )

        EventBus.subscribe(ServerStartupEvent, CheckAndCreateSuperUserListener)
        EventBus.subscribe(AuthenticateEvent, AuthenticateUserListener)
        EventBus.subscribe(ClassAuthorizeEvent, ClassAuthorizeListener)
        EventBus.subscribe(ObjectAuthorizeEvent, ObjectAuthorizeListener)

See Events System for full documentation on creating events, listeners, ordering, and error strategies.

Models

You can add custom models to a plugin. Create a models/ directory in your plugin package and define models the same way you do in your application:

from amsdal_models.classes.model import Model
from amsdal_utils.models.enums import ModuleType


class AuditLog(Model):
    __module_type__ = ModuleType.CONTRIB

    action: str
    details: str

Mark plugin models with __module_type__ = ModuleType.CONTRIB so AMSDAL handles their migrations.

Learn More