CDN image pipeline: sizes, formats, policy checks, cleanup (avatars/role-icons/guild-profiles)

[devin-ai-integration]

Scope

• Implement policy checks (premium/animated allowances) before accepting uploads
• Generate multiple sizes and formats for icons consistently
• Garbage-collect old icons upon updates

Acceptance criteria

• Config-driven validation for premium/animated profile pictures and role icons
• Generated variants: sizes (e.g., 64/128/256/512) and formats (e.g., png/webp) stored and retrievable
• Old icon variants cleaned up when a new image is stored
• Endpoints continue to return correct content type and cache headers

Code references

• avatars: https://github.com/erkinalp/anticensor/blob/master/src/cdn/routes/avatars.ts#L27-L31
• role-icons: https://github.com/erkinalp/anticensor/blob/master/src/cdn/routes/role-icons.ts#L29-L32
• guild-profiles: https://github.com/erkinalp/anticensor/blob/master/src/cdn/routes/guild-profiles.ts#L27-L31

Notes

• Ensure consistency in how hash/animated prefixes are handled across routes
• Consider background processing if resizing/transcoding proves expensive

[traycerai]

Plan

Observations

I've thoroughly analyzed the CDN image pipeline codebase and understand the complete request flow from API to CDN. The current implementation has basic upload/download functionality but lacks the sophisticated image processing, policy validation, and cleanup features requested in the GitHub issue. The system uses a microservice architecture where the API service calls the CDN service via HTTP with signature-based authentication.

Approach

I'll implement a comprehensive CDN image pipeline that adds policy validation, multi-format/multi-size generation, and cleanup functionality while maintaining backward compatibility. The solution will leverage existing Sharp/Jimp libraries for image processing, extend the configuration system for policy controls, and implement efficient storage management with proper cleanup of old variants.

Reasoning

I explored the codebase systematically, starting with the CDN routes mentioned in the issue, then examining the storage infrastructure, configuration system, and API-to-CDN communication flow. I found the existing image processing capabilities in ImageProxy middleware and discovered the premium/policy system through User and Guild entities. I also analyzed the complete request flow from client through API to CDN to understand integration points.

Proposed File Changes

📄 /src/util/config/types/CdnConfiguration.ts ^(NEW) 🔗

Extend the existing CdnConfiguration class to include comprehensive image processing and policy configuration options. Add fields for:

• imageProcessing object containing:

  • sizes: number[] - Array of allowed image sizes (default: [64, 128, 256, 512])
  • formats: string[] - Array of output formats (default: ["png", "webp"])
  • maxDimensions: { width: number, height: number } - Maximum input image dimensions
  • quality: { webp: number, jpeg: number } - Quality settings for lossy formats

• policies object containing:

  • avatars with allowAnimated: boolean and requiresPremium: boolean
  • roleIcons with allowAnimated: boolean and requiresPremium: boolean
  • guildProfiles with allowAnimated: boolean and requiresPremium: boolean

• cleanup object with:

  • enabled: boolean - Whether to cleanup old variants
  • retainOriginal: boolean - Whether to keep original uploads

This extends the existing configuration structure while maintaining backward compatibility with current resizeHeightMax, resizeWidthMax, and imagorServerUrl fields.

📄 /src/cdn/util/ImageProcessor.ts ^(NEW) 🔗

References

• 📄 /src/api/middlewares/ImageProxy.ts

Create a new image processing utility that abstracts Sharp and Jimp operations for consistent image manipulation across the CDN. This utility will:

• Export an ImageProcessor class that detects and uses Sharp if available, falls back to Jimp, or throws descriptive errors if neither is available

• Provide methods for:

  • generateVariants(buffer: Buffer, sizes: number[], formats: string[]) - Creates multiple size/format combinations from input buffer
  • validateImage(buffer: Buffer, maxDimensions: {width: number, height: number}) - Validates image dimensions and format
  • isAnimated(buffer: Buffer) - Detects if image contains animation
  • getImageInfo(buffer: Buffer) - Returns metadata like dimensions, format, file size

• Handle format conversion logic:

  • Static images: generate PNG and WebP variants
  • Animated images: preserve as GIF/APNG, generate static PNG/WebP from first frame
  • Apply quality settings for lossy formats

• Implement proper error handling with fallbacks and descriptive error messages

• Use the same Sharp/Jimp detection pattern found in src/api/middlewares/ImageProxy.ts for consistency

📄 /src/cdn/util/PolicyValidator.ts ^(NEW) 🔗

References

• 📄 /src/util/entities/User.ts
• 📄 /src/util/entities/Guild.ts
• 📄 /src/util/entities/Role.ts

Create a policy validation utility that checks upload permissions based on user/guild premium status and configuration. This utility will:

• Export a PolicyValidator class with methods:

  • validateAvatarUpload(userId: string, isAnimated: boolean) - Checks if user can upload animated avatars based on premium status
  • validateRoleIconUpload(roleId: string, isAnimated: boolean) - Validates role icon uploads (currently static only)
  • validateGuildProfileUpload(guildId: string, userId: string, isAnimated: boolean) - Checks guild profile avatar permissions

• Implement database queries to fetch:

  • User premium status from User entity (premium, premium_type fields)
  • Guild premium tier from Guild entity (premium_tier, premium_subscription_count fields)
  • Role information for role icon uploads

• Apply policy rules from configuration:

  • Check Config.get().cdn.policies.avatars.allowAnimated and requiresPremium flags
  • Cross-reference with user/guild premium status
  • Return descriptive error messages for policy violations

• Handle edge cases like missing entities and provide appropriate fallback behavior

• Use TypeORM queries similar to patterns found in src/util/entities/User.ts and src/util/entities/Guild.ts

📄 /src/cdn/util/StorageManager.ts ^(NEW) 🔗

References

• 📄 /src/cdn/util/Storage.ts
• 📄 /src/cdn/util/S3Storage.ts
• 📄 /src/cdn/util/FileStorage.ts

Create a storage management utility that handles variant storage and cleanup operations. This utility will:

• Export a StorageManager class that wraps the existing Storage interface with enhanced functionality:

  • storeVariants(basePath: string, variants: Map<string, Buffer>) - Stores multiple image variants atomically
  • cleanupOldVariants(basePath: string, keepFiles?: string[]) - Removes old variants while preserving specified files
  • listVariants(basePath: string) - Lists all variants for a given base path
  • getVariant(basePath: string, size?: number, format?: string) - Retrieves best matching variant

• Implement variant naming convention:

  • Original: avatars/{user_id}/{hash} (for backward compatibility)
  • Variants: avatars/{user_id}/{hash}_{size}.{format} (e.g., avatars/123/abc_128.webp)
  • Animated prefix: a_ maintained in hash for animated images

• Handle cleanup logic:

  • Before storing new variants, enumerate existing files in the directory
  • Delete all files except those being newly stored
  • Implement safe cleanup with error handling for concurrent access

• Provide fallback mechanisms:

  • If specific variant not found, try closest smaller size
  • If format not available, fall back to PNG
  • Maintain compatibility with existing single-file storage

• Use the existing storage instance from src/cdn/util/Storage.ts as the underlying storage provider

📄 /src/cdn/routes/avatars.ts ^(NEW) 🔗

References

• 📄 /src/cdn/util/ImageProcessor.ts ^(NEW)
• 📄 /src/cdn/util/PolicyValidator.ts ^(NEW)
• 📄 /src/cdn/util/StorageManager.ts ^(NEW)

Enhance the avatar upload and retrieval routes to implement the complete image pipeline with policy checks, variant generation, and cleanup. Modify the existing routes:

POST /:user_id route:

• Add policy validation using PolicyValidator.validateAvatarUpload() before processing
• Use ImageProcessor.validateImage() to check dimensions and format
• Detect animation with ImageProcessor.isAnimated() and validate against policy
• Generate multiple variants using ImageProcessor.generateVariants() with configured sizes and formats
• Store all variants using StorageManager.storeVariants() with cleanup of old files
• Update response to include variant information and maintain backward compatibility

GET routes (/:user_id and /:user_id/:hash):

• Parse size and format from request path or query parameters (e.g., ?size=128&format=webp)
• Use StorageManager.getVariant() to retrieve best matching variant
• Fall back to original file if no variants exist (backward compatibility)
• Set appropriate Content-Type header based on actual file format
• Maintain existing cache headers (Cache-Control: public, max-age=31536000)

DELETE route:

• Use StorageManager.cleanupOldVariants() to remove all variants for the user
• Maintain existing signature validation and response format

Remove existing TODO comments and replace with implemented functionality. Ensure all changes maintain backward compatibility with existing avatar URLs and API contracts.

📄 /src/cdn/routes/role-icons.ts ^(NEW) 🔗

References

• 📄 /src/cdn/util/ImageProcessor.ts ^(NEW)
• 📄 /src/cdn/util/PolicyValidator.ts ^(NEW)
• 📄 /src/cdn/util/StorageManager.ts ^(NEW)

Update role icon routes to implement the image pipeline while maintaining the static-only policy for role icons. Modify existing routes:

POST /:role_id route:

• Add policy validation using PolicyValidator.validateRoleIconUpload() - should reject animated images regardless of premium status
• Use ImageProcessor.validateImage() to check input image constraints
• Ensure ImageProcessor.isAnimated() returns false, throw error if animated
• Generate static variants only using ImageProcessor.generateVariants() with PNG and WebP formats
• Store variants using StorageManager.storeVariants() with cleanup
• Update response format while maintaining backward compatibility

GET routes (/:role_id and /:role_id/:hash):

• Enhance existing extension-trying logic to also check for size variants
• Use StorageManager.getVariant() to find best matching static variant
• Maintain existing fallback behavior that tries multiple extensions
• Preserve existing cache headers and content-type detection

DELETE route:

• Use StorageManager.cleanupOldVariants() for complete cleanup
• Maintain signature validation

Update the ALLOWED_MIME_TYPES to ensure only static formats are accepted. Remove TODO comments about animated support since role icons should remain static-only. Ensure the .png extension handling in storage paths works correctly with the new variant system.

📄 /src/cdn/routes/guild-profiles.ts ^(NEW) 🔗

References

• 📄 /src/cdn/util/ImageProcessor.ts ^(NEW)
• 📄 /src/cdn/util/PolicyValidator.ts ^(NEW)
• 📄 /src/cdn/util/StorageManager.ts ^(NEW)

Enhance guild profile avatar routes to support the full image pipeline with guild-specific policy validation. Modify existing routes:

POST / route:

• Extract guild_id and user_id from request parameters (route is mounted at /guilds/:guild_id/users/:user_id/avatars)
• Add policy validation using PolicyValidator.validateGuildProfileUpload() with guild and user context
• Use ImageProcessor.validateImage() and ImageProcessor.isAnimated() for input validation
• Check guild premium tier and user premium status for animated avatar permissions
• Generate variants using ImageProcessor.generateVariants() supporting both static and animated formats
• Store variants using StorageManager.storeVariants() with proper cleanup
• Maintain existing path structure: guilds/{guild_id}/users/{user_id}/avatars/{hash}

GET routes (/ and /:hash):

• Parse size/format preferences from request
• Use StorageManager.getVariant() to retrieve appropriate variant
• Handle both static and animated variants based on original upload
• Maintain existing cache headers and content-type detection
• Preserve backward compatibility with existing guild profile URLs

DELETE /:id route:

• Use StorageManager.cleanupOldVariants() for complete cleanup of all variants
• Maintain signature validation and response format

Ensure the animated hash prefix (a_) logic works correctly with the new variant system. Remove TODO comments and replace with implemented functionality. Maintain compatibility with the guild profile avatar system used by the API.

📄 /src/util/util/cdn.ts ^(NEW) 🔗

References

• 📄 /src/api/routes/users/@me/index.ts
• 📄 /src/api/routes/webhooks/#webhook_id/index.ts

Enhance the API-side CDN utility functions to support the new image pipeline features while maintaining backward compatibility. Modify existing functions:

handleFile function:

• Add optional validation parameters for image constraints (dimensions, file size)
• Implement pre-upload validation using basic image detection before sending to CDN
• Add better error handling with more descriptive error messages
• Maintain existing data URL parsing and base64 decoding logic
• Preserve backward compatibility for all existing callers

uploadFile function:

• Add optional metadata parameter to pass additional context to CDN (user premium status, etc.)
• Enhance error handling to provide more specific error messages from CDN responses
• Maintain existing FormData construction and signature authentication
• Preserve existing return type and response handling

deleteFile function:

• No changes needed as it already handles the complete cleanup via CDN DELETE endpoint

Add JSDoc comments to document the enhanced functionality and parameter options. Ensure all changes are backward compatible with existing API routes that call these functions, including src/api/routes/users/@me/index.ts and src/api/routes/webhooks/#webhook_id/index.ts.

📄 /src/cdn/util/index.ts ^(NEW) 🔗

References

• 📄 /src/cdn/util/ImageProcessor.ts ^(NEW)
• 📄 /src/cdn/util/PolicyValidator.ts ^(NEW)
• 📄 /src/cdn/util/StorageManager.ts ^(NEW)

Update the CDN utilities index file to export the new image processing utilities. Add exports for:

• ImageProcessor from ./ImageProcessor
• PolicyValidator from ./PolicyValidator
• StorageManager from ./StorageManager

Maintain existing exports for storage, multer, and any other current utilities. This ensures the new utilities are available for import by the CDN routes and other parts of the system.

Diagram

sequenceDiagram
    participant Client
    participant API
    participant CDN
    participant Storage
    participant DB

    Note over Client,Storage: Image Upload Flow with New Pipeline

    Client->>API: PATCH /users/@me (avatar: data:image/...)
    API->>API: handleFile() - parse data URL
    API->>CDN: POST /avatars/{user_id} (multipart)
    
    Note over CDN: New Policy & Processing Pipeline
    CDN->>DB: Query user premium status
    CDN->>CDN: PolicyValidator.validateAvatarUpload()
    CDN->>CDN: ImageProcessor.validateImage()
    CDN->>CDN: ImageProcessor.isAnimated()
    
    alt Policy Violation
        CDN-->>API: 400 Policy Error
        API-->>Client: 400 Error Response
    else Policy OK
        CDN->>CDN: ImageProcessor.generateVariants()
        Note over CDN: Generate sizes: 64,128,256,512<br/>Formats: png,webp
        CDN->>Storage: StorageManager.cleanupOldVariants()
        CDN->>Storage: StorageManager.storeVariants()
        CDN-->>API: 200 {id, variants, url}
        API-->>Client: 200 Updated User
    end

    Note over Client,Storage: Image Retrieval with Variants

    Client->>CDN: GET /avatars/{user_id}/{hash}?size=128&format=webp
    CDN->>Storage: StorageManager.getVariant()
    
    alt Variant Found
        Storage-->>CDN: Return variant buffer
    else Fallback
        Storage-->>CDN: Return closest/original
    end
    
    CDN-->>Client: Image with correct Content-Type

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

I've thoroughly analyzed the CDN image pipeline codebase and understand the complete request flow from API to CDN. The current implementation has basic upload/download functionality but lacks the sophisticated image processing, policy validation, and cleanup features requested in the GitHub issue. The system uses a microservice architecture where the API service calls the CDN service via HTTP with signature-based authentication.

### Approach

I'll implement a comprehensive CDN image pipeline that adds policy validation, multi-format/multi-size generation, and cleanup functionality while maintaining backward compatibility. The solution will leverage existing Sharp/Jimp libraries for image processing, extend the configuration system for policy controls, and implement efficient storage management with proper cleanup of old variants.

### Reasoning

I explored the codebase systematically, starting with the CDN routes mentioned in the issue, then examining the storage infrastructure, configuration system, and API-to-CDN communication flow. I found the existing image processing capabilities in ImageProxy middleware and discovered the premium/policy system through User and Guild entities. I also analyzed the complete request flow from client through API to CDN to understand integration points.

## Mermaid Diagram

sequenceDiagram
    participant Client
    participant API
    participant CDN
    participant Storage
    participant DB

    Note over Client,Storage: Image Upload Flow with New Pipeline

    Client->>API: PATCH /users/@me (avatar: data:image/...)
    API->>API: handleFile() - parse data URL
    API->>CDN: POST /avatars/{user_id} (multipart)
    
    Note over CDN: New Policy & Processing Pipeline
    CDN->>DB: Query user premium status
    CDN->>CDN: PolicyValidator.validateAvatarUpload()
    CDN->>CDN: ImageProcessor.validateImage()
    CDN->>CDN: ImageProcessor.isAnimated()
    
    alt Policy Violation
        CDN-->>API: 400 Policy Error
        API-->>Client: 400 Error Response
    else Policy OK
        CDN->>CDN: ImageProcessor.generateVariants()
        Note over CDN: Generate sizes: 64,128,256,512<br/>Formats: png,webp
        CDN->>Storage: StorageManager.cleanupOldVariants()
        CDN->>Storage: StorageManager.storeVariants()
        CDN-->>API: 200 {id, variants, url}
        API-->>Client: 200 Updated User
    end

    Note over Client,Storage: Image Retrieval with Variants

    Client->>CDN: GET /avatars/{user_id}/{hash}?size=128&format=webp
    CDN->>Storage: StorageManager.getVariant()
    
    alt Variant Found
        Storage-->>CDN: Return variant buffer
    else Fallback
        Storage-->>CDN: Return closest/original
    end
    
    CDN-->>Client: Image with correct Content-Type

## Proposed File Changes

### /src/util/config/types/CdnConfiguration.ts(NEW)

Extend the existing `CdnConfiguration` class to include comprehensive image processing and policy configuration options. Add fields for:

- `imageProcessing` object containing:
  - `sizes: number[]` - Array of allowed image sizes (default: [64, 128, 256, 512])
  - `formats: string[]` - Array of output formats (default: ["png", "webp"])
  - `maxDimensions: { width: number, height: number }` - Maximum input image dimensions
  - `quality: { webp: number, jpeg: number }` - Quality settings for lossy formats

- `policies` object containing:
  - `avatars` with `allowAnimated: boolean` and `requiresPremium: boolean`
  - `roleIcons` with `allowAnimated: boolean` and `requiresPremium: boolean` 
  - `guildProfiles` with `allowAnimated: boolean` and `requiresPremium: boolean`

- `cleanup` object with:
  - `enabled: boolean` - Whether to cleanup old variants
  - `retainOriginal: boolean` - Whether to keep original uploads

This extends the existing configuration structure while maintaining backward compatibility with current `resizeHeightMax`, `resizeWidthMax`, and `imagorServerUrl` fields.

### /src/cdn/util/ImageProcessor.ts(NEW)

References: 

- /src/api/middlewares/ImageProxy.ts

Create a new image processing utility that abstracts Sharp and Jimp operations for consistent image manipulation across the CDN. This utility will:

- Export an `ImageProcessor` class that detects and uses Sharp if available, falls back to Jimp, or throws descriptive errors if neither is available
- Provide methods for:
  - `generateVariants(buffer: Buffer, sizes: number[], formats: string[])` - Creates multiple size/format combinations from input buffer
  - `validateImage(buffer: Buffer, maxDimensions: {width: number, height: number})` - Validates image dimensions and format
  - `isAnimated(buffer: Buffer)` - Detects if image contains animation
  - `getImageInfo(buffer: Buffer)` - Returns metadata like dimensions, format, file size

- Handle format conversion logic:
  - Static images: generate PNG and WebP variants
  - Animated images: preserve as GIF/APNG, generate static PNG/WebP from first frame
  - Apply quality settings for lossy formats

- Implement proper error handling with fallbacks and descriptive error messages
- Use the same Sharp/Jimp detection pattern found in `src/api/middlewares/ImageProxy.ts` for consistency

### /src/cdn/util/PolicyValidator.ts(NEW)

References: 

- /src/util/entities/User.ts
- /src/util/entities/Guild.ts
- /src/util/entities/Role.ts

Create a policy validation utility that checks upload permissions based on user/guild premium status and configuration. This utility will:

- Export a `PolicyValidator` class with methods:
  - `validateAvatarUpload(userId: string, isAnimated: boolean)` - Checks if user can upload animated avatars based on premium status
  - `validateRoleIconUpload(roleId: string, isAnimated: boolean)` - Validates role icon uploads (currently static only)
  - `validateGuildProfileUpload(guildId: string, userId: string, isAnimated: boolean)` - Checks guild profile avatar permissions

- Implement database queries to fetch:
  - User premium status from `User` entity (`premium`, `premium_type` fields)
  - Guild premium tier from `Guild` entity (`premium_tier`, `premium_subscription_count` fields)
  - Role information for role icon uploads

- Apply policy rules from configuration:
  - Check `Config.get().cdn.policies.avatars.allowAnimated` and `requiresPremium` flags
  - Cross-reference with user/guild premium status
  - Return descriptive error messages for policy violations

- Handle edge cases like missing entities and provide appropriate fallback behavior
- Use TypeORM queries similar to patterns found in `src/util/entities/User.ts` and `src/util/entities/Guild.ts`

### /src/cdn/util/StorageManager.ts(NEW)

References: 

- /src/cdn/util/Storage.ts
- /src/cdn/util/S3Storage.ts
- /src/cdn/util/FileStorage.ts

Create a storage management utility that handles variant storage and cleanup operations. This utility will:

- Export a `StorageManager` class that wraps the existing `Storage` interface with enhanced functionality:
  - `storeVariants(basePath: string, variants: Map<string, Buffer>)` - Stores multiple image variants atomically
  - `cleanupOldVariants(basePath: string, keepFiles?: string[])` - Removes old variants while preserving specified files
  - `listVariants(basePath: string)` - Lists all variants for a given base path
  - `getVariant(basePath: string, size?: number, format?: string)` - Retrieves best matching variant

- Implement variant naming convention:
  - Original: `avatars/{user_id}/{hash}` (for backward compatibility)
  - Variants: `avatars/{user_id}/{hash}_{size}.{format}` (e.g., `avatars/123/abc_128.webp`)
  - Animated prefix: `a_` maintained in hash for animated images

- Handle cleanup logic:
  - Before storing new variants, enumerate existing files in the directory
  - Delete all files except those being newly stored
  - Implement safe cleanup with error handling for concurrent access

- Provide fallback mechanisms:
  - If specific variant not found, try closest smaller size
  - If format not available, fall back to PNG
  - Maintain compatibility with existing single-file storage

- Use the existing `storage` instance from `src/cdn/util/Storage.ts` as the underlying storage provider

### /src/cdn/routes/avatars.ts(NEW)

References: 

- /src/cdn/util/ImageProcessor.ts(NEW)
- /src/cdn/util/PolicyValidator.ts(NEW)
- /src/cdn/util/StorageManager.ts(NEW)

Enhance the avatar upload and retrieval routes to implement the complete image pipeline with policy checks, variant generation, and cleanup. Modify the existing routes:

**POST /:user_id route:**
- Add policy validation using `PolicyValidator.validateAvatarUpload()` before processing
- Use `ImageProcessor.validateImage()` to check dimensions and format
- Detect animation with `ImageProcessor.isAnimated()` and validate against policy
- Generate multiple variants using `ImageProcessor.generateVariants()` with configured sizes and formats
- Store all variants using `StorageManager.storeVariants()` with cleanup of old files
- Update response to include variant information and maintain backward compatibility

**GET routes (/:user_id and /:user_id/:hash):**
- Parse size and format from request path or query parameters (e.g., `?size=128&format=webp`)
- Use `StorageManager.getVariant()` to retrieve best matching variant
- Fall back to original file if no variants exist (backward compatibility)
- Set appropriate `Content-Type` header based on actual file format
- Maintain existing cache headers (`Cache-Control: public, max-age=31536000`)

**DELETE route:**
- Use `StorageManager.cleanupOldVariants()` to remove all variants for the user
- Maintain existing signature validation and response format

Remove existing TODO comments and replace with implemented functionality. Ensure all changes maintain backward compatibility with existing avatar URLs and API contracts.

### /src/cdn/routes/role-icons.ts(NEW)

References: 

- /src/cdn/util/ImageProcessor.ts(NEW)
- /src/cdn/util/PolicyValidator.ts(NEW)
- /src/cdn/util/StorageManager.ts(NEW)

Update role icon routes to implement the image pipeline while maintaining the static-only policy for role icons. Modify existing routes:

**POST /:role_id route:**
- Add policy validation using `PolicyValidator.validateRoleIconUpload()` - should reject animated images regardless of premium status
- Use `ImageProcessor.validateImage()` to check input image constraints
- Ensure `ImageProcessor.isAnimated()` returns false, throw error if animated
- Generate static variants only using `ImageProcessor.generateVariants()` with PNG and WebP formats
- Store variants using `StorageManager.storeVariants()` with cleanup
- Update response format while maintaining backward compatibility

**GET routes (/:role_id and /:role_id/:hash):**
- Enhance existing extension-trying logic to also check for size variants
- Use `StorageManager.getVariant()` to find best matching static variant
- Maintain existing fallback behavior that tries multiple extensions
- Preserve existing cache headers and content-type detection

**DELETE route:**
- Use `StorageManager.cleanupOldVariants()` for complete cleanup
- Maintain signature validation

Update the ALLOWED_MIME_TYPES to ensure only static formats are accepted. Remove TODO comments about animated support since role icons should remain static-only. Ensure the `.png` extension handling in storage paths works correctly with the new variant system.

### /src/cdn/routes/guild-profiles.ts(NEW)

References: 

- /src/cdn/util/ImageProcessor.ts(NEW)
- /src/cdn/util/PolicyValidator.ts(NEW)
- /src/cdn/util/StorageManager.ts(NEW)

Enhance guild profile avatar routes to support the full image pipeline with guild-specific policy validation. Modify existing routes:

**POST / route:**
- Extract `guild_id` and `user_id` from request parameters (route is mounted at `/guilds/:guild_id/users/:user_id/avatars`)
- Add policy validation using `PolicyValidator.validateGuildProfileUpload()` with guild and user context
- Use `ImageProcessor.validateImage()` and `ImageProcessor.isAnimated()` for input validation
- Check guild premium tier and user premium status for animated avatar permissions
- Generate variants using `ImageProcessor.generateVariants()` supporting both static and animated formats
- Store variants using `StorageManager.storeVariants()` with proper cleanup
- Maintain existing path structure: `guilds/{guild_id}/users/{user_id}/avatars/{hash}`

**GET routes (/ and /:hash):**
- Parse size/format preferences from request
- Use `StorageManager.getVariant()` to retrieve appropriate variant
- Handle both static and animated variants based on original upload
- Maintain existing cache headers and content-type detection
- Preserve backward compatibility with existing guild profile URLs

**DELETE /:id route:**
- Use `StorageManager.cleanupOldVariants()` for complete cleanup of all variants
- Maintain signature validation and response format

Ensure the animated hash prefix (`a_`) logic works correctly with the new variant system. Remove TODO comments and replace with implemented functionality. Maintain compatibility with the guild profile avatar system used by the API.

### /src/util/util/cdn.ts(NEW)

References: 

- /src/api/routes/users/@me/index.ts
- /src/api/routes/webhooks/#webhook_id/index.ts

Enhance the API-side CDN utility functions to support the new image pipeline features while maintaining backward compatibility. Modify existing functions:

**handleFile function:**
- Add optional validation parameters for image constraints (dimensions, file size)
- Implement pre-upload validation using basic image detection before sending to CDN
- Add better error handling with more descriptive error messages
- Maintain existing data URL parsing and base64 decoding logic
- Preserve backward compatibility for all existing callers

**uploadFile function:**
- Add optional metadata parameter to pass additional context to CDN (user premium status, etc.)
- Enhance error handling to provide more specific error messages from CDN responses
- Maintain existing FormData construction and signature authentication
- Preserve existing return type and response handling

**deleteFile function:**
- No changes needed as it already handles the complete cleanup via CDN DELETE endpoint

Add JSDoc comments to document the enhanced functionality and parameter options. Ensure all changes are backward compatible with existing API routes that call these functions, including `src/api/routes/users/@me/index.ts` and `src/api/routes/webhooks/#webhook_id/index.ts`.

### /src/cdn/util/index.ts(NEW)

References: 

- /src/cdn/util/ImageProcessor.ts(NEW)
- /src/cdn/util/PolicyValidator.ts(NEW)
- /src/cdn/util/StorageManager.ts(NEW)

Update the CDN utilities index file to export the new image processing utilities. Add exports for:

- `ImageProcessor` from `./ImageProcessor`
- `PolicyValidator` from `./PolicyValidator` 
- `StorageManager` from `./StorageManager`

Maintain existing exports for `storage`, `multer`, and any other current utilities. This ensures the new utilities are available for import by the CDN routes and other parts of the system.

---

Developer Humor

🖼️ Why did the avatar go to therapy?\n> Because it had too many issues with its image! 📸\n> Now with our new pipeline, every pixel gets\n> the premium treatment it deserves! ✨\n> \n> ┌─────────────────┐\n> │ Before: 😵 │ After: 😎 │\n> │ One size fits │ Multi-size, │\n> │ none perfectly │ multi-format │\n> └─────────────────┘

---

Execution Information

Branch: master
Commit: 0442d70

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.