8000 GitHub - llmII/spork-https: Little https helper library for Janet & jsec · GitHub
[go: up one dir, main page]

Skip to content

About

Little https helper library for Janet & jsec

Resources

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

Table of Contents

  1. Overview
    1. Features
  2. Status
  3. Dependencies
  4. Quick Start
    1. Installation
    2. Basic Usage
  5. API Reference
    1. https/get
      1. Parameters
      2. Returns
      3. Example
    2. https/post
      1. Parameters
      2. Example
    3. https/put
    4. https/patch
    5. https/delete
    6. https/head
    7. https/request
    8. https/open-stream
      1. Example
    9. https/download
      1. Example
    10. https/server
      1. Parameters
      2. Example
  6. TLS Options
    1. Security Options
  7. Testing
  8. Examples
    1. Simple GET Request
    2. POST with JSON
    3. Using spork/http Directly
  9. Development
    1. Code Formatting
    2. Documentation Generation
  10. Architecture
  11. Related Projects
  12. License
  13. Contributing
  14. Changelog

Overview

spork-https provides HTTPS support for spork's HTTP client using jsec for TLS encryption. It is a thin wrapper that demonstrates the stream-factory pattern in spork, enabling HTTPS requests through pluggable transport mechanisms.

Features

  • Simple HTTPS client API (https/get, https/post, etc.)
  • Streaming HTTPS responses via https/open-stream
  • Constant-memory downloads to files or sinks via https/download
  • Adaptive socket factory enabling seamless HTTP/HTTPS redirects
  • HTTPS server support with TLS encryption
  • Full TLS support via jsec
  • Certificate verification
  • Custom TLS options (ciphers, versions, client certificates, mTLS)
  • Compatible with spork's HTTP API
  • Works with Janet's with macro for automatic cleanup

Status

Functional - The library works for basic HTTPS client/server use cases.

Dependencies

  • Janet >= 1.35.0
  • spork (modified version with stream-factory support)
  • jsec >= 1.0.0

Quick Start

Installation

jpm install spork-https

Basic Usage

(import spork-https :as https)

# Simple HTTPS GET
(let [response (https/get "https://example.com/")]
  (pp (:status response))
  (pp (length (:body response))))

# HTTPS POST with body
(https/post "https://api.example.com/data"
            :body "{\"key\": \"value\"}"
            :headers {"Content-Type" "application/json"})

API Reference

https/get

(https/get url &keys opts)

Make an HTTPS GET request.

Parameters

  • url - HTTPS URL string (must start with https://)
  • opts - Optional keyword arguments:
    • :headers - Request headers table
    • :tls-opts - TLS options (see TLS Options)

Returns

Response table with:

  • :status - HTTP status code (integer)
  • :headers - Response headers table
  • :body - Response body (buffer)
  • :connection - TLS stream
  • :buffer - Internal buffer

Example

(import spork-https :as https)

(let [res (https/get "https://example.com/")]
  (assert (= (:status res) 200))
  (print "Body length: " (length (:body res))))

https/post

(https/post url &keys opts)

Make an HTTPS POST request.

Parameters

  • url - HTTPS URL string
  • opts - Optional keyword arguments:
    • :body - Request body (string or buffer)
    • :headers - Request headers table
    • :tls-opts - TLS options

Example

(https/post "https://api.example.com/submit"
            :body "data=value"
            :headers {"Content-Type" "application/x-www-form-urlencoded"})

https/put

(https/put url &keys opts)

Make an HTTPS PUT request. Parameters same as https/post.

https/patch

(https/patch url &keys opts)

Make an HTTPS PATCH request. Parameters same as https/post.

https/delete

(https/delete url &keys opts)

Make an HTTPS DELETE request.

https/head

(https/head url &keys opts)

Make an HTTPS HEAD request.

https/request

(https/request method url &keys opts)

Make an HTTPS request with specified method.

  • method - HTTP method string ("GET", "POST", etc.)
  • url - HTTPS URL string
  • opts - Optional keyword arguments:
    • :body - Request body content
    • :headers - Request headers table
    • :sink - Target to stream response body into (function, file, or buffer)
    • :max-redirects - Maximum number of 3xx redirects to follow (default 0)
    • :tls-opts - TLS options passed to jsec/tls/connect
    • :stream-opts - Additional stream options

https/open-stream

(https/open-stream url &keys opts)

Open a streaming HTTPS/HTTP connection to url. Returns a response stream object implementing :status, :headers, :read, :blocks, :lines, and :close. Automatically follows HTTP 3xx redirects across HTTP and HTTPS up to :max-redirects (default 10).

  • url - HTTPS/HTTP URL string
  • opts - Optional keyword arguments:
    • :method - HTTP method string (default "GET")
    • :body - Request body content
    • :headers - Request headers table
    • :max-redirects - Maximum redirects to follow (default 10)
    • :tls-opts - TLS options passed to jsec/tls/connect
    • :stream-opts - Additional stream options

Example

(import spork-https :as https)

(with [s (https/open-stream "https://example.com/stream")]
  (print "Status: " (:status s))
  (loop [block :in (:blocks s 1024)]
    (file/write stdout block)))

https/download

(https/download url dest &keys opts)

Download a resource over HTTPS/HTTP streaming directly to a file, buffer, or sink callback with constant $O(1)$ memory usage.

  • url - URL to download
  • dest - Target file path (string), file handle, buffer, or sink function ((fn [chunk]))
  • opts - Optional keyword arguments:
    • :headers - Request headers table
    • :max-redirects - Maximum redirects to follow (default 10)
    • :tls-opts - TLS options
    • :stream-opts - Additional stream options

Example

(import spork-https :as https)

# Download directly to file
(https/download "https://example.com/large-archive.tar.gz" "archive.tar.gz")

# Download with progress sink callback
(var total 0)
(https/download "https://example.com/data.bin"
                (fn [chunk]
                  (+= total (length chunk))
                  (file/write stdout ".")))

https/server

(https/server handler cert key &opt host port tls-opts)

Create an HTTPS server that handles incoming requests with TLS encryption.

Parameters

  • handler - Request handler function (same signature as spork/http)
    • Receives request table with :headers, :path, :method, :body
    • Returns response table with :status, :headers, :body
  • cert - Server certificate (PEM string or file path)
  • key - Server private key (PEM string or file path)
  • host - Host to bind to (default "0.0.0.0")
  • port - Port to bind to (default "8443")
  • tls-opts - Optional TLS configuration table (see TLS Options)

Example

(import spork-https :as https)
(import jsec/cert)

# Generate certificate and key
(let [result (cert/generate-self-signed-cert
               {:common-name "localhost"
                :organization "Test"
                :country "US"
                :days-valid 365
                :bits 2048})
      cert (result :cert)
      pkey (result :key)]

  # Create handler
  (defn handler [req]
    (case (req :method)
      "GET" {:status 200
             :headers {"Content-Type" "text/plain"}
             :body "Hello, HTTPS!"}
      {:status 405
       :headers {"Content-Type" "text/plain"}
       :body "Method Not Allowed"}))

  # Start server
  (def server (https/server handler cert pkey "0.0.0.0" "8443"))

  # Server runs until closed
  (ev/sleep 60)
  (:close server))

TLS Options

The :tls-opts table accepts the following keys:

Option Type Description
:verify boolean Verify server certificate (default: true)
:ca string Path to CA certificate file for verification
:cert string Client certificate for mTLS
:key string Client private key for mTLS
:security table Security options (TLS versions, ciphers, etc.)

Security Options

(https/get "https://example.com/"
           :tls-opts {:security {:min-version "TLS1.2"
                                 :max-version "TLS1.3"
                                 :ciphers "HIGH:!aNULL"}})

Testing

spork-https uses assay for testing.

# Run all tests
janet test/runner.janet # options like verbosity go here (ex: --verbosity 6)

# Clean build and test
jpm clean && jpm build && jpm test

The test suite covers:

  • HTTPS client tests (GET, POST, PUT, PATCH, DELETE)
  • HTTPS server tests (request handling, TLS handshake, concurrent clients)
  • Stream factory integration tests
  • Certificate generation tests

Examples

Runnable examples are in the examples/ directory:

File Description
simple-server.janet HTTPS server with self-signed cert
simple-client.janet HTTPS client requests
local-test.janet Client/server without network

Simple GET Request

(import spork-https :as https)

(let [res (https/get "https://api.github.com/users/janet-lang")]
  (when (= (:status res) 200)
    (print "Success!")
    (print (:body res))))

POST with JSON

(import spork-https :as https)
(import spork/json)

(let [payload (json/encode {:name "test" :value 42})
      res (https/post "https://api.example.com/data"
                     :body payload
                     :headers {"Content-Type" "application/json"})]
  (print "Status: " (:status res)))

Using spork/http Directly

You can use spork's http module directly with jsec as the stream factory:

(import spork/http)
(import jsec/tls :as tls)

(let [res (http/request "GET" "https://example.com/"
                       :stream-factory tls/connect)]
  (pp (:status res)))

Development

Code Formatting

jpm run format-janet   # Format Janet source files
jpm run format         # Format all code

Documentation Generation

jpm run gen-docs       # Generate markdown from org files
jpm run clean-gen      # Clean generated files

Architecture

spork-https is a thin wrapper that:

  1. Creates a TLS stream factory function with jsec
  2. Passes this factory to spork's http/request via :stream-factory
  3. Merges TLS options from :tls-opts into the factory

This design keeps spork transport-agnostic while enabling HTTPS through optional extensions.

Related Projects

  • spork - Janet utilities and HTTP client
  • jsec - TLS/SSL support for Janet via OpenSSL
  • janet-assay - Testing framework for Janet
  • Janet - The Janet programming language

License

ISC License - see LICENSE file

Contributing

Issues and pull requests welcome at https://github.com/llmII/spork-https. Tickets and patches (fossil, preferred) at https://code.amlegion.org/spork-https.

Changelog

See NEWS.org for version history.

About

Little https helper library for Janet & jsec

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0