cosid-spring-boot

name: cosid-spring-boot description: Configure CosId in Spring Boot applications with cosid-spring-boot-starter. Use when the user works with application.yml, Gradle or Maven dependencies, starter feature variants, Redis/JDBC/MongoDB/ZooKeeper/proxy distributors, SnowflakeId, SegmentId, SegmentChainId, CosIdGenerator, @CosId, IdGeneratorProvider, ID converters, machine guarder settings, clock-backwards synchronization, or Actuator endpoints in a Spring Boot service.

CosId Spring Boot Integration

CosId is a universal, flexible, high-performance distributed ID generator for Java 17+. The Spring Boot starter (cosid-spring-boot-starter) provides auto-configuration for all ID generation strategies.

Workflow

1. Confirm the user's Spring Boot and CosId major versions. CosId 2.x targets Spring Boot 3.x and Java 17; CosId 3.x targets Spring Boot 4.x and Java 17.
2. Choose the ID strategy. Use $cosid-strategy-guide first when the user has not chosen between SnowflakeId, SegmentId, SegmentChainId, and CosIdGenerator.
3. Select the distributor and starter capability needed by the deployment: Redis, JDBC, MongoDB, ZooKeeper, proxy, manual, or StatefulSet.
4. Provide the smallest working YAML for the selected strategy and backend.
5. Show how the application consumes the generator: shared bean, named provider, or @CosId.
6. Add validation guidance for uniqueness, ordering, machine ID ownership, segment allocation, and Actuator visibility.

Dependency Setup

Add the BOM and starter to your Gradle build. When you need a distributor backend, select the corresponding Gradle feature capability:

dependencies {
    implementation platform("me.ahoo.cosid:cosid-bom:${cosidVersion}")

    // Redis backend. Replace the capability with jdbc-support, mongo-support,
    // zookeeper-support, proxy-support, actuator-support, etc. as needed.
    implementation("me.ahoo.cosid:cosid-spring-boot-starter") {
        capabilities {
            requireCapability("me.ahoo.cosid:spring-redis-support")
        }
    }
}

For Maven, import the BOM and add the starter plus the backend module explicitly:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>me.ahoo.cosid</groupId>
            <artifactId>cosid-bom</artifactId>
            <version>${cosid.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>me.ahoo.cosid</groupId>
        <artifactId>cosid-spring-boot-starter</artifactId>
    </dependency>
    <!-- Redis backend. Use cosid-jdbc, cosid-mongo, or cosid-zookeeper for other backends. -->
    <dependency>
        <groupId>me.ahoo.cosid</groupId>
        <artifactId>cosid-spring-redis</artifactId>
    </dependency>
</dependencies>

Choosing an ID Strategy

There are 4 ID generation strategies in CosId. The right choice depends on your requirements:

Decision Guide

• Need maximum performance and have Redis/JDBC available? → SegmentChainId (default segment mode)
• Need time-sortable IDs across machines? → SnowflakeId
• Need compact string IDs or a large machine-ID design space? → CosIdGenerator
• Database-friendly monotonic IDs? → SegmentId or SegmentChainId
• Need only strategy selection? → Use $cosid-strategy-guide before writing YAML

Configuration Templates

Full-featured Redis Setup (Most Common)

This is the most typical production configuration with both SnowflakeId and SegmentChainId:

cosid:
  namespace: ${spring.application.name}
  machine:
    enabled: true
    distributor:
      type: redis
  generator:
    enabled: true
  snowflake:
    enabled: true
    share:
      enabled: true  # shared SnowflakeId as default IdGenerator
    provider:
      order_id:
        converter:
          type: radix
          prefix: ORDER
          radix:
            char-size: 11
            pad-start: true
  segment:
    enabled: true
    mode: chain  # CHAIN = SegmentChainId (recommended), SEGMENT = basic SegmentId
    distributor:
      type: redis
    share:
      enabled: true  # shared SegmentChainId as default StringIdGenerator
    provider:
      user_id:
        step: 100
        converter:
          type: to_string
          to-string:
            char-size: 10
            pad-start: true

JDBC Backend Setup

For environments where only a relational database is available:

cosid:
  namespace: ${spring.application.name}
  machine:
    enabled: true
    distributor:
      type: jdbc
  segment:
    enabled: true
    mode: chain
    distributor:
      type: jdbc
      jdbc:
        enable-auto-init-cosid-table: true
        enable-auto-init-id-segment: true

This auto-creates the cosid table and segment rows. The table schema:

CREATE TABLE IF NOT EXISTS cosid (
    name VARCHAR(100) NOT NULL,
    last_max_id BIGINT NOT NULL DEFAULT 0,
    last_fetch_time BIGINT NOT NULL DEFAULT 0,
    PRIMARY KEY (name)
);

MongoDB Backend Setup

cosid:
  namespace: ${spring.application.name}
  machine:
    enabled: true
    distributor:
      type: mongo
      mongo:
        database: cosid_db
  segment:
    enabled: true
    mode: chain
    distributor:
      type: mongo
      mongo:
        database: cosid_db

ZooKeeper Backend Setup

cosid:
  namespace: ${spring.application.name}
  machine:
    enabled: true
    distributor:
      type: zookeeper
  snowflake:
    enabled: true
  segment:
    enabled: true
    mode: chain
    distributor:
      type: zookeeper

Manual Machine ID (for fixed-instance deployments)

When you have a known, fixed set of instances:

cosid:
  namespace: ${spring.application.name}
  machine:
    enabled: true
    distributor:
      type: manual
      manual:
        machine-id: 1  # must be unique per instance
  snowflake:
    enabled: true

Kubernetes StatefulSet

For StatefulSet deployments, the pod ordinal is used as the machine ID:

cosid:
  namespace: ${spring.application.name}
  machine:
    enabled: true
    distributor:
      type: stateful_set
  snowflake:
    enabled: true

ID Converter Types

Converters transform long IDs into String representations. Configure via converter in each provider definition.

Converter Configuration Examples

# Short alphanumeric ID (radix62)
converter:
  type: radix
  prefix: ORDER
  radix:
    char-size: 11
    pad-start: true

# Numeric string with date prefix
converter:
  type: to_string
  prefix: BIZ-
  date-prefix:
    enabled: true
    pattern: yyMMdd
  to-string:
    char-size: 10
    pad-start: true

# Human-readable snowflake
converter:
  type: snowflake_friendly
  friendly:
    pad-start: true

# With group-based prefix (for date-partitioned segments)
converter:
  type: to_string
  prefix: BIZ-
  group-prefix:
    enabled: true
  to-string:
    char-size: 8
    pad-start: true

Using the ID Generator in Code

Injecting the Shared IdGenerator

When share.enabled: true, a default IdGenerator bean is registered:

@Service
public class OrderService {
    private final IdGenerator idGenerator;
    
    public OrderService(IdGenerator idGenerator) {
        this.idGenerator = idGenerator;
    }
    
    public Order createOrder() {
        long orderId = idGenerator.generate();
        String orderIdStr = idGenerator.generateAsString();
        // ...
    }
}

Injecting Named Generators

Named generators from provider are available via IdGeneratorProvider:

@Service
public class UserService {
    private final IdGenerator userIdGenerator;
    
    public UserService(IdGeneratorProvider provider) {
        this.userIdGenerator = provider.get("user_id");
    }
    
    public User createUser() {
        long userId = userIdGenerator.generate();
        // ...
    }
}

Using @CosId Annotation

The @CosId annotation auto-assigns IDs to entity fields:

import me.ahoo.cosid.annotation.CosId;

public class Order {
    @CosId("order_id")
    private Long id;
    
    // getters/setters
}

SnowflakeId State Parsing

Parse snowflake IDs back into their components:

SnowflakeIdState state = snowflakeId.getStateParser().parse(id);
// state.getTimestamp(), state.getMachineId(), state.getSequence()

SnowflakeId Bit Layout Customization

The default MillisecondSnowflakeId uses 41-bit timestamp, 10-bit machineId, 12-bit sequence. Customize per-provider:

cosid:
  snowflake:
    provider:
      short_lived_id:
        timestamp-unit: second  # use seconds instead of milliseconds
        epoch: 1577203200       # custom epoch (2020-01-01)
        timestamp-bit: 31
        machine-bit: 10
        sequence-bit: 22

Bit allocation must satisfy: timestampBit + machineBit + sequenceBit = 63.

Segment Grouping (Date-partitioned IDs)

Group segments by time period for date-based ID sequences:

cosid:
  segment:
    provider:
      daily_order:
        group:
          by: year_month_day  # or year, year_month
          pattern: yyMMdd
        converter:
          type: to_string
          prefix: BIZ-
          group-prefix:
            enabled: true
          to-string:
            char-size: 8
            pad-start: true

Machine ID Management

Guarder Configuration

The guarder keeps machine ID registrations alive via heartbeat:

cosid:
  machine:
    enabled: true
    distributor:
      type: redis
    guarder:
      enabled: true
      safe-guard-duration: 5m  # how long the guard is valid
      initial-delay: 1s
      delay: 10s

Clock Backwards Synchronization

Handle clock drift in distributed environments:

cosid:
  machine:
    enabled: true
    clock-backwards:
      spin-threshold: 100
      broken-threshold: 2000

• spin-threshold: Small clock drift is handled by spinning/waiting
• broken-threshold: Large clock drift throws ClockTooManyBackwardsException

State Storage

Machine state persists locally to survive restarts:

cosid:
  machine:
    enabled: true
    state-storage:
      local:
        state-location: .cosid-machine-state  # default path

Proxy Mode

For architectures that prefer a dedicated ID service:

# Client side
cosid:
  proxy:
    enabled: true
  segment:
    enabled: true
    mode: chain
    distributor:
      type: proxy

Actuator / Monitoring

Enable Spring Boot Actuator endpoints for monitoring:

management:
  endpoints:
    web:
      exposure:
        include:
          - cosid
          - cosidGenerator
          - cosidStringGenerator
          - health
  endpoint:
    health:
      show-details: always

The cosid endpoint shows all registered ID generators and their stats.

Validation Checklist

• Run a focused Spring Boot test that loads the application context with the chosen backend capability.
• Generate IDs concurrently and assert uniqueness.
• For SnowflakeId, verify machine ID allocation and clock-backwards settings.
• For SegmentId/SegmentChainId, verify the segment distributor initializes the cosid table or backend state.
• For converters, assert the expected prefix, padding, radix, and string length.
• For shared beans, assert IdGenerator or StringIdGenerator resolves to the intended provider.
• For production services, expose and inspect the CosId Actuator endpoint when actuator support is enabled.

Response Template

When answering a Spring Boot integration request, include:

1. Dependency coordinates and the required backend capability.
2. Minimal application.yml for the selected generator.
3. Code snippet for injection or @CosId.
4. Operational notes for machine ID, clock, state storage, and monitoring.
5. A small test or verification command the user can run.