aws-crt

What is aws-crt?

The aws-crt npm package is a low-level client library for AWS services, providing a high-performance, cross-platform implementation of the AWS Common Runtime (CRT). It offers functionalities for networking, cryptography, and other foundational services that are essential for building AWS SDKs and other AWS-related applications.

What are aws-crt's main functionalities?

MQTT Client

This feature allows you to create an MQTT client to connect to AWS IoT Core. The code sample demonstrates how to set up the client, connect to the broker, subscribe to a topic, and handle incoming messages.

const { mqtt } = require('aws-crt');

const client = mqtt.Client({
  host: 'example.iot.region.amazonaws.com',
  port: 8883,
  clientId: 'myClientId',
  clean: true,
  keepAlive: 60,
  protocol: 'mqtts',
  key: 'path/to/private-key.pem',
  cert: 'path/to/certificate.pem',
  ca: 'path/to/ca.pem'
});

client.on('connect', () => {
  console.log('Connected to MQTT broker');
  client.subscribe('my/topic', { qos: 1 });
});

client.on('message', (topic, message) => {
  console.log(`Received message: ${message.toString()} on topic: ${topic}`);
});

client.connect();

HTTP Client

This feature provides an HTTP client for making HTTP requests. The code sample shows how to create an HTTP client, make a GET request, and handle the response.

const { http } = require('aws-crt');

const client = new http.HttpClient();

const request = new http.HttpRequest('https://example.com', 'GET');

client.request(request, (response) => {
  console.log(`Status Code: ${response.statusCode}`);
  response.on('data', (chunk) => {
    console.log(`Body: ${chunk.toString()}`);
  });
});

WebSocket Client

This feature allows you to create a WebSocket client for real-time communication. The code sample demonstrates how to set up the client, connect to a WebSocket server, send messages, and handle incoming messages.

const { websocket } = require('aws-crt');

const client = new websocket.WebSocketClient('wss://example.com/socket');

client.on('open', () => {
  console.log('WebSocket connection opened');
  client.send('Hello, WebSocket!');
});

client.on('message', (message) => {
  console.log(`Received message: ${message}`);
});

client.on('close', () => {
  console.log('WebSocket connection closed');
});

client.connect();

Other packages similar to aws-crt

aws-sdk

The aws-sdk package is the official AWS SDK for JavaScript, providing a higher-level abstraction over AWS services. It is more user-friendly and feature-rich compared to aws-crt, which is a lower-level library focused on performance and foundational services.

mqtt

The mqtt package is a popular MQTT client for Node.js. While it offers similar MQTT functionalities as aws-crt, it does not provide the same level of integration with AWS services and lacks the additional features like HTTP and WebSocket clients.

axios

Axios is a widely-used HTTP client for Node.js and the browser. It provides a simpler and more user-friendly API for making HTTP requests compared to the low-level HTTP client in aws-crt.

ws

The ws package is a simple and fast WebSocket client for Node.js. It offers similar WebSocket functionalities as aws-crt but does not include the additional AWS-specific features.

README

AWS CRT JS

NodeJS/Browser bindings for the AWS Common Runtime

API Docs

License

This library is licensed under the Apache 2.0 License.

Building the package

Prereqs:

• Node 14+
• npm
• CMake 3.1+
• Linux: gcc 5+ or clang 3.6+
  • If your compiler can compile node, it can compile this library
• Windows: Visual Studio 2015+
• OSX: XCode or brew-installed llvm

To build the package locally

git clone https://github.com/awslabs/aws-crt-nodejs.git
cd aws-crt-nodejs
git submodule update --init
npm install

Using From Your NodeJS Application

Normally, you just declare aws-crt as a dependency in your package.json file.

Using From Your Browser Application

You can either add it to package.json (if using a tool like webpack), or just import the dist.browser/ folder into your web project

Installing from npm

npm install aws-crt

To reduce the size of package, we put the C source code in the S3 bucket. If the platform you are using doesn't have the prebuilt binary, the install script will pull the source from S3 bucket. In case of no public internet access, you can specify the "CRT_BINARY_HOST" environment variable for the host of the source code. The build script will fetch source code from that host instead. To fetch the source from S3, you can reach to the cloudfront distribution (Only works for version after v1.9.2) https://d332vdhbectycy.cloudfront.net/aws-crt-<version>-source.tgz, the sha256 checksum https://d332vdhbectycy.cloudfront.net/aws-crt-<version>-source.sha256

Debug C part of code

After building the package locally, use node ./scripts/build.js --debug to enable debug. Then, attach any C debugger to use node to run jest

Mac-Only TLS Behavior

Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. Beginning in v1.1.11, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:

static: certificate has an existing certificate-key pair that was previously imported into the Keychain.  Using key from Keychain instead of the one provided.