Ramble Core

chaos.lib.ramble

Module for managing ramble journals and pages.

Yeah, it's like a personal wiki or knowledge base, weird for a DevOps tool right? LMAO Amazing for keeping track of random knowledge, scripts, concepts, and ideas related to chaos engineering and system administration. Also, great for documenting secrets management strategies, configurations, and best practices.

gatherCreateRamble(payload)

Checks if the ramble already exists and asks for confirmation to edit.

Parameters:

Name	Type	Description	Default
payload	RambleCreatePayload	The context and target payload for creating the ramble.	required

Returns:

Type	Description
DataGatherRequest | None	DataGatherRequest | None: A request for user confirmation if the page already exists, otherwise None.

gatherDelRamble(payload)

Returns a DataGatherRequest for confirming the deletion of a ramble or journal.

Parameters:

Name	Type	Description	Default
payload	RambleDeletePayload	Represents context parameters necessary for deletion process.	required

Returns:

Type	Description
DataGatherRequest | None	DataGatherRequest | None: Object representation defining prompt requirement or None.

gatherEditRamble(payload)

If a journal is passed, returns a DataGatherRequest for page selection.

Parameters:

Name	Type	Description	Default
payload	RambleEditPayload	Context for editing a ramble.	required

Returns:

Type	Description
DataGatherRequest | None	DataGatherRequest | None: Request prompting for the page to edit, or None if valid file format supplied.

gatherReadRamble(payload)

Analyzes the read targets and returns a DataGatherRequest if any journals need page selection.

Parameters:

Name	Type	Description	Default
payload	RambleReadPayload	Payload specifying the reading target context.	required

Returns:

Type	Description
DataGatherRequest | None	DataGatherRequest | None: The user prompt to select a page, if applicable.

handleCreateRamble(payload)

Creates a new ramble journal or page, and returns the file path to open.

Parameters:

Name	Type	Description	Default
payload	RambleCreatePayload	The creation instructions including the target and confirmation status.	required

Returns:

Type	Description
ResultPayload[CreateRambleData]	ResultPayload[dict[str, Any]]: A payload containing the created file path or editing instructions on success.

handleDelRamble(payload)

Deletes a ramble journal or page.

Parameters:

Name	Type	Description	Default
payload	RambleDeletePayload	The confirmed target payload state.	required

Returns:

Type	Description
ResultPayload[None]	ResultPayload[None]: The status payload regarding operation's termination status.

handleEditRamble(payload)

Prepares editing of an existing ramble journal or page, returning info for the interface to handle it.

Parameters:

Name	Type	Description	Default
payload	RambleEditPayload	Details on what to edit and encryption state context.	required

Returns:

Type	Description
ResultPayload[EditRambleData]	ResultPayload[dict[str, Any]]: The result holding the requested file's path and its encryptability state.

handleEncryptRamble(payload)

Encrypts specified keys in a ramble page using sops.

Parameters:

Name	Type	Description	Default
payload	RambleEncryptPayload	The payload outlining the ramble to encrypt and which keys specifically.	required

Returns:

Type	Description
ResultPayload[None]	ResultPayload[None]: A payload summarizing encryption state messages or failure.

Notes

If -k not passed, encrypts everything except base keys. The tags key is never encrypted, helping to optimize searching.

handleFindRamble(payload)

Searches for rambles containing a specific term, optionally filtered by tag.

Parameters:

Name	Type	Description	Default
payload	RambleFindPayload	Definition of constraints to find target rambles.	required

Returns:

Type	Description
ResultPayload[list[str]]	ResultPayload[list[str]]: The list of matches, or an appropriate error response.

Notes

If nothing passed, lists all rambles.

handleMoveRamble(payload)

Moves or renames a ramble journal or page.

Parameters:

Name	Type	Description	Default
payload	RambleMovePayload	Context describing the origin point, and intended target point.	required

Returns:

Type	Description
ResultPayload[None]	ResultPayload[None]: Status payload of the operation.

handleReadRamble(payload)

Reads the content of specified rambles and returns them.

Parameters:

Name	Type	Description	Default
payload	RambleReadPayload	Contains targets and state required to retrieve rambles.	required

Returns:

Type	Description
ResultPayload[dict[str, Any]]	ResultPayload[dict[str, Any]]: A payload wrapping the read content for matching rambles.

handleUpdateEncryptRamble(payload)

Updates encryption keys for all encrypted rambles in the ramble directory.

Parameters:

Name	Type	Description	Default
payload	RambleUpdateEncryptPayload	Details regarding environment needed to update everything.	required

Returns:

Type	Description
ResultPayload[None]	ResultPayload[None]: Response mapping successes and errors of the operation.

is_safe_path(target_path, team)

Validates that the target path is within the ramble directory to prevent path traversal.

Parameters:

Name	Type	Description	Default
target_path	Path	The path that is being accessed.	required
team	str | None	The current team context.	required

Returns:

Name	Type	Description
bool	bool	True if the path is secure and valid.

Raises:

Type	Description
PermissionError	If path traversal is detected.
FileNotFoundError	If the underlying ramble directory doesn't exist.
ValueError	On generic path issues.
RuntimeError	For other unexpected failures.