eb38c9d942
Some checks failed
CI / build (push) Failing after 4m42s
- 添加缺失的 parser 辅助函数（parser_expect_string, parser_skip_value, parser_number_str） - 修复 Makefile：添加 test_cache 构建规则，补充 cache.c 依赖 - 修复 test_cache.c：使用 cache_stats() API 替代直接访问内部字段 - 修复 test_config.c：更新 config_merge() 调用参数以匹配新签名 - 修复 CI 工作流：使用 make build-all 构建依赖
134 lines
4.0 KiB
C
134 lines
4.0 KiB
C
/**
|
||
* cache.h - 内存响应缓存模块
|
||
*
|
||
* 基于 LRU + TTL 策略的轻量级内存缓存，用于缓存小文件响应。
|
||
* 避免重复磁盘 I/O，提升静态文件服务性能。
|
||
*
|
||
* 设计要点：
|
||
* - 哈希表 + 双向链表实现 O(1) 的 get/put
|
||
* - 单条缓存上限：避免大文件撑爆内存
|
||
* - 总容量上限：LRU 淘汰最久未使用的条目
|
||
* - TTL 过期：基于 expires_at 时间戳
|
||
* - 文件 mtime 校验：文件修改后缓存自动失效
|
||
* - 线程安全：pthread_mutex 保护
|
||
*
|
||
* @author xfy
|
||
*/
|
||
|
||
#ifndef COCOON_CACHE_H
|
||
#define COCOON_CACHE_H
|
||
|
||
#include <stddef.h>
|
||
#include <stdint.h>
|
||
#include <stdbool.h>
|
||
#include <time.h>
|
||
|
||
/* 前向声明，避免暴露内部结构 */
|
||
typedef struct cocoon_cache cocoon_cache_t;
|
||
|
||
/**
|
||
* cocoon_cache_entry_t - 缓存条目
|
||
*
|
||
* 存储完整的 HTTP 响应（头 + 体），用于直接发送给客户端。
|
||
*/
|
||
typedef struct {
|
||
char *key; /**< 缓存键（文件绝对路径） */
|
||
char *header; /**< 格式化后的 HTTP 响应头 */
|
||
size_t header_len; /**< 响应头长度 */
|
||
char *body; /**< 响应体（文件内容） */
|
||
size_t body_len; /**< 响应体长度 */
|
||
time_t mtime; /**< 文件修改时间（用于失效校验） */
|
||
time_t expires_at; /**< TTL 过期时间 */
|
||
} cocoon_cache_entry_t;
|
||
|
||
/**
|
||
* cocoon_cache_stats_t - 缓存统计
|
||
*/
|
||
typedef struct {
|
||
size_t entries; /**< 当前条目数 */
|
||
size_t total_size; /**< 当前总字节数 */
|
||
size_t hits; /**< 命中次数 */
|
||
size_t misses; /**< 未命中次数 */
|
||
size_t evictions; /**< 淘汰次数 */
|
||
size_t expirations; /**< TTL 过期次数 */
|
||
} cocoon_cache_stats_t;
|
||
|
||
/**
|
||
* cache_create - 创建缓存实例
|
||
*
|
||
* @param max_size 最大总容量（字节），0 表示默认 64MB
|
||
* @param ttl_seconds TTL 秒数，0 表示默认 60
|
||
* @param max_entry_size 单条最大大小（字节），0 表示默认 1MB
|
||
* @return 缓存实例，失败返回 NULL
|
||
*/
|
||
cocoon_cache_t *cache_create(size_t max_size, uint32_t ttl_seconds, size_t max_entry_size);
|
||
|
||
/**
|
||
* cache_destroy - 销毁缓存实例
|
||
*
|
||
* 释放所有缓存条目和内部结构。
|
||
*
|
||
* @param cache 缓存实例
|
||
*/
|
||
void cache_destroy(cocoon_cache_t *cache);
|
||
|
||
/**
|
||
* cache_get - 获取缓存条目
|
||
*
|
||
* 查找指定 key 的缓存。如果条目存在但 mtime 不匹配或已过期，
|
||
* 则视为未命中并删除该条目。
|
||
*
|
||
* @param cache 缓存实例
|
||
* @param key 缓存键（文件绝对路径）
|
||
* @param mtime 当前文件修改时间（用于失效校验）
|
||
* @return 缓存条目指针（引用，不拷贝），未命中返回 NULL
|
||
*/
|
||
const cocoon_cache_entry_t *cache_get(cocoon_cache_t *cache, const char *key, time_t mtime);
|
||
|
||
/**
|
||
* cache_put - 存入缓存
|
||
*
|
||
* 将响应存入缓存。如果缓存已满，按 LRU 淘汰旧条目。
|
||
* 如果条目大小超过 max_entry_size，则忽略（不存入）。
|
||
*
|
||
* @param cache 缓存实例
|
||
* @param key 缓存键
|
||
* @param header 响应头（会被拷贝）
|
||
* @param header_len 响应头长度
|
||
* @param body 响应体（会被拷贝）
|
||
* @param body_len 响应体长度
|
||
* @param mtime 文件修改时间
|
||
*/
|
||
void cache_put(cocoon_cache_t *cache, const char *key,
|
||
const char *header, size_t header_len,
|
||
const char *body, size_t body_len,
|
||
time_t mtime);
|
||
|
||
/**
|
||
* cache_stats - 获取缓存统计
|
||
*
|
||
* @param cache 缓存实例
|
||
* @param stats 输出统计结构
|
||
*/
|
||
void cache_stats(cocoon_cache_t *cache, cocoon_cache_stats_t *stats);
|
||
|
||
/**
|
||
* cache_clear - 清空缓存
|
||
*
|
||
* 删除所有缓存条目，重置统计。
|
||
*
|
||
* @param cache 缓存实例
|
||
*/
|
||
void cache_clear(cocoon_cache_t *cache);
|
||
|
||
/**
|
||
* cache_is_eligible - 判断文件是否适合缓存
|
||
*
|
||
* @param cache 缓存实例
|
||
* @param file_size 文件大小（字节）
|
||
* @return true 适合缓存
|
||
*/
|
||
bool cache_is_eligible(const cocoon_cache_t *cache, int64_t file_size);
|
||
|
||
#endif /* COCOON_CACHE_H */
|