jacob1123/docspell-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add read-only Docspell FUSE mount

Browse Source
This commit is contained in:
Jan Bader
2026-07-13 22:58:59 +02:00
parent c8219ed79b
commit 952d3d8532
7 changed files with 514 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+26
View File
@@ -21,3 +21,29 @@ Das Programm:
## Konfiguration
Erstellen Sie eine `docspell-import.json` Datei in Ihrem Home-Verzeichnis: [Beispiel-Konfiguration](./docspell-import-example.json)
## Read-only FUSE mount
The `mount` subcommand exposes a Docspell collection as a read-only filesystem.
It uses the same `~/docspell-import.json` configuration and password command as the import command.
```bash
mkdir -p ~/mnt/docspell
docspell-import mount --query '*' ~/mnt/docspell
# unmount when done
fusermount -u ~/mnt/docspell
```
Mounted files are grouped as:
```text
<Docspell folder>/<year>/<month>/<attachment name>
```
Options:
- `--query`: Docspell item query to expose, default `*`.
- `--limit`: number of items fetched per API request, default `1000`.
- `--auth-header`: token header, default `X-Docspell-Auth`.
The mount is read-only. File contents are downloaded lazily from `/api/v1/sec/attachment/{id}` when read.
docspell_client.go
+198
View File
@@ -0,0 +1,198 @@
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"path"
"strings"
"time"
)
const defaultDocspellAuthHeader = "X-Docspell-Auth"
type DocspellClient struct {
BaseURL string
Token string
AuthHeader string
HTTPClient *http.Client
}
type loginResponse struct {
Success bool `json:"success"`
Message string `json:"message"`
Token string `json:"token"`
RequireSecondFactor bool `json:"requireSecondFactor"`
}
type searchResponse struct {
Groups []struct {
Items []SearchItem `json:"items"`
} `json:"groups"`
Limit int `json:"limit"`
Offset int `json:"offset"`
LimitCapped bool `json:"limitCapped"`
}
type SearchItem struct {
ID string `json:"id"`
Name string `json:"name"`
State string `json:"state"`
Date int64 `json:"date"`
ItemDate int64 `json:"itemDate"`
Attachments []ItemAttachment `json:"attachments"`
Folder *DocspellEntity `json:"folder"`
CorrOrg *DocspellEntity `json:"corrOrg"`
CorrPerson *DocspellEntity `json:"corrPerson"`
Tags []DocspellTag `json:"tags"`
}
type ItemAttachment struct {
ID string `json:"id"`
Name string `json:"name"`
Size int64 `json:"size"`
ContentType string `json:"contentType"`
Converted bool `json:"converted"`
Position int `json:"position"`
}
type DocspellTag struct {
ID string `json:"id"`
Name string `json:"name"`
Category string `json:"category"`
Created int64 `json:"created"`
}
func NewDocspellClient(baseURL, authHeader string) *DocspellClient {
if authHeader == "" {
authHeader = defaultDocspellAuthHeader
}
return &DocspellClient{
BaseURL: strings.TrimRight(baseURL, "/"),
AuthHeader: authHeader,
HTTPClient: &http.Client{Timeout: 60 * time.Second},
}
}
func (c *DocspellClient) Login(ctx context.Context, account, password string) error {
var out loginResponse
err := c.doJSON(ctx, http.MethodPost, "/api/v1/open/auth/login", map[string]any{
"account": account,
"password": password,
}, &out)
if err != nil {
return err
}
if !out.Success {
return fmt.Errorf("login failed: %s", out.Message)
}
if out.RequireSecondFactor {
return fmt.Errorf("login requires a second factor; token-based mounting is not implemented")
}
if out.Token == "" {
return fmt.Errorf("login response did not include a token")
}
c.Token = out.Token
return nil
}
func (c *DocspellClient) SearchItems(ctx context.Context, query string, limit int) ([]SearchItem, error) {
if limit <= 0 {
limit = 1000
}
var all []SearchItem
for offset := 0; ; offset += limit {
var out searchResponse
err := c.doJSON(ctx, http.MethodPost, "/api/v1/sec/item/search", map[string]any{
"query": query,
"offset": offset,
"limit": limit,
"withDetails": true,
"searchMode": "normal",
}, &out)
if err != nil {
return nil, err
}
count := 0
for _, group := range out.Groups {
all = append(all, group.Items...)
count += len(group.Items)
}
if count == 0 || count < limit {
return all, nil
}
}
}
func (c *DocspellClient) GetItem(ctx context.Context, id string) (*SearchItem, error) {
var out SearchItem
if err := c.doJSON(ctx, http.MethodGet, "/api/v1/sec/item/"+url.PathEscape(id), nil, &out); err != nil {
return nil, err
}
return &out, nil
}
func (c *DocspellClient) DownloadAttachment(ctx context.Context, id string) ([]byte, error) {
return c.doBytes(ctx, http.MethodGet, "/api/v1/sec/attachment/"+url.PathEscape(id), nil)
}
func (c *DocspellClient) doJSON(ctx context.Context, method, apiPath string, in any, out any) error {
var body io.Reader
if in != nil {
buf, err := json.Marshal(in)
if err != nil {
return err
}
body = bytes.NewReader(buf)
}
req, err := http.NewRequestWithContext(ctx, method, c.url(apiPath), body)
if err != nil {
return err
}
if in != nil {
req.Header.Set("Content-Type", "application/json")
}
data, err := c.do(req)
if err != nil {
return err
}
if out == nil {
return nil
}
return json.Unmarshal(data, out)
}
func (c *DocspellClient) doBytes(ctx context.Context, method, apiPath string, body io.Reader) ([]byte, error) {
req, err := http.NewRequestWithContext(ctx, method, c.url(apiPath), body)
if err != nil {
return nil, err
}
return c.do(req)
}
func (c *DocspellClient) do(req *http.Request) ([]byte, error) {
if c.Token != "" {
req.Header.Set(c.AuthHeader, c.Token)
}
resp, err := c.HTTPClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
data, err := io.ReadAll(resp.Body)
if err != nil {
return nil, err
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return nil, fmt.Errorf("%s %s: %s: %s", req.Method, req.URL, resp.Status, strings.TrimSpace(string(data)))
}
return data, nil
}
func (c *DocspellClient) url(apiPath string) string {
return c.BaseURL + path.Clean("/"+apiPath)
}
go.mod
+4
View File
@@ -1,3 +1,7 @@
module git.javil.eu/jacob1123/docspell-import
go 1.23.4
require bazil.org/fuse v0.0.0-20230120002735-62a210ff1fd5
require golang.org/x/sys v0.4.0 // indirect
go.sum
+6
View File
@@ -0,0 +1,6 @@
bazil.org/fuse v0.0.0-20230120002735-62a210ff1fd5 h1:A0NsYy4lDBZAC6QiYeJ4N+XuHIKBpyhAVRMHRQZKTeQ=
bazil.org/fuse v0.0.0-20230120002735-62a210ff1fd5/go.mod h1:gG3RZAMXCa/OTes6rr9EwusmR1OH1tDDy+cg9c5YliY=
github.com/tv42/httpunix v0.0.0-20191220191345-2ba4b9c3382c h1:u6SKchux2yDvFQnDHS3lPnIRmfVJ5Sxy3ao2SIdysLQ=
github.com/tv42/httpunix v0.0.0-20191220191345-2ba4b9c3382c/go.mod h1:hzIxponao9Kjc7aWznkXaL4U4TWaDSs8zcsY4Ka08nM=
golang.org/x/sys v0.4.0 h1:Zr2JFtRQNX3BCZ8YtxRE9hNJYC8J6I1MVbMg6owUp18=
golang.org/x/sys v0.4.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
main.go
+28 -10
View File
@@ -37,16 +37,26 @@ type DocspellItem struct {
func main() {
fmt.Println("##################### START #####################")
fmt.Println(" Docspell Import - v0.2")
fmt.Println(" Docspell Import - v0.3")
fmt.Println(" by jacob1123")
fmt.Println(" (based on work by totti4ever) ")
fmt.Println("#################################################")
fmt.Println()
uploadMissing := flag.Bool("upload-missing", os.Getenv("DS_CC_UPLOAD_MISSING") == "true", "true, to upload files to docspell that do not yet exist there")
flag.Parse()
cfg, password := loadConfigAndPassword()
// Read config from user profile
if len(os.Args) > 1 && os.Args[1] == "mount" {
if err := runMountCommand(os.Args[2:], cfg, password); err != nil {
fmt.Fprintln(os.Stderr, "mount failed:", err)
os.Exit(1)
}
return
}
runImportCommand(cfg, password, os.Args[1:])
}
func loadConfigAndPassword() (config, string) {
homeDir, err := os.UserHomeDir()
if err != nil {
fmt.Println("Error getting user home directory:", err)
@@ -66,7 +76,6 @@ func main() {
os.Exit(1)
}
// Get password from command
cmd := exec.Command(cfg.PasswordCommand, cfg.PasswordCommandArgs...)
password, err := cmd.Output()
if err != nil {
@@ -74,10 +83,20 @@ func main() {
os.Exit(1)
}
return cfg, strings.TrimSpace(string(password))
}
func runImportCommand(cfg config, password string, args []string) {
importFlags := flag.NewFlagSet("import", flag.ExitOnError)
uploadMissing := importFlags.Bool("upload-missing", os.Getenv("DS_CC_UPLOAD_MISSING") == "true", "true, to upload files to docspell that do not yet exist there")
if err := importFlags.Parse(args); err != nil {
fmt.Println("Error parsing flags:", err)
os.Exit(1)
}
validateConfig(cfg)
// Login
loginCmd := exec.Command("dsc", "login", "--user", cfg.User, "--password", strings.TrimSpace(string(password)))
loginCmd := exec.Command("dsc", "login", "--user", cfg.User, "--password", password)
if err := loginCmd.Run(); err != nil {
fmt.Println("Login failed:", err)
os.Exit(0)
@@ -102,7 +121,7 @@ func main() {
fmt.Printf("Scanning folder '%s'\n", dsConsumedir)
fmt.Println()
err = filepath.Walk(dsConsumedir, func(path string, info os.FileInfo, err error) error {
err := filepath.Walk(dsConsumedir, func(path string, info os.FileInfo, err error) error {
if err != nil {
return err
}
@@ -114,7 +133,6 @@ func main() {
fmt.Println()
fmt.Printf("%s:\n", info.Name())
// Check if file exists in Docspell
cmd := exec.Command("dsc", "-f", "json", "file-exists", path)
output, err := cmd.Output()
if err != nil {
@@ -128,7 +146,7 @@ func main() {
return nil
}
if fileExistsResponse[0].Exists {
if len(fileExistsResponse) > 0 && fileExistsResponse[0].Exists {
err := handleExistingFile(cfg, fileExistsResponse[0])
if err != nil {
fmt.Println(" ERROR", err)
mount.go
+199
View File
@@ -0,0 +1,199 @@
package main
import (
"context"
"flag"
"fmt"
"os"
"path/filepath"
"sort"
"strings"
"time"
"bazil.org/fuse"
"bazil.org/fuse/fs"
)
type docspellFS struct {
root *dirNode
}
type dirNode struct {
name string
children map[string]fs.Node
}
type fileNode struct {
name string
attachmentID string
size uint64
modTime time.Time
client *DocspellClient
data []byte
}
func runMountCommand(args []string, cfg config, password string) error {
fsFlags := flag.NewFlagSet("mount", flag.ExitOnError)
query := fsFlags.String("query", "*", "Docspell item query to expose")
limit := fsFlags.Int("limit", 1000, "number of items to fetch per API request")
authHeader := fsFlags.String("auth-header", defaultDocspellAuthHeader, "HTTP header used for the Docspell auth token")
if err := fsFlags.Parse(args); err != nil {
return err
}
if fsFlags.NArg() != 1 {
return fmt.Errorf("usage: %s mount [flags] <mountpoint>", filepath.Base(os.Args[0]))
}
client := NewDocspellClient(cfg.DocspellURL, *authHeader)
if err := client.Login(context.Background(), cfg.User, password); err != nil {
return err
}
items, err := client.SearchItems(context.Background(), *query, *limit)
if err != nil {
return fmt.Errorf("search items: %w", err)
}
root := buildMountTree(client, items)
conn, err := fuse.Mount(
fsFlags.Arg(0),
fuse.FSName("docspell"),
fuse.Subtype("docspell-import"),
fuse.ReadOnly(),
)
if err != nil {
return err
}
defer conn.Close()
fmt.Printf("Mounted %d items read-only at %s. Unmount with: fusermount -u %s\n", len(items), fsFlags.Arg(0), fsFlags.Arg(0))
return fs.Serve(conn, &docspellFS{root: root})
}
func buildMountTree(client *DocspellClient, items []SearchItem) *dirNode {
root := &dirNode{name: "", children: map[string]fs.Node{}}
for _, item := range items {
folderName := "No Folder"
if item.Folder != nil && item.Folder.Name != "" {
folderName = item.Folder.Name
}
date := item.Date
if date == 0 {
date = item.ItemDate
}
yearMonth := "No Date"
modTime := time.Now()
if date > 0 {
modTime = time.UnixMilli(date)
yearMonth = modTime.Format("2006/01")
}
dir := ensureDir(root, folderName, strings.Split(yearMonth, "/")...)
base := sanitizeName(item.Name)
if base == "" {
base = item.ID
}
for i, att := range item.Attachments {
name := sanitizeName(att.Name)
if name == "" {
name = fmt.Sprintf("%s-%d.pdf", base, i+1)
}
if len(item.Attachments) > 1 {
name = fmt.Sprintf("%s - %02d - %s", base, i+1, name)
}
name = uniqueName(dir.children, name)
dir.children[name] = &fileNode{name: name, attachmentID: att.ID, size: uint64(att.Size), modTime: modTime, client: client}
}
}
return root
}
func ensureDir(root *dirNode, first string, rest ...string) *dirNode {
cur := root
parts := append([]string{first}, rest...)
for _, part := range parts {
part = sanitizeName(part)
if part == "" {
part = "_"
}
next, ok := cur.children[part].(*dirNode)
if !ok {
next = &dirNode{name: part, children: map[string]fs.Node{}}
cur.children[part] = next
}
cur = next
}
return cur
}
func sanitizeName(s string) string {
s = strings.TrimSpace(s)
s = strings.ReplaceAll(s, "/", "_")
s = strings.ReplaceAll(s, "\x00", "_")
return s
}
func uniqueName(children map[string]fs.Node, name string) string {
if _, ok := children[name]; !ok {
return name
}
ext := filepath.Ext(name)
base := strings.TrimSuffix(name, ext)
for i := 2; ; i++ {
candidate := fmt.Sprintf("%s (%d)%s", base, i, ext)
if _, ok := children[candidate]; !ok {
return candidate
}
}
}
func (f *docspellFS) Root() (fs.Node, error) { return f.root, nil }
func (d *dirNode) Attr(ctx context.Context, a *fuse.Attr) error {
a.Mode = os.ModeDir | 0555
return nil
}
func (d *dirNode) Lookup(ctx context.Context, name string) (fs.Node, error) {
child, ok := d.children[name]
if !ok {
return nil, fuse.ENOENT
}
return child, nil
}
func (d *dirNode) ReadDirAll(ctx context.Context) ([]fuse.Dirent, error) {
names := make([]string, 0, len(d.children))
for name := range d.children {
names = append(names, name)
}
sort.Strings(names)
entries := make([]fuse.Dirent, 0, len(names))
for _, name := range names {
typ := fuse.DT_File
if _, ok := d.children[name].(*dirNode); ok {
typ = fuse.DT_Dir
}
entries = append(entries, fuse.Dirent{Name: name, Type: typ})
}
return entries, nil
}
func (f *fileNode) Attr(ctx context.Context, a *fuse.Attr) error {
a.Mode = 0444
a.Size = f.size
a.Mtime = f.modTime
a.Ctime = f.modTime
return nil
}
func (f *fileNode) ReadAll(ctx context.Context) ([]byte, error) {
if f.data != nil {
return f.data, nil
}
data, err := f.client.DownloadAttachment(ctx, f.attachmentID)
if err != nil {
return nil, err
}
f.data = data
f.size = uint64(len(data))
return data, nil
}
mount_test.go
+53
View File
@@ -0,0 +1,53 @@
package main
import "testing"
func TestBuildMountTreeGroupsByFolderAndDate(t *testing.T) {
items := []SearchItem{{
ID: "item-1",
Name: "Invoice/July",
Date: 1720396800000,
Folder: &DocspellEntity{
Name: "Bills/Private",
},
Attachments: []ItemAttachment{{ID: "att-1", Name: "invoice.pdf", Size: 123}},
}}
root := buildMountTree(&DocspellClient{}, items)
folder, ok := root.children["Bills_Private"].(*dirNode)
if !ok {
t.Fatalf("expected sanitized folder directory, got %#v", root.children)
}
year, ok := folder.children["2024"].(*dirNode)
if !ok {
t.Fatalf("expected year directory, got %#v", folder.children)
}
month, ok := year.children["07"].(*dirNode)
if !ok {
t.Fatalf("expected month directory, got %#v", year.children)
}
if _, ok := month.children["invoice.pdf"].(*fileNode); !ok {
t.Fatalf("expected attachment file, got %#v", month.children)
}
}
func TestBuildMountTreeDeduplicatesAttachmentNames(t *testing.T) {
items := []SearchItem{{
ID: "item-1",
Name: "Invoice",
Attachments: []ItemAttachment{
{ID: "att-1", Name: "same.pdf"},
{ID: "att-2", Name: "same.pdf"},
},
}}
root := buildMountTree(&DocspellClient{}, items)
folder := root.children["No Folder"].(*dirNode)
date := folder.children["No Date"].(*dirNode)
if _, ok := date.children["Invoice - 01 - same.pdf"]; !ok {
t.Fatalf("expected first unique name, got %#v", date.children)
}
if _, ok := date.children["Invoice - 02 - same.pdf"]; !ok {
t.Fatalf("expected second unique name, got %#v", date.children)
}
}