### Install Blackfriday v2

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/russross/blackfriday/v2/README.md

Use `go get` to install the package in module mode. Alternatively, import it in your package and run `go get`.

```go
go get github.com/russross/blackfriday/v2
```

```go
import "github.com/russross/blackfriday/v2"
```

--------------------------------

### Generate Mox Configuration

Source: https://github.com/mjl-/mox/blob/main/website/install/index.md

Run the quickstart command to generate configuration files, add domains and accounts, and get DNS record information. This command should be executed from the Mox directory.

```bash
./mox quickstart you@example.com
```

--------------------------------

### Install blackfriday-tool

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/russross/blackfriday/v2/README.md

Download and install the `blackfriday-tool` command-line utility using `go get`. This tool provides a standalone markdown processing program.

```go
go get github.com/russross/blackfriday-tool
```

--------------------------------

### Install bbolt

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Install the bbolt library using go get. This command updates your go.mod and go.sum files.

```sh
$ go get go.etcd.io/bbolt@latest
```

--------------------------------

### Initialize Procfs and Get Stat Information

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/prometheus/procfs/README.md

Initializes the proc filesystem and retrieves CPU statistics. Use this to get basic system-level metrics.

```go
fs, err := procfs.NewFS("/proc")
stats, err := fs.Stat()
```

--------------------------------

### Install cfssl Tools

Source: https://github.com/mjl-/mox/blob/main/develop.txt

Installs the cfssl and cfssljson command-line tools required for TLS certificate management. Ensure Go is installed and configured.

```bash
go install github.com/cloudflare/cfssl/cmd/cfssl@latest
go install github.com/cloudflare/cfssl/cmd/cfssljson@latest
```

--------------------------------

### Add or Update Dependencies

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/prometheus/procfs/CONTRIBUTING.md

Use `go get` to add or update external packages. Remember to commit the changes to `go.mod`, `go.sum`, and the `vendor/` directory.

```bash
# Pick the latest tagged release.
go get example.com/some/module/pkg

# Pick a specific version.
go get example.com/some/module/pkg@vX.Y.Z
```

--------------------------------

### Compile Mox from Source

Source: https://github.com/mjl-/mox/blob/main/website/install/index.md

Compile the latest version of Mox from source using Go. Ensure your Go toolchain is version 1.23 or higher. This command compiles and installs the binary to the current directory.

```bash
GOBIN=$PWD CGO_ENABLED=0 go install github.com/mjl-/mox@latest
```

--------------------------------

### Initialize Block Device FS and Get Disk Stats

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/prometheus/procfs/README.md

Initializes a filesystem object that accesses both /proc and /sys, then retrieves disk statistics. This is useful for block device information.

```go
fs, err := blockdevice.NewFS("/proc", "/sys")
stats, err := fs.ProcDiskstats()
```

--------------------------------

### Install bbolt Command Line Utility

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Install the bbolt command line utility globally. This makes the 'bbolt' command available in your system's PATH.

```sh
$ go install go.etcd.io/bbolt/cmd/bbolt@latest
```

--------------------------------

### Start Pebble Server

Source: https://github.com/mjl-/mox/blob/main/develop.txt

Command to start the Pebble ACME server using the specified configuration file. This command will generate a new temporary CA certificate upon each start.

```sh
pebble -config local/pebble/config.json
```

--------------------------------

### Monitor BoltDB Database Statistics

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Provides an example of how to periodically collect and diff BoltDB database statistics. This helps in understanding database activity and performance over time.

```go
go func() {
	// Grab the initial stats.
	prev := db.Stats()

	for {
		// Wait for 10s.
		time.Sleep(10 * time.Second)

		// Grab the current stats and diff them.
		stats := db.Stats()
		diff := stats.Sub(&prev)

		// Encode stats to JSON and print to STDERR.
		json.NewEncoder(os.Stderr).Encode(diff)

		// Save stats for the next loop.
		prev = stats
	}
}()

```

--------------------------------

### Import and Open bbolt Database

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Import the bbolt library and open a database file. Ensure to close the database connection when done using defer.

```go
import bolt "go.etcd.io/bbolt"

db, err := bolt.Open(path, 0666, nil)
if err != nil {
  return err
}
def db.Close()
```

--------------------------------

### Create Mox User and Directory

Source: https://github.com/mjl-/mox/blob/main/website/install/index.md

Use this command to create a dedicated user and home directory for Mox. Ensure you are running as root.

```bash
useradd -m -d /home/mox mox
```

--------------------------------

### Mox Backup Command

Source: https://github.com/mjl-/mox/blob/main/README.md

Create a backup of your Mox configuration and data directory using the 'mox backup <destdir>' command. This is crucial before performing upgrades.

```bash
mox backup <destdir>
```

--------------------------------

### mtasts.Get

Source: https://github.com/mjl-/mox/blob/main/apidiff/v0.0.9.txt

The Get function signature has been updated to include a logger.

```APIDOC
## mtasts.Get

### Description
Retrieves a record and policy, now accepting a logger as the second argument.

### Method
func(context.Context, *golang.org/x/exp/slog.Logger, github.com/mjl-/mox/dns.Resolver, github.com/mjl-/mox/dns.Domain) (*Record, *Policy, string, error)
```

--------------------------------

### xxhash Benchmarking Commands

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/cespare/xxhash/v2/README.md

Commands to benchmark the pure Go and assembly implementations of the `Sum64` function. Use `benchstat` to analyze the results.

```bash
benchstat <(go test -tags purego -benchtime 500ms -count 15 -bench 'Sum64$')
```

```bash
benchstat <(go test -benchtime 500ms -count 15 -bench 'Sum64$')
```

--------------------------------

### BoltDB Read-Only Transaction

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Starts a read-only transaction using DB.View(). Provides a consistent view of the database, but only allows retrieval operations. No mutating operations are permitted.

```go
err := db.View(func(tx *bolt.Tx) error {
	...
	return nil
})
```

--------------------------------

### Generate Local CA Certificate and Key

Source: https://github.com/mjl-/mox/blob/main/develop.txt

Sets up a local Certificate Authority (CA) by generating its configuration, a certificate signing request (CSR), and then the CA's key and certificate. This is a prerequisite for signing host certificates.

```bash
mkdir -p local/cfssl
cd local/cfssl
cfssl print-defaults config > ca-config.json
cat <<EOF >ca-csr.json
{
    "CN": "mox ca",
    "key": {
        "algo": "ecdsa",
        "size": 256
    },
    "names": [
        {
            "C": "NL"
        }
    ]
}
EOF
cfssl gencert -initca ca-csr.json | cfssljson -bare ca - # Generate ca key and cert.
```

--------------------------------

### BoltDB Manual Transaction Management

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Manually starts and ends transactions using DB.Begin(). Ensure the transaction is properly closed using Rollback() or Commit(). This method provides more control but requires careful handling.

```go
// Start a writable transaction.
tx, err := db.Begin(true)
if err != nil {
    return err
}
defer tx.Rollback()

// Use the transaction...
_, err = tx.CreateBucket([]byte("MyBucket"))
if err != nil {
    return err
}

// Commit the transaction and check for error.
if err := tx.Commit(); err != nil {
    return err
}
```

--------------------------------

### Iterate Over All Keys Using ForEach()

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Use the ForEach() method for a simpler iteration over all keys in a bucket when you don't need the cursor's advanced navigation. Note that keys and values are only valid within the transaction.

```go
db.View(func(tx *bolt.Tx) error {
	// Assume bucket exists and has keys
	b := tx.Bucket([]byte("MyBucket"))

	b.ForEach(func(k, v []byte) error {
		fmt.Printf("key=%s, value=%s\n", k, v)
		return nil
	})
	return nil
})
```

--------------------------------

### Run Tests with Make

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/prometheus/procfs/CONTRIBUTING.md

Ensure all tests pass before committing and pushing your changes.

```bash
make test         # Make sure all the tests pass before you commit and push :)
```

--------------------------------

### Get Value by Key in BoltDB

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Use Bucket.Get() within a read-only transaction to retrieve the byte slice value associated with a key. Returns nil if the key does not exist. Values are only valid for the duration of the transaction.

```go
db.View(func(tx *bolt.Tx) error {
	b := tx.Bucket([]byte("MyBucket"))
	v := b.Get([]byte("answer"))
	fmt.Printf("The answer is: %s\n", v)
	return nil
})
```

--------------------------------

### BoltDB Read-Write Transaction

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Starts a read-write transaction using DB.Update(). All database operations are permitted within the closure. Return nil to commit, or an error to rollback. Always check the return error for disk failures.

```go
err := db.Update(func(tx *bolt.Tx) error {
	...
	return nil
})
```

--------------------------------

### Basic Markdown Processing with No Extensions

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/russross/blackfriday/v2/README.md

Use `blackfriday.Run` with `blackfriday.WithNoExtensions()` for the bare Markdown specification feature set.

```go
output := blackfriday.Run(input, blackfriday.WithNoExtensions())
```

--------------------------------

### Syscall Entry Points in Assembly

Source: https://github.com/mjl-/mox/blob/main/vendor/golang.org/x/sys/unix/README.md

Defines the entry points for system call dispatch in hand-written assembly files. These differ in the number of arguments they can pass to the kernel.

```go
func Syscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr)
func Syscall6(trap, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
func RawSyscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr)
```

--------------------------------

### Backup BoltDB Database using cURL

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Illustrates how to initiate a database backup using the cURL command-line tool, targeting an HTTP endpoint that serves the database file.

```sh
$ curl http://localhost/backup > my.db

```

--------------------------------

### Initialize BoltDB for Mobile Use

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Create a wrapper struct for BoltDB with an initializing constructor that takes a filepath. This method is suitable for mobile use on iOS and Android.

```go
func NewBoltDB(filepath string) *BoltDB {
	db, err := bolt.Open(filepath+"/demo.db", 0600, nil)
	if err != nil {
		log.Fatal(err)
	}

	return &BoltDB{db}
}

type BoltDB struct {
	db *bolt.DB
	...
}

func (b *BoltDB) Path() string {
	return b.db.Path()
}

func (b *BoltDB) Close() {
	b.db.Close()
}
```

--------------------------------

### Tidy and Vendor Dependencies

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/prometheus/procfs/CONTRIBUTING.md

Update `go.mod` and `go.sum` files and copy dependencies to the `vendor/` directory. Ensure `GO111MODULE` is set to `on` if your code is not within GOPATH.

```bash
# The GO111MODULE variable can be omitted when the code isn't located in GOPATH.
GO111MODULE=on go mod tidy

GO111MODULE=on go mod vendor
```

--------------------------------

### Read and Parse /proc/cpuinfo with util.ReadFileNoStat

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/prometheus/procfs/CONTRIBUTING.md

Use util.ReadFileNoStat to read the full content of /proc files, especially when data can change between reads. This avoids issues with stat calls returning incorrect sizes. The data can then be processed using a scanner.

```go
data, err := util.ReadFileNoStat("/proc/cpuinfo")
if err != nil {
    return err
}
reader := bytes.NewReader(data)
scanner := bufio.NewScanner(reader)
```

--------------------------------

### Iterate Over All Keys in a Bucket

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Use a cursor to iterate through all key-value pairs in a bucket in byte-sorted order. Ensure you seek to a position using First(), Last(), or Seek() before calling Next() or Prev().

```go
db.View(func(tx *bolt.Tx) error {
	// Assume bucket exists and has keys
	b := tx.Bucket([]byte("MyBucket"))

	c := b.Cursor()

	for k, v := c.First(); k != nil; k, v = c.Next() {
		fmt.Printf("key=%s, value=%s\n", k, v)
	}

	return nil
})
```

--------------------------------

### Basic Markdown Processing

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/russross/blackfriday/v2/README.md

Process markdown input by calling `blackfriday.Run` with a byte slice. This enables a set of popular extensions.

```go
output := blackfriday.Run(input)
```

--------------------------------

### Create Nested Buckets in BoltDB

Source: https://github.com/mjl-/mox/blob/main/vendor/go.etcd.io/bbolt/README.md

Demonstrates how to create nested buckets within an existing bucket using CreateBucketIfNotExists. This is useful for organizing data hierarchically, such as in a multi-tenant application.

```go
func (*Bucket) CreateBucket(key []byte) (*Bucket, error)
func (*Bucket) CreateBucketIfNotExists(key []byte) (*Bucket, error)
func (*Bucket) DeleteBucket(key []byte) error
```

```go
//createUser creates a new user in the given account.
func createUser(accountID int, u *User) error {
    // Start the transaction.
    tx, err := db.Begin(true)
    if err != nil {
        return err
    }
    defer tx.Rollback()

    // Retrieve the root bucket for the account.
    // Assume this has already been created when the account was set up.
    root := tx.Bucket([]byte(strconv.FormatUint(accountID, 10)))

    // Setup the users bucket.
    bkt, err := root.CreateBucketIfNotExists([]byte("USERS"))
    if err != nil {
        return err
    }

    // Generate an ID for the new user.
    userID, err := bkt.NextSequence()
    if err != nil {
        return err
    }
    u.ID = userID

    // Marshal and save the encoded user.
    if buf, err := json.Marshal(u); err != nil {
        return err
    } else if err := bkt.Put([]byte(strconv.FormatUint(u.ID, 10)), buf); err != nil {
        return err
    }

    // Commit the transaction.
    if err := tx.Commit(); err != nil {
        return err
    }

    return nil
}

```

--------------------------------

### xxhash API Overview

Source: https://github.com/mjl-/mox/blob/main/vendor/github.com/cespare/xxhash/v2/README.md

Provides the main functions and types for using the xxhash package. `Sum64` and `Sum64String` offer direct hashing, while `Digest` allows for incremental hashing.

```go
func Sum64(b []byte) uint64
func Sum64String(s string) uint64
type Digest struct{ ... }
    func New() *Digest
```

--------------------------------

### spf.Verify

Source: https://github.com/mjl-/mox/blob/main/apidiff/v0.0.9.txt

The Verify function in the spf module now accepts a *golang.org/x/exp/slog.Logger as an argument.

```APIDOC
## spf.Verify

### Description
Verifies DNS records for a given domain using a resolver and provided arguments.

### Method
func(context.Context, *golang.org/x/exp/slog.Logger, github.com/mjl-/mox/dns.Resolver, Args) (Received, github.com/mjl-/mox/dns.Domain, string, bool, error)
```