File System Management

Purpose and Scope

This document describes the File System Management subsystem in the Light framework, which provides a unified abstraction layer for multiple storage backends through Flysystem's MountManager. The system enables dynamic configuration of filesystems (local, S3, Aliyun OSS, Hostlink), GraphQL-based file operations with security validation, and authenticated HTTP access to stored files.

For information about the Node types (File and Folder classes) that represent filesystem entities in GraphQL, see Node Types (File and Folder). For details on filesystem configuration management UI, see Filesystem Configuration Management.

---

Architecture Overview

The filesystem management system consists of four primary layers: configuration storage, adapter initialization, operation API, and HTTP access routes.

Sources: src/App.php134-146 src/App.php695-787 src/Controller/FileSystemController.php1-364

---

Filesystem Configuration Storage

Filesystem configurations are stored as a JSON array in the Config model under the key "fs". Each filesystem configuration is an object containing type-specific parameters and a UUID identifier.

Configuration Structure

Field	Type	Description
uuid	string	Unique identifier for the filesystem (auto-generated)
name	string	Mount name used in MountManager (e.g., "local", "s3")
type	string	Adapter type: "local", "s3", "aliyun-oss", "hostlink"
data	object	Type-specific configuration parameters

Default Configuration

If no filesystem configurations exist in the database, the system automatically provides a default local filesystem:

Configuration Retrieval Flow

Sources: src/App.php695-715 src/App.php134-146

---

Storage Adapter Initialization

The App::getFS(int $index) method creates filesystem adapters based on configuration type. The system supports four adapter types, each with specific initialization logic.

Local Filesystem Adapter

Configuration fields:

• data.location: Absolute path to storage directory
• data.public_url: Optional public URL prefix for file access

Sources: src/App.php723-742

Amazon S3 Adapter

Required configuration fields in data:

• region: AWS region (e.g., "us-east-1")
• endpoint: S3 endpoint URL
• accessKey: AWS access key ID
• secretKey: AWS secret access key
• bucket: S3 bucket name
• prefix: Optional path prefix within bucket
• visibility: Default visibility setting

The adapter creates an Aws\S3\S3Client with path-style endpoint configuration and wraps it in an AwsS3V3Adapter.

Sources: src/App.php749-778

Aliyun OSS Adapter

Configuration is passed directly to AlphaSnow\Flysystem\Aliyun\AliyunFactory::createFilesystem(). Required fields in data:

• accessId: Aliyun access key ID
• accessSecret: Aliyun access key secret
• bucket: OSS bucket name
• endpoint: OSS endpoint URL

Sources: src/App.php745-747

Hostlink Adapter

Configuration fields in data:

• token: Hostlink API authentication token
• endpoint: Hostlink API endpoint URL

Creates an HL\Storage\Adapter instance wrapped in a Flysystem Filesystem.

Sources: src/App.php780-784

Adapter Creation Error Handling

If the specified filesystem type is not recognized, the method throws an exception:

Sources: src/App.php786

---

MountManager Initialization

The MountManager is initialized in the App constructor, creating a unified interface for all configured filesystems.

The resulting MountManager allows operations using location strings in the format "protocol://path/to/file", where protocol matches a configured filesystem's name field.

Sources: src/App.php134-146

---

File Operations API

The FileSystemController provides GraphQL mutations for all file and folder operations. Each operation includes security validation and event dispatching.

Folder Operations

Mutation	Permission	Description
lightFSCreateFolder	fs.folder:create	Creates a new directory
lightFSDeleteFolder	fs.folder:delete	Deletes a directory
lightFSRenameFolder	fs.folder:rename	Renames a directory

Example Usage:

Sources: src/Controller/FileSystemController.php36-91

File Operations

Mutation	Permission	Description
lightFSWriteFile	fs.file:write	Writes content to a file
lightFSDeleteFile	fs.file:delete	Deletes a file
lightFSRenameFile	fs.file:rename	Renames a file
lightFSMove	fs.node:move	Moves a file or folder

Sources: src/Controller/FileSystemController.php93-186

Upload Operations

The system provides two upload methods:

Base64 Upload

The mutation:

1. Strips Data URI header if present
2. Decodes base64 to binary
3. Validates extension and filename
4. Dispatches FileUploading event
5. Writes content to filesystem
6. Returns a File node object

Sources: src/Controller/FileSystemController.php189-229

Multipart Upload

When rename: true, the system automatically generates numbered filenames (e.g., "file (1).txt", "file (2).txt") to avoid conflicts.

Sources: src/Controller/FileSystemController.php231-262 src/Controller/FileSystemController.php264-275

---

Security Validation

All file operations enforce security constraints to prevent malicious uploads and unauthorized access.

Disallowed Extensions

The system blocks 45 dangerous file extensions defined in FileSystemController::DISALLOW_EXT:

Sources: src/Controller/FileSystemController.php34

Dot-Prefix Blocking

All operations reject files and folders starting with a dot (.) to prevent hidden file manipulation:

This prevents attacks targeting system files like .htaccess, .env, etc.

Sources: src/Controller/FileSystemController.php40-45 src/Controller/FileSystemController.php57-62 src/Controller/FileSystemController.php97-102

Validation Flow

Sources: src/Controller/FileSystemController.php36-229

---

Event Dispatching System

Every file operation dispatches an event before execution, enabling custom validation, logging, or transformation logic.

Event Classes

Event Class	Dispatched By	Properties
FolderCreating	createFolder()	location
FolderDeleting	deleteFolder()	location
FolderRenaming	renameFolder()	location, newName
FileWriting	writeFile()	location, content
FileDeleting	deleteFile()	location
FileRenaming	renameFile()	location, newName
NodeMoving	moveNode()	from, to
FileUploading	uploadBase64(), uploadFile()	location, filename

Event Handling Pattern

Event objects can be modified by listeners to alter the operation (e.g., changing destination, filtering content).

Sources: src/Controller/FileSystemController.php10-17 src/Controller/FileSystemController.php48 src/Controller/FileSystemController.php65 src/Controller/FileSystemController.php80

---

HTTP Access Routes

The App class registers two authenticated HTTP routes for direct file access outside the GraphQL API.

Protocol-Based Route

Route: GET /fs/{protocol}/{path}

Serves files using MountManager's protocol-based addressing:

GET /fs/local/uploads/document.pdf
GET /fs/s3/images/photo.jpg

Sources: src/App.php850-865

Index-Based Route

Route: GET /drive/{index}/{path}

Serves files using zero-based filesystem index from configuration:

GET /drive/0/uploads/document.pdf (first configured filesystem)
GET /drive/1/images/photo.jpg (second configured filesystem)

This route calls getDriveResponse(int $index, string $path) which:

1. Validates index against configured filesystems
2. Creates a Drive instance for the specified index
3. Checks file existence
4. Returns file with appropriate Content-Type header

Sources: src/App.php867-875 src/App.php540-564

---

Filesystem Configuration Management API

The FileSystemController provides mutations for runtime filesystem configuration management.

Add Filesystem

The mutation:

1. Retrieves or creates the fs Config record
2. Generates a UUID for the new filesystem
3. Appends the configuration to the JSON array
4. Saves to database

Sources: src/Controller/FileSystemController.php313-331

Update Filesystem

Finds the filesystem by UUID and replaces its configuration.

Sources: src/Controller/FileSystemController.php278-308

Delete Filesystem

Removes the filesystem with matching UUID from the configuration array.

Sources: src/Controller/FileSystemController.php346-363

Configuration Persistence

Note: Configuration changes require application restart to take effect, as the MountManager is initialized once during App::__construct().

Sources: src/Controller/FileSystemController.php278-363 src/App.php134-146