Azure IoT HTTP Base Library

Common errors

• Error: The 'url' argument must be of type string. Received an instance of URL

  cause Attempting to pass a `URL` object directly to a method expecting a string URL within an older version or specific internal client implementation that hasn't fully adopted `URL` objects.
  fix Ensure that any URL arguments are converted to strings using `url.toString()` before passing them to internal client methods, for example: `url: myUrl.toString()`.

• TypeError: Cannot read properties of undefined (reading 'statusCode') when handling response.

  cause Occurs when a low-level network request fails catastrophically or encounters an unexpected error state, leading to a `response` object being `undefined` or incomplete within the error object.
  fix Implement robust error handling around network requests, checking for the existence of `error.response` and its properties before accessing them. For example, `if (error.response) { console.error(error.response.statusCode); }`.

• Error: This package has a 'main' entrypoint that is not compatible with ES Modules.

  cause While the package is designed for Node.js 14+ and ships TypeScript types, an outdated build configuration or incorrect usage (e.g., trying to `require()` in an ES Module context) might lead to module resolution issues.
  fix Ensure your Node.js project is configured for ES Modules (`"type": "module"` in `package.json`) and use `import` statements. If using CommonJS, ensure you are using a compatible Node.js version and correct `require()` syntax (though `require` is generally not recommended for modern Azure SDKs).

Warnings

• gotcha This package is an internal library and is NOT intended for direct public consumption. Developers should use higher-level Azure IoT SDKs (e.g., `azure-iot-device-http`, `azure-iothub`) which abstract and manage these HTTP components.
  Fix: Always prefer using the official Azure IoT Device or Service SDKs for your application logic. Only interact with this package if you are extending the SDKs themselves or require very low-level HTTP transport control, which is rare.
• breaking The minimum required Node.js version was updated from Node.js 12 to Node.js 14. Applications running on older Node.js versions will encounter runtime errors.
  Fix: Upgrade your Node.js runtime to version 14.0.0 or higher. Node.js 12 reached end-of-life in April 2022.
• breaking The internal dependency for core HTTP authentication shifted from `@azure/core-http` to `@azure/core-auth` starting from version 1.12.2. While this is primarily an internal change, it signifies a restructuring in how authentication and HTTP client pipelines are managed within the SDK.
  Fix: No direct action required for most users, as this is an internal SDK change. If you were directly referencing internal types or structures related to `@azure/core-http` from this package (which is discouraged), be aware of potential interface changes or dependency mismatches.
• gotcha Recurring dependency vulnerabilities are addressed across releases. While patched regularly, it highlights the importance of keeping Azure SDKs updated to mitigate potential security risks.
  Fix: Regularly update `azure-iot-http-base` and other Azure SDK packages to their latest versions to receive critical security fixes and performance improvements.

Install

• npm install azure-iot-http-base npm
• yarn add azure-iot-http-base yarn
• pnpm add azure-iot-http-base pnpm

Imports

• HttpsClient

  import { HttpsClient } from 'azure-iot-http-base'

  While exportable, direct usage of HttpsClient is generally discouraged. Most applications should use higher-level Azure IoT SDKs like azure-iot-device-http or azure-iothub which abstract transport details.
• HttpClient

  import { HttpClient } from 'azure-iot-http-base'

  Similar to HttpsClient, direct import is not common. This class provides the base HTTP client functionality within the internal SDK architecture.
• RequestOptions

  import { RequestOptions } from 'azure-iot-http-base'

  Defines the structure for HTTP request options used internally. Typically consumed when working directly with HttpClient or HttpsClient, which is rare for end-user applications.
• SharedAccessKeyAuthenticationProvider

  import { SharedAccessKeyAuthenticationProvider } from 'azure-iot-http-base'

  Provides authentication logic for Shared Access Keys, primarily used internally by the HTTP clients for establishing secure connections.

Quickstart

Demonstrates how to instantiate and use `HttpsClient` for a basic GET request, highlighting that this is an internal library not typically for direct consumption by end-user applications.

import { HttpsClient, RequestOptions, RequestAndResponse } from 'azure-iot-http-base';
import { URL } from 'url';

// WARNING: This package is an internal library and direct usage is generally discouraged.
// Most developers should use higher-level Azure IoT SDKs like 'azure-iot-device-http'
// or 'azure-iothub' which manage these transport details.

async function makeSimpleHttpRequest() {
  console.log('Attempting a low-level HTTP GET request using azure-iot-http-base (for demonstration purposes only)...');

  const client = new HttpsClient();
  const url = new URL('https://httpbin.org/get?source=azure-iot-http-base-demo');

  const requestOptions: RequestOptions = {
    method: 'GET',
    url: url.toString(),
    headers: { 'User-Agent': 'Azure-IoT-HTTP-Base-Demo/1.0' }
  };

  try {
    const response: RequestAndResponse = await client.sendRequest(requestOptions);
    console.log(`\nHTTP Status: ${response.statusCode}`);
    console.log(`Response Headers: ${JSON.stringify(response.headers, null, 2)}`);
    console.log(`Response Body (truncated): ${response.body?.toString().substring(0, 200)}...`);
  } catch (error: any) {
    console.error(`\nError making HTTP request: ${error.message}`);
    if (error.response) {
      console.error(`Status: ${error.response.statusCode}`);
      console.error(`Body: ${error.response.body?.toString()}`);
    }
  }
}

makeSimpleHttpRequest().catch(console.error);