README
¶
Drive Plugin for Nimbus
Unified file storage across local filesystem, S3, GCS, R2, Spaces, and Supabase. Inspired by AdonisJS Drive.
Installation
Drive is a default plugin when creating a new app with nimbus new. To add manually:
nimbus add drive
Or in bin/server.go:
import "github.com/CodeSyncr/nimbus/plugins/drive"
app.Use(drive.New(nil)) // nil = ConfigFromEnv()
Configuration
Environment-based (recommended)
Set DRIVE_DISK and provider-specific vars in .env:
| Variable | Description | Default |
|---|---|---|
DRIVE_DISK |
Default disk: fs, s3, gcs, r2, spaces, supabase |
fs |
Local (fs): No extra vars. Uses storage/ by default.
Amazon S3:
DRIVE_DISK=s3
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=us-east-1
S3_BUCKET=
Cloudflare R2:
DRIVE_DISK=r2
R2_KEY=
R2_SECRET=
R2_BUCKET=
R2_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
DigitalOcean Spaces:
DRIVE_DISK=spaces
SPACES_KEY=
SPACES_SECRET=
SPACES_REGION=nyc3
SPACES_BUCKET=
SPACES_ENDPOINT=https://<region>.digitaloceanspaces.com
Google Cloud Storage:
DRIVE_DISK=gcs
GCS_BUCKET=
GCS_KEY=file://path/to/service-account.json
Supabase Storage:
DRIVE_DISK=supabase
SUPABASE_STORAGE_KEY=
SUPABASE_STORAGE_SECRET=
SUPABASE_STORAGE_REGION=
SUPABASE_STORAGE_BUCKET=
SUPABASE_ENDPOINT=https://<project>.supabase.co/storage/v1/s3
Code-based config
app.Use(drive.New(&drive.Config{
Default: "fs",
Disks: map[string]drive.DiskConfig{
"fs": {
Driver: "fs",
Location: "storage",
ServeFiles: true,
RouteBasePath: "/uploads",
},
"s3": {
Driver: "s3",
S3Bucket: "my-bucket",
S3Region: "us-east-1",
S3AccessKey: "...",
S3SecretKey: "...",
},
},
}))
Usage
import "github.com/CodeSyncr/nimbus/plugins/drive"
func uploadHandler(c *http.Context) error {
disk, err := drive.Use("") // default disk
if err != nil {
return err
}
file, _, _ := c.Request.FormFile("avatar")
defer file.Close()
err = disk.Put("avatars/1.jpg", file)
if err != nil {
return err
}
url, _ := disk.GetUrl("avatars/1.jpg")
return c.JSON(200, map[string]string{"url": url})
}
Disk operations
| Method | Description |
|---|---|
disk.Put(path, reader) |
Write file |
disk.Get(path) |
Read file (returns io.ReadCloser) |
disk.Delete(path) |
Remove file |
disk.Exists(path) |
Check existence |
disk.GetUrl(path) |
Public URL |
disk.GetSignedUrl(path, expiresIn) |
Temporary signed URL (private) |
Serving local files
When using the fs driver with ServeFiles: true and RouteBasePath: "/uploads", files are served at /uploads/*. Example: disk.GetUrl("avatars/1.jpg") → /uploads/avatars/1.jpg.
Documentation
¶
Index ¶
- Variables
- func ContentType(path string) string
- func SafePath(path string) (string, error)
- func SetGlobal(manager *Manager)
- type Config
- type Disk
- type DiskConfig
- type FSDisk
- func (d *FSDisk) Delete(path string) error
- func (d *FSDisk) Exists(path string) (bool, error)
- func (d *FSDisk) Get(path string) (io.ReadCloser, error)
- func (d *FSDisk) GetSignedUrl(path string, expiresIn time.Duration) (string, error)
- func (d *FSDisk) GetUrl(path string) (string, error)
- func (d *FSDisk) Put(path string, src io.Reader) error
- type Manager
- type Plugin
- type Visibility
Constants ¶
This section is empty.
Variables ¶
var ErrDriveNotRegistered = errors.New("drive: plugin not registered or app not booted")
Functions ¶
func ContentType ¶
ContentType returns a MIME type for the path based on extension.
Types ¶
type Config ¶
type Config struct {
// Default is the default disk name (fs, s3, gcs, r2, spaces, supabase).
Default string
// Disks holds per-disk configuration.
Disks map[string]DiskConfig
}
Config holds Drive plugin configuration.
func ConfigFromEnv ¶
func ConfigFromEnv() Config
ConfigFromEnv builds Config from environment variables. Adds disks for each provider that has required env vars set.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns default Drive configuration (fs only).
type Disk ¶
type Disk interface {
// Put writes content to the given path/key.
Put(path string, src io.Reader) error
// Get returns a reader for the file at path. Caller must close it.
Get(path string) (io.ReadCloser, error)
// Delete removes the file at path.
Delete(path string) error
// Exists returns true if the file exists.
Exists(path string) (bool, error)
// GetUrl returns the public URL for the file (public visibility).
// For local fs with serveFiles, returns path like /uploads/key.
// For S3/GCS, returns the full URL.
GetUrl(path string) (string, error)
// GetSignedUrl returns a temporary signed URL (private visibility).
// expiresIn is the duration until the URL expires.
GetSignedUrl(path string, expiresIn time.Duration) (string, error)
}
Disk is the interface for file storage operations.
func Use ¶
Use returns the disk with the given name. Empty name uses the default disk. Returns nil, err if Drive plugin is not registered or disk not found.
func UseDefault ¶
UseDefault returns the default disk (same as Use("")).
type DiskConfig ¶
type DiskConfig struct {
Driver string // "fs", "s3", "gcs"
Visibility Visibility // "public" or "private"
// FS driver
Location string // root directory for local storage
ServeFiles bool // register route to serve files via HTTP
RouteBasePath string // URL path prefix, e.g. "/uploads"
// S3 driver (also used for R2, Spaces, Supabase - S3-compatible)
S3Bucket string
S3Region string
S3AccessKey string
S3SecretKey string
S3Endpoint string // for S3-compatible (MinIO, R2, Spaces)
S3ForcePathStyle bool
// GCS driver
GCSBucket string
GCSKey string // path to service account JSON, e.g. file://gcs_key.json
}
DiskConfig is the configuration for a single disk.
type FSDisk ¶
type FSDisk struct {
// contains filtered or unexported fields
}
FSDisk implements Disk for local filesystem storage.
func (*FSDisk) Get ¶
func (d *FSDisk) Get(path string) (io.ReadCloser, error)
Get returns a reader for the file.
func (*FSDisk) GetSignedUrl ¶
GetSignedUrl returns a temporary URL. For local fs, we just return the public URL since we don't have signed URL support. In production with private files, you'd want to generate a token-based URL.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager holds disks and provides access.
func NewManager ¶
NewManager creates a manager with the given config.
func (*Manager) UseDefault ¶
UseDefault returns the default disk.
type Plugin ¶
type Plugin struct {
nimbus.BasePlugin
// contains filtered or unexported fields
}
Plugin integrates Drive file storage into Nimbus.
func (*Plugin) RegisterRoutes ¶
RegisterRoutes mounts the file serving route when ServeFiles is true.
type Visibility ¶
type Visibility string
Visibility determines file access: public (URL) or private (signed URL only).
const ( VisibilityPublic Visibility = "public" VisibilityPrivate Visibility = "private" )
Source Files