Business Rules

​

Link Types and Lifecycle

​

Link Types

​

Link Status Lifecycle

​

Anonymous Link TTL (Time-to-Live)

​

Configuration

static final int ANON_TTL_HOURS = 8;

const TTL_MS = 8 * 60 * 60 * 1000; // 8 hours

​

How It Works

1. Creation: When an anonymous user creates a short URL via POST /api/urls/public, the backend:
   • Sets expiresAt = now + 8 hours
   • Sets linkType = TEMPORARY
   • Sets userId = null
   • Sets status = ACTIVE
2. Client Storage: The frontend stores the URL in localStorage with the same 8-hour expiration
3. Expiration Check: On every redirect attempt (GET /{shortCode}), the backend:
   • Checks if expiresAt < now
   • If expired, returns HTTP 410 Gone (not 404)
   • Updates status to EXPIRED in database
4. Cleanup: A scheduled job runs every 15 minutes to permanently delete expired links

​

Example Timeline

​

Permanent Links

​

Characteristics

• Ownership: Linked to authenticated user via userId
• Expiration: expiresAt = null (never expires)
• Link Type: linkType = PERMANENT
• Visibility: Only visible to the owner in their dashboard
• Deletion: Owner can soft-delete via DELETE /api/urls/{id}

​

Anonymous to Permanent Conversion

1. Frontend sends array of original URLs from localStorage
2. Backend claims existing anonymous entries OR creates new ones
3. Claimed entries are updated:
   • userId set to authenticated user
   • linkType changed to PERMANENT
   • expiresAt set to null
4. Frontend clears localStorage

​

HTTP Status Codes for Links

​

Redirect Endpoint (GET /{shortCode})

// ShortUrlServiceImpl.java:117-124
if (shortUrl.isExpiredNow()) {
    if (shortUrl.getStatus() == LinkStatus.ACTIVE) {
        shortUrl.setStatus(LinkStatus.EXPIRED);
        shortUrlRepository.save(shortUrl);
    }
    throw new LinkExpiredException(shortCode);
}

​

Automated Cleanup Jobs

​

Cleanup Schedule

• lockAtLeastFor: 10 minutes (prevents immediate re-execution)
• lockAtMostFor: 14 minutes (safety timeout if job hangs)

​

Two-Phase Cleanup Strategy

UPDATE short_urls 
SET status = 'EXPIRED' 
WHERE expires_at < NOW() AND status = 'ACTIVE'

DELETE FROM short_urls 
WHERE status IN ('EXPIRED', 'DELETED')

​

Why Two Phases?

1. User requests redirect for expiring link
2. Cleanup job deletes the row mid-request
3. Redirect endpoint queries for the link
4. Gets 404 (not found) instead of 410 (expired)

​

ShedLock Configuration

@EnableSchedulerLock(defaultLockAtMostFor = "PT14M")

CREATE TABLE shedlock (
    name       VARCHAR(64)  NOT NULL PRIMARY KEY,
    lock_until TIMESTAMP    NOT NULL,
    locked_at  TIMESTAMP    NOT NULL,
    locked_by  VARCHAR(255) NOT NULL
);

​

Welford’s Algorithm for Latency Tracking

​

Why Welford’s Algorithm?

• O(1) space (only stores current mean and count)
• O(1) time per update
• Numerically stable (avoids overflow/underflow)

​

Implementation

// Welford's online mean: μₙ = μₙ₋₁ + (xₙ − μₙ₋₁) / n
long newCount = shortUrl.getRedirectCount() + 1;
double prev = shortUrl.getAvgRedirectMs() == null ? 0.0 : shortUrl.getAvgRedirectMs();
shortUrl.setAvgRedirectMs(prev + ((double) redirectLatencyMs - prev) / newCount);

​

How It Works

• μₙ = new average after n measurements
• μₙ₋₁ = previous average
• xₙ = new measurement (current redirect latency)
• n = total count of measurements

​

Latency Measurement

long startMs = System.currentTimeMillis();
String originalUrl = shortUrlService.resolveShortCode(shortCode, 0L);
long latencyMs = System.currentTimeMillis() - startMs;

// Update analytics with measured latency
shortUrlService.resolveShortCode(shortCode, latencyMs);

​

Soft Delete

​

Soft Delete Process

1. User calls DELETE /api/urls/{id} with JWT token
2. Backend verifies ownership (userId matches authenticated user)
3. Status changes from ACTIVE to DELETED
4. Link is no longer visible in user’s dashboard
5. Redirects to deleted links return 404 Not Found
6. Next cleanup job (≤15 min) hard-deletes the row

shortUrl.setStatus(LinkStatus.DELETED);
shortUrlRepository.save(shortUrl);

​

Why Soft Delete?

• Audit trail: Temporarily preserves data for debugging/analytics
• Undo capability: Could implement “restore” feature
• Analytics: Redirect counts remain accurate during cleanup window
• Race condition safety: Redirect checks see DELETED status vs. missing row

• Deleted data remains up to 15 minutes
• Requires cleanup job to purge

​

Short Code Generation

​

Algorithm

​

Collision Handling

private String generateUniqueCode() {
    for (int attempt = 0; attempt < MAX_COLLISION_RETRIES; attempt++) {
        String code = shortCodeGenerator.generate();
        if (!shortUrlRepository.existsByShortCode(code)) {
            return code;
        }
        log.debug("Short code collision on attempt {}/{}", attempt + 1, MAX_COLLISION_RETRIES);
    }
    throw new IllegalStateException(
        "Failed to generate a unique short code after " + MAX_COLLISION_RETRIES + " attempts");
}

​

Analytics Tracking

​

Global Platform Statistics

​

Security Rules

​

Password Hashing

@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder(12);
}

​

JWT Token Validation

• Signature verification
• Expiration check
• Subject (email) extraction

​

Access Control

• View their own short URLs
• Delete their own short URLs
• Create new short URLs (authenticated or anonymous)

if (!owner.getId().equals(shortUrl.getUserId())) {
    throw new UnauthorizedException("You do not own this short URL");
}

​

Business Rule Summary

​

Related Documentation

• Environment Variables - Configuration reference
• API Authentication - Authentication endpoints
• URL Management - URL management endpoints