Contents

apple/pir-service-example

Example PIR service & documentation for Live Caller ID Lookup & NEURLFilter

Overview

PIR Service Example provides:

  • PIRService, an example service for Live Caller ID Lookup.
  • PrivacyPass, an implementation of the Privacy Pass publicly verifiable tokens.

The documentation lives at Swift Package Index.

Developing PIR Service Example

Building PIR Service Example requires:

  • 64-bit processor with little-endian memory representation
  • macOS or Linux operating system
  • Swift version 6.0 or later
  • Optionally, XCode version 16.1 or later

Additionally, developing PIR Service Example requires:

Building

You can build PIR Service Example either via Xcode or via command line in a terminal.

Xcode

To build PIR Service Example from Xcode, simply open the root directory (i.e., the pir-service-example directory) of the repository in Xcode. See the Xcode documentation for more details on developing with Xcode.

Command line

To build PIR Service Example from command line, open the root directory (i.e., the pir-service-example directory) of the repository in a terminal, and run

swift build -c release

The build products will be in the .build/release/ folder.

To build in debug mode, run

swift build

The build products will be in the .build/debug/ folder.

[!WARNING] Runtimes may be slow in debug mode.

Testing

Run unit tests via

swift test -c release --parallel

To run tests in debug mode, run

swift test --parallel

[!WARNING] Runtimes may be slow in debug mode.

Database Reloading

The PIR Service supports dynamic database reloading without requiring a full service restart. This allows you to update the database and configuration while the service continues running.

Reloading Process
  1. Update your input database: Modify your input database file (e.g., input.txtpb) with new or updated entries.
  1. Process the new database: Run PIRProcessDatabase to generate the new database files:

``sh PIRProcessDatabase config.json ``

  1. Trigger reload: Send a SIGHUP signal to the running PIR Service process:

``sh kill -SIGHUP <PID> ``

You can find the process ID using: ``sh ps aux | grep PIRService ``

Behavior
  • When the service receives a SIGHUP signal, it reloads the configuration file and all associated database files.
  • The service logs "Reloading configuration..." when starting the reload and "Reloading configuration completed." when finished.
  • The service maintains multiple versions of the database to ensure compatibility with clients using older PIR parameters.
  • Clients automatically fetch updated PIR parameters periodically, or you can explicitly call RefreshPIR to force an immediate update.
Version Compatibility

The service is designed to handle database updates gracefully:

  • When you update the database, new PIR parameters may be generated.
  • The service stores both new and old versions of the dataset.
  • Clients using old PIR parameters will continue to work with the previous version of the dataset.
  • As clients update their PIR parameters, they will automatically use the new dataset.

For more details on maintaining PIR parameter compatibility across updates, see Reusing PIR Parameters.

Contributing

If you would like to make a pull request to PIR Service Example, please run pre-commit install. Then each commit will run some basic formatting checks.

Documentation

PIR Service Example uses DocC for documentation. For more information, refer to the DocC documentation and the Swift-DocC Plugin.

Xcode

The documentation can be built from Xcode via Product -> Build Documentation.

Command line

The documentation can be built from command line by running

swift package generate-documentation

and previewed by running

swift package --disable-sandbox preview-documentation --target PIRService

Package Metadata

Repository: apple/pir-service-example

Homepage: https://swiftpackageindex.com/apple/pir-service-example/main/documentation/pirservice

Stars: 207

Forks: 29

Open issues: 27

Default branch: main

Primary language: swift

License: Apache-2.0

README: README.md