Forem: Kevin Mungai

Simple Explanation of Ports and Adapters

Kevin Mungai — Mon, 18 May 2020 20:08:23 +0000

TL/DR;

Ports and Adapters help us define boundaries between our program and the outside world.
Ports and Adapters also help us define the behavior of the outside world.
Extra: don't call me let me call you.

Boundaries and the Behavior.

Every time our code calls the outside (think database, external API etc) there is a chance it might succeed or fail.

And when it succeeds or fails you will have to deal with it somehow. One cool way of dealing with the potential success or failure is to define the behavior of the "outside" (adapters).

By defining I mean creating a data structure (ports) that describes what might happen. e.g.

success
- A
- B
failure
- X
- Y
- Z

The data structure could be a simple JavaScript object or Clojure map with a key indicating the type.

Some programming languages give us the ability to use Inheritance to define different behavior while others give us the ability to define behaviour via Algebraic Data Types e.g Elm, F#, TypeScript.

At the end of the day all we want to do is to define the behavior of the outside and use that to determine what is going to happen next.

Do we wish to:

retry the API call
log that error and move on
use that newly found data for something.
forward that for processing

Adapters could be implemented via Polymorphism and examples include service objects in Rails and Django, MultiMethods in Clojure etc.

What if I receive data that I don't know how to deal with?
This means that chances are not all behaviors have been catered for and you needs to review this.

While the process of defining all these discrete behaviors might be a laborious task to do even for a small project, your future selves with thank you.

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live

John Woods

Don't call me, I'll call you.

The outside code should not call your code, remember your code is in-charge i.e events from outside should not emit directly into your code.

This means that you must maintain control by using the tools you have access to such as Reactive Extensions, or Channels or Actors etc.

This is not all but one can use or create libraries built on these tools to create simple to maintain logic.

A pattern that one can use in JavaScript land is the Meiosis Pattern.

One example of this is the BLOC Library in Dart that uses Streams to create a Business Logic Components (BLOCs) that has one sink, stream, plus other goodies. I have to attest that one can create some complex logic without knowledge of the Dart Streams package.

shoutout to the makers of the Flutter Bloc Project

Thank you for reading up to this point.

Is there anything I have missed or misunderstood? Please comment.

Programming Problem

Kevin Mungai — Thu, 12 Sep 2019 14:24:30 +0000

Write a program that given a number of documents, can find all the documents with words containing the letter "a" in them.

Using the with-open macro that will automatically close any I/O. The clojure.string/includes? function will check each line as it comes in if it contains the letter "a" and will return true or false.

(defn contains-a?
  [document]
  (with-open [rdr (clojure.java.io/reader document)]
    (clojure.string/includes? (line-seq rdr) "a")))

(filter #(contains-a? %) [documents])

Next step is to:

try and succeed as fast as possible, i.e once the program detects an "a" it should return true and stop looking through that file and,
leverage the AsynchronousFileChannel of Java plus core.async to maybe parallelize the work? Not sure how this would work.

Inspiration
gist

State Machines and USSD Applications

Kevin Mungai — Wed, 11 Sep 2019 15:43:18 +0000

Introduction

To be honest I have always had issues with USSD applications. I wanted a way to make creating USSD applications manageable.

Usually, USSD applications move from one state to another. Several cases must be managed.

what input and what type do we expect?
how do we handle empty cases?
can we go back?
do we want to log the current state?
do we want to version our ussd state machine?

Problem statement

this is borrowed from the Africastalking June Technical Challenge, just the first part.

User journey: person dials the USSD Code and gets prompted for a username and email address.

What is this state machine?

I wont try to make this complex but I will choose to use a normal map in a ussd.edn file.

there are two fixed states :start and :finish. These tell us where we are. We also have all the valid choices in their own set which are the expected user inputs, plus we have versioning.

What is appealing about this is that this map can be changed by someone who doesn't know anything about programming.

the layout is pretty simple

current state	via	next state
:start	:init	:text
:ready	"1"	:query-email
:query-email	:empty	:query-email
:query-email	:not-empty	:query-username
:query-username	:empty	:query-username
:query-username	:not-empty	:finish

{:fsm
 {:start {:init {:text "Welcome to the USSD application.\nWe are registering users.\nPress 1 to continue or just cancel.",
                 :next-state :ready}}
  :ready {"1" {:next-state :query-email
               :text "Please enter your email address."}}
  :query-email {:empty {:next-state :query-email
                        :text "Sorry, the text is empty.\nPlease enter an email"}
                :not-empty {:next-state :query-username
                            :text "Please enter a username."}}
  :query-username {:empty {:next-state :query-username
                           :text "Sorry, the text is empty.\nPlease enter a username"}
                   :not-empty {:next-state :finish
                               :text "Thank you for participating in the registration."}}
  :finish :finish}
 :choices #{"1"}
 :version "0.0.1"}

the callback

when our ussd application receives a callback from the Africastalking Service we get:

session-id
phone-number
network-code
service-code
text

how the database looks

{"ATUid_7c6bad2c84927fcd17cf8331b5c3e497"
  {:phone-number +254XXXXXXX
   :network-code XXXXXX
   :service-code *384*XXXX#
   :text ""
   :current-state :start
   :current-state-response "Welcome to the USSD Application\n"
   :past-state [{:from :start :via :init :ready}]}

By storing all the past states like this we are able to find out where our users are having a problem or even create a situation that allows our users to go back if they had an error of some kind.

overview

does the session exist? we check the current-state then we use the ussd finite state machine to to get the next state and then respond with the text response.

example:

{:next-state :query-email
 :text "Please enter your email address."}

if the session does not exist? we just associate the new session-id on to the database.

the code is below

https://gist.github.com/kevinmungai/4a8fcf9a56a055dc1ac6eb9884db987f

Custom Card Number Verification System Challenge

Kevin Mungai — Wed, 26 Dec 2018 23:08:50 +0000

caveat

This programming challenge is found at

http://neo.cellulant.com:3000/sw_internship.html

Google Web Cache

and it will be presented as is:

the challenge

Cellulant has implemented a custom, card number verification system to ensure detection and blocking of fake cards. A scratch card consists of 4 sets of 5 digits (20 digits in total) e.g. [10006-12342-00081-99993] which are printed separated by a space or a dash.

Each set of 5 digits consists of two parts, the first 4 digits (the number) and a 5th digit (the checksum) The formula dictates that each of the sets must be validated as follows: The first 4 digits, e.g 1234, as decimal numbers be converted into an octal number (base 8) i.e. 23228. This octal number is then processed to generate the checksum, as follows:

Add all digits to each other to get a new number “X”

If “X” is more than 1 digit, repeat step (1) until you have a single digit. “Y”

Append “Y” to the end of the original decimal number e.g. 1234 2

For Example:

Given the set “10006”

Convert 1000 to octal =>1750>
1+7+5+0=15
1+5=68
Valid number is 10006 so;
return (TRUE)

Given the set “99998”

Convert 9999 to octal => 23417
2+3+4+1+7=21
2+1=3
Valid number is 99993 so;
return (FALSE)

Create a Java, Java-Script or PHP script with the function that will receive a string value (scratch card number) and return boolean TRUE or FALSE, on whether the card number is valid, as shown below

You should use as many other functions as you deem necessary within your code.

really neat solution

This solution was contributed by Filipe Ramalho

We get the modulo operation of first-four with 7
Then we subtract the result from the checksum
Next we get the modulo operation of the result above with 7
Then we check if it is equal to 0

Better explained by Filipe Ramalho:

For 9999|8

9999 % 7 = 3 //First you modulo through 7

8 - 3 = 5 //Then you subtract the result from the checksum.

5 % 7 = 5 //Then you modulo that through 7.

The end result isn't 0, so the digit isn't valid

(defn is-valid?
  [number]
  (let [first-four (quot number 10)
        check-sum (rem number 10)]
    (-> first-four
        (mod 7)
        (- check-sum)
        (mod 7)
        (= 0))))


user> (is-valid-modified? 10006)
true
user> (is-valid-modified? 99993)
true
user> (is-valid-modified? 99998)
false
user> (is-valid-modified? 12342)
true
user> (is-valid-modified? 11697)
true

(defn validate-scratch-card [card-number]
  (let [f (comp is-valid? #(Integer/parseInt %))]
    (->> (string/split card-number #"(-|\s)")
         (map f)
         (every? true?))))

user> (validate-scratch-card "10006 12342 00081 99998")
false
user> (validate-scratch-card "10006 12342 00081 99993")
true

It is an elegant solution.

the old solution

Instead of using any of the proposed languages above, I shall use Clojure.

validate-scratch-card is a function which takes a string which may look like:

"10006-12342-00081-99993"
"10006 12342 00081 99993"

It would be nice to split the argument based on the presence of a space or a hyphen so that I could work on each substring:

;; has hyphen
user> (clojure.string/split "10006-12342-00081-99993" #("-|\s)")
;; ["10006" "12342" "00081" "99993"]

;; has spaces
user> (clojure.string/split "10006 12342 00081 99993" #"(-|\s)")
;; ["10006" "12342" "00081" "99993"]

Next item on the agenda is to parse each individual substring to Integer via the Java method Integer/parseInt.

user> (Integer/parseInt "10006")
;; 10006

map can be used to parse each individual substring

user> (map #(Integer/parseInt %) "10006 12342 00081 99993")
;; 10006

Each Integer can be checked for validity based on the rules above.
Each Integer has 2 parts:

first four digits (the number)
the fifth digit (the checksum)

user> (quot 10006 10)
;; 1000   first four digits (the number)

user> (rem 10006 10)
;; 6   fifth digit (checksum)

Next is to convert the first four digits to octal.

This will be achieved by creating a base converter

(defn- to-digits [number base]
  (loop [n number
         digits '()]
    (if (pos? n)
      (recur (quot n base)
             (conj digits (mod n base)))
      digits)))

(defn to-octal [number]
  "returns a list of octal numbers"
  (to-digits number 8))

user> (to-octal 1000)
;; (1 7 5 0)

Subsequent step is to sum up each of the generated numbers.

But before that, a function that takes two octal numbers and sums them up is needed.

(defn add-two-octal [x y]
  "add two octal numbers"
  (let [a (Integer/parseInt (str x) 8)
        b (Integer/parseInt (str y) 8)]
    (-> (+ a b)
        Integer/toOctalString
        Integer/parseInt)))

user> (add-two-octal 3 6)
;; 11

This add-two-octal function can then be used to sum up a list of octal numbers together as follows:

user> (reduce #(add-two-octal %1 %2)
              (to-octal 1000))
;; 15

user> (reduce #(add-two-octal %1 %2)
              '(1 7 5 0))
;; 15

Although the addition works fine it doesn't satisfy the requirement that the result of the sum should be a single digit.
If a single digit is the result of the sum then the single digit should be returned else the summation should be done again.
Also there is need for a function to separate the new summation if it happens to be two digits.

(defn separate [number]
  "a utility function to separate digits"
  (loop [n number
         digits '()]
    (if (zero? n)
      digits
      (recur (quot n 10)
             (conj digits (rem n 10))))))


(defn sum-octal [number]
  (let [sum (reduce #(add-two-octal %1 %2)
                    (to-octal number))]
    (if (zero? (quot sum 10))
      sum
      (apply add-two-octal (separate sum)))))

user> (sum-octal 1000)
;; 6

Next a function that takes a number and checks for validity can be written as follows:

(defn is-valid? [number]
  (let [first-four (quot number 10)
        check-sum (rem number 10)
        verify (sum-octal first-four)]
    (= verify check-sum)))

user> (is-valid? 10006)
;; true

user> (is-valid? 99998)
;; false

The is-valid? function and the #(Integer/parseInt %) can be composed together

(comp is-valid? #(Integer/parseInt %))

user> ((comp is-valid? #(Integer/parseInt %)) "10006")
;; true

Finally, the validate-scratch-card function will shape up as follows

(defn validate-scratch-card [card-number]
  (let [f (comp is-valid? #(Integer/parseInt %))]
    (->> (string/split card-number #"(-|\s)")
         (map f)
         (every? true?))))

user> (validate-scratch-card "10006 12342 00081 99993")
;; true

user> (validate-scratch-card "10006 12342 00081 99998")
;; false