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

> Understand the CoSky Redis key structure for services and instances. Learn about namespaces, type identifiers like svc_idx, and hash-tagging for efficient data management.

- Repository: [Ahoo Wang/cosky](https://github.com/ahoo-wang/cosky)
- Tags: deep-dive
- Published: 2026-02-23

---

**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`](https://github.com/ahoo-wang/cosky/blob/main/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.

```kotlin
// 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.

```kotlin
// 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.

```kotlin
// 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.).

```kotlin
// 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`):

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

```

**All instances of a specific service** (`getInstanceKeyPatternOfService`):

```kotlin
// 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`](https://github.com/ahoo-wang/cosky/blob/main/RedisKeys.kt) utility located in `cosky-core/src/main/kotlin/me/ahoo/cosky/core/util/`.

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

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

```

**Practical cluster key generation:**

```kotlin
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`](https://github.com/ahoo-wang/cosky/blob/main/DiscoveryKeyGenerator.kt) are consumed by [`RedisServiceRegistry.kt`](https://github.com/ahoo-wang/cosky/blob/main/RedisServiceRegistry.kt) and accompanying Lua scripts such as [`registry_register.lua`](https://github.com/ahoo-wang/cosky/blob/main/registry_register.lua) and [`registry_remove_service.lua`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/cosky-core/src/main/kotlin/me/ahoo/cosky/core/util/RedisKeys.kt).