signalwire.utils¶
signalwire.utils
¶
Copyright (c) 2025 SignalWire
This file is part of the SignalWire SDK.
Licensed under the MIT License. See LICENSE file in the project root for full license information.
__all__ = ['SchemaUtils', 'get_execution_mode', 'is_serverless_mode', 'validate_url']
module-attribute
¶
SchemaUtils
¶
Utility class for loading and working with SWML schemas
log = logger.bind(component='schema_utils')
instance-attribute
¶
schema_path = schema_path
instance-attribute
¶
schema = self.load_schema()
instance-attribute
¶
verbs = self._extract_verb_definitions()
instance-attribute
¶
full_validation_available
property
¶
Check if full JSON Schema validation is available.
__init__(schema_path=None, schema_validation=True)
¶
Initialize the schema utilities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
schema_path
|
str | None
|
Path to the schema file |
None
|
schema_validation
|
bool
|
Enable schema validation. Can also be disabled via SWML_SKIP_SCHEMA_VALIDATION=1 environment variable. |
True
|
load_schema()
¶
Load the JSON schema from the specified path
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The schema as a dictionary |
get_verb_properties(verb_name)
¶
Get the properties for a specific verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb (e.g., "ai", "answer", etc.) |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The properties for the verb or an empty dict if not found |
get_verb_required_properties(verb_name)
¶
Get the required properties for a specific verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb (e.g., "ai", "answer", etc.) |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
List of required property names for the verb or an empty list if not found |
validate_verb(verb_name, verb_config)
¶
Validate a verb configuration against the schema.
Performs full JSON Schema validation including type checking and nested object validation using jsonschema-rs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb (e.g., "ai", "answer", etc.) |
required |
verb_config
|
dict[str, Any]
|
The configuration for the verb |
required |
Returns:
| Type | Description |
|---|---|
tuple[bool, list[str]]
|
(is_valid, error_messages) tuple |
validate_document(document)
¶
Validate a complete SWML document against the schema.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
document
|
dict[str, Any]
|
The complete SWML document to validate |
required |
Returns:
| Type | Description |
|---|---|
tuple[bool, list[str]]
|
(is_valid, error_messages) tuple |
get_all_verb_names()
¶
Get all verb names defined in the schema
Returns:
| Type | Description |
|---|---|
list[str]
|
List of verb names |
get_verb_parameters(verb_name)
¶
Get the parameter definitions for a specific verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb (e.g., "ai", "answer", etc.) |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary mapping parameter names to their definitions |
generate_method_signature(verb_name)
¶
Generate a Python method signature for a verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb |
required |
Returns:
| Type | Description |
|---|---|
str
|
A Python method signature string |
generate_method_body(verb_name)
¶
Generate the method body implementation for a verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb |
required |
Returns:
| Type | Description |
|---|---|
str
|
The method body as a string |
validate_url(url, allow_private=False)
¶
Validate that a URL is safe to fetch (not pointing to private/internal resources).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str
|
The URL to validate |
required |
allow_private
|
bool
|
If True, allow private IP ranges (default: False) |
False
|
Returns:
| Type | Description |
|---|---|
bool
|
True if the URL is safe to fetch, False otherwise |
get_execution_mode()
¶
Determine the execution mode based on environment variables
Returns:
| Name | Type | Description |
|---|---|---|
str |
'server', 'cgi', 'lambda', 'google_cloud_function', 'azure_function', or 'unknown' |
is_serverless_mode()
¶
Check if running in any serverless environment.
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if in serverless mode, False if in server mode |
pom_utils
¶
Copyright (c) 2025 SignalWire
This file is part of the SignalWire SDK.
Licensed under the MIT License. See LICENSE file in the project root for full license information.
schema_utils
¶
Copyright (c) 2025 SignalWire
This file is part of the SignalWire SDK.
Licensed under the MIT License. See LICENSE file in the project root for full license information.
Schema utilities for SWML validation and verb extraction.
Uses jsonschema-rs for full JSON Schema validation with type checking.
logger = get_logger('signalwire.utils.schema_utils')
module-attribute
¶
SchemaValidationError
¶
SchemaUtils
¶
Utility class for loading and working with SWML schemas
log = logger.bind(component='schema_utils')
instance-attribute
¶
schema_path = schema_path
instance-attribute
¶
schema = self.load_schema()
instance-attribute
¶
verbs = self._extract_verb_definitions()
instance-attribute
¶
full_validation_available
property
¶
Check if full JSON Schema validation is available.
__init__(schema_path=None, schema_validation=True)
¶
Initialize the schema utilities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
schema_path
|
str | None
|
Path to the schema file |
None
|
schema_validation
|
bool
|
Enable schema validation. Can also be disabled via SWML_SKIP_SCHEMA_VALIDATION=1 environment variable. |
True
|
load_schema()
¶
Load the JSON schema from the specified path
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The schema as a dictionary |
get_verb_properties(verb_name)
¶
Get the properties for a specific verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb (e.g., "ai", "answer", etc.) |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The properties for the verb or an empty dict if not found |
get_verb_required_properties(verb_name)
¶
Get the required properties for a specific verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb (e.g., "ai", "answer", etc.) |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
List of required property names for the verb or an empty list if not found |
validate_verb(verb_name, verb_config)
¶
Validate a verb configuration against the schema.
Performs full JSON Schema validation including type checking and nested object validation using jsonschema-rs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb (e.g., "ai", "answer", etc.) |
required |
verb_config
|
dict[str, Any]
|
The configuration for the verb |
required |
Returns:
| Type | Description |
|---|---|
tuple[bool, list[str]]
|
(is_valid, error_messages) tuple |
validate_document(document)
¶
Validate a complete SWML document against the schema.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
document
|
dict[str, Any]
|
The complete SWML document to validate |
required |
Returns:
| Type | Description |
|---|---|
tuple[bool, list[str]]
|
(is_valid, error_messages) tuple |
get_all_verb_names()
¶
Get all verb names defined in the schema
Returns:
| Type | Description |
|---|---|
list[str]
|
List of verb names |
get_verb_parameters(verb_name)
¶
Get the parameter definitions for a specific verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb (e.g., "ai", "answer", etc.) |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary mapping parameter names to their definitions |
generate_method_signature(verb_name)
¶
Generate a Python method signature for a verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb |
required |
Returns:
| Type | Description |
|---|---|
str
|
A Python method signature string |
generate_method_body(verb_name)
¶
Generate the method body implementation for a verb
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verb_name
|
str
|
The name of the verb |
required |
Returns:
| Type | Description |
|---|---|
str
|
The method body as a string |
token_generators
¶
Copyright (c) 2025 SignalWire
This file is part of the SignalWire SDK.
Licensed under the MIT License. See LICENSE file in the project root for full license information.
url_validator
¶
Copyright (c) 2025 SignalWire
This file is part of the SignalWire SDK.
Licensed under the MIT License. See LICENSE file in the project root for full license information.
URL validation utility to prevent SSRF attacks
logger = logging.getLogger('signalwire.url_validator')
module-attribute
¶
validate_url(url, allow_private=False)
¶
Validate that a URL is safe to fetch (not pointing to private/internal resources).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str
|
The URL to validate |
required |
allow_private
|
bool
|
If True, allow private IP ranges (default: False) |
False
|
Returns:
| Type | Description |
|---|---|
bool
|
True if the URL is safe to fetch, False otherwise |
validators
¶
Copyright (c) 2025 SignalWire
This file is part of the SignalWire SDK.
Licensed under the MIT License. See LICENSE file in the project root for full license information.