mirror of
https://github.com/yusing/godoxy.git
synced 2026-02-22 18:37:46 +01:00
6da7227f9b
This is a large-scale refactoring across the codebase that replaces the custom `gperr.Error` type with Go's standard `error` interface. The changes include: - Replacing `gperr.Error` return types with `error` in function signatures - Using `errors.New()` and `fmt.Errorf()` instead of `gperr.New()` and `gperr.Errorf()` - Using `%w` format verb for error wrapping instead of `.With()` method - Replacing `gperr.Subject()` calls with `gperr.PrependSubject()` - Converting error logging from `gperr.Log*()` functions to zerolog's `.Err().Msg()` pattern - Update NewLogger to handle multiline error message - Updating `goutils` submodule to latest commit This refactoring aligns with Go idioms and removes the dependency on custom error handling abstractions in favor of standard library patterns.
Homepage Widgets Package
Warning
This package is a work in progress and is not stable.
This package provides a widget framework for the GoDoxy homepage dashboard, enabling integration with various service providers to display real-time data.
Overview
The internal/homepage/widgets package defines the widget interface and common utilities for building homepage widgets. It provides a standardized way to integrate external services into the homepage dashboard.
Architecture
Core Components
widgets/
├── widgets.go # Widget interface and config
└── http.go # HTTP client and error definitions
Data Types
type Config struct {
Provider string `json:"provider"`
Config Widget `json:"config"`
}
type Widget interface {
Initialize(ctx context.Context, url string, cfg map[string]any) error
Data(ctx context.Context) ([]NameValue, error)
}
type NameValue struct {
Name string `json:"name"`
Value string `json:"value"`
}
Constants
const (
WidgetProviderQbittorrent = "qbittorrent"
)
Errors
var ErrInvalidProvider = errors.New("invalid provider")
API Reference
Widget Interface
type Widget interface {
// Initialize sets up the widget with connection configuration
Initialize(ctx context.Context, url string, cfg map[string]any) error
// Data returns current widget data as name-value pairs
Data(ctx context.Context) ([]NameValue, error)
}
Configuration
Config.UnmarshalMap
Parses widget configuration from a map.
func (cfg *Config) UnmarshalMap(m map[string]any) error
Parameters:
m- Map containingproviderandconfigkeys
Returns:
error- Parsing or validation error
Example:
widgetCfg := widgets.Config{}
err := widgetCfg.UnmarshalMap(map[string]any{
"provider": "qbittorrent",
"config": map[string]any{
"username": "admin",
"password": "password123",
},
})
HTTP Client
var HTTPClient = &http.Client{
Timeout: 10 * time.Second,
}
Available Providers
- qbittorrent - qBittorrent torrent client integration (WIP)
Usage Example
Creating a Custom Widget
package mywidget
import (
"context"
"github.com/yusing/godoxy/internal/homepage/widgets"
)
type MyWidget struct {
URL string
APIKey string
}
func (m *MyWidget) Initialize(ctx context.Context, url string, cfg map[string]any) error {
m.URL = url
m.APIKey = cfg["api_key"].(string)
return nil
}
func (m *MyWidget) Data(ctx context.Context) ([]widgets.NameValue, error) {
// Fetch data and return as name-value pairs
return []widgets.NameValue{
{Name: "Status", Value: "Online"},
{Name: "Uptime", Value: "24h"},
}, nil
}
Registering the Widget
// In widgets initialization
widgetProviders["mywidget"] = struct{}{}
Using the Widget in Homepage
// Fetch widget data
widget := getWidget("qbittorrent")
data, err := widget.Data(ctx)
if err != nil {
log.Fatal(err)
}
// Display data
for _, nv := range data {
fmt.Printf("%s: %s\n", nv.Name, nv.Value)
}
Integration with Homepage
graph TD
A[Homepage Dashboard] --> B[Widget Config]
B --> C[Widget Factory]
C --> D{Provider Type}
D -->|qbittorrent| E[qBittorrent Widget]
D -->|custom| F[Custom Widget]
E --> G[Initialize]
F --> G
G --> H[Data Fetch]
H --> I[Render UI]
Related Packages
internal/homepage/integrations/qbittorrent- qBittorrent widget implementationinternal/serialization- Configuration unmarshaling utilitiesgithub.com/yusing/goutils/errs- Error handling