gcp-storage

GCP Cloud Storage client for Kit

Files

Dependencies

• gcp-core
• rsa
• crypto

Installation

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

Usage

import Kit.GcpStorage as Storage

main = fn =>
  match Storage.client-from-env()
    | Err e ->
      println "Authentication failed: ${e}"
    | Ok storage ->
      match Storage.list-buckets storage
        | Err e ->
          println "Failed to list buckets: ${e}"
        | Ok result ->
          println "Buckets:"
          List.for-each (fn(bucket) =>
            println "  ${bucket.name} (${bucket.location})"
          ) result.buckets

main

Development

Running Examples

Run parity-safe examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

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

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:

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

Running Parity

Run interpreter/compiler parity checks for examples:

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

The checked-in examples are dry-run examples so parity checks do not require live GCP credentials or a Cloud Storage bucket.

Generating Documentation

Generate API documentation from doc comments:

kit doc

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

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/gcp-storage/, making it available for import as Kit.GcpStorage in other projects.

License

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

Exported Functions & Types

GCPStorageError

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

is-retryable?

Check if a storage error is retryable.

Returns true for transient errors that may succeed on retry: - Rate limit errors (with backoff) - Server errors (5xx)

GCPStorageError -> Bool

client

{project-id: String, service-account: {project-id: String, private-key-id: String, private-key: String, client-email: String, client-id: String, token-uri: String}, access-token: {token: String, expires-at-ms: Int}} -> StorageClient

client-from-metadata

() -> Result StorageClient String

client-from-env

() -> Result StorageClient String

client-with-token

NonEmptyString -> NonEmptyString -> StorageClient

get-object

StorageClient -> NonEmptyString -> NonEmptyString -> Result String GCPStorageError

download-to-file

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () GCPStorageError

put-object

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

put-object-with-type

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

start-resumable-upload

StorageClient -> NonEmptyString -> NonEmptyString -> String -> Int -> Result String GCPStorageError

resume-upload

String -> String -> String -> Result ObjectInfo GCPStorageError

resumable-upload

StorageClient -> NonEmptyString -> NonEmptyString -> String -> String -> Result ObjectInfo GCPStorageError

resumable-upload-file

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result ObjectInfo GCPStorageError

default-chunk-size

Int

upload-chunk

String -> String -> Int -> Int -> Int -> String -> Result (Option ObjectInfo) GCPStorageError

get-upload-status

String -> Int -> Result Int GCPStorageError

chunked-upload

StorageClient -> NonEmptyString -> NonEmptyString -> String -> String -> Int -> Result ObjectInfo GCPStorageError

chunked-upload-file

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Int -> Result ObjectInfo GCPStorageError

delete-object

StorageClient -> NonEmptyString -> NonEmptyString -> Result () GCPStorageError

exists?

StorageClient -> NonEmptyString -> NonEmptyString -> Bool

head-object

StorageClient -> NonEmptyString -> NonEmptyString -> Result ObjectInfo GCPStorageError

update-object-metadata

StorageClient -> NonEmptyString -> NonEmptyString -> {content-type: String, cache-control: String, content-disposition: String, content-encoding: String, content-language: String} -> Result ObjectInfo GCPStorageError

set-content-type

StorageClient -> NonEmptyString -> NonEmptyString -> String -> Result ObjectInfo GCPStorageError

set-cache-control

StorageClient -> NonEmptyString -> NonEmptyString -> String -> Result ObjectInfo GCPStorageError

set-custom-metadata

StorageClient -> NonEmptyString -> NonEmptyString -> List (String, String) -> Result ObjectInfo GCPStorageError

copy-object

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () GCPStorageError

move-object

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () GCPStorageError

compose-objects

StorageClient -> NonEmptyString -> List String -> NonEmptyString -> Result ObjectInfo GCPStorageError

compose-objects-with-generations

StorageClient -> NonEmptyString -> List {name: String, generation: String} -> NonEmptyString -> Result ObjectInfo GCPStorageError

list-objects

StorageClient -> NonEmptyString -> String -> Int -> Result ListObjectsResponse GCPStorageError

list-objects-with-token

StorageClient -> NonEmptyString -> String -> Int -> String -> Result ListObjectsResponse GCPStorageError

list-objects-delimiter

StorageClient -> NonEmptyString -> String -> String -> Int -> Result ListObjectsResponse GCPStorageError

list-buckets

StorageClient -> Result ListBucketsResponse GCPStorageError

list-buckets-with-token

StorageClient -> String -> Result ListBucketsResponse GCPStorageError

get-bucket

StorageClient -> NonEmptyString -> Result BucketInfo GCPStorageError

create-bucket

StorageClient -> NonEmptyString -> Result () GCPStorageError

create-bucket-with-options

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

delete-bucket

StorageClient -> NonEmptyString -> Result () GCPStorageError

is-versioning-enabled?

StorageClient -> NonEmptyString -> Result Bool GCPStorageError

enable-versioning

StorageClient -> NonEmptyString -> Result () GCPStorageError

disable-versioning

StorageClient -> NonEmptyString -> Result () GCPStorageError

list-object-versions

StorageClient -> NonEmptyString -> String -> Int -> Result ListObjectsResponse GCPStorageError

list-object-versions-with-token

StorageClient -> NonEmptyString -> String -> Int -> String -> Result ListObjectsResponse GCPStorageError

get-object-version

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result String GCPStorageError

head-object-version

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result ObjectInfo GCPStorageError

delete-object-version

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () GCPStorageError

restore-object-version

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result ObjectInfo GCPStorageError

delete-after-days

Int -> LifecycleRule

delete-prefix-after-days

String -> Int -> LifecycleRule

transition-after-days

String -> Int -> LifecycleRule

delete-old-versions

Int -> Int -> LifecycleRule

get-lifecycle-rules

StorageClient -> NonEmptyString -> Result (List LifecycleRule) GCPStorageError

set-lifecycle-rules

StorageClient -> NonEmptyString -> List LifecycleRule -> Result () GCPStorageError

delete-lifecycle-rules

StorageClient -> NonEmptyString -> Result () GCPStorageError

cors-allow-all

Int -> CorsRule

cors-for-origins

List String -> List String -> Int -> CorsRule

cors-read-only

List String -> Int -> CorsRule

get-cors

StorageClient -> NonEmptyString -> Result (List CorsRule) GCPStorageError

set-cors

StorageClient -> NonEmptyString -> List CorsRule -> Result () GCPStorageError

delete-cors

StorageClient -> NonEmptyString -> Result () GCPStorageError

retention-days

Int -> RetentionPolicy

retention-years

Int -> RetentionPolicy

retention-seconds

Int -> RetentionPolicy

get-retention-policy

StorageClient -> NonEmptyString -> Result (Option RetentionPolicy) GCPStorageError

set-retention-policy

StorageClient -> NonEmptyString -> RetentionPolicy -> Result () GCPStorageError

remove-retention-policy

StorageClient -> NonEmptyString -> Result () GCPStorageError

lock-retention-policy

StorageClient -> NonEmptyString -> Result () GCPStorageError

has-retention-policy?

StorageClient -> NonEmptyString -> Bool

is-retention-locked?

StorageClient -> NonEmptyString -> Bool

iam-role-object-viewer

Role for viewing objects (read-only access to objects)

String

iam-role-object-creator

Role for creating objects (can upload but not delete)

String

iam-role-object-admin

Role for full control of objects (read, write, delete objects)

String

iam-role-admin

Role for full control of bucket and objects

String

iam-role-legacy-bucket-reader

Role for viewing bucket metadata and listing objects

String

iam-role-legacy-bucket-writer

Role for creating, replacing, and deleting objects

String

iam-binding

String -> List String -> IamBinding

iam-public-read

() -> IamBinding

get-iam-policy

StorageClient -> NonEmptyString -> Result IamPolicy GCPStorageError

set-iam-policy

StorageClient -> NonEmptyString -> IamPolicy -> Result IamPolicy GCPStorageError

add-iam-binding

StorageClient -> NonEmptyString -> IamBinding -> Result IamPolicy GCPStorageError

remove-iam-binding

StorageClient -> NonEmptyString -> String -> List String -> Result IamPolicy GCPStorageError

is-public?

StorageClient -> NonEmptyString -> Bool

make-public

StorageClient -> NonEmptyString -> Result IamPolicy GCPStorageError

make-private

StorageClient -> NonEmptyString -> Result IamPolicy GCPStorageError

get-labels

Gets labels from a bucket.

Labels are key-value pairs used for organizing and categorizing buckets. They can be used for billing reports, resource management, and filtering.

Parameters:

Returns:

StorageClient -> NonEmptyString -> Result (List (String, String)) GCPStorageError

match Storage.get-labels client "my-bucket"
  | Ok labels ->
    List.fold (fn(_, pair) =>
      match pair | (k, v) -> println "  ${k}: ${v}"
    ) no-op labels
  | Err e -> println "Failed: ${e}"

set-labels

Sets labels on a bucket, replacing all existing labels.

This replaces all labels on the bucket with the provided labels. To add/update specific labels while preserving others, use update-labels.

Parameters:

Returns:

StorageClient -> NonEmptyString -> List (String, String) -> Result (List (String, String)) GCPStorageError

labels = [("environment", "production"), ("team", "backend")]
match Storage.set-labels client "my-bucket" labels
  | Ok _ -> println "Labels set"
  | Err e -> println "Failed: ${e}"

update-labels

Updates labels on a bucket, merging with existing labels.

This adds or updates the specified labels while preserving existing ones. To remove a label, use remove-label or remove-labels.

Parameters:

Returns:

StorageClient -> NonEmptyString -> List (String, String) -> Result (List (String, String)) GCPStorageError

# Add a new label without removing existing ones
match Storage.update-labels client "my-bucket" [("version", "2.0")]
  | Ok labels -> println "Updated labels"
  | Err e -> println "Failed: ${e}"

remove-label

Removes a single label from a bucket.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> Result (List (String, String)) GCPStorageError

match Storage.remove-label client "my-bucket" "deprecated"
  | Ok _ -> println "Label removed"
  | Err e -> println "Failed: ${e}"

remove-labels

Removes multiple labels from a bucket.

Parameters:

Returns:

StorageClient -> NonEmptyString -> List String -> Result (List (String, String)) GCPStorageError

match Storage.remove-labels client "my-bucket" ["temp", "deprecated"]
  | Ok labels -> println "Labels removed"
  | Err e -> println "Failed: ${e}"

clear-labels

Clears all labels from a bucket.

Parameters:

Returns:

StorageClient -> NonEmptyString -> Result () GCPStorageError

match Storage.clear-labels client "my-bucket"
  | Ok _ -> println "All labels cleared"
  | Err e -> println "Failed: ${e}"

get-label

Gets a specific label value from a bucket.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> Option String

match Storage.get-label client "my-bucket" "environment"
  | Some env -> println "Environment: ${env}"
  | None -> println "No environment label"

has-label?

Checks if a bucket has a specific label.

Parameters:

Returns:

StorageClient -> NonEmptyString -> NonEmptyString -> Bool

if Storage.has-label? client "my-bucket" "production" then
  println "This is a production bucket"

upload-file

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () GCPStorageError

download-file

StorageClient -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Result () GCPStorageError

signed-url

StorageClient -> NonEmptyString -> NonEmptyString -> PositiveInt -> NonEmptyString -> Result String GCPStorageError