{"id":31776745,"url":"https://github.com/codelieutenant/utils","last_synced_at":"2025-10-10T05:55:15.960Z","repository":{"id":314661180,"uuid":"1056290131","full_name":"CodeLieutenant/utils","owner":"CodeLieutenant","description":"Go Utils for General Development","archived":false,"fork":false,"pushed_at":"2025-09-13T21:33:15.000Z","size":160,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-02T05:47:25.384Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodeLieutenant.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-13T19:20:13.000Z","updated_at":"2025-09-13T21:33:18.000Z","dependencies_parsed_at":"2025-09-13T23:31:48.400Z","dependency_job_id":"a2adca9d-04d8-46fc-96f9-b1c7d8189833","html_url":"https://github.com/CodeLieutenant/utils","commit_stats":null,"previous_names":["codelieutenant/utils"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/CodeLieutenant/utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeLieutenant%2Futils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeLieutenant%2Futils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeLieutenant%2Futils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeLieutenant%2Futils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodeLieutenant","download_url":"https://codeload.github.com/CodeLieutenant/utils/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeLieutenant%2Futils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002863,"owners_count":26083468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T05:55:14.975Z","updated_at":"2025-10-10T05:55:15.954Z","avatar_url":"https://github.com/CodeLieutenant.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Utils\n\nA comprehensive Go utility library providing essential tools for common development tasks.\n\n[![Go Version](https://img.shields.io/badge/go-1.25+-blue.svg)](https://golang.org/doc/devel/release.html)\n[![Go Reference](https://pkg.go.dev/badge/github.com/CodeLieutenant/utils.svg)](https://pkg.go.dev/github.com/CodeLieutenant/utils)\n[![Go Report Card](https://goreportcard.com/badge/github.com/CodeLieutenant/utils)](https://goreportcard.com/report/github.com/CodeLieutenant/utils)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![codecov](https://codecov.io/gh/CodeLieutenant/utils/graph/badge.svg?token=lqhmgWPlWJ)](https://codecov.io/gh/CodeLieutenant/utils)\n\n## Installation\n\n```bash\ngo get github.com/CodeLieutenant/utils\n```\n\n## Modules\n\nThis package contains several utility modules:\n\n- **Core utilities** - File operations, path handling, password generation, memory formatting\n- **Environment management** - Environment variable handling with type conversion\n- **Network utilities** - IP address detection and validation\n- **Cryptographic utilities** - Key parsing and hashing algorithms\n- **[HTTP utilities](httputils/README.md)** - Chi router helpers and HTTP response utilities\n- **[Logging](logger/README.md)** - Structured logging with stacktraces and runtime info\n- **[URL signing](urlsigner/README.md)** - HMAC-based URL signing for secure links\n- **[Signal handling](signals/README.md)** - Cross-platform OS signal management\n\n## 📚 Detailed Documentation\n\nEach subpackage has comprehensive documentation with examples:\n\n- **[Logger Package](logger/README.md)** - Structured logging with slog, stacktraces, and runtime information\n- **[HTTP Utils Package](httputils/README.md)** - Chi router setup, middleware, and HTTP helpers\n- **[Signals Package](signals/README.md)** - Cross-platform OS signal handling utilities\n- **[URL Signer Package](urlsigner/README.md)** - HMAC-based URL signing for secure time-limited links\n\n## Core Utilities\n\n### File Operations\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"os\"\n\n    \"github.com/CodeLieutenant/utils\"\n)\n\nfunc main() {\n    // Create a directory with permissions\n    dirPath, err := utils.CreateDirectory(\"/tmp/myapp\", 0755)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"Directory created: %s\\n\", dirPath)\n\n    // Create a log file\n    logFile, err := utils.CreateLogFile(\"/tmp/myapp/app.log\")\n    if err != nil {\n        panic(err)\n    }\n    defer logFile.Close()\n\n    // Check if file exists\n    if utils.FileExists(\"/tmp/myapp/app.log\") {\n        fmt.Println(\"Log file exists!\")\n    }\n}\n```\n\n### Password Generation\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/CodeLieutenant/utils\"\n)\n\nfunc main() {\n    // Generate a secure random password\n    password, err := utils.GenerateRandomPassword(16)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"Generated password: %s\\n\", password)\n}\n```\n\n### Memory Size Formatting\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/CodeLieutenant/utils\"\n)\n\nfunc main() {\n    // Format memory sizes\n    size := utils.MemorySize(1024 * 1024 * 1024) // 1 GiB\n    fmt.Printf(\"Memory size: %s\\n\", size.String()) // Output: 1GiB\n\n    // Different sizes\n    fmt.Printf(\"1024 bytes: %s\\n\", utils.MemorySize(1024).String()) // 1KiB\n    fmt.Printf(\"1MB: %s\\n\", utils.MemorySize(1024*1024).String())   // 1MiB\n}\n```\n\n### Unsafe String/Bytes Conversion\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/CodeLieutenant/utils\"\n)\n\nfunc main() {\n    // Zero-copy string to bytes conversion\n    str := \"hello world\"\n    bytes := utils.UnsafeBytes(str)\n    fmt.Printf(\"String as bytes: %v\\n\", bytes)\n\n    // Zero-copy bytes to string conversion\n    backToString := utils.UnsafeString(bytes)\n    fmt.Printf(\"Bytes as string: %s\\n\", backToString)\n}\n```\n\n## Environment Management\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/CodeLieutenant/utils\"\n)\n\nfunc main() {\n    // Initialize environment (loads .env file automatically)\n    env := utils.NewEnv(false)\n\n    // Get string with default\n    dbHost := utils.GetStringEnv(env, \"DB_HOST\", \"localhost\")\n    fmt.Printf(\"Database host: %s\\n\", dbHost)\n\n    // Get integer with default\n    dbPort := utils.GetIntEnv(env, \"DB_PORT\", 5432)\n    fmt.Printf(\"Database port: %d\\n\", dbPort)\n\n    // Get boolean with default\n    debug := utils.GetBoolEnv(env, \"DEBUG\", false)\n    fmt.Printf(\"Debug mode: %t\\n\", debug)\n\n    // Get duration with default\n    timeout := utils.GetDurationEnv(env, \"REQUEST_TIMEOUT\", \"30s\")\n    fmt.Printf(\"Request timeout: %v\\n\", timeout)\n\n    // Get string slice\n    allowedHosts := utils.GetStringsEnv(env, \"ALLOWED_HOSTS\", []string{\"localhost\"})\n    fmt.Printf(\"Allowed hosts: %v\\n\", allowedHosts)\n}\n```\n\n## Network Utilities\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/CodeLieutenant/utils\"\n)\n\nfunc main() {\n    // Get local machine IP\n    localIP := utils.GetLocalIP()\n    fmt.Printf(\"Local IP: %s\\n\", localIP)\n\n    // Get all local IPs\n    localIPs := utils.GetLocalIPs()\n    fmt.Printf(\"All local IPs: %v\\n\", localIPs)\n}\n```\n\n## Cryptographic Utilities\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/CodeLieutenant/utils\"\n)\n\nfunc main() {\n    // Parse hex-encoded key\n    hexKey := \"deadbeefcafebabe1234567890abcdef12345678\"\n    key1, err := utils.ParseKey(hexKey)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"Hex key length: %d bytes\\n\", len(key1))\n\n    // Parse base64-encoded key\n    base64Key := \"base64:3q2+78r+uro=\"\n    key2, err := utils.ParseKey(base64Key)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"Base64 key length: %d bytes\\n\", len(key2))\n\n    // Get hash function\n    hasher := utils.ParseHasher(\"sha256\")\n    if hasher != nil {\n        h := hasher()\n        h.Write([]byte(\"hello world\"))\n        hash := h.Sum(nil)\n        fmt.Printf(\"SHA256 hash length: %d bytes\\n\", len(hash))\n    }\n}\n```\n\n## HTTP Utilities\n\n\u003e 📖 **For comprehensive HTTP utilities documentation, see: [HTTP Utils Package Documentation](httputils/README.md)**\n\n```go\npackage main\n\nimport (\n    \"net/http\"\n\n    \"github.com/CodeLieutenant/utils/httputils\"\n    \"github.com/go-chi/chi/v5\"\n)\n\nfunc main() {\n    // Setup router with production middleware\n    config := httputils.ProductionMiddlewareConfig()\n    options := \u0026httputils.RouterSetupOptions{\n        LoggerColor: false,\n        Middleware:  config,\n    }\n\n    r := httputils.SetupRouter(options)\n\n    // Add routes\n    r.Get(\"/api/health\", func(w http.ResponseWriter, r *http.Request) {\n        response := map[string]string{\"status\": \"ok\"}\n        httputils.NewResponse(w).OK(response)\n    })\n\n    http.ListenAndServe(\":8080\", r)\n}\n```\n\n## Logging\n\n\u003e 📖 **For comprehensive logging documentation, see: [Logger Package Documentation](logger/README.md)**\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log/slog\"\n\n    \"github.com/CodeLieutenant/utils/logger\"\n)\n\nfunc main() {\n    // Configure structured logging\n    config := \u0026logger.LogConfig{\n        Level:          \"info\",\n        Format:         \"json\",\n        Output:         \"stdout\",\n        AddSource:      true,\n        AddStacktrace:  true,\n        AddRuntimeInfo: true,\n    }\n\n    // Setup logger\n    slogger, err := logger.SetupLogger(\"myapp\", \"v1.0.0\", config)\n    if err != nil {\n        panic(err)\n    }\n\n    // Use the logger\n    ctx := context.Background()\n    slogger.InfoContext(ctx, \"Application started\",\n        slog.String(\"version\", \"v1.0.0\"),\n        slog.Int(\"port\", 8080),\n    )\n\n    slogger.ErrorContext(ctx, \"Something went wrong\",\n        slog.String(\"error\", \"database connection failed\"),\n    )\n}\n```\n\n## URL Signing\n\n\u003e 📖 **For comprehensive URL signing documentation, see: [URL Signer Package Documentation](urlsigner/README.md)**\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"net/url\"\n    \"time\"\n\n    \"github.com/CodeLieutenant/utils\"\n    \"github.com/CodeLieutenant/utils/urlsigner\"\n)\n\nfunc main() {\n    // Create HMAC signer with SHA256\n    key, _ := utils.ParseKey(\"deadbeefcafebabe1234567890abcdef12345678\")\n    signer := urlsigner.New(\"sha256\", key)\n\n    // Sign a URL with 1 hour expiration\n    originalURL := \"https://example.com/api/download?file=document.pdf\"\n    signedURL, err := signer.Sign(originalURL, time.Hour)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"Signed URL: %s\\n\", signedURL)\n\n    // Verify the signed URL\n    parsedURL, _ := url.Parse(signedURL)\n    if err := signer.Verify(parsedURL); err != nil {\n        fmt.Printf(\"Verification failed: %v\\n\", err)\n    } else {\n        fmt.Println(\"URL signature is valid!\")\n    }\n}\n```\n\n## Signal Handling\n\n\u003e 📖 **For comprehensive signal handling documentation, see: [Signals Package Documentation](signals/README.md)**\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"os\"\n\n    \"github.com/CodeLieutenant/utils/signals\"\n)\n\nfunc main() {\n    // Get signal by name\n    sigterm, err := signals.Get(\"SIGTERM\")\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"SIGTERM signal: %v\\n\", sigterm)\n\n    // Must get signal (panics if not found)\n    sigint := signals.MustGet(\"SIGINT\")\n    fmt.Printf(\"SIGINT signal: %v\\n\", sigint)\n\n    // Use in signal handling\n    sigChan := make(chan os.Signal, 1)\n    signal.Notify(sigChan, sigint, sigterm)\n\n    fmt.Println(\"Waiting for signal...\")\n    sig := \u003c-sigChan\n    fmt.Printf(\"Received signal: %v\\n\", sig)\n}\n```\n\n## Environment Constants\n\nThe package provides predefined environment constants:\n\n```go\nconst (\n    EnvDev   = \"development\"\n    EnvProd  = \"production\"\n    EnvStage = \"staging\"\n)\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\nmake test\n\n# Run tests with coverage\nmake test-coverage\n\n# View coverage report\nmake coverage-html\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Dependencies\n\n- [github.com/go-chi/chi/v5](https://github.com/go-chi/chi) - HTTP router\n- [github.com/joho/godotenv](https://github.com/joho/godotenv) - Environment file loading\n- [github.com/stretchr/testify](https://github.com/stretchr/testify) - Testing toolkit\n- [golang.org/x/crypto](https://golang.org/x/crypto) - Extended cryptography support\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodelieutenant%2Futils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodelieutenant%2Futils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodelieutenant%2Futils/lists"}