Add README with install and logging docs

README.md

@@ -0,0 +1,76 @@
+# reforger_utils
+
+Utilities for downloading and processing Arma Reforger workshop content.
+
+## Install
+
+This module is hosted on a private Gitea instance.
+
+Set private module settings once:
+
+```powershell
+go env -w GOPRIVATE=gitea.tbdevent.eu
+```
+
+Then install a version:
+
+```powershell
+go get gitea.tbdevent.eu/ilbinek/reforger_utils@v0.0.15
+```
+
+## Features
+
+- Download asset metadata and manifests from BI APIs.
+- Download and rebuild fragmented files.
+- Parse PAK file entries.
+- Optional SOCKS5/Tor support for HTTP requests.
+
+## Basic Usage
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"gitea.tbdevent.eu/ilbinek/reforger_utils"
+)
+
+func main() {
+	assets, err := reforger_utils.DoAssetsRequest("BADC0DEDABBEDA5E", "0.12.4573")
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("found %d assets\n", len(assets))
+}
+```
+
+## Logging
+
+The library uses structured slog logging and writes JSON logs to stdout by default.
+This is container-friendly (including Dokploy) because logs are newline-based and do not overwrite previous output.
+
+You can inject your own logger:
+
+```go
+package main
+
+import (
+	"log/slog"
+	"os"
+
+	"gitea.tbdevent.eu/ilbinek/reforger_utils"
+)
+
+func main() {
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
+	reforger_utils.SetLogger(logger)
+}
+```
+
+## Development
+
+```powershell
+go test ./...
+```

logger.go

@@ -0,0 +1,36 @@
+package reforger_utils
+
+import (
+	"log/slog"
+	"os"
+	"sync"
+)
+
+var (
+	loggerMu sync.RWMutex
+	logger   = newDefaultLogger()
+)
+
+func newDefaultLogger() *slog.Logger {
+	return slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
+}
+
+// SetLogger configures the package logger.
+// Passing nil resets it to the default JSON logger writing to stdout.
+func SetLogger(l *slog.Logger) {
+	loggerMu.Lock()
+	defer loggerMu.Unlock()
+
+	if l == nil {
+		logger = newDefaultLogger()
+		return
+	}
+
+	logger = l
+}
+
+func getLogger() *slog.Logger {
+	loggerMu.RLock()
+	defer loggerMu.RUnlock()
+	return logger
+}

util.go

@@ -9,18 +9,17 @@ import (
 	"path/filepath"
 	"slices"
 	"strings"
-	"sync"
 
 	"golang.org/x/net/proxy"
 )
 
 var Debug = false
 var Tor = false
-var DownThreads = 8
+var Socks5Address = "127.0.0.1:9050"
 
 func getHttpClient() (*http.Client, error) {
 	if Tor {
-		dialer, err := proxy.SOCKS5("tcp", "127.0.0.1:9050", nil, proxy.Direct)
+		dialer, err := proxy.SOCKS5("tcp", Socks5Address, nil, proxy.Direct)
 		if err != nil {
 			return nil, err
 		}
@@ -55,9 +54,8 @@ func DoAssetsRequest(addonID, version string) (AssetsReply, error) {
 	defer res.Body.Close()
 
 	if res.StatusCode != 200 {
-		// print entire body
 		body, _ := io.ReadAll(res.Body)
-		fmt.Println(string(body))
+		getLogger().Error("assets request failed", "status", res.Status, "addon_id", addonID, "version", version, "body", string(body))
 		return AssetsReply{}, fmt.Errorf("bad status: %s", res.Status)
 	}
 
@@ -65,7 +63,7 @@ func DoAssetsRequest(addonID, version string) (AssetsReply, error) {
 	decoder := json.NewDecoder(res.Body)
 	var assetsReply AssetsReply
 	if err := decoder.Decode(&assetsReply); err != nil {
-		panic(err)
+		return AssetsReply{}, fmt.Errorf("failed to decode assets response: %w", err)
 	}
 
 	return assetsReply, nil
@@ -95,7 +93,7 @@ func GetManifest(manifestUrl string) (Manifest, error) {
 	// Decode the JSON response
 	var manifest Manifest
 	if err := json.NewDecoder(res.Body).Decode(&manifest); err != nil {
-		panic(err)
+		return Manifest{}, fmt.Errorf("failed to decode manifest response: %w", err)
 	}
 
 	return manifest, nil
@@ -120,8 +118,8 @@ func Download(manifest Manifest, downloadDir string, filen string) ([]byte, erro
 		if err != nil {
 			return nil, err
 		}
-		remContent = content
-		downloaded += len(content)
+		remContent = *content
+		downloaded += len(*content)
 
 		if Debug {
 			// save remainder to file in the fragments/ directory, prefix with gap
@@ -136,61 +134,28 @@ func Download(manifest Manifest, downloadDir string, filen string) ([]byte, erro
 	// start downloading chunks
 	ret := make([]byte, manifest.Size)
 	totalMB := float32(manifest.Size) / 1024.0 / 1024.0
+	lastLoggedPercent := float32(-1)
+	log := getLogger().With("file", filen)
+	log.Info("download started", "size_bytes", manifest.Size)
 
-	// A channel to signal the main goroutine to check for errors
-	doneChan := make(chan bool)
-
-	var wg sync.WaitGroup
-	wg.Add(DownThreads)
-	var mu sync.Mutex
-
-	fragChan := make(chan Fragment, DownThreads)
-	errChan := make(chan error, DownThreads)
-
-	// Start worker threads
-	for i := 0; i < DownThreads; i++ {
-		go func() {
-			defer wg.Done()
-			for fragment := range fragChan {
+	// Download all fragments serially to keep execution simple and deterministic.
+	for idx, fragment := range manifest.Fragments {
 		url := transformShaToURL(fragment.Sha512, fragment.Size)
 		content, err := getContent(url)
 		if err != nil {
-					errChan <- err
-					return
+			return nil, err
 		}
-				mu.Lock()
-				downloaded += len(content) * len(fragment.Offsets)
+		downloaded += len(*content) * len(fragment.Offsets)
 		for _, offset := range fragment.Offsets {
-					trackFrag = append(trackFrag, Frag{Offset: offset, Size: len(content)})
-					copy(ret[offset:offset+len(content)], content)
+			trackFrag = append(trackFrag, Frag{Offset: offset, Size: len(*content)})
+			copy(ret[offset:offset+len(*content)], *content)
 		}
 		percent := float32(downloaded) / float32(manifest.Size) * 100.0
 		downedMB := float32(downloaded) / 1024.0 / 1024.0
-				fmt.Printf("\r\033[32mDownloaded\033[0m %fMB/%fMB (\033[36m%.2f%%\033[0m) of \033[33m%s\033[0m", downedMB, totalMB, percent, filen)
-				mu.Unlock()
+		if percent-lastLoggedPercent >= 5 || idx == len(manifest.Fragments)-1 {
+			log.Info("download progress", "downloaded_mb", downedMB, "total_mb", totalMB, "percent", percent)
+			lastLoggedPercent = percent
 		}
-		}()
-	}
-
-	// A separate goroutine to wait for all workers to finish and then close the error channel
-	go func() {
-		wg.Wait()
-		close(doneChan)
-	}()
-
-	// Send fragments to workers
-	for _, fragment := range manifest.Fragments {
-		fragChan <- fragment
-	}
-	close(fragChan)
-
-	// Wait for workers to finish or an error to occur
-	select {
-	case <-doneChan:
-		// All workers finished successfully
-	case err := <-errChan:
-		// An error occurred
-		return nil, err
 	}
 
 	// sort trackFrag by Offset
@@ -206,7 +171,7 @@ func Download(manifest Manifest, downloadDir string, filen string) ([]byte, erro
 			// gap detected
 			gapSize := frag.Offset - curPos
 			if currentRem+gapSize > len(remContent) {
-				panic("not enough remainder content to fill gap")
+				return nil, fmt.Errorf("not enough remainder content to fill gap in %s", filen)
 			}
 			copy(ret[curPos:curPos+gapSize], remContent[currentRem:currentRem+gapSize])
 			remContent = remContent[gapSize:]
@@ -216,12 +181,12 @@ func Download(manifest Manifest, downloadDir string, filen string) ([]byte, erro
 
 	// Append rest of remainder content
 	copy(ret[curPos:], remContent)
-	fmt.Println()
+	log.Info("download completed", "size_bytes", len(ret))
 
 	return ret, nil
 }
 
-func getContent(url string) ([]byte, error) {
+func getContent(url string) (*[]byte, error) {
 	client, err := getHttpClient()
 	if err != nil {
 		return nil, err
@@ -233,6 +198,7 @@ func getContent(url string) ([]byte, error) {
 	defer resp.Body.Close()
 
 	if resp.StatusCode != 200 {
+		getLogger().Error("content request failed", "status", resp.Status, "url", url)
 		return nil, fmt.Errorf("bad status: %s", resp.Status)
 	}
 
@@ -241,7 +207,7 @@ func getContent(url string) ([]byte, error) {
 		return nil, err
 	}
 
-	return body, nil
+	return &body, nil
 }
 
 func transformShaToURL(sha512s string, size int) string {