@restnfeel/agentc-starter-kit/src/cms/cache/types.ts

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

// Cache Types and Interfaces for AgentC CMS Caching System

export type CacheLevel = "browser" | "cdn" | "server" | "database" | "memory";
export type CacheStrategy =
  | "ttl"
  | "lru"
  | "lfu"
  | "invalidation-based"
  | "write-through"
  | "write-behind";
export type CacheProvider =
  | "redis"
  | "memcached"
  | "cloudflare"
  | "aws-cloudfront"
  | "azure-cdn"
  | "memory"
  | "browser";
export type ContentType =
  | "static-asset"
  | "component-data"
  | "api-response"
  | "template-data"
  | "user-session"
  | "page-content";
export type CacheStatus =
  | "hit"
  | "miss"
  | "expired"
  | "invalid"
  | "warming"
  | "error";
export type InvalidationStrategy =
  | "manual"
  | "time-based"
  | "version-based"
  | "tag-based"
  | "dependency-based";

// Core Cache Configuration
export interface CacheConfig {
  level: CacheLevel;
  strategy: CacheStrategy;
  provider: CacheProvider;
  ttl: number; // Time to live in seconds
  maxSize?: number; // Maximum cache size in MB
  maxItems?: number; // Maximum number of cached items
  compression?: boolean;
  encryption?: boolean;
  region?: string; // For CDN configurations
  endpoint?: string; // For custom cache endpoints
  credentials?: CacheCredentials;
}

export interface CacheCredentials {
  apiKey?: string;
  secretKey?: string;
  region?: string;
  endpoint?: string;
  token?: string;
}

// Cache Entry Structure
export interface CacheEntry<T = any> {
  key: string;
  value: T;
  contentType: ContentType;
  metadata: CacheMetadata;
  headers?: Record<string, string>;
  etag?: string;
  lastModified: Date;
  createdAt: Date;
  expiresAt: Date;
  accessCount: number;
  lastAccessed: Date;
  size: number; // Size in bytes
  compressed: boolean;
  encrypted: boolean;
  tags: string[];
  dependencies: string[];
}

export interface CacheMetadata {
  source: string; // Origin of the cached data
  version: string;
  checksum: string;
  mimeType?: string;
  encoding?: string;
  originalSize: number;
  compressedSize?: number;
  cacheLevel: CacheLevel;
  strategy: CacheStrategy;
  priority: number; // 1-10, higher = more important
  cost: number; // Cost to regenerate/fetch
}

// Cache Statistics and Metrics
export interface CacheStats {
  hitRate: number; // Percentage of cache hits
  missRate: number; // Percentage of cache misses
  hitCount: number;
  missCount: number;
  totalRequests: number;
  averageResponseTime: number;
  medianResponseTime: number;
  p95ResponseTime: number;
  p99ResponseTime: number;
  totalSize: number; // Total cache size in bytes
  itemCount: number;
  evictionCount: number;
  errorCount: number;
  lastReset: Date;
  uptime: number; // Uptime in seconds
}

export interface CachePerformanceMetrics {
  cacheLevel: CacheLevel;
  provider: CacheProvider;
  stats: CacheStats;
  networkMetrics: NetworkMetrics;
  resourceUtilization: ResourceUtilization;
  costMetrics: CostMetrics;
  trends: PerformanceTrends;
  alerts: CacheAlert[];
}

export interface NetworkMetrics {
  bandwidth: number; // MB/s
  latency: number; // ms
  throughput: number; // requests/s
  errorRate: number; // percentage
  timeouts: number;
  connections: number;
  bytesTransferred: number;
  requestsPerSecond: number;
}

export interface ResourceUtilization {
  cpuUsage: number; // percentage
  memoryUsage: number; // percentage
  diskUsage: number; // percentage
  networkUsage: number; // percentage
  connectionPool: number; // active connections
}

export interface CostMetrics {
  storageCost: number; // USD per month
  bandwidthCost: number; // USD per month
  computeCost: number; // USD per month
  totalCost: number; // USD per month
  costPerRequest: number; // USD
  savings: number; // USD saved through caching
}

export interface PerformanceTrends {
  hitRateTrend: number[]; // Last 24 hours
  responseTrend: number[]; // Response times
  errorTrend: number[]; // Error rates
  costTrend: number[]; // Cost over time
  usageTrend: number[]; // Usage patterns
}

// Cache Invalidation
export interface CacheInvalidation {
  strategy: InvalidationStrategy;
  trigger: InvalidationTrigger;
  scope: InvalidationScope;
  pattern?: string; // For pattern-based invalidation
  tags?: string[]; // For tag-based invalidation
  dependencies?: string[]; // For dependency-based invalidation
  timestamp: Date;
  reason: string;
  executedBy: string;
}

export interface InvalidationTrigger {
  type: "manual" | "automatic" | "scheduled" | "event-based";
  source: string;
  condition?: string;
  schedule?: CronSchedule;
  event?: string;
}

export interface InvalidationScope {
  level: CacheLevel[];
  contentTypes: ContentType[];
  keys?: string[];
  patterns?: string[];
  tags?: string[];
  excludeKeys?: string[];
}

export interface CronSchedule {
  pattern: string; // Cron pattern
  timezone: string;
  enabled: boolean;
  nextRun: Date;
  lastRun?: Date;
}

// CDN Configuration
export interface CDNConfig extends CacheConfig {
  provider:
    | "cloudflare"
    | "aws-cloudfront"
    | "azure-cdn"
    | "google-cdn"
    | "fastly"
    | "keycdn";
  distributionId?: string;
  zones: CDNZone[];
  behaviors: CDNBehavior[];
  headers: CDNHeaderConfig;
  compression: CompressionConfig;
  security: CDNSecurityConfig;
  analytics: boolean;
  logging: boolean;
  purgeApi: boolean;
}

export interface CDNZone {
  name: string;
  region: string;
  enabled: boolean;
  ttl: number;
  origin: string;
  customDomain?: string;
  ssl: boolean;
  http2: boolean;
  ipv6: boolean;
}

export interface CDNBehavior {
  pathPattern: string;
  cachingDisabled: boolean;
  ttl: number;
  queryStringCaching: boolean;
  headerCaching: string[];
  compression: boolean;
  contentTypes: string[];
  methods: string[];
}

export interface CDNHeaderConfig {
  cacheControl: string;
  vary: string[];
  customHeaders: Record<string, string>;
  corsHeaders: CORSConfig;
  securityHeaders: SecurityHeaders;
}

export interface CompressionConfig {
  enabled: boolean;
  algorithms: ("gzip" | "brotli" | "deflate")[];
  minSize: number; // Minimum file size to compress (bytes)
  contentTypes: string[];
  level: number; // Compression level 1-9
}

export interface CDNSecurityConfig {
  hotlinkProtection: boolean;
  ipWhitelist: string[];
  ipBlacklist: string[];
  rateLimiting: RateLimitConfig;
  ddosProtection: boolean;
  waf: boolean;
  botProtection: boolean;
}

export interface CORSConfig {
  allowedOrigins: string[];
  allowedMethods: string[];
  allowedHeaders: string[];
  exposedHeaders: string[];
  credentials: boolean;
  maxAge: number;
}

export interface SecurityHeaders {
  xFrameOptions: string;
  xContentTypeOptions: string;
  xXSSProtection: string;
  referrerPolicy: string;
  contentSecurityPolicy: string;
  strictTransportSecurity: string;
}

export interface RateLimitConfig {
  enabled: boolean;
  requestsPerMinute: number;
  requestsPerHour: number;
  requestsPerDay: number;
  burstLimit: number;
  whitelist: string[];
  action: "block" | "throttle" | "captcha";
}

// Browser Cache Configuration
export interface BrowserCacheConfig extends CacheConfig {
  serviceWorker: boolean;
  localStorage: boolean;
  sessionStorage: boolean;
  indexedDB: boolean;
  cacheAPI: boolean;
  maxAge: number;
  staleWhileRevalidate: number;
  cacheFirst: boolean;
  networkFirst: boolean;
  offlineSupport: boolean;
}

// Server Cache Configuration
export interface ServerCacheConfig extends CacheConfig {
  redis?: RedisConfig;
  memcached?: MemcachedConfig;
  memory?: MemoryConfig;
  clustering: boolean;
  sharding: boolean;
  replication: boolean;
  persistence: boolean;
  backupSchedule?: CronSchedule;
}

export interface RedisConfig {
  host: string;
  port: number;
  password?: string;
  database: number;
  cluster: boolean;
  sentinel: boolean;
  maxConnections: number;
  connectionTimeout: number;
  commandTimeout: number;
  retryAttempts: number;
}

export interface MemcachedConfig {
  servers: string[];
  timeout: number;
  retries: number;
  poolSize: number;
  compression: boolean;
  serialization: "json" | "msgpack" | "pickle";
}

export interface MemoryConfig {
  maxSize: number; // MB
  algorithm: "lru" | "lfu" | "fifo";
  checkPeriod: number; // seconds
  gcInterval: number; // seconds
}

// Cache Alerts and Monitoring
export interface CacheAlert {
  id: string;
  type: AlertType;
  severity: AlertSeverity;
  message: string;
  description: string;
  threshold: number;
  currentValue: number;
  triggerTime: Date;
  resolvedTime?: Date;
  status: AlertStatus;
  cacheLevel: CacheLevel;
  provider: CacheProvider;
  actions: AlertAction[];
}

export type AlertType =
  | "hit-rate-low"
  | "miss-rate-high"
  | "response-time-high"
  | "error-rate-high"
  | "storage-full"
  | "memory-usage-high"
  | "connection-limit"
  | "cost-threshold"
  | "availability-low";

export type AlertSeverity = "low" | "medium" | "high" | "critical";
export type AlertStatus = "active" | "resolved" | "acknowledged" | "suppressed";

export interface AlertAction {
  type: "email" | "sms" | "webhook" | "auto-scale" | "invalidate" | "failover";
  enabled: boolean;
  config: Record<string, any>;
  conditions: string[];
}

// Cache Warming and Preloading
export interface CacheWarmingConfig {
  enabled: boolean;
  schedule: CronSchedule;
  urls: string[];
  patterns: string[];
  priority: number;
  concurrency: number;
  timeout: number;
  retries: number;
  userAgents: string[];
  headers: Record<string, string>;
}

export interface CachePreloadRequest {
  key: string;
  url: string;
  contentType: ContentType;
  priority: number;
  headers?: Record<string, string>;
  method: string;
  body?: any;
  timeout: number;
}

// Cache API Interfaces
export interface ICacheProvider {
  get<T>(key: string): Promise<CacheEntry<T> | null>;
  set<T>(key: string, value: T, options?: CacheSetOptions): Promise<boolean>;
  delete(key: string): Promise<boolean>;
  clear(pattern?: string): Promise<boolean>;
  exists(key: string): Promise<boolean>;
  ttl(key: string): Promise<number>;
  keys(pattern?: string): Promise<string[]>;
  stats(): Promise<CacheStats>;
  health(): Promise<HealthStatus>;
}

export interface CacheSetOptions {
  ttl?: number;
  tags?: string[];
  dependencies?: string[];
  priority?: number;
  metadata?: Partial<CacheMetadata>;
  headers?: Record<string, string>;
  compress?: boolean;
  encrypt?: boolean;
}

export interface HealthStatus {
  status: "healthy" | "degraded" | "unhealthy";
  uptime: number;
  lastCheck: Date;
  responseTime: number;
  issues: string[];
  metrics: CacheStats;
}

// Cache Management API
export interface CacheManagerAPI {
  // Configuration
  configure(config: CacheConfig): Promise<void>;
  getConfig(): Promise<CacheConfig>;
  updateConfig(updates: Partial<CacheConfig>): Promise<void>;

  // Cache Operations
  get<T>(key: string, level?: CacheLevel): Promise<T | null>;
  set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
  invalidate(request: CacheInvalidation): Promise<void>;
  warm(config: CacheWarmingConfig): Promise<void>;
  preload(requests: CachePreloadRequest[]): Promise<void>;

  // Monitoring and Analytics
  getStats(level?: CacheLevel): Promise<CachePerformanceMetrics>;
  getAlerts(): Promise<CacheAlert[]>;
  exportMetrics(format: "json" | "csv" | "prometheus"): Promise<string>;

  // Management
  flush(level?: CacheLevel): Promise<void>;
  backup(): Promise<string>; // Returns backup ID
  restore(backupId: string): Promise<void>;
  optimize(): Promise<void>;
}

// Event System
export interface CacheEvent {
  type: CacheEventType;
  level: CacheLevel;
  provider: CacheProvider;
  key?: string;
  contentType?: ContentType;
  timestamp: Date;
  data: Record<string, any>;
  metadata: {
    source: string;
    version: string;
    traceId: string;
  };
}

export type CacheEventType =
  | "cache-hit"
  | "cache-miss"
  | "cache-set"
  | "cache-delete"
  | "cache-invalidate"
  | "cache-warm"
  | "cache-error"
  | "cache-full"
  | "cache-expired"
  | "provider-connect"
  | "provider-disconnect"
  | "alert-triggered"
  | "alert-resolved";

export interface CacheEventListener {
  eventTypes: CacheEventType[];
  handler: (event: CacheEvent) => void;
  filters?: Record<string, any>;
  priority: number;
}

// Integration with AgentC Components
export interface ComponentCacheConfig {
  componentType: string; // HeroSection, CTASection, etc.
  cacheStrategy: CacheStrategy;
  ttl: number;
  invalidationTriggers: string[];
  dependencies: string[];
  priority: number;
  preprocessing?: ComponentPreprocessConfig;
}

export interface ComponentPreprocessConfig {
  minify: boolean;
  compress: boolean;
  optimize: boolean;
  bundleCSS: boolean;
  bundleJS: boolean;
  generateETags: boolean;
  responsive: boolean;
}

// Cache Policies
export interface CachePolicy {
  name: string;
  description: string;
  rules: CachePolicyRule[];
  priority: number;
  enabled: boolean;
  environments: string[];
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
}

export interface CachePolicyRule {
  condition: string; // JavaScript expression
  action: CachePolicyAction;
  weight: number;
  description: string;
}

export interface CachePolicyAction {
  type: "cache" | "bypass" | "redirect" | "modify";
  config: CacheConfig;
  headers?: Record<string, string>;
  redirectUrl?: string;
  modifications?: Record<string, any>;
}

// Export all interfaces
export default {
  // Types
  CacheLevel,
  CacheStrategy,
  CacheProvider,
  ContentType,
  CacheStatus,
  InvalidationStrategy,
  AlertType,
  AlertSeverity,
  AlertStatus,
  CacheEventType,

  // Main interfaces
  CacheConfig,
  CacheEntry,
  CacheMetadata,
  CacheStats,
  CachePerformanceMetrics,
  CacheInvalidation,
  CDNConfig,
  BrowserCacheConfig,
  ServerCacheConfig,
  CacheAlert,
  ICacheProvider,
  CacheManagerAPI,
  CacheEvent,
  ComponentCacheConfig,
  CachePolicy,
};