media

README

togo-framework/media

Media library for togo — uploads, image conversions & thumbnails, attach media to any model.

Install

togo install togo-framework/media

media is togo's answer to Spatie Media Library / Rails Active Storage. Files are stored through the togo storage plugin (k.Storage), metadata is persisted, and you attach media to any model by (model_type, model_id, collection). Image uploads get conversions (e.g. thumb, preview) generated automatically.

How it works

• Blobs live in the storage plugin — install one: togo install togo-framework/storage-s3 (or r2 / gdrive / supabase).
• Metadata is stored in your DB when reachable (table media), otherwise in memory.
• On image upload, conversions are generated (default thumb 200×200 crop, preview 1024×1024 fit) and stored as derived files.
• Media is served back through REST routes (/api/media/...).

Usage

import "github.com/togo-framework/media"

m, _ := media.FromKernel(k)

// Attach an upload to a model.
rec, err := m.Attach(ctx, "User", userID, "avatar", "me.png", fileBytes)

// Fetch a model's media in a collection.
items, _ := m.Get(ctx, "User", userID, "avatar")

// Build URLs (original + conversions).
orig  := m.URL(rec, "")       // /api/media/<id>
thumb := m.URL(rec, "thumb")  // /api/media/<id>/thumb

// Read bytes directly, or delete (removes blobs + conversions).
data, _ := m.Bytes(rec, "thumb")
_ = m.Delete(ctx, rec.ID)

Custom conversions

m.SetConversions([]media.Conversion{
    {Name: "thumb", Width: 150, Height: 150, Fit: false},  // crop to fill
    {Name: "hero",  Width: 1600, Height: 900, Fit: true},  // fit within
})

REST API

Method	Path
POST	/api/media	multipart upload: model_type, model_id, collection, file
GET	/api/media?model_type=&model_id=&collection=	list a model's media
GET	/api/media/{id}	stream the original
GET	/api/media/{id}/{conversion}	stream a conversion (e.g. thumb)
DELETE	/api/media/{id}	delete (blobs + conversions)

Configuration

No required env. Install a storage provider for blobs and (optionally) a database for persistent metadata — media auto-detects both. Without a storage plugin, Attach returns a clear error; without a DB, metadata is kept in memory.

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package media is a media library for togo — upload files to the storage plugin, attach them to any model, and generate image conversions (thumbnails).

It is the togo answer to Spatie Media Library / Rails Active Storage: blobs live in the storage plugin (k.Storage); metadata + conversions are recorded so you can attach media to a model by (model_type, model_id, collection) and fetch it back with derived sizes.

m, _ := media.FromKernel(k)
rec, _ := m.Attach(ctx, "User", userID, "avatar", "me.png", bytes)
url := m.URL(rec, "thumb")

Index

• Variables
• type Conversion
• type Media
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func (s *Service) Attach(ctx context.Context, modelType, modelID, collection, name string, data []byte) (*Media, error)
  • func (s *Service) Bytes(m *Media, conversion string) ([]byte, error)
  • func (s *Service) Delete(ctx context.Context, id string) error
  • func (s *Service) Find(ctx context.Context, id string) (*Media, error)
  • func (s *Service) Get(ctx context.Context, modelType, modelID, collection string) ([]*Media, error)
  • func (s *Service) SetConversions(c []Conversion)
  • func (s *Service) URL(m *Media, conversion string) string
• type Store

Variables

var DefaultConversions = []Conversion{
	{Name: "thumb", Width: 200, Height: 200, Fit: false},
	{Name: "preview", Width: 1024, Height: 1024, Fit: true},
}

DefaultConversions are generated for image uploads unless overridden.

Types

type Conversion

type Conversion struct {
	Name   string
	Width  int
	Height int
	Fit    bool // true = Fit (preserve aspect within WxH); false = Thumbnail (crop to fill)
}

Conversion is a named image transformation applied on attach.

type Media

type Media struct {
	ID          string            `json:"id"`
	ModelType   string            `json:"model_type"`
	ModelID     string            `json:"model_id"`
	Collection  string            `json:"collection"`
	Disk        string            `json:"disk"`
	Path        string            `json:"path"`
	Name        string            `json:"name"`
	Mime        string            `json:"mime"`
	Size        int64             `json:"size"`
	Conversions map[string]string `json:"conversions,omitempty"` // conversion name → storage path
	Custom      map[string]any    `json:"custom,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
}

Media is a stored file attached to a model.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service is the media runtime stored on the kernel (k.Get("media")).

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel returns the media Service registered on the kernel.

func (*Service) Attach

func (s *Service) Attach(ctx context.Context, modelType, modelID, collection, name string, data []byte) (*Media, error)

Attach stores file bytes in the storage plugin, records the media row against (modelType, modelID, collection), and generates image conversions when the upload is an image.

func (*Service) Bytes

func (s *Service) Bytes(m *Media, conversion string) ([]byte, error)

Bytes reads the stored bytes for a media record (optionally a conversion).

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, id string) error

Delete removes a media record and its stored blobs (original + conversions).

func (*Service) Find

func (s *Service) Find(ctx context.Context, id string) (*Media, error)

Find returns a single media record by id.

func (*Service) Get

func (s *Service) Get(ctx context.Context, modelType, modelID, collection string) ([]*Media, error)

Get returns the media attached to a model in a collection.

func (*Service) SetConversions

func (s *Service) SetConversions(c []Conversion)

SetConversions overrides the image conversions generated on attach.

func (*Service) URL

func (s *Service) URL(m *Media, conversion string) string

URL returns the route that serves a media record (or a named conversion).

type Store

type Store interface {
	Save(ctx context.Context, m *Media) error
	List(ctx context.Context, modelType, modelID, collection string) ([]*Media, error)
	Get(ctx context.Context, id string) (*Media, error)
	Delete(ctx context.Context, id string) error
}

Store persists media metadata. The plugin uses a SQL-backed store when a DB is reachable, and an in-memory store otherwise.