# upkg

Go utility packages collection.

## file_manager

File management abstraction layer supporting multiple storage backends.

### Features

- **Local Storage**: Store files on local filesystem with manifest-based metadata
- **S3 Compatible Storage**: Support AWS S3, MinIO, and other S3-compatible services
- **SHA256 Verification**: Optional file integrity verification
- **Automatic Cleanup**: Configurable timeout for incomplete uploads and expiration for completed files
- **Persistent State**: State managed via manifest files (local) or object metadata (S3)

### Usage

```go
import "gitea.loveuer.com/loveuer/upkg/controller/file_manager"
```

#### Local Storage

```go
fm := file_manager.New(
    file_manager.WithDir("/path/to/uploads"),
    file_manager.WithTimeout(5*time.Minute),
    file_manager.WithExpire(24*time.Hour),
)
defer fm.CloseManager()
```

#### S3 Storage

```go
fm := file_manager.New(
    file_manager.WithS3(
        "http://minio:9000",
        "access-key",
        "secret-key",
        "bucket-name",
        "us-east-1",
    ),
    file_manager.WithS3PathStyle(true),
    file_manager.WithTimeout(10*time.Minute),
    file_manager.WithExpire(48*time.Hour),
)
defer fm.CloseManager()
```

#### API

```go
// Create creates a file record, returns code for upload
result, err := fm.Create(ctx, "filename.txt", 1024, "")

// Upload uploads file content
total, written, err := fm.Upload(ctx, code, 0, 1024, reader)

// Get retrieves file content
data, err := fm.Get(ctx, code)

// GetInfo returns file metadata
info, err := fm.GetInfo(ctx, code)

// Delete removes file
err := fm.Delete(ctx, code)

// Close closes file handle
err := fm.Close(code)

// CloseManager shuts down the manager
fm.CloseManager()
```

### Manifest Format (Local)

```json
{
  "filename": "file.txt",
  "size": 1024,
  "sha256": "abc123...",
  "path": "/uploads/abc123",
  "create_time": "2024-01-01T00:00:00Z",
  "complete": true
}
```

### S3 Object Metadata

- `x-amz-meta-filename`: Original filename
- `x-amz-meta-size`: File size
- `x-amz-meta-sha256`: SHA256 hash (optional)
- `x-amz-meta-create-time`: Creation timestamp
- `x-amz-meta-complete`: Upload completion status
- `x-amz-meta-code`: Unique file code

## logger

A lightweight, structured logging package for Go.

### Features

- **Simple API**: Format strings and structured fields
- **Global & Instance**: Use default global logger or create custom instances
- **Context Support**: Extract trace_id from context automatically
- **Multiple Formats**: Text (default) and JSON
- **Level Filtering**: DEBUG, INFO, WARN, ERROR, FATAL, PANIC
- **No Dependencies**: Standard library only
- **High Performance**: ~727 ns/op for text format, zero-allocation when filtered

### Quick Start

```go
import "gitea.loveuer.com/loveuer/upkg/logger"

// Global logger (default)
logger.Info("hello %s", "world")
logger.Error("failed: %v", err)

// With fields
logger.InfoField("user logged in",
    "user_id", 123,
    "action", "login",
)

// Context with trace_id
ctx := context.WithValue(ctx, "trace_id", "req-123")
logger.InfoCtx(ctx, "request processed")
```

### Custom Logger

```go
log := logger.New(
    logger.WithLevel(logger.DEBUG),
    logger.WithFormat(logger.JSON),
    logger.WithOutput(logger.Stdout),
    logger.WithCaller(true),
)

log.Info("custom logger")
log.InfoField("event", "key", "value")
```

### API

#### Level Methods

```go
log.Debug(format string, args ...)
log.Info(format string, args ...)
log.Warn(format string, args ...)
log.Error(format string, args ...)
log.Fatal(format string, args ...)
log.Panic(format string, args ...)
```

#### Context Methods

```go
log.InfoCtx(ctx, format string, args ...)
// Automatically adds trace_id from ctx as a field
```

#### Field Methods

```go
log.InfoField(message string, keyValues ...interface{})
// Example: log.InfoField("user created", "id", 123, "name", "john")
```

### Configuration Options

```go
logger.New(
    WithLevel(INFO),              // Minimum log level
    WithFormat(TEXT),             // TEXT or JSON
    WithOutput(Stdout),           // Stdout, Stderr, or use WithOutputFile
    WithOutputFile("/path/to.log"), // Write to file
    WithCaller(true),             // Include file:line in output
    WithFieldKey("trace_id"),     // Context field key name
    WithPrefix("myapp"),          // Text format prefix
    WithTimeFormat("2006-01-02"), // Custom time format
)
```

### Performance

| Benchmark | ns/op | B/op | allocs |
|-----------|-------|------|--------|
| Info (Text) | 727 | 319 | 6 |
| Info (JSON) | 1932 | 1026 | 18 |
| Info (Filtered) | 2 | 0 | 0 |
| InfoField | 1889 | 1014 | 14 |
| InfoWithCaller | 1772 | 856 | 11 |

### Text Format Output

```
2026-01-17 15:30:45 INFO hello world
2026-01-17 15:30:45 INFO user logged in user_id=123 action=login
```

### JSON Format Output

```json
{"time":"2026-01-17T15:30:45Z","level":"INFO","message":"hello world"}
{"time":"2026-01-17T15:30:45Z","level":"INFO","message":"user logged in","user_id":123,"action":"login"}
```

## Packages

| Package | Description |
|---------|-------------|
| `controller/file_manager` | File storage abstraction (local/S3) |
| `logger` | Structured logging package |

## License

MIT