Mirror of https://github.com/roostorg/osprey
github.com/roostorg/osprey
1# Osprey Example Rules
2
3This example rules project demonstrates how to write a simple rule that:
4
5- Creates entities based on items inside of your event JSON
6- Uses a UDF to return a `true`/`false` value, which determines whether a user should be banned or not
7- Adds an "effect" to the event using a UDF
8
9For this example, imagine that you are attempting to moderate a social media network. The one rule on your networks is that
10users may never say "hello" to each other. As a result, you want to ban any user who ever mentions the word "hello".
11
12Posts on your network are a JSON object that looks like this:
13
14```json
15{
16 "text": "here is some text"
17}
18```
19
20Your users also have user IDs which are strings. Whenever a user creates an event, imagine that you normally propagate those events like so:
21
22```json
23{
24 "user_id": "user_1923",
25 "event_type": "post",
26 "post": {
27 "text": "here is some text"
28 }
29}
30```
31
32To moderate these events with Osprey, you can produce them on a Kafka event bus in the following format which Osprey understands:
33
34```json
35{ "send_time": "2025-08-25T14:30:45.123456789Z", "data": "{\"action_id\": 1, \"action_name\": \"create_post\", \"data\":{\"user_id\": \"user_1923\", \"event_type\": \"create_post\", \"post\": { \"text\": \"hello world\" }}}"}
36```
37
38## Try it out
39
40From inside the Osprey project root directory, run `docker compose up`. This will start an Osprey worker and a Kafka server.
41
42Next, use `kafka-console-producer` to send a test event to the Osprey Kafka consumer:
43
44```sh
45# Note that on some Linux distrubtions, this may be `kafka-console-producer.sh` rather than `kafka-console-producer`.
46kafka-console-producer --bootstrap-server localhost:9092 --topic osprey.actions_input
47```
48
49Copy and paste the event above into the producer, then check the Osprey worker's logs. You should see an event that has a `ban-user` effect attached to it. The output JSON looks like this:
50
51```json
52{
53 "__action_id": 1,
54 "__timestamp": "2025-08-25T14:30:45.123456+00:00",
55 "__error_count": 0,
56 "__ban_user": [
57 "user_1923|User said \"hello\""
58 ],
59 "EventType": "create_post",
60 "PostText": "hello world",
61 "UserId": "user_1923",
62 "ContainsHello": true
63}
64```
65
66You can also try sending an event that does not contain the word "hello", and you should see that no effects are added to the event.
67
68```json
69{
70 "__action_id": 1,
71 "__timestamp": "2025-08-25T14:30:45.123456+00:00",
72 "__error_count": 0,
73 "EventType": "create_post",
74 "PostText": "i wont say that word",
75 "UserId": "user_1923",
76 "ContainsHello": false
77}
78```