Immutable. This exact content is served forever at /api/v1/blob/58c4a9c95f3b7045.
---
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** - 63-bit time-sortable IDs (timestamp + machineId + sequence; the sign bit is reserved)
- `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
```java
// 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.
```java
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.
```java
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 |
| clock sync | wrapper | Wrap with `ClockSyncSnowflakeId` in production (not a config switch) |
## Common Pitfalls
- **Clock backwards**: Always use `ClockSyncSnowflakeId` wrapper in production
- **Machine ID overflow**: With 10 bits, max 1024 instances per namespace
- **Sequence exhaustion**: The default millisecond layout caps at 4096 IDs per millisecond per machine (~4.096M/s); generation spins into the next millisecond rather than failing. For higher sustained ceilings reallocate bits (larger `sequenceBit`); the second-based layout (`SecondSnowflakeId`, 22-bit sequence) instead allows a full ~4.19M-ID burst within a single second without inter-millisecond spinning
- **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:
```java
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