Skip to content

infrastructure.enrichers.device_enricher

src.infrastructure.enrichers.device_enricher

Device enricher implementation using user-agents library.

Parses user agent strings to extract device, browser, and OS information. Implements DeviceEnricher protocol with fail-open behavior.

Reference
  • docs/architecture/session-management-architecture.md

Classes

UserAgentDeviceEnricher

Device enricher using the user-agents library.

Parses user agent strings using the well-maintained user-agents library which provides accurate browser, OS, and device detection.

Implements DeviceEnricher protocol (structural typing).

Behavior
  • Fail-open: Returns empty result on parse errors
  • Non-blocking: Pure string parsing (<1ms)
  • Best-effort: Unknown agents return partial data
Source code in src/infrastructure/enrichers/device_enricher.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
class UserAgentDeviceEnricher:
    """Device enricher using the user-agents library.

    Parses user agent strings using the well-maintained user-agents library
    which provides accurate browser, OS, and device detection.

    Implements DeviceEnricher protocol (structural typing).

    Behavior:
        - Fail-open: Returns empty result on parse errors
        - Non-blocking: Pure string parsing (<1ms)
        - Best-effort: Unknown agents return partial data
    """

    def __init__(self, logger: LoggerProtocol) -> None:
        """Initialize device enricher.

        Args:
            logger: Logger for error/debug messages.
        """
        self._logger = logger

    async def enrich(self, user_agent: str) -> DeviceEnrichmentResult:
        """Parse user agent string to extract device information.

        Args:
            user_agent: Raw user agent string from HTTP header.

        Returns:
            DeviceEnrichmentResult with parsed device info.
            Returns empty result (all None) on parse failure.
        """
        if not user_agent:
            return DeviceEnrichmentResult()

        try:
            ua: UserAgent = parse_user_agent(user_agent)

            # Extract browser info
            browser = ua.browser.family if ua.browser.family else None
            browser_version = (
                ua.browser.version_string if ua.browser.version_string else None
            )

            # Extract OS info
            os_name = ua.os.family if ua.os.family else None
            os_version = ua.os.version_string if ua.os.version_string else None

            # Determine device type
            device_type = self._determine_device_type(ua)

            # Check if bot
            is_bot = ua.is_bot

            # Build human-readable device info
            device_info = self._build_device_info(browser, os_name)

            return DeviceEnrichmentResult(
                device_info=device_info,
                browser=browser,
                browser_version=browser_version,
                os=os_name,
                os_version=os_version,
                device_type=device_type,
                is_bot=is_bot,
            )

        except Exception as e:
            self._logger.warning(
                "Failed to parse user agent",
                user_agent=user_agent[:100],
                error=str(e),
            )
            return DeviceEnrichmentResult()

    def _determine_device_type(self, ua: UserAgent) -> str:
        """Determine device type from parsed user agent.

        Args:
            ua: Parsed UserAgent object.

        Returns:
            Device type: "mobile", "tablet", "pc", or "other".
        """
        if ua.is_mobile:
            return "mobile"
        if ua.is_tablet:
            return "tablet"
        if ua.is_pc:
            return "desktop"
        return "other"

    def _build_device_info(
        self,
        browser: str | None,
        os_name: str | None,
    ) -> str | None:
        """Build human-readable device info string.

        Args:
            browser: Browser name.
            os_name: OS name.

        Returns:
            Human-readable string like "Chrome on Mac OS X", or None.
        """
        if browser and os_name:
            return f"{browser} on {os_name}"
        if browser:
            return browser
        if os_name:
            return f"Unknown browser on {os_name}"
        return None
Functions
__init__ 
__init__(logger: LoggerProtocol) -> None

Parameters:

Name Type Description Default
logger LoggerProtocol

Logger for error/debug messages.

 required
Source code in src/infrastructure/enrichers/device_enricher.py 
31
32
33
34
35
36
37
def __init__(self, logger: LoggerProtocol) -> None:
    """Initialize device enricher.

    Args:
        logger: Logger for error/debug messages.
    """
    self._logger = logger
enrich async 
enrich(user_agent: str) -> DeviceEnrichmentResult

Parse user agent string to extract device information.

Parameters:

Name Type Description Default
user_agent str

Raw user agent string from HTTP header.

 required

Returns:

Type Description
DeviceEnrichmentResult

DeviceEnrichmentResult with parsed device info.
DeviceEnrichmentResult

Returns empty result (all None) on parse failure.
Source code in src/infrastructure/enrichers/device_enricher.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
async def enrich(self, user_agent: str) -> DeviceEnrichmentResult:
    """Parse user agent string to extract device information.

    Args:
        user_agent: Raw user agent string from HTTP header.

    Returns:
        DeviceEnrichmentResult with parsed device info.
        Returns empty result (all None) on parse failure.
    """
    if not user_agent:
        return DeviceEnrichmentResult()

    try:
        ua: UserAgent = parse_user_agent(user_agent)

        # Extract browser info
        browser = ua.browser.family if ua.browser.family else None
        browser_version = (
            ua.browser.version_string if ua.browser.version_string else None
        )

        # Extract OS info
        os_name = ua.os.family if ua.os.family else None
        os_version = ua.os.version_string if ua.os.version_string else None

        # Determine device type
        device_type = self._determine_device_type(ua)

        # Check if bot
        is_bot = ua.is_bot

        # Build human-readable device info
        device_info = self._build_device_info(browser, os_name)

        return DeviceEnrichmentResult(
            device_info=device_info,
            browser=browser,
            browser_version=browser_version,
            os=os_name,
            os_version=os_version,
            device_type=device_type,
            is_bot=is_bot,
        )

    except Exception as e:
        self._logger.warning(
            "Failed to parse user agent",
            user_agent=user_agent[:100],
            error=str(e),
        )
        return DeviceEnrichmentResult()