0
# Properties Backend
1

2
Control Service-based properties storage and retrieval system for data jobs. The properties backend enables storing configuration, state, and other key-value data remotely through the Control Service Properties API, accessible through both CLI commands and the JobInput API in data job code.
3

4
## Types
5

6
```python { .api }
7
from typing import Dict
8
from vdk.api.plugin.plugin_input import IPropertiesServiceClient
9
from vdk.internal.builtin_plugins.run.job_context import JobContext
10
```
11

12
## Capabilities
13

14
### Properties Service Client
15

16
Implementation of IPropertiesServiceClient that connects to VDK Control Service Properties API.
17

18
```python { .api }
19
class ControlServicePropertiesServiceClient(IPropertiesServiceClient):
20
    def __init__(self, rest_api_url: str):
21
        """
22
        Initialize Properties client for Control Service.
23
        
24
        Parameters:
25
        - rest_api_url: str - Base URL for Control Service REST API
26
        """
27
        
28
    @ConstrolServiceApiErrorDecorator()
29
    def read_properties(self, job_name: str, team_name: str):
30
        """
31
        Read properties for a data job from Control Service.
32
        
33
        Parameters:
34
        - job_name: str - Name of the data job
35
        - team_name: str - Name of the team owning the job
36
        
37
        Returns:
38
        dict: Properties data retrieved from Control Service
39
        """
40
        
41
    @ConstrolServiceApiErrorDecorator()
42
    def write_properties(self, job_name: str, team_name: str, properties: Dict) -> Dict:
43
        """
44
        Write properties for a data job to Control Service.
45
        
46
        Parameters:
47
        - job_name: str - Name of the data job
48
        - team_name: str - Name of the team owning the job
49
        - properties: Dict - Properties data to store
50
        
51
        Returns:
52
        Dict: The properties that were written
53
        """
54
```
55

56
### Properties Plugin Initialization
57

58
Hook implementation that registers the Control Service properties backend with vdk-core.
59

60
```python { .api }
61
@hookimpl
62
def initialize_job(context: JobContext) -> None:
63
    """
64
    Initialize Control Service Properties client implementation.
65
    
66
    Parameters:
67
    - context: JobContext - Job execution context
68
    
69
    Sets up properties factory methods for:
70
    - "default": Default properties backend
71
    - "control-service": Explicit Control Service backend
72
    """
73
```
74

75
## Usage Patterns
76

77
### CLI Usage
78

79
Access properties through vdk CLI commands:
80

81
```bash
82
# Set a property
83
vdk properties --set 'database-url' 'postgresql://localhost:5432/mydb'
84

85
# Set multiple properties
86
vdk properties --set 'api-key' 'abc123' --set 'timeout' '30'
87

88
# Get all properties
89
vdk properties --get-all
90

91
# Get specific property
92
vdk properties --get 'database-url'
93
```
94

95
### JobInput API Usage
96

97
Access properties in data job code through the JobInput interface:
98

99
```python
100
from vdk.api.job_input import IJobInput
101

102
def run(job_input: IJobInput):
103
    # Get a specific property
104
    api_url = job_input.get_property('api-url')
105
    
106
    # Get all properties
107
    all_props = job_input.get_all_properties()
108
    
109
    # Set properties
110
    job_input.set_property('last-run', '2023-01-15')
111
    
112
    # Set multiple properties
113
    new_props = {
114
        'status': 'completed',
115
        'record-count': '1000'
116
    }
117
    job_input.set_all_properties(new_props)
118
```
119

120
### Programmatic Usage
121

122
Direct usage of the properties client:
123

124
```python
125
from vdk.plugin.control_cli_plugin.control_service_properties_client import (
126
    ControlServicePropertiesServiceClient
127
)
128

129
# Initialize client
130
client = ControlServicePropertiesServiceClient("https://api.example.com")
131

132
# Read properties
133
properties = client.read_properties("my-job", "my-team")
134
print(f"Database URL: {properties.get('database-url')}")
135

136
# Write properties
137
new_properties = {
138
    "api-endpoint": "https://api.newservice.com",
139
    "timeout-seconds": "60"
140
}
141
client.write_properties("my-job", "my-team", new_properties)
142
```
143

144
## Integration Details
145

146
### Backend Registration
147

148
The properties plugin automatically registers with vdk-core during job initialization:
149

150
1. Checks if `CONTROL_SERVICE_REST_API_URL` is configured
151
2. If configured, registers `ControlServicePropertiesServiceClient` as both "default" and "control-service" backends
152
3. If not configured, logs warning and skips registration
153

154
### Factory Method Setup
155

156
```python
157
# Registered factory methods
158
context.properties.set_properties_factory_method(
159
    "default", 
160
    lambda: ControlServicePropertiesServiceClient(url)
161
)
162
context.properties.set_properties_factory_method(
163
    "control-service", 
164
    lambda: ControlServicePropertiesServiceClient(url)
165
)
166
```
167

168
### Error Handling
169

170
All API calls are decorated with `@ConstrolServiceApiErrorDecorator()` which provides:
171

172
- HTTP error handling with user-friendly messages
173
- Authentication error detection and guidance
174
- Retry logic for transient failures
175
- Proper error categorization (user vs. platform errors)
176

177
## Configuration Requirements
178

179
The properties backend requires these configuration values:
180

181
```python
182
# Required
183
CONTROL_SERVICE_REST_API_URL = "https://api.example.com"
184

185
# Authentication (if required)
186
API_TOKEN = "your-api-token"
187
API_TOKEN_AUTHORIZATION_URL = "https://auth.example.com/oauth/token"
188

189
# Optional HTTP settings
190
CONTROL_HTTP_VERIFY_SSL = True
191
CONTROL_HTTP_TOTAL_RETRIES = 3
192
CONTROL_HTTP_READ_TIMEOUT_SECONDS = 30
193
```
194

195
## Data Persistence
196

197
Properties are stored remotely in the Control Service with:
198

199
- **Job-scoped storage**: Properties are isolated per job and team
200
- **Persistent storage**: Data survives job executions and deployments  
201
- **API-based access**: Available through REST API and client libraries
202
- **Deployment integration**: Uses deployment ID "TODO" (placeholder for future enhancement)