Connector Instance Bridge Service for DataPower

Overview

The Connector Instance Bridge Service provides continuous, on-write synchronization between DataPower-specific records and the generic s2r_connector_instance table. This service ensures that when an API publisher creates, updates, or deletes a DataPower gateway or cluster, a corresponding generic representation is maintained.

This component solves the problem of traffic attribution for DataPower instances modified after an initial, one-time data migration. Without this continuous sync, traffic from new or renamed gateways would not be correctly attributed, as the generic ingest resolver would be unable to find a matching connector_instance_id.

The service is invoked by the administrative services responsible for managing DataPower gateway and cluster entities immediately after they persist a change to the database. It acts as a secondary, fault-tolerant persistence step.

How it Works

The service ensures data consistency by translating DataPower-specific records into a vendor-agnostic format in the s2r_connector_instance table. This process follows a strict set of rules to guarantee data integrity and operational stability.

sequenceDiagram
    actor User as API Publisher
    participant AdminSvc as DataPower Admin Service
    participant BridgeSvc as Connector Instance Bridge Service
    participant DB as Database

    User->>AdminSvc: Create/Update/Delete DataPower Gateway
    AdminSvc->>DB: Persist change to s2r_datapower_instance
    DB-->>AdminSvc: Success
    AdminSvc->>BridgeSvc: syncGateway(gatewayRecord)
    BridgeSvc->>DB: UPSERT to s2r_connector_instance
    alt on database error
        BridgeSvc->>BridgeSvc: Catch exception, log S2R-ADM-0453
    end
    BridgeSvc-->>AdminSvc: Return (void)
    AdminSvc-->>User: Operation successful

The core mechanism is governed by the following principles:

• ID-Keyed Synchronization: The primary key of a record in s2r_connector_instance is the same UUID as the source DataPower gateway or cluster (s2r_datapower_instance or s2r_datapower_cluster). All write operations use an ON CONFLICT (id) DO UPDATE clause (an "upsert"). This makes operations idempotent and simplifies renames into a standard field update, avoiding the need to manage multiple records for the same entity.

• Soft Deletes: When a DataPower gateway or cluster is deleted, its corresponding record in s2r_connector_instance is not removed. Instead, its enabled flag is set to false. This is critical because a hard delete would cascade through foreign key relationships (ON DELETE SET NULL), stripping historical traffic data of its attribution.

• Fault Tolerance: The service is designed to never cause the primary administrative operation (e.g., saving a gateway configuration) to fail. All internal exceptions, such as database connection errors, are caught and logged with the warning code S2R-ADM-0453. A failed sync can be corrected by the next successful update to the same entity or by a periodic backfill process.

• Single Source of Truth for Derived Data: The data_plane_ips field is not calculated in the service. Instead, its value is derived within the database by the PostgreSQL function s2r_derive_data_plane_ips(text). This ensures that the derivation logic is consistent between this service and any backfill utilities.

• Tenant Scoping: All database operations are strictly scoped to the tenant associated with the current connection. SQL queries include explicit WHERE clauses on the tenant_id column to enforce data isolation between tenants, complementing the database's Row-Level Security (RLS) policies.

API Reference

The service exposes methods for synchronizing and disabling bridge records. These methods are called internally by other platform services.

syncGateway

Registers or updates the bridge record for a single DataPower gateway instance. This method is idempotent and can be safely called for create, update, enable, or disable operations.

public void syncGateway(DataPowerInstanceRecord instance)

Parameters:

The method performs an upsert into s2r_connector_instance. If the gateway belongs to a cluster, the cluster_instance_id is resolved via a subselect that only links to a valid, existing cluster bridge record. This prevents errors from out-of-order writes.

syncCluster

Registers or updates the bridge record for a DataPower HA cluster.

public void syncCluster(DataPowerClusterRecord cluster)

Parameters:

disableGateway

Marks a gateway's bridge record as disabled (enabled = false). This is a soft delete.

public void disableGateway(UUID instanceId, String actor)

Parameters:

disableCluster

Marks a cluster's bridge record as disabled (enabled = false). This is a soft delete.

public void disableCluster(UUID clusterId, String actor)

Parameters:

Database Schema and Field Mappings

The service writes to the s2r_connector_instance table. The following table describes the columns managed by this service for DataPower entities.

Example SQL Operation

When syncGateway is called, it executes a SQL INSERT ... ON CONFLICT statement to create or update the record. The following is the template for this operation. The ? placeholders are filled with values from the DataPowerInstanceRecord.

insert into s2r_connector_instance
    (id, vendor, name, enabled, management_url, is_cluster, cluster_instance_id,
     data_plane_ips, created_at, updated_at, updated_by)
values (?, ?, ?, ?, ?, false,
        (select ci.id from s2r_connector_instance ci
          where ci.id = ? and ci.is_cluster
            and ci.tenant_id = '...' -- Tenant scope predicate
        ),
        s2r_derive_data_plane_ips(?),
        now(), now(), ?)
on conflict (id) do update set
    vendor              = excluded.vendor,
    name                = excluded.name,
    enabled             = excluded.enabled,
    management_url      = excluded.management_url,
    is_cluster          = false,
    cluster_instance_id = excluded.cluster_instance_id,
    data_plane_ips      = excluded.data_plane_ips,
    updated_at          = now(),
    updated_by          = excluded.updated_by
where s2r_connector_instance.tenant_id = excluded.tenant_id

Troubleshooting

The service is designed for high resilience and to prevent cascading failures.

• Condition: Bridge sync failure for a DataPower gateway or cluster.
• Log Message: S2R-ADM-0453 connector_instance bridge sync failed for DataPower <kind> <id>: <error_message>
• Cause: This warning is logged when an unexpected exception occurs during the database update, such as a loss of connectivity or a transient database error.
• Impact: The operation is non-fatal by design. The API publisher's primary action (e.g., saving the DataPower entity) succeeds. However, the s2r_connector_instance table will not reflect the latest change. This may cause traffic from the affected gateway to be temporarily unattributed or attributed to its parent cluster until the sync is successful.
• Resolution: The state will be automatically corrected on the next successful save operation for that same gateway or cluster. Alternatively, a periodic data backfill process will repair the inconsistency.

All SOAP-to-REST docs