SDK-363: Switch remote SDK calls from /devicecmdnew/ to HTTP Relay channel

Replace the legacy /devicecmdnew/{tenant}/{device}/ binary channel with
the /devices/{device}/ HTTP Relay for all remote edge and drive API calls.
The relay forwards full HTTP requests (including cookies) to the device,
which fixes cookie-dependent endpoints like /stats/*.

- Add _relay_base() to derive portal DNS hostname from device DDNS name
- Add auto-SSO login on first relay API access (edge and drive)
- Append /admingui/api base path for relay requests
- Add edge.stats module for device performance metrics
- Fetch deviceDnsName in default device field list

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: asafn-ctera

cterasdk/core/devices.py

@@ -11,7 +11,7 @@ class Devices(BaseCommand):
 
     name_attr = 'name'
     type_attr = 'deviceType'
-    default = ['name', 'portal', 'deviceType', 'version', 'remoteAccessUrl']
+    default = ['name', 'portal', 'deviceType', 'version', 'remoteAccessUrl', 'deviceDnsName']
 
     def _create_device_resource_uri(self, device_name, tenant):
         session = self._core.session()

cterasdk/core/remote.py

@@ -1,11 +1,30 @@
+from urllib.parse import urlparse
 from .enum import DeviceType
 from ..objects.synchronous import edge, drive
-from ..common import parse_base_object_ref
+
+
+def _relay_base(Portal, device):
+    """
+    Build the base URL for the HTTP Relay channel.
+
+    The portal's RemoteDeviceServlet resolves the tenant from the Host header
+    using DNS suffix matching (e.g. portal.ctera.me).  Accessing the portal by
+    IP causes Host: <ip> which fails that check.  We derive the correct portal
+    hostname from the device's DDNS name (vGateway-7192.portal.ctera.me) and
+    substitute it into the base URL so every relay request carries the right
+    Host header while still connecting to the same portal endpoint.
+    """
+    device_dns = getattr(device, 'deviceDnsName', None)
+    if device_dns and device.name in device_dns:
+        portal_hostname = device_dns[len(device.name) + 1:]   # strip "vGateway-7192."
+        parsed = urlparse(Portal.ctera.baseurl)
+        port = f':{parsed.port}' if parsed.port not in (None, 80, 443) else ''
+        return f'{parsed.scheme}://{portal_hostname}{port}{parsed.path}/devices/{device.name}'
+    return f'{Portal.ctera.baseurl}/devices/{device.name}'
 
 
 def remote_command(Portal, device):
-    tenant = parse_base_object_ref(device.portal).name
-    base = f'{Portal.ctera.baseurl}/devicecmdnew/{tenant}/{device.name}'
+    base = _relay_base(Portal, device)
 
     ManagedDevice = None
     if device.deviceType in DeviceType.Gateways:

cterasdk/edge/__init__.py

@@ -30,6 +30,7 @@
     'shares',
     'shell',
     'smb',
+    'stats',
     'support',
     'sync',
     'syslog',

cterasdk/edge/stats.py

@@ -0,0 +1,35 @@
+import logging
+
+from .base_command import BaseCommand
+
+
+logger = logging.getLogger('cterasdk.edge')
+
+
+VALID_STAT_TYPES = ('cpu', 'memory', 'cache', 'volume', 'connections', 'local_io', 'disk_io', 'cloud_io')
+VALID_INTERVALS = ('hour', 'day', 'week', 'month', 'year', 'last')
+
+
+class Stats(BaseCommand):
+    """
+    Edge Filer statistics retrieved via the HTTP Relay channel.
+
+    Valid stat types: cpu, memory, cache, volume, connections, local_io, disk_io, cloud_io
+    Valid intervals: hour, day, week, month, year, last
+    """
+
+    def get(self, stat_type, interval='hour'):
+        """
+        Get device statistics
+
+        :param str stat_type: Statistic type.
+         Options: ``cpu``, ``memory``, ``cache``, ``volume``, ``connections``, ``local_io``, ``disk_io``, ``cloud_io``
+        :param str,optional interval: Time interval, defaults to ``hour``.
+         Options: ``hour``, ``day``, ``week``, ``month``, ``year``, ``last``
+        :returns: Statistics data
+        """
+        if stat_type not in VALID_STAT_TYPES:
+            raise ValueError(f'Invalid stat_type {stat_type!r}. Valid: {VALID_STAT_TYPES}')
+        if interval not in VALID_INTERVALS:
+            raise ValueError(f'Invalid interval {interval!r}. Valid: {VALID_INTERVALS}')
+        return self._edge.api.get(f'/stats/{stat_type}', params={'interval': interval})

cterasdk/objects/synchronous/drive.py

@@ -1,21 +1,42 @@
+import logging
+
 import cterasdk.settings
 from ...clients import clients
 from ..services import Management
 from ..endpoints import EndpointBuilder
+from ...common import parse_base_object_ref
 from ...lib.session.edge import Session
 from ...edge import backup, cli, logs, services, support, sync
 
 
+logger = logging.getLogger('cterasdk.drive')
+
+
 class Clients:
 
     def __init__(self, drive, Portal):
+        self._drive = drive
+        self._Portal = Portal
+        self._authenticated = False
         if Portal:
             drive._Portal = Portal
             drive.default.close()
             drive._ctera_session.start_remote_session(Portal.session())
-            self.api = Portal.default.clone(clients.API, EndpointBuilder.new(drive.base), authenticator=lambda *_: True)
+            self._api = Portal.default.clone(clients.API, EndpointBuilder.new(drive.base, '/admingui/api'), authenticator=lambda *_: True)
         else:
-            self.api = drive.default.clone(clients.API, EndpointBuilder.new(drive.base, '/admingui/api'))
+            self._api = drive.default.clone(clients.API, EndpointBuilder.new(drive.base, '/admingui/api'))
+
+    @property
+    def api(self):
+        if self._Portal and not self._authenticated:
+            tenant = parse_base_object_ref(self._drive.portal).name
+            device_name = self._drive.name
+            logger.debug('Auto-SSO login via relay channel. %s', {'tenant': tenant, 'device': device_name})
+            token = self._Portal.api.execute(f'/portals/{tenant}/devices/{device_name}', 'singleSignOn')
+            if token:
+                self._api.get('/ssologin', params={'ticket': token})
+            self._authenticated = True
+        return self._api
 
 
 class Drive(Management):

cterasdk/objects/synchronous/edge.py

@@ -1,34 +1,54 @@
+import logging
+
 import cterasdk.settings
 from ...clients import clients
 from ..services import Management
 from ..endpoints import EndpointBuilder
 from .. import authenticators
-from ...common import modules
+from ...common import modules, parse_base_object_ref
 from ...lib.session.edge import Session
 
 
 from ...edge import (
     afp, aio, antivirus, array, audit, backup, cache, cli, config, connection, ctera_migrate,
     dedup, directoryservice, drive, files, firmware, ftp, groups, licenses, login,
     logs, mail, network, nfs, ntp, power, remote, rsync, ransom_protect, services,
-    shares, shell, smb, snmp, ssh, ssl, support, sync, syslog, tasks, telnet,
+    shares, shell, smb, snmp, ssh, ssl, stats, support, sync, syslog, tasks, telnet,
     timezone, users, volumes,
 )
 
 
+logger = logging.getLogger('cterasdk.edge')
+
+
 class Clients:
 
     def __init__(self, edge, Portal):
+        self._edge = edge
+        self._Portal = Portal
+        self._authenticated = False
         if Portal:
             edge._Portal = Portal
             edge.default.close()
             edge._ctera_session.start_remote_session(Portal.session())
-            self.api = Portal.default.clone(clients.API, EndpointBuilder.new(edge.base), authenticator=lambda *_: True)
+            self._api = Portal.default.clone(clients.API, EndpointBuilder.new(edge.base, '/admingui/api'), authenticator=lambda *_: True)
         else:
             self.migrate = edge.default.clone(clients.Migrate, EndpointBuilder.new(edge.base, '/migration/rest/v1'))
-            self.api = edge.default.clone(clients.API, EndpointBuilder.new(edge.base, '/admingui/api'))
+            self._api = edge.default.clone(clients.API, EndpointBuilder.new(edge.base, '/admingui/api'))
             self.io = IO(edge)
 
+    @property
+    def api(self):
+        if self._Portal and not self._authenticated:
+            tenant = parse_base_object_ref(self._edge.portal).name
+            device_name = self._edge.name
+            logger.debug('Auto-SSO login via relay channel. %s', {'tenant': tenant, 'device': device_name})
+            token = self._Portal.api.execute(f'/portals/{tenant}/devices/{device_name}', 'singleSignOn')
+            if token:
+                self._api.get('/ssologin', params={'ticket': token})
+            self._authenticated = True
+        return self._api
+
 
 class IO:
 
@@ -106,6 +126,7 @@ def __init__(self, host=None, port=None, https=True, Portal=None, *, base=None):
         self.shell = shell.Shell(self)
         self.smb = smb.SMB(self)
         self.snmp = snmp.SNMP(self)
+        self.stats = stats.Stats(self)
         self.ssh = ssh.SSH(self)
         self.ssl = modules.initialize(ssl.SSLModule, self)
         self.support = support.Support(self)
@@ -164,5 +185,5 @@ def _omit_fields(self):
         return super()._omit_fields + ['afp', 'aio', 'array', 'audit', 'antivirus', 'backup', 'cache', 'cli', 'config', 'ctera_migrate',
                                        'dedup', 'directoryservice', 'drive', 'files', 'firmware', 'ftp', 'groups', 'licenses', 'logs',
                                        'mail', 'network', 'nfs', 'ntp', 'power', 'ransom_protect', 'rsync', 'services', 'shares', 'shell',
-                                       'smb', 'snmp', 'ssh', 'ssl', 'support', 'sync', 'syslog', 'tasks', 'telnet', 'timezone',
+                                       'smb', 'snmp', 'ssh', 'ssl', 'stats', 'support', 'sync', 'syslog', 'tasks', 'telnet', 'timezone',
                                        'users', 'volumes']

tests/ut/core/admin/test_remote.py

@@ -73,6 +73,38 @@ def _create_device_param(name, portal, device_type, remote_access_url):
         param.remoteAccessUrl = remote_access_url
         return param
 
+    def test_auto_sso_on_first_api_access(self):
+        """Verify that first access to edge.api triggers SSO login via relay channel."""
+        remote_session = self.patch_call("cterasdk.lib.session.edge.Session.start_remote_session")
+        remote_session.return_value = munch.Munch({'account': munch.Munch({'name': 'mickey', 'tenant': 'tenant'})})
+        get_multi_response = TestCoreRemote._create_device_param(self._device_name, self._device_portal,
+                                                                 'vGateway', self._device_remote_access_url)
+        self._init_global_admin(get_multi_response=get_multi_response, execute_response=self._sso_ticket)
+        self._activate_portal_session()
+        device = devices.Devices(self._global_admin).device(self._device_name)
+        device._ctera_clients._api = mock.MagicMock()
+        _ = device.api
+        self._global_admin.api.execute.assert_called_once_with(
+            f'/portals/{self._tenant_name}/devices/{self._device_name}', 'singleSignOn')
+        device._ctera_clients._api.get.assert_called_once_with('/ssologin', params={'ticket': self._sso_ticket})
+
+    def test_auto_sso_not_repeated_on_subsequent_api_access(self):
+        """Verify that subsequent api accesses do not re-trigger SSO."""
+        remote_session = self.patch_call("cterasdk.lib.session.edge.Session.start_remote_session")
+        remote_session.return_value = munch.Munch({'account': munch.Munch({'name': 'mickey', 'tenant': 'tenant'})})
+        get_multi_response = TestCoreRemote._create_device_param(self._device_name, self._device_portal,
+                                                                 'vGateway', self._device_remote_access_url)
+        self._init_global_admin(get_multi_response=get_multi_response, execute_response=self._sso_ticket)
+        self._activate_portal_session()
+        device = devices.Devices(self._global_admin).device(self._device_name)
+        device._ctera_clients._api = mock.MagicMock()
+        _ = device.api
+        _ = device.api
+        _ = device.api
+        self._global_admin.api.execute.assert_called_once_with(
+            f'/portals/{self._tenant_name}/devices/{self._device_name}', 'singleSignOn')
+        device._ctera_clients._api.get.assert_called_once_with('/ssologin', params={'ticket': self._sso_ticket})
+
     @staticmethod
     def _create_current_session_object():
         session = Object()

tests/ut/edge/test_stats.py

@@ -0,0 +1,37 @@
+from cterasdk.edge import stats
+from tests.ut.edge import base_edge
+
+
+class TestEdgeStats(base_edge.BaseEdgeTest):
+
+    def setUp(self):
+        super().setUp()
+        self._init_filer()
+
+    def test_get_cpu_default_interval(self):
+        stats.Stats(self._filer).get('cpu')
+        self._filer.api.get.assert_called_with('/stats/cpu', params={'interval': 'hour'})
+
+    def test_get_memory_with_interval(self):
+        stats.Stats(self._filer).get('memory', interval='day')
+        self._filer.api.get.assert_called_with('/stats/memory', params={'interval': 'day'})
+
+    def test_get_all_stat_types(self):
+        for stat_type in stats.VALID_STAT_TYPES:
+            self._filer.api.get.reset_mock()
+            stats.Stats(self._filer).get(stat_type, interval='hour')
+            self._filer.api.get.assert_called_with(f'/stats/{stat_type}', params={'interval': 'hour'})
+
+    def test_get_all_intervals(self):
+        for interval in stats.VALID_INTERVALS:
+            self._filer.api.get.reset_mock()
+            stats.Stats(self._filer).get('cpu', interval=interval)
+            self._filer.api.get.assert_called_with('/stats/cpu', params={'interval': interval})
+
+    def test_invalid_stat_type_raises_value_error(self):
+        with self.assertRaises(ValueError):
+            stats.Stats(self._filer).get('invalid_type')
+
+    def test_invalid_interval_raises_value_error(self):
+        with self.assertRaises(ValueError):
+            stats.Stats(self._filer).get('cpu', interval='invalid_interval')