Skip to content

HTTP Streaming

When To Use

Use this archetype when devices are controlled over HTTP or REST and emit activity through a long-lived notification stream, webhook-like feed, multipart stream, or repeated poll/long-poll endpoint.

Core Shape

  • shared HTTP client owned by transport or equivalent shared service
  • per-device protocol object for serialized operations
  • long-lived event stream manager
  • event translation layer from vendor payloads to PQ events
  • optional status polling for device health and missing state

Typical Files

  • Communication/Transport.cs
  • Communication/Protocol.cs
  • Communication/<StreamManager>.cs
  • Events/<Routing>.cs
  • Commands/*.cs
  • StatusPolling.cs
  • AdapterRegistrations.cs

Minimal Flow

HTTP stream -> stream manager -> transport callback -> event routing -> Thing method -> PQ event/status

command -> protocol queue -> HTTP request -> result

Minimal Pseudocode

public partial class Protocol
{
    public Task<XDocument> GetStatus() => Enqueue(async _ =>
    {
        var xml = await Transport.Http.GetStringAsync("/status");
        return XDocument.Parse(xml);
    });
}

Common Pitfalls

  • making concurrent HTTP calls when the device expects serialized access
  • treating stream disconnects as non-fatal when they are the real health signal
  • mixing event parsing logic into command handlers instead of a routing layer
  • omitting polling when the stream does not cover all state

Good First Deliverable

Connect to the device, parse one streamed event type, and poll one health endpoint.