PIR Service Example

Live Caller ID Lookup is a new feature that allows the system to communicate with a third party service to privately retrieve information about a phone number for an incoming call. This allows the system to automatically block known spam callers and display identity information on the incoming call screen.

NEURLFilter is a new feature for iOS and macOS that allows the system to communicate with a third party service to privately check if a requested URL should be allowed or not. This allows your app to implement URL filtering in a privacy preserving manner.

This repository provides a functional server backend to test the Live Caller ID Lookup and NEURLFilter features.

Warning

While functional, this is just an example service and should not be run in production.

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:

• Nick Lockwood SwiftFormat
• pre-commit
• SwiftLint

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.

2. Process the new database: Run PIRProcessDatabase to generate the new database files:

   PIRProcessDatabase config.json

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

   kill -SIGHUP <PID>

   You can find the process ID using:

   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