Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ jobs:
with:
persist-credentials: false
- uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
- name: Compile and inspect Go packages
- name: Test, compile, and inspect Go packages
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
with:
context: .
Expand Down
1 change: 1 addition & 0 deletions BUILD.md
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,7 @@ limitations, and redistribution requirements.
```sh
go build ./...
go vet ./...
go test ./...
```

Frontend HTML, CSS, and JavaScript live in `internal/webui` and are embedded with
Expand Down
4 changes: 3 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@ RUN go mod download

FROM dependencies AS checks
COPY . .
RUN CGO_ENABLED=0 go build ./... && CGO_ENABLED=0 go vet ./... \
RUN CGO_ENABLED=0 go test ./... \
&& CGO_ENABLED=0 go build ./... \
&& CGO_ENABLED=0 go vet ./... \
&& CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build ./... \
&& CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go vet ./...

Expand Down
8 changes: 8 additions & 0 deletions MAINTAINER.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,14 @@ itself on the destination machine.
The Go toolchain is specified in [go.mod](go.mod) and the container build toolchain
in [Dockerfile](Dockerfile). Keep them compatible when updating either one.

Release inputs pin Go modules and bundled OCR/WebView2 assets by version and
checksum. The Go container image is selected by version tag, while Debian package
repositories are live and package installation includes current upgrades. Thus a
rebuild uses the same source-level dependencies but may resolve different base
image and native system package revisions; release artifacts are not guaranteed
to be bit-for-bit reproducible. This intentionally favors current Debian security
updates over snapshot-based repeatability.

Release source collection must resolve the exact dependency versions used in the
build. Missing sources stop publication rather than substituting a different
version. Preserve the source and notice downloads alongside published binaries;
Expand Down
222 changes: 70 additions & 152 deletions README.md

Large diffs are not rendered by default.

70 changes: 70 additions & 0 deletions cmd/shelfmark/options_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
package main

import (
"errors"
"flag"
"io"
"os"
"testing"

"log/slog"
)

func TestParseOptions(t *testing.T) {
originalArgs := os.Args
originalOutput := diagnosticOutput
t.Cleanup(func() {
os.Args = originalArgs
diagnosticOutput = originalOutput
})
diagnosticOutput = io.Discard

for _, test := range []struct {
name string
args []string
want options
wantErr bool
wantHelp bool
}{
{
name: "defaults",
want: options{listen: "127.0.0.1:8766", dataDir: "/app", logLevel: slog.LevelInfo},
},
{
name: "explicit options normalize level",
args: []string{"-headless", "-listen", "localhost:9000", "-data-dir", "/data", "-log-level", " WARN "},
want: options{headless: true, listen: "localhost:9000", dataDir: "/data", logLevel: slog.LevelWarn, logLevelSet: true},
},
{
name: "empty data directory uses executable directory",
args: []string{"-data-dir="},
want: options{listen: "127.0.0.1:8766", dataDir: "/app", logLevel: slog.LevelInfo},
},
{name: "invalid level", args: []string{"-log-level", "trace"}, wantErr: true},
{name: "unknown option", args: []string{"-unknown"}, wantErr: true},
{name: "help", args: []string{"-h"}, wantHelp: true},
} {
t.Run(test.name, func(t *testing.T) {
os.Args = append([]string{"shelfmark"}, test.args...)
got, err := parseOptions("/app")
if test.wantHelp {
if !errors.Is(err, flag.ErrHelp) {
t.Fatalf("parseOptions() error = %v, want flag.ErrHelp", err)
}
return
}
if test.wantErr {
if err == nil {
t.Fatalf("parseOptions() = %+v, want error", got)
}
return
}
if err != nil {
t.Fatalf("parseOptions() error = %v", err)
}
if got != test.want {
t.Fatalf("parseOptions() = %+v, want %+v", got, test.want)
}
})
}
}
3 changes: 2 additions & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,8 @@ ISBNs available for matching and a note about edition ambiguity.
ISBN lookups also fetch Open Library edition JSON; the work record supplies
fallback author names, while the edition supplies its actual title, subtitle,
languages, series labels, publisher and date. Missing edition records are normal;
transport failures remain warnings and partial results are not cached. Explicit
transport failures remain warnings; useful partial results are cached, while
failed searches with no candidates are not. Explicit
contributor roles and labelled translation statements provide translator evidence.
EPUB readers recognize inline and refined contributor roles, and writes preserve
unselected roles.
Expand Down
11 changes: 6 additions & 5 deletions docs/ux.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ Matching. New groups can be added without expanding a single API-key dialog.
- Navigate books and matches with the keyboard; dialogs manage focus and Escape.
- Edit descriptions over several lines and clear metadata fields intentionally.
- Stop background matching, and see catalog failures alongside useful results.
- Review and discard staged drafts without changing ebook files; background matching
is owned by the server and continues if the browser closes.
- Keep API keys masked with a password field; saving other settings preserves the key.
- Use small screens with stacked panels and scrollable metadata tables.
- See folder paths as paths on the server, including when browsing remotely.
Expand All @@ -23,9 +25,8 @@ Matching. New groups can be added without expanding a single API-key dialog.
2. **Scan progress.** Show discovered/read/skipped counts and cancellation for
large collections. Separate job state from the current selection so users can
keep reviewing while a scan runs.
3. **Draft management.** Add a drafts-only library filter, discard actions, and
recovery for books that were moved or deleted. Discard should show what will
be lost and leave book files unchanged.
3. **Draft management.** Add a drafts-only library filter and recovery for books
that were moved or deleted. Discard actions are available from the draft review.
4. **Metadata profiles.** Allow users to choose visible fields and default field
selection for catalog matches. Keep manual editing available for every
supported field and show format-specific limitations beside the control.
Expand All @@ -37,5 +38,5 @@ Matching. New groups can be added without expanding a single API-key dialog.
states. Keep these browser preferences separate from server-wide settings.

For larger libraries, use a paginated or virtualized list before adding more
client-side filters. Background work currently belongs to the open browser;
continuing jobs after it closes would require server-owned job state.
client-side filters. Background matching is server-owned, but its job status is
held in memory and is lost when Shelfmark shuts down.
7 changes: 6 additions & 1 deletion internal/app/proposal.go
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,12 @@ func (s *Server) proposal(w http.ResponseWriter, r *http.Request) {
if edited {
evidence = "Manual edit"
}
fields = append(fields, proposalField{Evidence: evidence, ReviewRequired: review, Name: name, Current: library.Text(current[name]), Value: library.Text(proposed[name]),
inputValue, err := library.InputText(name, proposed[name])
if err != nil {
jsonError(w, err)
return
}
fields = append(fields, proposalField{Evidence: evidence, ReviewRequired: review, Name: name, Current: library.Text(current[name]), Value: inputValue,
Changed: changed, Supported: supported, Suggested: changed && supported && !review && (edited || library.Text(proposed[name]) != "" || (name == "subtitle" && evidence != ""))})
}
notes := ""
Expand Down
64 changes: 53 additions & 11 deletions internal/app/search.go
Original file line number Diff line number Diff line change
Expand Up @@ -37,30 +37,52 @@ func (s *Server) search(w http.ResponseWriter, r *http.Request) {
jsonOut(w, result)
}

// cachedSearch loads suggestions on selection without scheduling a catalog
// request or running content inspection. A miss leaves explicit search to the user.
func (s *Server) cachedSearch(w http.ResponseWriter, r *http.Request) {
var in struct {
ID string `json:"id"`
}
if err := decode(r, &in); err != nil {
jsonError(w, err)
return
}
result, err := s.findMatches(r.Context(), in.ID, nil, lookupOptions{CacheOnly: true})
if err != nil {
jsonError(w, err)
return
}
jsonOut(w, result)
}

// lookupOptions controls scheduling and cache reuse for one search action.
type lookupOptions struct {
Background bool
IgnoreCache bool
CacheOnly bool
}

// findMatches is shared by explicit lookups and the server-owned background job.
// A nil query asks the backend to derive terms from the current working metadata.
func (s *Server) findMatches(ctx context.Context, id string, query *string, options lookupOptions) (catalog.Result, error) {
background := options.Background
if !background {
if !background && !options.CacheOnly {
s.manualSearches.Add(1)
defer s.manualSearches.Add(-1)
}
if query != nil && strings.TrimSpace(*query) == "" {
return catalog.Result{}, errors.New("enter a title, author or ISBN")
}
select {
case s.searches <- struct{}{}:
defer func() {
<-s.searches
}()
case <-ctx.Done():
return catalog.Result{}, ctx.Err()
// Reading cached matches must not wait behind a background catalog request.
if !options.CacheOnly {
select {
case s.searches <- struct{}{}:
defer func() {
<-s.searches
}()
case <-ctx.Done():
return catalog.Result{}, ctx.Err()
}
}

path := s.lookupPath(id)
Expand All @@ -73,8 +95,15 @@ func (s *Server) findMatches(ctx context.Context, id string, query *string, opti
return catalog.Result{}, err
}

slog.Info("metadata search started", "book_id", id, "background", background, "ignore_cache", options.IgnoreCache)
if options.CacheOnly {
slog.Debug("loading cached matches for book selection", "book_id", id)
} else {
slog.Info("metadata search started", "book_id", id, "background", background, "ignore_cache", options.IgnoreCache)
}
if !prefs.GoogleBooks && !prefs.OpenLibrary && !prefs.InternetArchive {
if options.CacheOnly {
return catalog.Result{Candidates: []catalog.Candidate{}}, nil
}
slog.Warn("metadata search unavailable: no catalogs enabled", "hint", "enable at least one catalog in Settings")
return catalog.Result{
Candidates: []catalog.Candidate{},
Expand Down Expand Up @@ -110,17 +139,25 @@ func (s *Server) findMatches(ctx context.Context, id string, query *string, opti
}{catalogOptions, prefs.InspectContent, prefs.OCR, current, identity, query != nil})
key := catalog.CacheKey(fp+string(encoded), terms)
// Bypassing cache reads still allows a successful fresh search to replace
// the old entry. Failures retain the existing cache and are never cached.
// the old entry. Useful partial results retain their provider warnings; a
// failed search with no candidates must not replace an existing entry.
if options.IgnoreCache {
slog.Debug("search cache bypassed by request", "book_id", id)
} else {
var cached catalog.Result
ok, err := s.db.CacheGet(ctx, key, time.Duration(prefs.CacheDays)*24*time.Hour, &cached)
if err != nil {
if options.CacheOnly {
slog.Warn("could not load cached catalog matches", "book_id", id, "error", err)
return catalog.Result{}, err
}
slog.Warn("search cache read failed; querying catalogs", "error", err)
}
if ok && err == nil {
slog.Debug("search cache hit", "book_id", id, "candidates", len(cached.Candidates))
if options.CacheOnly {
return cached, nil
}
// Empty results avoid repeated background work, but an explicit lookup
// must retry content inspection and all enabled catalogs for new matches.
if background || len(cached.Candidates) > 0 {
Expand All @@ -132,6 +169,9 @@ func (s *Server) findMatches(ctx context.Context, id string, query *string, opti
slog.Debug("search cache miss or disabled", "book_id", id)
}
}
if options.CacheOnly {
return catalog.Result{Candidates: []catalog.Candidate{}}, nil
}
// Indexed content is read locally. It is never submitted to a catalog service.
clues := ""
if prefs.InspectContent && query == nil {
Expand All @@ -156,9 +196,11 @@ func (s *Server) findMatches(ctx context.Context, id string, query *string, opti
results := s.catalog.Search(ctx, catalog.SearchRequest{
Query: terms, CustomQuery: query != nil, Identity: identity, ISBNs: isbns, Background: background,
}, catalogOptions)
if len(results.Warnings) == 0 && ctx.Err() == nil && prefs.CacheDays > 0 {
if (len(results.Candidates) > 0 || len(results.Warnings) == 0) && ctx.Err() == nil && prefs.CacheDays > 0 {
if err := s.db.CachePut(ctx, key, results); err != nil {
slog.Warn("could not cache search results", "error", err)
} else {
slog.Debug("catalog results cached", "book_id", id, "candidates", len(results.Candidates), "warnings", len(results.Warnings))
}
}

Expand Down
1 change: 1 addition & 0 deletions internal/app/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ func (s *Server) Handler() http.Handler {
mux.HandleFunc("GET /api/background", s.backgroundStatus)
mux.HandleFunc("POST /api/cover", s.cover)
mux.HandleFunc("POST /api/search", s.search)
mux.HandleFunc("POST /api/search/cached", s.cachedSearch)
mux.HandleFunc("POST /api/ui-error", s.uiError)
mux.HandleFunc("POST /api/apply", s.apply)
mux.HandleFunc("POST /api/staged-count", s.stagedCount)
Expand Down
Loading
Loading