ActiveDebianSync Search packages via API

• Back to ActiveDebianSync main section

ActiveDebianSync includes a powerful package search feature similar to apt-file, allowing you to search for packages by name, description, or files they contain.

Features

Search feature provides:

• Package name search: 
  Find packages by their name (partial or exact match)
   
• Description search: 
  Search packages by keywords in their description
   
• File search: 
  Find which package contains a specific file (like apt-file search)
   
• Package file listing: 
  List all files contained in a package (like apt-file list)
   
• Package information: 
  Get detailed metadata about a package

Enable the package search feature in your config.json:

{
  "package_search_enabled": true,//Enable/disable the package search feature
  "sync_contents": true // Download Contents files for file-to-package search
}

Note: If sync_contents is false, file search functionality will be limited as Contents files won't be available.

Enabling Search After Initial Setup

If you initially had sync_contents: false and later change it to true, a background scheduler will automatically:

1. Detect that Contents files are missing
2. Download them from the configured Debian mirror
3. Index them into the search database

This check runs every 15 minutes, so changes take effect without restarting the daemon.

API Endpoints

All search endpoints are available under /api/search/ and require API access (subject to IP filtering if configured).

General Search

Endpoint: GET /api/search
Search across package names, descriptions, and files.
 

Example: curl "http://127.0.0.1:9090/api/search?q=nginx&type=name&release=bookworm"

Response:

{
  "query": "nginx",
  "type": "name",
  "count": 15,
  "results": [
      {
          "package_name": "nginx",
          "version": "1.22.1-9",
          "description": "small, powerful, scalable web/proxy server",
          "section": "httpd",
          "release": "bookworm",
          "component": "main",
          "architecture": "amd64",
          "filename": "pool/main/n/nginx/nginx_1.22.1-9_amd64.deb",
          "match_type": "name"
      }
  ]
}

File Search

Endpoint: GET /api/search/file
Find packages containing a specific file path (similar to apt-file search).

Example: Find which package provides /usr/bin/vim curl : "http://127.0.0.1:9090/api/search/file?path=/usr/bin/vim"

Response:

{
  "file_path": "/usr/bin/vim",
  "count": 2,
  "results": [
      {
          "package_name": "vim",
          "version": "9.0.1378-2",
          "description": "Vi IMproved - enhanced vi editor",
          "release": "bookworm",
          "component": "main",
          "architecture": "amd64",
          "match_type": "file",
          "matched_file": "usr/bin/vim"
      }
  ]
}
 

Search packages by name only.

Endpoint: GET /api/search/package

Example: curl "http://127.0.0.1:9090/api/search/package?name=python3"
 

Search packages by description keywords.

Endpoint: GET /api/search/description

Example: Find packages related to "web server": curl "http://127.0.0.1:9090/api/search/description?q=web%20server"
 

Package Files Listing: List all files contained in a package (similar to apt-file list).

Endpoint: GET /api/search/package-files

Example: List all files in the nginx package curl "http://127.0.0.1:9090/api/search/package-files?package=nginx"  

Response:

{
  "package": "nginx",
  "count": 42,
  "files": [
      "etc/nginx/nginx.conf",
      "usr/sbin/nginx",
      "usr/share/doc/nginx/README.Debian",
      "usr/share/man/man8/nginx.8.gz"
  ]
}

Package Information

Get detailed information about a specific package, including its files.

Endpoint: GET /api/search/package-info

Example:curl "http://127.0.0.1:9090/api/search/package-info?package=nginx&release=bookworm"

Response:

{
  "package": {
      "package_name": "nginx",
      "version": "1.22.1-9",
      "description": "small, powerful, scalable web/proxy server",
      "section": "httpd",
      "release": "bookworm",
      "component": "main",
      "architecture": "amd64",
      "filename": "pool/main/n/nginx/nginx_1.22.1-9_amd64.deb"
  },
  "files": [
      "etc/nginx/nginx.conf",
      "usr/sbin/nginx"
  ],
  "files_count": 42
}

Search Status

Get the status of the search index, including statistics and indexing progress.

Endpoint: GET /api/search/status

Example: curl "http://127.0.0.1:9090/api/search/status"

Response:

{
  "enabled": true,
  "status": "ready",
  "stats": {
      "total_packages": 65432,
      "total_files": 12345678,
      "last_indexed": "2024-01-15T10:30:00Z"
  },
  "index_status": [
      {
          "release": "bookworm",
          "component": "main",
          "architecture": "amd64",
          "packages_count": 32000,
          "files_count": 6000000,
          "last_indexed": "2024-01-15T10:30:00Z"
      },
      {
          "release": "bookworm",
          "component": "contrib",
          "architecture": "amd64",
          "packages_count": 1500,
          "files_count": 250000,
          "last_indexed": "2024-01-15T10:30:00Z"
      }
  ]
}

Usage Examples

• Find which package provides a command
  Find which package provides the 'convert' command
  curl -s "http://127.0.0.1:9090/api/search/file?path=usr/bin/convert" | jq '.results[].package_name'
   
• Search for all packages related to a topic
  Find all packages related to PostgreSQL
  curl -s "http://127.0.0.1:9090/api/search?q=postgresql&limit=50" | jq '.results[] | {name: .package_name, desc: .description}'
   
• Check if a specific package exists
  Check if package exists and get its info
  curl -s "http://127.0.0.1:9090/api/search/package-info?package=htop&release=bookworm"
   
• List configuration files in a package
  List all files in a package and filter for config files
  curl -s "http://127.0.0.1:9090/api/search/package-files?package=nginx" | jq '.files | map(select(startswith("etc/")))'
   
• Find packages by file extension
  Find packages containing Python files 
  curl -s "http://127.0.0.1:9090/api/search/file?path=.py&limit=20"  

Database/table Structure

The search feature uses an SQLite database stored alongside the configuration file (e.g., /etc/ActiveDebianSync/package_search.db).

packages: 
Stores package metadata

• package_name, version, description, section
• release, component, architecture
• filename, indexed_at

package_files: 
Stores file-to-package mappings

• file_path, package_name
• release, component, architecture

index_status: 
Tracks indexing progress

• release, component, architecture
• last_indexed, packages_count, files_count

Automatic Indexing

• During Sync
  Package indexes are automatically updated after each repository synchronization:
  After syncing metadata (Release, Packages.gz files)
  Contents files are downloaded (if sync_contents: true)
  The search database is updated with new package information
   
• Background Index Checker
  A background process runs every 15 minutes to ensure indexes are up-to-date:
  Checks if Contents files exist when sync_contents is enabled
  Downloads missing Contents files
  Creates missing search indexes
  Useful when enabling sync_contents after initial setup
• Manual Trigger
  To force a re-index, you can trigger a manual sync:
  curl -X POST "http://127.0.0.1:9090/api/sync/trigger"

Performance 

• The search database uses SQLite with WAL mode for optimal read performance
• Indexes are created on commonly searched fields
• Large Contents files (100MB+) may take a few minutes to index initially
• Search queries typically complete in milliseconds

Troubleshooting

• Search returns no results
  Check if search is enabled: curl http://127.0.0.1:9090/api/search/status
  Verify indexes exist (check packages_count > 0)
  Ensure a sync has completed at least once
• File search not working
  Verify sync_contents: true in config
  Check if Contents files exist in dists/<release>/Contents-<arch>.gz
  Wait for the background indexer to download and index them
   
• Slow search performance
  Check database size with /api/search/status
  Use more specific filters (release, architecture)
  Reduce the limit parameter