Redis Key Structure for Services and Instances in CoSky: A Complete Guide

CoSky uses deterministic Redis key patterns prefixed with namespaces and suffixed with type identifiers like svc_idx, svc_stat, svc_itc_idx, and svc_itc to store service discovery data, with optional hash-tagging for Redis Cluster compatibility.

The ahoo-wang/cosky repository implements a high-performance service discovery system that persists all registry information in Redis. Understanding the Redis key structure for services and instances in CoSky is essential for debugging, monitoring, and extending the platform.

Core Key Patterns in DiscoveryKeyGenerator.kt

All Redis keys are generated through DiscoveryKeyGenerator.kt located in cosky-discovery/src/main/kotlin/me/ahoo/cosky/discovery/. The class defines constants that serve as key suffixes:

• SERVICE_IDX → svc_idx
• SERVICE_STAT → svc_stat
• SERVICE_INSTANCE_IDX → svc_itc_idx
• SERVICE_INSTANCE → svc_itc

Service-Level Keys

Service Index (getServiceIdxKey): Stores the set of all service IDs registered under a namespace.

// Returns: "{namespace}:svc_idx"
val key = DiscoveryKeyGenerator.getServiceIdxKey("production")
// Result: "production:svc_idx"

Service Statistics (getServiceStatKey): Maintains a hash of per-service counters and metrics.

// Returns: "{namespace}:svc_stat"
val statKey = DiscoveryKeyGenerator.getServiceStatKey("production")
// Result: "production:svc_stat"

Instance-Level Keys

Instance Index (getInstanceIdxKey): A set containing all instance IDs belonging to a specific service.

// Returns: "{namespace}:svc_itc_idx:{serviceId}"
val idxKey = DiscoveryKeyGenerator.getInstanceIdxKey("production", "order-service")
// Result: "production:svc_itc_idx:order-service"

Instance Data (getInstanceKey): Stores the full serialized instance metadata (host, port, weight, schema, etc.).

// Returns: "{namespace}:svc_itc:{instanceId}"
val dataKey = DiscoveryKeyGenerator.getInstanceKey("production", "instance-01")
// Result: "production:svc_itc:instance-01"

Wildcard Patterns for Batch Operations

CoSky supports pattern-based scanning for cleanup and aggregation operations.

All instances in a namespace (getInstanceKeyPatternOfNamespace):

// Pattern: "{namespace}:svc_itc:*"
val allInstancesPattern = DiscoveryKeyGenerator.getInstanceKeyPatternOfNamespace("production")
// Result: "production:svc_itc:*"

All instances of a specific service (getInstanceKeyPatternOfService):

// Pattern: "{namespace}:svc_itc:{serviceId}@*"
val serviceInstancesPattern = DiscoveryKeyGenerator.getInstanceKeyPatternOfService("production", "order-service")
// Result: "production:svc_itc:order-service@*"

Redis Cluster Support with Hash-Tagging

When deploying CoSky in Redis Cluster mode, the system ensures all related keys map to the same hash slot using the RedisKeys.kt utility located in cosky-core/src/main/kotlin/me/ahoo/cosky/core/util/.

The hashTag(key) function wraps keys with curly braces:

object RedisKeys {
    fun hashTag(key: String): String {
        return if (key.contains("{") && key.contains("}")) {
            key
        } else {
            "{$key}"
        }
    }
}

Practical cluster key generation:

val baseKey = DiscoveryKeyGenerator.getInstanceKey("production", "instance-01")
// Base: "production:svc_itc:instance-01"

val clusterKey = RedisKeys.hashTag(baseKey)
// Cluster-ready: "{production:svc_itc:instance-01}"

This guarantees that the service index, instance index, and instance data for a given namespace all reside on the same Redis node, enabling atomic multi-key operations and Lua script execution.

Implementation in Service Registry

The key patterns defined in DiscoveryKeyGenerator.kt are consumed by RedisServiceRegistry.kt and accompanying Lua scripts such as registry_register.lua and registry_remove_service.lua.

When registering a service instance, the registry:

1. Adds the service ID to the svc_idx set
2. Adds the instance ID to the svc_itc_idx:{serviceId} set
3. Stores instance metadata in svc_itc:{instanceId}

This structure enables O(1) lookups for service discovery and efficient cleanup using pattern-based deletion when services are deregistered.

Summary

• CoSky uses deterministic key patterns with prefixes svc_idx, svc_stat, svc_itc_idx, and svc_itc to organize service discovery data in Redis.
• The DiscoveryKeyGenerator.kt class provides type-safe methods for generating keys for namespaces, services, and instances.
• Wildcard patterns support batch operations like service cleanup and instance aggregation.
• RedisKeys.kt adds hash-tagging support ({key}) to ensure cluster compatibility and enable atomic multi-key operations.
• Service registration uses these keys in RedisServiceRegistry.kt and Lua scripts to maintain consistent service metadata.

Frequently Asked Questions

What is the purpose of the svc_idx key in CoSky?

The svc_idx key stores a Redis set containing all service IDs registered under a specific namespace. When generated via DiscoveryKeyGenerator.getServiceIdxKey("namespace"), it returns a key like namespace:svc_idx. This index enables the discovery service to quickly list all available services without scanning the entire keyspace.

How does CoSky handle Redis Cluster mode?

CoSky handles Redis Cluster mode through the RedisKeys.hashTag() function in cosky-core/src/main/kotlin/me/ahoo/cosky/core/util/RedisKeys.kt. This utility wraps keys with curly braces (e.g., {namespace:svc_itc:instance-01}) to ensure all related keys for a namespace map to the same hash slot. This design allows atomic Lua script operations across service and instance keys.

What is the difference between svc_itc_idx and svc_itc keys?

The svc_itc_idx key (generated by getInstanceIdxKey) is a Redis set that stores the IDs of all instances belonging to a specific service, acting as an index. The svc_itc key (generated by getInstanceKey) stores the actual serialized instance data including host, port, metadata, and health status. The index enables O(1) lookup of instance membership, while the data key contains the full registration details.

Where are the Redis key patterns defined in the CoSky source code?

All Redis key patterns are centrally defined in cosky-discovery/src/main/kotlin/me/ahoo/cosky/discovery/DiscoveryKeyGenerator.kt. This Kotlin object contains constants like SERVICE_IDX, SERVICE_STAT, SERVICE_INSTANCE_IDX, and SERVICE_INSTANCE, along with methods such as getServiceIdxKey(), getInstanceKey(), and pattern generators for wildcard operations. Cluster hash-tagging logic resides separately in cosky-core/src/main/kotlin/me/ahoo/cosky/core/util/RedisKeys.kt.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}