API Reference¶

This page documents the public Go API of go-phileas.

Package `services`¶

Import path: github.com/philterd/go-phileas/pkg/services

FilterService¶

FilterService is the main entry point for filtering text. It holds a compiled set of filters derived from a policy and is safe for concurrent use.

type FilterService struct { /* unexported */ }

NewFilterService¶

func NewFilterService(pol *policy.Policy) *FilterService

Creates a new FilterService configured according to the given policy using the default InMemoryContextService. Filters are compiled once at construction time.

Parameters

Name	Type	Description
`pol`	`*policy.Policy`	The policy that defines which identifiers to activate and how to handle them.

Returns a pointer to the new FilterService.

Example

pol := &policy.Policy{
    Identifiers: policy.Identifiers{
        EmailAddress: &policy.EmailAddressFilter{},
    },
}

svc := services.NewFilterService(pol)

NewFilterServiceWithContext¶

func NewFilterServiceWithContext(pol *policy.Policy, contextService ContextService) *FilterService

Creates a new FilterService with a custom ContextService. Use this when you need a distributed or persistent store for referential integrity across multiple processes. See Context Service for details.

Parameters

Name	Type	Description
`pol`	`*policy.Policy`	The policy that defines which identifiers to activate and how to handle them.
`contextService`	`ContextService`	The context service used to store token→replacement mappings.

Returns a pointer to the new FilterService.

Example

customStore := &MyRedisContextService{} // implements ContextService
svc := services.NewFilterServiceWithContext(pol, customStore)

Filter¶

func (s *FilterService) Filter(pol *policy.Policy, context string, input string) (*model.FilterResult, error)

Applies all active filters to input and returns a FilterResult containing the filtered text and a list of identified spans.

Spans are sorted by position (ascending CharacterStart). Overlapping spans are deduplicated; the first match wins.

Parameters

Name	Type	Description
`pol`	`*policy.Policy`	The policy (used to resolve per-call configuration).
`context`	`string`	A named context label (e.g. a document ID or tenant name) that groups related Filter calls for referential integrity. Stored in each returned span. See Context Service.
`input`	`string`	The text to filter.

Returns (*model.FilterResult, error).

Example

result, err := svc.Filter(pol, "document-42", "Please call 555-867-5309.")
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.FilteredText)
// Output: Please call {{{REDACTED-phone-number}}}.

for _, span := range result.Spans {
    fmt.Printf("type=%s text=%q start=%d end=%d\n",
        span.FilterType, span.Text, span.CharacterStart, span.CharacterEnd)
}

Explain¶

func (s *FilterService) Explain(pol *policy.Policy, context string, input string) ([]model.Span, error)

Applies all active filters to input and returns the list of identified spans without modifying the original text. Use Explain when you only need to inspect what would be detected — for example, to audit or preview sensitive information — without performing any replacements.

Spans are sorted by position (ascending CharacterStart).

Parameters

Name	Type	Description
`pol`	`*policy.Policy`	The policy (used to resolve per-call configuration).
`context`	`string`	A named context label stored in each returned span. See Context Service.
`input`	`string`	The text to analyze.

Returns ([]model.Span, error).

Example

spans, err := svc.Explain(pol, "document-42", "SSN: 123-45-6789, email: john@example.com")
if err != nil {
    log.Fatal(err)
}

for _, span := range spans {
    fmt.Printf("type=%s text=%q start=%d end=%d\n",
        span.FilterType, span.Text, span.CharacterStart, span.CharacterEnd)
}
// Output:
// type=ssn text="123-45-6789" start=5 end=16
// type=email-address text="john@example.com" start=25 end=41

ContextService¶

ContextService is the interface used to store PII token→replacement mappings per named context, enabling referential integrity across multiple Filter calls.

type ContextService interface {
    Get(context, token string) (string, bool)
    Put(context, token, replacement string)
}

InMemoryContextService¶

The default implementation. Backed by a map[string]map[string]string and protected by a sync.RWMutex for safe concurrent use.

func NewInMemoryContextService() *InMemoryContextService

Used automatically by NewFilterService. Pass a custom implementation to NewFilterServiceWithContext to replace it.

FilterJSON¶

func FilterJSON(policyJSON string, context string, input string) (*model.FilterResult, error)

A convenience function that parses policyJSON, builds a FilterService, and filters input in one call. Suitable for one-shot or scripted use cases.

Parameters

Name	Type	Description
`policyJSON`	`string`	A JSON string representing a `policy.Policy`.
`context`	`string`	Context label stored in each returned span.
`input`	`string`	The text to filter.

Returns (*model.FilterResult, error).

Example

policyJSON := `{
    "identifiers": {
        "ssn": {}
    }
}`

result, err := services.FilterJSON(policyJSON, "ctx", "SSN: 123-45-6789")
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.FilteredText)
// Output: SSN: {{{REDACTED-ssn}}}

Package `model`¶

Import path: github.com/philterd/go-phileas/pkg/model

FilterResult¶

FilterResult is returned by Filter and FilterJSON. It contains the processed text and metadata about every identified span.

type FilterResult struct {
    FilteredText string  // The input text with sensitive information replaced.
    Context      string  // The context label passed to Filter.
    Spans        []Span  // The list of identified spans, sorted by position.
}

Example — inspecting the result

result, _ := svc.Filter(pol, "ctx", "Email john@example.com or call 555-1234.")

fmt.Println(result.FilteredText)

for _, s := range result.Spans {
    fmt.Printf("[%d:%d] %s -> %q\n",
        s.CharacterStart, s.CharacterEnd, s.FilterType, s.Replacement)
}

Span¶

Span describes a single piece of identified sensitive information.

type Span struct {
    CharacterStart int        // Zero-based index of the first character.
    CharacterEnd   int        // Zero-based index one past the last character.
    FilterType     FilterType // The type of sensitive information (e.g. "ssn", "email-address").
    Context        string     // The context label from the Filter call.
    Confidence     float64    // Confidence score (0.0–1.0).
    Text           string     // The original matched text.
    Replacement    string     // The replacement text that was written to FilteredText.
    Salt           string     // Salt used for hashing, if any.
    Ignored        bool       // True if the span was ignored per policy.
    Applied        bool       // True if the replacement was applied to FilteredText.
    Classification string     // Optional custom classification label.
}

Helper functions¶

DoesSpanExist¶

func DoesSpanExist(characterStart, characterEnd int, spans []Span) bool

Returns true if a span covering [characterStart, characterEnd) already exists in spans. Useful for deduplication when building custom filter logic.

DropOverlappingSpans¶

func DropOverlappingSpans(spans []Span) []Span

Returns a new slice with overlapping spans removed. The first match (lowest start position) is kept.

Package `policy`¶

Import path: github.com/philterd/go-phileas/pkg/policy

Strategy constants¶

const (
    StrategyRedact            = "REDACT"
    StrategyRandomReplace     = "RANDOM_REPLACE"
    StrategyStaticReplace     = "STATIC_REPLACE"
    StrategyCryptoReplace     = "CRYPTO_REPLACE"
    StrategyHashSHA256Replace = "HASH_SHA256_REPLACE"
    StrategyLast4             = "LAST_4"
    StrategyMask              = "MASK"

    DefaultRedactionFormat = "{{{REDACTED-%t}}}"
)

Policy¶

type Policy struct {
    Identifiers     Identifiers      `json:"identifiers"`
    Ignored         []Ignored        `json:"ignored,omitempty"`
    IgnoredPatterns []IgnoredPattern `json:"ignoredPatterns,omitempty"`
    Crypto          *Crypto          `json:"crypto,omitempty"`
}

FilterStrategy¶

type FilterStrategy struct {
    Strategy          string `json:"strategy"`
    RedactionFormat   string `json:"redactionFormat,omitempty"`
    StaticReplacement string `json:"staticReplacement,omitempty"`
    MaskCharacter     string `json:"maskCharacter,omitempty"`
}

BaseFilter¶

Embedded in every identifier filter type.

type BaseFilter struct {
    Enabled         *bool            `json:"enabled,omitempty"`
    Ignored         []string         `json:"ignored,omitempty"`
    IgnoredFiles    []string         `json:"ignoredFiles,omitempty"`
    IgnoredPatterns []IgnoredPattern `json:"ignoredPatterns,omitempty"`
}

func (b BaseFilter) IsEnabled() bool

IsEnabled() returns true when Enabled is nil or points to true.

Identifiers¶

type Identifiers struct {
    Age                  *AgeFilter
    BankRoutingNumber    *BankRoutingNumberFilter
    BitcoinAddress       *BitcoinAddressFilter
    CreditCard           *CreditCardFilter
    Currency             *CurrencyFilter
    Date                 *DateFilter
    DriversLicense       *DriversLicenseFilter
    EmailAddress         *EmailAddressFilter
    IbanCode             *IbanCodeFilter
    IPAddress            *IPAddressFilter
    MACAddress           *MACAddressFilter
    PassportNumber       *PassportNumberFilter
    PhoneNumber          *PhoneNumberFilter
    PhoneNumberExtension *PhoneNumberExtensionFilter
    SSN                  *SSNFilter
    StreetAddress        *StreetAddressFilter
    TrackingNumber       *TrackingNumberFilter
    URL                  *URLFilter
    VIN                  *VINFilter
    ZipCode              *ZipCodeFilter
    PhEye                []PhEyeFilter
}

See Identifiers for the full description and options for each field.

PhEyeConfiguration¶

Connection settings for a ph-eye NER service instance.

type PhEyeConfiguration struct {
    Endpoint string `json:"endpoint,omitempty"` // Default: "http://localhost:18080"
    Timeout  int    `json:"timeout,omitempty"`  // Seconds. Default: 600
    Labels   string `json:"labels,omitempty"`   // Comma-separated. Default: "Person"
}

PhEyeFilter¶

Configures a single ph-eye NER filter. Identifiers.PhEye is a slice, so multiple instances can coexist in one policy.

type PhEyeFilter struct {
    BaseFilter
    PhEyeConfiguration    PhEyeConfiguration `json:"phEyeConfiguration,omitempty"`
    PhEyeFilterStrategies []FilterStrategy   `json:"phEyeFilterStrategies,omitempty"`
    RemovePunctuation     bool               `json:"removePunctuation,omitempty"`
    BearerToken           string             `json:"bearerToken,omitempty"`
    WindowSize            int                `json:"windowSize,omitempty"`
    Priority              int                `json:"priority,omitempty"`
}

API Reference¶

Package services¶

FilterService¶

NewFilterService¶

NewFilterServiceWithContext¶

Filter¶

Explain¶

ContextService¶

InMemoryContextService¶

FilterJSON¶

Package model¶

FilterResult¶

Span¶

Helper functions¶

DoesSpanExist¶

DropOverlappingSpans¶

Package policy¶

Strategy constants¶

Policy¶

FilterStrategy¶

BaseFilter¶

Identifiers¶

PhEyeConfiguration¶

PhEyeFilter¶

Package `services`¶

Package `model`¶

Package `policy`¶