Consumer Integration API

Relevant source files

The following files were used as context for generating this wiki page:

• internal/api/consumer.go
• internal/api/capabilities_catalog.go
• internal/api/consumer_test.go
• internal/api/residential.go
• scripts/verify-consumer-contract.ts
• internal/store/migrations.go

The Consumer Integration API provides a programmatic interface for external programs to discover and utilize proxy nodes managed by the HX-ProxyGroup control plane. It serves a frozen, token-addressed node listing that allows consumers to dial nodes themselves without requiring an administrative API key.

This API separates the control plane's responsibility—defining which nodes exist and how to reach them—from the consumer's responsibility, which includes probing, ranking, and rotation scheduling. The only server-side exception is the residential /ctl/ control token calls, which handle active session management.

Sources: internal/api/consumer.go:21-30, internal/api/capabilities_catalog.go:167-175

Architecture and Data Flow

The Consumer Integration API operates in a separate namespace from the session-authenticated administrator API to avoid route collisions. It exposes two primary categories of endpoints: Node Discovery (token-addressed) and Residential Control (session-aware).

Discovery Request Flow

When a consumer requests a node listing, the server validates the share token and retrieves the associated exports.

The server collapses every export failure (unknown token, disabled listener, or non-exportable resource) into a generic 404 response. This prevents attackers from probing the existence of specific listeners through distinct error messages.

Sources: internal/api/consumer.go:37-65, internal/api/consumer.go:72-78, scripts/verify-consumer-contract.ts:60-68

API Endpoints

The Consumer Integration API uses token-based authentication via path parameters.

Endpoint	Method	Auth	Description
/nodes/<token>	GET	Token in Path	Reads the frozen node listing for a specific listener or channel.
/ctl/<token>/nodes	GET	Token in Path	Lists control nodes available for a residential channel.
/ctl/<token>/nodes/<idx>/claim	POST	Token in Path	Claims a specific residential node for a session.
/ctl/<token>/nodes/<idx>/heartbeat	POST	Token in Path	Maintains a lease on a claimed residential node.
/ctl/<token>/nodes/<idx>/release	POST	Token in Path	Releases a held residential node lease.
/ctl/<token>/nodes/<idx>/next	POST	Token in Path	Rotates the residential exit for a specific slot.

Sources: internal/api/capabilities_catalog.go:167-178, internal/api/capabilities_catalog.go:257-268, internal/api/residential.go:244-307

Node Discovery Payload

The discovery endpoint returns a ConsumerPayload containing metadata and an array of nodes.

{
  "name": "Hong Kong Line",
  "share_path": "/sub/0123456789abcdef",
  "subscription_urls": {
    "clash": "/sub/0123456789abcdef?format=clash",
    "v2rayn": "/sub/0123456789abcdef?format=v2rayn"
  },
  "nodes": [
    {
      "name": "HK-01",
      "protocol": "mixed",
      "host": "proxy.example.com",
      "port": 7890,
      "transport": "tcp",
      "tls": true,
      "auth": {
        "username": "svc-user",
        "password": "secret-password"
      }
    }
  ]
}

Sources: internal/api/consumer_test.go:88-109, scripts/verify-consumer-contract.ts:79-85

Residential Control System

Residential channels use a control token system for session management. Unlike discovery tokens, control tokens allow consumers to burn provider quota by rotating IPs.

Residential Session State Machine

The residential system manages leases to prevent concurrent holders from using the same session slot.

Residential nodes are addressed by their ordinal index to ensure node names remain stable across rotations. The system uses an alloc_version and lease_id for compare-and-set operations during rotation.

Sources: internal/api/residential.go:294-318, internal/store/migrations.go:503-518, internal/store/migrations.go:610-618

Contract Verification

The project enforces a strict contract between the server implementation, documentation, and agent skills. The verify-consumer-contract.ts script ensures that three components always agree:

1. docs/CONSUMER_INTEGRATION_CONTRACT.md (Human documentation)
2. internal/listener/consumer.go (Server implementation)
3. .agents/skills/hx-consumer-api/SKILL.md (Agent instructions)

If tokens in the Go vocabularies (e.g., ConsumerFields, ConsumerProtocols, ConsumerStatusCodes) drift in one place but not the others, the build fails.

Sources: scripts/verify-consumer-contract.ts:9-25, scripts/verify-consumer-contract.ts:88-115

Data Models

The Consumer API relies on specific database schemas for managing shareable tokens and residential sessions.

Traffic and Resource Totals

The system tracks usage at the channel and listener levels to provide consumption visibility.

Field	Type	Description
resource_type	TEXT	Category: listener, node, or residential_channel.
upload_bytes	INTEGER	Total bytes uploaded.
download_bytes	INTEGER	Total bytes downloaded.
connection_count	INTEGER	Total connections established.

Sources: internal/store/migrations.go:548-575

Residential Client Sessions

Client sessions maintain the link between a consumer's auth credentials and the allocated residential exit.

Field	Type	Constraints
auth_username	TEXT	UNIQUE, used for data-plane分流.
lease_id	TEXT	ID of the current lease holder.
alloc_version	INTEGER	Monotonic version for CAS operations.
declared_index	INTEGER	Stable index for node addressing.

Sources: internal/store/migrations.go:610-620, internal/store/migrations.go:535-542

Summary

The Consumer Integration API provides a secure, token-addressed gateway for proxy node discovery and residential IP management. By strictly separating administrative management from consumer discovery, it ensures that client programs can access required node data without compromising the full control-plane security. The integration is backed by a verified contract and a monotonic lease system for residential sessions.