Closes #201: Branch cloning

docs/configuration.md

@@ -58,23 +58,31 @@ Note that a valid prefix is required, as the randomly-generated branch ID alone
 
 Default: `[]` (empty list)
 
-A list of import paths to functions which validate whether a branch is permitted to be synced.
+A list of import paths to functions which validate whether a branch is permitted to be synced from main.
+
+---
+
+## `pull_validators`
+
+Default: `[]` (empty list)
+
+A list of import paths to functions which validate whether changes from other branches can be pulled into a branch.
 
 ---
 
 ## `merge_validators`
 
 Default: `[]` (empty list)
 
-A list of import paths to functions which validate whether a branch is permitted to be merged.
+A list of import paths to functions which validate whether a branch is permitted to be merged into main.
 
 ---
 
 ## `revert_validators`
 
 Default: `[]` (empty list)
 
-A list of import paths to functions which validate whether a branch is permitted to be reverted.
+A list of import paths to functions which validate whether a previously merged branch is permitted to be reverted.
 
 ---
 

docs/models/branchevent.md

@@ -12,6 +12,10 @@ The time at which the event occurred.
 
 The [branch](./branch.md) to which this event pertains.
 
+### Related Branch
+
+The related branch affected by this event, where applicable. (This is relevant only when one branch is merged into another.)
+
 ### User
 
 The NetBox user responsible for triggering this event. This field may be null if the event was triggered by an internal process.

netbox_branching/__init__.py

@@ -33,6 +33,7 @@ class AppConfig(PluginConfig):
 
         # Branch action validators
         'sync_validators': [],
+        'pull_validators': [],
         'merge_validators': [],
         'revert_validators': [],
         'archive_validators': [],

netbox_branching/api/serializers.py

@@ -1,6 +1,7 @@
 from drf_spectacular.utils import extend_schema_field
 from rest_framework import serializers
 
+from core.api.serializers import ObjectChangeSerializer
 from core.choices import ObjectChangeActionChoices
 from netbox.api.exceptions import SerializerNotFound
 from netbox.api.fields import ChoiceField, ContentTypeField
@@ -13,6 +14,7 @@
 __all__ = (
     'BranchSerializer',
     'BranchEventSerializer',
+    'BranchPullSerializer',
     'ChangeDiffSerializer',
     'CommitSerializer',
 )
@@ -58,6 +60,11 @@ class BranchEventSerializer(NetBoxModelSerializer):
         nested=True,
         read_only=True
     )
+    related_branch = BranchSerializer(
+        nested=True,
+        read_only=True,
+        allow_null=True
+    )
     user = UserSerializer(
         nested=True,
         read_only=True
@@ -70,7 +77,7 @@ class BranchEventSerializer(NetBoxModelSerializer):
     class Meta:
         model = BranchEvent
         fields = [
-            'id', 'url', 'display', 'time', 'branch', 'user', 'type',
+            'id', 'url', 'display', 'time', 'branch', 'related_branch', 'user', 'type',
         ]
         brief_fields = ('id', 'url', 'display')
 
@@ -138,4 +145,29 @@ def get_object(self, obj):
 
 
 class CommitSerializer(serializers.Serializer):
-    commit = serializers.BooleanField(required=False)
+    commit = serializers.BooleanField(
+        required=False,
+        default=False
+    )
+
+
+class BranchPullSerializer(CommitSerializer):
+    source = BranchSerializer(
+        nested=True
+    )
+    atomic = serializers.BooleanField(
+        required=False,
+        default=True
+    )
+    start = ObjectChangeSerializer(
+        nested=True,
+        required=False,
+        allow_null=True,
+        default=None
+    )
+    end = ObjectChangeSerializer(
+        nested=True,
+        required=False,
+        allow_null=True,
+        default=None
+    )

netbox_branching/api/views.py

@@ -1,6 +1,7 @@
 from django.core.exceptions import PermissionDenied
 from django.http import HttpResponseBadRequest
 from drf_spectacular.utils import extend_schema
+from rest_framework import status
 from rest_framework.decorators import action
 from rest_framework.mixins import ListModelMixin, RetrieveModelMixin
 from rest_framework.response import Response
@@ -10,7 +11,7 @@
 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.jobs import MergeBranchJob, PullBranchJob, RevertBranchJob, SyncBranchJob
 from netbox_branching.models import Branch, BranchEvent, ChangeDiff
 from . import serializers
 
@@ -54,6 +55,43 @@ def sync(self, request, pk):
 
         return Response(JobSerializer(job, context={'request': request}).data)
 
+    @extend_schema(
+        methods=['post'],
+        request=serializers.BranchPullSerializer(),
+        responses={200: JobSerializer()},
+    )
+    @action(detail=True, methods=['post'])
+    def pull(self, request, pk):
+        """
+        Enqueue a background job to pull changes from one Branch into another.
+        """
+        if not request.user.has_perm('netbox_branching.pull_branch'):
+            raise PermissionDenied("This user does not have permission to pull branches.")
+
+        branch = self.get_object()
+        if not branch.ready:
+            return HttpResponseBadRequest("Branch is not ready to apply changes.")
+
+        serializer = serializers.BranchPullSerializer(data=request.data)
+        if not serializer.is_valid():
+            return Response(
+                serializer.errors,
+                status=status.HTTP_400_BAD_REQUEST
+            )
+
+        # Enqueue a background job
+        job = PullBranchJob.enqueue(
+            instance=branch,
+            user=request.user,
+            source=serializer.validated_data['source'],
+            atomic=serializer.validated_data['atomic'],
+            start=serializer.validated_data['start'],
+            end=serializer.validated_data['end'],
+            commit=serializer.validated_data['commit']
+        )
+
+        return Response(JobSerializer(job, context={'request': request}).data)
+
     @extend_schema(
         methods=['post'],
         request=serializers.CommitSerializer(),

netbox_branching/choices.py

@@ -43,13 +43,15 @@ class BranchStatusChoices(ChoiceSet):
 class BranchEventTypeChoices(ChoiceSet):
     PROVISIONED = 'provisioned'
     SYNCED = 'synced'
+    PULLED = 'pulled'
     MERGED = 'merged'
     REVERTED = 'reverted'
     ARCHIVED = 'archived'
 
     CHOICES = (
         (PROVISIONED, _('Provisioned'), 'green'),
         (SYNCED, _('Synced'), 'cyan'),
+        (PULLED, _('Pulled'), 'blue'),
         (MERGED, _('Merged'), 'blue'),
         (REVERTED, _('Reverted'), 'orange'),
         (ARCHIVED, _('Archived'), 'gray'),

netbox_branching/constants.py

@@ -10,6 +10,7 @@
 # Branch actions
 BRANCH_ACTIONS = (
     'sync',
+    'pull',
     'merge',
     'revert',
     'archive',

netbox_branching/forms/misc.py

@@ -1,18 +1,22 @@
 from django import forms
 from django.utils.translation import gettext_lazy as _
 
-from netbox_branching.models import ChangeDiff
+from utilities.forms.utils import get_field_value
+from utilities.forms.widgets import HTMXSelect
+from netbox_branching.models import Branch, ChangeDiff, ObjectChange
 
 __all__ = (
     'BranchActionForm',
+    'BranchPullForm',
     'ConfirmationForm',
 )
 
 
 class BranchActionForm(forms.Form):
     pk = forms.ModelMultipleChoiceField(
         queryset=ChangeDiff.objects.all(),
-        required=False
+        required=False,
+        widget=forms.HiddenInput()
     )
     commit = forms.BooleanField(
         required=False,
@@ -42,6 +46,48 @@ def clean(self):
         return self.cleaned_data
 
 
+class BranchPullForm(BranchActionForm):
+    source = forms.ModelChoiceField(
+        queryset=Branch.objects.all(),
+        widget=HTMXSelect(
+            attrs={
+                'hx-target': 'body'
+            }
+        )
+    )
+    atomic = forms.BooleanField(
+        label=_('Atomic'),
+        required=False,
+        initial=True,
+        help_text=_('Complete only if all changes from the source branch are applied successfully.')
+    )
+    # TODO: Populate choices for start & end fields dynamically
+    start = forms.ModelChoiceField(
+        queryset=ObjectChange.objects.none(),
+        required=False
+    )
+    end = forms.ModelChoiceField(
+        queryset=ObjectChange.objects.none(),
+        required=False
+    )
+
+    field_order = ('source', 'atomic', 'start', 'end', 'commit')
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        self.fields['source'].queryset = Branch.objects.exclude(pk=self.branch.pk)
+
+        if source_id := get_field_value(self, 'source'):
+            try:
+                source = Branch.objects.get(pk=source_id)
+                unpulled_changes = self.branch.get_unpulled_changes(source)
+                self.fields['start'].queryset = unpulled_changes
+                self.fields['end'].queryset = unpulled_changes
+            except Branch.DoesNotExist:
+                pass
+
+
 class ConfirmationForm(forms.Form):
     confirm = forms.BooleanField(
         required=True,

netbox_branching/forms/model_forms.py

@@ -1,7 +1,9 @@
-from netbox_branching.models import Branch
+from django import forms
+from django.utils.translation import gettext_lazy as _
 
 from netbox.forms import NetBoxModelForm
-from utilities.forms.fields import CommentField
+from netbox_branching.models import Branch
+from utilities.forms.fields import CommentField, DynamicModelChoiceField
 from utilities.forms.rendering import FieldSet
 
 __all__ = (
@@ -11,10 +13,29 @@
 
 class BranchForm(NetBoxModelForm):
     fieldsets = (
-        FieldSet('name', 'description', 'tags'),
+        FieldSet('name', 'description', 'clone_from', 'atomic', 'tags'),
+    )
+    clone_from = DynamicModelChoiceField(
+        label=_('Clone from'),
+        queryset=Branch.objects.all(),
+        required=False
+    )
+    atomic = forms.BooleanField(
+        label=_('Atomic'),
+        required=False,
+        initial=True,
+        help_text=_('Clone only if all changes from the source branch are applied successfully.')
     )
     comments = CommentField()
 
     class Meta:
         model = Branch
-        fields = ('name', 'description', 'comments', 'tags')
+        fields = ('name', 'description', 'clone_from', 'atomic', 'comments', 'tags')
+
+    def save(self, *args, **kwargs):
+
+        if clone_from := self.cleaned_data.get('clone_from'):
+            self.instance._clone_source = clone_from
+            self.instance._clone_atomic = self.cleaned_data['atomic']
+
+        return super().save(*args, **kwargs)

netbox_branching/jobs.py

@@ -10,6 +10,7 @@
 __all__ = (
     'MergeBranchJob',
     'ProvisionBranchJob',
+    'PullBranchJob',
     'RevertBranchJob',
     'SyncBranchJob',
 )
@@ -38,7 +39,7 @@ def run(self, *args, **kwargs):
         logger.setLevel(logging.DEBUG)
         logger.addHandler(ListHandler(queue=get_job_log(self.job)))
 
-        # Provision the Branch
+        # Provision the Branch by copying the main schema
         branch = self.job.object
         branch.provision(user=self.job.user)
 
@@ -112,6 +113,27 @@ def run(self, commit=True, *args, **kwargs):
             logger.info("Dry run completed; rolling back changes")
 
 
+class PullBranchJob(JobRunner):
+    """
+    Pull changes from one Branch into another.
+    """
+    class Meta:
+        name = 'Pull branch'
+
+    def run(self, **kwargs):
+        # Initialize logging
+        logger = logging.getLogger('netbox_branching.branch.pull')
+        logger.setLevel(logging.DEBUG)
+        logger.addHandler(ListHandler(queue=get_job_log(self.job)))
+
+        # Pull changes from the source Branch
+        try:
+            branch = self.job.object
+            branch.pull(user=self.job.user, **kwargs)
+        except AbortTransaction:
+            logger.info("Dry run completed; rolling back changes")
+
+
 class RevertBranchJob(JobRunner):
     """
     Revert changes from a merged Branch.

netbox_branching/migrations/0003_branchevent_related_branch.py

@@ -0,0 +1,17 @@
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('netbox_branching', '0002_branch_schema_id_unique'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='branchevent',
+            name='related_branch',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='+', to='netbox_branching.branch'),
+        ),
+    ]