VOOZH about

URL: https://deepwiki.com/mathsgod/light/7.5-filesystem-configuration-management

⇱ Filesystem Configuration Management | mathsgod/light | DeepWiki

Loading...
Loading...
Last indexed: 31 January 2026 (cf9511)
Menu

Filesystem Configuration Management

Purpose and Scope

This document details how filesystem configurations are stored, managed, and accessed within the Light framework. Filesystem configurations define the connection parameters for various storage backends (Local, AWS S3, Aliyun OSS, Hostlink) and enable the MountManager to establish connections to these storage systems.

For information about the filesystem architecture and Node abstraction, see Filesystem Architecture. For details on specific file operations (create, delete, upload), see File Operations API. For information on supported storage backends and their configuration parameters, see Storage Backends.

Storage Architecture

Filesystem configurations are stored in the Config model as a single JSON-encoded array under the key "fs". This centralized storage approach allows runtime configuration changes without code deployment and enables dynamic filesystem registration.



Sources: src/Controller/FileSystemController.php278-363 src/Model/Config.php1-28




Configuration Data Structure


Each filesystem configuration is stored as a JSON object within the array. The structure includes:





































FieldTypeDescriptionRequired
uuidStringUnique identifier generated via Ramsey\Uuid\Uuid::uuid4()Yes
typeStringBackend type: "local", "s3", "oss", "hostlink"Yes
nameStringHuman-readable filesystem nameYes
CredentialsMixedBackend-specific configuration (varies by type)Yes


Backend-Specific Configuration Fields


Local Filesystem:


    

  • root - Base directory path on server
    • 



AWS S3:


    

  • key - AWS access key ID
    • 

  • secret - AWS secret access key
    • 

  • bucket - S3 bucket name
    • 

  • region - AWS region (e.g., "us-east-1")
    • 

  • endpoint - Custom endpoint URL (optional)
    • 

  • public_url - Base URL for public file access
    • 



Aliyun OSS:


    

  • accessKeyId - Aliyun access key
    • 

  • accessKeySecret - Aliyun secret key
    • 

  • bucket - OSS bucket name
    • 

  • endpoint - OSS endpoint URL
    • 

  • public_url - Base URL for public file access
    • 



Hostlink Storage:


    

  • token - Authentication token
    • 

  • endpoint - API endpoint URL
    • 



Sources: src/Controller/FileSystemController.php283-331




Configuration Retrieval


The Config::Value() static method provides access to the filesystem configuration JSON:




The implementation at src/Model/Config.php15-27 shows the retrieval logic:




Consumer code typically decodes the JSON to access individual filesystem configurations:




Sources: src/Model/Config.php15-27 src/Controller/FileSystemController.php285-288




CRUD Operations


The FileSystemController provides GraphQL mutations for managing filesystem configurations. All operations manipulate the JSON array stored in the Config model.


Add Filesystem Configuration


The lightFSadd mutation creates a new filesystem configuration and assigns it a UUID.




Implementation details at src/Controller/FileSystemController.php313-331:


    

  1. Loads the Config record with name="fs", creating it with value="[]" if it doesn't exist
    2. 

  2. Decodes the JSON array
    3. 

  3. Generates a new UUID via Ramsey\Uuid\Uuid::uuid4()->toString()
    4. 

  4. Appends the new configuration object to the array
    5. 

  5. Re-encodes the array with JSON_UNESCAPED_UNICODE flag
    6. 

  6. Saves the Config record
    7. 



Required Permission: filesystem.add (enforced via @Right annotation at line 314)


Sources: src/Controller/FileSystemController.php313-331




Update Filesystem Configuration


The lightFSupdate mutation modifies an existing filesystem configuration identified by UUID.




Implementation at src/Controller/FileSystemController.php278-308:


    

  1. Loads the existing Config record with name="fs", returning false if not found
    2. 

  2. Decodes the JSON array
    3. 

  3. Iterates through the array to find a matching uuid field
    4. 

  4. Replaces the matched element with the new data
    5. 

  5. Re-encodes and saves, returning false if UUID was not found
    6. 



Required Permission: filesystem.update (enforced via @Right annotation at line 279)


Sources: src/Controller/FileSystemController.php278-308




Delete Filesystem Configuration


The lightFSdelete mutation removes a filesystem configuration by UUID.


Implementation at src/Controller/FileSystemController.php346-363:


    

  1. Loads the Config record with name="fs", returning false if not found
    2. 

  2. Decodes the JSON array
    3. 

  3. Filters the array to exclude the element with matching uuid
    4. 

  4. Re-encodes the filtered array and saves
    5. 



Required Permission: filesystem.delete (enforced via @Right annotation at line 347)


Sources: src/Controller/FileSystemController.php346-363




List Filesystem Configurations


The listFileSystem query returns all configured filesystems.


Note: This query is deprecated at src/Controller/FileSystemController.php336 The preferred method is accessing the filesystem list through the app query's listFileSystem field (see Root Query Type).


Implementation at src/Controller/FileSystemController.php333-344:


    

  1. Loads the Config record with name="fs", returning empty array if not found
    2. 

  2. Decodes and returns the JSON array
    3. 



Required Permission: filesystem.list (enforced via @Right annotation at line 334)


Sources: src/Controller/FileSystemController.php333-344




Permission Model


Filesystem configuration management uses a separate permission namespace from file operations:
































OperationPermissionGraphQL Mutation/Query
Add filesystemfilesystem.addlightFSadd
Update filesystemfilesystem.updatelightFSupdate
Delete filesystemfilesystem.deletelightFSdelete
List filesystemsfilesystem.listlistFileSystem


These permissions are distinct from file operation permissions:


    

  • File operations use permissions like fs.file:write, fs.folder:delete (see File Operations API)
    • 

  • Filesystem configuration operations use permissions like filesystem.add, filesystem.update
    • 



This separation allows administrators to grant users the ability to perform file operations on existing filesystems without allowing them to modify the filesystem configurations themselves.


Sources: src/Controller/FileSystemController.php279 src/Controller/FileSystemController.php314 src/Controller/FileSystemController.php334 src/Controller/FileSystemController.php347




Integration with Application Initialization


The Light\App class loads filesystem configurations during initialization to populate the MountManager:




The initialization process:


    

  1. Retrieves the "fs" configuration via Config::Value("fs")
    2. 

  2. Parses the JSON array of filesystem configurations
    3. 

  3. For each configuration, creates the appropriate Flysystem adapter based on the type field
    4. 

  4. Mounts each filesystem in the MountManager with a unique scheme (e.g., local://, s3://)
    5. 

  5. Creates Drive objects that wrap the mounted filesystems for GraphQL API exposure
    6. 



This means configuration changes require application restart or a manual reload mechanism to take effect in the MountManager.


Sources: Inferred from system architecture (see Diagram 6 in high-level diagrams)




UUID-Based Identification


All filesystem configurations use UUID v4 identifiers generated by the Ramsey UUID library. This approach provides:


    

  • Globally Unique Identifiers: No collision risk when configurations are exported/imported across environments
    • 

  • Immutable References: File location strings can reference filesystems by UUID scheme (e.g., {uuid}://path/to/file)
    • 

  • Safe Updates: The update operation uses UUID matching rather than array indices, preventing accidental overwrites
    • 



UUID generation occurs at src/Controller/FileSystemController.php325:




The update and delete operations use this UUID for lookup at src/Controller/FileSystemController.php293 and src/Controller/FileSystemController.php356 respectively.


Sources: src/Controller/FileSystemController.php325 src/Controller/FileSystemController.php293 src/Controller/FileSystemController.php356




Example GraphQL Operations


Adding a Filesystem Configuration




Response: true on success, with UUID auto-generated


Updating a Filesystem Configuration




Response: true if UUID found and updated, false if UUID not found


Deleting a Filesystem Configuration




Response: true if UUID found and deleted, false if UUID not found or config record doesn't exist


Sources: src/Controller/FileSystemController.php313-363




Error Handling


The filesystem configuration operations handle several error conditions:





































ConditionOperationBehavior
Config record doesn't existupdate, deleteReturns false
Config record doesn't existaddCreates new record with value="[]"
Config record doesn't existlistReturns empty array []
UUID not foundupdate, deleteReturns false (no exception)
Invalid JSONAllCauses json_decode() failure (uncaught)


Note that permission violations are handled by the GraphQL layer via @Right annotations and will throw authorization errors before the mutation methods execute.


Sources: src/Controller/FileSystemController.php285-287 src/Controller/FileSystemController.php320-322 src/Controller/FileSystemController.php340-342 src/Controller/FileSystemController.php350-352