feat: add human-readable duration format support for reservation timeouts

Add support for human-readable duration formats (e.g., '2h30m', '5h', '30m')
for reservation timeouts in addition to existing integer seconds format.

Changes:
- Add duration parser in testflinger-common with support for s/m/h/d units
- Update CLI reserve command with --timeout/-t argument accepting duration formats
- Add DurationField to server schema for automatic parsing and validation
- Update documentation with duration format examples
- Maintain full backward compatibility with existing integer timeout values

Examples:
- testflinger-cli reserve -q queue -i image.img -k lp:user -t 2h30m
- Job YAML: timeout: '5h' (parsed to 18000 seconds)
- API: {"timeout": "30m"} (validated and converted to 1800)

Fixes: CERTTF-586

Author: gajeshbhat

cli/pyproject.toml

@@ -12,6 +12,7 @@ dependencies = [
   "pyjwt>=2.10.1",
   "pyyaml>=6.0.2",
   "requests>=2.32.3",
+  "testflinger-common",
   "xdg-base-dirs>=6.0.2",
 ]
 dynamic = ["version"]
@@ -70,3 +71,6 @@ convention = "pep257"
 
 [tool.uv]
 cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true } }]
+
+[tool.uv.sources]
+testflinger-common = { path = "../common" }

cli/testflinger_cli/__init__.py

@@ -37,6 +37,7 @@
 import argcomplete
 import requests
 import yaml
+from testflinger_common.duration import parse_duration, DurationParseError
 
 from testflinger_cli import (
     autocomplete,
@@ -286,6 +287,14 @@ def _add_reserve_args(self, subparsers):
                 "(ex: -k lp:userid -k gh:userid)"
             ),
         )
+        parser.add_argument(
+            "--timeout",
+            "-t",
+            help=(
+                "Reservation timeout. Can be specified in seconds (3600) "
+                "or using duration format (30m, 5h, 4d). Default is 1 hour."
+            ),
+        )
 
     def _add_status_args(self, subparsers):
         """Command line arguments for status."""
@@ -1022,6 +1031,15 @@ def reserve(self):
         for ssh_key in ssh_keys:
             if not ssh_key.startswith("lp:") and not ssh_key.startswith("gh:"):
                 logger.error("Invalid SSH key format: %s", ssh_key)
+
+        # Parse timeout if provided
+        timeout_seconds = None
+        if self.args.timeout:
+            try:
+                timeout_seconds = parse_duration(self.args.timeout)
+            except DurationParseError as e:
+                logger.error("Invalid timeout format: %s", e)
+                sys.exit(1)
         template = inspect.cleandoc(
             """job_queue: {queue}
                                     provision_data:
@@ -1031,6 +1049,8 @@ def reserve(self):
         )
         for ssh_key in ssh_keys:
             template += f"\n      - {ssh_key}"
+        if timeout_seconds is not None:
+            template += f"\n        timeout: {timeout_seconds}"
         job_data = template.format(queue=queue, image=image)
         print("\nThe following yaml will be submitted:")
         print(job_data)

cli/testflinger_cli/tests/test_duration_cli.py

@@ -0,0 +1,46 @@
+# Copyright (C) 2025 Canonical
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Tests for duration format support in CLI reserve command."""
+
+import sys
+import testflinger_cli
+
+
+def test_reserve_with_timeout(capsys, requests_mock):
+    """Test reserve command with duration timeout generates correct YAML."""
+    requests_mock.get("https://testflinger.canonical.com/v1/agents/queues", json={})
+    requests_mock.get("https://testflinger.canonical.com/v1/agents/images/fake", json={})
+
+    sys.argv = ["", "reserve", "-q", "fake", "-i", "http://fake_image.xz",
+                "-k", "lp:fakeuser", "-t", "2h30m", "-d"]
+
+    tfcli = testflinger_cli.TestflingerCli()
+    tfcli.reserve()
+    std = capsys.readouterr()
+    assert "timeout: 9000" in std.out  # 2h30m = 9000 seconds
+
+
+def test_reserve_without_timeout(capsys, requests_mock):
+    """Test reserve command without timeout omits timeout field."""
+    requests_mock.get("https://testflinger.canonical.com/v1/agents/queues", json={})
+    requests_mock.get("https://testflinger.canonical.com/v1/agents/images/fake", json={})
+
+    sys.argv = ["", "reserve", "-q", "fake", "-i", "http://fake_image.xz",
+                "-k", "lp:fakeuser", "-d"]
+
+    tfcli = testflinger_cli.TestflingerCli()
+    tfcli.reserve()
+    std = capsys.readouterr()
+    assert "timeout:" not in std.out

cli/uv.lock

@@ -0,0 +1,189 @@
+# Copyright (C) 2025 Canonical
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Duration parsing utilities for Testflinger.
+
+This module provides utilities to parse duration strings in human-readable
+formats (like '30m', '5h', '4d') into seconds, similar to the sleep command.
+"""
+
+import re
+from typing import Union
+
+
+class DurationParseError(ValueError):
+    """Raised when a duration string cannot be parsed."""
+    pass
+
+
+def parse_duration(duration: Union[str, int]) -> int:
+    """Parse a duration string or integer into seconds.
+    
+    Supports the following formats:
+    - Plain integers (interpreted as seconds): 3600
+    - Duration strings with suffixes:
+      - 's' or 'sec' for seconds: '30s', '30sec'
+      - 'm' or 'min' for minutes: '30m', '30min'  
+      - 'h' or 'hour' for hours: '5h', '5hour'
+      - 'd' or 'day' for days: '4d', '4day'
+    
+    Multiple units can be combined: '1h30m', '2d5h30m'
+    
+    Args:
+        duration: Duration as string or integer
+        
+    Returns:
+        Duration in seconds as integer
+        
+    Raises:
+        DurationParseError: If the duration string is invalid
+        
+    Examples:
+        >>> parse_duration(3600)
+        3600
+        >>> parse_duration('30m')
+        1800
+        >>> parse_duration('5h')
+        18000
+        >>> parse_duration('4d')
+        345600
+        >>> parse_duration('1h30m')
+        5400
+        >>> parse_duration('2d5h30m')
+        192600
+    """
+    if isinstance(duration, int):
+        if duration < 0:
+            raise DurationParseError("Duration cannot be negative")
+        return duration
+    
+    if not isinstance(duration, str):
+        raise DurationParseError(f"Duration must be string or int, got {type(duration)}")
+    
+    duration = duration.strip()
+    if not duration:
+        raise DurationParseError("Duration cannot be empty")
+    
+    # Try parsing as plain integer first
+    try:
+        value = int(duration)
+        if value < 0:
+            raise DurationParseError("Duration cannot be negative")
+        return value
+    except ValueError:
+        pass
+
+    # Check for negative numbers in duration strings
+    if duration.strip().startswith('-'):
+        raise DurationParseError("Duration cannot be negative")
+    
+    # Parse duration string with units
+    # Pattern matches: number followed by optional unit
+    # Units: s/sec, m/min, h/hour, d/day (case insensitive)
+    # Order matters - longer forms first to avoid partial matches
+    pattern = r'(\d+)\s*(secs?|mins?|hours?|days?|sec|min|hour|day|s|m|h|d)'
+    matches = re.findall(pattern, duration.lower())
+
+    if not matches:
+        raise DurationParseError(f"Invalid duration format: '{duration}'")
+
+    # Check if the entire string was consumed by matches
+    # Reconstruct what should have been matched and compare
+    reconstructed = ''
+    for num, unit in matches:
+        reconstructed += f"{num}{unit}"
+
+    # Remove all whitespace for comparison
+    normalized_input = re.sub(r'\s+', '', duration.lower())
+
+    if normalized_input != reconstructed:
+        raise DurationParseError(f"Invalid duration format: '{duration}'")
+    
+    total_seconds = 0
+    unit_multipliers = {
+        's': 1,
+        'sec': 1,
+        'secs': 1,
+        'm': 60,
+        'min': 60,
+        'mins': 60,
+        'h': 3600,
+        'hour': 3600,
+        'hours': 3600,
+        'd': 86400,
+        'day': 86400,
+        'days': 86400,
+    }
+    
+    for num_str, unit in matches:
+        num = int(num_str)
+        if num < 0:
+            raise DurationParseError("Duration components cannot be negative")
+        
+        multiplier = unit_multipliers[unit]
+        total_seconds += num * multiplier
+    
+    return total_seconds
+
+
+def format_duration(seconds: int) -> str:
+    """Format seconds into a human-readable duration string.
+    
+    Args:
+        seconds: Duration in seconds
+        
+    Returns:
+        Human-readable duration string
+        
+    Examples:
+        >>> format_duration(3600)
+        '1h'
+        >>> format_duration(1800)
+        '30m'
+        >>> format_duration(5400)
+        '1h30m'
+        >>> format_duration(345600)
+        '4d'
+    """
+    if seconds < 0:
+        raise ValueError("Duration cannot be negative")
+    
+    if seconds == 0:
+        return '0s'
+    
+    parts = []
+    
+    # Days
+    if seconds >= 86400:
+        days = seconds // 86400
+        parts.append(f"{days}d")
+        seconds %= 86400
+    
+    # Hours
+    if seconds >= 3600:
+        hours = seconds // 3600
+        parts.append(f"{hours}h")
+        seconds %= 3600
+    
+    # Minutes
+    if seconds >= 60:
+        minutes = seconds // 60
+        parts.append(f"{minutes}m")
+        seconds %= 60
+    
+    # Seconds
+    if seconds > 0:
+        parts.append(f"{seconds}s")
+    
+    return ''.join(parts)

common/src/testflinger_common/duration.py

@@ -0,0 +1,15 @@
+# Copyright (C) 2025 Canonical
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Tests for testflinger_common package."""