mqtt

Kind	ffi-c
Capabilities	ffi
Categories	networking ffi
Keywords	mqtt iot messaging pubsub protocol

MQTT protocol client bindings for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_mqtt.c`	C FFI wrapper around libmosquitto
`c/kit_mqtt.h`	C header for the FFI wrapper
`examples/basic.kit`	Basic usage example
`kit.toml`	Package manifest with metadata and native library configuration
`src/mqtt.kit`	Kit MQTT API and extern-c bindings
`tests/mqtt.test.kit`	Tests for exported MQTT functions and constants

Dependencies

No Kit package dependencies.

This package depends on the system Mosquitto client library.

Platform	Command
macOS	`brew install mosquitto`
Ubuntu	`sudo apt install libmosquitto-dev`
Fedora	`sudo dnf install mosquitto-devel`

Installation

kit add gitlab.com/kit-lang/packages/kit-mqtt.git

The package requires Kit's ffi capability when running or building code that imports Kit.MQTT.

Usage

import Kit.MQTT as Mqtt

main = fn =>
  # Initialize the Mosquitto library before creating clients
  match Mqtt.lib-init
    | Err e -> println ("Init error: " ++ e)
    | Ok _ ->
      println "MQTT library initialized"

      # Show the linked Mosquitto version and QoS constants
      println ("Mosquitto version: " ++ Mqtt.version)
      println ("QoS 0: " ++ (show Mqtt.qos-0))
      println ("QoS 1: " ++ (show Mqtt.qos-1))
      println ("QoS 2: " ++ (show Mqtt.qos-2))

      match Mqtt.new "kit-client"
        | Err e -> println ("Client error: " ++ e)
        | Ok client ->
          match Mqtt.connect client "localhost" 1883 60
            | Err e -> println ("Connect error: " ++ e)
            | Ok _ ->
              match Mqtt.subscribe client "kit/test" (Mqtt.qos-1)
                | Ok _ -> println "Subscribed to kit/test"
                | Err e -> println ("Subscribe error: " ++ e)

              match Mqtt.publish client "kit/test" "Hello from Kit!" (Mqtt.qos-1) false
                | Ok _ -> println "Published message"
                | Err e -> println ("Publish error: " ++ e)

              match Mqtt.loop client 1000
                | Err e -> println ("Loop error: " ++ e)
                | Ok _ ->
                  if Mqtt.has-message? then
                    println ("Topic: " ++ Mqtt.get-last-topic)
                    println ("Payload: " ++ Mqtt.get-last-payload)
                    Mqtt.clear-message
                  else
                    println "No message received"

              match Mqtt.disconnect client
                | Ok _ -> println "Disconnected"
                | Err e -> println ("Disconnect error: " ++ e)

          Mqtt.destroy client

      Mqtt.lib-cleanup

main

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit --allow=ffi

Compile examples to a native binary:

kit build examples/basic.kit --allow=ffi && ./basic

The basic example attempts to connect to localhost:1883. Without a broker, it still exercises library initialization, version reporting, QoS constants, and client creation before printing a connection error.

To exercise the connect, subscribe, publish, and receive path locally, start a broker in another shell:

mosquitto -v -p 1883

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Checking Parity

Compare interpreter and compiled output for examples:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Native Wrapper Notes

The Kit extern bindings link to the package wrapper library, kit_mqtt. The wrapper library is built from c/kit_mqtt.c and links against the system mosquitto library.

If you change c/kit_mqtt.c, c/kit_mqtt.h, src/mqtt.kit, or native metadata in kit.toml, run kit install before testing examples that import Kit.MQTT. That refreshes the package cache used by import Kit.MQTT.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/mqtt/, builds libkit_mqtt.dylib, and makes the package available for import as Kit.MQTT in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Mosquitto is released under the Eclipse Public License 2.0.

Exported Functions & Types

`qos-0`

QoS 0: At most once delivery (fire and forget).

Int

`qos-1`

QoS 1: At least once delivery (acknowledged).

Int

`qos-2`

QoS 2: Exactly once delivery (assured).

Int

`lib-init`

Initialize the MQTT library. Must be called before any other operations.

Returns:

Result Unit String

`lib-cleanup`

Clean up the MQTT library and release global resources.

Unit

`new`

Create a new MQTT client instance.

Parameters:

Returns:

NonEmptyString -> Result Ptr String

Check if a new message has been received.

Returns:

Bool

`get-last-topic`

Get the topic of the last received message.

Returns:

String

`get-last-payload`

Get the payload of the last received message.

Returns:

String

`clear-message`

Clear the last received message.

Unit

`set-credentials`

Set username and password for broker authentication.

Parameters:

Returns:

Ptr -> NonEmptyString -> NonEmptyString -> Result Unit String

`version`

Get the Mosquitto library version string.

Returns:

String