223 lines
5.1 KiB
Markdown
223 lines
5.1 KiB
Markdown
# 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
|