File Server

Module <cweb/fileserver.h> — static files and in-memory cache

Loads and serves static assets from the filesystem and/or a binary cache. Supports exclusion patterns (fnmatch), MIME detection, and hybrid mode.

Constants

MAX_FILENAME, MAX_MIME_TYPE, MAX_CACHED_FILES

Types

CachedFile

Contains relative name, MIME type, pointer to in-memory data, size, last_modified, is_loaded.

FileServerMode

  • FILESERVER_MODE_FILESYSTEM — directly from disk.
  • FILESERVER_MODE_MEMORY — cache only.
  • FILESERVER_MODE_HYBRID — cache first, else filesystem.

FileServerConfig

  • static_dir — asset root directory.
  • cache_file — path to binary cache file.
  • lookup_path — optional URL normalization (e.g. /assets/).
  • mode, auto_reload, max_file_size.
  • exclude_patterns / exclude_count — exclusion globs.

Initialization

int cweb_fileserver_init(FileServerConfig *config)

  • Purpose: Starts file server with full configuration (directory, cache path, …).
  • Return: 0 on success.

int cweb_default_fileserver_config(FileServerMode mode, size_t max_file_size, bool auto_reload)

  • Purpose: Convenience: sets predefined project paths (e.g. ./assets, ./build/static_cache.bin) as in the reference implementation and internally calls cweb_fileserver_init.
  • Return: 0 on success.

void cweb_fileserver_destroy(void)

  • Purpose: Frees cache entries and configuration.

Exclusion lists

int cweb_fileserver_config_add_exclude(FileServerConfig *cfg, const char *pattern)

  • Purpose: Adds an fnmatch pattern to config (e.g. *.secret).

void cweb_fileserver_config_free_excludes(FileServerConfig *cfg)

  • Purpose: Frees the exclude string list.

int cweb_fileserver_add_exclude(const char *pattern)

  • Purpose: Global exclude on active instance.

Build and load cache

int cweb_fileserver_build_cache(const char *static_dir, const char *cache_file)

  • Purpose: Scans static_dir and writes binary cache to cache_file.

int cweb_fileserver_load_cache(const char *cache_file)

  • Purpose: Loads cache from disk into memory.

int cweb_fileserver_save_cache(const char *cache_file)

  • Purpose: Persists current cache.

void cweb_fileserver_clear_cache(void)

  • Purpose: Clears in-memory cache.

Lookup and reload

CachedFile *cweb_find_cached_file(const char *filename)

  • Purpose: Looks up entry by relative path name.

int cweb_load_file_to_cache(const char *filepath, const char *relative_path)

  • Purpose: Reads a specific file into cache.

HTTP integration

void cweb_fileserver_handle_request(Request *req, Response *res)

  • Purpose: Main entry: if request should be treated as static file, fills res with body and headers.

bool cweb_fileserver_is_static_file(const char *path)

  • Purpose: Heuristic whether path looks like a static asset request.

int cweb_serve_from_filesystem(const char *filepath, Response *res)

  • Purpose: Load a file from disk directly into res.

int cweb_serve_from_memory(const char *path, Response *res)

  • Purpose: Serve from cache entry.

MIME and validation

const char *cweb_get_mime_type(const char *filename)

  • Purpose: MIME type from filename/extension (static string pool).

bool cweb_is_file_modified(const char *filepath, time_t cached_time)

  • Purpose: For auto_reload: is file newer than cache timestamp?

Binary helpers (cache format)

The following read/write primitive types little-endian in cache files:

Function Purpose
int write_bytes(FILE *f, const void *buf, size_t len) write raw bytes
int read_bytes(FILE *f, void *buf, size_t len) read raw bytes
int write_u32_le(FILE *f, uint32_t v) uint32 LE
int write_u64_le(FILE *f, uint64_t v) uint64 LE
int read_u32_le(FILE *f, uint32_t *out) read uint32 LE
int read_u64_le(FILE *f, uint64_t *out) read uint64 LE

Return: 0 on success, otherwise error code.

Legacy inline aliases (backward compatibility)

The header defines static inline functions without the cweb_ prefix (fileserver_init, serve_from_memory, …) that forward identically to cweb_*. For new code paths use cweb_*; aliases remain for older projects.

See also