cosid-manual-integration

name	cosid-manual-integration
description	Manually integrate CosId into Java or Kotlin applications without Spring Boot auto-configuration. Use when the user needs programmatic setup for SnowflakeId, SegmentId, SegmentChainId, CosIdGenerator, machine ID distribution, custom IdConverter wiring, non-Spring environments, library/framework integration, or production-safe generator lifecycle management.

CosId Manual Integration Skill

Use this skill when CosId must be configured with code instead of cosid-spring-boot-starter.

Workflow

1. Identify the generator strategy. Use $cosid-strategy-guide first if the user has not chosen one.
2. Identify the coordination mechanism: manual machine ID, StatefulSet ordinal, Redis, JDBC, MongoDB, ZooKeeper, or proxy.
3. Show the minimal constructor/wiring path for the chosen generator.
4. Include lifecycle handling for distributors, guard/heartbeat, prefetch workers, and state storage when relevant.
5. Add a small verification example: uniqueness, monotonicity, parser behavior, or restart behavior.

Core APIs

CosId provides three main ID generation strategies:

1. SnowflakeId - 64-bit time-sortable IDs (timestamp + machineId + sequence)

   • MillisecondSnowflakeId - millisecond precision, 41-bit timestamp, 10-bit machine, 12-bit sequence
   • SecondSnowflakeId - second precision, 31-bit timestamp, 10-bit machine, 22-bit sequence
   • SafeJavaScriptSnowflakeId - wrapper constraining to 53 bits for JS compatibility

2. SegmentId - Batch ID allocation for high throughput

   • SegmentChainId - lock-free chain with prefetch worker (~127M+ ops/s)
   • Requires a SegmentIdDistributor (Redis, JDBC, ZooKeeper, MongoDB)

3. CosIdGenerator - Large-scale cluster string ID generator (~15M+ ops/s)

   • Uses Radix62 encoding for compact string IDs
   • Requires MachineIdDistributor for machine ID allocation (same as SnowflakeId)
   • Supports much larger instance counts than SnowflakeId (not constrained by 63-bit long format)

Machine ID Allocation

For SnowflakeId, each instance needs a unique machineId. Options:

• Manual: Set machineId directly (0-1023 for default 10-bit)
• Redis: SpringRedisMachineIdDistributor - uses Redis for coordination
• JDBC: JdbcMachineIdDistributor - uses database table
• ZooKeeper: ZookeeperMachineIdDistributor - uses ZK nodes
• MongoDB: MongoMachineIdDistributor - uses MongoDB collection
• StatefulSet: Kubernetes StatefulSet ordinal as machineId

Always define the namespace and instance identity deliberately. For production, prefer a distributor that can guard ownership and reclaim expired machine IDs.

SnowflakeId Configuration Pattern

// 1. Create a backend-specific MachineIdDistributor
MachineIdDistributor distributor = createMachineIdDistributor();

// 2. Allocate machine ID
int machineBit = 10;
InstanceId instanceId = InstanceId.of("order-service-0", true);
MachineState machineState = distributor.distribute(
    "my-namespace",
    machineBit,
    instanceId,
    Duration.ofSeconds(10)
);
int machineId = machineState.getMachineId();

// 3. Create SnowflakeId
SnowflakeId snowflakeId = new MillisecondSnowflakeId(machineId);

// 4. Wrap with clock sync for safety
SnowflakeId safeId = new ClockSyncSnowflakeId(snowflakeId);

// 5. Generate IDs
long id = safeId.generate();

If the user has fixed deployment slots, use ManualMachineIdDistributor or directly provide the machine ID, but warn that duplicate machine IDs can create duplicate IDs.

Segment Configuration Pattern

Use SegmentId or SegmentChainId when monotonic IDs and batch allocation are more important than time-encoded IDs.

IdSegmentDistributor distributor = createIdSegmentDistributor("order_id", 100);
SegmentChainId idGenerator = new SegmentChainId(distributor);

long id = idGenerator.generate();
String text = idGenerator.generateAsString();

For SegmentChainId, ensure the prefetch worker lifecycle is owned by the application and is closed during shutdown if the concrete setup exposes close/shutdown behavior.

CosIdGenerator Pattern

Use CosIdGenerator when callers need compact string IDs rather than long IDs.

CosIdGenerator generator = new Radix62CosIdGenerator(machineId);
String id = generator.generateAsString();

Wrap with the clock-sync variant when system clock drift is a production concern.

Key Parameters

Parameter	Default	Description
epoch	2019-12-24	Custom epoch for timestamp calculation
timestampBit	41 (ms) / 31 (s)	Bits for timestamp component
machineBit	10	Bits for machine ID (max 1024 machines)
sequenceBit	12 (ms) / 22 (s)	IDs per time unit per machine
clockSync	true	Enable clock backwards synchronization

Common Pitfalls

• Clock backwards: Always use ClockSyncSnowflakeId wrapper in production
• Machine ID overflow: With 10 bits, max 1024 instances per namespace
• Sequence exhaustion: High throughput may need SecondSnowflakeId (4M/s/machine) over millisecond variant (4K/s/machine)
• JavaScript safety: Use SafeJavaScriptSnowflakeId if IDs go to frontend
• Lifecycle leaks: Close distributor clients and background workers when the application shuts down
• State loss: Persist machine state when restart stability matters

Testing Configuration

For tests, use ManualMachineIdDistributor with fixed machine IDs:

MachineIdDistributor distributor = new ManualMachineIdDistributor(1);

Add tests for the property that matters in the user's case:

• Uniqueness across concurrent generation
• Local monotonicity for SegmentId/SegmentChainId
• Time parser correctness for SnowflakeId
• JavaScript-safe range or string conversion
• Machine ID conflict behavior when manual IDs are used

Source Pointers

• Source: cosid-core/src/main/java/me/ahoo/cosid/
• Examples: examples/ directory
• Spring Boot starter: cosid-spring-boot-starter/ for auto-config reference