github.com/KimMachineGun/automemlimit v0.7.1: configure Go runtime memory limit using automemlimit memlimit options

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: configure Go runtime memory limit using automemlimit memlimit options
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/KimMachineGun/automemlimit@v0.7.1
Demonstrate these symbols/APIs:
  - github.com/KimMachineGun/automemlimit/memlimit.Limit
  - github.com/KimMachineGun/automemlimit/memlimit.SetGoMemLimitWithOpts
  - github.com/KimMachineGun/automemlimit/memlimit.WithProvider
  - github.com/KimMachineGun/automemlimit/memlimit.WithRatio

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:426c1a24437af85bdd92dbb4479b51c9ea61cae5d2b150a986999fc446ca7792","contract":["memlimit.Limit creates a Provider returning the specified memory limit in bytes","memlimit.WithProvider and memlimit.WithRatio configure SetGoMemLimitWithOpts to scale the memory limit","SetGoMemLimitWithOpts updates the Go runtime memory limit via debug.SetMemoryLimit","SetGoMemLimitWithOpts with ratio 1.0 applies the exact memory limit without scaling","SetGoMemLimitWithOpts returns an error when given an invalid ratio outside (0.0, 1.0]","SetGoMemLimitWithOpts caps limits exceeding math.MaxInt64 to math.MaxInt64"],"goal":"configure Go runtime memory limit using automemlimit memlimit options","kind":"HOW","packages":["pkg:golang/github.com/KimMachineGun/automemlimit@v0.7.1"],"schemaVersion":1,"symbols":["github.com/KimMachineGun/automemlimit/memlimit.Limit","github.com/KimMachineGun/automemlimit/memlimit.SetGoMemLimitWithOpts","github.com/KimMachineGun/automemlimit/memlimit.WithProvider","github.com/KimMachineGun/automemlimit/memlimit.WithRatio"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/KimMachineGun/automemlimit@v0.7.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/KimMachineGun/automemlimit@v0.7.1","symbols":["github.com/KimMachineGun/automemlimit/memlimit.Limit","github.com/KimMachineGun/automemlimit/memlimit.SetGoMemLimitWithOpts","github.com/KimMachineGun/automemlimit/memlimit.WithProvider","github.com/KimMachineGun/automemlimit/memlimit.WithRatio"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.26.6

require github.com/KimMachineGun/automemlimit v0.7.1

require github.com/pbnjay/memory v0.0.0-20210728143218-7b4eea64cf58 // indirect

github.com/KimMachineGun/automemlimit v0.7.1 h1:QcG/0iCOLChjfUweIMC3YL5Xy9C3VBeNmCZHrZfJMBw=
github.com/KimMachineGun/automemlimit v0.7.1/go.mod h1:QZxpHaGOQoYvFhv/r4u3U0JTC2ZcOwbSr11UZF46UBM=
github.com/pbnjay/memory v0.0.0-20210728143218-7b4eea64cf58 h1:onHthvaw9LFnH4t2DcNVpwGmV9E1BkGknEliJkfwQj0=
github.com/pbnjay/memory v0.0.0-20210728143218-7b4eea64cf58/go.mod h1:DXv8WO4yhMYhSNPKjeNKa5WY9YCIEBRbNzFFPJbWO6Y=

package main

import (
	"fmt"
	"runtime/debug"

	"github.com/KimMachineGun/automemlimit/memlimit"
)

func main() {
	targetLimit := uint64(256 * 1024 * 1024) // 256MB
	ratio := 0.8

	limit, err := memlimit.SetGoMemLimitWithOpts(
		memlimit.WithProvider(memlimit.Limit(targetLimit)),
		memlimit.WithRatio(ratio),
	)
	if err != nil {
		fmt.Printf("Failed to set memory limit: %v\n", err)
		return
	}

	expectedLimit := int64(float64(targetLimit) * ratio)
	currentLimit := debug.SetMemoryLimit(-1)

	fmt.Printf("Memory limit set successfully: %d bytes (expected: %d, current: %d)\n", limit, expectedLimit, currentLimit)
}

{
  "schemaVersion": 1,
  "goal": "configure Go runtime memory limit using automemlimit memlimit options",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/KimMachineGun/automemlimit@v0.7.1"
  ],
  "symbols": [
    "github.com/KimMachineGun/automemlimit/memlimit.Limit",
    "github.com/KimMachineGun/automemlimit/memlimit.SetGoMemLimitWithOpts",
    "github.com/KimMachineGun/automemlimit/memlimit.WithProvider",
    "github.com/KimMachineGun/automemlimit/memlimit.WithRatio"
  ]
}

package main

import (
	"fmt"
	"math"
	"os"
	"runtime/debug"

	"github.com/KimMachineGun/automemlimit/memlimit"
)

func main() {
	// Snapshot initial limit
	origLimit := debug.SetMemoryLimit(-1)
	defer debug.SetMemoryLimit(origLimit)

	// Contract 1: memlimit.Limit creates a Provider returning the specified memory limit in bytes
	fixedLimit := uint64(512 * 1024 * 1024) // 512 MB
	provider := memlimit.Limit(fixedLimit)
	val, err := provider()
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: Limit provider returned error: %v\n", err)
		os.Exit(1)
	}
	if val != fixedLimit {
		fmt.Fprintf(os.Stderr, "FAIL: Limit provider returned %d, expected %d\n", val, fixedLimit)
		os.Exit(1)
	}

	// Contract 2: memlimit.WithProvider and memlimit.WithRatio configure SetGoMemLimitWithOpts to scale the memory limit
	ratio := 0.75
	expectedSetLimit := int64(float64(fixedLimit) * ratio)

	retLimit, err := memlimit.SetGoMemLimitWithOpts(
		memlimit.WithProvider(memlimit.Limit(fixedLimit)),
		memlimit.WithRatio(ratio),
	)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: SetGoMemLimitWithOpts returned error: %v\n", err)
		os.Exit(1)
	}
	if retLimit != expectedSetLimit {
		fmt.Fprintf(os.Stderr, "FAIL: SetGoMemLimitWithOpts returned %d, expected %d\n", retLimit, expectedSetLimit)
		os.Exit(1)
	}

	// Contract 3: SetGoMemLimitWithOpts updates the Go runtime memory limit via debug.SetMemoryLimit
	currentLimit := debug.SetMemoryLimit(-1)
	if currentLimit != expectedSetLimit {
		fmt.Fprintf(os.Stderr, "FAIL: debug.SetMemoryLimit(-1) returned %d, expected %d\n", currentLimit, expectedSetLimit)
		os.Exit(1)
	}

	// Contract 4: SetGoMemLimitWithOpts with ratio 1.0 applies the exact memory limit without scaling
	retLimitFull, err := memlimit.SetGoMemLimitWithOpts(
		memlimit.WithProvider(memlimit.Limit(fixedLimit)),
		memlimit.WithRatio(1.0),
	)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: SetGoMemLimitWithOpts with ratio 1.0 returned error: %v\n", err)
		os.Exit(1)
	}
	if retLimitFull != int64(fixedLimit) {
		fmt.Fprintf(os.Stderr, "FAIL: SetGoMemLimitWithOpts with ratio 1.0 returned %d, expected %d\n", retLimitFull, int64(fixedLimit))
		os.Exit(1)
	}
	if cur := debug.SetMemoryLimit(-1); cur != int64(fixedLimit) {
		fmt.Fprintf(os.Stderr, "FAIL: runtime memory limit is %d, expected %d\n", cur, int64(fixedLimit))
		os.Exit(1)
	}

	// Contract 5: SetGoMemLimitWithOpts returns an error when given an invalid ratio outside (0.0, 1.0]
	_, errInvalidRatio := memlimit.SetGoMemLimitWithOpts(
		memlimit.WithProvider(memlimit.Limit(fixedLimit)),
		memlimit.WithRatio(1.5),
	)
	if errInvalidRatio == nil {
		fmt.Fprintln(os.Stderr, "FAIL: SetGoMemLimitWithOpts with ratio 1.5 should return error")
		os.Exit(1)
	}

	// Contract 6: SetGoMemLimitWithOpts caps limits exceeding math.MaxInt64 to math.MaxInt64
	hugeLimit := uint64(math.MaxUint64)
	retHuge, errHuge := memlimit.SetGoMemLimitWithOpts(
		memlimit.WithProvider(memlimit.Limit(hugeLimit)),
		memlimit.WithRatio(1.0),
	)
	if errHuge != nil {
		fmt.Fprintf(os.Stderr, "FAIL: SetGoMemLimitWithOpts with huge limit returned error: %v\n", errHuge)
		os.Exit(1)
	}
	if retHuge != math.MaxInt64 {
		fmt.Fprintf(os.Stderr, "FAIL: SetGoMemLimitWithOpts with huge limit returned %d, expected %d\n", retHuge, int64(math.MaxInt64))
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed successfully.")
}