/ 
Concierge-Users-v0.7.3
/ Concierge::Users::YAML

NAME

Concierge::Users::YAML - YAML file-per-user storage backend for Concierge::Users

VERSION

v0.7.3

SYNOPSIS

use Concierge::Users;

# Setup with the YAML backend
Concierge::Users->setup({
    storage_dir             => '/var/lib/myapp/users',
    backend                 => 'yaml',
    include_standard_fields => 'all',
});

# Runtime -- the backend is loaded automatically
my $users = Concierge::Users->new('/var/lib/myapp/users/users-config.json');

DESCRIPTION

Concierge::Users::YAML implements the Concierge::Users storage interface using one YAML file per user via the YAML::Tiny module. Each user record is stored as <storage_dir>/<user_id>.yaml.

This backend is well-suited for applications that primarily access individual users and for small-to-moderate user counts where human-readable per-user files are convenient.

Archiving: When setup() is called and .yaml files already exist in the storage directory, all YAML files are moved into a timestamped subdirectory users_YYYYMMDD_HHMMSS/ before the new setup proceeds.

Applications interact with this module indirectly through the Concierge::Users API; direct instantiation is not required.

METHODS

configure

my $result = Concierge::Users::YAML->configure(\%setup_config);

Class method called by Concierge::Users->setup(). Archives any existing YAML files in the storage directory and returns the backend configuration. Returns a hashref with success, message, and config.

new

my $backend = Concierge::Users::YAML->new(\%runtime_config);

Constructor called by Concierge::Users->new(). Stores the runtime configuration for file operations.

add

my $result = $backend->add($user_id, \%initial_record);

Creates a new <user_id>.yaml file. Sets created_date and last_mod_date to the current UTC timestamp.

fetch

my $result = $backend->fetch($user_id);

Loads and returns the user data from <user_id>.yaml. Returns { success => 1, data => \%record } or { success => 0, message => "..." }.

update

my $result = $backend->update($user_id, \%updates);

Loads the existing file, merges updates, and writes back. Read-only fields (user_id, created_date, last_mod_date) are stripped automatically; last_mod_date is refreshed.

delete

my $result = $backend->delete($user_id);

Removes the <user_id>.yaml file.

list

my $result = $backend->list(\%filters, \%options);

Reads every .yaml file in the storage directory and applies the parsed filter structure (see "FILTER DSL" in Concierge::Users::Meta). With no filters, returns all users. Result: { data => \@records, total_count => $n }.

CAVEATS

  • list() reads all .yaml files in the storage directory, including the users-config.yaml reference file generated by setup(). The config file will appear as an entry without a valid user_id and is included in the returned data.

  • Performance is linear with the number of users since every file must be opened and parsed for list operations.

DEPENDENCIES

YAML::Tiny

SEE ALSO

Concierge::Users -- main API

Concierge::Users::Meta -- field definitions and validators

Concierge::Users::Database, Concierge::Users::File -- alternative backends

AUTHOR

Bruce Van Allen <bva@cruzio.com>

LICENSE

This module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.