karrio-server-core 2025.5__py3-none-any.whl

karrio/server/core/migrations/0002_apilogindex.py

@@ -0,0 +1,69 @@
+# Generated by Django 3.2.13 on 2022-07-18 12:05
+
+from django.db import migrations, models
+import django.db.models.deletion
+import karrio.server.core.utils as utils
+
+
+def forwards_func(apps, schema_editor):
+    db_alias = schema_editor.connection.alias
+    APILog = apps.get_model("core", "APILog")
+    APILogIndex = apps.get_model("core", "APILogIndex")
+    logs = APILog.objects.using(db_alias).filter(response__isnull=False).iterator()
+
+    for log in logs:
+        response = utils.failsafe(
+            lambda: utils.DP.to_dict(utils.DP.to_dict(log.response))
+        )
+        entity_id = utils.failsafe(lambda: response["id"])
+
+        if entity_id is not None:
+            _index = APILogIndex(
+                apirequestlog_ptr=log,
+                entity_id=entity_id,
+            )
+            _index.save_base(raw=True)
+
+        if isinstance(response, dict):
+            log.response = utils.DP.jsonify(response)
+            log.save()
+
+
+def reverse_func(apps, schema_editor):
+    pass
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("rest_framework_tracking", "0011_auto_20201117_2016"),
+        ("core", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="APILogIndex",
+            fields=[
+                (
+                    "apirequestlog_ptr",
+                    models.OneToOneField(
+                        auto_created=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        parent_link=True,
+                        primary_key=True,
+                        serialize=False,
+                        to="rest_framework_tracking.apirequestlog",
+                    ),
+                ),
+                (
+                    "entity_id",
+                    models.CharField(db_index=True, max_length=50, null=True),
+                ),
+            ],
+            options={
+                "verbose_name": "API Request Log",
+                "abstract": False,
+            },
+            bases=("core.apilog",),
+        ),
+        migrations.RunPython(forwards_func, reverse_func),
+    ]

karrio/server/core/migrations/0003_apilogindex_test_mode.py

@@ -0,0 +1,62 @@
+# Generated by Django 4.1.4 on 2022-12-17 11:46
+
+from django.db import migrations, models
+import karrio.server.core.utils as utils
+import karrio.lib as lib
+
+
+def forwards_func(apps, schema_editor):
+    db_alias = schema_editor.connection.alias
+    APILog = apps.get_model("core", "APILog")
+    APILogIndex = apps.get_model("core", "APILogIndex")
+    logs = (
+        APILog.objects.using(db_alias)
+        .filter(models.Q(response__icontains="test_mode"))
+        .iterator()
+    )
+
+    for log in logs:
+        response = utils.failsafe(lambda: lib.to_dict(lib.to_dict(log.response)))
+        entity_id = utils.failsafe(lambda: response["id"])
+        test_mode = utils.failsafe(lambda: response["test_mode"])
+
+        if test_mode is None and '"test_mode": true' in log.response:
+            test_mode = True
+        if test_mode is None and '"test_mode": false' in log.response:
+            test_mode = False
+
+        if test_mode is not None and hasattr(log, "apilogindex"):
+            log.apilogindex.test_mode = test_mode
+            log.apilogindex.save()
+
+        if hasattr(log, "apilogindex") is False:
+            _index = APILogIndex(
+                apirequestlog_ptr=log,
+                entity_id=entity_id,
+                test_mode=test_mode,
+            )
+            _index.save_base(raw=True)
+
+        log.response = utils.DP.jsonify(response)
+        log.save()
+
+
+def reverse_func(apps, schema_editor):
+    pass
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("core", "0002_apilogindex"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="apilogindex",
+            name="test_mode",
+            field=models.BooleanField(
+                default=True, help_text="execution context", null=True
+            ),
+        ),
+        migrations.RunPython(forwards_func, reverse_func),
+    ]

karrio/server/core/migrations/0004_metafield.py

@@ -0,0 +1,74 @@
+# Generated by Django 4.2.8 on 2024-01-13 22:41
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+import functools
+import karrio.server.core.models.base
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ("core", "0003_apilogindex_test_mode"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Metafield",
+            fields=[
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "id",
+                    models.CharField(
+                        default=functools.partial(
+                            karrio.server.core.models.base.uuid,
+                            *(),
+                            **{"prefix": "metaf_"}
+                        ),
+                        editable=False,
+                        max_length=50,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                (
+                    "key",
+                    models.CharField(db_index=True, max_length=50, verbose_name="name"),
+                ),
+                ("value", models.CharField(blank=True, max_length=250, null=True)),
+                (
+                    "type",
+                    models.CharField(
+                        choices=[
+                            ("text", "text"),
+                            ("number", "number"),
+                            ("boolean", "boolean"),
+                        ],
+                        db_index=True,
+                        default="text",
+                        max_length=50,
+                        verbose_name="type",
+                    ),
+                ),
+                ("is_required", models.BooleanField(default=False)),
+                (
+                    "created_by",
+                    models.ForeignKey(
+                        blank=True,
+                        editable=False,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Metafield",
+                "verbose_name_plural": "Metafields",
+                "db_table": "metafield",
+            },
+            bases=(karrio.server.core.models.base.ControlledAccessModel, models.Model),
+        ),
+    ]

karrio/server/core/migrations/0005_alter_metafield_type_alter_metafield_value.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.2.3 on 2025-06-19 05:27
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('core', '0004_metafield'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='metafield',
+            name='type',
+            field=models.CharField(choices=[('text', 'text'), ('number', 'number'), ('boolean', 'boolean'), ('json', 'json'), ('date', 'date'), ('date_time', 'date_time'), ('password', 'password')], db_index=True, default='text', max_length=50, verbose_name='type'),
+        ),
+        migrations.AlterField(
+            model_name='metafield',
+            name='value',
+            field=models.JSONField(blank=True, null=True),
+        ),
+    ]

karrio/server/core/migrations/0006_add_api_log_requested_at_index.py

@@ -0,0 +1,22 @@
+# Generated migration to add index to APIRequestLog table for archiving performance
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('core', '0005_alter_metafield_type_alter_metafield_value'),
+    ]
+
+    operations = [
+        migrations.RunSQL(
+            # Create index on requested_at for archiving queries
+            sql=[
+                "CREATE INDEX IF NOT EXISTS api_log_requested_at_idx ON rest_framework_tracking_apirequestlog (requested_at);",
+            ],
+            reverse_sql=[
+                "DROP INDEX IF EXISTS api_log_requested_at_idx;",
+            ],
+        ),
+    ]

karrio/server/core/models/__init__.py

@@ -0,0 +1,48 @@
+import ast
+import yaml
+import typing
+import functools
+
+import karrio.lib as lib
+from karrio.server.core.models.base import (
+    ControlledAccessModel,
+    get_access_filter,
+    register_model,
+    uuid,
+    MetafieldType,
+    METAFIELD_TYPE,
+)
+from karrio.server.core.models.third_party import (
+    APILog,
+    APILogIndex,
+)
+from karrio.server.core.models.metafield import (
+    Metafield,
+)
+from karrio.server.core.models.entity import Entity, OwnedEntity
+
+
+def _identity(value: typing.Any):
+    return value
+
+
+def field_default(value: typing.Any) -> typing.Callable:
+    return functools.partial(_identity, value=value)
+
+
+def metafields_to_dict(metafields: typing.List[Metafield]) -> dict:
+    _values = {}
+
+    for _ in metafields:
+        # Skip metafields with None or empty values
+        if _.value is None or _.value == "":
+            continue
+
+        if _.type == "number":
+            _values.update({_.key: lib.failsafe(lambda: ast.literal_eval(_.value))})
+        elif _.type == "boolean":
+            _values.update({_.key: lib.failsafe(lambda: bool(yaml.safe_load(_.value)))})
+        else:
+            _values.update({_.key: _.value})
+
+    return _values

karrio/server/core/models/base.py

@@ -0,0 +1,103 @@
+import pydoc
+import typing
+import functools
+from uuid import uuid4
+from django.db import models
+from django.conf import settings
+
+import karrio.lib as lib
+
+T = typing.TypeVar("T")
+MODEL_TRANSFORMERS = getattr(settings, "MODEL_TRANSFORMERS", [])
+ACCESS_METHOD = getattr(
+    settings,
+    "KARRIO_ENTITY_ACCESS_METHOD",
+    "karrio.server.core.middleware.WideAccess",
+)
+get_access_filter = pydoc.locate(ACCESS_METHOD)()
+
+
+def uuid(prefix: str = None):
+    return f'{prefix or ""}{uuid4().hex}'
+
+
+class ControlledAccessModel:
+    @classmethod
+    def access_by(cls: models.Model, context, manager: str = "objects"):
+        test_mode = (
+            context.get("test_mode")
+            if isinstance(context, dict)
+            else getattr(context, "test_mode", None)
+        )
+
+        if hasattr(cls, "created_by"):
+            key = "created_by"
+        elif hasattr(cls, "actor"):
+            key = "actor"
+        else:
+            key = "user"
+
+        query = get_access_filter(context, key)
+
+        if hasattr(cls, "test_mode") and test_mode is not None:
+            query = query & models.Q(
+                models.Q(test_mode=test_mode) | models.Q(test_mode__isnull=True)
+            )
+
+        queryset = getattr(cls, manager, cls.objects)
+
+        if hasattr(cls, "resolve_context_data"):
+            queryset = cls.resolve_context_data(queryset, context)
+
+        return queryset.filter(query)
+
+    @classmethod
+    def resolve_context_data(cls, queryset, context):
+        # 1. Self-optimization (e.g., Carrier resolving its own configs)
+        if hasattr(queryset, 'resolve_config_for'):
+            queryset = queryset.resolve_config_for(context)
+
+        # 2. Relation optimization
+        relations = getattr(cls, "CONTEXT_RELATIONS", [])
+        if relations:
+            from django.db.models import Prefetch
+            prefetches = []
+
+            for field_name in relations:
+                field = cls._meta.get_field(field_name)
+                related_model = field.related_model
+
+                # Check if related model is capable of context resolution
+                if hasattr(related_model.objects, 'resolve_config_for'):
+                    qs = related_model.objects.resolve_config_for(context)
+                    prefetches.append(Prefetch(field_name, queryset=qs))
+                elif hasattr(related_model, 'access_by'):
+                    # Recurse into related model's access_by (which calls its resolve_context_data)
+                    qs = related_model.access_by(context)
+                    prefetches.append(Prefetch(field_name, queryset=qs))
+
+            if prefetches:
+                queryset = queryset.prefetch_related(*prefetches)
+
+        return queryset
+
+
+def register_model(model: T) -> T:
+    transform = lambda model, transformer: (
+        model if transformer is None else pydoc.locate(transformer)(model)
+    )
+
+    return functools.reduce(transform, MODEL_TRANSFORMERS, model)
+
+
+class MetafieldType(lib.StrEnum):
+    text = "text"
+    number = "number"
+    boolean = "boolean"
+    json = "json"
+    date = "date"
+    date_time = "date_time"
+    password = "password"
+
+
+METAFIELD_TYPE = [(c.name, c.name) for c in list(MetafieldType)]

karrio/server/core/models/entity.py

@@ -0,0 +1,24 @@
+from django.db import models
+from django.conf import settings
+from karrio.server.core.models.base import uuid, ControlledAccessModel
+
+
+class Entity(models.Model):
+    class Meta:
+        abstract = True
+
+    id = models.CharField(max_length=50, primary_key=True, default=uuid, editable=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    def __str__(self):
+        return (
+            str(self.id) if self.id is not None else f"{self.__class__.__name__}(None)"
+        )
+
+
+class OwnedEntity(ControlledAccessModel, Entity):
+    class Meta:
+        abstract = True
+
+    created_by = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)

karrio/server/core/models/metafield.py

@@ -0,0 +1,144 @@
+import json
+import re
+import functools
+from datetime import datetime, date
+import django.conf as conf
+import django.db.models as models
+import django.utils.translation as translation
+from django.core.exceptions import ValidationError
+
+import karrio.server.core.models.base as core
+import karrio.server.core.models.entity as entity
+
+_ = translation.gettext_lazy
+
+
+@core.register_model
+class Metafield(entity.OwnedEntity):
+    class Meta:
+        db_table = "metafield"
+        verbose_name = "Metafield"
+        verbose_name_plural = "Metafields"
+
+    id = models.CharField(
+        max_length=50,
+        editable=False,
+        primary_key=True,
+        default=functools.partial(core.uuid, prefix="metaf_"),
+    )
+    key = models.CharField(_("name"), max_length=50, db_index=True)
+    value = models.JSONField(null=True, blank=True)
+    type = models.CharField(
+        _("type"),
+        max_length=50,
+        choices=core.METAFIELD_TYPE,
+        default=core.METAFIELD_TYPE[0][0],
+        db_index=True,
+    )
+    is_required = models.BooleanField(null=False, default=False)
+
+    # Related fields
+    created_by = models.ForeignKey(
+        conf.settings.AUTH_USER_MODEL,
+        blank=True,
+        null=True,
+        on_delete=models.CASCADE,
+        editable=False,
+    )
+
+    @property
+    def object_type(self):
+        return "metafield"
+
+    def clean(self):
+        """Validate the value based on the metafield type."""
+        super().clean()
+        if self.value is not None:
+            self._validate_value()
+
+    def _validate_value(self):
+        """Validate value based on metafield type."""
+        if self.type == core.MetafieldType.text:
+            if not isinstance(self.value, str):
+                raise ValidationError(f"Value must be a string for type 'text'")
+
+        elif self.type == core.MetafieldType.number:
+            if not isinstance(self.value, (int, float)):
+                raise ValidationError(f"Value must be a number for type 'number'")
+
+        elif self.type == core.MetafieldType.boolean:
+            if not isinstance(self.value, bool):
+                raise ValidationError(f"Value must be a boolean for type 'boolean'")
+
+        elif self.type == core.MetafieldType.json:
+            # JSON can be any valid JSON value (dict, list, string, number, boolean, null)
+            try:
+                if isinstance(self.value, str):
+                    json.loads(self.value)
+            except (json.JSONDecodeError, TypeError):
+                raise ValidationError(f"Value must be valid JSON for type 'json'")
+
+        elif self.type == core.MetafieldType.date:
+            if isinstance(self.value, str):
+                try:
+                    datetime.strptime(self.value, '%Y-%m-%d')
+                except ValueError:
+                    raise ValidationError(f"Value must be a valid date (YYYY-MM-DD) for type 'date'")
+            else:
+                raise ValidationError(f"Value must be a date string (YYYY-MM-DD) for type 'date'")
+
+        elif self.type == core.MetafieldType.date_time:
+            if isinstance(self.value, str):
+                try:
+                    datetime.fromisoformat(self.value.replace('Z', '+00:00'))
+                except ValueError:
+                    raise ValidationError(f"Value must be a valid ISO datetime for type 'date_time'")
+            else:
+                raise ValidationError(f"Value must be a datetime string for type 'date_time'")
+
+        elif self.type == core.MetafieldType.password:
+            if not isinstance(self.value, str):
+                raise ValidationError(f"Value must be a string for type 'password'")
+
+    def get_parsed_value(self):
+        """Return the value parsed according to its type."""
+        if self.value is None:
+            return None
+
+        if self.type == core.MetafieldType.text:
+            return str(self.value)
+
+        elif self.type == core.MetafieldType.number:
+            return self.value
+
+        elif self.type == core.MetafieldType.boolean:
+            return bool(self.value)
+
+        elif self.type == core.MetafieldType.json:
+            if isinstance(self.value, str):
+                try:
+                    return json.loads(self.value)
+                except json.JSONDecodeError:
+                    return self.value
+            return self.value
+
+        elif self.type == core.MetafieldType.date:
+            if isinstance(self.value, str):
+                try:
+                    return datetime.strptime(self.value, '%Y-%m-%d').date()
+                except ValueError:
+                    return self.value
+            return self.value
+
+        elif self.type == core.MetafieldType.date_time:
+            if isinstance(self.value, str):
+                try:
+                    return datetime.fromisoformat(self.value.replace('Z', '+00:00'))
+                except ValueError:
+                    return self.value
+            return self.value
+
+        elif self.type == core.MetafieldType.password:
+            return str(self.value)
+
+        return self.value

karrio/server/core/models/third_party.py

@@ -0,0 +1,21 @@
+from django.db import models
+from rest_framework_tracking.models import APIRequestLog
+
+from karrio.server.core.models.base import ControlledAccessModel
+
+
+class APILog(APIRequestLog, ControlledAccessModel):
+    class Meta:
+        ordering = ["-requested_at"]
+        proxy = True
+
+    @property
+    def object_type(self):
+        return "log"
+
+
+class APILogIndex(APILog):
+    entity_id = models.CharField(max_length=50, null=True, db_index=True)
+    test_mode = models.BooleanField(
+        default=True, null=True, help_text="execution context"
+    )