feat: dev fixes, added receiver for signal to provide mutated inteface name (#42)

* fix(devcontainer): proxy/DNS hardening, dep install, cross-plugin examples

Several related devcontainer issues observed against a corporate network
with HTTP proxy, MITM TLS interception, and a wildcard DNS search domain.

docker-compose.yml:
- Pin postgres/redis to static IPs on a 172.28.200.0/24 bridge subnet.
  Avoids the corporate MITM range at 172.30.x.x that Docker would
  otherwise auto-pick.
- Add 'dns_search: ["."]' to netbox so bare names like 'postgres'
  and 'redis' don't get the host's DNS search domain appended (a
  wildcard search domain was returning the wrong IP for the bare
  service names).
- Bump postgres max_connections to 200.

devcontainer.json:
- Move HTTP_PROXY/HTTPS_PROXY/NO_PROXY from containerEnv to remoteEnv.
  VS Code resolves '${localEnv:HTTP_PROXY}' to an empty string when the
  variable is unset on the host, which under containerEnv silently
  overrides the value docker-compose loaded from .env. remoteEnv runs
  after container start and can't shadow compose env.
- Drop the three REQUESTS_CA_BUNDLE / SSL_CERT_FILE / CURL_CA_BUNDLE
  passes (they pointed at host paths that don't exist inside the
  container; setup.sh handles CA-bundle resolution itself).

scripts/setup.sh:
- Add a fallback that reads HTTP/HTTPS/NO_PROXY directly from
  .devcontainer/.env when remoteEnv left them empty (closes the same
  gap as above for users who don't have proxy vars on the host).
- Pin postgres/redis hostnames in /etc/hosts. Backstop for the case
  Docker's embedded DNS doesn't alias 'redis' because of a collision
  with another container on the host of the same name. /etc/hosts is
  consulted before DNS by libc, so this also covers the search-domain
  case as defence in depth.
- Install pytest-cov, reuse, and (for the agent loop) the rest of the
  test toolchain in the same install line — pyproject lists these as
  dev deps but the previous setup.sh didn't install them, so fresh
  containers shipped without 'pytest --cov' or the reuse-lint
  pre-commit hook working. In-source comment now tracks what each
  dep is for.

.env.example:
- Expand the commented NO_PROXY example to include 127.0.0.0/8 and ::1
  loopback ranges (useful when container-local services bind there).

config/*.py.example:
- Add commented-out example wiring for an additional plugin mounted
  from a sibling workspace ('netbox-example-plugin' under
  /workspaces/myorg/…). Demonstrates the org-grouped mount pattern
  without naming any specific real plugin.

scripts/process-helpers.sh:
- Restore executable bit (file is sourced by setup.sh and was losing
  +x on some checkouts).

* chore(devcontainer): ignore docker-compose.override.yml

Allow a local-only compose override file alongside the committed
docker-compose.yml. docker compose auto-merges it on top, so site- or
plugin-specific env vars, mounts, or service tweaks can live in the
developer's working tree without polluting the shared compose file.

* feat(integration): bridge netbox-librenms-plugin module-name prediction

netbox-librenms-plugin's module-adoption flow predicts what interface
names a module's templates will produce so it can find pre-existing
standalone interfaces to adopt into the module. That prediction calls
NetBox's built-in template.instantiate(), which never sees our rename
rules — so for any module covered by an InterfaceNameRule, adoption
silently misses the post-rename name.

Closes the gap on both sides without coupling either plugin to the other:

engine.predict_rule_output(module, module_bay, raw_names):
- Pure name-prediction function that mirrors apply_interface_name_rules'
  template evaluation but does no DB writes. Returns the names that
  would exist post-apply (channel_count > 0 expands one raw name into
  channel_count output names).
- Falls back to the raw name if evaluate_name_template raises, matching
  the apply path's behavior of leaving the interface alone on failure.

signals.on_librenms_predict_module_interface_names:
- Receiver for netbox-librenms-plugin's predict_module_interface_names
  Signal. Routes the predicted names through predict_rule_output and
  returns the rewritten list. Returns None when module_bay is missing
  or the engine raises, so librenms-plugin keeps its original list.
- Import is guarded so INR loads cleanly when librenms-plugin is absent.

Tests cover:
- predict_rule_output: no-rule passthrough, simple rename, breakout
  expansion (1→N), multi-name preservation, pure-function guarantee
  (no Interface row mutations), template-eval failure fallback.
- LibrenmsPredictReceiverTest: end-to-end signal dispatch returns
  rewritten names, None when module_bay missing, None when engine
  raises.

* fix: tighten validation of interface name in receiver

* chore: adjust compose

* fix: addressing review

* fix: addressing review

Author: marcinpsk

.devcontainer/.env.example

@@ -28,7 +28,7 @@ SKIP_SUPERUSER=false
 # Proxy Configuration (optional, for corporate networks)
 # HTTP_PROXY=http://proxy.example.com:8080
 # HTTPS_PROXY=http://proxy.example.com:8080
-# NO_PROXY=localhost,127.0.0.1,postgres,redis
+# NO_PROXY=localhost,127.0.0.1,127.0.0.0/8,::1,postgres,redis
 # REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
 # SSL_CERT_FILE=/path/to/ca-bundle.crt
 # CURL_CA_BUNDLE=/path/to/ca-bundle.crt

.devcontainer/config/extra-plugins.py.example

@@ -20,5 +20,6 @@ Examples:
 
 EXTRA_PLUGINS = [
     # {"name": "netbox-librenms-plugin", "source": "/workspaces/netbox-librenms-plugin"},
+    # {"name": "netbox-example-plugin", "source": "/workspaces/myorg/netbox-example-plugin"},
     # {"name": "netbox-secrets", "source": "pip"},
 ]

.devcontainer/config/plugin-config.py.example

@@ -10,8 +10,13 @@ Plugin configuration for the NetBox Interface Name Rules Plugin in the dev conta
 
 PLUGINS = [
     "netbox_interface_name_rules",
+    # "netbox_example_plugin",  # uncomment once the package is in EXTRA_PLUGINS above
 ]
 
 PLUGINS_CONFIG = {
     "netbox_interface_name_rules": {},
+    # "netbox_example_plugin": {
+    #     "api_url": "",
+    #     "api_token": "",
+    # },
 }

.devcontainer/devcontainer.json

@@ -34,16 +34,15 @@
     "SUPERUSER_NAME": "${localEnv:SUPERUSER_NAME:admin}",
     "SUPERUSER_EMAIL": "${localEnv:SUPERUSER_EMAIL:admin@example.com}",
     "SUPERUSER_PASSWORD": "${localEnv:SUPERUSER_PASSWORD:admin}",
-    "SKIP_SUPERUSER": "${localEnv:SKIP_SUPERUSER:false}",
+    "SKIP_SUPERUSER": "${localEnv:SKIP_SUPERUSER:false}"
+  },
+  "remoteEnv": {
     "HTTP_PROXY": "${localEnv:HTTP_PROXY}",
     "HTTPS_PROXY": "${localEnv:HTTPS_PROXY}",
     "http_proxy": "${localEnv:HTTP_PROXY}",
     "https_proxy": "${localEnv:HTTPS_PROXY}",
     "NO_PROXY": "${localEnv:NO_PROXY}",
-    "no_proxy": "${localEnv:NO_PROXY}",
-    "REQUESTS_CA_BUNDLE": "${localEnv:REQUESTS_CA_BUNDLE}",
-    "SSL_CERT_FILE": "${localEnv:SSL_CERT_FILE}",
-    "CURL_CA_BUNDLE": "${localEnv:CURL_CA_BUNDLE}"
+    "no_proxy": "${localEnv:NO_PROXY}"
   },
   "features": {},
   "customizations": {

.devcontainer/docker-compose.yml

@@ -41,11 +41,13 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
+    dns_search: ["."]
     ports:
       - "8000:8000"
 
   postgres:
     image: postgres:18
+    command: postgres -c max_connections=200
     environment:
       POSTGRES_DB: ${DB_NAME:-netbox}
       POSTGRES_USER: ${DB_USER:-netbox}
@@ -57,6 +59,9 @@ services:
       interval: 30s
       timeout: 10s
       retries: 5
+    networks:
+      default:
+        ipv4_address: 172.28.200.3
 
   redis:
     image: redis:8-alpine
@@ -68,10 +73,21 @@ services:
       interval: 30s
       timeout: 10s
       retries: 5
+    networks:
+      default:
+        ipv4_address: 172.28.200.2
 
 volumes:
   postgres_data:
   redis_data:
   netbox_media:
   netbox_static:
   gh_config:
+
+networks:
+  default:
+    driver: bridge
+    ipam:
+      config:
+        # Pinned to avoid Docker auto-assigning 172.30.x.x
+        - subnet: "172.28.200.0/24"

.devcontainer/scripts/process-helpers.sh

@@ -18,6 +18,24 @@ for _ca_var in REQUESTS_CA_BUNDLE SSL_CERT_FILE CURL_CA_BUNDLE; do
 done
 unset _ca_var _val
 
+# VS Code containerEnv resolves ${localEnv:HTTP_PROXY} to "" when the variable is not
+# set on the host, silently overriding the value docker-compose got from .env.
+# Fall back to reading proxy settings directly from .devcontainer/.env.
+if [ -z "$HTTP_PROXY" ] && [ -z "$HTTPS_PROXY" ]; then
+  _DOTENV="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/.env"
+  if [ -f "$_DOTENV" ]; then
+    _v=$(grep -m1 '^HTTP_PROXY=' "$_DOTENV" | cut -d'=' -f2-)
+    [ -n "$_v" ] && export HTTP_PROXY="$_v" http_proxy="$_v"
+    _v=$(grep -m1 '^HTTPS_PROXY=' "$_DOTENV" | cut -d'=' -f2-)
+    [ -n "$_v" ] && export HTTPS_PROXY="$_v" https_proxy="$_v"
+    _v=$(grep -m1 '^NO_PROXY=' "$_DOTENV" | cut -d'=' -f2-)
+    [ -n "$_v" ] && export NO_PROXY="$_v" no_proxy="$_v"
+    [ -n "$HTTP_PROXY" ] && echo "🌐 Loaded proxy settings from .env (containerEnv fallback)"
+    unset _v
+  fi
+  unset _DOTENV
+fi
+
 # Detect plugin workspace directory
 detect_plugin_workspace() {
   if [ -f "$PWD/pyproject.toml" ]; then
@@ -35,6 +53,21 @@ detect_plugin_workspace() {
   fi
 }
 
+# Pin compose service hostnames in /etc/hosts.
+# Corporate DNS search domains (e.g. .cnad.dev) cause bare names like 'postgres' and 'redis'
+# to resolve to external corporate hosts. Docker's embedded DNS alias for 'redis' is also
+# blocked by a name collision with another container on the host named 'redis'.
+# These IPs are statically assigned via ipv4_address in docker-compose.yml.
+echo "📌 Pinning compose service hostnames in /etc/hosts..."
+for _entry in "172.28.200.3 postgres" "172.28.200.2 redis"; do
+  _ip="${_entry%% *}"
+  _host="${_entry##* }"
+  sed -i "/[[:space:]]${_host}\$/d" /etc/hosts 2>/dev/null || true
+  printf '%s\t%s\n' "$_ip" "$_host" >> /etc/hosts
+  echo "  ✓ ${_host} → ${_ip}"
+done
+unset _entry _ip _host
+
 # Proxy/CA setup
 if [ -n "$HTTP_PROXY" ] || [ -n "$HTTPS_PROXY" ]; then
   echo "🌐 Configuring proxy settings..."
@@ -105,7 +138,11 @@ fi
 echo "🔧 Installing development dependencies..."
 apt-get update -qq
 apt-get install -y -qq net-tools git
-$PIP_CMD install pytest pytest-django ruff pre-commit
+# Dev tools used by the agent loop and pre-commit hooks. Keep in sync with
+# the `dev` extras in pyproject.toml — at minimum, anything invoked by:
+#   - test + coverage runs:                  pytest, pytest-django, pytest-cov
+#   - pre-commit hooks (.pre-commit-config.yaml):  ruff, pre-commit, reuse
+$PIP_CMD install pytest pytest-django pytest-cov ruff pre-commit reuse
 
 # Install GitHub CLI
 if ! command -v gh >/dev/null 2>&1; then
@@ -228,6 +265,19 @@ if [ -f "$CONF_FILE" ]; then
   echo "✅ Plugin configuration injected into NetBox settings"
 fi
 
+# Write local_settings.py to apply Django-level overrides that can't go through
+# NetBox's configuration module (settings.py only reads specific keys from it).
+LOCAL_SETTINGS="/opt/netbox/netbox/netbox/local_settings.py"
+cat > "$LOCAL_SETTINGS" << 'LOCALSETTINGS'
+# Auto-generated by devcontainer setup.sh — do not edit manually.
+
+# Silence django-debug-toolbar's test-mode system check (E001).
+# SILENCED_SYSTEM_CHECKS in /etc/netbox/config/extra.py has no effect because
+# settings.py never reads that key from netbox.configuration.
+SILENCED_SYSTEM_CHECKS = ["debug_toolbar.E001"]
+LOCALSETTINGS
+echo "✅ local_settings.py written (SILENCED_SYSTEM_CHECKS)"
+
 # Run migrations
 cd /opt/netbox/netbox
 export DEBUG="${DEBUG:-True}"

.devcontainer/scripts/setup.sh

@@ -51,6 +51,7 @@ db.sqlite3
 .devcontainer/config/plugin-config.py
 .devcontainer/config/extra-configuration.py
 .devcontainer/config/extra-plugins.py
+.devcontainer/docker-compose.override.yml
 
 # Proxy CA certificates (keep local)
 ca-bundle.crt

.gitignore

@@ -108,6 +108,46 @@ def apply_interface_name_rules(module, module_bay, force_reapply=False):
     return renamed
 
 
+def predict_rule_output(module, module_bay, raw_names):
+    """Predict the names apply_interface_name_rules would produce for raw_names.
+
+    Pure function — does not save, mutate, or query the Interface table. Used
+    by external integrations (e.g., netbox-librenms-plugin) that need to know
+    the post-rename names without actually applying any rule.
+
+    For breakout rules (channel_count > 0), each raw name expands to
+    channel_count predicted names. For simple renames, one name in → one name
+    out. Returns raw_names unchanged when no rule matches or evaluation fails.
+    """
+    device_type = module.device.device_type if module.device else None
+    platform = module.device.platform if module.device else None
+    rule = find_matching_rule(module.module_type, _get_parent_module_type(module_bay), device_type, platform)
+    if not rule:
+        return list(raw_names)
+
+    variables = build_variables(module_bay, device=module.device)
+
+    output = []
+    for raw_name in raw_names:
+        vars_copy = dict(variables)
+        vars_copy["base"] = raw_name
+        try:
+            if rule.channel_count > 0:
+                temp = []
+                for ch in range(rule.channel_count):
+                    vars_copy["channel"] = str(rule.channel_start + ch)
+                    temp.append(evaluate_name_template(rule.name_template, vars_copy))
+                output.extend(temp)
+            else:
+                output.append(evaluate_name_template(rule.name_template, vars_copy))
+        except (ValueError, TypeError, re.error):
+            # Template eval failed; apply path would also fail and leave the
+            # interface alone, so the predicted name is the raw name.
+            output.append(raw_name)
+
+    return output
+
+
 def _try_rename_device_interface(rule, iface, vc_position, device, renamed_pks):
     """Attempt to rename a single device-level interface using *rule*.
 

netbox_interface_name_rules/engine.py

@@ -241,3 +241,50 @@ def _apply_rules_for_device_deferred(device_pk):
             total,
             device,
         )
+
+
+# ---------------------------------------------------------------------------
+# Cross-plugin integration: netbox-librenms-plugin name prediction
+# ---------------------------------------------------------------------------
+# When netbox-librenms-plugin is installed it exposes a Signal that asks
+# subscribers to rewrite the list of interface names it predicts a module's
+# templates will produce. Without this rewrite, its module-adoption lookup
+# would only see NetBox's raw template output and miss interfaces we renamed
+# after install. The import is guarded so INR works fine when librenms-plugin
+# is absent.
+
+try:
+    from netbox_librenms_plugin.signals import (
+        predict_module_interface_names as _librenms_predict_signal,
+    )
+except ImportError:
+    _librenms_predict_signal = None
+
+
+def on_librenms_predict_module_interface_names(sender, device, module, names, **kwargs):
+    """Rewrite librenms-plugin's predicted template names through our rule engine.
+
+    Always defined so it can be imported and tested in isolation even when
+    netbox-librenms-plugin is not installed.  Signal registration is guarded
+    below so it only connects when the signal actually exists.
+    """
+    module_bay = getattr(module, "module_bay", None)
+    if module_bay is None:
+        return None
+    try:
+        from .engine import predict_rule_output
+
+        return predict_rule_output(module, module_bay, names)
+    except Exception:
+        logger.exception(
+            "predict_rule_output failed for module pk=%s; leaving names unchanged",
+            getattr(module, "pk", "?"),
+        )
+        return None
+
+
+if _librenms_predict_signal is not None:
+    receiver(
+        _librenms_predict_signal,
+        dispatch_uid="interface_name_rules_predict_module_interface_names",
+    )(on_librenms_predict_module_interface_names)