NetBox internals this plugin depends on

This reference records the NetBox integration points and supporting runtime dependencies the plugin relies on. Use it to locate affected code when upgrading NetBox. Interfaces outside NetBox's documented plugin API may change without warning.

The table also includes Django and third-party dependencies, plus documented interfaces whose behavior matters to the integration. It is a dependency ledger, not a list of unsupported APIs alone.

Dependency ledger

Dependencies are grouped by responsibility. Execution integration lives in execution.py. API dependencies cover run dispatch, declaration authorization and write-lock ordering. The permission helper uses the same refusal exception as NetBox's object-edit views.

Keep the table and canary in sync. Each row has a probe in scripts/check_netbox_internals.py, in the same order. A test checks that they match. The canary resolves symbols after django.setup() without querying the database. It also fails if NetBox skips loading the plugin because the host is outside its supported version range.

CI runs the canary against NetBox's feature branch as a blocking check. The full test leg on that branch is advisory. The canary checks symbol presence, not signatures, relation types or behavior. Those contracts need the full suite against the pinned NetBox ref.

Run it locally from the plugin repository root:

PYTHONPATH=$PWD/testing NETBOX_CONFIGURATION=configuration \
  python scripts/check_netbox_internals.py --netbox /path/to/netbox/netbox

Migration lookups. migration/source.py owns discovery of built-in module and Script rows. The write passes act on those results, keeping knowledge of the legacy source layout in one place.

Keep these path and content-type distinctions intact:

• Open stored source with file_path, not full_path. The latter adds a filesystem root, while the built-in loader uses the relative storage key.
• Resolve built-in Script and ScriptModule content types with for_concrete_model=False. Jobs and Event Rules record the proxy types. Synchronization registrations use the concrete ManagedFile type instead.

Bulk import. The source-field gate in views/projects.py checks the instance NetBox is about to save, not the form's cleaned_data. It relies on two undocumented behaviors: a blank CSV cell preserves the stored value, and NetBox removes fields absent from the record before constructing the instance. A change to either could cause unchanged imports to require activate, refusing updates rather than bypassing authorization.

Why they are not avoidable

These dependencies are not optional. Without the request processors, a Script's changes lose their user attribution and its events never reach webhooks or Event Rules. Without the router probe, a Script running inside a branch writes through a connection the run's transaction does not cover, so a dry run may not revert and a failure may not roll back. Without a safe request copy, the run cannot reach a worker.

The plugin does not depend on NetBox's AbortTransaction. It needs only an exception to trigger dry-run rollback, so it defines its own equivalent.

The advisory-lock namespaces

The plugin also depends on two PostgreSQL advisory-lock namespaces, which are not symbols in the table:

• (770100, .) for Projects, keyed by storage_key in storage/locks.py.
• (770101, 1) for the migration run in models/migration.py.

The migration namespace is derived from the Project namespace. Changing the first changes both.

Session-level locks use django_pg_utils.advisory_lock from django-pgware, which NetBox supplies through its pinned requirements and uses in netbox/jobs.py, extras/jobs.py and ipam/api/views.py. Database-only Project and declaration writes use project_write_lock() on the same Project key via pg_advisory_xact_lock. That lock lasts until the enclosing transaction ends.

Separation from NetBox's locks depends on the numeric keys, not their arity. PostgreSQL separates one-bigint keys from two-integer keys, but NetBox uses both. For example, CustomField.data_lock_key() returns (ADVISORY_LOCK_KEYS['custom-field-data'], pk). NetBox takes that pair at session scope in extras/jobs.py and at transaction scope in extras/models/customfields.py.

NetBox's keys are registered in ADVISORY_LOCK_KEYS in netbox/constants.py or hashed per tree by utilities/ltree.py triggers. The registered range recorded here is 100100 to 115100, separate from 770100 and 770101. The canary checks every registered key against both plugin namespaces and fails the feature-branch check on a collision. Check the live constants when upgrading.

Like django_rq and strawberry, the advisory-lock helper is supplied by NetBox rather than declared separately by this plugin.

Proposed NetBox APIs

A documented execution context. The upstream request is for an API that owns transactions on the default and routed aliases, applies request processors according to commit intent, defines processor startup failures, rolls back dry runs, clears pending events on failure and restores request context on every exit. It would replace the execution dependencies above except AbortScript. These requirements also apply to other plugins executing user-supplied code.

Legacy abort compatibility. AbortScript belongs to the built-in Custom Scripts feature and is expected to leave with it at v5.0. Until then, unchanged legacy Scripts can raise it. No separate import guard is used: on a host above max_version, NetBox reads the plugin configuration and skips loading it. Only __init__.py and constants.py load on that path, and neither imports the legacy exception.

Attribution without a synthetic request. The context should accept an attribution identity without requiring a synthetic HTTP request. The dependency described here is core.signals.handle_changed_object: it reads current_request and returns without recording an ObjectChange or queuing that change's event when no request is set. This concerns collecting and attributing changes, not flushing events already queued by a committed run. A supported context should make both responsibilities explicit.

Composable request processors. utilities.request.apply_request_processors() is close to the loop in execution.py, but cannot express two requirements: skipping event_tracking for dry runs and treating its startup failure as fatal. Parameters for those choices, or a documented composition interface, would remove the local loop.

Job data before execution. Job.enqueue() has no argument for setting the new Job row's data. With immediate=True, it also invokes the handler before returning. The plugin therefore creates the immediate Job itself so revision provenance exists before execution. A row-data argument or a documented post-save, pre-handler hook would remove that duplication.

A legacy export service. Migration needs serializable module and class records, content checksums, Data Source references, repository paths, source streams and the Event Rules, permissions, Job history, schedules and recurrences that refer to them. A supported service would replace the reads in migration/source.py and reduce dependence on field names in a feature being retired.

The write dependencies would remain. Migration validates, orders and records changes that operators could also make through NetBox. Those writes still need compatibility checks as the built-in models change.

A write and execution fence. This is a separate request for persistent, NetBox-owned state enforced below the views. It should make the built-in UI, REST API, Event Rule dispatch and runscript refuse new work through one shared check.

A plugin can refuse ordinary row saves with a pre_save receiver that raises AbortRequest, including without a request in scope. NetBox documents the request-abort pattern, and handle_deleted_object also raises it for a protection rule before checking for a request. Direct saves send the proxy as sender, while automatic synchronization saves the concrete ManagedFile. A receiver intended to cover both must connect to both senders.

That does not provide a complete fence. A row-save signal does not prevent execution, and synchronization has two additional limits:

• Storage writes happen separately. ManagedFile.sync_data() writes through the storage backend without calling save(). SyncedDataMixin.clean() calls sync(), so validation can replace stored content before a save is refused.
• Synchronization errors are not isolated per record. The auto_sync receiver on post_sync loops over AutoSyncRecords without per-record error handling. An exception stops later records, including config templates, export templates, config contexts and config context profiles. The sync has already recorded COMPLETED, but the Job changes it to failed. Raising to refuse one record can therefore disrupt unrelated synchronization. Per-record isolation would address this for other plugins too.

Current migration limits. The plugin does not provide this complete fence. Cutover disables captured Object Permissions and Event Rules, cancels reachable waiting tasks and removes built-in synchronization registrations. Cleanup deletes eligible mapped modules and their source, retaining modules with protected history or references. It does not delete every built-in row. See cleanup for retained and blocked modules.

Permission withdrawal does not restrict superusers, permissions supplied through DEFAULT_PERMISSIONS, or plain Django grants honored by RemoteUserBackend through ModelBackend. A privileged user can also grant extras.add_scriptmodule again and upload new built-in Custom Scripts.

Task deletion and failed Job status do not guarantee that a cancelled run cannot execute. The scheduler can enqueue a task fetched before deletion, even with one worker. The reference pass holds back its replacement when the run has started, or its task is queued again, by the time the pass runs. The migration journal does not provide exactly-once execution. Keep the cancellation and replay limits in the migration guide as the operational reference.

Inventory and staging are repeatable and content-addressed, but that is not an execution fence. Cutover still requires a maintenance window and control of new submissions. A supported fence must address both writes and execution before the plugin can promise that the built-in feature is closed.