wittyintegratedfilebrowser

package module
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: AGPL-3.0 Imports: 20 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

It is built by WittyModule's one builder (kit/web/build-bundle.mjs), found at ../WittyModule or wherever WITTYMODULE says.

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.

Module API 5, and every app

It is built for module API 5 (WittyMediaServer 0.8.0-alpha and later), and carries integration.json beside module.json and sdui.json. It claims no routes, data or lifecycle: the server keeps its folder route, GET /api/fs, calls this helper's places and list itself, checks every answer against the folder asked for, and names what kind of media each file is. Without this module, a folder's path is typed instead. The web part exports register(host), which claims nothing yet (WittyModule 0.5.2 has no hook for a folder picker), and its default export is the folder window that Settings, Libraries opens.

Its sdui.json is written from Go (ui/ui.go; go test ./ui -update-sdui writes it, and go test ./ui fails when it's out of date), so every app draws its screens natively, a TV's included:

  • Server folders (page wittyintegratedfilebrowser, under More in the menu, for administrators only): the server's drives and usual folders, each opening its folder; opened with ?name=<a folder's path>, where the folder is, Up, its folders (each opening its own page) and its files with their sizes. Read-only, and a folder on another machine (\\nas\share) is never opened. Anyone else sees a note that it's for administrators.
  • Data sources its helper answers (sdui.items), for administrators only: wittyintegratedfilebrowser.places, the drives and usual folders with the space left on each (offered in the page editor's gallery as Server drives and space), and wittyintegratedfilebrowser.folder (path), one folder.

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).

The files are checked with wittymodule check and described in WittyMediaServer's docs/MODULES-API5.md and 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.5.4 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

This section is empty.

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 Answers added in v0.4.0

func Answers(places func() []Place) sdui.Answers

Answers answers the server's SDUI calls; places are where to start (PlacesFor).

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.

func Items added in v0.4.0

func Items(r sdui.ItemsRequest, places func() []Place) (sdui.ItemsAnswer, error)

Items answers one of the module's sources.

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 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.
Package ui is WittyIntegratedFileBrowser's server-driven UI (sdui.json), written from Go so the file and the code answering its sources can't drift: `go test ./ui -update-sdui` writes it.
Package ui is WittyIntegratedFileBrowser's server-driven UI (sdui.json), written from Go so the file and the code answering its sources can't drift: `go test ./ui -update-sdui` writes it.

Jump to

Keyboard shortcuts

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