Into the Pocketverse

This blog is an overview of what I've been up to since August. The work I've focused on has mostly been centered on developing a single-page application for a Pocket Server. Though I have a working prototype, it attracted the interest of a friend as a key component to one of his projects, and I am holding onto that code while this gets sorted out. Through the development of this, though, I did some yak shaving and have gathered these projects under the moniker of the Pocketverse.

The constraints of developing against a Pocket Server led me to write tooling that gave me a tighter development feedback loop. The first major component was generating OpenAPI-style documentation for the REST server that runs on the Pocket Server. The client is documented on the website, but it's not in a machine-consumable format. I wrote Mocket, a mock server that would allow me to test the features I needed on my laptop without needing to have a Pocket Server running and connected. The last thing I wrote was Munztasche, which is a simple utility for inlining.

Each of these yaks warrant their own post because each of them was their own project within the project. I am not prepared to do that at the moment, and I hope that anyone developing for Pocket Servers either finds them useful, has advice, wants to collaborate, or some combination thereof.

Pocket Server API

The OpenAPI specification is great for operating in a REST environment and having a common means of documenting it. While the Pocket Server rest API is simple enough that I need only rely on Javascript's fetch, I knew that I might want a little more handling and would prefer a client I could regenerate automatically as the REST API settled and I reflash the boards with the latest firmware firmware. I ended up using a handlebars template to further coerce what the generated code ended up looking like. Given the hardware limitations, I was seeking a balance between small file sizes and ergonomic developer experience. This project lives at the pocketverse/pocket-server-api repository. I intended on having a tutorial written up before posting this, but time marches on and other projects require my attention. I figure it would be better to record my thoughts now and (hopefully) spark some interest in Pocket Servers and possibly hacking on these developer experience tools with me.

Mocket

I am fully bought into the school of thought that you should be able to deploy a damn good approximation of your production environment locally on your laptop. For many reasons, it's often impossible to get something that is directly 1:1, but I think the exercise is worth trying because it helps you understand what you're working with better, and whatever you do come up with should provide tighter feedback loops. So, since I had the API documented, I knew that I didn't really want mock responses and that I would be better served by having something that emulated the behavior of the Pocket Server. I wrote Mocket for this and only implemented the endpoints I needed. Currently, I have working implementations for the GET /files and GET /files/{filename} endpoints. Minus the FAT32 constraints on the board, those endpoints behave like the Pocket Server itself. The remaining endpoints are not implemented. I intend to implement them as needed, and I welcome others to contribute.

Munztasche

Munztasche is two things. Maybe it is one and a half things. There is the Munztasche Design Pattern, a file structure and development pattern that keeps Node dependencies out of the application and provides a standard to build an inlining tool around. The inlining tool is a simple command-line utility that reads through the tag and extracts all the CSS and Javascript links. It then squeezes all of the code into the Pocket Server required single index.html .

Tying Them All Together

The way that I started my application is by writing down the features I would need that interact with the Pocket Server REST API. Once I had those endpoints gathered, I copied those specific endpoints from pocketverse/pocket-server-api into a docs/api/spec.yaml file in the repository. The use of a discrete subset of the full API specification is intentional. Not only does this keep the file we end up with lighter, but we don't run the risk of exposing additional capabilities through our application.

After the spec.yaml is crated, I then copied the pocketverse mustache template into /templates/index.mustache. From there I ran this command:

openapi-generator generate \
    -i docs/api/spec.yaml \
    -g javascript \
    -t templates/ \
    -o ./js/generated-client \
    --global-property apiTests=false,modelTests=false,apiDocs=false,modelDocs=false

You will note that this command turns off the tests and the documents, and the reason for this is that I only want an index.js file that gives me methods I can use once imported. Something I also do with this command is keep a dev version. The difference between the spec.dev.yaml and the spec.yaml is that the defined URL is http://localhost:8010instead of http://pocket.local and the reason for that is because I built the initial application against Mocket.

So, now that we have a standardized method of accessing both our dev and production APIs, we can write our business logic. We could connect to the pocket server and upload the file or we could download and perform a go run main.go. With the exception of the aforementioned completed endpoints, all the endpoints attached to the Mocket server will return a 200 OK and the message "endpoint not yet implemented."

Assuming there is some complexity to our application and knowing that we have avoided using a front-end framework, following the Munztasche Design Pattern we separated out the CSS & JS of the code so that the structure, interactivity, and style were all separate components; however, we must get it back into a single file so we can see how it behaves on the server itself.

For this inlining task, I pull down Munztasche and build it. Once I have it built, I can put the binary in my home path, but the project is still being developed, so I copy the binary into the repository I'm working out of and run ./munztasche b index.html. It outputs the bundle HTML into a /dist directory.

We're now off to the races and can upload the file to the server for testing and see how different devices interact with my Pocket Server application.

Coda

Having now done this, I am happy that I've found a way to give myself a development process that will make working with the Pocket Server easier to drop in and out of. It has also given me this horror-euphoria notion that creating tools that work for my purposes is more within my reach than I previously thought. It's euphoric because I know what works for me, and it's tinged with horror because it might mean a lifetime's worth of yaks.

As for this little collection of projects, I think the API documentation is as complete as it can be without battle testing each endpoint, and I left some tutorials around OpenAPI that I would like to write on the table. The other two utilities are incomplete, but I hope they can grow with the Pocket Server ecosystem. In each of the repositories, I added a CONTRIBUTING.md with a "what needs doing" section. Here, I captured where I left the state of things, what some aspirations are, and generally what kinds of contributions would be welcomed. Hope to catch you at the code forge!

Mocket

Munztasche

Tying Them All Together

Coda

License

Comprar Glass Hound Computing un café

Más de Glass Hound Computing