logo
Documentation
Versions

RabbitMQ Barong Event API

#Overview of RabbitMQ details

Barong submits all events into three exchanges depending on event category (read next).

The exchange name consists of three parts:

1) application name (typically barong)

2) fixed keyword events.

3) category of event, like system (generic system event), model (the attributes of some record were updated)

The routing key looks like user.password.reset.token, user.created. The event name matches the routing key but with event category appended at the beginning, like system.user.password.reset.token, market.user.created.

#Overview of RabbitMQ message

Each produced message in Event API is JWT (complete format).

This is very similar to Management API.

The example below demonstrates both generation and verification of JWT:

require "jwt-multisig"
require "securerandom"

jwt_payload = {
    iss:   'barong',
    jti:   SecureRandom.uuid,
    iat:   Time.now.to_i,
    exp:   Time.now.to_i + 60,
    event: event_payload
}

    private_key = OpenSSL::PKey.read(Base64.urlsafe_decode64(private_key)
    algorithm   = 'RS256'
    jwt         = JWT::Multisig.generate_jwt jwt_payload, \
      { barong: private_key },
      { barong: algorithm }

   Kernel.puts "GENERATED JWT", jwt.to_json, "\n"

   verification_result = JWT::Multisig.verify_jwt jwt.deep_stringify_keys, \
  { barong: public_key }, { verify_iss: true, iss: "barong", verify_jti: true }

  decoded_jwt_payload = verification_result[:payload]

  Kernel.puts "MATCH AFTER VERIFICATION: #{jwt_payload == decoded_jwt_payload}."

The RabbitMQ message is stored in JWT field called event.

#Overview of Event API message

The typical event looks like (JSON):

event: {
  record: {
    foo: "ID30DD0DD986",
    bar: "[email protected]",
    baz: "member",
    qux: 0
  },
  name: "model.user.created"
}

The field event[:name] contains event name (same as routing key). The fields foo, bar, baz, qux (example) are fields which carry useful information.

Barong Event API messages

#Format of model.user.created event

event: {
  record: {
    uid: "ID30DD0DD986",
    email: "[email protected]",
    role: "member",
    level: 0,
    otp: false,
    state: "pending",
    created_at: "2019-01-28T08:35:29Z",
    updated_at: "2019-01-28T08:35:29Z"
  },
  name: "model.user.created"
}
FieldDescription
recordCreated user up-to-date attributes.

#Format of model.user.updated event

event: {
    record: {
    uid: "ID30DD0DD986",
    email: "[email protected]",
    role: "member",
    level: 1,
    otp: false,
    state: "pending",
    created_at: "2019-01-28T08:35:29Z",
    updated_at: "2019-01-28T08:35:29Z"
  },
  changes: {
    level: 0
  }
  name: "model.user.updated"
}
FieldDescription
recordCreated user up-to-date attributes.
changesThe changed user attributes and their values.

#Format of model.user.created event

event: {
  record: {
    address:"Illinois",
    city:"New Garfieldbury",
    country:"COD",
    dob:"1984-05-22",
    first_name:"Irina",
    last_name:"Heathcote",
    postcode:"10029",
    created_at:"2019-10-02T08:14:20Z",
    updated_at:"2019-10-02T08:14:20Z",
    user: {
      email: "[email protected]",
      level: 0,
      otp: false,
      referral_uid: nil,
      role: "member",
      state: "pending",
      uid: "IDEA819FB3F1",
      updated_at: "2019-10-02T08:14:20Z"
      created_at: "2019-10-02T08:14:20Z"
    }
  },
  name: "model.profile.created"
}
FieldDescription
recordCreated profile up-to-date attributes.

#Format of model.user.updated event

event: {
  record: {
    address:"Illinois",
    city:"New Garfieldbury",
    country:"COD",
    created_at:"2019-10-02T08:14:20Z",
    dob:"1984-05-22",
    first_name:"Irina",
    last_name:"Heathcote",
    postcode:"10029",
    updated_at:"2019-10-02T08:14:20Z",
    user: {
      email: "[email protected]",
      level: 0,
      otp: false,
      referral_uid: nil,
      role: "member",
      state: "pending",
      uid: "IDEA819FB3F1",
      updated_at: "2019-10-02T08:14:20Z"
      created_at: "2019-10-02T08:14:20Z"
    }
  },
  changes: {
    first_name: "Vernell"
  },
  name: "model.profile.updated"
}
FieldDescription
recordProfile up-to-date attributes.
changesThe changed profile attributes and their values.

#Format of model.label.created event

event: {
  record: {
    id: 1,
    key: "email",
    value: "verified",
    user: {
      uid: "ID30DD0DD986",
      email: "[email protected]",
      role: "member",
      level: 2,
      otp: false,
      state: "active",
      created_at: "2019-01-28T08:35:29Z",
      updated_at: "2019-01-28T08:35:29Z"
    }
  },
  name: "model.label.created"
}
FieldDescription
recordCreated label up-to-date attributes.

#Format of model.label.updated event

event: {
  record: {
    id: 1,
    key: "new_key",
    value: "verified",
    user: {
      uid: "ID30DD0DD986",
      email: "[email protected]",
      role: "member",
      level: 2,
      otp: false,
      state: "active",
      created_at: "2019-01-28T08:35:29Z",
      updated_at: "2019-01-28T08:35:29Z"
    }
  },
  changes: {
    key: "old_key"
  }
  name: "model.label.updated"
}
FieldDescription
recordCreated label up-to-date attributes.
changesThe changed label attributes and their values.

#Format of model.document.created event

event: {
  record: {
    doc_type: 'Passport',
    doc_expire: '3020-01-22',
    doc_number: 'AA1234BB',
    upload: [],
    updated_at:"2019-01-28T08:35:29Z",
    created_at:"2019-01-28T08:35:29ZZ",
    user: {
      uid: "ID30DD0DD986",
      email: "[email protected]",
      role: "member",
      level: 2,
      otp: false,
      state: "active",
      created_at: "2019-01-28T08:35:29Z",
      updated_at: "2019-01-28T08:35:29Z"
    }
  }
  name: "model.document.created"
}
FieldDescription
userThe up-to-date user attributes.
doc_typeDocument type.
doc_expireExperation time for document.
doc_numberDocument number.
uploadArray of updaded objects
updated_atTime of document object creation
created_atTime of last document update

#Format of system.user.email.confirmation.token event

event: {
  record: {
    user: {
      uid: "ID739065AFD3",
      email: "[email protected]",
      role: "member",
      level: 0,
      otp: false,
      state: "pending",
      created_at: "2019-01-28T09:03:50Z",
      updated_at: "2019-01-28T09:03:50Z"
    },
    language: "EN",
    domain: "www.barong.io",
    token: "eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1NDg2NjYyMzAsImV4cCI6MTU0ODY3MjIzMCwic3ViIjoiY29uZmlybWF0aW9uIiwiaXNzIjoiYmFyb25nIiwiYXVkIjpbInBlYXRpbyIsImJhcm9uZyJdLCJqdGkiOiI5OWJkNzFkMjU2NTdlMmI1YzI1MCIsImVtYWlsIjoiYWRtaW4xMjNAYmFyb25nLmlvIiwidWlkIjoiSUQ3MzkwNjVBRkQzIn0.OI5tL9kV6cA1JBAy7G5iqd3WplxcB-waHYKFjm83koMEpx2Hlw9fksq5lip5cIHTjR8i3ambFL40OaCwDNc1jAiDsHwuv2nLswgi88_M1G8KVFylboQdtgmH_cZiz-Y-51Fq2oqEID5QyJnsSMSJbfspb6A0JGT_V-SPK4WFZw43F_RKhlZBCrxojljMwd20rGqFPYirMgUpsfiW0_-mESXzQ7UK1eA8mYO7Id4y6JR2Yoo-JTloEnBL1M189tOz6LqmmQB0M_QjTiHG3y9I97Med3StgVziYo9qog9kJXyPuXbboddg__5WEhMcWbaToohoiT5UvpVJHKfgxEVaDg"
  },
  name: "system.user.email.confirmation.token"
}
FieldDescription
userThe up-to-date user attributes.
languageThe language.
domainThe domain name of barong.
tokenValid confirm-acc jwt token (mandatory param for user confirmation endpoint) /identity/users/email/confirm_code.

#Format of system.user.email.confirmed event

event: {
  record: {
    user: {
      uid: "IDB1629BFE9E",
      email: "[email protected]",
      role: "member",
      level: 0,
      otp: false,
      state: "active",
      created_at: "2019-01-28T10:17:27Z",
      updated_at: "2019-01-28T10:17:45Z"
    },
    language: "EN",
    domain: "www.barong.io"
  },
  name: "system.user.email.confirmed"
}
FieldDescription
userThe up-to-date user attributes.
languageThe language.
domainThe domain name of barong.

#Format of system.user.password.reset.token event

event: {
  record: {
    user: {
      uid: "ID30DD0DD986",
      email: "[email protected]",
      role: "member",
      level: 0,
      otp: false,
      state: "pending",
      created_at: "2019-01-28T08:35:29Z",
      updated_at: "2019-01-28T08:35:29Z"
    },
    language: "EN",
    domain: "www.barong.io",
    token: "eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1NDg2NjQ1OTUsImV4cCI6MTU0ODY3MDU5NSwic3ViIjoicmVzZXQiLCJpc3MiOiJiYXJvbmciLCJhdWQiOlsicGVhdGlvIiwiYmFyb25nIl0sImp0aSI6IjRhY2IzM2IzYmE2NDc0ZjY1YTI5IiwiZW1haWwiOiJhZG1pbjEyQGJhcm9uZy5pbyIsInVpZCI6IklEMzBERDBERDk4NiJ9.Rie4LCbkV0jVBbhMoceYx8a9uDA-ea9D1v790zlIqP_EY8Iue_OOKXYWiC1Y-55MPicFbknBILjZlPewvAF8ZrhqIt04ROsgBdDGEUGY_SnLWhXzqSx9-v_o_w2MVjLOUxvRBm6sD0RvL-_5LmOcLqhYtf7ZPUnPDwsvhDedqDfbXPEvI7OK2SZ-1uPAOg1IMOX1k7xaDt5I1Wp-Knr2DmEgwNYbIjaXraComYcMdtVSuYVJAufgA0kTADMeT3cV3jzGy9dNfs8heMCtf5tr72IbL0_N0VeUQj9uaPDUr4ntsYk7gOPmA3RSVrSismtYdBXA9oLA0b0YfOctiY9dqg"
  },
  name: "system.user.password.reset.token"
}
FieldDescription
userThe up-to-date user attributes.
languageThe language.
domainThe domain name of barong.
tokenValid reset-pass jwt token (mandatory param for password reset endpoint) /identity/users/password/confirm_code.

#Format of system.user.account.deleted event

event: {
  record: {
    user: {
      uid: "IDB1629BFE9E",
      email: "[email protected]",
      role: "member",
      level: 1,
      otp: false,
      state: "deleted",
      created_at: "2019-01-28T10:17:27Z",
      updated_at: "2019-01-28T10:17:45Z",
    }
  },
  name: "system.user.account.deleted"
}
FieldDescription
userThe up-to-date user attributes.

#Format of system.user.password.reset event

event: {
  record: {
    user: {
      uid: "ID30DD0DD986",
      email: "[email protected]",
      role: "member",
      level: 0,
      otp: false,
      state: "pending",
      created_at: "2019-01-28T08:35:29Z",
      updated_at: "2019-01-28T09:42:36Z"
    }
  },
  name: "system.user.password.reset"
}
FieldDescription
userThe up-to-date user attributes.

#Format of system.user.password.change event

event: {
  record: {
    user: {
      uid: "IDC554ED1D0F",
      email: "[email protected]",
      role: "member",
      level: 0,
      otp: false,
      state: "active",
      created_at: "2019-01-09T15:54:56Z",
      updated_at: "2019-01-28T09:59:03Z"
    }
  },
  name: "system.user.password.change"
}
FieldDescription
userThe up-to-date user attributes.

#Format of system.document.verified event

event: {
  record: {
    user: {
      uid: "IDC554ED1D0F",
      email: "[email protected]",
      role: "member",
      level: 0,
      otp: false,
      state: "active",
      created_at: "2019-01-09T15:54:56Z",
      updated_at: "2019-01-28T09:59:03Z"
    },
    id: 1,
    key: "something",
    value: "verified"
  },
  name: "system.document.verified"
}
FieldDescription
userThe up-to-date user attributes.

#Format of system.document.rejected event

event: {
  record: {
    user: {
      uid: "IDC554ED1D0F",
      email: "[email protected]",
      role: "member",
      level: 0,
      otp: false,
      state: "active",
      created_at: "2019-01-09T15:54:56Z",
      updated_at: "2019-01-28T09:59:03Z"
    },
    id: 1,
    key: "something",
    value: "rejected"
  },
  name: "system.document.rejected"
}
FieldDescription
userThe up-to-date user attributes.

#Format of system.session.create event

  event: {
    record: {
      user: {
        uid: "ID30DD0DD986",
        email: "[email protected]",
        role: "member",
        level: 0,
        otp: false,
        state: "pending",
        created_at: "2019-01-28T08:35:29Z",
        updated_at: "2019-01-28T08:35:29Z"
      },
      user_ip: "127.0.0.1",
      user_agent: "Chrome"
    },
    name: "system.session.create"
  }

#Producing events using Ruby

require "bunny"

def generate_jwt(jwt_payload)
  Kernel.abort "Please, see «Overview of RabbitMQ message» for implementation guide."
end

Bunny.run host: "localhost", port: 5672, username: "guest", password: "guest" do |session|
  channel     = session.channel
  exchange    = channel.direct("barong.events.model")
  jwt_payload = {
    iss:   "barong",
    jti:   SecureRandom.uuid,
    iat:   Time.now.to_i,
    exp:   Time.now.to_i + 60,
    event: {
      record: {
        uid: "ID30DD0DD986",
        email: "[email protected]",
        role: "member",
        level: 0,
        otp: false,
        state: "pending",
        created_at: "2019-01-28T08:35:29Z",
        updated_at: "2019-01-28T08:35:29Z"
      },
    name: "model.user.created"
  }
  }
  exchange.publish(generate_jwt(jwt_payload), routing_key: "user.created")
end

IMPORTANT: Don't forget to implement the logic for JWT exception handling!

#Producing events using rabbitmqadmin

rabbitmqadmin publish routing_key=user.created payload=JWT exchange=barong.events.model

Don't forget to pass environment variable JWT.

#Consuming events using Ruby

require "bunny"

def verify_jwt(jwt_payload)
  Kernel.abort "Please, see «Overview of RabbitMQ message» for implementation guide."
end

Bunny.run host: "localhost", port: 5672, username: "guest", password: "guest" do |session|
  channel  = session.channel
  exchange = channel.direct("barong.events.model")
  queue    = channel.queue("", auto_delete: true, durable: true, exclusive: true)
                    .bind(exchange, routing_key: "user.created")
  queue.subscribe manual_ack: true, block: true do |delivery_info, metadata, payload|
    Kernel.puts verify_jwt(JSON.parse(payload)).fetch(:event)
    channel.ack(delivery_info.delivery_tag)
  rescue => e
    channel.nack(delivery_info.delivery_tag, false, true)
  end
end

IMPORTANT: Don't forget to implement the logic for JWT exception handling!