Skip to content

find.md

Latest commit

 

History

History
224 lines (156 loc) · 8.28 KB

find.md

File metadata and controls

224 lines (156 loc) · 8.28 KB
Raw

find Function Spec

This document defines the intended behavior for rewriting the native find function in src/gio.cc.

Goal

Implement find so that it uses GNOME's file search mechanism used by Nautilus, and returns result objects that match the same shape and semantics as ls.

Scope

  • Platform: Linux GNOME environments.
  • Runtime: Node native addon exported from this repository.
  • Function under spec: find.
  • This is a functional specification, not an implementation note.

Primary Requirement

find must use the GNOME/Nautilus search backend rather than manual recursive filesystem traversal or shelling out to Tracker CLI commands.

In practice, this means:

  1. Use the GNOME desktop search/indexing mechanism that Nautilus relies on.
  2. Prefer native library/API access over spawning shell commands.
  3. Do not construct shell commands from user input.
  4. Do not use popen, system, or equivalent shell-based fallbacks for search execution.

API Surface

The public JavaScript API should remain:

  1. find(query, callback)
  2. find(query, sourcePath, callback)
  3. find(query, options, callback)
  4. find(query, sourcePath, options, callback)

Arguments

query

  • Type: string
  • Required.
  • Represents a user-entered search term.
  • Matching should be case-insensitive.
  • Matching behavior should align with Nautilus-style filename/title search as closely as practical.

sourcePath

  • Type: string
  • Optional.
  • When provided, search should be scoped to that directory subtree or search root if the GNOME search backend supports scoped search.
  • If the underlying GNOME search API cannot restrict results directly, implementation may post-filter results, but must still use the GNOME/Nautilus search source as the data origin.

callback

  • Type: function
  • Required.
  • Callback style should remain:
  1. success: callback(null, results)
  2. failure: callback(errorMessageString, null)

options

  • Type: object
  • Optional.
  • Supported fields:
  1. dateFrom: Date | string | number, compared against result mtime
  2. dateTo: Date | string | number, compared against result mtime
  3. minSize: number, minimum result size in bytes
  4. maxSize: number, maximum result size in bytes

Filtering may be applied after GNOME-backed search results are resolved, but the search origin must remain GNOME/Nautilus-backed.

Return Value

The native function should return undefined and deliver results through the callback.

Result Shape

Each result item must match the same object shape returned by ls, not the reduced shape currently returned by find.

Each result object should include the same fields ls currently emits when available:

  1. name: string
  2. display_name: string
  3. href: string
  4. location: string
  5. is_dir: boolean
  6. is_hidden: boolean
  7. is_readable: boolean
  8. is_writable: boolean
  9. is_symlink: boolean
  10. filesystem: string
  11. content_type: string when available
  12. size: number when available
  13. mtime: number when available
  14. atime: number when available
  15. ctime: number when available

Result Semantics

  • href must represent the matched file path in the same style as ls.
  • location must represent the parent directory path in the same style as ls.
  • Metadata should be gathered using the same or equivalent GIO file info attributes used by ls.
  • Missing metadata should be handled the same way as ls handles it now.

Matching Rules

The rewritten find should behave like a user-facing desktop search rather than a raw filesystem grep.

Required matching characteristics:

  1. Case-insensitive matching.
  2. Partial substring matching.
  3. Search should primarily target file display names / titles / names in a way consistent with Nautilus search.
  4. Results should include files and directories.

Preferred behavior:

  1. Returned order should reflect GNOME search backend ordering if available.
  2. Duplicate logical results should be removed.
  3. Hidden files should be included or excluded according to what the GNOME search backend returns by default, unless the implementation explicitly defines a repo-wide policy.

Search Scope Behavior

find(query, callback)

  • Search across the default GNOME/Nautilus searchable scope available to the current user session.
  • Results may reflect what the desktop indexer currently knows about.

find(query, sourcePath, callback)

  • Search should be restricted to sourcePath when possible.
  • If the GNOME search backend cannot natively scope the query, the implementation may:
  1. run the GNOME-backed search first
  2. filter results so only items under sourcePath remain
  • If the GNOME backend is unavailable or returns no matches, a recursive GIO filesystem fallback may be used.

Error Handling

The rewritten function must validate arguments before invoking any search backend.

Validation failures

Use JavaScript exceptions for invalid arguments, consistent with the rest of the addon:

  1. missing query
  2. non-string query
  3. missing callback
  4. non-function callback
  5. if provided, non-string sourcePath

Runtime failures

Use callback errors for runtime search failures:

  1. backend unavailable
  2. query execution failure
  3. metadata resolution failure that prevents result construction
  4. scope restriction failure when it makes the final result unusable

Runtime failure callback format:

  • callback(errorMessageString, null)

Security Requirements

The rewrite must satisfy these constraints:

  1. No shell command construction from user input.
  2. No popen, system, or shell-based Tracker wrappers.
  3. No command-line fallback that interpolates raw query text.
  4. No use-after-free of search strings or URI buffers.
  5. No leaking per-result allocations when producing large result sets.

Performance Requirements

  1. The function should use indexed desktop search rather than recursive full-tree traversal as the primary search mechanism.
  2. Metadata collection should avoid unnecessary duplicate lookups when possible.
  3. The function should remain responsive for large result sets.
  4. If the backend can return more results than desired, the implementation may impose a limit, but that limit must be explicit and documented.
  5. Filesystem fallback is acceptable only as a secondary path when the GNOME backend is unavailable, fails, or returns no matches.

Implementation Constraints

The rewrite should preserve these external behaviors:

  1. Same exported function name: find
  2. Same callback-based API
  3. Same optional sourcePath overload
  4. Same Linux/GIO-oriented code style as the rest of the addon

The rewrite should remove these current behaviors:

  1. manual recursive traversal as the primary search mechanism
  2. shell-based Tracker fallback
  3. reduced result shape compared with ls

Acceptance Criteria

The rewrite is complete when all of the following are true:

  1. find("report", cb) performs GNOME/Nautilus-backed search.
  2. find("report", "/home/user/Documents", cb) returns only results under that scope.
  3. Every returned result includes the same metadata fields that ls returns.
  4. Callback success uses callback(null, results).
  5. Runtime failures use callback(errorMessageString, null).
  6. No shell command execution is used in the search path.
  7. The implementation does not rely on recursive directory walking as its main search engine.
  8. Duplicate results are not returned.
  9. If Tracker is unavailable or yields no matches, the implementation may return results from a GIO-based filesystem fallback.

Suggested Test Cases

  1. Search for an existing filename fragment and verify non-empty results.
  2. Search with mixed case and verify case-insensitive matching.
  3. Search with sourcePath and verify every href stays under that path.
  4. Compare one returned result against ls(parentDir, cb) and confirm matching object shape.
  5. Search for a nonexistent term and verify callback(null, []).
  6. Pass invalid argument types and verify JavaScript exceptions are thrown.
  7. Run search with filenames containing spaces, quotes, and shell metacharacters and verify safe handling.

Notes for Future Rewrite

The rewrite should treat ls as the canonical metadata formatter for result objects. If practical, the implementation should share metadata construction logic with ls rather than maintaining a second partially overlapping formatter.