Forem: Jackson Bowe

Mafia 1: User Authentication

Jackson Bowe — Fri, 21 Apr 2023 05:02:31 +0000

This is the second post in a series of articles documenting my process creating a serverless multiplayer game - Mafia.

This article covers adding User Authentication and Authorization to the game.

Setup AWS
Infrastructure overview
User authentication
User authorization
Quasar frontend

Setting up AWS for a new project

If you search online for AWS project best practices you will find a dozen different guidelines all espousing their method to be the "best". I'd like to avoid pushing my methodology on you here, but this is a quick rundown of the process that I used.

My main AWS account (the one that I first created) is an empty shell containing no resources. In this account I created an AWS Organization. Under an organization, you can create groups - I've made a group for Mafia. Inside the Mafia group I make two more groups; dev and prod. These two groups each have an AWS account in them.

In my root AWS account I then configured IAM Identity Center for Single-Sign-On (SSO) and created an SSO profile for myself with Admin Access to the two Mafia accounts. This new SSO account can now generate AWS CLI access keys for each of the deployments (prod/dev).

Infrastructure Overview

In this game users will have individual profiles. Logging in retrieves the associated profile from the database and tags all future API calls with the users' ID. The API will then use the provided ID to determine if the caller has permissions to perform whichever action they're attempting.

AWS has all the tools to create a robust serverless user authentication system and SST makes it super easy to get started. For this project I'm going to be using the following AWS services:

AWS Cognito - to handle user authentication (validate passwords)
AWS ApiGateway - to route frontend actions to backend functions
AWS Lambda - the logic
AWS DynamoDB - to store user profiles

There are two main 'routes' to the API for authentication; /noauth and /{other}. The /noauth route is exclusively used for signup/signin/recovery/etc actions (may be expanded in future).
The /{other} route is simple a placeholder for all other routes. Each of these calls are processed through a custom Lambda Authorizer which validates the users access token and then forwards to the AuthController Lambda.

DynamoDB setup

DynamoDB is a NoSQL database which offers huge horizontal scaling for a relatively low price point, following a pay-per-request model. There's plenty of ways to use DynamoDB but for this project I'm attempting to follow Single Table Design (STD??) principles as best I can.

The goal of STD is one big boy DynamoDB table that holds all entity data in one place. The benefits of this approach is speed (apparently?) and increasing the complexity of your business logic by a few magnitudes. I'll try until it gets to hard I guess.

With the single table approach it's important to have a good grasp on what the access patterns are going to be. That is, in what ways do I intend to query data. Theoretically, by knowing how you intend to query the data you can infer the optimal way to store it. If you are unfamiliar with DynamoDB this next part might be a bit confusing.

Currently my access patterns are as follows:

[GET] Item by exact ID (PK + SK) - To retrieve a single record: User/Lobby/Game/etc
[QUERY] Items by partition ID - To retrieve all records under a partition key: eg. A Lobby and all Users in it
[QUERY] Items by type (GSI1) - To retrieve all records of a type Users/Lobby/Game

GET calls return exactly one record whereas QUERY's return all records that match.

In NoSQL Workbench I made a mock up of the data structure to visualize my GSI's.

Primary projection: The red marking shows that Lobby(PK=2143) contains records for itself (SK=A) and the user UncleGenghi (SK=U#1234). Note that I'm encoding the entity type into the SK.

GSI1 (itemsByType): Projects all records into their TYPE grouping.

User Authentication

As mentioned previously, I am using AWS Cognito to handle user registration and validation. The Cognito functions are exposed to the frontend via HTTPS API using ApiGateway. Calls such as /noauth/auth pass directly to the AuthController, in this example returning a JWT access token (providing supplied email and password are valid). The JWT token must then be used in the headers of all future requests.

User Authorization

I decided to use a custom Lambda Authorizer for this project with these two resources for reference: AWS Article, Code.
Custom Lambda Authorizers are great for adding fine grain authorization but come with some noticeable performance reductions and cost increases.

For starters, in terms of AWS resources a Lambda Authorizer is identical to a standard lambda function. This means that all API Gateway routes that flow through a Lambda Authorizer now count as 2 lambda invocations. Two invocations means an increase in time and cost. The more complex the authorizer, the slower every API route that uses it gets.

Below is an example of an API call that returns a list of all open lobbies. As we can see, before the GET /lobby/list call we must first be authorized.

Overall, while the authorizer definitely adds overhead to the API I believe that the ability to have granular access is crucial.

Quasar frontend

Quasar framework is my go-to when building complex web apps. It uses VueJS under the hood but comes with so many useful utilities that it's hard for me to justify not using it.

I think that both the best and worst thing about Quasar is how easy it is to create visually appealing and responsive frontends. I say "and worst" because to be honest, using Quasar feels like cheating. Prior to using Quasar I had very little frontend experience with vanilla Javascript and CSS, essentially zero foundational knowledge. Quasar lets me get away with not learning the basics and still succeed. Still not sure how I feel about that, but anyway...

This is my attempt at a login page. It's probably nothing fancy to any experienced WebDev's reading, but it's pretty up there for me. I linked it up to the backend and it works great. I may remove the self signup feature temporarily in place of an invite-only system so I can do some controlled public testing, but that's unimportant to this article.

To ensure that my design is appropriately responsive I'm using an app called ResponsivelyApp. The app lets me select several target screen sizes and validate my design on all of them in the same screen. Check it out.

That pretty much wraps up everything I wanted to cover in this article. In my estimation the main educational aspect of this article series is going to be the AWS design and integration. Frontend design/development is very much a necessary chore to me while API and cloud infrastructure design it where the real interesting stuff happens.

At the time of writing this I've made significant progress towards a lobby hosting/joining system. It's not quite at the stage where I can confidently write about it, but what I can say is that it leverages AWS IoT Core to facilitate real-time push notifications to the frontend.

If you're interested in this project I've made a discord (https://discord.gg/EcGx9h2fwy) where I post updates as I go. Happy to answer any questions whether technical or game related.

Cheers,

Mafia: A Serverless Multiplayer Game

Jackson Bowe — Mon, 27 Feb 2023 01:19:56 +0000

This is the first post (of hopefully many) where I will be documenting my journey creating a serverless multiplayer game; Mafia (name not final... unless???).

I'm going to use this first post to cover the tools I intend to use and give a general idea of what this game should look like at the end. So here we go...

What is this game?

I'm basing this game heavily on the popular table top game by the same name. It's a social deduction game in which a majority team, the Townies, try to root out the opposing minority team, the Mafia.

Members of the Mafia are aware of their allies and must work together to mislead the Town and avoid suspicion. Town players are not aware of anyone else's role and must use their deductive reasoning to locate evildoers.

Mechanics

The game isn't strictly turn based however it follows a similar principal. There are four states; Morning, Day, Evening, and Night.

During the Day all members of the town (inclusive of the mafia members) gather to discuss what leads they have found on the Mafia. At this time they may also decide to remove a player under suspicion of being a member of the Mafia.

At Evening, the public forum closes and players are given time to process they day's conversation, and if possible with their role they can chose a player to target that night. For example, a Detective may chose to follow another player and see who they visit that night. Mafia members are able to converse amongst themselves during this time.

During the Night the game processes all the player actions.

In the Morning, the events of the previous Night are revealed to the Town.

The cycle repeats until there is a winner.

Enough with the nerd stuff, tell me about the tech stack!

Heavy sarcasm :)

Tools I'm using to make this

I want the game to be playable in the web browser at this stage, may change in future. Also primarily using AWS for the backend.

Backend

AWS ApiGateway for player to backend communication
AWS DynamoDB as a database following Single Table Design principles
AWS Cognito for user authentication
AWS S3 for medium/large file storage (images etc.)
AWS IoT Core for the pub/sub functionality (live updates)
Postman to test and document the API

All application logic will be written in Python.

Frontend

The frontend will be made with Quasar Framework - a Vue.js wrapper. Quasar comes bundles with a wide array of prebuilt components and very thorough documentation. An additional benefit is that Quasar streamlines the process of packaging a single codebase into multiple deployment formats; web, mobile, and desktop. This sparks joy.

The glue

As I previously stated my goal with this project is 100% serverless, however there is another requirement that is just as important; 100% Infrastructure as Code. IaC is exactly as it reads, all infrastructure covered in the Backend section should be provisioned in code, with nothing needing to be created in AWS manually.

There are several benefits to this approach:

Changes to Infrastructure can be tracked with Git. Manual editing via the AWS console is un-trackable and generates no history.
The project can be deployed with a single command. If I deploy in Australia, and then have reason to deploy in North America, I must be able to do so with confidence and speed.
The project can be destroyed with a single command. This is extremely important. If I determine that the cost becomes unsustainable I must be able to completely eradicate all traces of it with no remnants remaining. Scorched earth.

The IaC framework I will be using for this project is Serverless Stack (SST).

SST is a cloud architecture development kit that lets you provision Infrastructure as Code by leveraging the base AWS CDK with improvements geared towards serverless applications. If you've used any IaC providers in the past like Terraform, AWS CDK, Serverless, SAM etc. - I seriously recommend checking out SST. It's next level.

Process, MVP, and Timeline

This project is my way of diving head first into serverless cloud development. I'm using something I'm passionate about to motivate and upskill myself into a field that I think is the future. For this reason I will be attempting to follow as many best practices as I can, and sharing them here as I adopt them.

Below is a flow chart with my rough architecture plan. This will no doubt change as the project matures.

Process

User actions are sent via REST API to an AWS Api Gateway. This distributes requests to the appropriate lambda microservice, called Controllers. The Controllers handle all application logic between frontend and backend services such as the database.

As there is no server I am not able to maintain continuous state. All user actions must be written to the database. During the Night sequence, all user actions will be read from the database and combined with data about the game (settings etc.).

The combined user actions and game settings will be resolved using my custom MafiaEngine. This will return the resolved game state to be communicated back to the users.

Minimum Viable Product

The maximum number of players in a game is 15. A typical game will have 9 Town players, 3 Mafia players, and 3 Neutrals. A fully featured game will have large role diversity between the players, however as players can share the same role I will be aiming for the following.

Town: Citizen, Doctor, Bodyguard, Detective, Escort

Mafia: Mafioso, Liaison (evil Escort)

Neutral: Serial Killer, Survivor, Jester (of course)

The game will need a fully functioning lobby system, stage transitioning (morning/night/etc.), and state resolution.

Timeline

I began routine work in early January 2023 and have maintained decent weekly progress. I hope to have a playable version of this game out within 2 months (end April). Between now and then I will aim for regular updates and cover technical roadblocks and solutions.

Conclusion

I don't particularly want this series to be a generic game "devlog" thing. The real motivation behind this project was to get familiar with serverless cloud development and I think it's going to be a massive learning opportunity.

What I'm more interested in writing about it showing how I've implemented some serverless feature and provide a legitimate use case that it is fulfilling.

If this project sounds interesting I'd love to hear from you, especially if you see me running headlong into a classic pitfall.

Note: I'm keeping somewhat-up-to-date technical documentation for the project at https://mafia-sdg.netlify.app/.

Cheers,

Provisioning Lambda Docker Images with AWS CDK (Python)

Jackson Bowe — Fri, 10 Feb 2023 04:43:51 +0000

This is Part 1 of a two-part post. In this part, I will cover provisioning the lambda docker image, and in the next part, I will cover interacting with it.

Covered:

Declare Lambda Docker Image in CDK
Importing local modules to main docker script
Writing the Dockerfile
Reading/Writing to Docker Image filesystem
Testing locally

Prerequisites

Docker installed
CDK installed and set up correctly

Prior experience with Docker would be helpful, although I managed to figure this out and it was my first time dealing with Docker so you should be fine.

Directory structure

cdk-project
|-- lambdas/
    |-- docker_func/
        |-- app/
           |-- __init__.py
           |-- components/
              |-- __init__.py
              |-- com1.py
              |-- com2.py
           |-- utils/
              |-- __init__.py
              |-- ut1.py
           |-- main.py
           |-- output.json # Optional
        |-- Dockerfile
        |-- README.md
        |-- requirements.txt
|-- project/
   |-- project_stack.py

Process

Step by step process based on the above project structure. The file names I’ll be using in these steps directly relate to the files in the above Directory Structure.

Note: Starting in the root directory of your CDK project ../#/cdk-project>

1 - Declare the docker using CDK

# ../project/project_stack.py
docker_lambda = _lambda.DockerImageFunction(self, 'DockerLambda', 
    code=_lambda.DockerImageCode.from_image_asset(
             'lambdas/docker_func'
    ),  
    timeout=Duration.seconds(30), # Default is only 3 seconds  
    memory_size=1000, # If your docker code is pretty complex  
    environment={  
        "BUCKET_NAME": bucket.bucket_name # Optional  
    }  
)

2 - In a new terminal navigate to top-level of docker function

cd lambdas/docker_func

3 - Provision some basic components/util classes

# app/components/com1.pyclass Com1():  
def __init__(self):  
  pass
###

# app/components/com2.pyclass Com2():  
def __init__(self):  
  pass
###

# app/utils/ut1.pyclass Ut1():  
def __init__(self):  
  pass

4 - Set components and utils to be treated as modules by adding __init__.py to each folder and importing the classes specified in #3.

# app/components/__init__.py  
from components.com1 import *  
from componented.com2 import *

###
# app/utils/__init__.py  
from utils.ut1 import *

Warning
If you skip this step you will not be able to import these modules in the way that you think. When docker packages up your files it moves them all around which breaks relative imports (even though it may work locally)

5 - Write the dockerfile

FROM public.ecr.aws/lambda/python:3.8

# Copy function code  
COPY app/main.py ${LAMBDA_TASK_ROOT}

# Add local dependencies  
ADD app/components components  
ADD app/utils utils  
ADD app/template.docx template.docx  

# Install the function's dependencies using file requirements.txt  
# from your project folder.COPY requirements.txt  .  
RUN  pip3 install -r requirements.txt --target "${LAMBDA_TASK_ROOT}"

# Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile)  
CMD [ "main.handler" ]

Info
I'm using main.py in this example, note all occurances and change if needed

In the Add local dependencies section of the Dockerfile there’s some important details.

These ADD commands tell docker that when it is packaging up your files it needs to grab the contents of source and place it in target when done.

eg. ADD source target > ADD app/components components

This means that once our app is built, we can access the files inside components via

from components.com1 import Com1

The last line CMD ["main.handler"] sets the docker entry point to the function handler in main.py:

# main.py
def handler(event, context):  
    pass

If you don’t want to call your file main.py then just change all instances where I use it to your preferred name.

6 - Deploy your changes. It should take a while to upload initially. I mean a long while. Like 7–10 minutes.

Writing to the local file system (optional)

If you try to write a file you will get:

[ERROR] OSError: [Errno 30] Read-only file ststel: '/path'

This is because the only writable directory with any AWS Lambda function is the /tmp folder.

If you need to write a document, do it like below:

document.save('/tmp/report.docx') # example using python-docx

Testing locally

Uploading the docker image every time you make a change is possibly the fastest way to transform your brain from goo to soup. Don’t do that. Do this instead.

Say you’ve got a Docker Image that uses the python-docx library (not important, it’s just a good example). Your script loads a template.docx file and saves the resulting output.docx file.

To test locally we use python’s if __name__ == "__main__": magic to provide dummy data to our handler function. This method will ONLY run when we manually run the script.

# main.py
def handler(payload, context, prefix='/tmp/'):  
   # ... code  
   document.save(prefix+"output.json")  
   # ... more code  

   return  

if __name__ == "__main__":  
    with open("input.json") as f: # input.json sample event input  
        handler(json.load(f), None, prefix='')

Note in the above code I’m using a prefix argument to my handler() function. This is to control where the output file is written. For my local testing, I don’t want the file to be written to the /tmp directory because that will be a reserved folder once I deploy.

To run the file locally you will need to be in the app folder (referencing the directory structure from the start).

C:\<path>\cdk-project\lambdas\docker_func\app> python main.py

That should pretty much cover it. The above steps are all I needed to do to get my lambda working. For reference what it does is:

One lambda function preps a json object and sends it to the Docker Image.
Docker Image parses the json data, imports 3rd party libraries, reads and populates template documents, saves the output to docker filesystem, uploads the result to S3, and finally returns the S3 object URI to the Lambda that invoked it.

Hopefully this is helpful to anyone who reads. Thanks.

Forem: Jackson Bowe

Mafia 1: User Authentication

Contents

Setting up AWS for a new project

Infrastructure Overview

DynamoDB setup

User Authentication

User Authorization

Quasar frontend

Mafia: A Serverless Multiplayer Game

What is this game?

Mechanics

Enough with the nerd stuff, tell me about the tech stack!

Tools I'm using to make this

Backend

Frontend

The glue

Process, MVP, and Timeline

Process

Minimum Viable Product

Timeline

Conclusion

Provisioning Lambda Docker Images with AWS CDK (Python)

Prerequisites

Directory structure

Process

Writing to the local file system (optional)

Testing locally