Forem: Maple

Building a Python-requests-style HTTP Client in Haskell

Maple — Sat, 14 Mar 2026 11:16:08 +0000

The Problem with Learning Haskell

When I started learning Haskell, I always struggled to find a suitable scenario to apply it. Without a concrete problem to solve, it is difficult to make real progress.

At some point I had some practical work to do: fetch data from HTTP APIs, process the results, and post them to other endpoints. My instinct was to reach for Python and the requests library, because it is genuinely handy for this kind of task. You grab a URL, get back some JSON, transform it, and send it somewhere else. The whole thing can be done in a few lines.

But I thought: this is exactly the kind of real problem I need. Why not try Haskell?

Exploring the Existing Ecosystem

The first thing I reached for was http-client. It is powerful and the foundation for most other Haskell HTTP libraries. But using it directly requires quite a bit of setup for simple tasks. You need to create a manager, parse a request, and work with a set of low-level types. It is a great library, but it is designed for cases where you need precise control.

There are some lighter alternatives. wreq is a popular one, built on a lens API. Lenses are a fascinating part of the Haskell ecosystem and many people find them worth learning. req is another option with a clean, type-safe API. I used req to finish the work I was doing, and it worked well. But I still missed the simplicity of Python's requests, and I kept thinking about whether something like it was possible in Haskell.

Finding http-dispatch and Deciding to Build Something

Some time later, I came across http-dispatch. It was much closer to what I had in mind. The API was straightforward and the concepts were familiar. Unfortunately the library had not been maintained for a long time. There were some bugs, and some fixes in the source code had never made it to Hackage.

That is when I decided to build my own.

The goal was simple: a library for scenarios where you do not need fine-grained control over the HTTP lifecycle. For those cases, http-client is the right tool. But for the common case of making a request and getting back a response, I wanted something that felt closer to the Python experience.

The Core Abstraction

I started from the most basic mental model of an HTTP interaction: you have a request, you send it to a server, and you get back a response.

This became the core API:

data Request a = Request
  { method  :: Method
  , url     :: String
  , headers :: Headers
  , body    :: Maybe a
  }

data Response a = Response
  { status  :: Int
  , headers :: Headers
  , body    :: a
  }

send :: (ToRequestBody a, FromResponseBody b) => Request a -> IO (Response b)

The send function takes a Request and produces a Response in IO. The type parameters carry the body types, and the typeclass constraints handle serialization and deserialization automatically.

For common HTTP methods, there are simple shortcuts:

-- A simple GET request
resp <- get "https://example.com" :: IO (Response String)
print resp.status  -- 200
print resp.body    -- HTML content as String

-- POST with a plain text body
resp <- post "https://httpbin.org/post" ("hello" :: String) :: IO (Response String)
print resp.status  -- 200

You can also construct a Request manually when you need custom headers:

let req = Request
      { method  = GET
      , url     = "https://api.example.com/data"
      , headers = [("Authorization", "Bearer my-token")]
      , body    = Nothing :: Maybe BS.ByteString
      }
resp <- send req :: IO (Response String)

The library supports modern Haskell record dot syntax (resp.status, resp.body) as well as traditional accessor functions (responseStatus resp, responseBody resp) for those who prefer not to enable language extensions.

JSON Integration

The feature I most wanted to replicate from Python's requests is its JSON handling. In Python, you pass json= to your request and call .json() on the response. It handles the content type header, the serialization, and the deserialization for you. Most API work is exactly this: send JSON, receive JSON.

Haskell's type system makes this possible in a way that is, I think, even nicer than Python. Because we declare our data types upfront, we get static guarantees about the shape of the data.

Here is an example of parsing a JSON response:

{-# LANGUAGE DeriveGeneric #-}

import Data.Aeson (FromJSON)
import GHC.Generics (Generic)
import Network.HTTP.Request

data Date = Date
  { __type :: String
  , iso     :: String
  } deriving (Show, Generic)

instance FromJSON Date

main :: IO ()
main = do
  response <- get "https://api.leancloud.cn/1.1/date" :: IO (Response Date)
  print response.status  -- 200
  print response.body    -- Date { __type = "Date", iso = "2026-03-14T..." }

There is no explicit parsing step. The type annotation :: IO (Response Date) is enough to tell the library to decode the JSON body into a Date value. If decoding fails, an AesonException is thrown.

Sending JSON works the same way:

data Message = Message { content :: String } deriving (Generic)

instance ToJSON Message

main :: IO ()
main = do
  resp <- post "https://api.example.com/messages" (Message "Hello")
            :: IO (Response String)
  print resp.status

Any type with a ToJSON instance is automatically serialized, and Content-Type: application/json is set on the request. You do not need to think about it.

This gives you the simplicity of Python's requests combined with the compile-time guarantees of a static type system. You define your API shapes as types, and the compiler helps you use them correctly.

Using It for an LLM Agent

With the library in a working state, I wanted to build something more substantial with it. I decided to implement a small LLM agent. That became hasuke, a CLI tool for interacting with Claude.

Calling an Anthropic-style API is exactly the use case this library was built for. You construct a JSON request body, send it to the endpoint, and get back a JSON response. The library handled all of this without any friction.

But after building the first version, I noticed that it would sit silently until the full response was generated, then display everything at once. Modern LLM providers support streaming responses to address this: they send partial results incrementally using Server-Sent Events, so you start seeing output right away.

Adding Streaming and SSE Support

I extended the library to support streaming. The key was to express this within the existing type system without changing the core API. I introduced a StreamBody type:

data StreamBody a = StreamBody
  { readNext    :: IO (Maybe a)
  , closeStream :: IO ()
  }

To receive a streaming response, you just change the type annotation:

let req = Request GET "https://example.com/stream" [] (Nothing :: Maybe BS.ByteString)
resp <- send req :: IO (Response (StreamBody BS.ByteString))

let loop = do
      mChunk <- resp.body.readNext
      case mChunk of
        Nothing    -> return ()
        Just chunk -> BS.putStr chunk >> loop
loop
resp.body.closeStream

For SSE, the library parses the event stream protocol automatically. Each SseEvent has fields for the data, event type, and event id:

data SseEvent = SseEvent
  { sseData :: T.Text
  , sseType :: Maybe T.Text
  , sseId   :: Maybe T.Text
  }

Using it looks like this:

let req = Request POST "https://api.anthropic.com/v1/messages" headers (Just body)
resp <- send req :: IO (Response (StreamBody SseEvent))

let loop = do
      mEvent <- resp.body.readNext
      case mEvent of
        Nothing    -> return ()
        Just event -> T.putStr event.sseData >> loop
loop
resp.body.closeStream

The send function signature did not change at all. When the target type is StreamBody SseEvent, the library keeps the connection open and streams events through an internal buffer. From the caller's side, you are just getting a different kind of response body.

This is where Haskell's type system earns its keep. Adding a completely different data transfer mode required almost no changes to the existing API. The same send function, the same Request type, the same conventions. It is now working well in hasuke.

Where Things Stand

The library is published on Hackage under the name request and can be installed with cabal or stack in the usual way. The source code is on GitHub at https://github.com/aisk/request. It powers the streaming output in hasuke, which you can find at https://github.com/aisk/hasuke.

There are features still missing, such as support for HTML form encoding and some other less common use cases. I plan to add these gradually over time. If you run into something you need, feel free to open an issue on GitHub. Feedback and contributions are very welcome.

For the common case of calling JSON APIs, whether in a single response or as a stream, the library does what it was built to do. If you are learning Haskell and looking for a practical project, or you just need a lightweight HTTP client, it might be worth a try.

Making Python Modules Callable: Introducing Cadule

Maple — Fri, 26 Dec 2025 15:02:37 +0000

When writing Python code, I often find myself missing a feature from Node.js: the ability to directly require a module and have it become callable. In Node.js, you can export a function from a module and call it immediately:

const messUpThings = require('./mess-up-things');
messUpThings(); // Works!

I know some developers aren't fond of this pattern, but there are legitimate use cases for it.

The Problem

Consider a scenario where you need to write a helper function with a self-descriptive name, like mess_up_things. The function name itself tells you what it does. You have a few options:

Create a util or helper module: Put it in a util.py or helper.py module. But many developers dislike these generic names, especially Go developers who prefer more descriptive package names.
Create a dedicated file: Put it in mess_up_things.py. But then you need to write verbose import statements like:

from mess_up_things import mess_up_things

This repetition feels unnecessary. Wouldn't it be nice if you could just do:

import mess_up_things
mess_up_things()

Exploring Solutions

If you're familiar with Python's magic methods, you might know that any object with a __call__ method becomes callable. Since modules are instances of types.ModuleType, and they support magic methods like __getattr__, couldn't we just define a __call__ method directly on a module?

Unfortunately, Python doesn't support this out of the box. There was actually PEP 713 that proposed adding module-level __call__ support, but it was rejected.

However, if you're familiar with Python's runtime, you'll find there's a trick to achieve this behavior:

import sys

class MyModule(sys.modules[__name__].__class__):
    def __call__(self):
        print("Messing up things...")

sys.modules[__name__].__class__ = MyModule

This works by dynamically replacing the module's __class__ at runtime. But who wants to copy-paste this boilerplate every time?

Enter Cadule

To avoid repeating this boilerplate, I've encapsulated this simple mechanism into a package called Cadule (short for Callable [Mo]dule Less).

Installation

pip install cadule

Usage

Create a file called mess_up_things.py:

import cadule

@cadule
def __call__():
    print("Messing up things...")

Then in your Python REPL or another script:

>>> import mess_up_things
>>> mess_up_things()
Messing up things...
>>> callable(mess_up_things)
True

That's it! The entire mess_up_things module is now a callable object. When you call it, it executes the decorated __call__ function.

You can also pass arguments and return values:

import cadule

@cadule
def __call__(target):
    return f"Messing up {target}!"

>>> import mess_up_things
>>> mess_up_things("the database")
'Messing up the database!'

When to Use It

Cadule is particularly useful for:

Single-purpose modules: When a module's main purpose is to expose one function
DSL and fluent interfaces: Creating more natural-looking APIs
Scripts and utilities: Making command-line tools more intuitive

Github: https://github.com/aisk/cadule

Bringing timeout to macOS Without Installing All of GNU Coreutils

Maple — Sun, 21 Sep 2025 07:21:11 +0000

Not long ago, I was writing a shell script on macOS and ran into a small but surprising issue: there was no built-in timeout command. If you’ve spent time on Linux, you’ve probably taken timeout for granted, it’s part of GNU coreutils and is incredibly handy when you want to limit how long a command can run.

On macOS, though, the situation is different. macOS ships with a BSD-flavored set of core utilities, and GNU’s version of timeout simply isn’t there. My first instinct was to install GNU coreutils through Homebrew:

brew install coreutils

This does work—but it comes with a catch. To avoid conflicts with the BSD commands that ship with macOS (like ls and cat), Homebrew installs GNU coreutils under names prefixed with a g. So instead of ls, you get gls; instead of timeout, you get gtimeout.

That’s fine if you’re working in a personal environment, but it creates headaches for writing portable shell scripts. If I write a script that calls gtimeout on macOS, it won’t run out-of-the-box on Linux, where the command is just timeout. Homebrew does provide a way to remove the g prefix, but that’s a pretty heavy-handed solution—suddenly your system’s default ls, cat, and other tools are replaced by GNU versions, which can break expectations in subtle ways.

So, instead of going down that path, I decided to build a standalone timeout command that behaves like GNU’s version but doesn’t bring along the entire coreutils package. This way, you can install just what you need without worrying about side effects.

The project is open source and lives here:
👉 https://github.com/aisk/timeout

And to make installation easier, I also set up a Homebrew tap. You can install it directly with:

brew install aisk/homebrew-tap/timeout

That’s it—you’ll get a drop-in replacement for timeout, without the g prefix, and without swapping out your other system tools.

I built this mainly to solve my own problem, but if it helps you too, I’d really appreciate a star on the GitHub repo. Every bit of support means a lot and helps me keep the project alive.

Build and Modify Linux System Image for C-sky based Gx6605s Board

Maple — Sun, 11 Aug 2024 12:02:03 +0000

The Gx6605s is a very cheap development board (39 Chinese Yuan with free shipping), which has a C-sky instruction set based CPU. The support for Linux kernel, GCC, and even Greenlet, is upstreamed.

I have a Gx6605s board which I bought years ago, and I only tried to run it with C-sky's official system image. It's a Buildroot-based Linux system, and there is no package manager for it. I can't install more packages / software on it, thus it is not useful for me, so I quickly lost interest in it.

When I found it in a box after moving to another city, I thought maybe I could do something with it, so I decided to give it a try.

But sadly, the company behind the development of the dev board and instruction set has abandoned the development for the dev board and C-sky instructions, and has continued their work on RiscV.

They have a Buildroot fork on GitLab which can produce the root file system for the image, but the support for this board and C-sky instruction set was dropped some time ago. Now this repo can't produce a system image for Gx6605s.

I made a dig into the repo and found that there is a branch called master_backup, which was once their development branch capable of building C-sky CPU based system images. The build processes were run on GitLab Pipeline. So, you can fork this repo, and then run the GitLab Pipeline on the web page to get the generated system image.

But unfortunately, there is a file that Gx6605s Buildroot depended on, hosted at https://github.com/c-sky/tools, which has been deleted and changed to a new unrelated repo. Luckily, I found a mirror site that has this repo, so you can just apply this patch to get the file:

diff --git a/package/csky-debug/csky-debug.mk b/package/csky-debug/csky-debug.mk
index 241755019e..a318247ebf 100644
--- a/package/csky-debug/csky-debug.mk
+++ b/package/csky-debug/csky-debug.mk
@@ -6,7 +6,7 @@

 CSKY_DEBUG_VERSION = V4.2.0-tmp-20170411
 CSKY_DEBUG_SOURCE = DebugServerConsole-linux-x86_64-$(CSKY_DEBUG_VERSION).tar.gz
-CSKY_DEBUG_SITE = https://github.com/c-sky/tools/raw/master
+CSKY_DEBUG_SITE = https://isrc.iscas.ac.cn/gitlab/mirrors/github.com/c-sky_tools/-/raw/master

 define HOST_CSKY_DEBUG_INSTALL_CMDS
        mkdir -p $(HOST_DIR)/csky-debug

With this, you can build a system image for the Gx6605s board, and it's a little newer than the one provided on the C-sky official site. However, I want to modify the system image by adding more packages, such as MicroPython and even a GCC compiler. Therefore, I need to build it locally.

Take a look at the .gitlab-ci.yml. I believe it's using a Docker image called maohan001/ubuntu-buildroot as the building environment. Please note that since they dropped support for the C-sky instruction set, if you want to build the image in the future, please pull and backup this image. It's not Dockerfile-based, so we don't know how to reproduce it.

I've never used Buildroot before, but from the GitLab Pipeline's log and the .gitlab-ci.yml, I assume one should run make {config-name} inside the Docker image with the buildroot root path to create a configuration for the specified development board. Then, run make to download all necessary files and build the compiler, kernel, libc, and userland.

So, for the Gx6605s, we should use $ make csky_610_gx6605s_4.9_uclibc_br_defconfig, and then $ make. You will get a usb.img.xz in the output/images folder. This should be exactly what you got in the GitLab Pipeline.

And as the Buildroot's official website says, now we can run $ make menuconfig to customize the build process, such as adding MicroPython to the system.