Forem: Egregors

PassKey in Go

Egregors — Sun, 25 Feb 2024 11:56:41 +0000

😅 What?

In this article, we are implementing full-working auth flow by WebAuthn / PassKey mechanism. We gonna use Go and vanilla JS with minimal amount of dependencies.

🤦‍♀️ Why?

You can easily find a few pretty good articles about WebAuthn | PassKey. One of them has a lot of details and solution example on node.js. I recommend checking it out first.

In this post, I'd like to tell about the implementation PassKey auth on a particular stack: Go + vanilla JS. We will make a backend of top of webauthn go lib, add a simple web page for registration | login, HTTP server to serve static and provide PassKey API.

A code tells us mach more, right?

TLDR; https://github.com/egregors/go-passkey

🧑‍💻 Implementation

So, in general we want to make a tiny website, which allow us to sign up new user with only username and PassKey and login with the same creds.

For backend, I gonna use go (go1.21.7) with the only two dependencies:

github.com/go-webauthn/webauthn – default and looks like the only lib for webauthnon go
github.com/google/uuid – UUID provider, we will need it to generate session keys. Totally optional

We're going to implement a web server to serve static (index.html, js, css) and API to provide backend part of auth process.

The frontend will be just a simple HTML form with username input and Registration and Login buttons. Client side of webauthn will represents in just a few JavaScript functions.

– What? But... but we need to use React even for absolutely not suitable problems...
– No, we don't.

It will also be a few dependencies:

https://simplewebauthn.dev/docs/packages/browser – JS lib to use WebAuthn browser API
https://getbootstrap.com/docs/5.0 – just to save time

🏛️ Architecture

Registration

On a high level, the whole process does not seem very complicated.

First, we ask username and send it to backend. In BeginRegistration API endpoint, we are trying to get existing user or create a new one. Here we call webAuthn.BeginRegistration to get auth options and sessions data. Both contain Challenge which should be signed by authenticator. Create a new session, put it with a session data from webAuthn to the store. And send options back to client.

On a client, we got an auth options and now ready to communicate with browser WebAuthn API. Here we are using JS lib and call SimpleWebAuthnBrowser.startRegistration (inside register function). The lib asks the authenticator to create a new Passkey. Authenticator generates new key pair and provides attestationResponse. Attestation contains credential information and signed Challenge. Now we need just forward this attestationResponse to backend, by calling FinishRegistration endpoint.

On a backend side we just get session key from headers, with session information we can get User. After that we should provide user, session and attestation result for validation into webAuthn. If signature is correct and all other validation are passed, we'll get Credential (public key and some meta) of current user. Save it to the store and clear the session. Well done!

Login

It may not be obvious, but the login process looks almost the same as the registration process. The only difference here is we don't ask authenticator to create a new keys pair before signing the challenge. Let's just to implement it and you're going to see it be yourself.

🎒 Backend

Before we start making API, we need to provide required dependencies. To deal with webAuthn we need a data store and webAuthn compatible User models.

type PasskeyUser interface {  
   webauthn.User  
   AddCredential(*webauthn.Credential)  
   UpdateCredential(*webauthn.Credential)  
}  

type PasskeyStore interface {  
   GetUser(userName string) PasskeyUser  
   SaveUser(PasskeyUser)  
   GetSession(token string) webauthn.SessionData  
   SaveSession(token string, data webauthn.SessionData)  
   DeleteSession(token string)  
}

Implementation of these stuff is not a main topic here, so let's skip it. (You always can find the whole code on GitHub: https://github.com/egregors/go-passkey?tab=readme-ov-file)

We are starting from creating webauthn backend and setting up the server:
./main.go

package main  

import (  
   "encoding/json"  
   "fmt"   
   "log"   
   "net/http"   
   "os"  

   "github.com/go-webauthn/webauthn/webauthn"   
   "github.com/google/uuid"
)  

var (  
   webAuthn *webauthn.WebAuthn  
   err      error  

   datastore PasskeyStore  
   l         Logger  
)

func main() {  
   l = log.Default()  

   proto := getEnv("PROTOCOL", "http")  
   host := getEnv("HOST", "localhost")  
   port := getEnv("PORT", ":8080")  
   origin := fmt.Sprintf("%s://%s%s", proto, host, port)  

   l.Printf("[INFO] make webauthn config")  
   wconfig := &webauthn.Config{  
      RPDisplayName: "Go Webauthn",    // Display Name for your site  
      RPID:          host,             // Generally the FQDN for your site  
      RPOrigins:     []string{origin}, // The origin URLs allowed for WebAuthn  
   }  

   l.Printf("[INFO] create webauthn")  
   if webAuthn, err = webauthn.New(wconfig); err != nil {  
      fmt.Printf("[FATA] %s", err.Error())  
      os.Exit(1)  
   }  

   l.Printf("[INFO] create datastore")  
   datastore = NewInMem(l)  

   l.Printf("[INFO] register routes")  
   // Serve the web files  
   http.Handle("/", http.FileServer(http.Dir("./web")))  

   // Add auth the routes  
   http.HandleFunc("/api/passkey/registerStart", BeginRegistration)  
   http.HandleFunc("/api/passkey/registerFinish", FinishRegistration)  
   http.HandleFunc("/api/passkey/loginStart", BeginLogin)  
   http.HandleFunc("/api/passkey/loginFinish", FinishLogin)  

   // Start the server  
   l.Printf("[INFO] start server at %s", origin)  
   if err := http.ListenAndServe(port, nil); err != nil {  
      fmt.Println(err)  
   }  
}

// getEnv is a helper function to get the environment variable
func getEnv(key, def string) string {  
   if value, exists := os.LookupEnv(key); exists {  
      return value  
   }  

   return def  
}

As you see, here we create a webAuthn instance and add 5 http handlers:

/ – going to serve static files from ./web: index.html, css and script.js
/api/passkey/registerStart – get username from client, send auth options back
/api/passkey/registerFinish – get new public key and attestation from client, sent validation result
/api/passkey/loginStart – get username, send auth options back
/api/passkey/loginFinish – get attestation from client, sent validation

Each of Start | Finish hanlder look simular:

./main.go

func BeginRegistration(w http.ResponseWriter, r *http.Request) {  
   l.Printf("[INFO] begin registration ----------------------\\")  

   username, err := getUsername(r)  
   if err != nil {  
      l.Printf("[ERRO] can't get user name: %s", err.Error())  
      panic(err)  
   }  

   user := datastore.GetUser(username) // Find or create the new user  

   options, session, err := webAuthn.BeginRegistration(user)  
   if err != nil {  
      msg := fmt.Sprintf("can't begin registration: %s", err.Error())  
      l.Printf("[ERRO] %s", msg)  
      JSONResponse(w, "", msg, http.StatusBadRequest)  

      return  
   }  

   // Make a session key and store the sessionData values  
   t := uuid.New().String()  
   datastore.SaveSession(t, *session)  

   JSONResponse(w, t, options, http.StatusOK) // return the options generated with the session key  
   // options.publicKey contain our registration options
}  

func FinishRegistration(w http.ResponseWriter, r *http.Request) {  
   // Get the session key from the header  
   t := r.Header.Get("Session-Key")  
   // Get the session data stored from the function above  
   session := datastore.GetSession(t) // FIXME: cover invalid session  

   // In out example username == userID, but in real world it should be different   user := datastore.GetUser(string(session.UserID)) // Get the user  

   credential, err := webAuthn.FinishRegistration(user, session, r)  
   if err != nil {  
      msg := fmt.Sprintf("can't finish registration: %s", err.Error())  
      l.Printf("[ERRO] %s", msg)  
      JSONResponse(w, "", msg, http.StatusBadRequest)  

      return  
   }  

   // If creation was successful, store the credential object  
   user.AddCredential(credential)  
   datastore.SaveUser(user)  
   // Delete the session data  
   datastore.DeleteSession(t)  

   l.Printf("[INFO] finish registration ----------------------/")  
   JSONResponse(w, "", "Registration Success", http.StatusOK) // Handle next steps  
}  

func BeginLogin(w http.ResponseWriter, r *http.Request) {  
   l.Printf("[INFO] begin login ----------------------\\")  

   username, err := getUsername(r)  
   if err != nil {  
      l.Printf("[ERRO]can't get user name: %s", err.Error())  
      panic(err)  
   }  

   user := datastore.GetUser(username) // Find the user  

   options, session, err := webAuthn.BeginLogin(user)  
   if err != nil {  
      msg := fmt.Sprintf("can't begin login: %s", err.Error())  
      l.Printf("[ERRO] %s", msg)  
      JSONResponse(w, "", msg, http.StatusBadRequest)  

      return  
   }  

   // Make a session key and store the sessionData values  
   t := uuid.New().String()  
   datastore.SaveSession(t, *session)  

   JSONResponse(w, t, options, http.StatusOK) // return the options generated with the session key  
   // options.publicKey contain our registration options
}  

func FinishLogin(w http.ResponseWriter, r *http.Request) {  
   // Get the session key from the header  
   t := r.Header.Get("Session-Key")  
   // Get the session data stored from the function above  
   session := datastore.GetSession(t) // FIXME: cover invalid session  

   // In out example username == userID, but in real world it should be different   user := datastore.GetUser(string(session.UserID)) // Get the user  

   credential, err := webAuthn.FinishLogin(user, session, r)  
   if err != nil {  
      l.Printf("[ERRO] can't finish login %s", err.Error())  
      panic(err)  
   }  

   // Handle credential.Authenticator.CloneWarning  
   if credential.Authenticator.CloneWarning {  
      l.Printf("[WARN] can't finish login: %s", "CloneWarning")  
   }  

   // If login was successful, update the credential object  
   user.UpdateCredential(credential)  
   datastore.SaveUser(user)  
   // Delete the session data  
   datastore.DeleteSession(t)  

   l.Printf("[INFO] finish login ----------------------/")  
   JSONResponse(w, "", "Login Success", http.StatusOK)  
}  

// JSONResponse is a helper function to send json responsefunc JSONResponse(w http.ResponseWriter, sessionKey string, data interface{}, status int) {  
   w.Header().Set("Content-Type", "application/json")  
   w.Header().Set("Session-Key", sessionKey)  
   w.WriteHeader(status)  
   _ = json.NewEncoder(w).Encode(data)  
}  

// getUsername is a helper function to extract the username from json requestfunc getUsername(r *http.Request) (string, error) {  
   type Username struct {  
      Username string `json:"username"`  
   }  
   var u Username  
   if err := json.NewDecoder(r.Body).Decode(&u); err != nil {  
      return "", err  
   }  

   return u.Username, nil  
}

And... in fact, all the work on the server side that needed to be done.

👨‍🎨 Frontend

For frontend part we need first of all HTML page
./web/index.html

<!DOCTYPE html>  
<html lang="en">  
<head>  
    <meta charset="UTF-8">  
    <meta name="viewport" content="width=device-width, initial-scale=1.0">  
    <title>Passkey</title>  
    <link href="bootstrap.min.css" rel="stylesheet">  
</head>  
<body>  

<div class="container d-flex justify-content-center align-items-center vh-100">  
    <div class="bg-light p-5 rounded w-50">  
        <h1 class="mb-4 text-center">🔑 Passkey</h1>  
        <div class="text-center" id="message"></div>  
        <div class="mb-3">  
            <input type="text" class="form-control" id="username" placeholder="username">  
        </div>        
        <div class="d-grid gap-2">  
            <div class="row">  
                <div class="col">  
                    <button class="btn btn-primary w-100" id="registerButton">Register</button>  
                </div>                
                <div class="col">  
                    <button class="btn btn-primary w-100" id="loginButton">Login</button>  
                </div>            
            </div>        
        </div>    
    </div>
</div>  

<script src="index.es5.umd.min.js"></script>  
<script src="script.js"></script>  
</body>  
</html>

Here we just make a simple "form" with username input, two buttons and place to messages. I use bootstrap ccs here to make the form a bit prettier and index.es5.umd.min.js – js lib for working with browser API. We do not use here any other frameworks. Just vanilla JS and SimpleWebAuthnBrowser lib.

All the magic will be inside script.js. Just kidding, there is no magic here at all.
./web/script.js

document.getElementById('registerButton').addEventListener('click', register);  
document.getElementById('loginButton').addEventListener('click', login);  


function showMessage(message, isError = false) {  
    const messageElement = document.getElementById('message');  
    messageElement.textContent = message;  
    messageElement.style.color = isError ? 'red' : 'green';  
}  

async function register() {  
    // Retrieve the username from the input field  
    const username = document.getElementById('username').value;  

    try {  
        // Get registration options from your server. Here, we also receive the challenge.  
        const response = await fetch('/api/passkey/registerStart', {  
            method: 'POST', headers: {'Content-Type': 'application/json'},  
            body: JSON.stringify({username: username})  
        });  
        console.log(response)  

        // Check if the registration options are ok.  
        if (!response.ok) {  
            const msg = await response.json();  
            throw new Error('User already exists or failed to get registration options from server: ' + msg);  
        }  

        // Convert the registration options to JSON.  
        const options = await response.json();  
        console.log(options)  

        // This triggers the browser to display the passkey / WebAuthn modal (e.g. Face ID, Touch ID, Windows Hello).  
        // A new attestation is created. This also means a new public-private-key pair is created.        
        const attestationResponse = await SimpleWebAuthnBrowser.startRegistration(options.publicKey);  

        // Send attestationResponse back to server for verification and storage.  
        const verificationResponse = await fetch('/api/passkey/registerFinish', {  
            method: 'POST',  
            headers: {  
                'Content-Type': 'application/json',  
                'Session-Key': response.headers.get('Session-Key')  
            },  
            body: JSON.stringify(attestationResponse)  
        });  


        const msg = await verificationResponse.json();  
        if (verificationResponse.ok) {  
            showMessage(msg, false);  
        } else {  
            showMessage(msg, true);  
        }  
    } catch  
        (error) {  
        showMessage('Error: ' + error.message, true);  
    }  
}  

async function login() {  
    // Retrieve the username from the input field  
    const username = document.getElementById('username').value;  

    try {  
        // Get login options from your server. Here, we also receive the challenge.  
        const response = await fetch('/api/passkey/loginStart', {  
            method: 'POST', headers: {'Content-Type': 'application/json'},  
            body: JSON.stringify({username: username})  
        });  
        // Check if the login options are ok.  
        if (!response.ok) {  
            const msg = await response.json();  
            throw new Error('Failed to get login options from server: ' + msg);  
        }  
        // Convert the login options to JSON.  
        const options = await response.json();  
        console.log(options)  

        // This triggers the browser to display the passkey / WebAuthn modal (e.g. Face ID, Touch ID, Windows Hello).  
        // A new assertionResponse is created. This also means that the challenge has been signed.        
        const assertionResponse = await SimpleWebAuthnBrowser.startAuthentication(options.publicKey);  

        // Send assertionResponse back to server for verification.  
        const verificationResponse = await fetch('/api/passkey/loginFinish', {  
            method: 'POST',  
            headers: {  
                'Content-Type': 'application/json',  
                'Session-Key': response.headers.get('Session-Key'),  
            },  
            body: JSON.stringify(assertionResponse)  
        });  

        const msg = await verificationResponse.json();  
        if (verificationResponse.ok) {  
            showMessage(msg, false);  
        } else {  
            showMessage(msg, true);  
        }  
    } catch (error) {  
        showMessage('Error: ' + error.message, true);  
    }  
}

🤔 What next?

So, now we know how to register and login users by passKey, but is it a complete solution? Of course not!

Session processing are simplified to maintain low complicity level (session key could be easily stolen)
Store is just inmem struct with a few maps (thread unsafe!)
We didn't provide any middleware to actually use authentication (some public and some private routes)

Besides, we left here a pair of fascinating question:

How to allow user to have several passkeys associated with one account?
What should we do if credential.Authenticator.CloneWarning is true?
It would be nice to have some sort of middleware to handle User status.

📚 Reference

Serialize and Deserialize Binary Tree

Egregors — Mon, 31 Jan 2022 11:35:07 +0000

What?

A binary tree is a tree data structure in which each node has at most two children. It could be (and it is!) pretty useful in many ways.

In this article, we gonna try to serialize and deserialize binary trees using Golang.

Why?

The original purpose is quite prosaic: a bunch of binary trees problems on LeetCode requires some testing. However, the definition of trees “by hand” is so annoying. So, to use the original LeetCode input format, we gonna make our own serialize \ deserialize package.

How?

Let's start with a TreeNode definition. It's going to be a node with Int value, but you may use any type you need here.

type TreeNode struct {
    Val   int
    Left  *TreeNode
    Right *TreeNode
}

It's basically all we need to start building trees. We'll take a simple tree, just for example:

To make it in a code, we should create a root node and define all internal nodes recursively:

root := &TreeNode{
    Val: 1,
    Left: &TreeNode{
        Val:   2,
        Left:  nil,
        Right: nil,
    },
    Right: &TreeNode{
        Val: 3,
        Left: &TreeNode{
            Val:   4,
            Left:  nil,
            Right: nil,
        },
        Right: &TreeNode{
            Val:   5,
            Left:  nil,
            Right: nil,
        },
    },
}

Looks a bit messy, and it's super annoying to annotate trees like this one by your hands. It could be one of the many reasons you want to implement serialize \ deserialize for your data.

Serialize

First, we want to find a way to make a useful representation of trees. Serialization generally is a process of encoding some data into byte progression. When we got how to do this, we'll can store trees like a string-data, for example for tests or for transporting trees between programs through the Web.

Level Order Binary Tree Traversal

As far as we want to support LeetCode binary trees format, we should serialize it “line by line”.

We can do this by using Level Order Binary Tree Traversal which is one of the ways to use Breadth first search algorithm.

The main idea is to go through the tree “line by line” and accumulate the result of each line traversal.

We could do this recursively with a simple queue approach. So, first, let's define a queue.

type NodeQueue []*TreeNode

func (q *NodeQueue) IsEmpty() bool           { return len(*q) == 0 }
func (q *NodeQueue) Push(nodes ...*TreeNode) { *q = append(*q, nodes...) }
func (q *NodeQueue) Pop() *TreeNode {
    if !q.IsEmpty() {
        n := (*q)[0]
        *q = (*q)[1:]
        return n
    }
    return nil
}

We want to collect our nodes level by level. That means we should be able:

Push a node in the queue (to make it a bit more convenient, let's allow to push a few nodes at a time);
Pop nodes from the queue;
know if the queue IsEmpty.

Next, we're going to write a recursive bfs function to collect values of all nodes “line by line”.

const EmptyNodeMark = "null"

func bfs(q *NodeQueue) []string {
    if q.IsEmpty() {
        return nil
    }

    var (
        nextQ        NodeQueue
        level        []string
    )

    for !q.IsEmpty() {
        n := q.Pop()
        if n != nil {
            level = append(level, strconv.Itoa(n.Val))
            nextQ.Push(n.Left, n.Right)
        } else {
            level = append(level, EmptyNodeMark)
        }
    }

    return append(level, bfs(&nextQ)...)
}

As usual, when we are dealing with a recursive function, we start with a terminator. In this case, we would like to interrupt calls if our queue is empty.

Next, we have two main goals for each call:

collect values of all nodes in the current queue (current level);
build a next queue for the next iteration (next level).

The initial call of bfs will be with a queue that contains just root of the tree. In our example, it's node 1.

So, we just pop a node from the current queue and if it is not empty, we append its value into level slice.

Next, we push children of all nodes from the current queue into nextQ slice. For node 1, it will be nodes 2 and 3.

When the current queue q becomes empty, we can take the next step and repeat the whole process for the nextQ.

Thus, our current queue is [2, 3] and our result accumulator is "1". After the next iteration, the next queue going to be [nil, nil, 4, 5] and the resulting accumulator – ["1", "2", "3"].

And so on and so forth…

But there is a problem, independently of tree shape the last level will always contain only "null" values. In our example, it's [ nil, nil, nil, nil ].

We shouldn't include any unnecessary redundant data in the final result, especially when we are talking about serialization. Let's little rework our bfs.

We want to detect “the last level” and interrupt calls at this place, without including useless parts of data.

const EmptyNodeMark = "null"

func bfs(q *NodeQueue) []string {
    var (
        nextQ        NodeQueue
        level        []string
        isEmptyLevel = true
    )

    for !q.IsEmpty() {
        n := q.Pop()
        if n != nil {
            level = append(level, strconv.Itoa(n.Val))
            nextQ.Push(n.Left, n.Right)
            isEmptyLevel = false
        } else {
            level = append(level, EmptyNodeMark)
        }
    }

    if isEmptyLevel {
        return nil
    }

    return append(level, bfs(&nextQ)...)
}

Ok, looks like this is generally all we need to serialize the tree. Now we can implement Stringer interface for TreeNode.

const (
    EmptyNodeMark = "null"
    Separator     = ","
)

func (t TreeNode) String() string { return t.serialize() }

func (t TreeNode) serialize() string {
    data := bfs(&NodeQueue{&t})

    // remove redundant nulls
    i := len(data) - 1
    for data[i] == EmptyNodeMark {
        i--
    }

    return fmt.Sprintf("[%s]", strings.Join(data[:i+1], Separator))
}

Here in serialize() method, we just concatenate values of all nodes with comma separator.

Deserialize

Since we are done with serialization, we need to do the opposite. Deserializing gonna be a bit more tricky, but the main idea is still the same.

First, we need to prepare our serialized data to build an actual tree. Serialized representation of the tree from the example is "[1,2,3,null,null,4,5]". Let's unwrap /s'up Rust fellows! ;) / brackets and build a string slice.

nodes := strings.Split(
    strings.TrimSuffix(strings.TrimPrefix(data, "["), "]"),
    Separator,
)

For now, we got a string slice as an input, and we need to build a whole tree from it.

As a first step, we create root node by hand, using the head of data slice like a root value. Next, we gonna move through data slice tail and build the tree recursively. Here is still the same BFS algorithm with a queue.

const EmptyNodeMark = "null"

func bfsBuild(q *NodeQueue, data []string) error {
    if len(data) == 0 || q == nil {
        return nil
    }

    var nextQ NodeQueue

    for !q.IsEmpty() {
        n := q.Pop()
        if n != nil {
            // if the data tail of current level contains only nulls, they could be reduced.
            // that means, if the data becomes empty earlier than level does, there is no more nodes
            if len(data) == 0 {
                return nil
            }
            l, r := data[0], data[1]
            data = data[2:]

            if l != EmptyNodeMark {
                if lVal, lErr := strconv.Atoi(l); lErr == nil {
                    n.Left = &TreeNode{Val: lVal}
                } else {
                    return lErr
                }
            }

            if r != EmptyNodeMark {
                if rVal, rErr := strconv.Atoi(r); rErr == nil {
                    n.Right = &TreeNode{Val: rVal}
                } else {
                    return rErr
                }
            }

            nextQ.Push(n.Left, n.Right)
        }
    }

    return bfsBuild(&nextQ, data)
}

When we fetched the first value from the data slice, the length of this slice must be always even. Because of in a binary tree and all non-nil nodes guaranteed to have two children (including nil-nodes). So each iteration we are creating children for all non-nil nodes in the queue, and extracting for this purpose len(q) * 2 elements from the data slice. Until the data become empty.

That is it! Now we can merge data parsing and tree building functions in TreeNode constructor.

func NewTreeNode(data string) (*TreeNode, error) {
    if len(data) < 2 {
        return nil, errors.New("invalid input")
    }
    nodes := strings.Split(
        strings.TrimSuffix(strings.TrimPrefix(data, "["), "]"),
        Separator,
    )
    rootVal, err := strconv.Atoi(nodes[0])
    if err != nil {
        return nil, err
    }

    root := &TreeNode{Val: rootVal}
    err = bfsBuild(&NodeQueue{root}, nodes[1:])
    if err != nil {
        return nil, err
    }
    return root, nil
}

TreeNode package

Needless to say, you could find all this code in the repo: https://github.com/egregors/TreeNode

And moreover, you can use this package as a dependency to deal with LeetCode binary tree problems, or whatever you want.

Your first Stack project (build, test, dist)

Egregors — Thu, 30 Jan 2020 02:21:04 +0000

01 – VS Code for Haskell in 2020
02 – Your first Stack project (build, test, dist)

Stack – Haskell build tool-set

Despite conventional wisdom that Haskell is an academic-first language, there exist powerful production-ready build tools. The most common and useful for my opinion tool-set is Stack. Check previous post out to install stack and setup SV Code for development.

In this post, we'll try to implement a pretty simple project with Stack.

New Stack project

First of all, we need to init our awesome project using a new command: The stack new command will create a new directory containing all the needed files to start a project correctly.

Init from template

Stack new command creates a project skeleton according to some template. For our tiny project, we gonna use the default simple template:

stack new addStrInts

Now, you should see something like:

➜  addStrInts git:(master) ✗ ls
ChangeLog.md     README.md        addStrInts.cabal package.yaml     stack.yaml
LICENSE          Setup.hs         app              src              test

File structure

So, we got all the necessary files to start developing. Let's take a look at the most interesting stuff Stack created for us.

LICENSE – license according to Stack template (BSD3 by default)
addStrInts.cabal – project build config, we'll make a few changes here soon
app – folder with the application entry point
src – literally place for most of your code
test – folder for QuickCheck props test

The most important file here is addStrInts.cabal. This is the build configuration. Maintainer info, GHC version, dependencies, compiler options, etc. All of this could be found here.

For now, let's just update description, homepage, bug-reports and author, maintainer fields. Just put your GitHub user and Name into it.

Before we a going to add some code, let's check: is our project even compiles. For this purpose run stack setup and stack build (or, if you use VS Code, just press Stack Build button in the bottom). If you see the output like this — the project was built successfully

/Users/egregors/Documents/GitHub/addStrInts/addStrInts.cabal was modified manually. Ignoring /Users/egregors/Documents/GitHub/addStrInts/package.yaml in favor of the cabal file.
If you want to use the package.yaml file instead of the cabal file,
then please delete the cabal file.
Building all executables for `addStrInts' once. After a successful build of all of them, only specified executables will be rebuilt.
addStrInts> build (lib + exe)
Preprocessing library for addStrInts-0.1.0.0..
Building library for addStrInts-0.1.0.0..
[1 of 2] Compiling Lib
[2 of 2] Compiling Paths_addStrInts
Preprocessing executable 'addStrInts-exe' for addStrInts-0.1.0.0..
Building executable 'addStrInts-exe' for addStrInts-0.1.0.0..
[1 of 2] Compiling Main
[2 of 2] Compiling Paths_addStrInts
Linking .stack-work/dist/x86_64-osx/Cabal-2.4.0.1/build/addStrInts-exe/addStrInts-exe ...
addStrInts> copy/register
Installing library in /Users/egregors/Documents/GitHub/addStrInts/.stack-work/install/x86_64-osx/38556cea096b692240464d8e9f5f4a8fb0069d37b484d3266c298211dcc2a5e4/8.6.5/lib/x86_64-osx-ghc-8.6.5/addStrInts-0.1.0.0-2sRMucrO0w0Df0SlAhTLCI
Installing executable addStrInts-exe in /Users/egregors/Documents/GitHub/addStrInts/.stack-work/install/x86_64-osx/38556cea096b692240464d8e9f5f4a8fb0069d37b484d3266c298211dcc2a5e4/8.6.5/bin
Registering library for addStrInts-0.1.0.0..

Add Str Ints implementation

So, let's add some code! We wanna write a program which will be asking a few numbers from the user, and prints sum of them (yep, real-world Haskell app)

Let's start by making a few pure functions for typecast and calculate sum, next we'll add some tests, and finally, add one IO function for interaction with the user.

And Stack will help us with all this stuff.

Lib's code

All our "business" code we'll put in the StrAdd module, so let's create file StrAdd.hs in the src directory. You may delete Lib.hs, we don't need it anyway.

But now you should add the new dependency in our addStrInts.cabal file. Go to the library path, and replace Libs by AddStr.
To avoid build errors, edit app/Main.hs:

module Main where

main :: IO ()
main = undefined

Let's start with helpers. We will get strings as input, and we need to be sure all of the chars in the string are numbers.

module StrAdd where

import           Data.Char

isAllDigits :: String -> Bool
isAllDigits val = all (== True)
  $ map (\x -> x `elem` ['1', '2', '3', '4', '5', '6', '7', '8', '9']) val

To play around with our first function we should run the ghci session. Run stack ghci --ghci-options StrAdd.hs in terminal to load StrAdd.hs code and try to test isAllDigits function (or press Load GHCi if you use VS Code):

Loaded GHCi configuration from /private/var/folders/sk/jzr1583n0vs6zb05b0gb7hw40000gn/T/haskell-stack-ghci/9469312f/ghci-script
[1 of 1] Compiling StrAdd           ( StrAdd.hs, interpreted )
Ok, one module loaded.
*StrAdd> isAllDigits "1234"
True
*StrAdd> isAllDigits "4st"
False
*StrAdd> isAllDigits "123_5"
False

Looks good (no)! So, time to add some tests! Let's go into test/Spec.hs
Now this file contains stub:

main :: IO ()
main = putStrLn "Test suite not yet implemented"

in Spec.hs. To check test runner works properly, let's try run stack test.

You should see something like:

➜  src git:(master) ✗ stack test
/Users/egregors/Documents/GitHub/addStrInts/addStrInts.cabal was modified manually. Ignoring /Users/egregors/Documents/GitHub/addStrInts/package.yaml in favor of the cabal file.
If you want to use the package.yaml file instead of the cabal file,
then please delete the cabal file.
addStrInts-0.1.0.0: unregistering (local file changes: addStrInts.cabal)
addStrInts> configure (lib + exe + test)
Configuring addStrInts-0.1.0.0...
addStrInts> build (lib + exe + test)
Preprocessing library for addStrInts-0.1.0.0..
Building library for addStrInts-0.1.0.0..
Preprocessing test suite 'addStrInts-test' for addStrInts-0.1.0.0..
Building test suite 'addStrInts-test' for addStrInts-0.1.0.0..
Preprocessing executable 'addStrInts-exe' for addStrInts-0.1.0.0..
Building executable 'addStrInts-exe' for addStrInts-0.1.0.0..
addStrInts> copy/register
Installing library in /Users/egregors/Documents/GitHub/addStrInts/.stack-work/install/x86_64-osx/38556cea096b692240464d8e9f5f4a8fb0069d37b484d3266c298211dcc2a5e4/8.6.5/lib/x86_64-osx-ghc-8.6.5/addStrInts-0.1.0.0-2sRMucrO0w0Df0SlAhTLCI
Installing executable addStrInts-exe in /Users/egregors/Documents/GitHub/addStrInts/.stack-work/install/x86_64-osx/38556cea096b692240464d8e9f5f4a8fb0069d37b484d3266c298211dcc2a5e4/8.6.5/bin
Registering library for addStrInts-0.1.0.0..
addStrInts> test (suite: addStrInts-test)

Progress 1/2: addStrIntsTest suite not yet implemented

addStrInts> Test suite addStrInts-test passed
Completed 2 action(s).

It’s time to add some tests.

Tests

First, let's try silly way. We'll add few test functions into Spec.hs:

import           StrAdd

main :: IO ()
main = do
  -- quickCheck prop_isAllDigit
  putStrLn ""
  putStrLn $ if isAllDigits "123" then "OK" else "FAIL!"
  putStrLn $ if not $ isAllDigits "4st" then "OK" else "FAIL!"
  putStrLn $ if not $ isAllDigits "123_4" then "OK" else "FAIL!"
  return ()

Now, just run stack test or press Stack Test button in the VS Code.

You should get smth like:

...

Progress 1/2: addStrInts
OK
OK
OK

addStrInts> Test suite addStrInts-test passed
...

Looks ok, but writing test this way is too boring and inefficient. And, obviously, it's hard to cover quite a few cases. That is why in Haskell we usually write property tests.

Let's take a look at the QuickCheck. The main idea is that you need to describe QuickCheck a set of the properties your function should have, and QuickCheck will automatically generate a bunch of testing data for this function.

Let's try to rewrite our test, but first, we need to add a new dependency. Go to addStrInts.cabal, test-suite addStrInts-test part and add QuickCheck to build-depends field:

...
test-suite addStrInts-test
  type: exitcode-stdio-1.0
  main-is: Spec.hs
  other-modules:
      Paths_addStrInts
  hs-source-dirs:
      test
  ghc-options: -threaded -rtsopts -with-rtsopts=-N
  build-depends:
      addStrInts
    , base >=4.7 && <5
    , QuickCheck
  default-language: Haskell2010

Now, we can use QuickCheck in our test. So, let's say if isAllDigit is true and it's not an empty string, then the length of the original string must be the equal string after isDigit filter:

import           StrAdd
import           Data.Char
import           Test.QuickCheck

prop_isAllDigit :: String -> Bool
prop_isAllDigit val = if isAllDigits val || val == ""
  then onlyDigit == length val
  else onlyDigit /= length val
  where onlyDigit = length $ filter isDigit val

main :: IO ()
main = do
  quickCheck prop_isAllDigit
  putStrLn "Done"

Now, run the test stack test:

➜  src git:(master) ✗ stack test
/Users/egregors/Documents/GitHub/addStrInts/addStrInts.cabal was modified manually. Ignoring /Users/egregors/Documents/GitHub/addStrInts/package.yaml in favor of the cabal file.
If you want to use the package.yaml file instead of the cabal file,
then please delete the cabal file.
addStrInts> test (suite: addStrInts-test)

*** Failed! Falsified (after 1 test):  
""
Done

addStrInts> Test suite addStrInts-test passed

And we got the first error! Looks like isAllDigit do not work properly for an empty string.

This is a quick fix (StrAdd.hs) by pattern matching:

module StrAdd where

import           Data.Char

isAllDigits :: String -> Bool
-- isAllDigits val = all (== True) $ map isDigit val
isAllDigits ""  = False
isAllDigits val = all (== True)
  $ map (\x -> x `elem` ['1', '2', '3', '4', '5', '6', '7', '8', '9']) val

So +++ OK, passed 100 tests. looks good, but 100 cases are too few for us. Let say, to be perfectly sure, we wanna 1000 cases:

main :: IO ()
main = do
  quickCheckWith stdArgs { maxSuccess = 1000 } prop_isAllDigit
  putStrLn "Done"

By quickCheckWith we ask QuickCheck to generate maxSuccess test cases. And dramatically fast we got another error:

*** Failed! Falsified (after 608 tests):                  
"0"
Done

It looks like, we forget about zero! I'm sure you noticed it right away.
Let's modify our function:

isAllDigits :: String -> Bool
isAllDigits ""  = False
isAllDigits val = all (== True) $ map isDigit val

Try to run stack test again to be sure, all works properly now. Well done!

Now just add the remaining code, and move on to writing the IO action.
Your StrAdd should look like:

module StrAdd where

import           Data.Char

isAllDigits :: String -> Bool
isAllDigits ""  = False
isAllDigits val = all (== True) $ map isDigit val

strAddInts :: String -> String -> Either String Int
strAddInts a b
  | isAllDigits a && isAllDigits b       = Right (read a + read b)
  | not (isAllDigits a || isAllDigits b) = Left "Both args are wrong"
  | not (isAllDigits a)                  = Left "First arg is wrong"
  | otherwise                            = Left "Second ars is wrong"

Entry point

Nobody likes dirty function, especially in Haskell, but unfortunately without any side effects our code becomes absolutely useless (even more useless then our current project!). So, let's add some IO actions for communication with the user.

Functions with side effects – the most dangerous and unpredictable functions in a whole project. So you need to try to make that code isolated. In this small Stack project, we'll place all user-interaction code in the program entry point app/Main.hs. This way, the entry point will be responsible just for interacting with the user, and all "business" code stays aside in src/StrAdd.hs.

module Main where

import           StrAdd

main :: IO ()
main = do
  putStrLn "Enter first argument"
  a <- getLine
  putStrLn "Enter second argument"
  b <- getLine

  let result = strAddInts a b

  putStrLn (displayResult result)

Don't forgate add displayResult helper function in StrAdd.hs:

displayResult :: Either String Int -> String
displayResult (Left  addError) = "error: " ++ show addError
displayResult (Right res     ) = "answer: " ++ show res

This is all. Now we should build the whole our project: stack build. If you did all right build process should finish without errors.

After the build, we finally may try to run our project as a real program: stack exec addStrInts-exe

Looks good!

➜  addStrInts git:(master) ✗ stack exec addStrInts-exe
Enter first argument
42
Enter second argument
69
answer: 111

Conclusion

According to the stack-way, you could develop Haskell applications within a full-featured powerful build system. Of cause, in this post, we touched just a tip of the iceberg, but it will be enough for the first meeting and start working with Stack.

We’ll meet a Stack much closer next time, trying to implement http interaction and external dependencies

VS Code for Haskell in 2020

Egregors — Mon, 20 Jan 2020 05:35:30 +0000

01 – VS Code for Haskell in 2020
02 – Your first Stack project (build, test, dist)

UPD

So, for now, you don't need any of the mess below! Thanks to guys making hie-server, you finally can just download VS Code plugin and this is all: please check this out: https://mpickering.github.io/ide/posts/2020-07-10-ghc-libdir.html

Looks like vscode-hie-server, will be hosted under the Haskell organization, and it's just working :D

I have left this guide here, just to remember how tough it was.

Outdated 👇

If you trying to find some Haskell IDE guides, most of them probably will be about emacs and hashell-mode. But in this case, you will need to deal with emacs first. And if you haven't any experience with this kind of IDE it will take a while.

Also, for some reason, you would wanna fool around with Haskell on the Windows with the same "good enough" experience like in the macOS or Linux.

That's why I believe vscode with a few very useful extensions will be a better solution

So this little guide let you get absolutely the same Haskell programming experience, independently from OS

TL;DR

get vscode and stack
Install stack dependencies:
stack install intero QuickCheck hlint brittany ghcid
add $HOME/.local/bin to your $PATH
Install VS Code extensions (IDE, linter, formatter, hoogle). You should have code in your $PATH:
code \ --install-extension ucl.haskelly \ --install-extension hoovercj.haskell-linter \ --install-extension maxgabriel.brittany \ --install-extension jcanero.hoogle-vscode
restart vscode ... profit!

Setup with details

Haskell Platform | Stack

First of all, you should install Haskell and a few tools. I recommend use stack installer for this purpose. Stack is a kind of package manager for Haskell. Like cabal, but not quite. It will install GHC automatically as well. Next, it will be useful tool for working with isolated dependencies, ghci REPL, building and testing your projects.

The simplest way is just to execute install script from the official site for unix-like OS:

curl -sSL https://get.haskellstack.org/ | sh

or download installer for Шindows

Haskelly

Next, we'll install one of the popular vscode extension for Haskell. It contains:

highlight
snippets
hovers
jump to definition
find references
code completion
integrated REPL
Build, Test and Run commands

Exclude the vscode extension you should install a few Haskell packages (don't forgate to add $HOME/.local/bin to your $PATH):

stack install intero QuickCheck  # for a global installation
stack build intero QuickCheck    # for a local installation

Especially I like load GCHi feature. When you're starting with Haskell you'll spend a lot of time in GHCi, and eventually, it becomes a kind of habit. You know, you are writing a beautiful function in the context of your current file, and you wanna test it within context. Load GHCi starts GHCi and automatically loads all stuff from your current file. And you got a useful way of playing around with your functions. Make some changes, safe files, and just type :r to reload a new version into GHCi.

We are almost here. This is the minimum setup for pleasant Haskell development, but we'll make it even better. Much better!

Hlint

hlint is an absolute must-have for any beginner | middle Haskell developer. This is the linter that teaches you Haskell even better than books! From docs: HLint is a tool for suggesting possible improvements to Haskell code. These suggestions include ideas such as using alternative functions, simplifying code and spotting redundancies.

Install by stack

stack install hlint

Next, we need to install vscode integrations for hlint: vscode-haskell-linter.

After that hlint will suggest you some code improving. But keep it in mind, sometimes hlint may be kind of rude :3

Brittany

Next one. If we are talking about indentations it's always difficult in Haskell. That's why you definitely need some code formatting tool. Personally, I prefer brittany

stack install brittany

And brittany-vscode-extension as well. This tool applies to be the default "Format Document" command or shortcut.

ghcid

It does not look like a big deal but in fact, this tool becomes an absolutely necessary thing for a smooth workflow. To a first approximation, it opens ghci and runs :reload whenever your source code changes, formatting the output to fit a fixed height console.

So, usually, I have split up the window to three parts:
source code, GHCi with loaded up current code and ghcid like a realtime indicator that all is good.

To run ghcid you should use stack exec ghcid YOUR_FILE_NAME.hs command

Hoogle

Just shortcut for Hoogle search.

All of this should be enough to comfortable Haskell learning/development independently of your platform