netboxlabs-netbox-branching 0.3.0__tar.gz

netboxlabs_netbox_branching-0.3.0/LICENSE.md

@@ -0,0 +1,164 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management
+System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+[Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations than an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

netboxlabs_netbox_branching-0.3.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.1
+Name: netboxlabs-netbox-branching
+Version: 0.3.0
+Summary: A git-like branching implementation for NetBox
+Author-email: NetBox Labs <support@netboxlabs.com>
+Maintainer-email: NetBox Labs <support@netboxlabs.com>
+License: PolyForm Shield License 1.0.0
+Project-URL: Homepage, https://netboxlabs.com/
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: Django
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: check-manifest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+
+# NetBox Branching
+
+This [NetBox](http://netboxlabs.com/oss/netbox/) plugin introduces branching functionality. A branch is a discrete, static snapshot of the NetBox database which can be modified independently and later merged back into the main database. This enables users to make "offline" changes to objects within NetBox and avoid interfering with its integrity as the network source of truth. It also provides the opportunity to review changes in bulk prior to their application.
+
+## Requirements
+
+* NetBox v4.1 or later
+* PostgreSQL 12 or later
+
+## Installation
+
+Brief installation instructions are provided below. For a complete installation guide, please refer to the included documentation.
+
+1. Activate the NetBox virtual environment:
+
+```
+$ source /opt/netbox/venv/bin/activate
+```
+
+2. Install the plugin from [PyPI](https://pypi.org/project/netboxlabs-netbox-branching/):
+
+```
+$ pip install netboxlabs-netbox-branching
+```
+
+3. Add `netbox_branching` to `PLUGINS` in `configuration.py`:
+
+```python
+PLUGINS = [
+    # ...
+    'netbox_branching',
+]
+```
+
+4. Create `local_settings.py` to override the `DATABASES` & `DATABASE_ROUTERS` settings. This enables dynamic schema support.
+
+```python
+from netbox_branching.utilities import DynamicSchemaDict
+from .configuration import DATABASE
+
+# Wrap DATABASES with DynamicSchemaDict for dynamic schema support
+DATABASES = DynamicSchemaDict({
+    'default': DATABASE,
+})
+
+# Employ our custom database router
+DATABASE_ROUTERS = [
+    'netbox_branching.database.BranchAwareRouter',
+]
+```
+
+5. Run NetBox migrations:
+
+```
+$ ./manage.py migrate
+```

netboxlabs_netbox_branching-0.3.0/README.md

@@ -0,0 +1,56 @@
+# NetBox Branching
+
+This [NetBox](http://netboxlabs.com/oss/netbox/) plugin introduces branching functionality. A branch is a discrete, static snapshot of the NetBox database which can be modified independently and later merged back into the main database. This enables users to make "offline" changes to objects within NetBox and avoid interfering with its integrity as the network source of truth. It also provides the opportunity to review changes in bulk prior to their application.
+
+## Requirements
+
+* NetBox v4.1 or later
+* PostgreSQL 12 or later
+
+## Installation
+
+Brief installation instructions are provided below. For a complete installation guide, please refer to the included documentation.
+
+1. Activate the NetBox virtual environment:
+
+```
+$ source /opt/netbox/venv/bin/activate
+```
+
+2. Install the plugin from [PyPI](https://pypi.org/project/netboxlabs-netbox-branching/):
+
+```
+$ pip install netboxlabs-netbox-branching
+```
+
+3. Add `netbox_branching` to `PLUGINS` in `configuration.py`:
+
+```python
+PLUGINS = [
+    # ...
+    'netbox_branching',
+]
+```
+
+4. Create `local_settings.py` to override the `DATABASES` & `DATABASE_ROUTERS` settings. This enables dynamic schema support.
+
+```python
+from netbox_branching.utilities import DynamicSchemaDict
+from .configuration import DATABASE
+
+# Wrap DATABASES with DynamicSchemaDict for dynamic schema support
+DATABASES = DynamicSchemaDict({
+    'default': DATABASE,
+})
+
+# Employ our custom database router
+DATABASE_ROUTERS = [
+    'netbox_branching.database.BranchAwareRouter',
+]
+```
+
+5. Run NetBox migrations:
+
+```
+$ ./manage.py migrate
+```

netboxlabs_netbox_branching-0.3.0/netbox_branching/__init__.py

@@ -0,0 +1,24 @@
+from netbox.plugins import PluginConfig
+
+
+class AppConfig(PluginConfig):
+    name = 'netbox_branching'
+    verbose_name = 'NetBox Branching'
+    description = 'A git-like branching implementation for NetBox'
+    version = '0.3.0'
+    base_url = 'branching'
+    min_version = '4.1'
+    middleware = [
+        'netbox_branching.middleware.BranchMiddleware'
+    ]
+    default_settings = {
+        # This string is prefixed to the name of each new branch schema during provisioning
+        'schema_prefix': 'branch_',
+    }
+
+    def ready(self):
+        super().ready()
+        from . import events, search, signal_receivers
+
+
+config = AppConfig

netboxlabs_netbox_branching-0.3.0/netbox_branching/api/serializers.py

@@ -0,0 +1,138 @@
+from drf_spectacular.utils import extend_schema_field
+from rest_framework import serializers
+
+from core.choices import ObjectChangeActionChoices
+from netbox.api.exceptions import SerializerNotFound
+from netbox.api.fields import ChoiceField, ContentTypeField
+from netbox.api.serializers import NetBoxModelSerializer
+from netbox_branching.choices import BranchEventTypeChoices
+from netbox_branching.models import ChangeDiff, Branch, BranchEvent
+from users.api.serializers import UserSerializer
+from utilities.api import get_serializer_for_model
+
+__all__ = (
+    'BranchSerializer',
+    'BranchEventSerializer',
+    'ChangeDiffSerializer',
+    'CommitSerializer',
+)
+
+
+class BranchSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name='plugins-api:netbox_branching-api:branch-detail'
+    )
+    owner = UserSerializer(
+        nested=True,
+        read_only=True
+    )
+    merged_by = UserSerializer(
+        nested=True,
+        read_only=True
+    )
+
+    class Meta:
+        model = Branch
+        fields = [
+            'id', 'url', 'display', 'name', 'status', 'owner', 'description', 'schema_id', 'last_sync', 'merged_time',
+            'merged_by', 'comments', 'tags', 'custom_fields', 'created', 'last_updated',
+        ]
+        brief_fields = ('id', 'url', 'display', 'name', 'status', 'description')
+
+    def create(self, validated_data):
+        """
+        Record the user who created the Branch as its owner.
+        """
+        validated_data['owner'] = self.context['request'].user
+        return super().create(validated_data)
+
+
+class BranchEventSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name='plugins-api:netbox_branching-api:branchevent-detail'
+    )
+    branch = BranchSerializer(
+        nested=True,
+        read_only=True
+    )
+    user = UserSerializer(
+        nested=True,
+        read_only=True
+    )
+    type = ChoiceField(
+        choices=BranchEventTypeChoices,
+        read_only=True
+    )
+
+    class Meta:
+        model = BranchEvent
+        fields = [
+            'id', 'url', 'display', 'time', 'branch', 'user', 'type',
+        ]
+        brief_fields = ('id', 'url', 'display')
+
+
+class ChangeDiffSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name='plugins-api:netbox_branching-api:changediff-detail'
+    )
+    branch = BranchSerializer(
+        nested=True,
+        read_only=True
+    )
+    object_type = ContentTypeField(
+        read_only=True
+    )
+    object = serializers.SerializerMethodField(
+        read_only=True
+    )
+    action = ChoiceField(
+        choices=ObjectChangeActionChoices,
+        read_only=True
+    )
+    diff = serializers.JSONField(
+        read_only=True
+    )
+    original_data = serializers.JSONField(
+        source='original',
+        read_only=True,
+        allow_null=True
+    )
+    modified_data = serializers.JSONField(
+        source='modified',
+        read_only=True,
+        allow_null=True
+    )
+    current_data = serializers.JSONField(
+        source='current',
+        read_only=True,
+        allow_null=True
+    )
+
+    class Meta:
+        model = ChangeDiff
+        fields = [
+            'id', 'url', 'display', 'branch', 'object_type', 'object_id', 'object', 'object_repr', 'action',
+            'conflicts', 'diff', 'original_data', 'modified_data', 'current_data', 'last_updated',
+        ]
+        brief_fields = ('id', 'url', 'display', 'object_type', 'object_id', 'object_repr', 'action')
+
+    @extend_schema_field(serializers.JSONField(allow_null=True))
+    def get_object(self, obj):
+        """
+        Serialize a nested representation of the changed object.
+        """
+        if obj.object is None:
+            return None
+
+        try:
+            serializer = get_serializer_for_model(obj.object)
+        except SerializerNotFound:
+            return obj.object_repr
+        data = serializer(obj.object, nested=True, context={'request': self.context['request']}).data
+
+        return data
+
+
+class CommitSerializer(serializers.Serializer):
+    commit = serializers.BooleanField(required=False)

netboxlabs_netbox_branching-0.3.0/netbox_branching/api/urls.py

@@ -0,0 +1,10 @@
+from netbox.api.routers import NetBoxRouter
+from . import views
+
+router = NetBoxRouter()
+router.APIRootView = views.RootView
+router.register('branches', views.BranchViewSet)
+router.register('branch-events', views.BranchEventViewSet)
+router.register('changes', views.ChangeDiffViewSet)
+
+urlpatterns = router.urls

netboxlabs_netbox_branching-0.3.0/netbox_branching/api/views.py

@@ -0,0 +1,125 @@
+from django.core.exceptions import PermissionDenied
+from django.http import HttpResponseBadRequest
+from drf_spectacular.utils import extend_schema
+from rest_framework.decorators import action
+from rest_framework.mixins import ListModelMixin, RetrieveModelMixin
+from rest_framework.response import Response
+from rest_framework.routers import APIRootView
+from rest_framework.viewsets import ModelViewSet
+
+from core.api.serializers import JobSerializer
+from netbox.api.viewsets import BaseViewSet, NetBoxReadOnlyModelViewSet
+from netbox_branching import filtersets
+from netbox_branching.jobs import MergeBranchJob, RevertBranchJob, SyncBranchJob
+from netbox_branching.models import Branch, BranchEvent, ChangeDiff
+from . import serializers
+
+
+class RootView(APIRootView):
+    def get_view_name(self):
+        return 'Branching'
+
+
+class BranchViewSet(ModelViewSet):
+    queryset = Branch.objects.all()
+    serializer_class = serializers.BranchSerializer
+    filterset_class = filtersets.BranchFilterSet
+
+    @extend_schema(
+        methods=['post'],
+        request=serializers.CommitSerializer(),
+        responses={200: JobSerializer()},
+    )
+    @action(detail=True, methods=['post'])
+    def sync(self, request, pk):
+        """
+        Enqueue a background job to synchronize a branch from main.
+        """
+        if not request.user.has_perm('netbox_branching.sync_branch'):
+            raise PermissionDenied("This user does not have permission to sync branches.")
+
+        branch = self.get_object()
+        if not branch.ready:
+            return HttpResponseBadRequest("Branch is not ready to sync.")
+
+        serializer = serializers.CommitSerializer(data=request.data)
+        commit = serializer.validated_data['commit'] if serializer.is_valid() else False
+
+        # Enqueue a background job
+        job = SyncBranchJob.enqueue(
+            instance=branch,
+            user=request.user,
+            commit=commit
+        )
+
+        return Response(JobSerializer(job, context={'request': request}).data)
+
+    @extend_schema(
+        methods=['post'],
+        request=serializers.CommitSerializer(),
+        responses={200: JobSerializer()},
+    )
+    @action(detail=True, methods=['post'])
+    def merge(self, request, pk):
+        """
+        Enqueue a background job to merge a branch.
+        """
+        if not request.user.has_perm('netbox_branching.merge_branch'):
+            raise PermissionDenied("This user does not have permission to merge branches.")
+
+        branch = self.get_object()
+        if not branch.ready:
+            return HttpResponseBadRequest("Branch is not ready to merge.")
+
+        serializer = serializers.CommitSerializer(data=request.data)
+        commit = serializer.validated_data['commit'] if serializer.is_valid() else False
+
+        # Enqueue a background job
+        job = MergeBranchJob.enqueue(
+            instance=branch,
+            user=request.user,
+            commit=commit
+        )
+
+        return Response(JobSerializer(job, context={'request': request}).data)
+
+    @extend_schema(
+        methods=['post'],
+        request=serializers.CommitSerializer(),
+        responses={200: JobSerializer()},
+    )
+    @action(detail=True, methods=['post'])
+    def revert(self, request, pk):
+        """
+        Enqueue a background job to revert a merged branch.
+        """
+        if not request.user.has_perm('netbox_branching.revert_branch'):
+            raise PermissionDenied("This user does not have permission to revert branches.")
+
+        branch = self.get_object()
+        if not branch.merged:
+            return HttpResponseBadRequest("Only merged branches can be reverted.")
+
+        serializer = serializers.CommitSerializer(data=request.data)
+        commit = serializer.validated_data['commit'] if serializer.is_valid() else False
+
+        # Enqueue a background job
+        job = RevertBranchJob.enqueue(
+            instance=branch,
+            user=request.user,
+            commit=commit
+        )
+
+        return Response(JobSerializer(job, context={'request': request}).data)
+
+
+class BranchEventViewSet(ListModelMixin, RetrieveModelMixin, BaseViewSet):
+    queryset = BranchEvent.objects.all()
+    serializer_class = serializers.BranchEventSerializer
+    filterset_class = filtersets.BranchEventFilterSet
+
+
+class ChangeDiffViewSet(NetBoxReadOnlyModelViewSet):
+    queryset = ChangeDiff.objects.all()
+    serializer_class = serializers.ChangeDiffSerializer
+    filterset_class = filtersets.ChangeDiffFilterSet

netboxlabs_netbox_branching-0.3.0/netbox_branching/choices.py

@@ -0,0 +1,46 @@
+from django.utils.translation import gettext_lazy as _
+
+from utilities.choices import ChoiceSet
+
+
+class BranchStatusChoices(ChoiceSet):
+    NEW = 'new'
+    PROVISIONING = 'provisioning'
+    READY = 'ready'
+    SYNCING = 'syncing'
+    MERGING = 'merging'
+    REVERTING = 'reverting'
+    MERGED = 'merged'
+    FAILED = 'failed'
+
+    CHOICES = (
+        (NEW, _('New'), 'cyan'),
+        (PROVISIONING, _('Provisioning'), 'orange'),
+        (READY, _('Ready'), 'green'),
+        (SYNCING, _('Syncing'), 'orange'),
+        (MERGING, _('Merging'), 'orange'),
+        (REVERTING, _('Reverting'), 'orange'),
+        (MERGED, _('Merged'), 'blue'),
+        (FAILED, _('Failed'), 'red'),
+    )
+
+    TRANSITIONAL = (
+        PROVISIONING,
+        SYNCING,
+        MERGING,
+        REVERTING
+    )
+
+
+class BranchEventTypeChoices(ChoiceSet):
+    PROVISIONED = 'provisioned'
+    SYNCED = 'synced'
+    MERGED = 'merged'
+    REVERTED = 'reverted'
+
+    CHOICES = (
+        (PROVISIONED, _('Provisioned'), 'green'),
+        (SYNCED, _('Synced'), 'cyan'),
+        (MERGED, _('Merged'), 'blue'),
+        (REVERTED, _('Reverted'), 'orange'),
+    )

netboxlabs_netbox_branching-0.3.0/netbox_branching/constants.py

@@ -0,0 +1,11 @@
+# Name of the main (non-branch) PostgreSQL schema
+MAIN_SCHEMA = 'public'
+
+# HTTP cookie
+COOKIE_NAME = 'active_branch'
+
+# HTTP header for API requests
+BRANCH_HEADER = 'X-NetBox-Branch'
+
+# URL query parameter name
+QUERY_PARAM = '_branch'

netboxlabs_netbox_branching-0.3.0/netbox_branching/contextvars.py

@@ -0,0 +1,8 @@
+from contextvars import ContextVar
+
+__all__ = (
+    'active_branch',
+)
+
+
+active_branch = ContextVar('active_branch', default=None)