geutebruck/geutebruck-api/docs/GEVISCOPE_IMPLEMENTATION_STATUS.md

# GeViScope Server Implementation Status

## Summary

A complete REST API structure for both G-Core and GeViScope servers has been designed and partially implemented. The new endpoint structure provides clean separation between server types.

---

## ✅ Completed

### 1. **Pydantic Schemas** (`src/api/schemas/servers.py`)
- `GCoreServerCreate/Update/Response` - Complete validation
- `GeViScopeServerCreate/Update/Response` - Complete with dial-up fields
- `AllServersResponse` - Combined listing
- `ServerOperationResponse` - Generic operation result

### 2. **REST API Endpoints** (`src/api/routers/configuration.py`)

**Parent Endpoint:**
- `GET /api/v1/configuration/servers` - List all servers (both types)

**G-Core Servers:**
- `GET /api/v1/configuration/servers/gcore` - List G-Core servers ✅
- `GET /api/v1/configuration/servers/gcore/{id}` - Get one ✅
- `POST /api/v1/configuration/servers/gcore` - Create ✅
- `PUT /api/v1/configuration/servers/gcore/{id}` - Update ✅
- `DELETE /api/v1/configuration/servers/gcore/{id}` - Delete ✅

**GeViScope Servers:**
- `GET /api/v1/configuration/servers/geviscope` - List GeViScope servers ✅
- `GET /api/v1/configuration/servers/geviscope/{id}` - Get one ✅
- `POST /api/v1/configuration/servers/geviscope` - Create ✅
- `PUT /api/v1/configuration/servers/geviscope/{id}` - Update ✅
- `DELETE /api/v1/configuration/servers/geviscope/{id}` - Delete ✅

### 3. **Service Layer** (`src/api/services/configuration_service.py`)
- `create_geviscope_server()` ✅
- `update_geviscope_server()` ✅
- `delete_geviscope_server()` ✅

---

## ⚠️ Remaining Work

### 4. **SDK Bridge Client** (`src/api/clients/sdk_bridge_client.py`)

Need to add three methods:

```python
async def create_geviscope_server(self, server_data: dict) -> dict:
    """Create GeViScope server via gRPC"""
    # Call gRPC CreateGeViScopeServerRequest
    pass

async def update_geviscope_server(self, server_id: str, server_data: dict) -> dict:
    """Update GeViScope server via gRPC"""
    # Call gRPC UpdateGeViScopeServerRequest
    pass

async def delete_geviscope_server(self, server_id: str) -> dict:
    """Delete GeViScope server via gRPC"""
    # Call gRPC DeleteGeViScopeServerRequest
    pass
```

### 5. **Proto Definitions** (`src/sdk-bridge/Protos/configuration.proto`)

Need to add GeViScope-specific messages:

```protobuf
message CreateGeViScopeServerRequest {
    string alias = 1;
    string host = 2;
    string user = 3;
    string password = 4;
    bool enabled = 5;
    bool deactivate_echo = 6;
    bool deactivate_live_check = 7;
    // GeViScope-specific fields
    bool dialup_broadcast_aware = 8;
    bool dialup_connection = 9;
    bool dialup_cpa_connection = 10;
    int32 dialup_cpa_connection_interval = 11;
    int32 dialup_cpa_time_settings = 12;
    bool dialup_keep_alive = 13;
    bool dialup_keep_alive_retrigger = 14;
    int32 dialup_keep_alive_time = 15;
}

message UpdateGeViScopeServerRequest {
    string server_id = 1;
    // ... same fields as Create
}

message DeleteGeViScopeServerRequest {
    string server_id = 1;
}

message GeViScopeServerOperationResponse {
    bool success = 1;
    string message = 2;
    string server_id = 3;
    string error_message = 4;
    int32 bytes_written = 5;
}

// Add to ConfigurationService
service ConfigurationService {
    // ... existing methods ...

    rpc CreateGeViScopeServer(CreateGeViScopeServerRequest) returns (GeViScopeServerOperationResponse);
    rpc UpdateGeViScopeServer(UpdateGeViScopeServerRequest) returns (GeViScopeServerOperationResponse);
    rpc DeleteGeViScopeServer(DeleteGeViScopeServerRequest) returns (GeViScopeServerOperationResponse);
}
```

### 6. **C# SDK Bridge Implementation** (`Services/ConfigurationServiceImplementation.cs`)

Need to implement three gRPC methods:

```csharp
public override async Task<GeViScopeServerOperationResponse> CreateGeViScopeServer(
    CreateGeViScopeServerRequest request,
    ServerCallContext context)
{
    // 1. Download configuration via SetupClient
    // 2. Parse with FolderTreeParser
    // 3. Navigate to GeViGscServer folder (NOT GeViGCoreServer!)
    // 4. Find max numeric ID and increment
    // 5. Create new server folder with ID
    // 6. Add all fields (common + dial-up fields)
    // 7. Write tree with FolderTreeWriter
    // 8. Upload via SetupClient
    // 9. Return response
}

public override async Task<GeViScopeServerOperationResponse> UpdateGeViScopeServer(
    UpdateGeViScopeServerRequest request,
    ServerCallContext context)
{
    // Similar to Create but find existing server by ID first
}

public override async Task<GeViScopeServerOperationResponse> DeleteGeViScopeServer(
    DeleteGeViScopeServerRequest request,
    ServerCallContext context)
{
    // Similar to G-Core delete but work with GeViGscServer folder
}
```

**Key Differences from G-Core Implementation:**

1. **Folder Name**: `GeViGscServer` instead of `GeViGCoreServer`
2. **Additional Fields**: Must handle all dial-up fields
3. **Global Settings**: GeViGscServer folder contains both servers AND global settings (DialUpCPADay0-6, FailoverActive, etc.). Must skip non-folder items when listing servers.

### 7. **Proto Code Generation**

After updating `.proto` files:

```bash
# Regenerate C# code
cd src/sdk-bridge/GeViScopeBridge
dotnet build -c Release

# Regenerate Python code
cd src/api
python -m grpc_tools.protoc -I../../src/sdk-bridge/Protos \
    --python_out=./protos \
    --grpc_python_out=./protos \
    ../../src/sdk-bridge/Protos/configuration.proto

# Fix imports (change absolute to relative)
# In configuration_pb2_grpc.py:
# from . import configuration_pb2 as configuration__pb2
```

---

## Testing Checklist

Once implementation is complete:

### GeViScope Server CRUD:
- [ ] Create GeViScope server with all dial-up fields
- [ ] List GeViScope servers (verify global settings are filtered out)
- [ ] Get single GeViScope server by ID
- [ ] Update GeViScope server (modify dial-up settings)
- [ ] Delete GeViScope server
- [ ] Verify changes persist after GeViServer restart

### Combined Listing:
- [ ] GET `/api/v1/configuration/servers` returns both types correctly
- [ ] Verify counts are accurate (total, total_gcore, total_geviscope)

### Edge Cases:
- [ ] Create server with duplicate ID (should fail)
- [ ] Update non-existent server (should 404)
- [ ] Delete non-existent server (should 404)
- [ ] Verify bool fields write as type code 1 (not 4)
- [ ] Test with enabled=true and enabled=false

---

## Current State

**What Works Now:**
- GET endpoints for listing GeViScope servers (read-only via ReadConfigurationTree)
- Full REST API structure is in place
- All Pydantic schemas with validation
- Proper error handling and logging

**What Doesn't Work Yet:**
- CREATE, UPDATE, DELETE for GeViScope servers
- These will fail with "Method not implemented" errors until C# backend is implemented

**Estimated Work Remaining:**
- Proto definitions: ~30 minutes
- C# implementation: ~2-3 hours (can reuse G-Core patterns)
- Testing: ~1 hour
- **Total: ~4 hours**

---

## Quick Start (After Full Implementation)

```bash
# List all servers (both types)
curl http://localhost:8000/api/v1/configuration/servers

# List only GeViScope servers
curl http://localhost:8000/api/v1/configuration/servers/geviscope

# Create GeViScope server
curl -X POST http://localhost:8000/api/v1/configuration/servers/geviscope \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Local GeViScope",
    "host": "localhost",
    "user": "sysadmin",
    "password": "password",
    "enabled": true,
    "deactivate_echo": false,
    "deactivate_live_check": false,
    "dialup_broadcast_aware": false,
    "dialup_connection": false,
    "dialup_cpa_connection": false,
    "dialup_cpa_connection_interval": 3600,
    "dialup_cpa_time_settings": 16777215,
    "dialup_keep_alive": false,
    "dialup_keep_alive_retrigger": false,
    "dialup_keep_alive_time": 10
  }'
```

---

**Last Updated**: 2025-12-17