Class: FiberJob::JID

Inherits:
Object
  • Object
show all
Defined in:
lib/fiber_job/jid.rb

Overview

JID (Job ID) generation utilities for unique job identification. Provides methods to generate unique, sortable, and URL-safe job identifiers that can be used for tracking, logging, and job management operations.

Examples:

Generate a JID

jid = FiberJob::JID.generate
# => "01J4X8K2V3N9QRSTUVWXYZ1234"

Extract timestamp from JID

timestamp = FiberJob::JID.timestamp(jid)
# => 2024-08-17 15:30:25 UTC

Author:

  • FiberJob Team

Since:

  • 1.1.0

Constant Summary collapse

ENCODING =

Base32 alphabet for ULID encoding (Crockford’s Base32) Excludes ambiguous characters: 0, 1, I, L, O, U

Since:

  • 1.1.0

'0123456789ABCDEFGHJKMNPQRSTVWXYZ'
TIMESTAMP_LENGTH =

Length of the timestamp component in the JID (10 characters)

Since:

  • 1.1.0

10
RANDOM_LENGTH =

Length of the random component in the JID (16 characters)

Since:

  • 1.1.0

16
TOTAL_LENGTH =

Total length of a JID

Since:

  • 1.1.0

TIMESTAMP_LENGTH + RANDOM_LENGTH

Class Method Summary collapse

Class Method Details

.generate(time = nil) ⇒ String

Generates a new unique Job ID (JID).

JIDs are 26-character strings that combine:

  • 10-character timestamp component (millisecond precision)

  • 16-character random component

This format ensures:

  • Lexicographical sortability by creation time

  • URL-safe characters only

  • Extremely low collision probability

  • Easy visual identification

Examples:

Generate a JID

jid = FiberJob::JID.generate
# => "01J4X8K2V3N9QRSTUVWXYZ1234"

Generate with specific time

specific_time = Time.parse("2024-01-01 00:00:00 UTC")
jid = FiberJob::JID.generate(specific_time)
# => "01HKPNQ2V3ABCDEFGHIJKLMNOP"

Parameters:

  • time (Time, nil) (defaults to: nil) —

    Optional time to use for timestamp (defaults to current time)

Returns:

  • (String) —

    A 26-character unique job identifier

Since:

  • 1.1.0



58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/fiber_job/jid.rb', line 58

def generate(time = nil)
  time ||= Time.now
  timestamp_ms = (time.to_f * 1000).to_i

  # Encode timestamp as 10-character base32 string
  timestamp_part = encode_timestamp(timestamp_ms)
  
  # Generate 16-character random component
  random_part = encode_random(16)

  "#{timestamp_part}#{random_part}"
end

.generate_batch(count, time = nil) ⇒ Array<String>

Generates a batch of unique JIDs efficiently. Ensures no duplicates within the batch by incrementing timestamp microseconds when necessary.

Examples:

Generate batch of JIDs

jids = FiberJob::JID.generate_batch(5)
# => ["01J4X8K2V3...", "01J4X8K2V4...", ...]

Parameters:

  • count (Integer) —

    Number of JIDs to generate

  • time (Time, nil) (defaults to: nil) —

    Base time for generation (defaults to current time)

Returns:

  • (Array<String>) —

    Array of unique JIDs

Since:

  • 1.1.0



124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/fiber_job/jid.rb', line 124

def generate_batch(count, time = nil)
  base_time = time || Time.now
  jids = []

  count.times do |i|
    # Ensure uniqueness by adding microseconds offset
    jid_time = Time.at(base_time.to_f + (i * 0.001))
    jids << generate(jid_time)
  end

  jids
end

.timestamp(jid) ⇒ Time

Extracts the timestamp from a JID.

Examples:

Extract timestamp

jid = "01J4X8K2V3N9QRSTUVWXYZ1234"
timestamp = FiberJob::JID.timestamp(jid)
# => 2024-08-17 15:30:25 UTC

Parameters:

  • jid (String) —

    The job ID to extract timestamp from

Returns:

  • (Time) —

    The timestamp when the JID was generated

Raises:

  • (ArgumentError) —

    If JID format is invalid

Since:

  • 1.1.0



81
82
83
84
85
86
87
88
 
# File 'lib/fiber_job/jid.rb', line 81

def timestamp(jid)
  validate_format!(jid)
  
  timestamp_part = jid[0, TIMESTAMP_LENGTH]
  timestamp_ms = decode_timestamp(timestamp_part)
  
  Time.at(timestamp_ms / 1000.0)
end

.valid?(jid) ⇒ Boolean

Validates JID format.

Examples:

Validate JID

FiberJob::JID.valid?("01J4X8K2V3N9QRSTUVWXYZ1234")  # => true
FiberJob::JID.valid?("invalid")                      # => false

Parameters:

  • jid (String) —

    The job ID to validate

Returns:

  • (Boolean) —

    True if valid, false otherwise

Since:

  • 1.1.0



98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/fiber_job/jid.rb', line 98

def valid?(jid)
  return false unless jid.is_a?(String)
  return false unless jid.length == TOTAL_LENGTH
  return false unless jid.match?(/\A[#{ENCODING}]+\z/)
  
  # Additional validation: timestamp should be reasonable
  begin
    ts = timestamp(jid)
    # JID timestamp should be within reasonable bounds
    ts > Time.new(2020, 1, 1) && ts < Time.now + 86400 # Not more than 1 day in future
  rescue ArgumentError
    false
  end
end