Add POSIX special file support (#259)

This commit adds support for POSIX special files throughout the
filesystem stack. The FileSystem trait now includes a mknod() method
that accepts mode (containing file type and permissions) and rdev
(device major/minor numbers for character and block devices). A new rdev
field in the Stats struct stores device numbers, and new file type
constants (S_IFIFO, S_IFCHR, S_IFBLK, S_IFSOCK) are exported for use by
implementations.

The FUSE layer implements mknod() by delegating to the FileSystem trait
and properly returning entry attributes after creation. The fillattr()
function now maps all file types (FIFO, character device, block device,
socket) to their corresponding FUSE FileType variants instead of
treating everything as regular files.

For AgentFS (SQLite-based storage), the fs_inode table gains an rdev
column to persist device numbers. The mknod implementation creates
inodes with the appropriate mode bits and device numbers, following the
same pattern as file and directory creation.

HostFS passes through to the libc mknod() call for native filesystem
support. OverlayFS implements copy-on-write semantics for special files,
checking both layers and handling whiteouts before creating in the delta
layer.

Also add some syscall tests verify mknod() and mkfifo() behavior
including FIFO creation, permission handling, error cases (EEXIST,
ENOENT), and device node creation when CAP_MKNOD is available.

Author: penberg

SPEC.md

@@ -1,6 +1,6 @@
 # Agent Filesystem Specification
 
-**Version:** 0.3
+**Version:** 0.4
 
 ## Introduction
 
@@ -170,7 +170,8 @@ CREATE TABLE fs_inode (
   size INTEGER NOT NULL DEFAULT 0,
   atime INTEGER NOT NULL,
   mtime INTEGER NOT NULL,
-  ctime INTEGER NOT NULL
+  ctime INTEGER NOT NULL,
+  rdev INTEGER NOT NULL DEFAULT 0
 )
 ```
 
@@ -185,6 +186,7 @@ CREATE TABLE fs_inode (
 - `atime` - Last access time (Unix timestamp, seconds)
 - `mtime` - Last modification time (Unix timestamp, seconds)
 - `ctime` - Creation/change time (Unix timestamp, seconds)
+- `rdev` - Device number for character and block devices (major/minor encoded)
 
 **Mode Encoding:**
 
@@ -196,6 +198,10 @@ File type (upper bits):
   0o100000 - Regular file (S_IFREG)
   0o040000 - Directory (S_IFDIR)
   0o120000 - Symbolic link (S_IFLNK)
+  0o010000 - FIFO/named pipe (S_IFIFO)
+  0o020000 - Character device (S_IFCHR)
+  0o060000 - Block device (S_IFBLK)
+  0o140000 - Socket (S_IFSOCK)
 
 Permissions (lower 12 bits):
   0o000777 - Permission bits (rwxrwxrwx)
@@ -417,7 +423,7 @@ To read `length` bytes starting at byte offset `offset`:
 1. Resolve path to inode
 2. Query inode (includes link count):
    ```sql
-   SELECT ino, mode, nlink, uid, gid, size, atime, mtime, ctime
+   SELECT ino, mode, nlink, uid, gid, size, atime, mtime, ctime, rdev
    FROM fs_inode WHERE ino = ?
    ```
 
@@ -685,6 +691,13 @@ Such extensions SHOULD use separate tables to maintain referential integrity.
 
 ## Revision History
 
+### Version 0.4
+
+- Added POSIX special file support (FIFOs, character devices, block devices, sockets)
+- Added `rdev` column to `fs_inode` table for device major/minor numbers
+- Added `S_IFIFO`, `S_IFCHR`, `S_IFBLK`, `S_IFSOCK` file type constants to Mode Encoding
+- Updated stat query to include `rdev` field
+
 ### Version 0.3
 
 - Added `fs_origin` table to Overlay Filesystem for tracking copy-up origin inodes

cli/src/fuse.rs

@@ -8,6 +8,7 @@ use crate::fuser::{
     Request,
 };
 use agentfs_sdk::error::Error as SdkError;
+use agentfs_sdk::filesystem::{S_IFBLK, S_IFCHR, S_IFDIR, S_IFIFO, S_IFLNK, S_IFMT, S_IFSOCK};
 use agentfs_sdk::{BoxedFile, FileSystem, Stats};
 use parking_lot::Mutex;
 use std::{
@@ -548,6 +549,67 @@ impl Filesystem for AgentFSFuse {
         reply.ok();
     }
 
+    /// Creates a special file node (FIFO, device, socket, or regular file).
+    ///
+    /// Creates a file node at `name` under `parent` with the specified mode
+    /// and device number, then stats it to return proper attributes.
+    fn mknod(
+        &mut self,
+        req: &Request,
+        parent: u64,
+        name: &OsStr,
+        mode: u32,
+        _umask: u32,
+        rdev: u32,
+        reply: ReplyEntry,
+    ) {
+        tracing::debug!(
+            "FUSE::mknod: parent={}, name={:?}, mode={:o}, rdev={}",
+            parent,
+            name,
+            mode,
+            rdev
+        );
+        let Some(path) = self.lookup_path(parent, name) else {
+            reply.error(libc::ENOENT);
+            return;
+        };
+
+        let uid = req.uid();
+        let gid = req.gid();
+        let fs = self.fs.clone();
+        let (result, path) = self.runtime.block_on(async move {
+            let result = fs.mknod(&path, mode, rdev as u64, uid, gid).await;
+            (result, path)
+        });
+
+        if let Err(e) = result {
+            reply.error(error_to_errno(&e));
+            return;
+        }
+
+        // Get the new node's stats
+        let fs = self.fs.clone();
+        let (stat_result, path) = self.runtime.block_on(async move {
+            let result = fs.stat(&path).await;
+            (result, path)
+        });
+
+        match stat_result {
+            Ok(Some(stats)) => {
+                let attr = fillattr(&stats);
+                self.add_path(attr.ino, path);
+                reply.entry(&TTL, &attr, 0);
+            }
+            Ok(None) => {
+                reply.error(libc::ENOENT);
+            }
+            Err(e) => {
+                reply.error(error_to_errno(&e));
+            }
+        }
+    }
+
     /// Creates a new directory.
     ///
     /// Creates a directory at `name` under `parent`, then stats it to return
@@ -1271,15 +1333,18 @@ impl AgentFSFuse {
 /// The uid and gid parameters override the stored values to ensure proper
 /// file ownership reporting (avoids "dubious ownership" errors from git).
 fn fillattr(stats: &Stats) -> FileAttr {
-    let kind = if stats.is_directory() {
-        FileType::Directory
-    } else if stats.is_symlink() {
-        FileType::Symlink
-    } else {
-        FileType::RegularFile
+    let file_type = stats.mode & S_IFMT;
+    let kind = match file_type {
+        S_IFDIR => FileType::Directory,
+        S_IFLNK => FileType::Symlink,
+        S_IFIFO => FileType::NamedPipe,
+        S_IFCHR => FileType::CharDevice,
+        S_IFBLK => FileType::BlockDevice,
+        S_IFSOCK => FileType::Socket,
+        _ => FileType::RegularFile,
     };
 
-    let size = if stats.is_directory() {
+    let size = if file_type == S_IFDIR {
         4096_u64 // Standard directory size
     } else {
         stats.size as u64
@@ -1298,7 +1363,7 @@ fn fillattr(stats: &Stats) -> FileAttr {
         nlink: stats.nlink,
         uid: stats.uid,
         gid: stats.gid,
-        rdev: 0,
+        rdev: stats.rdev as u32,
         flags: 0,
         blksize: 512,
     }

cli/tests/syscall/Makefile

@@ -19,7 +19,9 @@ SRCS = main.c \
        test-link.c \
        test-unlink.c \
        test-copyup-inode-stability.c \
-       test-rename.c
+       test-rename.c \
+       test-mknod.c \
+       test-mkfifo.c
 
 # Object files
 OBJS = $(SRCS:.c=.o)

cli/tests/syscall/main.c

@@ -35,6 +35,8 @@ int main(int argc, char *argv[]) {
         {"unlink", test_unlink},
         {"copyup_inode_stability", test_copyup_inode_stability},
         {"rename", test_rename},
+        {"mknod", test_mknod},
+        {"mkfifo", test_mkfifo},
     };
 
     int num_tests = sizeof(tests) / sizeof(tests[0]);

cli/tests/syscall/test-common.h

@@ -53,5 +53,7 @@ int test_unlink(const char *base_path);
 int test_copyup_inode_stability(const char *base_path);
 int test_rename(const char *base_path);
 int test_chown(const char *base_path);
+int test_mknod(const char *base_path);
+int test_mkfifo(const char *base_path);
 
 #endif /* TEST_COMMON_H */

cli/tests/syscall/test-mkfifo.c

@@ -0,0 +1,145 @@
+#define _GNU_SOURCE
+#include "test-common.h"
+#include <sys/stat.h>
+#include <fcntl.h>
+#include <unistd.h>
+
+int test_mkfifo(const char *base_path) {
+    char path[512];
+    struct stat st;
+    int result;
+    mode_t old_umask;
+
+    /* Save and clear umask for predictable permission tests */
+    old_umask = umask(0);
+
+    /* Test 1: Create a FIFO (named pipe) using mkfifo */
+    snprintf(path, sizeof(path), "%s/test_fifo_mkfifo", base_path);
+    unlink(path);  /* Clean up any previous test file */
+
+    result = mkfifo(path, 0644);
+    TEST_ASSERT_ERRNO(result == 0, "mkfifo creation should succeed");
+
+    result = stat(path, &st);
+    TEST_ASSERT_ERRNO(result == 0, "stat on FIFO should succeed");
+    TEST_ASSERT(S_ISFIFO(st.st_mode), "created node should be a FIFO");
+    TEST_ASSERT((st.st_mode & 0777) == 0644, "FIFO should have correct permissions (0644)");
+
+    unlink(path);
+
+    /* Test 2: mkfifo with existing path should fail with EEXIST */
+    snprintf(path, sizeof(path), "%s/test.txt", base_path);
+
+    result = mkfifo(path, 0644);
+    TEST_ASSERT(result < 0, "mkfifo on existing file should fail");
+    TEST_ASSERT(errno == EEXIST, "errno should be EEXIST for existing path");
+
+    /* Test 3: mkfifo in non-existent directory should fail with ENOENT */
+    snprintf(path, sizeof(path), "%s/nonexistent_dir/test_mkfifo", base_path);
+
+    result = mkfifo(path, 0644);
+    TEST_ASSERT(result < 0, "mkfifo in non-existent directory should fail");
+    TEST_ASSERT(errno == ENOENT, "errno should be ENOENT for non-existent directory");
+
+    /* Test 4: Create a FIFO with different permissions (0755) */
+    snprintf(path, sizeof(path), "%s/test_fifo_perms_755", base_path);
+    unlink(path);
+
+    result = mkfifo(path, 0755);
+    TEST_ASSERT_ERRNO(result == 0, "mkfifo with 0755 should succeed");
+
+    result = stat(path, &st);
+    TEST_ASSERT_ERRNO(result == 0, "stat on FIFO should succeed");
+    TEST_ASSERT((st.st_mode & 0777) == 0755, "FIFO should have 0755 permissions");
+
+    unlink(path);
+
+    /* Test 5: Create a FIFO with restrictive permissions (0600) */
+    snprintf(path, sizeof(path), "%s/test_fifo_perms_600", base_path);
+    unlink(path);
+
+    result = mkfifo(path, 0600);
+    TEST_ASSERT_ERRNO(result == 0, "mkfifo with 0600 should succeed");
+
+    result = stat(path, &st);
+    TEST_ASSERT_ERRNO(result == 0, "stat on FIFO should succeed");
+    TEST_ASSERT((st.st_mode & 0777) == 0600, "FIFO should have 0600 permissions");
+
+    unlink(path);
+
+    /* Test 6: Create FIFO in subdirectory */
+    char subdir_path[512];
+    snprintf(subdir_path, sizeof(subdir_path), "%s/mkfifo_subdir", base_path);
+    mkdir(subdir_path, 0755);
+
+    snprintf(path, sizeof(path), "%s/mkfifo_subdir/test_fifo", base_path);
+    unlink(path);
+
+    result = mkfifo(path, 0644);
+    TEST_ASSERT_ERRNO(result == 0, "mkfifo in subdirectory should succeed");
+
+    result = stat(path, &st);
+    TEST_ASSERT_ERRNO(result == 0, "stat on FIFO in subdirectory should succeed");
+    TEST_ASSERT(S_ISFIFO(st.st_mode), "created node in subdir should be a FIFO");
+
+    unlink(path);
+    rmdir(subdir_path);
+
+    /* Test 7: Create FIFO and verify it has size 0 */
+    snprintf(path, sizeof(path), "%s/test_fifo_size", base_path);
+    unlink(path);
+
+    result = mkfifo(path, 0644);
+    TEST_ASSERT_ERRNO(result == 0, "mkfifo should succeed");
+
+    result = stat(path, &st);
+    TEST_ASSERT_ERRNO(result == 0, "stat on FIFO should succeed");
+    TEST_ASSERT(st.st_size == 0, "FIFO should have size 0");
+
+    unlink(path);
+
+    /* Test 8: Create FIFO and verify link count is 1 */
+    snprintf(path, sizeof(path), "%s/test_fifo_nlink", base_path);
+    unlink(path);
+
+    result = mkfifo(path, 0644);
+    TEST_ASSERT_ERRNO(result == 0, "mkfifo should succeed");
+
+    result = stat(path, &st);
+    TEST_ASSERT_ERRNO(result == 0, "stat on FIFO should succeed");
+    TEST_ASSERT(st.st_nlink == 1, "FIFO should have nlink == 1");
+
+    unlink(path);
+
+    /* Test 9: Create FIFO with world-writable permissions (0666) */
+    snprintf(path, sizeof(path), "%s/test_fifo_666", base_path);
+    unlink(path);
+
+    result = mkfifo(path, 0666);
+    TEST_ASSERT_ERRNO(result == 0, "mkfifo with 0666 should succeed");
+
+    result = stat(path, &st);
+    TEST_ASSERT_ERRNO(result == 0, "stat on FIFO should succeed");
+    TEST_ASSERT((st.st_mode & 0777) == 0666, "FIFO should have 0666 permissions");
+
+    unlink(path);
+
+    /* Test 10: Verify FIFO shows up in directory listing */
+    snprintf(path, sizeof(path), "%s/test_fifo_readdir", base_path);
+    unlink(path);
+
+    result = mkfifo(path, 0644);
+    TEST_ASSERT_ERRNO(result == 0, "mkfifo should succeed");
+
+    /* Verify file exists via lstat too */
+    result = lstat(path, &st);
+    TEST_ASSERT_ERRNO(result == 0, "lstat on FIFO should succeed");
+    TEST_ASSERT(S_ISFIFO(st.st_mode), "lstat should report FIFO type");
+
+    unlink(path);
+
+    /* Restore original umask */
+    umask(old_umask);
+
+    return 0;
+}