pushrules

Documentation

Index

• Constants
• func BoolTweakOr(tweaks map[string]interface{}, key TweakKey, def bool) bool
• func ValidateRule(kind Kind, rule *Rule) []error
• type AccountRuleSets
  • func DefaultAccountRuleSets(localpart string, serverName gomatrixserverlib.ServerName) *AccountRuleSets
• type Action
  • func (a *Action) MarshalJSON() ([]byte, error)
  • func (a *Action) UnmarshalJSON(bs []byte) error
• type ActionKind
  • func ActionsToTweaks(as []*Action) (ActionKind, map[string]interface{}, error)
• type Condition
• type ConditionKind
• type EvaluationContext
• type Kind
• type Rule
• type RuleSet
  • func DefaultGlobalRuleSet(localpart string, serverName gomatrixserverlib.ServerName) *RuleSet
• type RuleSetEvaluator
  • func NewRuleSetEvaluator(ec EvaluationContext, ruleSet *RuleSet) *RuleSetEvaluator
  • func (rse *RuleSetEvaluator) MatchEvent(event *gomatrixserverlib.Event) (*Rule, error)
• type Scope
• type TweakKey

Constants

const (
	MRuleMaster              = ".m.rule.master"
	MRuleSuppressNotices     = ".m.rule.suppress_notices"
	MRuleInviteForMe         = ".m.rule.invite_for_me"
	MRuleMemberEvent         = ".m.rule.member_event"
	MRuleContainsDisplayName = ".m.rule.contains_display_name"
	MRuleTombstone           = ".m.rule.tombstone"
	MRuleRoomNotif           = ".m.rule.roomnotif"
)

const (
	MRuleCall                  = ".m.rule.call"
	MRuleEncryptedRoomOneToOne = ".m.rule.encrypted_room_one_to_one"
	MRuleRoomOneToOne          = ".m.rule.room_one_to_one"
	MRuleMessage               = ".m.rule.message"
	MRuleEncrypted             = ".m.rule.encrypted"
)

const (
	MRuleContainsUserName = ".m.rule.contains_user_name"
)

Functions

func BoolTweakOr

func BoolTweakOr(tweaks map[string]interface{}, key TweakKey, def bool) bool

BoolTweakOr returns the named tweak as a boolean, and returns `def` on failure.

func ValidateRule

func ValidateRule(kind Kind, rule *Rule) []error

ValidateRule checks the rule for errors. These follow from Sytests and the specification.

Types

type AccountRuleSets

type AccountRuleSets struct {
	Global RuleSet `json:"global"` // Required
}

An AccountRuleSets carries the rule sets associated with an account.

func DefaultAccountRuleSets

func DefaultAccountRuleSets(localpart string, serverName gomatrixserverlib.ServerName) *AccountRuleSets

DefaultAccountRuleSets is the complete set of default push rules for an account.

type Action

type Action struct {
	// Kind is the type of action. Has custom encoding in JSON.
	Kind ActionKind `json:"-"`

	// Tweak is the property to tweak. Has custom encoding in JSON.
	Tweak TweakKey `json:"-"`

	// Value is some value interpreted according to Kind and Tweak.
	Value interface{} `json:"value"`
}

An Action is (part of) an outcome of a rule. There are (unofficially) terminal actions, and modifier actions.

func (*Action) MarshalJSON

func (a *Action) MarshalJSON() ([]byte, error)

func (*Action) UnmarshalJSON

func (a *Action) UnmarshalJSON(bs []byte) error

type ActionKind

type ActionKind string

ActionKind is the primary discriminator for actions.

const (
	UnknownAction ActionKind = ""

	// NotifyAction indicates the clients should show a notification.
	NotifyAction ActionKind = "notify"

	// DontNotifyAction indicates the clients should not show a notification.
	DontNotifyAction ActionKind = "dont_notify"

	// CoalesceAction tells the clients to show a notification, and
	// tells both servers and clients that multiple events can be
	// coalesced into a single notification. The behaviour is
	// implementation-specific.
	CoalesceAction ActionKind = "coalesce"

	// SetTweakAction uses the Tweak and Value fields to add a
	// tweak. Multiple SetTweakAction can be provided in a rule,
	// combined with NotifyAction or CoalesceAction.
	SetTweakAction ActionKind = "set_tweak"
)

func ActionsToTweaks

func ActionsToTweaks(as []*Action) (ActionKind, map[string]interface{}, error)

ActionsToTweaks converts a list of actions into a primary action kind and a tweaks map. Returns a nil map if it would have been empty.

type Condition

type Condition struct {
	// Kind is the primary discriminator for the condition
	// type. Required.
	Kind ConditionKind `json:"kind"`

	// Key indicates the dot-separated path of Event fields to
	// match. Required for EventMatchCondition and
	// SenderNotificationPermissionCondition.
	Key string `json:"key,omitempty"`

	// Pattern indicates the value pattern that must match. Required
	// for EventMatchCondition.
	Pattern string `json:"pattern,omitempty"`

	// Is indicates the condition that must be fulfilled. Required for
	// RoomMemberCountCondition.
	Is string `json:"is,omitempty"`
}

A Condition dictates extra conditions for a matching rules. See ConditionKind.

type ConditionKind

type ConditionKind string

ConditionKind represents a kind of condition.

SPEC: Unrecognised conditions MUST NOT match any events, effectively making the push rule disabled.

const (
	UnknownCondition ConditionKind = ""

	// EventMatchCondition indicates the condition looks for a key
	// path and matches a pattern. How paths that don't reference a
	// simple value match against rules is implementation-specific.
	EventMatchCondition ConditionKind = "event_match"

	// ContainsDisplayNameCondition indicates the current user's
	// display name must be found in the content body.
	ContainsDisplayNameCondition ConditionKind = "contains_display_name"

	// RoomMemberCountCondition matches a simple arithmetic comparison
	// against the total number of members in a room.
	RoomMemberCountCondition ConditionKind = "room_member_count"

	// SenderNotificationPermissionCondition compares power level for
	// the sender in the event's room.
	SenderNotificationPermissionCondition ConditionKind = "sender_notification_permission"
)

type EvaluationContext

type EvaluationContext interface {
	// UserDisplayName returns the current user's display name.
	UserDisplayName() string

	// RoomMemberCount returns the number of members in the room of
	// the current event.
	RoomMemberCount() (int, error)

	// HasPowerLevel returns whether the user has at least the given
	// power in the room of the current event.
	HasPowerLevel(userID, levelKey string) (bool, error)
}

An EvaluationContext gives a RuleSetEvaluator access to the environment, for rules that require that.

type Kind

type Kind string

Kind is the type of push rule. See also RuleSet.

const (
	UnknownKind   Kind = ""
	OverrideKind  Kind = "override"
	ContentKind   Kind = "content"
	RoomKind      Kind = "room"
	SenderKind    Kind = "sender"
	UnderrideKind Kind = "underride"
)

type Rule

type Rule struct {
	// RuleID is either a free identifier, or the sender's MXID for
	// SenderKind. Required.
	RuleID string `json:"rule_id"`

	// Default indicates whether this is a server-defined default, or
	// a user-provided rule. Required.
	//
	// The server-default rules have the lowest priority.
	Default bool `json:"default"`

	// Enabled allows the user to disable rules while keeping them
	// around. Required.
	Enabled bool `json:"enabled"`

	// Actions describe the desired outcome, should the rule
	// match. Required.
	Actions []*Action `json:"actions"`

	// Conditions provide the rule's conditions for OverrideKind and
	// UnderrideKind. Not allowed for other kinds.
	Conditions []*Condition `json:"conditions"`

	// Pattern is the body pattern to match for ContentKind. Required
	// for that kind. The interpretation is the same as that of
	// Condition.Pattern.
	Pattern string `json:"pattern"`
}

A Rule contains matchers, conditions and final actions. While evaluating, at most one rule is considered matching.

Kind and scope are part of the push rules request/responses, but not of the core data model.

type RuleSet

type RuleSet struct {
	Override  []*Rule `json:"override,omitempty"`
	Content   []*Rule `json:"content,omitempty"`
	Room      []*Rule `json:"room,omitempty"`
	Sender    []*Rule `json:"sender,omitempty"`
	Underride []*Rule `json:"underride,omitempty"`
}

A RuleSet contains all the various push rules for an account. Listed in decreasing order of priority.

func DefaultGlobalRuleSet

func DefaultGlobalRuleSet(localpart string, serverName gomatrixserverlib.ServerName) *RuleSet

DefaultGlobalRuleSet returns the default ruleset for a given (fully qualified) MXID.

type RuleSetEvaluator

type RuleSetEvaluator struct {
	// contains filtered or unexported fields
}

A RuleSetEvaluator encapsulates context to evaluate an event against a rule set.

func NewRuleSetEvaluator

func NewRuleSetEvaluator(ec EvaluationContext, ruleSet *RuleSet) *RuleSetEvaluator

NewRuleSetEvaluator creates a new evaluator for the given rule set.

func (*RuleSetEvaluator) MatchEvent

func (rse *RuleSetEvaluator) MatchEvent(event *gomatrixserverlib.Event) (*Rule, error)

MatchEvent returns the first matching rule. Returns nil if there was no match rule.

type Scope

type Scope string

Scope only has one valid value. See also AccountRuleSets.

const (
	UnknownScope Scope = ""
	GlobalScope  Scope = "global"
)

type TweakKey

type TweakKey string

A TweakKey describes a property to be modified/tweaked for events that match the rule.

const (
	UnknownTweak TweakKey = ""

	// SoundTweak describes which sound to play. Using "default" means
	// "enable sound".
	SoundTweak TweakKey = "sound"

	// HighlightTweak asks the clients to highlight the conversation.
	HighlightTweak TweakKey = "highlight"
)