Ahmed Alani

Moya, Decodable, and RxSwift Bindings

Mon, 18 Sep 2017 15:07:00 -0500

If your application integrates with a REST API, one of the first things you’ll implement is a network abstraction and serialization layer. Moya and Decodable are examples of libraries that make this dead simple for Swift / iOS. You don’t want to repeat the same boilerplate code accessing each resource, so let’s create generic extensions that will make our life easier.

Moya and Decodable

Moya is a thin facade around the Alamofire HTTP client. Instead of writing Alamofire.request("https://api.mysite.com/v1/orders/\(userId)") and managing parameters, paths, encoding, etc., we can implement Moya’s protocol and access an endpoint via enum: MoyaProvider<MyApi>().request(.getOrders(userId)). Not only does this keep our API configuration encapsulated and consistent, but it’s much easier to read. The API call returns a Moya.Response, which ultimately needs to be converted into a model.

Decodable is an object mapping library that handles JSON serialization and deserialization into Swift objects. Mappings are specified as extensions on models and–once specified–deserialization is a simple call to the decode extension: let orders = try [Order].decode(json).

Even in the simplest case of making a request and mapping a response, we want to avoid writing the above code for every single resource we interact with. Here’s a generic extension that will handle mapping for us against any response; all we need to provide is the type information:

public extension Moya.Response {
    public func map<T: Decodable>(_ type: T.Type) 
      throws -> T {
      return try type.decode(try self.mapJSON())
    }
    
    public func map<T: Decodable>(_ type: [T.Type]) 
      throws -> [T] {
      return try Array<T>.decode(try self.mapJSON())
    }
}

Here we see two map methods, the first for returning a single mapped object and second for an array of objects.
The self.mapJSON() call is just a Moya extension that will convert a Response to JSON using JSONSerialization.jsonObject. Feel free to use your own serialization code.

The net result is the API calls are now fluent, succinct, and readable for all resources:

internal func getOrders(userId: String) throws -> [Orders] {
      return provider.request(.getOrders(userId))
                     .map([Orders.self])
}

RxSwift-ifying our Code

If you use RxSwift and want to utilize the above extensions in an Observable chain, we can employ the same strategy with the flatMap and just operators:

public extension ObservableType where E == Moya.Response {
  public func map<T: Decodable>(_ type: T.Type) 
  -> Observable<T> {
    return flatMap { (response : Response) 
    -> Observable<T> in
      return Observable.just(try response.map(type))
    }
  }

  public func map<T: Decodable>(_ type: [T.Type]) 
  -> Observable<[T]> {
    return flatMap { (response : Response) 
      -> Observable<[T]> in
        return Observable.just(try response.map(type))
    }
  }
}

The reactive code is now just as clean and easy to read as the non-reactive code:

provider.rx.request(.getOrders(userId))
        .map([Orders.self])
        .subscribe { orders in
          // Handle orders ...
         }

Improvements

As an exercise, I suggest you consider these improvements for a “real” implementations:

Utilize ViewModels. Your API call(s) may return data that does not exactly conform to your view. Are there any well established design patterns that can help you handle this separation of concerns? How would this code work with the above examples?
Errors in an RxSwift observable chain will terminate a subscription, which is something you want to avoid in most cases. If any sort of error occurs in the above examples (network issue, mapping issue, etc.), our subscription will be terminated and updates will cease. How might you handle this problem?

All of the above code is available on GitHub here.

Dockerfiles for Hugo and S3 Website

Thu, 24 Aug 2017 15:07:00 -0500

In the last post we used two docker images to publish a static site, one for encapsulating our Hugo process and another for the S3 website tool. I received a few direct messages asking how to customize these images. Here’s a quick addendum to show you the Dockerfiles for both.

Hugo Image

FROM gliderlabs/alpine:latest
MAINTAINER Ahmed Alani

ENV HUGO_VERSION=0.20
RUN apk add --update \
  wget \
  ca-certificates \
  python \
  python-dev \
  py-pip \
  bash && \
  pip install pygments && \
  wget https://github.com/spf13/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-64bit.tar.gz && \
  tar xzf hugo_${HUGO_VERSION}_linux-64bit.tar.gz && \
  rm hugo_${HUGO_VERSION}_linux-64bit.tar.gz && \
  mkdir -p /usr/local/bin && \
  mv hugo_${HUGO_VERSION}_linux_amd64/hugo* /usr/local/bin/hugo

VOLUME /src
WORKDIR /src

ENTRYPOINT ["hugo"]

View the GitHub Source. If you need details regarding the Dockerfile syntax, see the reference. Quick notes:

FROM gliderlabs/alpine:latest - We’re using alpine linux because it’s a lightweight distro (< 5MB) and gives us access to the apk package manager for installing dependencies.
ENV HUGO_VERSION=0.20 - This specifies the default version of Hugo we want to download. You can override this while building the image, e.g. $ docker build --build-arg HUGO_VERSION=0.XX .

s3_website Image

FROM anapsix/alpine-java:8_jdk
MAINTAINER Ahmed Alani

RUN apk add --update \
bash \
curl-dev \
ruby \
ruby-dev \
ruby-irb \
ruby-rdoc \
ruby-rake \
ruby-io-console \
ruby-bundler && \
gem install s3_website --no-ri --no-rdoc && \
s3_website install

VOLUME /src
WORKDIR /src

ENTRYPOINT ["s3_website"]

View the GitHub Source. Quick notes:

FROM anapsix/alpine-java:8_jdk - We’re still using alpine linux, but this comes with the Java 8 JDK pre-installed, which is a pre-requisite for s3_website.
gem install s3_website - We’re not specifying the version for the s3_website gem in order to grab the latest by default. This isn’t a good practice, but you can include that improvement in your own image.

So Recursive It Hurts

Sat, 06 Feb 2016 11:53:00 -0500

Hugo is the new kid on the block in the world of static site generators. Docker has set the DevOps world ablaze by popularizing container technology. Naturally, I’ll be perpetuating the hype train for both with my blog. Let’s run Hugo in a Docker container, generate my website, and host it using Amazon S3.

Why Hugo?

If I want to host a blog using a platform like Wordpress, I need to provision, maintain, and (most importantly) pay for a LAMP stack just to get started. Don’t get me wrong, I like Wordpress and I’ve hosted sites with it in the past. It comes with a rich set of features like post scheduling, WYSYWIG editors, extensive plugins, and so on. However, for my personal blog that’s entirely too much work. Static site generators like Hugo follow a different model. I download a website template, write a post in Markdown, then Hugo renders my content into a full HTML. Now I can host my site anywhere and all I need to worry about are bandwidth fees.

Hugo comes with several pre-built binaries that allow you to run it out of the box on most OS’s. Sadly, extra features like syntax highlighting requires installing additional dependencies to get up and running. I’m lazy, so memorizing OS-specific commands for a project is an immediate no-go. Which version of Python do I install? Which packages do I download with pip? Let’s use Docker containers to run Hugo with batteries included.

Docker to the rescue

Using Docker, we can create a tiny sandboxed environment—a container—that bundles everything we need to run Hugo. Containers can include almost anything, such as a filesystem, OS binaries, the Hugo binary, and additional dependencies for extra features. This is basically static linking on steroids. I no longer have to remember custom install instructions per machine to get the full Hugo experience. I just download the Docker image and I’m ready to go. Note that Docker is supported by several operating systems.

Run Hugo with Docker to build our site

Images for containers can be shared, which means that once a Hugo image is defined, anyone with Docker installed can download and run it. Let’s grab Hugo from the public image I uploaded to Docker Hub.

$ docker pull alani/hugo

Now that we have an image for Hugo, we can run a container with it and use Hugo to create a new site.

$ mkdir ahmedalani.com
$ cd ahmedalani.com

$ docker run --rm -v `pwd`:/src alani/hugo new site .

Breaking down the command quickly:

docker run --rm - Run a temporary container. This means it will not exist after we exit.
-v `pwd`:/src - Mount the /src volume in the container to the current directory on my machine, /ahmedalani.com. The /src volume is the working directory in the container.
alani/hugo new site . - Run the container using the alani/hugo image we just downloaded. Because the container represents the Hugo process, pass it additional parameters new site . This will generate a Hugo site in the container’s working directory, and subsequently, our host machine’s directory.

At this point if we ls, our directory should contain a Hugo site template.

- ahmedalani.com
----- archetypes\
----- config.yaml
----- content\
--------- posts\
----- data\
----- layouts\
----- static\
----- ...

Time to create out first post. Let’s also make running the container easier by using the alias command.

$ alias hugo="docker run -it --rm -v `pwd`:/src -p 1313:1313 alani/hugo"

$ hugo new post/so-recursive-it-hurts.md
/src/content/post/so-recursive-it-hurts.md created

After adding some content (like this blog post), we can preview the blog locally using Hugo’s built-in webserver.

$ hugo server -w --baseUrl="http://localhost:1313" --bind=0.0.0.0

0 of 0 draft rendered
0 future content
1 pages created
0 paginator pages created
0 tags created
0 categories created
in 34 ms
Watching for changes in /src/{data,content,layouts,static,themes/hugo-incorporated}
Serving pages from /src/public
Web Server is available at http://0.0.0.0:1313/
Press Ctrl+C to stop

We’re up! Hugo will launch a web server in the container and serve up the site on port 1313. It will also watch the source code in the /src volume and regenerate + live reload the site if we make any edits.

Quick side notes:

In the alias command, I bound the container’s port 1313 to my host port 1313, otherwise I wouldn’t have been able to access the site from my browser.
Ctrl+C will cause the Hugo web server to stop and this will exit our container.

Hosting on Amazon S3

The final step is to host our static site somewhere. This is fairly trivial to do with Amazon S3 and gives us the benefit of Amazon’s reliability and CDN. Follow this guide to set up an S3 bucket with correct permissions.

We can use the handy s3_website tool to synchronize files with our S3 bucket when we make an update. And because I’ve discovered a shiny new hammer, I’ve created a Docker image that encapsulates s3_website and its dependencies as well.

Pull down the image.

$ docker pull alani/s3website

Create the S3 config and add your bucket information, including AWS credentials. Don’t check s3config.yml into source control.

$ alias s3website="docker run -i -t --rm -v `pwd`:/src alani/s3website"
$ s3website cfg create # Creates s3config.yml
$ open s3config.yml # Add your S3 information & credentials. Don't check in

It’s time to generate the final set of files and upload to S3.

$ hugo --baseUrl="http://ahmedalani.com"

0 of 0 drafts rendered
0 future content
1 pages created
0 paginator pages created
0 tags created
0 categories created
in 107 ms

$ s3website push --site public

[info] Deploying public/* to ahmedalani.com
[succ] Created index.xml (application/rss+xml)
...
[info] Summary: Created 39 files. Transferred 1.6 MB, 2.1 MB/s.
[info] Successfully pushed the website to http://ahmedalani.com.s3-website-us-east-1.amazonaws.com

Final Thoughts

I wrote this article to see if Docker can serve as a useful wrapper for everyday tools and so far I’m pretty happy using it across multiple machines. As you’ve probably deduced, dockerizing tools can get out of control if we start creating bloated containers for every single simple process. Try to build and use lean images and, at the end of the day, remember that this is just another tool in your belt.