Skip to content

Wrap awscrt types (QoS/Connection/AwsCrtError) out of public signatures #101

Description

@eman

Summary

Deferred follow-up from #95 (comprehensive repo evaluation, batch 6: architecture cleanup).

Several public/semi-public signatures in the MQTT layer still expose awscrt SDK types directly, e.g.:

  • awscrt.mqtt.QoS as a parameter/return type (mqtt/connection.py, mqtt/subscriptions.py, mqtt/client.py)
  • awscrt.mqtt.Connection as an internal connection handle type
  • awscrt.exceptions.AwsCrtError surfacing directly from library calls instead of being translated into the library's own exception hierarchy (MqttError and subclasses)

This leaks a third-party dependency's types into the library's own API surface, coupling callers (including the Home Assistant integration) to awscrt's versioning and making it harder to swap the underlying MQTT transport in the future.

Suggested approach

  • Introduce a library-owned QoS-equivalent enum (or reuse an existing nwp500 enum if one covers this) and translate to/from awscrt.mqtt.QoS at the connection-layer boundary.
  • Ensure AwsCrtError is always caught and re-raised/wrapped as an nwp500 exception (e.g. MqttError) at public API boundaries, per the project's exception-handling conventions (specific exception types, no leaking SDK exceptions).
  • Audit all public method signatures in nwp500/mqtt/ and nwp500/__init__.py-exported names for remaining awscrt type references.

Acceptance criteria

  • No awscrt types appear in the signatures of public/exported classes or methods.
  • Existing behavior unchanged; awscrt remains an internal implementation detail.
  • ruff/mypy clean, tests updated accordingly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions