wittyintegratedfilebrowser

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

README

WittyIntegratedFileBrowser

Lets you choose a server's folders from any device. A browser's own folder window only sees the device it runs on, so without this a phone or a TV can't pick folders on the server, and you type the path instead.

Choosing a folder on the server, in the page

Browsing the server's folders from the browser.

What it does

  • Places: drives with their label and free space, Home, Videos, Music and the rest, plus places an app adds, such as folders already in use.
  • Getting around: back, forward, up, a clickable path that turns into a text box (network paths too), and recently chosen folders.
  • Seeing what's there: files with their kind, DVD and Blu-ray folders marked, sizes, dates, a count of what's inside, and hidden items on request. A very large folder stops at 3,000 entries unless the app sets another limit.
  • Choosing: the folder you're in, or tick several and use them all.
  • Every way of using it: keyboard (arrows, Enter, Space, Backspace, / to filter, Ctrl+L for the path), touch, mouse and screen readers, with a full-screen layout on phones.
  • In Docker and other containers: when a folder can't be opened, or a mount point looks empty, it says which user and group the server runs as and who owns the folder, with a link to fixing it on UGREEN, Synology, QNAP, Unraid, TrueNAS SCALE, Asustor or plain Linux. Outside a container it says nothing of the kind.
  • It only reads. Nothing is created, renamed or deleted.

The folder window in the app, and naming what kind of media each file is, stay with the server. If a version can't read a folder, the server tries it itself.

How to use it is in Help inside WittyMediaServer: see Getting started.

How to get it

An admin adds it from the module store inside WittyMediaServer: Settings → Modules, then Browse the store, then Add beside WittyIntegratedFileBrowser. That needs WittyMediaServer 0.6.0-alpha or later, and it works with nothing older. The range this version fits is in module.json: 0.6.0-alpha through 0.6.x.

What it needs

WittyModule, which is how a server talks to it, and golang.org/x/sys, both built in. The window in web/ is React and uses the app's theme. It's written in Go with no cgo.

If you use it in another app, put the Go half behind that app's sign-in.

Platforms

A program is built for each system below, and the server uses the right one.

System Where it stands
Linux (x64, arm64, 32-bit ARM, x86) Its tests pass on x64. The other CPUs are only built
Windows (x64, arm64) Built. This version hasn't been run on Windows since it became its own program
macOS (Intel, Apple silicon) Built by the release tool. It has not been run on a real Mac
FreeBSD (amd64, arm64) Cross-compiled only. It has not been run

On macOS and FreeBSD the server has no sandbox for a module's helper: it gets a small environment and a soft memory limit, and nothing more.

The window is one browser bundle for every system.

Building and testing

You need Go 1.26 or newer. In a worktree, first run the copy of dev-modules.mjs kept above the repositories (node D:/projects/dev-modules.mjs on the development machine). It writes a go.work that git ignores, so the checkout builds against the repositories beside it. Never run go work use.

go vet ./...
go test ./... -count=1
go run github.com/wittywilla/wittymodule/cmd/wittymodule check .

The last one checks the manifest. On the same tool, pack -targets linux/amd64 -out release . builds a release for one system. CI also builds for every system.

The browser half builds with Node.js:

npm install
npm run build:bundle

To use it in another app, Places(extra...) says where to start, and List(path, Options) gives a folder's folders and files, with ErrNotFound and ErrDenied. Serve both as JSON for the React window in web/, which takes list, onPick and onClose. When a folder can't be read, Explain(path) (the helper's access call) says why in a container, or nil; send it as access beside the listing, or in the error's data, and the window shows it. The checks that need a container and another user are in docs/TESTING.md.

Licence

GNU Affero General Public License v3.0 (or later): see LICENSE and NOTICE. If you redistribute it or build on it, please keep the NOTICE attribution. Each release archive carries a THIRD-PARTY-NOTICES.txt for what its programs link.

In every app: its server-driven UI

It carries its own sdui.json: its theme scope, and a data source its helper answers, wittyintegratedfilebrowser.places: the server's drives and usual folders with the space left on each, for administrators only, offered in the page editor's gallery as Server drives and space.

Stays in its own code: the folder window itself (places, filter, multi-select, disc folders marked, and help when a folder can't be read), which opens from Settings, Libraries.

The file is checked with wittymodule check and described in WittyMediaServer's docs/SDUI-MODULES.md.

WittyIntegratedFileBrowser is an independent open-source project. It isn't associated with, sponsored by or endorsed by any publisher, rights holder, service or other media software project. It lists folders on the machine it runs on, and doesn't provide or check what's in them. Any third-party names here only describe what it works with, and belong to their owners. It's provided “as is”, with no warranty; see LICENSE. Local law applies to how you use it. This isn't legal advice.

Releasing

A version tag builds a program for every platform, signs the checksum list, and publishes a release that servers can install.

Versions move in small steps as work lands. go run github.com/wittywilla/wittymodule/cmd/wittymodule@v0.4.0 bump . raises it everywhere it is written (add -part minor for a bigger step). A bump isn't a release: nothing is tagged or published until you tag it. CI fails when code changed since the last tag and the version didn't, because tags never move.

To release:

  1. Check that version in module.json is the one to publish, with the bump committed.
  2. Tag that commit and push the tag: git tag vX.Y.Z, then git push origin vX.Y.Z. A tag with a suffix, such as v1.2.0-beta, is published as a prerelease.
  3. Watch the Actions tab. The signing step uses the WMS_SIGNING_KEY secret of the release environment, and nothing is published without it.

To take a version back, run the withdraw workflow from the Actions tab. It adds the version to a signed list on the release tagged withdrawals, which servers read.

Licensed under AGPL-3.0-or-later: see LICENSE and NOTICE.

Documentation

Overview

Package wittyintegratedfilebrowser lists a computer's drives, folders and files for a folder browser shown in a web page, so folders can be chosen from another device than the one holding them. It only reads: nothing is created, renamed or deleted.

Index

Constants

View Source
const PlacesSource = "wittyintegratedfilebrowser.places"

PlacesSource is the source's type.

Variables

View Source
var (
	// ErrNotFound: the path does not exist (or cannot be seen).
	ErrNotFound = errors.New("folder not found")
	// ErrDenied: the folder exists but cannot be opened.
	ErrDenied = errors.New("not allowed to open this folder")
)
View Source
var InContainer = func() bool {
	if os.Getenv("WITTYMODULE_CONTAINER") != "" || os.Getenv("WMS_DOCKER") == "1" {
		return true
	}
	return exists("/.dockerenv") || exists("/run/.containerenv")
}

InContainer says whether this runs in a container (Docker, Podman and the like), where a folder the server can't read is most often a user and group mapping that doesn't match the folder's owner. The host may say so (WITTYMODULE_CONTAINER, or WMS_DOCKER from WittyMediaServer's image); a helper isn't given those today, so the files container engines leave at the root tell it instead. A variable, so tests can say either.

View Source
var ManifestJSON []byte

ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").

Functions

func DiscFolder

func DiscFolder(p string) string

DiscFolder says whether a folder holds a disc's structure: "dvd" for a VIDEO_TS folder (or one holding it), "bluray" for BDMV, else "".

func FileKind

func FileKind(name string) string

FileKind classifies a file by its extension: video, audio, book, disc, subtitle, image or other.

func IsHidden

func IsHidden(name string) bool

IsHidden: dot-files, $-folders and Windows system folders nobody keeps media in.

Types

type Entry

type Entry struct {
	Name     string `json:"name"`
	Path     string `json:"path"`
	Dir      bool   `json:"dir"`
	Kind     string `json:"kind,omitempty"` // files: what Options.Kind says (video, audio, book, disc, subtitle, image, other)
	Disc     string `json:"disc,omitempty"` // folders holding a DVD (VIDEO_TS) or Blu-ray (BDMV): "dvd" or "bluray"
	Size     int64  `json:"size,omitempty"`
	Modified int64  `json:"modified,omitempty"` // Unix seconds
	Hidden   bool   `json:"hidden,omitempty"`
}

Entry is one folder or file in a listing.

type Item added in v0.3.0

type Item struct {
	ID       string `json:"id"`
	Kind     string `json:"kind"`
	Title    string `json:"title"`
	Subtitle string `json:"subtitle,omitempty"`
	Icon     string `json:"icon,omitempty"`
}

Item is one card, in the server's SDUI item shape.

type ItemsAnswer added in v0.3.0

type ItemsAnswer struct {
	Items []Item `json:"items"`
	More  bool   `json:"more"`
	Total int    `json:"total"`
}

ItemsAnswer is the answer to sdui.items.

func PlaceItems added in v0.3.0

func PlaceItems(r ItemsRequest, places []Place) (ItemsAnswer, error)

PlaceItems answers the places source. Where folders are on the server is for its administrators only, so anyone else is answered with nothing.

type ItemsRequest added in v0.3.0

type ItemsRequest struct {
	Source map[string]any `json:"source"`
	Offset int            `json:"offset"`
	Limit  int            `json:"limit"`
	Viewer struct {
		Admin bool `json:"admin"`
	} `json:"viewer"`
}

ItemsRequest is the part of the server's sdui.items call this module reads.

func ParseItemsRequest added in v0.3.0

func ParseItemsRequest(raw json.RawMessage) (ItemsRequest, error)

ParseItemsRequest reads an sdui.items call's parameters.

type Listing

type Listing struct {
	Path      string         `json:"path"`
	Parent    *string        `json:"parent"` // nil at a drive's root
	Sep       string         `json:"sep"`
	Entries   []Entry        `json:"entries"`
	Counts    map[string]int `json:"counts"` // "folder" and each file kind
	Truncated bool           `json:"truncated"`
}

Listing is a folder's contents.

func List

func List(path string, o Options) (*Listing, error)

List returns a folder's folders and files, folders first, by name. A path to a file lists the folder holding it; "D:" means the drive's root.

type Note added in v0.3.0

type Note struct {
	// Why: "denied" when the folder can't be opened, "empty-mount" when it is a
	// mount point that looks empty to the server.
	Why string `json:"why"`
	// Folder is the one in the way: the folder asked for, or a folder above it
	// that the server isn't allowed to go through.
	Folder   string `json:"folder"`
	UID      int    `json:"uid"`
	GID      int    `json:"gid"`
	Groups   []int  `json:"groups,omitempty"` // the server's other groups
	OwnerUID int    `json:"ownerUid"`
	OwnerGID int    `json:"ownerGid"`
}

Note says why a folder may not be readable when the server runs in a container: the user and group the server runs as, and who owns the folder in the way, so the two can be compared. It holds numbers only; the page words it and links to the fix.

func Explain added in v0.3.0

func Explain(path string) *Note

Explain says why a folder can't be read, or nil when there is nothing worth saying: outside a container, for a folder that opens and has something in it, or one that isn't there. It reads at most one name from the folder, so it is quick on a large or slow one.

type Options

type Options struct {
	ShowHidden bool                     // include dot-files and system folders
	MaxEntries int                      // 0 = 3000
	Kind       func(name string) string // classifies files; nil = FileKind
}

Options change a listing.

type Place

type Place struct {
	Name  string `json:"name"`
	Path  string `json:"path"`
	Group string `json:"group"` // drives, folders, or the host's own group name
	Label string `json:"label,omitempty"`
	Free  uint64 `json:"free,omitempty"`
	Total uint64 `json:"total,omitempty"`
}

Place is somewhere to start browsing: a drive, a usual folder, or one the host adds (such as folders already in use).

func Places

func Places(extra ...Place) []Place

Places lists where to start: the drives (with their free space), the user's usual folders, then extra in the order given. Only places that exist are returned.

func PlacesFor added in v0.2.0

func PlacesFor(home string, extra ...Place) []Place

PlacesFor is Places for a given home folder, for a process that is not told its own. An empty home leaves out the usual folders.

Directories

Path Synopsis
cmd
wittyintegratedfilebrowser-module command
Command wittyintegratedfilebrowser-module is WittyIntegratedFileBrowser as a helper process, so a new version can reach a server without a new server.
Command wittyintegratedfilebrowser-module is WittyIntegratedFileBrowser as a helper process, so a new version can reach a server without a new server.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL