herolib/lib/core/httpconnection

HTTPConnection Module

The HTTPConnection module provides a robust HTTP client implementation with support for JSON handling, custom headers, retries, and caching.

Features

• Generic JSON methods for type-safe requests
• Custom header support
• Built-in retry mechanism
• Cache configuration
• URL encoding support

Basic Usage

import incubaid.herolib.core.httpconnection

// Create a new HTTP connection
mut conn := HTTPConnection{
    base_url: 'https://api.example.com'
    retry: 5  // number of retries for failed requests
}

important: How to use it on a management class e.g. an installe or a client

// e.g. HetznerManager is the object on which we want to have an http client

pub fn (mut h HetznerManager) connection() !&httpconnection.HTTPConnection {
 mut c := h.conn or {
  mut c2 := httpconnection.new(
   name:  'hetzner_${h.name}'
   url:   h.baseurl
   cache: true
   retry: 3
  )!
  c2.basic_auth(h.user, h.password)
  c2
 }

 return c
}

Examples

GET Request with JSON Response

// Define your data structure
struct User {
    id    int
    name  string
    email string
}

// Make a GET request and decode JSON response
user := conn.get_json_generic[User](
    method: .get
    prefix: 'users/1'
    dataformat: .urlencoded
)!

GET Request for List of Items

// Get a list of items and decode each one
users := conn.get_json_list_generic[User](
    method: .get
    prefix: 'users'
    list_dict_key: 'users'  // if response is wrapped in a key
    dataformat: .urlencoded
)!

POST Request with JSON Data

// Create new resource with POST
new_user := conn.post_json_generic[User](
    method: .post
    prefix: 'users'
    dataformat: .urlencoded
    params: {
        'name': 'John Doe'
        'email': 'john@example.com'
    }
)!

Real-World Example: SSH Key Management

Here's a practical example inspired by SSH key management in a cloud API:

// Define the SSH key structure
struct SSHKey {
pub mut:
    name        string
    fingerprint string
    type_       string    @[json: 'type']
    size        int
    created_at  string
    data        string
}

// Get all SSH keys
fn get_ssh_keys(mut conn HTTPConnection) ![]SSHKey {
    return conn.get_json_list_generic[SSHKey](
        method: .get
        prefix: 'key'
        list_dict_key: 'key'
        dataformat: .urlencoded
    )!
}

// Create a new SSH key
fn create_ssh_key(mut conn HTTPConnection, name string, key_data string) !SSHKey {
    return conn.post_json_generic[SSHKey](
        method: .post
        prefix: 'key'
        dataformat: .urlencoded
        params: {
            'name': name
            'data': key_data
        }
    )!
}

// Delete an SSH key
fn delete_ssh_key(mut conn HTTPConnection, fingerprint string) ! {
    conn.delete(
        method: .delete
        prefix: 'key/${fingerprint}'
        dataformat: .urlencoded
    )!
}

Custom Headers

You can set default headers for all requests or specify headers for individual requests:

import net.http { Header }

// Set default headers for all requests
conn.default_header = http.new_header(
    key: .authorization
    value: 'Bearer your-token-here'
)

// Add custom headers for specific request
response := conn.get_json(
    method: .get
    prefix: 'protected/resource'
    header: http.new_header(
        key: .content_type
        value: 'application/json'
    )
)!

Error Handling

The module uses V's built-in error handling. All methods that can fail return a Result type:

// Handle potential errors
user := conn.get_json_generic[User](
    method: .get
    prefix: 'users/1'
) or {
    println('Error: ${err}')
    return
}

Cache Configuration

The module supports caching of responses. Configure caching behavior through the CacheConfig struct:

mut conn := HTTPConnection{
    base_url: 'https://api.example.com'
    cache: CacheConfig{
        enabled: true
        // Add other cache configuration as needed
    }
}