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

@@ -54,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)
 	}
 
@@ -64,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
@@ -94,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
@@ -135,9 +134,12 @@ 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)
 
 	// Download all fragments serially to keep execution simple and deterministic.
-	for _, fragment := range manifest.Fragments {
+	for idx, fragment := range manifest.Fragments {
 		url := transformShaToURL(fragment.Sha512, fragment.Size)
 		content, err := getContent(url)
 		if err != nil {
@@ -150,7 +152,10 @@ func Download(manifest Manifest, downloadDir string, filen string) ([]byte, erro
 		}
 		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)
+		if percent-lastLoggedPercent >= 5 || idx == len(manifest.Fragments)-1 {
+			log.Info("download progress", "downloaded_mb", downedMB, "total_mb", totalMB, "percent", percent)
+			lastLoggedPercent = percent
+		}
 	}
 
 	// sort trackFrag by Offset
@@ -166,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:]
@@ -176,7 +181,7 @@ 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
 }
@@ -193,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)
 	}