diff --git a/docs/samy.functions.md b/docs/samy.functions.md index 0d5d354..5dab9e9 100644 --- a/docs/samy.functions.md +++ b/docs/samy.functions.md @@ -16,6 +16,9 @@ The goal of this file is to provide “daily driver” functions SAMY needs acro - Bootstrap - `Initialize-NuGetProvider` +- Task + validation helpers + - `Test-ComputerName` + - `Get-TaskHandlerName` - Registry helpers - `Set-RegistryValueInHkuRoot` - `Set-RegistryValueForCurrentAndAllUsers` @@ -64,6 +67,69 @@ Uses `Write-LogHybrid` with `-LogToEvent` to record bootstrap state and failures --- +## Task + validation helpers + +### Test-ComputerName +**Purpose** +Validates a proposed computer name before applying it (typically from UI input). + +**Rules enforced** +- Must not be null/empty/whitespace. +- Must be **15 characters or fewer** (NetBIOS computer name limit). +- Must match: `^[A-Za-z0-9-]+$` (letters, numbers, hyphen only). + +**Returns** +- `$true` if name is valid +- `$false` if name fails any rule + +**Where it’s used** +- Typically in handlers such as rename/computer identity workflows, to prevent invalid names from being applied. + +**Maintenance notes** +- If you want stricter rules (common): + - disallow leading or trailing hyphen + - disallow all-numeric names +- Keep any rule changes consistent with your environment (AD join rules, naming standards, etc.). + +--- + +### Get-TaskHandlerName +**Purpose** +Resolves the PowerShell function name that should execute for a given task object. + +This supports two patterns: +1. **Explicit handler name** stored on the task object (preferred when set) +2. **Convention-based handler name** derived from task `Name` + +**Resolution order** +1. Checks the task object for one of these properties (first match wins): + - `HandlerFn` + - `Handler` + - `Fn` +2. If none are present/usable, falls back to: + - `"Invoke-$Task.Name"` + +**Normalization** +When a handler value is found: +- Converts to string +- Trims whitespace +- Removes a leading `/` (in case the value is stored like a URL path) + +**Returns** +- A string function name (e.g. `Invoke-RenameComputer`) when resolved +- `$null` if no usable handler or name exists + +**Where it’s used** +- The HTTP router / request dispatcher uses this to map a requested task route to the correct handler function. + +**Why it exists** +- Allows tasks to follow a simple convention (`Invoke-`) while still supporting overrides for: + - legacy handler names + - special routing cases + - tasks that map to a shared/common handler + +--- + ## Registry Helpers ### Set-RegistryValueInHkuRoot