persistence

README

Persistence (pkg/core/tools/persistence)

This directory contains tools for managing Falcon's persistent state, including saved requests and environment variables.

Key Features

• Request Storage: Save and load complex HTTP requests as YAML files with {{VAR}} placeholders.
• Environment Management: Switch between different environments (dev, prod, staging) with specific variable sets.
• Variable Scope: Session-scoped variables (cleared on exit) or global-scoped variables (persistent in .falcon/variables.json).

Merged Tools (2)

To reduce confusion, multiple tools were merged into two unified tools with action parameters:

request (replaces: save_request, load_request, list_requests)

{"action": "save", "name": "create_user", "method": "POST", "url": "...", "headers": {}, "body": "..."}
{"action": "load", "name": "create_user"}
{"action": "list"}

Persists to .falcon/requests/<name>.yaml. Requests can include {{VAR}} placeholders for variable substitution.

environment (replaces: set_environment, list_environments)

{"action": "set", "name": "prod", "variables": {"API_KEY": "...", "BASE_URL": "..."}}
{"action": "list"}

Persists to .falcon/environments/<name>.yaml. Switch environments to change which variables are active.

Variable Scope

• Session scope: Cleared when the conversation ends. Use for temporary tokens, test IDs.

  • Set: variable({"action": "set", "name": "auth_token", "value": "...", "scope": "session"})
  • Get: variable({"action": "get", "name": "auth_token", "scope": "session"})

• Global scope: Persisted in .falcon/variables.json across sessions. Use for API keys, base URLs, framework names.

  • Set: variable({"action": "set", "name": "API_KEY", "value": "...", "scope": "global"})
  • Get: variable({"action": "get", "name": "API_KEY", "scope": "global"})

Example Prompts

Trigger these tools by asking:

• "Save this request as 'create_user' for later use."
• "Load and run the saved 'create_user' request."
• "List all my saved requests."
• "Set the environment to 'production'."
• "Set a global variable API_KEY to 12345."
• "Get the current value of auth_token."

Documentation

Overview

Package persistence provides request persistence and environment management tools for ZAP.

Index

• type EnvironmentParams
• type EnvironmentTool
  • func NewEnvironmentTool(manager *PersistenceManager) *EnvironmentTool
  • func (t *EnvironmentTool) Description() string
  • func (t *EnvironmentTool) Execute(args string) (string, error)
  • func (t *EnvironmentTool) Name() string
  • func (t *EnvironmentTool) Parameters() string
• type PersistenceManager
  • func NewPersistenceManager(baseDir string) *PersistenceManager
  • func (pm *PersistenceManager) GetBaseDir() string
  • func (pm *PersistenceManager) GetCurrentEnv() string
  • func (pm *PersistenceManager) GetEnvironment() map[string]string
  • func (pm *PersistenceManager) SetEnvironment(name string) error
• type RequestParams
• type RequestTool
  • func NewRequestTool(manager *PersistenceManager) *RequestTool
  • func (t *RequestTool) Description() string
  • func (t *RequestTool) Execute(args string) (string, error)
  • func (t *RequestTool) Name() string
  • func (t *RequestTool) Parameters() string
• type VariableParams
• type VariableTool
  • func NewVariableTool(store *shared.VariableStore) *VariableTool
  • func (t *VariableTool) Description() string
  • func (t *VariableTool) Execute(args string) (string, error)
  • func (t *VariableTool) Name() string
  • func (t *VariableTool) Parameters() string

Types

type EnvironmentParams

type EnvironmentParams struct {
	Action    string            `json:"action"` // "set", "list"
	Name      string            `json:"name,omitempty"`
	Variables map[string]string `json:"variables,omitempty"` // optional: define env vars
}

type EnvironmentTool

type EnvironmentTool struct {
	// contains filtered or unexported fields
}

EnvironmentTool is the unified environment management tool that replaces set_environment and list_environments.

func NewEnvironmentTool

func NewEnvironmentTool(manager *PersistenceManager) *EnvironmentTool

func (*EnvironmentTool) Description

func (t *EnvironmentTool) Description() string

func (*EnvironmentTool) Execute

func (t *EnvironmentTool) Execute(args string) (string, error)

func (*EnvironmentTool) Name

func (t *EnvironmentTool) Name() string

func (*EnvironmentTool) Parameters

func (t *EnvironmentTool) Parameters() string

type PersistenceManager

type PersistenceManager struct {
	// contains filtered or unexported fields
}

PersistenceManager maintains state for persistence tools (environment, etc.) Renamed from PersistenceTool to avoid confusion with the package name or specific tools.

func NewPersistenceManager

func NewPersistenceManager(baseDir string) *PersistenceManager

NewPersistenceManager creates a new persistence manager

func (*PersistenceManager) GetBaseDir

func (pm *PersistenceManager) GetBaseDir() string

GetBaseDir returns the base directory

func (*PersistenceManager) GetCurrentEnv

func (pm *PersistenceManager) GetCurrentEnv() string

GetCurrentEnv returns the name of the current environment

func (*PersistenceManager) GetEnvironment

func (pm *PersistenceManager) GetEnvironment() map[string]string

GetEnvironment returns the current environment variables

func (*PersistenceManager) SetEnvironment

func (pm *PersistenceManager) SetEnvironment(name string) error

SetEnvironment sets the current environment by name

type RequestParams

type RequestParams struct {
	Action  string            `json:"action"` // "save", "load", "list"
	Name    string            `json:"name,omitempty"`
	Method  string            `json:"method,omitempty"`
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
	Body    interface{}       `json:"body,omitempty"`
}

type RequestTool

type RequestTool struct {
	// contains filtered or unexported fields
}

RequestTool is the unified request management tool that replaces save_request, load_request, and list_requests.

func NewRequestTool

func NewRequestTool(manager *PersistenceManager) *RequestTool

func (*RequestTool) Description

func (t *RequestTool) Description() string

func (*RequestTool) Execute

func (t *RequestTool) Execute(args string) (string, error)

func (*RequestTool) Name

func (t *RequestTool) Name() string

func (*RequestTool) Parameters

func (t *RequestTool) Parameters() string

type VariableParams

type VariableParams struct {
	Action string `json:"action"` // "set", "get", "delete", "list"
	Name   string `json:"name,omitempty"`
	Value  string `json:"value,omitempty"`
	Scope  string `json:"scope,omitempty"` // "session" (default) or "global"
}

VariableParams defines variable operations

type VariableTool

type VariableTool struct {
	// contains filtered or unexported fields
}

VariableTool provides variable get/set/list operations

func NewVariableTool

func NewVariableTool(store *shared.VariableStore) *VariableTool

NewVariableTool creates a new variable tool

func (*VariableTool) Description

func (t *VariableTool) Description() string

Description returns the tool description

func (*VariableTool) Execute

func (t *VariableTool) Execute(args string) (string, error)

Execute performs variable operations

func (*VariableTool) Name

func (t *VariableTool) Name() string

Name returns the tool name

func (*VariableTool) Parameters

func (t *VariableTool) Parameters() string

Parameters returns the tool parameter description