netbox-change-control 0.3.0__py3-none-any.whl

netbox_change_control/__init__.py

@@ -0,0 +1,87 @@
+from netbox.plugins import PluginConfig, get_plugin_config
+
+__version__ = '0.3.0'
+
+
+class ChangeControlConfig(PluginConfig):
+    name = 'netbox_change_control'
+    verbose_name = 'NetBox Change Control'
+    description = 'Policy-driven change control and mandatory review for NetBox branches'
+    version = __version__
+    base_url = 'change-control'
+    # NetBox refuses to load the plugin outside this range, which is the only place the
+    # requirement is enforced rather than documented. The floor is 4.6.9 because that is what
+    # is tested; below 4.6.5 the initial migration cannot even apply, since it depends on
+    # extras.0140, and below 4.6.0 on core.0024 and users.0016 as well.
+    min_version = '4.6.9'
+    max_version = '4.6.99'
+    default_settings = {  # noqa: RUF012
+        # Block writes to branching-supported models outside of a branch. Users holding the
+        # netbox_change_control.bypass_policy permission are exempt.
+        'protect_main': False,
+        # Limit protect_main to specific models. Empty means every branching-supported model.
+        # Entries are 'app_label.modelname' or 'app_label.*', for example ['circuits.*'].
+        'protect_main_scope': [],
+        # Refuse to merge a branch which has no approved change request. This is the core
+        # guarantee of the plugin; disable it only to troubleshoot.
+        'enforce_merge_gate': True,
+        # Send a NetBox notification to the outstanding reviewers when a change request
+        # needs review, and to the requester when it is approved or rejected.
+        'notify_reviewers': True,
+        # Where a branch page shows its change request. 'right_page' puts it in a card in
+        # the right-hand column, beside branching's own cards; 'alerts' puts it in a band
+        # across the top of the page, above them. Naming both shows both, and an empty list
+        # shows neither.
+        'branch_page_placement': ['right_page'],
+        # Which built-in pre-merge checks to make available. True offers all of them, False
+        # none, and a list a subset. Registering only makes a check selectable: a policy
+        # decides where it applies, by naming it in its Checks field. Valid names:
+        #   'has-changes'       the branch contains something to merge
+        #   'no-conflicts'      no conflicts with main
+        #   'not-stale'         the branch is recent enough to sync
+        #   'threads-resolved'  every comment thread on the Changes tab is resolved
+        'enable_builtin_checks': True,
+        # Checks reported by an external system through the REST API. Each is created as
+        # pending and blocks the merge until a result is reported. Entries are a name, or a
+        # (name, label) pair.
+        'required_external_checks': [],
+        # Allow change requests to merge themselves once every gate is satisfied. Each
+        # request must also opt in individually. Turning this off disables the feature
+        # globally without editing any request, and stops the periodic job being registered.
+        'enable_auto_merge': True,
+        # Minutes between automatic merge sweeps. This bounds how late a change window can
+        # fire: at 10, a window opening at 21:00 merges by 21:09. Lower it for tighter
+        # windows, at the cost of one Job record per run. A change window shorter than this
+        # interval may never merge automatically, and says so on the change request. Takes
+        # effect when the worker restarts.
+        'auto_merge_interval': 10,
+    }
+
+    def ready(self):
+        super().ready()
+
+        from netbox_branching.models import Branch
+
+        # NetBox auto-imports a plugin's navigation, search and template_content modules, but
+        # not its dashboard module, so a widget is registered only if something imports it.
+        # Without this the My Reviews widget is missing from "Add widget", and a dashboard
+        # already holding one fails to load at all.
+        from . import dashboard, events, signal_receivers  # noqa: F401
+
+        # Registering the job is what makes rqworker schedule it, so skipping the import
+        # when auto-merge is off means no periodic job and no Job records at all.
+        if get_plugin_config('netbox_change_control', 'enable_auto_merge'):
+            from . import jobs  # noqa: F401
+        from .checks import register_builtin_checks
+        from .validators import require_approved_change_request
+
+        Branch.register_preaction_check(require_approved_change_request, 'merge')
+
+        # Registering makes a check available; a policy decides where it applies. True makes
+        # every built-in available, False none, and a list a subset.
+        selection = get_plugin_config('netbox_change_control', 'enable_builtin_checks')
+        if selection:
+            register_builtin_checks(list(selection) if isinstance(selection, (list, tuple, set)) else None)
+
+
+config = ChangeControlConfig

netbox_change_control/api/serializers.py

@@ -0,0 +1,251 @@
+from netbox.api.serializers import NetBoxModelSerializer
+from rest_framework import serializers
+
+from netbox_change_control.models import (
+    ChangeComment,
+    ChangeRequest,
+    MergeCheck,
+    Policy,
+    PolicyRule,
+    Review,
+)
+
+__all__ = (
+    'ChangeCommentSerializer',
+    'ChangeRequestSerializer',
+    'MergeCheckSerializer',
+    'PolicyRuleSerializer',
+    'PolicySerializer',
+    'ReviewSerializer',
+)
+
+
+class PolicySerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:policy-detail')
+
+    class Meta:
+        model = Policy
+        fields = (
+            'id',
+            'url',
+            'display',
+            'name',
+            'description',
+            'enabled',
+            'weight',
+            'object_types',
+            'conditions',
+            'condition_state',
+            'checks',
+            'comments',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name')
+
+
+class PolicyRuleSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:policyrule-detail')
+    policy = PolicySerializer(nested=True)
+
+    class Meta:
+        model = PolicyRule
+        fields = (
+            'id',
+            'url',
+            'display',
+            'policy',
+            'name',
+            'min_reviews',
+            'groups',
+            'users',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name', 'min_reviews')
+
+
+class ChangeRequestSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:changerequest-detail')
+    approved = serializers.BooleanField(source='is_approved', read_only=True)
+    branch_name = serializers.CharField(read_only=True)
+    branch_deleted = serializers.BooleanField(read_only=True)
+    ready_to_merge = serializers.BooleanField(source='is_ready_to_merge', read_only=True)
+    # Derived from the policy evaluation, so it is reported and never set. A writable status
+    # let a caller mark a request Completed, which is terminal and blocks its branch from ever
+    # merging. Use the abandon and reopen actions for the two transitions a person makes.
+    status = serializers.CharField(read_only=True)
+    merge_blocked_reason = serializers.CharField(read_only=True)
+    has_conflicts = serializers.BooleanField(read_only=True)
+
+    class Meta:
+        model = ChangeRequest
+        fields = (
+            'id',
+            'url',
+            'display',
+            'ref',
+            'branch',
+            'branch_name',
+            'branch_deleted',
+            'title',
+            'description',
+            'status',
+            'priority',
+            'requester',
+            'approved',
+            'ready_to_merge',
+            'merge_blocked_reason',
+            'has_conflicts',
+            'scheduled_start',
+            'scheduled_end',
+            'auto_merge',
+            'comments',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'ref', 'title', 'status')
+
+
+class ReviewSerializer(NetBoxModelSerializer):
+    """
+    A review is a personal statement, so the API records it as the caller and never as
+    somebody else.
+
+    `reviewer` is read-only and defaults to the requesting user. Leaving it writable let any
+    token holding `add_review` post an approval attributed to a colleague, which defeats the
+    merge gate with one request. The object form does not offer the field for the same reason.
+    """
+
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:review-detail')
+    reviewer = serializers.PrimaryKeyRelatedField(read_only=True)
+
+    class Meta:
+        model = Review
+        fields = (
+            'id',
+            'url',
+            'display',
+            'change_request',
+            'reviewer',
+            'decision',
+            'comment',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'decision')
+
+    def validate(self, attrs):
+        """
+        Attribute a new review to the caller.
+
+        A read-only field carrying a default is not enough, because DRF leaves a read-only
+        field out of validated_data entirely. The assignment also has to happen before
+        super(), since NetBox's ValidatedModelSerializer builds a model instance from these
+        attributes and calls full_clean() on it, which would reject the missing reviewer.
+        """
+        # `not self.nested` matters: a nested serializer's to_internal_value returns a model
+        # instance rather than a dict, and assigning into it raises TypeError.
+        if self.instance is None and not self.nested:
+            request = self.context.get('request')
+            if request is not None:
+                attrs['reviewer'] = request.user
+        return super().validate(attrs)
+
+
+class MergeCheckSerializer(NetBoxModelSerializer):
+    """
+    External systems report a result by PATCHing status, summary and details_url onto an
+    existing check.
+    """
+
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:mergecheck-detail')
+    blocks_merge = serializers.BooleanField(read_only=True)
+    # A reporter must not decide whether its own check counts. Requiredness comes from the
+    # configuration or the policy, and the gate reads it from there rather than from this row,
+    # so a writable field here would only mislead.
+    required = serializers.BooleanField(read_only=True)
+    # The check belongs to the change request which created it. Moving it elsewhere would
+    # detach a result from what it was measuring.
+    change_request = serializers.PrimaryKeyRelatedField(read_only=True)
+
+    class Meta:
+        model = MergeCheck
+        fields = (
+            'id',
+            'url',
+            'display',
+            'change_request',
+            'name',
+            'label',
+            'status',
+            'required',
+            'summary',
+            'details_url',
+            'completed',
+            'blocks_merge',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name', 'status')
+
+
+class ChangeCommentSerializer(NetBoxModelSerializer):
+    """
+    A comment is a personal statement, so the API records it as the caller and never as
+    somebody else.
+
+    `author` is read-only and defaults to the requesting user, for the same reason `reviewer`
+    is on ReviewSerializer. Leaving it writable let any token holding `add_changecomment` post
+    a comment attributed to a colleague, which is enough to fake a sign-off in the discussion
+    a reviewer reads before approving.
+    """
+
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:changecomment-detail')
+    author = serializers.PrimaryKeyRelatedField(read_only=True)
+
+    def validate(self, attrs):
+        """
+        Attribute a new comment to the caller.
+
+        A read-only field carrying a default is not enough, because DRF leaves a read-only
+        field out of validated_data entirely. The assignment also has to happen before
+        super(), since NetBox's ValidatedModelSerializer builds a model instance from these
+        attributes and calls full_clean() on it, which would reject the missing author.
+        """
+        # `not self.nested` matters: a nested serializer's to_internal_value returns a model
+        # instance rather than a dict, and assigning into it raises TypeError.
+        if self.instance is None and not self.nested:
+            request = self.context.get('request')
+            if request is not None:
+                attrs['author'] = request.user
+        return super().validate(attrs)
+
+    class Meta:
+        model = ChangeComment
+        fields = (
+            'id',
+            'url',
+            'display',
+            'change_request',
+            'change_diff',
+            'parent',
+            'author',
+            'text',
+            'resolved',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'text')

netbox_change_control/api/urls.py

@@ -0,0 +1,14 @@
+from netbox.api.routers import NetBoxRouter
+
+from . import views
+
+router = NetBoxRouter()
+router.register('policies', views.PolicyViewSet)
+router.register('policy-rules', views.PolicyRuleViewSet)
+router.register('change-requests', views.ChangeRequestViewSet)
+router.register('reviews', views.ReviewViewSet)
+router.register('checks', views.MergeCheckViewSet)
+router.register('change-comments', views.ChangeCommentViewSet)
+
+app_name = 'netbox_change_control-api'
+urlpatterns = router.urls

netbox_change_control/api/views.py

@@ -0,0 +1,173 @@
+from typing import ClassVar
+
+from django.shortcuts import get_object_or_404
+from netbox.api.authentication import TokenPermissions
+from netbox.api.viewsets import NetBoxModelViewSet
+from rest_framework import status
+from rest_framework.decorators import action
+from rest_framework.exceptions import PermissionDenied
+from rest_framework.response import Response
+
+from netbox_change_control import filtersets
+from netbox_change_control.models import (
+    ChangeComment,
+    ChangeRequest,
+    MergeCheck,
+    Policy,
+    PolicyRule,
+    Review,
+)
+from netbox_change_control.permissions import ABANDON_PERMISSION, CHANGE_PERMISSION, REOPEN_PERMISSION
+
+from .serializers import (
+    ChangeCommentSerializer,
+    ChangeRequestSerializer,
+    MergeCheckSerializer,
+    PolicyRuleSerializer,
+    PolicySerializer,
+    ReviewSerializer,
+)
+
+__all__ = (
+    'ChangeCommentViewSet',
+    'ChangeRequestViewSet',
+    'MergeCheckViewSet',
+    'PolicyRuleViewSet',
+    'PolicyViewSet',
+    'ReviewViewSet',
+)
+
+
+class PolicyViewSet(NetBoxModelViewSet):
+    queryset = Policy.objects.prefetch_related('object_types', 'tags')
+    serializer_class = PolicySerializer
+    filterset_class = filtersets.PolicyFilterSet
+
+
+class PolicyRuleViewSet(NetBoxModelViewSet):
+    queryset = PolicyRule.objects.prefetch_related('groups', 'users', 'tags')
+    serializer_class = PolicyRuleSerializer
+    filterset_class = filtersets.PolicyRuleFilterSet
+
+
+class ObjectActionPermissions(TokenPermissions):
+    """
+    Permissions for an action performed *on* an object rather than one that creates one.
+
+    NetBox maps every POST to `add_<model>`, which is right for creating an object and wrong
+    here: abandoning a change request is not adding one, and requiring `add_changerequest` to
+    give up on somebody else's change is both surprising and too broad.
+
+    The blanket requirement is dropped, and each action states the permission it wants and
+    restricts its own queryset to the objects the caller holds that permission on. Everything
+    else is inherited, including the check that a write token is not read-only.
+    """
+
+    perms_map: ClassVar = {**TokenPermissions.perms_map, 'POST': []}
+
+
+class ChangeRequestViewSet(NetBoxModelViewSet):
+    queryset = ChangeRequest.objects.prefetch_related('policies', 'tags')
+    serializer_class = ChangeRequestSerializer
+    filterset_class = filtersets.ChangeRequestFilterSet
+
+    def _restricted(self, request, action_name, pk):
+        """
+        Fetch the object, honouring any constraint on the caller's permission for this action.
+
+        `self.get_object()` cannot be used: BaseViewSet.initial() has already narrowed
+        `self.queryset` to what the caller may *add*, which is the wrong question for these.
+
+        A caller holding the permission but constrained away from this object gets a 404,
+        which is the NetBox convention for an object-level miss. Not holding it at all is a
+        403, raised by the action before it gets here.
+        """
+        return get_object_or_404(ChangeRequest.objects.restrict(request.user, action_name), pk=pk)
+
+    # `status` is read-only on the serializer because it is derived from the policy
+    # evaluation. These are the two transitions a person makes by hand, each behind its own
+    # permission, so an integration can still give up on a change or take one back up without
+    # the field being writable and Completed being one typo away.
+
+    @action(detail=True, methods=['post'], permission_classes=[ObjectActionPermissions])
+    def submit(self, request, pk=None):
+        if not request.user.has_perm(CHANGE_PERMISSION):
+            raise PermissionDenied('You do not have permission to change change requests.')
+
+        change_request = self._restricted(request, 'change', pk)
+        if not change_request.submit():
+            return Response(
+                {'detail': 'Only a draft can be submitted for review.'},
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        from netbox_change_control import events
+
+        events.emit(change_request, events.CHANGE_REQUEST_SUBMITTED)
+        change_request.refresh_from_db()
+        return Response(self.get_serializer(change_request).data)
+
+    @action(detail=True, methods=['post'], url_path='return-to-draft')
+    def return_to_draft(self, request, pk=None):
+        if not request.user.has_perm(CHANGE_PERMISSION):
+            raise PermissionDenied('You do not have permission to change change requests.')
+
+        change_request = self._restricted(request, 'change', pk)
+        if not change_request.return_to_draft():
+            return Response(
+                {
+                    'detail': (
+                        f'A {change_request.get_status_display().lower()} change request cannot be returned to draft.'
+                    )
+                },
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        return Response(self.get_serializer(change_request).data)
+
+    @action(detail=True, methods=['post'], permission_classes=[ObjectActionPermissions])
+    def abandon(self, request, pk=None):
+        if not request.user.has_perm(ABANDON_PERMISSION):
+            raise PermissionDenied('You do not have permission to abandon change requests.')
+
+        change_request = self._restricted(request, 'abandon', pk)
+        if not change_request.abandon():
+            return Response(
+                {'detail': f'A {change_request.get_status_display().lower()} change request cannot be abandoned.'},
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        return Response(self.get_serializer(change_request).data)
+
+    @action(detail=True, methods=['post'], permission_classes=[ObjectActionPermissions])
+    def reopen(self, request, pk=None):
+        if not request.user.has_perm(REOPEN_PERMISSION):
+            raise PermissionDenied('You do not have permission to reopen change requests.')
+
+        change_request = self._restricted(request, 'reopen', pk)
+        if not change_request.reopen():
+            return Response(
+                {'detail': 'Only an abandoned change request can be reopened.'},
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        change_request.refresh_from_db()
+        return Response(self.get_serializer(change_request).data)
+
+
+class ReviewViewSet(NetBoxModelViewSet):
+    queryset = Review.objects.select_related('reviewer', 'change_request')
+    serializer_class = ReviewSerializer
+    filterset_class = filtersets.ReviewFilterSet
+
+
+class MergeCheckViewSet(NetBoxModelViewSet):
+    queryset = MergeCheck.objects.select_related('change_request')
+    serializer_class = MergeCheckSerializer
+    filterset_class = filtersets.MergeCheckFilterSet
+
+
+class ChangeCommentViewSet(NetBoxModelViewSet):
+    queryset = ChangeComment.objects.select_related('author', 'change_diff', 'change_request')
+    serializer_class = ChangeCommentSerializer
+    filterset_class = filtersets.ChangeCommentFilterSet