204 |

Benjamin 205 |
206 | Idempotency with side-effects 207 |

208 |

209 |

210 |

211 |

Description
Usage
Configuration
Getting the logbook
Writing to the logbook
Status of the side-effect
Policy with regard to unknown events
Tests
Limitations
License

223 |

224 |

225 | 226 |

227 |

Description

228 |

229 |

230 | Benjamin gives you a macro that transforms code like this: 231 |

232 | 233 |

234 |

(let [logbook (get-logbook entity)]
235 |   (when (some pred logbook)
236 |     (let [response (body)]
237 |       (when (success? response)
238 |         (write logbook)))))
239 |

240 |

241 | 242 |

243 | Into this: 244 |

245 | 246 |

247 |

(with-logbook entity :event
248 |   body)
249 |

250 |

251 | 252 |

253 | There is a blog post that delves in the motivation and backstory. 254 |

255 |

256 |

257 | 258 |

259 |

Usage

260 |

261 |

262 | In your namespace, require: 263 |

264 |

265 |

[benjamin.core :refer [with-logbook]]
266 |

267 |

268 | 269 |

270 |

(with-logbook user :newsletter
271 |   (email (:email user) newsletter))  
272 |

273 |

274 | 275 |

276 | Benjamin executes body in a future and returns that future object immediately. Deref'ing the latter is subject to the semantics of futures (blocks until operations complete). success-fn is provided to determine the success of body. success-fn runs within the same thread as body and will not block. 277 |

278 |

279 |

280 | 281 |

282 |

Configuration

283 |

284 |

logbook-fn A function that retrieves a logbook given an entity.
persistence-fn A function that persists an updated logbook given an entity and an event
success-fn A predicate function that determines the success of body.
events A Clojure map with events as keys and predicates as values.
allow-undeclared-events? When Benjamin receives an event not found in the events map, it will either allows body to run or forbid it. This boolean setting determines this behavior. Defaults to false.

291 | 292 |

293 | Tip: system users can configure this library via a component that ships with the latest snapshot. 294 |

295 | 296 |

297 | Manual configuration is done by requiring: 298 |

299 | 300 |

301 |

[benjamin.configuration :refer [set-config!]]
302 |

303 |

304 |

305 | 306 |

307 |

Accessing the logbook

308 |

309 |

310 |

(set-config! :logbook-fn f)
311 |

312 |

313 | 314 |

315 | logbook-fn is a function that receives the entity as argument and returns a logbook. 316 | The default is :logbook which will work when the entity map embeds the logbook, as in: 317 |

318 | 319 |

320 |

{:first-name "Benjamin"
321 |  :last-name "Peirce"
322 |  :occupation "Mathematician"
323 |  :email "benjamin.peirce@harvard.edu"
324 |  :logbook [{:welcome-email timestamp}
325 |            {:subscription-reminder timestamp}
326 |            {:subscription-reminder timestamp}
327 |            {:newsletter timestamp}
328 |            {:newsletter timestamp}
329 |            {:newsletter timestamp}]}
330 |

331 |

332 |

333 |

334 | 335 |

336 |

Deriving predicates from events

337 |

338 |

339 |

(set-config! :events {:event predicate
340 |                       :event predicate
341 |                       :event predicate
342 |                       ...})
343 |

344 |

345 | 346 |

347 | Predicates are one argument functions that receive a logbook entry. A logbook entry is a map with an event as the key and a timestamp as the value. 348 |

349 | 350 |

351 | The following example checks if the logbook entry was written today. 352 |

353 | 354 |

355 |

#(if-let [date (first (vals %))]
356 |    (time/today? date)
357 |    false)
358 |

359 |

360 | 361 |

362 | Several predicates are offered in the benjamin.predicates namespace for convenience. That namespace has a dependency that you need to require in your build should you want to use them. This is because benjamin does not have any dependency of its own (it relies entirely on language features). 363 |

364 | 365 | 366 |

367 |

368 |

369 |

370 |

371 |

372 |

373 | 374 |

375 |

Getting the logbook

376 |

377 |

378 | :logbook-fn is a function of one argument, entity. Its responsibility is to retrieve the logbook for a entity (user, for example). The return value is a vector of maps, where the map has the event as key, and a date as value. Benjamin will run the predicate associated with the event on the logbook to determine whether the side-effect should is allowed or not. 379 |

380 | 381 |

382 | Tip: If you have dependencies (for example, a database), use a higher–order function that returns logbook-fn. 383 | Tip: The benjamin component in the system library has an option called logbook-fn-wrap-component? that is meant to achieve this. 384 |

385 |

386 |

387 | 388 |

389 |

Writing to the logbook

390 |

391 |

392 | :persistence-fn is a function of two arguments, entity and event. Its responsibility is to append to the logbook and persist the entity. 393 | You have to provide an implementation or an error will be thrown. For example: 394 |

395 | 396 |

397 |

(set-config! :persistence-fn
398 |              (fn [entity event] (let [logbook (conj (:logbook entity) {event (t/now)})]
399 |                                  (assoc entity :logbook logbook)
400 |                                  (save db entity))))
401 |

402 |

403 | 404 |

405 | Tip: If you have dependencies (for example, a database), use a higher–order function that returns persistence-fn. 406 |

407 | 408 |

409 |

(defn logbook [db :db :as dependencies}]
410 |   (fn [entity event] (let [logbook (conj (:logbook entity) {event (t/now)})]
411 |                        (assoc entity :logbook logbook)
412 |                        (save db entity)))
413 |

414 |

415 |

416 | Tip: The benjamin component in the system library includes an option, persistence-fn-wrap-component?, that will wrap dependencies associated with it in the system map. 417 |

418 |

419 |

420 | 421 |

422 |

Status of the side-effect

423 |

424 |

425 | The success function is a function of one argument, ie. the return value of the side-effectful body. 426 | It determines if the operation was successful and thus for inclusion in the logbook. 427 |

428 | 429 |

430 |

(set-config! :success-fn (constantly true))
431 |

432 |

433 | 434 |

435 | The default assumes all your operations will be A-okay. You’ll probably want to pass along something more realistic. 436 |

437 |

438 |

439 | 440 |

441 |

Policy with regard to unknown events

442 |

443 |

444 |

(with-logbook entity event
445 |   body)
446 |

447 |

448 | 449 |

450 | If the event is unknown, that is if it doesn’t show up in the events map, no predicate can be derived and then we rely on a policy you can set yourself. 451 | Either we accept unknown events and we proceed with the side-effect, or we reject them and return immediately. The default is strict, but you can change that. 452 |

453 | 454 |

455 |

(set-config! :allow-undeclared-events? true)
456 |

457 |

458 |

459 |

460 | 461 |

462 |

Tests

463 |

464 |

465 | A test suite is provided in benjamin.core-test. Call (test-ns *ns*) in the namespace, or run boot testing for continous testing. 466 |

467 |

468 |

469 | 470 |

471 |

Limitations

472 |

473 |

474 | You can work with as many entities you want. You can declare as many events as you want. You can have any side-effectful procedures in the body. Your success-fn may dispatch on the return value if you run different types of operations in the body. 475 |

476 | 477 |

478 | The configuration is a singleton with dynamic scope, so deal with it to the best of your understanding. Personally, I set it once and treat it as a constant for the lifetime of the application. 479 |

480 |

481 |

482 | 483 |

484 |

License

485 |

486 |

487 | Licensing terms will be revealed shortly. In the meantime, do what you want with it. 488 |

489 |

490 |

491 |

Benjamin 205 | 206 | Idempotency with side-effects 207 |

Table of Contents