azure-storage

Azure Blob Storage client for Kit

Files

Dependencies

• azure-core

This package requires the net capability because Blob Storage operations use HTTPS.

Installation

kit add gitlab.com/kit-lang/packages/kit-azure-storage.git

Usage

import Kit.Azure-Storage as Storage

main = fn =>
  match Storage.client-from-env
    | Err err ->
      println "Unable to create Azure Storage client: ${err}"
    | Ok storage ->
      # List containers in the storage account.
      match Storage.list-containers storage
        | Err err -> println "List containers failed: ${err}"
        | Ok result ->
          println "Containers: ${Int.to-string (List.length result.containers)}"

      # Upload, read, and delete a blob.
      container = "my-container"
      blob-name = "kit/hello.txt"
      content = "Hello from Kit"

      match Storage.put-blob-with-type storage container blob-name content "text/plain"
        | Err err -> println "Upload failed: ${err}"
        | Ok _ ->
          match Storage.get-blob storage container blob-name
            | Ok downloaded -> println downloaded
            | Err err -> println "Download failed: ${err}"

          match Storage.delete-blob storage container blob-name
            | Ok _ -> println "Deleted ${blob-name}"
            | Err err -> println "Delete failed: ${err}"

main

Authentication

Storage.client-from-env supports either a full Azure Storage connection string or an account name and key:

export AZURE_STORAGE_CONNECTION_STRING='DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net'

or:

export AZURE_STORAGE_ACCOUNT=myaccount
export AZURE_STORAGE_KEY='base64-account-key'

For Azure-hosted workloads with managed identity enabled, create a client with:

match Storage.client-from-managed-identity "myaccount"
  | Ok storage -> println "Using managed identity"
  | Err err -> println "Managed identity failed: ${err}"

API Overview

Blob operations:

• get-blob
• put-blob
• put-blob-with-type
• delete-blob
• exists?
• head-blob
• copy-blob
• list-blobs
• list-blobs-with-marker
• list-blobs-delimiter

Container operations:

• list-containers
• list-containers-with-marker
• create-container
• delete-container

File convenience helpers:

• upload-file
• download-file

Development

Running Examples

Run the basic example with the interpreter:

kit run examples/basic.kit

Compile the basic example to a native binary:

kit build examples/basic.kit && ./basic

The upload/download example also needs a target container:

export AZURE_CONTAINER=mycontainer
kit run examples/upload-download.kit

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running Parity Checks

Run interpreter/compiler parity checks for the examples:

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

This verifies that examples run through the interpreter, compile, execute as native binaries, and produce matching output.

Running kit dev

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

kit dev

This will:

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

Generating Documentation

Generate API documentation from doc comments:

kit doc src/storage.kit -o docs/storage.html

Note: Kit sources with doc comments (##) generate HTML documentation.

Cleaning Build Artifacts

Remove generated files, caches, parity results, 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/azure-storage/, making it available for import as Kit.Azure-Storage in other projects.

If dependency cache contents are stale during local development, reinstall with:

kit install --force

License

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

Exported Functions & Types

AzureStorageError

Azure Storage error type with specific variants for different failure modes.

StorageClient

Azure Storage client configuration.

Fields: - azure: Underlying Azure client for authentication and signing - base-url: Base URL for blob storage (https://{account}.blob.core.windows.net)

BlobInfo

Metadata for an Azure blob.

Fields: - name: The blob's name (path) within the container - container: Container name containing this blob - size: Size of the blob in bytes - content-type: MIME type of the blob content - etag: Entity tag (version identifier) of the blob - last-modified: ISO 8601 timestamp of last modification

ContainerInfo

Metadata for an Azure container.

Fields: - name: Container name - last-modified: ISO 8601 timestamp of last modification

ListBlobsResponse

Response from listing blobs in a container.

Fields: - blobs: List of blobs matching the query - prefixes: List of common prefixes (for hierarchical listing with delimiter) - next-marker: Marker for fetching next page (empty if none)

ListContainersResponse

Response from listing containers in a storage account.

Fields: - containers: List of containers - next-marker: Marker for fetching next page (empty if none)

client

Create storage client from Azure client.

Wraps an existing Azure client for blob storage operations.

Parameters:

Returns:

Azure.AzureClient -> StorageClient

azure = Azure.client creds
storage = Storage.client azure

client-from-connection-string

Create client from Azure connection string.

Parses an Azure Storage connection string and creates a client. Connection string format: "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net"

Parameters:

Returns:

String -> Result StorageClient String

conn-str = "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=...;"
match Storage.client-from-connection-string conn-str
  | Ok client -> print "Client created"
  | Err err -> print "Error: ${err}"

client-from-env

Create client from environment variables.

Reads credentials from AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY environment variables.

Returns:

() -> Result StorageClient String

match Storage.client-from-env()
  | Ok client -> print "Client created from environment"
  | Err err -> print "Error: ${err}"

client-from-managed-identity

Create client with managed identity.

Creates a client using Azure Managed Identity for authentication. Useful for applications running in Azure VMs, App Service, or AKS.

Parameters:

Returns:

NonEmptyString -> Result StorageClient String

match Storage.client-from-managed-identity "mystorageaccount"
  | Ok client -> print "Using managed identity"
  | Err err -> print "Error: ${err}"

client-with-credentials

Create client with explicit credentials.

Creates a client with shared key authentication using explicit account credentials.

Parameters:

Returns:

NonEmptyString -> NonEmptyString -> StorageClient

storage = Storage.client-with-credentials "myaccount" "base64encodedkey=="

get-blob

Get blob content.

Downloads the content of a blob from an Azure container.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> Result String AzureStorageError

match Storage.get-blob client "my-container" "data/file.txt"
  | Ok content -> print content
  | Err err -> print "Error: ${err}"

put-blob

Upload blob with default content type.

Uploads content to an Azure container with default content type (application/octet-stream).

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> String -> Result () AzureStorageError

match Storage.put-blob client "my-container" "data.txt" "Hello, Azure!"
  | Ok _ -> print "Upload successful"
  | Err err -> print "Error: ${err}"

put-blob-with-type

Upload blob with specific content type.

Uploads content to an Azure container with a custom content type. Creates a BlockBlob in Azure Storage.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> String -> String -> Result () AzureStorageError

json = "{\"name\": \"example\"}"
match Storage.put-blob-with-type client "my-container" "data.json" json "application/json"
  | Ok _ -> print "Upload successful"
  | Err err -> print "Error: ${err}"

delete-blob

Delete blob.

Deletes a blob from an Azure container.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> Result () AzureStorageError

match Storage.delete-blob client "my-container" "old-file.txt"
  | Ok _ -> print "Deleted successfully"
  | Err err -> print "Error: ${err}"

exists?

Check if blob exists (convenience function).

Simplified wrapper around head-blob that returns a boolean.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> Bool

if Storage.exists? client "my-container" "test.txt" then
  print "Blob exists"
else
  print "Blob not found"

head-blob

Get blob metadata using HEAD request.

Retrieves blob metadata without downloading the content.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> Result BlobInfo AzureStorageError

match Storage.head-blob client "my-container" "test.txt"
  | Ok info ->
    print "Size: ${Int.to-string info.size} bytes"
    print "Content-Type: ${info.content-type}"
  | Err err -> print "Error: ${err}"

copy-blob

Copy blob within Azure Storage.

Copies a blob from one location to another within Azure Storage. The source and destination can be in the same or different containers. This is a server-side operation that doesn't download the blob.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () AzureStorageError

match Storage.copy-blob client "src-container" "old/file.txt" "dest-container" "new/file.txt"
  | Ok _ -> print "Blob copied"
  | Err err -> print "Error: ${err}"

list-blobs

List blobs in container.

Retrieves a list of blobs from an Azure container with optional prefix filtering.

Parameters:

Returns:

StorageClient -> NonEmptyString -> String -> Int -> Result ListBlobsResponse AzureStorageError

match Storage.list-blobs client "my-container" "logs/" 100
  | Ok response ->
    print "Found ${List.length response.blobs} blobs"
    if String.length response.next-marker > 0 then
      print "More results available"
  | Err err -> print "Error: ${err}"

list-blobs-with-marker

List blobs with pagination marker.

Continues a previous list-blobs call using a pagination marker.

Parameters:

Returns:

StorageClient -> NonEmptyString -> String -> Int -> String -> Result ListBlobsResponse AzureStorageError

# Get first page
match Storage.list-blobs client "my-container" "" 1000
  | Ok response ->
    if String.length response.next-marker > 0 then
      # Get next page
      match Storage.list-blobs-with-marker client "my-container" "" 1000 response.next-marker
        | Ok next-page -> print "Got next page"
        | Err err -> print "Error: ${err}"
  | Err err -> print "Error: ${err}"

list-blobs-delimiter

List blobs with delimiter (hierarchical listing).

Lists blobs using a delimiter to simulate a directory structure. Common prefixes (directory-like paths) are returned separately from blobs.

Parameters:

Returns:

StorageClient -> NonEmptyString -> String -> String -> Int -> Result ListBlobsResponse AzureStorageError

# List "directories" and files in root
match Storage.list-blobs-delimiter client "my-container" "" "/" 100
  | Ok response ->
    print "Directories: ${List.length response.prefixes}"
    print "Files: ${List.length response.blobs}"
  | Err err -> print "Error: ${err}"

list-containers

List containers in storage account.

Retrieves a list of all containers in the storage account.

Parameters:

Returns:

StorageClient -> Result ListContainersResponse AzureStorageError

match Storage.list-containers client
  | Ok response ->
    print "Found ${List.length response.containers} containers"
  | Err err -> print "Error: ${err}"

list-containers-with-marker

List containers with pagination marker.

Continues a previous list-containers call using a pagination marker.

Parameters:

Returns:

StorageClient -> String -> Result ListContainersResponse AzureStorageError

match Storage.list-containers client
  | Ok response ->
    if String.length response.next-marker > 0 then
      match Storage.list-containers-with-marker client response.next-marker
        | Ok next-page -> print "Got next page"
        | Err err -> print "Error: ${err}"
  | Err err -> print "Error: ${err}"

create-container

Create container.

Creates a new container in the storage account. Container names must be lowercase and follow DNS naming rules.

Parameters:

Returns:

StorageClient -> NonEmptyString -> Result () AzureStorageError

match Storage.create-container client "my-new-container"
  | Ok _ -> print "Container created"
  | Err "Container already exists" -> print "Container exists"
  | Err err -> print "Error: ${err}"

delete-container

Delete container.

Deletes a container from the storage account. The container must be empty before deletion.

Parameters:

Returns:

StorageClient -> NonEmptyString -> Result () AzureStorageError

match Storage.delete-container client "old-container"
  | Ok _ -> print "Container deleted"
  | Err "Container is not empty" -> print "Delete blobs first"
  | Err err -> print "Error: ${err}"

upload-file

Upload file from local filesystem to Azure Storage.

Reads a file from the local filesystem and uploads it to Azure Storage. Automatically detects content type based on file extension.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () AzureStorageError

match Storage.upload-file client "my-container" "reports/data.pdf" "/tmp/report.pdf"
  | Ok _ -> print "File uploaded"
  | Err err -> print "Error: ${err}"

download-file

Download blob from Azure Storage to local filesystem.

Downloads a blob from Azure Storage and writes it to the local filesystem.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () AzureStorageError

match Storage.download-file client "my-container" "reports/data.pdf" "/tmp/report.pdf"
  | Ok _ -> print "File downloaded"
  | Err err -> print "Error: ${err}"