Forem: Ivan

How to Get Your Brand Recommended by ChatGPT

Ivan — Fri, 23 Jan 2026 23:35:47 +0000

When someone asks ChatGPT "what's the best CRM for small businesses" or "can you recommend a project management tool," the AI provides direct suggestions. If your brand appears in those recommendations, you gain a significant advantage in the consideration process. If you are absent, potential customers may never discover you.

This guide explains how ChatGPT forms recommendations and what you can do to increase your chances of being recommended.

How ChatGPT Decides What to Recommend

ChatGPT does not browse the internet in real-time for most queries. Instead, it draws from patterns learned during training on large amounts of text data. When recommending products or services, ChatGPT references what it learned about brands, their reputations, their features, and how they are discussed across the web.

Several factors influence whether ChatGPT recommends your brand:

Content volume and quality: Brands with substantial, high-quality content explaining what they do and why they are valuable are more likely to be well-represented in training data.

Third-party validation: Reviews, mentions in publications, expert endorsements, and customer testimonials all contribute to how ChatGPT perceives your brand's credibility.

Clear category association: ChatGPT needs to understand what category your brand belongs to and what problems it solves. Ambiguous positioning leads to missed recommendations.

Reputation signals: The overall sentiment of how your brand is discussed online influences whether ChatGPT views you as a recommendable option.

Step 1: Audit Your Current Visibility

Before optimizing, understand where you stand. Ask ChatGPT the questions your potential customers might ask about your product category.

Test queries like:

"What is the best [your category]?"
"Can you recommend a [your product type]?"
"What are the alternatives to [your competitor]?"
"What [product type] should I use for [use case]?"

Document whether your brand appears, where you rank in the recommendation list, how you are described, and which competitors appear instead.

This baseline helps you prioritize efforts and measure progress. For a detailed framework, see our complete AI audit guide.

Step 2: Create Comprehensive Content

ChatGPT learns from content available on the web. If your brand has limited content explaining what you offer, why it matters, and who it helps, ChatGPT has little to reference when forming recommendations.

Develop content that clearly establishes your brand:

Product and service pages that explain exactly what you offer, not just feature lists but the problems you solve and outcomes you enable.

Comparison content that honestly positions your offering relative to alternatives, helping ChatGPT understand where you fit in the market.

Use case content addressing specific scenarios where your product excels, making it easier for ChatGPT to match you with relevant queries.

FAQ content answering common questions about your category and your specific offering.

Thought leadership demonstrating your expertise in your space through guides, analysis, and educational content.

The goal is ensuring that when ChatGPT processes information about your category, your brand is well-represented with clear, accurate, and comprehensive information.

Step 3: Build Third-Party Validation

ChatGPT weighs third-party sources heavily. Self-promotional content on your own website matters, but external validation carries more weight.

Focus on building:

Customer reviews on relevant platforms. Encourage satisfied customers to leave detailed reviews explaining their experience and the value they received.

Media coverage in publications your industry respects. Seek opportunities for features, interviews, or expert commentary.

Expert endorsements from recognized authorities in your space. Analysts, industry experts, and respected practitioners can provide valuable validation.

Case studies and testimonials that document real customer success, preferably with specific metrics and outcomes.

When ChatGPT encounters consistent positive signals about your brand from multiple independent sources, it increases confidence in recommending you.

Step 4: Strengthen Category Association

ChatGPT needs to clearly understand what category your brand belongs to and what specific problems you solve. Weak or ambiguous positioning leads to missed recommendations.

Ensure your brand is clearly associated with:

Your primary category: If you are a project management tool, that association should be unmistakable across your content and mentions.

Specific problems you solve: Beyond category, connect your brand to the particular challenges you address.

Your target audience: Who is your product for? Enterprise teams, small businesses, specific industries?

Key differentiators: What makes you distinct from alternatives in your category?

Consistent messaging across your website, third-party profiles, and external mentions reinforces these associations.

Step 5: Optimize for Related Queries

ChatGPT responds to many different phrasings of similar questions. Consider the various ways potential customers might ask about solutions in your category.

Create content addressing:

Direct category queries: "best [category]" type searches

Problem-based queries: "how do I solve [problem]" where your product is the answer

Comparison queries: "alternative to [competitor]" or "[product A] vs [product B]"

Use case queries: "[category] for [specific situation]"

Feature queries: "[category] with [specific capability]"

Content addressing these different query types increases the chances that ChatGPT connects your brand with relevant questions.

Step 6: Maintain Accuracy and Consistency

ChatGPT can become confused when it encounters contradictory information about your brand. Ensure consistency across all platforms:

Consistent naming: Use the same brand name everywhere, avoiding variations that might not be connected.

Accurate information: Keep product information, pricing, and claims current and accurate across all sources.

Unified positioning: Communicate the same core value proposition across channels.

Inconsistencies in your information can reduce ChatGPT's confidence in recommending you or lead to inaccurate descriptions.

Step 7: Monitor and Adjust

AI recommendations are not static. ChatGPT's responses can shift as models are updated, and your competitive landscape continues evolving.

Establish ongoing monitoring:

Regular testing: Query ChatGPT monthly with your key questions and document changes.

Competitor tracking: Note when competitors appear or disappear from recommendations.

Description accuracy: Monitor how ChatGPT describes your brand and correct inaccuracies through content updates.

Continuous attention allows you to identify and address issues before they become significant problems.

What About ChatGPT's Browsing Features?

Some ChatGPT users have access to browsing capabilities that allow real-time web searches. For these queries, traditional SEO factors become more relevant since ChatGPT actively searches for current information.

Strong search visibility complements AI recommendation optimization. Brands that perform well in both areas capture opportunities regardless of how users interact with ChatGPT.

For more on how traditional SEO and AI optimization work together, see our GEO vs SEO guide.

Common Mistakes to Avoid

Expecting immediate results: ChatGPT's knowledge is based on training data, not real-time information. Changes you make today may take time to influence recommendations.

Focusing only on your website: Third-party validation often matters more than your own content. Balance investment between owned content and external presence.

Ignoring competitors: Understanding what competitors who get recommended are doing differently provides valuable insights for your own strategy.

Generic content: Vague marketing language does not help ChatGPT understand what makes you valuable. Be specific about capabilities, outcomes, and differentiators.

Getting Started

Begin with an audit of your current ChatGPT visibility. Understanding your baseline tells you whether you need foundational work or refinement of existing presence.

If you are absent from recommendations entirely, prioritize comprehensive content development and third-party validation. If you appear but are poorly positioned, focus on strengthening specific weak areas.

The brands establishing ChatGPT recommendation presence now are building advantages that become harder for competitors to overcome as AI assistants become more central to how people discover products and services.

Want to understand how your brand currently performs in AI recommendations? Get a free visibility report to see where you stand and what to prioritize.

Git Isn't Enough for AI Coding: What I Use Instead

Ivan — Fri, 23 Jan 2026 22:59:50 +0000

I've been using Git for over a decade. It's one of the best tools ever made for software development. But after six months of heavy AI-assisted coding, I've had to admit something uncomfortable:

Git's workflow doesn't match how AI coding actually works.

This isn't a criticism of Git. It's an observation about how AI assistants have changed the development loop.

The Problem

Git was designed for deliberate, discrete changes. You work on something, stage it, write a meaningful commit message, and move on. The rhythm is: work → commit → work → commit.

AI coding breaks this rhythm completely.

When I'm iterating with Cursor or Claude Code:

I try three different approaches in ten minutes
The AI modifies files I didn't explicitly ask about
Changes happen faster than I can meaningfully review them
I'm focused on guiding the AI, not thinking about version control

In practice, I end up with long gaps between commits. And those gaps are exactly when AI does something unexpected—deletes files it thinks are "unused," breaks imports, or refactors in a direction I didn't want.

Git protects what I commit. It can't protect what I don't.

What I Tried First

More discipline: "Just commit before every AI operation." This works in theory. In practice, when I'm in flow and iterating quickly, I skip it. The one time I forget is the time Cursor deletes my middleware folder.

Cursor Checkpoints: These are useful but limited. They only cover Composer interactions, don't persist across sessions, and revert everything from a prompt (including manual edits I made after).

VS Code Local History: File-by-file recovery. Tedious when AI changed 20 files.

Git stash: Manual, requires discipline, only one stash at a time.

None of these provided reliable, continuous protection.

What I Use Now

I found a tool called mrq that takes a different approach. Instead of requiring commits, it captures every file change automatically in the background.

npm install -g mrq-cli
mrq watch

That's it. Now every change is recorded—from AI, from manual edits, from anything.

When something breaks:

mrq history          # See recent
snapshotsmrq restore abc123   # Go back to any point

I'm back to exactly where I was, even if I never committed. The mrq docs explain the full workflow, but honestly the basics are just those two commands.

How I Use Both Together

I haven't replaced Git. I use both for different purposes:
Git: Meaningful commits, collaboration, deployment, PR reviews
mrq: Continuous protection during AI iteration

My workflow:

Start session: mrq watch
Work with AI freely, iterate fast
Hit a milestone: git commit -m "Feature complete"
Something broke? mrq restore

Git gives me clean history for collaboration. mrq gives me protection during the messy iteration phase.

When You Need This

If you're doing light AI usage—occasional Copilot suggestions, simple completions—Git alone is probably fine.

If you're doing heavy AI coding—Cursor Composer, Claude Code multi-file edits, agent mode—you need continuous protection. The speed and unpredictability of AI changes creates gaps that Git's commit model doesn't cover.

There's a good breakdown of why git doesn't fit AI workflows that explains this in more detail.

Conclusion

Git remains essential. It's still the backbone of collaboration, deployment, and project history.

But AI coding has exposed a gap between commits where you're unprotected. For me, the solution was adding automatic snapshots to my workflow—not replacing Git, but complementing it.

The developers I know who work confidently with AI have all set up some form of continuous protection. The specific tool matters less than having something that doesn't require discipline to remember.

What do you use for AI coding protection? I'm curious if there are other approaches I haven't tried.

The Best Way to Use Teenage Engineering Manuals

Ivan — Wed, 21 Jan 2026 17:45:19 +0000

If you own a Teenage Engineering device, you've probably tried to use the official PDF manual. The EP-133 manual is 144 pages. The OP-1 manual is 100+ pages. The OP-XY manual is even longer. These are dense technical documents that assume you'll read them cover-to-cover, but in reality you just need quick answers to specific questions.

There's a better way: Teenage Manual - a searchable, conversational interface for all Teenage Engineering device manuals. Instead of scrolling through PDFs, you can ask questions and get direct answers from the official documentation.

What It Is

Teenage Manual is the best way to access Teenage Engineering manuals. It supports 9 devices with full manual access:

EP-133 (KO II) - The sampler
OP-1 - The original portable synth
OP-1 Field - The upgraded version
OP-XY - The latest flagship
EP-1320 - The medieval-themed sampler
EP-40 - The riddim machine
TX-6 - The portable mixer
TP-7 - The field recorder
CM-15 - The modular controller

Each device has its own page with two ways to access the manual: ask questions in a chat interface that knows the manual inside and out, or browse the manual in a structured view organized by category.

How It Works

The AI chat interface is available on each device's ask page - for example, EP-133 ask, OP-1 ask, OP-1 Field ask, OP-XY ask, EP-1320 ask, or EP-40 ask.

The AI uses the full OCR'd manual as context, so it's not making things up - it's giving you answers directly from the official documentation. Ask "how do I copy a pattern?" and it tells you exactly how, with the right button combinations and clear instructions.

You don't need to know the exact terminology. Ask "how do I make it louder?" and the AI understands you're asking about volume or gain. The AI knows which device you're asking about, knows the full context of the manual, and can reference specific sections and button combinations.

Error Codes and Troubleshooting

When your device shows an error code like E.05 or E.10, you need to know what it means and how to fix it. Teenage Manual has dedicated error code pages for devices that have them:

EP-133 error codes - Complete troubleshooting guide for E.01, E.02, E.03, E.05, E.10, E.11, E.12
EP-1320 error codes - Fixes for E.01, E.02, E.03, E.04, E.05
EP-40 error codes - Solutions for E.01, E.02, E.03, E.04, E.05

Each page shows what each error code means, whether it's a hardware issue or something you can fix yourself, and step-by-step instructions for fixing the fixable ones.

Why It's Better Than PDFs

PDF manuals are designed for printing, not for finding information. When you're in the flow making music, you need quick answers, not a 144-page document to scroll through.

With Teenage Manual, you stay in the flow. Ask a question, get an answer, keep making music. No switching apps, no scrolling, no frustration. The manual is always there, always searchable, always ready. No need to download PDFs or remember where you saved them.

The most common questions people ask are things like "How do I make my first beat?" "What does the fader do?" "How do I sync with other devices?" These are basic questions that should be easy to answer. With PDFs, they're not. With Teenage Manual, they are.

Pro Features

The free version gives you full access to all manuals and unlimited questions. Pro features ($5/month) add voice input for when your hands are on the device, saved answers to reference later, YouTube context to use tutorial transcripts as context for questions, and synced chat history across devices.

The voice input is useful when you're working with hardware and your hands are busy.

Real-World Usage

Since launching, there have been 1,000+ users in the first week and 3,500+ questions asked. People are using Teenage Manual instead of Googling everything or scrolling through PDFs.

Check out the wall of love to see what users are saying.

Try It Yourself

If you own a Teenage Engineering device, give it a try. Go to your device's ask page - for example, EP-133 ask, OP-1 ask, OP-XY ask, or EP-1320 ask - and ask a question. Try "How do I make my first beat?" or "What are the tape tricks?" or "How do I sync with other devices?"

You'll get direct answers from the official manual, with proper button references and clear instructions. No scrolling, no guessing, no context switching.

If you're seeing an error code, check the error code pages. For EP-133 errors, EP-1320 errors, or EP-40 errors, you'll find what each code means and how to fix it.

What's Next

I'm planning to open source the manual processing so the community can contribute, add more devices as Teenage Engineering releases new products, improve the manual view with better organization and navigation, and add video tutorials to integrate YouTube tutorials as learning resources.

You can follow the changelog to see what's new.

Conclusion

Teenage Manual is the best way to access Teenage Engineering manuals. It's searchable, conversational, and actually usable. If you own a Teenage Engineering device, give it a try. Check out the pro page to see all the features.

Instead of scrolling through PDFs, you can ask questions and get direct answers from the official documentation. That's what makes it the best way to use Teenage Engineering manuals.

AI Deleted My Code: How to Recover

Ivan — Mon, 22 Dec 2025 14:07:22 +0000

It happens fast. You're iterating with Cursor or Claude Code, things are going well, and then the AI decides your codebase needs "cleaning up." Suddenly, files are gone. Maybe it consolidated what it thought were duplicates. Maybe it removed "unused" code that was actually imported elsewhere. Maybe it just hallucinated that a file shouldn't exist.

If you're reading this, it probably just happened to you. Let's get your code back, and then make sure it never happens again.

First: Don't Close Anything

Your editor likely still has deleted files in memory. Every tab you close is potential recovery lost. Keep everything open while you work through this.

Check Your Editor's Undo History

Start with the obvious. If the deleted file's tab is still open, try Ctrl+Z (or Cmd+Z on Mac) repeatedly. Sometimes the file content is recoverable even after the file itself was deleted from disk.

This doesn't always work, especially for files the AI deleted without opening, but it's worth trying first.

Use Local History

Both VS Code and Cursor maintain a local history of file changes that most developers don't know about. Press Ctrl+Shift+P (or Cmd+Shift+P), type "Local History: Find Entry to Restore", and browse for your deleted files.

This works even for files that were deleted, as long as they were edited at some point. It's saved me more times than I'd like to admit.

Check Your AI Tool's Recovery Features

If you're using Cursor, look for "Checkpoint created" messages in the Composer panel. Each prompt creates a checkpoint you can restore to. Click "Restore" next to the one from before the deletion.

For Claude Code, press Esc twice or type /rewind to open the checkpoint menu. You can restore just the code, just the conversation, or both.

The limitation with these is that they're tied to conversation context. If you've done a lot of work since the deletion, or if the deletion happened through Tab completions rather than Composer, you might not have a useful checkpoint.

Fall Back to Git

If you committed before the AI made its changes, Git is your friend:

git status           # See what's been deleted
git checkout .       # Restore everything to the last commit

If you didn't commit... well, that's the problem, isn't it? Git can only restore what you remembered to save.

When Nothing Works

If none of the above recovered your files, check your system backups. Time Machine on Mac, File History on Windows, or cloud sync services like Dropbox often keep recent versions. It's a long shot, but sometimes it works.

If you've exhausted all options and your code is truly gone, you've learned an expensive lesson about working with AI.

Preventing This Next Time

The fundamental problem is that AI agents are unpredictable. You can write better prompts, you can be more careful about reviewing diffs, but you can't eliminate the risk entirely. AI will occasionally delete things you didn't want deleted.

The solution is having recovery baked in, not bolted on.

Git works, but it requires discipline. You have to commit before every AI interaction, which breaks your flow when you're iterating quickly. And the one time you forget is the time the AI goes haywire.

This is why we built mrq. It watches your project directory and captures every file change automatically. No commits, no decisions, no interruptions. You just run mrq watch and forget about it.

When an AI deletes something:

mrq history        # See recent snapshots
mrq restore abc123 # Go back to any point

You're back to exactly where you were, even if you never committed. Even if the deletion happened three AI interactions ago. Every change is captured, every state is recoverable.

The reality of AI coding is that things break unexpectedly. The question is whether you're prepared when they do.

mrq captures every file change automatically while you code with AI. Set it once, recover instantly when things break.

Introducing Automatic Security Audits for AI

Ivan — Sat, 20 Dec 2025 18:09:47 +0000

AI coding assistants move fast. They can refactor modules, add dependencies, and wire up integrations before you've finished reading the diff. That speed is valuable, but security issues can slip in just as quickly: hardcoded API keys, string-concatenated SQL queries, debug endpoints that never get removed.

So we built something to help catch these issues early.

What It Does

mrq now scans your code changes for common security vulnerabilities automatically. Every snapshot triggers a background analysis looking for:

Hardcoded secrets, API keys, and credentials
SQL injection patterns
XSS vulnerabilities
Exposed sensitive data
Insecure configurations
Debug code that shouldn't ship

Results appear in your dashboard. If something gets flagged, you'll see a warning on that snapshot with details about what was found and where.

Issues are displayed inline with your snapshot history.

Why It Matters

Traditional security scanning happens in CI/CD, often hours after code was written. By then, the context is gone.

With mrq, feedback is immediate. You're still in the middle of your session when an issue gets flagged. You can fix it while everything is fresh.

Limitations

This is experimental. Security analysis is hard, and we're using AI to identify patterns. There will be false positives and false negatives. This is not a replacement for proper security audits, code review, or dedicated scanning tools in your pipeline.

Think of it as an early warning system. A nudge to double-check something before it gets committed.

Availability

Security audits are available on paid plans (Starter, Pro, Team). The feature runs automatically with no configuration needed.

Try it out →

How to Recover AI Coding Mistakes

Ivan — Fri, 19 Dec 2025 23:10:36 +0000

If you've spent any significant time coding with AI assistants, you've probably had that moment where something goes wrong. Maybe the AI overwrote a file you needed, or confidently refactored something in a way that broke half your tests, or went down a rabbit hole that left your codebase in a confusing state.

AI tools are genuinely useful for accelerating development. Their capability to make sweeping changes quickly can occasionally work against you though. Here's how we think about preventing and recovering from these situations.

The Recovery Problem

AI coding assistants can modify code in ways that are hard to track manually. A single prompt might touch a dozen files. The AI doesn't hesitate or ask for confirmation the way a human collaborator might. Changes happen fast, sometimes faster than you can review them.

AI assistants are actually quite capable and reliable for most tasks. The challenge is that their speed and confidence can outpace human review capacity, especially during longer sessions. You need a way to capture state continuously so you can always get back to where you were.

How mrq Handles This

We built mrq specifically for this workflow. It runs in the background while you work with AI assistants and automatically captures snapshots when meaningful changes happen. You don't need to think about version control during your session, just focus on the work.

Getting started is simple:

npm install -g mrq-cli@latest
mrq login
mrq watch --daemon

Once the daemon is running, every significant change to your codebase is captured automatically. You can see your snapshot history anytime:

$ mrq history

Recent Snapshots
────────────────────────────────────────────────────
  10:47:23  abc123  Added OAuth provider config and login route
                    +142 lines, -3 lines across 4 files

  10:43:51  def456  Refactored auth middleware to support JWT
                    +87 lines, -45 lines across 2 files

  10:41:02  ghi789  Fixed token validation edge case
                    +12 lines, -8 lines across 1 file

  10:38:15  jkl012  Initial auth module setup
                    +234 lines across 6 files
────────────────────────────────────────────────────

Each snapshot includes an AI-generated summary describing what changed, so you can quickly scan and find the point you want to return to.

Instant Recovery

When something goes wrong, recovery is a single command:

mrq restore def456

Your current state is automatically backed up before the restore, so if you change your mind, you can get back to where you were. There's no hunting through history or trying to remember when things last worked. You just pick a snapshot and restore.

The dashboard at dashboard.getmrq.com gives you a visual interface for browsing snapshots, comparing changes between any two points, and viewing the actual diffs. This is particularly helpful when you want to understand what the AI changed before deciding whether to restore.

Working Confidently with AI

The bigger benefit is psychological. When you know you can always recover, you're more willing to let the AI try ambitious things. Want to see if it can refactor your entire auth system? Go for it. If it doesn't work out, you're one command away from being back where you started.

This changes how you work with AI assistants. Instead of carefully scoping prompts to minimize risk, you can be more exploratory. Try the aggressive approach first. If it works, great. If not, restore and try something more conservative.

A Note on Git

You might wonder why not just use git for this. Git is excellent for deliberate, discrete commits with meaningful messages for collaboration and code review.

The challenge is that git requires intentional action to capture state. During rapid AI-assisted iteration, stopping to commit breaks your flow. Most developers either skip commits during these sessions (and lose their safety net) or create noisy checkpoint commits that clutter history.

mrq complements git. Use mrq for the messy exploration phase, then commit to git when you're happy with where things landed. You get continuous protection during development without sacrificing a clean git history for collaboration.

Getting Started

mrq is currently in open beta with a free tier that covers most individual developer needs. If you've experienced the frustration of losing AI-assisted work, or find yourself holding back on experiments because recovery feels uncertain, give it a try:

npm install -g mrq-cli@latest
mrq login  
mrq watch

We'd love to hear how it works for your workflow.

Build & Deploy AI-Powered Web Services from a Single Prompt

Ivan — Tue, 16 Jul 2024 17:29:32 +0000

At Shuttle, we've been working on a new tool that we think could change how developers approach AI integration. We're calling it ShuttleAI, and it allows you to build and deploy AI-powered web services from a single prompt.

Here's the TL;DR:

Describe your AI service in plain language

ShuttleAI generates a project spec for you to review

Approve or modify the spec

ShuttleAI creates the project files

You can prompt for changes or deploy

It's that simple. But let's dig into the details.

The Problem: AI Integration is Hard

If you've ever tried to integrate AI into a web service, you know it's not trivial. Here are some common challenges:

Complexity: AI frameworks often require specialized knowledge.
Time: Setting up AI services can take weeks or months.
Infrastructure: Managing AI models needs robust, scalable infrastructure.
Ongoing maintenance: AI services require continuous monitoring and updates.

These barriers can be significant, especially for smaller teams or developers new to the noisy AI space.

How ShuttleAI Works

ShuttleAI aims to simplify this process dramatically. Here's a step-by-step breakdown:

Describe Your Service: You provide a prompt describing the AI service you want to build. For example:

"Build a web service that takes weather forecast data and user profiles as input, then returns personalized weather recommendations."

Review the Spec: ShuttleAI generates a project specification document in markdown. This includes:
- API endpoints
- Data models
- AI model selection
- Infrastructure requirements
You can review and modify this spec as needed.
Generate Project Files: Once you approve the spec, ShuttleAI creates all necessary project files. This includes:
- Backend code (eg. Python with Flask)
- AI model integration code
- Infrastructure in the form of Infrastructure from Code
Iterative Refinement: You can prompt ShuttleAI to make changes at this stage. For example:
```
"Add rate limiting to the API endpoints"
```
ShuttleAI will update the project files accordingly.
Deploy: Once you're satisfied, ShuttleAI compiles and deploys your project on the Shuttle platform.

Use Cases

We're excited to see what developers will build with ShuttleAI. Here are a few ideas we've been thinking about:

Personalized Content Engines: Analyze user behavior and content metadata to provide tailored recommendations.
Intelligent Data Processing: Create services that clean, normalize, and enrich data using AI.
Natural Language Interfaces: Build APIs that can understand and respond to natural language queries.
Predictive Analytics Services: Develop APIs that forecast trends based on historical data.

Beta Testing and Early Access

ShuttleAI is still in development, and we're looking for beta testers. If you're interested in being one of the first to try it out, we're offering early access to the first 100 developers who sign up for our waitlist.

As a beta tester, you'll get:

Early access to ShuttleAI
Direct support from our development team
The opportunity to shape the future of the tool

Click here to sign up for early access!

What's Next?

We're continuously working on improving ShuttleAI. Some features we're exploring for future releases:

Support for more AI models and APIs
Advanced customization options for generated services
A marketplace for sharing and deploying AI service templates

We Want Your Feedback

ShuttleAI is still evolving, and we want to build it in a way that truly serves developers' needs. If you have ideas, questions, or concerns, we want to hear them.

Drop us a line at hello@shuttle.rs or open an issue in our GitHub repo.

Remember, the first 100 signups get early access to the beta. Don't miss out on the chance to shape the future of AI service development!

Click here to sign up for early access!

Rethinking Virtualization for Backends

Ivan — Thu, 27 Oct 2022 20:16:38 +0000

TLDR
Virtual machines and containers have improved backends in a lot of ways, but over time they have also created a lot of problems. We believe it's time to rethink how we use virtualization for backend development.

We're building a backend framework that shifts the scope of virtualization from processes down to service components.

In web applications nowadays, you can sort any component somewhere in a broad spectrum from client-side to server-side.

On the client-side, there's everything that runs on people's devices, most likely a browser or an app. On the server-side, there's everything that runs in the cloud. That includes databases, authentication management, batch jobs, events handling etc.

Each web framework squarely fits somewhere on that line. React, the most popular front-end web framework out there, is wholly client-side. Express, one of the most popular backend web frameworks, is wholly server-side.

Client-side has been historically dominated by JavaScript frameworks. This is not surprising since every client ships a powerful JavaScript engine and that is the best way to make a web page interactive.

On the server-side, things are more fragmented. This is also not surprising: backend services are just plain native processes that use their environment's network stack to respond to requests. And there is a world of different ways to write and run these: literally the history of computing.

As in many other scenarios in software engineering and computer science, this huge free space of options is also the cause of a lot of problems. To understand why, we need to talk about containers.

Containers are a solution and a problem

On its way to settling in its standards, the cloud - epitomized by AWS - has evolved massively over the past decade. My co-founder has written a post on this previously.

Today we, as software engineers, deal with it as it is: the result of incremental changes on top of a status quo. And it is not ideal.

What starts life as physical machines in a data center gets split up into tens, sometimes hundreds, of virtual machines in the AWS console. But VMs are heavy, slow to start and it's difficult to make a lot of them coexist without wasting resources like RAM and storage.

Then came along containers. Building on top of the Linux kernel's namespacing features, they made images smaller and runtimes more efficient than VMs. The genius of it is to move the virtualization layer from the hardware - where the kernel itself runs virtualized - to the software - where only processes run "virtualized". With containers, virtualized processes run natively in the host kernel, like any other. Except that their I/Os are carefully kept segregated from others in the host system. Any bit of compiled code that is executable on the host can be run in a container. And you can run processes in a container without a separate boot sequence and a full-fledged virtualized operating system with its own heavy machinery like a scheduler and dedicated virtualized hardware.

Containers are actually much older than a lot of people realise, going as far as 2008 with LXC in Linux’s case (even more in the case of FreeBSD). Their popularity, however, really took off with the arrival of Docker. The execution of Docker as a platform-as-a-service product was so good it took over software engineering practices for the following decade. And it is still the gold standard today in terms of usage.

Of course, companies were quick to build products on top of containers. They basically pass through the benefits of containers to their paying customers. Heroku is one of the most notable example. And while containers delivered most of us, directly or indirectly, from having to deal with VMs as a unit of deployment, they certainly have their issues. The biggest one being their size.

VMs have to run an entire operating system, containers don't. So they're quite a lot smaller. But container images still have to contain enough userspace to make the things you want to run actually runnable. For the way most people use them in deployments of web apps, this is generally still quite a lot!

The heavier your containers are, the more difficult everything else becomes. They take longer to build, they need more resources to run, they are more expensive to store, etc.

At shuttle we're convinced that a lot of the pains experienced by software engineers in the post-Docker world can be traced back to that very simple statement: containers are often too heavy for the job.

Replacing containers

You're probably thinking: it's nice and optimistic to say containers are too heavy, but what do you replace them with?

Well first, as an open-source company, you avoid making the same mistake Docker made. If you make the scope of virtualization too broad, you will end up with the same result as containers. The root cause behind the heavy weight of containers is that they have been built for too many usecases. They layer virtualization on top of all the I/Os of a native Linux process: their usecase is just about anything that runs.

We’re concerned with the backend services most people write. These are HTTP request/response handlers, with or without state. And for that specific usecase, most projects just end up worse off by handing over backend services as container images to their deployment platform of choice.

So we need to restrict the scope of virtualization to something more specific to web app backends. This is a trade-off of course, like most things in software engineering. By restricting the scope of a tool, you lose the ability to do certain things. But like most of these trade-offs, you usually are better served by erring on the side of simplicity unless you have specific needs that require extra complexity. In other words: use heavy machinery when you actually have a need for it, not before.

Where does that leave us then? We need a new take on virtualization. One that has, perhaps, simplified I/Os and is engineered for backend services. Thankfully, we don't have to invent most of that wheel: let's talk about WASI.

WASM and WASI

If WASM+WASI existed in 2008, we wouldn't have needed to created Docker. That's how important it is. Webassembly on the server is the future of computing. A standardized system interface was the missing link. Let's hope WASI is up to the task! https://t.co/wnXQg4kwa4
— Solomon Hykes (@solomonstre) March 27, 2019

WebAssembly (abbreviated WASM) is an instruction set for extremely lightweight virtual machines. Its most common use is to speed up client-side interactivity. This is made possible as popular browsers have rolled out WASM runtimes a few years back.

WASM is made for fast sandboxing. However, without any extension, it is unable to perform even simple I/O operations like reading data from a file descriptor. This is not a big deal if WASM is used in the browser - we definitely don't want to let browsers freely provide file system access to web apps. But it is a serious limitation if WASM is to be used server-side - how else are you going to serve endpoints without that?

Therefore, the introduction of WASM was followed, a short while later, by WASI - the WebAssembly System Interface. WASI is a standard API to give WASM code the ability to do system-level I/O. This allows WASM code running in a WASI-compliant runtime to do a lot of what a native process can do through syscalls.

The really powerful thing about WASM is that it is a very common compilation target. Major languages (and commonly associated frameworks) now support building WASM as a target, just the same way you build for amd64 or arm. And a lot of standard libraries have added support for WASI-based I/Os.

This is what Docker's founder had to say about WASI, back in 2019. And we agree with them. At the end of the day containers are, really, just I/O-level virtualization. Now, a few years after its initial introduction, WASM runtimes have stabilised their support of WASI. This creates a prime environment to engineer, on top of WASI, a solution to containers' biggest drawbacks.

Changing virtualization for backends

When we launched shuttle for its early alpha, back in March 2022, our purpose was to address the issues people face when building and deploying web app backends. So we created an open-source infrastructure-from-code platform with which you don’t need to write Containerfiles and orchestrate images, starting with support for Rust.

Since then, more than 1.2k people starred the shuttle repo and hundreds joined our discord community. And we've seen more than 2000 deployments and hundreds of users! From which we received a ton of feedback.

What we quickly realized is that while we simplified the process of getting started implementing your own backend and setting up its infrastructure, we completely failed to solve two core problems: long build and deploy times.

Rust has notoriously long build times (this probably has to do with static linking and heavy reliance on compile-time code generation). And while it supports incremental compilation out of the box, in a containerized environment, missing the cache for an image layer means having to rebuild from scratch.

We've found that no matter how much we tweaked our internal caching, too often users had to wait too long for their projects to build and deploy - something that can take minutes in the simplest projects, and closer to half an hour in complex ones. The reason was simple: our execution of our idea for shuttle is built on top of containers. And no matter how much we try to distance containers from our users, their limitations always surface back.

It was time for a complete rethink, so we took a radical view: let's start from the services people are writing, distilling what they need done quickly and easily. And let's make it our mission to optimize the hell out of the entire stack. We thought that if the execution of that idea is done right, it'd let us trim the dependency tree of services our users deploy and slim the runtime that every service ships with.

What we quickly realized is that while we trimmed down the process of getting started implementing your own backend and setting up its infrastructure, we completely failed to solve two core problems: long build and deploy times.

After all, a major culprit of these long build and deploy times in the real world is the large number of heavy dependencies of even simple projects. There's not much you can do about this: most services have a pretty big runtime that includes heavy machinery like an asynchronous executor (e.g. tokio), a web server (e.g. hyper), database drivers (e.g. sqlx) and more. And on every deploy you need to re-build them and hope artifact caches are hit in order to get an incremental build. And it's not just building either, the running time of tests is also impacted by this. The closure of the codebase you're engaging in those tests is very large indeed as it follows that of your dependencies.

This stuff materializes itself everywhere. Just try taking this hello world snippet:

use axum::{Router, routing::get};

async fn get_hello() -> &'static str {
    "You're slow, Heroku!"
}

#[tokio::main]
async fn main() {
    let port = std::env::var("PORT").unwrap();

    let router = Router::new()
        .route("/", get(get_hello))
        .into_make_service();

    hyper::Server::bind(&format!("127.0.0.1:{port}").parse().unwrap())
        .serve(router)
        .await
        .unwrap();
}

and deploy it to Heroku:

To try to address this, we wanted to move all these heavy dependencies to a common runtime across services. So your tokio, hyper, sqlx and co (in the case of Rust), now all belong to a long-lived containerized process running persistently in the cloud. Whereas all your service logic, database and endpoint code build into lightweight WASM modules that are dynamically loaded in-place by this global persistent process. That way "building" means compiling a very lightweight codebase with a small dependency footprint. And "deploying" means calling upon the control plane of that long-lived process to replace service components without rolling out new images, containers or VMs.

This leaves us with a trimmed down user-facing API that still uses familiar objects like PgClients and axum-style routes with guards:

Except that now the virtualization platform in which your services are run is responsible for instantiating these objects and calling these functions.

With this approach, the component of virtualization that you end up deploying on a daily basis is much smaller than traditional VMs and containers. In a way we can say this makes the virtualization layer more adapted to the specific needs of backend services running in the cloud. It's an optimized I/O surface between backend service components that change a lot (e.g. endpoint implementations) and their environing long-lived runtimes that don't (e.g. tokio/hyper/sqlx).

This results in "images" that are effectively up to 100x smaller because of the switch from container images to WASM binaries. And super fast to deploy too, from tens of minutes sometimes to less than a second all the time. All because when things are really incremental, you don't have to build and test a large codebase with its large userspace dependencies on every push. You just need to build and test the code you're writing and the changes you've made.

Our vision for this new way of doing backend development is shuttle-next: a next-generation backend framework with the fastest build, test and deployment times ever.

We believe that scoping down virtualization to the level of service components will eventually become the norm for backend development. In the same way we all think it's often not best to setup and start a VM only to run a single process, we will eventually all think it's misguided to build and start a container only to run a single service.

We are launching shuttle-next as part of our closed beta for shuttle later this month, with the public release coming soon after. If you’re keen to give it a try early, sign up for the beta! We'd love to know what you think!

In the meantime, check out shuttle's GitHub repo and Twitter for updates. If you’d like to support us, please star the repo and/or join the shuttle Discord community!

Create and Deploy a Discord bot in Rust, for free

Ivan — Thu, 15 Sep 2022 13:28:29 +0000

In this post, we will look at a simple way to add custom functionality to a Discord server using a bot written in Rust. We will first register a bot with Discord, then go about how to create a Serenity application that will later run on shuttle. Finally, we will make the bot do something useful, writing some Rust code to get information from an external service.

The full code can be found in this repository.

Registering our bot

Before we start making our bot, we need to register it for Discord. We do that by going to https://discord.com/developers/applications and creating a new application.

The application process is also used for adding functionality to Discord but we will be only using the bot offering. Fill in the basic details and you should get to the following screen:

You want to copy the Application ID and have it handy, because we will use it to add our bot to a test server.

Next, we want to create a bot. You can set its public username here:

You want to click the reset token and copy this value (we will use it in a later step). This value represents the username and password as a single value that Discord uses to authenticate that our server is the one controlling the bot. You want to keep this value secret.

You also want to tick the MESSAGE CONTENT INTENT setting so it can read the commands input.

To add the bot to the server we will test on, we can use the following URL (replace *application_id* in the URL with the ID you copied beforehand):

https://discord.com/oauth2/authorize?client_id=*application_id*&scope=bot&permissions=8

Here, we create it with permissions=8 so that it can do everything on the server. If you are adding to another server, select only the permissions it needs.

We now have a bot on our server:

Oh, they’re offline 😢

Getting a bot online

At this moment, our bot is not running because there is no code. We will have to write it and run it before we can start interacting with it.

Serenity

Serenity is a library for writing Discord bots (and communicating with the Discord API). We can create a new Serenity project which is readily deployable on shuttle with: cargo shuttle init --serenity

If you don’t have shuttle yet, you can install it with cargo install cargo-shuttle. Afterwards, run the following in an empty directory:

cargo shuttle init --serenity

After running it you, should see the following generated in src/lib.rs:

use log::{error, info};
use serenity::async_trait;
use serenity::model::channel::Message;
use serenity::model::gateway::Ready;
use serenity::prelude::*;
use shuttle_service::error::CustomError;
use shuttle_service::SecretStore;
use sqlx::PgPool;

struct Bot;

#[async_trait]
impl EventHandler for Bot {
    async fn message(&self, ctx: Context, msg: Message) {
        if msg.content == "!hello" {
            if let Err(e) = msg.channel_id.say(&ctx.http, "world!").await {
                error!("Error sending message: {:?}", e);
            }
        }
    }

    async fn ready(&self, _: Context, ready: Ready) {
        info!("{} is connected!", ready.user.name);
    }
}

#[shuttle_service::main]
async fn serenity(#[shared::Postgres] pool: PgPool) -> shuttle_service::ShuttleSerenity {
    // Get the discord token set in `Secrets.toml` from the shared Postgres database
    let token = pool
        .get_secret("DISCORD_TOKEN")
        .await
        .map_err(CustomError::new)?;

    // Set gateway intents, which decides what events the bot will be notified about
    let intents = GatewayIntents::GUILD_MESSAGES | GatewayIntents::MESSAGE_CONTENT;

    let client = Client::builder(&token, intents)
        .event_handler(Bot)
        .await
        .expect("Err creating client");

    Ok(client)
}

Building an interaction for our bot

We want to call our bot when chatting in a text channel. Discord enables this with slash commands.

Slash commands can be server-specific (servers are named as guilds in Discords API documentation) or application specific (across all servers the bot is in). For testing, we will only enable it on a single guild/server. This is because the application-wide commands can take an hour to fully register whereas the guild/server specific ones are instant, so we can test the new commands immediately.

You can copy the guild ID by right-clicking here on the server name and click copy ID (you will need developer mode enabled to do this):

Now that we have the information for setup, we can start writing our bot and its commands.

We will first get rid of the async fn message hook as we won’t be using it in this example. In the ready hook we will call set_application_commands with a GuildId to register a command with Discord. Here we register a hello command with a description and no parameters (Discord refers to these as options).

#[async_trait]
impl EventHandler for Bot {
    async fn ready(&self, ctx: Context, ready: Ready) {
        info!("{} is connected!", ready.user.name);

        let guild_id = GuildId(*your guild id*);

        let commands = GuildId::set_application_commands(&guild_id, &ctx.http, |commands| {
            commands.create_application_command(|command| { command.name("hello").description("Say hello") })
        }).await.unwrap();

        info!("{:#?}", commands);
    }
}

Serenity has a bit of a different way of registering commands using a callback. If you are working on a larger command application, poise (which builds on Serenity) might be better suited.

With our command registered, we will now add a hook for when these commands are called using interaction_create.

#[async_trait]
impl EventHandler for Bot {
    async fn ready(&self, ctx: Context, ready: Ready) {
        // ...
    }

    async fn interaction_create(&self, ctx: Context, interaction: Interaction) {
        if let Interaction::ApplicationCommand(command) = interaction {
            let response_content = match command.data.name.as_str() {
                "hello" => "hello".to_owned(),
                command => unreachable!("Unknown command: {}", command),
            };

            let create_interaction_response =
                command.create_interaction_response(&ctx.http, |response| {
                    response
                        .kind(InteractionResponseType::ChannelMessageWithSource)
                        .interaction_response_data(|message| message.content(response_content))
                });

            if let Err(why) = create_interaction_response.await {
                eprintln!("Cannot respond to slash command: {}", why);
            }
        }
    }
}

Trying it out

Now with the code written we can test it locally. Before we do that we have to authenticate the bot with Discord. We do this with the value we got from "Reset Token" on the bot screen in one of the previous steps. To register a secret with shuttle we create a Secrets.toml file with a key value pair. This pair is read by the pool.get_secret("DISCORD_TOKEN") call in the ready hook:

# Secrets.toml
DISCORD_TOKEN="*your discord token*"
DISCORD_GUILD_ID="*the guild we are testing on*"

Currently secrets are stored using shuttle's database Postgres offering (thus why the parameter on main is PgPool). Therefore during local testing you need access to a Postgres database. Shuttle's local runner does this using Docker which will require Docker desktop being locally installed to use the Secrets locally. This is is subject to change in the future so that it doesn't require Docker for local secrets. There is also a known issue with deploying Secrets on Windows so if you have problems consult the Discord.

cargo shuttle run

We should see that our bot now displays as online:

When typing, we should see our command come up with its description:

Our bot should respond with "hello" to our command:

Wow! Let’s make our bot do something a little more useful.

Making the bot do something

There is plenty of free APIs that can be used for getting information on a variety of topics.

For this demo, we are going to build a bot that gives a forecast for a location. I used the AccuWeather API for this demo. If you are following this tutorial 1:1 you can go and register an application to get an access key. If you are using a different API this is still the sort of process you would follow.

To get a forecast using the API requires two requests:

Get a location ID for a named location
Get the forecast at the location ID

The API requires making network requests and it returns a JSON response. We can make the requests with cargo add reqwest -F json and deserialize the results to structures using serde, with cargo add serde. We will then have a function that chains the two requests together and deserializes the forecast to a readable result.

You can skip some of the boilerplate by using direct access on untyped values. But we will opt for the better strongly typed structured approach.

Here we type some of the structures returned by the API and add #[derive(Deserialize)] so they can be decoded from JSON. All the keys are in PascalCase so we use the #[serde(rename_all = "PascalCase")] helper attribute to stay aligned with Rust standards. Some are completely different from the Rust field name so we use #[serde(alias = ...)] on the field to set its matching JSON representation.

// In weather.rs
use serde::Deserialize;

#[derive(Deserialize, Debug)]
#[serde(rename_all = "PascalCase")]
pub struct Location {
    key: String,
    localized_name: String,
    country: Country,
}

impl Display for Location {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}, {}", self.localized_name, self.country.id)
    }
}

#[derive(Deserialize, Debug)]
pub struct Country {
    #[serde(alias = "ID")]
    pub id: String,
}

#[derive(Deserialize, Debug)]
#[serde(rename_all = "PascalCase")]
pub struct Forecast {
    pub headline: Headline,
}

#[derive(Deserialize, Debug)]
pub struct Headline {
    #[serde(alias = "Text")]
    pub overview: String,
}

The above skips a lot of the fields returned by the API, only opting for the ones we will use in this demo. If you wanted to type all the fields you could try the new type from JSON feature in rust-analyzer to avoid having to write as much.

Our location request call also fails if the search we put in returns no places. We will create an intermediate type that represents this case and implements std::error::Error:

// Again in weather.rs
use std::fmt::Display;

#[derive(Debug)]
pub struct CouldNotFindLocation {
    place: String,
}

impl Display for CouldNotFindLocation {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Could not find location '{}'", self.place)
    }
}

impl std::error::Error for CouldNotFindLocation {}

Now with all the types written, we create a new async function that, given a place and a client, will return the forecast along with the location:

// Again in weather.rs
pub async fn get_forecast(
    place: &str,
        api_key: &str,
    client: &Client,
) -> Result<(Location, Forecast), Box<dyn std::error::Error>> {
        // Endpoints we will use
    const LOCATION_REQUEST: &str = "http://dataservice.accuweather.com/locations/v1/cities/search";
    const DAY_REQUEST: &str = "http://dataservice.accuweather.com/forecasts/v1/daily/1day/";

        // The URL to call combined with our API_KEY and the place (via the q search parameter)
    let url = format!("{}?apikey={}&q={}", LOCATION_REQUEST, api_key, place);
        // Make the request we will call
    let request = client.get(url).build().unwrap();
        // Execute the request and await a JSON result that will be converted to a
        // vector of locations
    let resp = client
        .execute(request)
        .await?
        .json::<Vec<Location>>()
        .await?;

        // Get the first location. If empty respond with the above declared
        // `CouldNotFindLocation` error type
    let first_location = resp
        .into_iter()
        .next()
        .ok_or_else(|| CouldNotFindLocation {
            place: place.to_owned(),
        })?;

        // Now have the location combine the key/identifier with the URL 
    let url = format!("{}{}?apikey={}", DAY_REQUEST, first_location.key, api_key);

        let request = client.get(url).build().unwrap();
    let forecast = client
        .execute(request)
        .await?
        .json::<Forecast>()
        .await?;

        // Combine the location with the foreact
    Ok((first_location, forecast))
}

Now we have a function to get the weather, given a reqwest client and a place, we can wire that into the bots logic.

Setting up the reqwest client

Our get_forecast requires a reqwest Client and the weather API key. We will add some fields to our bot for holding this data and initialize this in the shuttle_service::main function. Using the secrets feature we can get our weather API key:

// In lib.rs
struct Bot {
    weather_api_key: String,
    client: reqwest::Client,
        discord_guild_id: GuildId,
}

#[shuttle_service::main]
async fn serenity(#[shared::Postgres] pool: PgPool) -> shuttle_service::ShuttleSerenity {
    // Get the discord token set in `Secrets.toml` from the shared Postgres database
    let token = pool
        .get_secret("DISCORD_TOKEN")
        .await
        .map_err(CustomError::new)?;

    let weather_api_key = pool
        .get_secret("WEATHER_API_KEY")
        .await
        .map_err(CustomError::new)?;

        let discord_guild_id = pool
        .get_secret("DISCORD_GUILD_ID")
        .await
        .map_err(CustomError::new)?;

    // Set gateway intents, which decides what events the bot will be notified about
    let intents = GatewayIntents::GUILD_MESSAGES | GatewayIntents::MESSAGE_CONTENT;

    let client = Client::builder(&token, intents)
        .event_handler(Bot {
            weather_api_key,
            client: reqwest::Client::new(),
                        discord_guild_id: GuildId(discord_guild_id.parse().unwrap())
        })
        .await
        .expect("Err creating client");

    Ok(client)
}

Registering a /weather command

We will add our new command with a place option/parameter. Back in the ready hook, we can add an additional command alongside the existing hello command:

let commands = GuildId::set_application_commands(&guild_id, &ctx.http, |commands| {
    commands
        .create_application_command(|command| { command.name("hello").description("Say hello") })
        .create_application_command(|command| {
            command
                .name("weather")
                .description("Display the weather")
                .create_option(|option| {
                    option
                        .name("place")
                        .description("City to lookup forecast")
                        .kind(CommandOptionType::String)
                        .required(true)
                })
        })
}).await.unwrap();

Discord allows us to set the expected type and whether it is required. Here, the place needs to be a string and is required.

Now in the interaction handler, we can add a new branch to the match tree. We pull out the option/argument corresponding to place and extract its value. Because of the restrictions made when setting the option we can assume that it is well-formed (unless Discord sends a bad request) and thus the unwraps here. After we have the arguments of the command we call the get_forecast function and format the results into a string to return.

"weather" => {
    let argument = command
        .data
        .options
        .iter()
        .find(|opt| opt.name == "place")
        .cloned();

    let value = argument.unwrap().value.unwrap();
    let place = value.as_str().unwrap();
    let result = weather::get_forecast(place).await;        

    match result {
        Ok((location, forecast)) => format!(
            "Forecast: {} in {}",
            forecast.headline.overview, location
        ),
        Err(err) => {
            format!("Err: {}", err)
        }
    }
}

Running

Now, we have these additional secrets we are using and we will add them to the Secrets.toml file:

# In Secrets.toml
# Existing secrets:
DISCORD_TOKEN="***"
DISCORD_GUILD_ID="***"
# New secret
WEATHER_API_KEY="***"

With the secrets added, we can run the server:

cargo shuttle run

While typing, we should see our command come up with the options/parameters:

Entering “Paris” as the place we get a result with a forecast:

And entering a location that isn’t registered returns an error, thanks to the error handling we added to the get_forecast function:

Deploying on shuttle

With all of that setup, it is really easy to get your bot hosted and running without having to run your PC 24/7.

Just write:

cargo shuttle deploy

And you are good to go. Easy-pease, right?

You could now take this idea even further:

Use a different API, to create a bot that can return funny facts or return new spaceflights
Maybe you could use one of shuttle's provided databases to remember certain information about a user
Expand on the weather forecast idea by adding more advanced options and follow-ups to command options
Use the localization information to return information in other languages

This blog post is powered by shuttle! If you have any questions, or want to provide feedback, join our Discord server!

Shuttle: The Rust-native, open source, cloud development platform.
Deploying and managing your Rust web apps can be an expensive, anxious and time consuming process.

If you want a batteries included and ops-free experience, try out Shuttle.

Building an authentication system in Rust using session tokens

Ivan — Fri, 19 Aug 2022 14:30:09 +0000

Most websites have some kind of user system. But implementing authentication can be a bit complex. It requires several things working together.

Making sure the system is secure is daunting. How do we know others cannot easily log into accounts and make edits on other people's behalf? And building stateful systems is difficult.

Today we will look at a minimal implementation in Rust. For this demo we won't be using a specific authentication library, instead writing from scratch using our own database and backend API.

We will be walking through implementing the system including a frontend for interacting with it. We will be using Axum for routing and other handling logic. The source code for this tutorial can be found here. We will then deploy the code on shuttle, which will handle running the server and giving us access to a Postgres server.

To prevent this post from being an hour long, some things are skipped over (such as error handling) and so might not match up one-to-one with the tutorial. This post also assumes basic knowledge of HTML, web servers, databases and Rust.

This isn't verified to be secure, use it at your own risk!!

Let's get started

First, we will install shuttle for creating the project (and later for deployment). If you don't already have it you can install it with cargo install cargo-shuttle. We will first go to a new directory for our project and create a new Axum app with cargo shuttle init --axum.

You should see the following in src/lib.rs:

use axum::{routing::get, Router};
use sync_wrapper::SyncWrapper;

async fn hello_world() -> &'static str {
    "Hello, world!"
}

#[shuttle_service::main]
async fn axum() -> shuttle_service::ShuttleAxum {
    let router = Router::new().route("/hello", get(hello_world));
    let sync_wrapper = SyncWrapper::new(router);

    Ok(sync_wrapper)
}

Templates

For generating HTML we will be using Tera, so we can go ahead and add this with cargo add tera. We will store all our templates in a template directory in the project root.

We want a general layout for our site, so we create a base layout. In our base layout, we can add specific tags that will apply to all pages such as a Google font. With this layout all the content will be injected in place of {% block content %}{% endblock content %}:

<!-- in "templates/base.html" -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Title</title>
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Karla:wght@500&display=swap" rel="stylesheet">
    <link href="/styles.css" rel="stylesheet">
</head>
<body>
    {% block content %}{% endblock content %}
</body>
</html>

And now we can create our first page that will be displayed under the / path

<!-- in "templates/index.html" -->
{% extends "base.html" %}
{% block content %}
<h1>Hello world</h1>
{% endblock content %}

Now we have our template, we need to register it under a Tera instance. Tera has a nice filesystem-based registration system, but we will use the include_str! macro so that the content is in the binary. This way we don't have to deal with the complexities of a filesystem at runtime. We register both templates so that the index page knows about base.html.

let mut tera = Tera::default();
tera.add_raw_templates(vec![
    ("base.html", include_str!("../templates/base.html")),
    ("index", include_str!("../templates/index.html")),
])
.unwrap();

We add it via an Extension (wrapped in Arc so that extension cloning does not deep clone all the templates)

#[shuttle_service::main]
async fn axum() -> shuttle_service::ShuttleAxum {
    let mut tera = Tera::default();
    tera.add_raw_templates(vec![
        ("base.html", include_str!("../templates/base.html")),
        ("index", include_str!("../templates/index.html")),
    ])
    .unwrap();

    let router = Router::new()
        .route("/hello", get(hello_world))
        .layer(Extension(Arc::new(tera)));

    let sync_wrapper = SyncWrapper::new(router);
    Ok(sync_wrapper)
}

Rendering views

Now we have created our Tera instance we want it to be accessible to our get methods. To do this in Axum, we add the extension as a parameter to our function. In Axum, an Extension is a unit struct. Rather than dealing with .0 to access fields, we use destructuring in the parameter (if you thought that syntax looks weird).

async fn index(
    Extension(templates): Extension<Templates>,
) -> impl IntoResponse {
    Html(templates.render("index", &Context::new()).unwrap())
}

Serving assets

We can create a public/styles.css file

body {
    font-family: 'Karla', sans-serif;
    font-size: 12pt;
}

And easily create a new endpoint for it to be served from:

async fn styles() -> impl IntoResponse {
    Response::builder()
        .status(http::StatusCode::OK)
        .header("Content-Type", "text/css")
        .body(include_str!("../public/styles.css").to_owned())
        .unwrap()
}

Here we again are using include_str! to not have to worry about the filesystem at runtime. ServeDir is an alternative if you have a filesystem at runtime. You can use this method for other static assets like JavaScript and favicons.

Running

We will add our two new routes to the router (and remove the default "hello world" one) to get:

let router = Router::new()
    .route("/", get(index))
    .route("/styles.css", get(styles))
    .layer(Extension(Arc::new(tera)));

With our main service we can now test it locally with cargo shuttle run.

Nice!

Adding users

We will start with a user's table in SQL. (this is defined in schema.sql).

CREATE TABLE users (
    id integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    username text NOT NULL UNIQUE,
    password text NOT NULL
);

The id is generated by the database using a sequence. The id is a primary key, which we will use to reference users. It is better to use a fixed value field for identification rather than using something like the username field because you may add the ability to change usernames, which can leave things pointing to the wrong places.

Registering our database

Before our app can use the database we have to add sqlx with some features: cargo add sqlx -F postgres runtime-tokio-native-tls. We will also enable the Postgres feature for shuttle with cargo add shuttle-service -F sqlx-postgres.

Now back in the code we add a parameter with #[shared::Postgres] pool: Database. The #[shared::Postgres] annotation tells shuttle to provision a Postgres database using the infrastructure from code design!

type Database = sqlx::PgPool;

#[shuttle_service::main]
async fn axum(
    #[shared::Postgres] pool: Database
) -> ShuttleAxum {
    // Build tera as before

    let router = Router::new()
        .route("/", get(index))
        .route("/styles.css", get(styles))
        .layer(Extension(Arc::new(tera)))
        .layer(pool);

    // Wrap and return router as before
}

Signup

For getting users into our database, we will create a post handler. In our handler, we will parse data using multipart. I wrote a simple parser for multipart that we will use here. The below example contains some error handling that we will ignore for now.

async fn post_signup(
    Extension(database): Extension<Database>,
    multipart: Multipart,
) -> impl IntoResponse {
    let data = parse_multipart(multipart)
        .await
        .map_err(|err| error_page(&err))?;

    if let (Some(username), Some(password), Some(confirm_password)) = (
        data.get("username"),
        data.get("password"),
        data.get("confirm_password"),
    ) {
        if password != confirm_password {
            return Err(error_page(&SignupError::PasswordsDoNotMatch));
        }

        let user_id = create_user(username, password, database);

        Ok(todo!())
    } else {
        Err(error_page(&SignupError::MissingDetails))
    }
}

Creating users and storing passwords safety

When storing passwords in a database, for security reasons we don't want them to be in the exact format as plain text. To transform them away from the plain text format we will use a cryptographic hash function from pbkdf2 (cargo add pbkdf2):

fn create_user(username: &str, password: &str, database: &Database) -> Result<i32, SignupError> {
    let salt = SaltString::generate(&mut OsRng);
    // Hash password to PHC string ($pbkdf2-sha256$...)
    let hashed_password = Pbkdf2.hash_password(password.as_bytes(), &salt).unwrap().to_string();

    // ...
}

With hashing, if someone gets the value in the password field they cannot find out the actual password value. The only thing this value allows is whether a plain text password matches this value. And with salting different names are encoded differently. Here all these passwords were registered as "password", but they have different values in the database because of salting.

postgres=> select * from users;
 id | username |                                            password
----+----------+------------------------------------------------------------------------------------------------
  1 | user1    | $pbkdf2-sha256$i=10000,l=32$uC5/1ngPBs176UkRjDbrJg$mPZhv4FfC6HAfdCVHW/djgOT9xHVAlbuHJ8Lqu7R0eU
  2 | user2    | $pbkdf2-sha256$i=10000,l=32$4mHGcEhTCT7SD48EouZwhg$A/L3TuK/Osq6l41EumohoZsVCknb/wiaym57Og0Oigs
  3 | user3    | $pbkdf2-sha256$i=10000,l=32$lHJfNN7oJTabvSHfukjVgA$2rlvCjQKjs94ZvANlo9se+1ChzFVu+B22im6f2J0W9w
(3 rows)

With the following simple database query and our hashed password, we can insert users.

fn create_user(username: &str, password: &str, database: &Database) -> Result<i32, SignupError> {
    // ...

    const INSERT_QUERY: &str =
        "INSERT INTO users (username, password) VALUES ($1, $2) RETURNING id;";

    let fetch_one = sqlx::query_as(INSERT_QUERY)
        .bind(username)
        .bind(hashed_password)
        .fetch_one(database)
        .await;

    // ...
}

And we can handle the response and get the new user id with the following:

fn create_user(username: &str, password: &str, database: &Database) -> Result<i32, SignupError> {
    // ...

    match fetch_one {
        Ok((user_id,)) => Ok(user_id),
        Err(sqlx::Error::Database(database))
            if database.constraint() == Some("users_username_key") =>
        {
            return Err(SignupError::UsernameExists);
        }
        Err(err) => {
            return Err(SignupError::InternalError);
        }
    }
}

Great now we have the signup handler written, let's create a way to invoke it in the UI.

Using HTML forms

To invoke the endpoint with multipart we will use an HTML form.

<!-- in "templates/signup.html" -->
{% extends "base.html" %}
{% block content %}
<form action="/signup" enctype="multipart/form-data" method="post">
    <label for="username">Username</label>
    <input type="text" name="username" id="username" minlength="1" maxlength="20" pattern="[0-9a-z]+" required>
    <label for="password">Password</label>
    <input type="password" name="password" id="password" required>
    <label for="confirm_password">Confirm Password</label>
    <input type="password" name="confirm_password" id="confirm_password" required>
    <input type="submit" value="Signup">
</form>
{% endblock content %}

Notice the action and method that correspond to the route we just added. Notice also the enctype being multipart, which matches what we are parsing in the handler. The above has a few attributes to do some client-side validation, but in the full demo it is also handled on the server.

We create a handler for this markup in the same way as done for our index with:

async fn get_signup(
    Extension(templates): Extension<Templates>,
) -> impl IntoResponse {
    Html(templates.render("signup", &Context::new()).unwrap())
}

We can add signup to the Tera instance and then add both the get and post handlers to the router by adding it to the chain:

.route("/signup", get(get_signup).post(post_signup))

Sessions

Once signed up, we want to save the logged-in state. We don't want the user to have to send their username and password for every request they make.

Cookies and session tokens

Cookies help store the state between browser requests. When a response is sent down with Set-Cookie, then any subsequent requests the browser/client makes will send cookie information. We can then pull this information off of headers on requests on the server.

Again, these need to be safe. We don't want collisions/duplicates. We want it to be hard to guess. For these reasons, we will represent it as a 128-bit unsigned integer. This has 2^128 options, so a very low chance of a collision.

We want to generate a "session token". We want the tokens to be cryptographically secure. Given a session id, we don't want users to be able to find the next one. A simple globally incremented u128 wouldn't be secure because if I know I have session 10 then I can send requests with session 11 for the user who logged in after. With a cryptographically secure generator, there isn't a distinguishing pattern between subsequently generated tokens. We will use the ChaCha algorithm/crate (we will add cargo add rand_core rand_chacha). We can see that it does implement the crypto marker-trait confirming it is valid for cryptographic scenarios.

This is unlike Pseudo-random number generators where you can predict the next random number given a start point and the algorithm. This could be a problem if we have our token we can get the session token of the person who logged in after us really easy and thus impersonate them.

To initialize the random generator we use SeedableRng::from_seed. The seed in this case is an initial state for the generator. Here we use OsRng.next_u64() which retrieves randomness from the operating system rather a seed. We will be doing something similar to the creation of the Tera instance. We must wrap it in an arc and a mutex because generating new identifiers requires mutable access. We now have the following main function:

#[shuttle_service::main]
async fn axum(
    #[shared::Postgres] pool: Database
) -> ShuttleAxum {
    // Build tera as before

    let random = ChaCha8Rng::seed_from_u64(OsRng.next_u64())

    let router = Router::new()
        .route("/", get(index))
        .route("/styles.css", get(styles))
        .route("/signup", get(get_signup).post(post_signup))
        .layer(Extension(Arc::new(tera)))
        .layer(pool)
        .layer(Extension(Arc::new(Mutex::new(random))));

    // Wrap and return router as before
}

Adding sessions to signup

As well as creating a user on signup, we will create the session token for the newly signed-up user. We post it to the table with our user_id

type Random = Arc<Mutex<ChaCha8Rng>>;

pub(crate) async fn new_session(
    database: &Database, 
    random: Random, 
    user_id: i32
) -> String {
    const QUERY: &str = "INSERT INTO sessions (session_token, user_id) VALUES ($1, $2);";

    let mut u128_pool = [0u8; 16];
    random.lock().unwrap().fill_bytes(&mut u128_pool);

    // endian doesn't matter here
    let session_token = u128::from_le_bytes(u128_pool);

    let _result = sqlx::query(QUERY)
        .bind(&session_token.to_le_bytes().to_vec())
        .bind(user_id)
        .execute(database)
        .await
        .unwrap();

    session_token
}

In the full demo, we use the new type pattern over a u128 to make this easier, but we will stick with a u128 type here.

Now we have our token, we need to package it into a cookie value. We will do it in the simplest way possible, using .to_string(). We will send a response that does two things, sets this new value and returns/redirects us back to the index page. We will create a utility function for doing this:

fn set_cookie(session_token: &str) -> impl IntoResponse {
    http::Response::builder()
        .status(http::StatusCode::SEE_OTHER)
        .header("Location", "/")
        .header("Set-Cookie", format!("session_token={}; Max-Age=999999", session_token))
        .body(http_body::Empty::new())
        .unwrap()
}

Now we can complete our signup handler by adding random as a parameter and returning our set cookie response.

async fn post_signup(
    Extension(database): Extension<Database>,
    Extension(random): Extension<Random>,
    multipart: Multipart,
) -> impl IntoResponse {
    let data = parse_multipart(multipart)
        .await
        .map_err(|err| error_page(&err))?;

    if let (Some(username), Some(password), Some(confirm_password)) = (
        data.get("username"),
        data.get("password"),
        data.get("confirm_password"),
    ) {
        if password != confirm_password {
            return Err(error_page(&SignupError::PasswordsDoNotMatch));
        }

        let user_id = create_user(username, password, &database);

        let session_token = new_session(database, random, user_id);

        Ok(set_cookie(&session_token))
    } else {
        Err(error_page(&SignupError::MissingDetails))
    }
}
let session_token = new_session(database, random, user_id);

Using the session token

Great so now we have a token/identifier for a session. Now we can use this as a key to get information about users.

We can pull the cookie value using the following spaghetti of iterators and options:

let session_token = req
    .headers()
    .get_all("Cookie")
    .iter()
    .filter_map(|cookie| {
        cookie
            .to_str()
            .ok()
            .and_then(|cookie| cookie.parse::<cookie::Cookie>().ok())
    })
    .find_map(|cookie| {
        (cookie.name() == USER_COOKIE_NAME).then(move || cookie.value().to_owned())
    })
    .and_then(|cookie_value| cookie_value.parse::<u128>().ok());

Auth middleware

In the last post, we went into detail about middleware. You can read more about it in more detail there.

In our middleware, we will get a little fancy and make the user pulling lazy. This is so that requests that don't need user data don't have to make a database trip. Rather than adding our user straight onto the request, we split things apart. We first create an AuthState which contains the session token, the database, and a placeholder for our user (Option<User>)

#[derive(Clone)]
pub(crate) struct AuthState(Option<(u128, Option<User>, Database)>);

pub(crate) async fn auth<B>(
    mut req: http::Request<B>,
    next: axum::middleware::Next<B>,
    database: Database,
) -> axum::response::Response {
    let session_token = /* cookie logic from above */;

    req.extensions_mut()
        .insert(AuthState(session_token.map(|v| (v, None, database))));

    next.run(req).await
}

Then we create a method on AuthState which makes the database request.

Now we have the user's token we need to get their information. We can do that using SQL joins

impl AuthState {
    pub async fn get_user(&mut self) -> Option<&User> {
        let (session_token, store, database) = self.0.as_mut()?;
        if store.is_none() {
            const QUERY: &str =
                "SELECT id, username FROM users JOIN sessions ON user_id = id WHERE session_token = $1;";

            let user: Option<(i32, String)> = sqlx::query_as(QUERY)
                .bind(&session_token.to_le_bytes().to_vec())
                .fetch_optional(&*database)
                .await
                .unwrap();

            if let Some((_id, username)) = user {
                *store = Some(User { username });
            }
        }
        store.as_ref()
    }
}

Here we cache the user internally using an Option. With the caching in place if another middleware gets the user and then a different handler tries to get the user it results in one database request, not two!

We can add the middleware to our chain using:

#[shuttle_service::main]
async fn axum(
    #[shared::Postgres] pool: Database
) -> ShuttleAxum {
    // tera and random creation as before

    let middleware_database = database.clone();

    let router = Router::new()
        .route("/", get(index))
        .route("/styles.css", get(styles))
        .route("/signup", get(get_signup).post(post_signup))
        .layer(axum::middleware::from_fn(move |req, next| {
            auth(req, next, middleware_database.clone())
        }))
        .layer(Extension(Arc::new(tera)))
        .layer(pool)
        .layer(Extension(Arc::new(Mutex::new(random))));

    // Wrap and return router as before
}

Getting middleware and displaying our user info

Modifying our index Tera template, we can add an "if block" to show a status if the user is logged in.

<!-- in "templates/index.html" -->
{% extends "base.html" %}
{% block content %}
<h1>Hello world</h1>
{% if username %}
    <h3>Logged in: {{ username }}</h3>
{% endif %}
{% endblock content %}

Using our middleware in requests is easy in Axum by including a reference to it in the parameters. We then add the username to the context for it to be rendered on the page.

async fn index(
    Extension(current_user): Extension<AuthState>,
    Extension(templates): Extension<Templates>,
) -> impl IntoResponse {
    let mut context = Context::new();
    if let Some(user) = current_user.get_user().await {
        context.insert("username", &user.username);
    }
    Html(templates.render("index", &context).unwrap())
}

Logging in and logging out

Great we can signup and that now puts us in a session. We may want to log out and drop the session. This is very simple to do by returning a response with the cookie Max-Age set to 0.

pub(crate) async fn logout_response() -> impl axum::response::IntoResponse {
    Response::builder()
        .status(http::StatusCode::SEE_OTHER)
        .header("Location", "/")
        .header("Set-Cookie", "session_token=_; Max-Age=0")
        .body(Empty::new())
        .unwrap()
}

For logging in we have a very similar logic for signup with pulling multipart information of a post request. Unlike signup, we don't want to create a new user. We want to check the row with that username has a password that matches. If the credentials match then we create a new session:

async fn post_login(
    Extension(database): Extension<Database>,
    multipart: Multipart,
) -> impl IntoResponse {
    let data = parse_multipart(multipart)
        .await
        .map_err(|err| error_page(&err))?;

    if let (Some(username), Some(password)) = (data.get("username"), data.get("password")) {
        const LOGIN_QUERY: &str = "SELECT id, password FROM users WHERE users.username = $1;";

        let row: Option<(i32, String)> = sqlx::query_as(LOGIN_QUERY)
            .bind(username)
            .fetch_optional(database)
            .await
            .unwrap();

        let (user_id, hashed_password) = if let Some(row) = row {
            row
        } else {
            return Err(LoginError::UserDoesNotExist);
        };

        // Verify password against PHC string
        let parsed_hash = PasswordHash::new(&hashed_password).unwrap();
        if let Err(_err) = Pbkdf2.verify_password(password.as_bytes(), &parsed_hash) {
            return Err(LoginError::WrongPassword);
        }

        let session_token = new_session(database, random, user_id);


        Ok(set_cookie(&session_token))
    } else {
        Err(error_page(&LoginError::NoData))
    }
}

Then we refer back to the signup section and replicate the same HTML form and handler that renders the Tera template as seen before but for a login screen. At the end of that we can add two new routes with three handlers completing the demo:

#[shuttle_service::main]
async fn axum(
    #[shared::Postgres] pool: Database
) -> ShuttleAxum {
    // tera, middleware and random creation as before

    let router = Router::new()
        // ...
        .route("/logout", post(logout_response))
        .route("/login", get(get_login).post(post_login))
        // ...

    // Wrap and return router as before
}

Deployment

This is great, we now have a site with signup and login functionality. But we have no users, our friends can't log in on our localhost. We want it live on the interwebs. Luckily we are using shuttle, so it is as simple as:

cargo shuttle deploy

Because of our #[shuttle_service::main] annotation and out-the-box Axum support our deployment doesn't need any prior config, it is instantly live!

Now you can go ahead with these concepts and add functionality for listing and deleting users. The full demo implements these if you are looking for clues.

Thoughts building the tutorial and other ideas on where to take it

This demo includes the minimum required for authentication. Hopefully, the concepts and snippets are useful for building it into an existing site or for starting a site that needs authentication. If you were to continue, it would be as simple as more fields onto the user object or building relations with the id field on the user's table. I will leave it out with some of my thoughts and opinions while building the site as well as things you could try extending it with.

For templating Tera is great. I like how I separate the markup into external files rather than bundling it into src/lib.rs. Its API is easy to use and is well documented. However, it is quite a simple system. I had a few errors where I would rename or remove templates and because the template picker for rendering uses a map it can panic at runtime if the template does not exist. It would be nice if the system allowed checking that templates exist at compile time. The data sending works on serde serialization, which is a little bit more computation overhead than I would like. It also does not support streaming. With streaming, we could send a chunk of HTML that doesn't depend on database values first, and then we can add more content when the database transaction has gone through. If it supported streaming we could avoid the all-or-nothing pages with white page pauses and start connections to services like Google Fonts earlier. Let me know what your favorite templating engine is for Rust and whether it supports those features!

For working with the database, sqlx has typed macros. I didn't use them here but for more complex queries you might prefer the type-checking behavior. Maybe 16 bytes for storing session tokens is a bit overkill. You also might want to try sharding that table if you have a lot of sessions or using a key-value store (such as Redis) might be simpler. We also didn't implement cleaning up the sessions table, if you were storing sessions using Redis you could use the EXPIRE command to automatically remove old keys.

This blog post is powered by shuttle! The serverless platform built for Rust.

Shuttle: Stateful Serverless for Rust

Deploying and managing your Rust web apps can be an expensive, anxious and time consuming process.

If you want a batteries included and ops-free experience, try out shuttle.

Design Patterns with Rust Types

Ivan — Thu, 28 Jul 2022 21:45:00 +0000

This post introduces some patterns and tricks to better utilise Rust's type system for clean and safe code.

This post is on the advanced side and in general there are no absolutes - these patterns usually need to be evaluated on a case-by-case basis to see if the cost / benefit trade-off is worth it.

The new type pattern

The new type pattern provides encapsulation as well as a guarantee that the right type of value is supplied at compile time. There are several uses and benefits for the new type pattern - let's take a look at some examples.

Identifier Separation

A common representation of an identifier is a number - in this case let's use the unsigned integer type usize.

Let's say we have a function that receives an identifier for a User from a database by username. By using a unique username our API retrieves the identifier of the user:

fn get_user_id_from_username(username: &str) -> usize

Let's say we have a similar mechanism for another entity, Post.

If our application is performing operations involving posts and users, the logic can get in a mix:

let user_id: usize = get_user_id_from_username(username);
let post_id: usize = get_last_post();

fn delete_post(post_id: usize) {
    // ...
}

delete_post(user_id);

Here get_user_id_from_username and get_last_post both return usizes while delete)_post also takes a usize. In this code we can accidentally call delete_post with a user_id, there's nothing in the type system that would stop us from doing that.

To differentiate between these two identifiers we can use the new type pattern:

The new type pattern boils down to creating a new tuple struct with a single item, in this case usize

struct UserId(pub usize);

Now we can change our library definition to return a UserId instead of usize

fn get_user_id_from_username(username: String) -> UserId {
    let user_id: usize = ...
    UserId(user_id)
}

Doing similar for the posts system with a PostId, when now compiling we get an error on when calling get_post.

   |
14 |     get_post(x);
   |              ^ expected struct `PostId`, found struct `UserId`

The new-type pattern enforces type-safety at compile time without any performance overhead at runtime.

Re-adding functionality to our type

After creating this new wrapper type, we may need to implement some of the behaviour of the type it is encapsulating to appease our compiler. For example consider a set of 'banned' users:

let banned_users: HashSet<UserId> = HashSet::new();

The above doesn't compile because our new type UserId doesn't implement equality and hashing behaviour whereas usize did. To add these traits back we can use the inbuilt derive macro, which generates implementations for our struct based on the single and only field.

#[derive(PartialEq, Eq, Hash)]
struct UserId(usize);

And we're good to go!

Contract based programming in Rust / sub-typing

The new type pattern can also be used to constrain types to only take 'valid' values.

In the above example we used a wrapper type to enforce flow of values, this method also enforces the content of the value. In our application we only want usernames to contain lowercase alphabetic characters. Wrapping over String we can do this:

struct Username(String);

The only way to create a Username is using the TryFrom trait.

impl TryFrom<String> for Username {
    type Error = String;

    fn try_from(value: String) -> Result<Self, Self::Error> {
        if value.chars().all(|c| matches!(c, 'a'..='z')) {
            Ok(Username(value))
        } else {
            Err(value)
        }
    }
}

This implementation returns a new Username if all the characters are lowercase. Else the string is returned and can be reused in logic possibly displaying an error.

As the string field is private a Username cannot be created with Username(my_string). It also cannot be modified by outsiders and invalidate our contract.

We can now use this structure as an argument to our API.

fn create_user(db: &mut DB, username: Username) -> Result<(), CreationError> {
    // ...
}

Since the username is validated to be lowercase ahead of time, the create_user function doesn't care about whether the username is valid inside in its own scope.

This can lead to easier error handling. CreationError doesn't have to include a variant for the if the username has invalid characters.

Although the only safe way to construct if through the validator TryFrom trait, the Username can be created through unsafe transmute (casting the bits of one value to the type of another without checks). This is normally fine though as with unsafe you are introducing undefined behaviour anyway.

let string = String::new("muahahaha 👿");
let bad_username = unsafe { std::mem::transmute::<String, Username>(string) };
dbg!(bad_username);

Wrapping vs canonical type

Our wrapped type is great from the outside, however we are relying on logic internal to the type to validate our contract.

If we want to we can be really drill down on the structure of our username. Here we also enforce that the username has to be between four and ten letters.

#[rustfmt::skip]
enum Alphabet {
    A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z
}

enum Username {
    FourLetters([Alphabet; 4]),
    FiveLetters([Alphabet; 5]),
    SixLetters([Alphabet; 6]),
    SevenLetters([Alphabet; 7]),
    EightLetters([Alphabet; 8]),
    NineLetters([Alphabet; 9]),
    TenLetters([Alphabet; 10]),
}

Even though there is no way to make an invalid username (except for unsafe) this is a little over the top 😂. In some edge cases it can be beneficial but in the example above this is clearly overkill.

Working with foreign traits on foreign types

Traits are great. They can be defined on structs and enums, but you may run into some issues when implementing a foreign trait on a foreign type.

This is by design, and here's why:

In our crate the compiler doesn't know when calling MyTrait methods on MyStruct whether to use the implementation defined in crate 3 or crate 4! Rust has a set of orphan rules to prevent this situation from happening.

In the situation where you'd like to implement a foreign trait on a foreign type - the 'new type' pattern can come to the rescue yet again:

// lives in crate X
trait ToTree {
    // ...
}

fn very_useful_function(something: impl ToTree) -> () {
    // ..
}

// Our crate
struct Wrapper(pub crate_y::MyType);

impl ToTree for Wrapper {
    // ...
}

// Yay
very_useful_function(Wrapper(foreign_value))

One of the gotchas with this is that you have to manually implement the trait. You can't use derive macros, e.g. #[derive(PartialEq)] and reach through to the declaration of the wrapped type and read its declaration. You also have to make sure that you can properly implement the trait on the item. crate_y::MyType might hide information needed for the implementation 😕.

Ok - enough with the new type pattern. Let's leave it for a minute and look at some other tricks when working with types in Rust.

Using either to unify different types

Sometimes we have a case where we have a complicated data type

enum PostUser {
    Single {
        username: UserId
    },
    Group {
        usernames: HashSet<UserId>
    }
}

We'd like a method that returns an iterator, but we're stuck since we either return a single once iterable (std::iter::Once) or an iterator over a hashset. These iterators are different types and have different properties, so Rust doesn't like when we try to build a function returning both.

A Rust function / method cannot can only return one type:

impl PostUser {
    fn iter(&self) -> impl Iterator<Item=&UserId> + '_ {
        match self {
            PostUser::User { username } => std::iter::once(username),
            PostUser::Group { usernames } => usernames.into_iter(),
        }
    }
}

The following will fail because the match arms have different types.

   |
17 | /         match self {
18 | |             PostUser::User { username } => std::iter::once(username),
   | |                                            ------------------------- this is found to be of type `std::iter::Once<&UserId>`
19 | |             PostUser::Group { usernames } => usernames.into_iter(),
   | |                                              ^^^^^^^^^^^^^^^^^^^^^ expected struct `std::iter::Once`, found struct `std::collections::hash_set::Iter`
20 | |         }
   | |_________- `match` arms have incompatible types
   |
   = note: expected struct `std::iter::Once<&UserId>`
              found struct `std::collections::hash_set::Iter<'_, UserId>`

The either crate offers a general purpose sum type that implements many traits. Using either::Left for the once iterator and either::Right we can build two iterators into what Rust considers as a single type.

impl PostUser {
    fn iter(&self) -> impl Iterator<Item=&UserId> + '_ {
        match self {
            PostUser::User { username } => either::Left(std::iter::once(username)),
            PostUser::Group { usernames } => either::Right(usernames.into_iter()),
        }
    }
}

We could have instead boxed the results and returned Box<dyn Iterator<Item=&UserId>>. The benefit of using either is that it uses static dispatch rather than dynamic dispatch. enum_dispatch has good performance comparison for using static dispatch over dyn so if you are on a critical hot path, and you know all the returned types it is faster to use enums to unify types rather than dynamic trait dispatching.

Extension traits

When creating a library we may add some functions for working with existing types (whether in the standard library or a different crate).

Let's say we are writing a library on top of serenity which has models for discord servers (discord refers to them as guilds).

Let's write a helper function that gets the number of channels in a Guild.

async fn get_number_of_channels(
    guild: &serenity::model::Guild,
    http: impl AsRef<Http>
) -> serenity::Result<usize>

When calling the function we have to pass the guild as the first argument.

let guild: serenity::model::Guild = // ...
get_number_of_channels(&guild, client);

But from a design perspective we might prefer to use member notation instead: guild.get_number_of_channels(client).

We can't use add a direct implementation for a type defined outside our current crate.

/ impl serenity::model::Guild {
|     fn number_of_channels<T: AsRef<Http>>(&self, http: T) -> serenity::Result<usize> {
|         todo!()
|     }
| }
|_^ impl for type defined outside of crate.

To define an associated method on a type outside the crate we must instead make an intermediate 'Extension' trait:

trait GuildExt {
    fn number_of_channels<T: AsRef<Http>>(&self, http: T) -> serenity::Result<usize>;
}

impl GuildExt for serenity::model::Guild {
    fn number_of_channels<T: AsRef<Http>>(&self, http: T) -> serenity::Result<usize> {
        // ...
    }
}

Using the intermediate trait the compiler can reason about when the method exists. To use the method syntax and show the compiler that the extension exists we must import the trait into our scope:

use crate::GuildExt;
let guild: serenity::model::Guild = // ...
let number_of_channels = guild.get_number_of_channels(client);

This pattern is used in the futures crate with the FutureExt trait.
Here using the trait FutureExt provides additional methods to the existing Future trait in Rust's standard library. Aside from syntax aesthetics, it becomes much easier to find object-specific functions when using an IDE.

You can use the easy_ext for doing this pattern on a single type without having to write the trait / trait definition is generated for you.

Conclusion

We saw how we can use various patterns like the new-type pattern and extension pattern to make our Rust code more ergonomic and take advantage of the type system and compiler to write better code. There is a great book out on Rust design patterns which covers some of these and many more patterns in Rust.

Shuttle: Stateful Serverless for Rust

Deploying and managing your Rust web apps can be an expensive, anxious and time consuming process.

If you want a batteries included and ops-free experience, try out Shuttle.

Discussion time!

What are your favourite design patterns in Rust? Let us know and we'll cover them next time!

Infrastructure from code - not 'as', but 'from'

Ivan — Tue, 26 Jul 2022 17:09:00 +0000

In the early days of Facebook (back when it was still called thefacebook.com), Mark Zuckerberg hosted it on Harvard’s university servers. Back then companies used to buy or rent physical servers to run their software on. The advent of the cloud in the mid-2000s changed the game. The elasticity that this enabled has in big part enabled the rapid progress that we’ve all enjoyed since then. What we demand from software has increased tremendously, and correspondingly its architecture has become much more elaborate. The power of flexibility came at a price though - the complexity of wiring code with infrastructure. That price is even higher today.

The Container Hero

Heroku became part of the cloud-native lore as the first incredibly successful attempt at tackling this complexity. They led the first crusade to rid software developers of the infrastructure complexity dragon. People loved it. Heroku pioneered the wildly popular container-based approach to deployment that abstracted away the burden of managing virtual machines. By being opinionated with the use of containers, Heroku was able to appeal to a broad set of customers looking to quickly build apps. Containers are mutually isolated processes, wired together by third-party configuration which does not belong in the application’s code base - this design choice results in a lack of elasticity and granular control of your system. This results in a conservative outlook of dealing with infrastructure, constantly over-provisioning and hence overpaying to account for potential future load.

Furthermore, infrastructure is still treated separately from code - the two worlds live separately and don’t really know much about each other. There is much less wiring to do than with AWS for example, but what is left to do - and there’s a lot of it - you still have to do yourself. Heroku trades off AWS’s elasticity for ready-made building block components that are statically wired up together through a combination of CLI commands and dashboard operations. Of course, Heroku is limited by its founding principle: static containers as building blocks of applications. With Heroku, it is true you do not have to think about infrastructure - but only in the beginning. Once your application scales, your bills stack up and you’re left without a choice: go back to AWS.

The Serverless Conundrum

We need to talk about serverless. Serverless (think AWS Lambda) was a new cloud computing execution model where machine allocation happens on-demand and the user is primarily abstracted away from the underlying servers. With it came a familiar promise - developers not needing to think about infrastructure at all. Despite its somewhat counterintuitive name (because, of course, there are always servers running somewhere), serverless sounds like a great ideal to strive towards. This is simple, developers want to spend as much time as possible on delivering business value by writing code, while companies would like to avoid spending fortunes on DevOps. This seems to be the holy grail, but there’s a catch. You might ask, “if you say serverless is so great, why have we all not switched yet”?

Well, serverless forces you to write application business logic as functions, rather than the more traditional idiom of stateful processes. To reap the benefits of serverless, you have to build your application as a multitude of stateless request or event handlers, often requiring a bottoms-up redesign of your system. For some use-cases the serverless paradigm works, but in many cases breaking things into discrete, decoupled functions may not be optimal or even feasible. The next question is, can we have our cake and eat it too? Can we maintain the paradigm of stateful processes and abstract away the underlying infrastructure and orchestration?

Infrastructure from Code

At shuttle we want to empower engineers by creating the best possible developer experience.

We've already developed an annotation based system that enables Rust apps to be deployed with a one-liner, as well as dependencies like databases being provisioned through static analysis in real-time.

#[shuttle_service::main]
async fn rocket(
    #[shared::Postgres] pool: PgPool, // automatic db provisioning + hands you back an authenticated connection pool
) -> shuttle_service::ShuttleRocket {
    // application code
}

Building on the phenomenal engineering done before us, we see a better future. One where developers don’t need to do any “wiring” whatsoever when it comes to code and infrastructure.

In this future, infrastructure can be defined directly from code. Not in the “Infrastructure as Code” kind of way though, but in the way that the code that developers write implicitly defines infrastructure. What your code actually needs in terms of infrastructure should be inferred as you build your application, instead of you having to think upfront about what infrastructure piece is needed and how to wire it up.

This setup should also break the boundaries that keep containers isolated from each other (and thus make it difficult to orchestrate them), without necessarily getting rid of the paradigm of containers. It should not force you into any specific way of writing applications, but just be an extension of your workflow.

Having your cake and eating it too

When looking back at Heroku’s success, it becomes apparent that focusing on one language, Ruby, which was becoming quite popular at the time - was a remarkable strategy. It enabled their team to focus acutely and produce an unparalleled experience for their users.

At shuttle we are convinced Rust is the best language to start this journey with. It’s been the most loved language by developers for many years in a row (as well as one of the fastest-growing languages). If you want to create the best developer experience - it makes sense to start with the most loved language. Indeed, Rust is the first language packed with such a powerful set of tools for static analysis and code generation, that are required to create the best developer experience when it comes to Infrastructure as from Code.

Removing the burden of dealing with DevOps from developers, many of whom find it daunting and stressful, not only do we stand to make development more enjoyable and efficient, but also enable far more people to write and ship applications.

From inception, all of us shared affection for open source software, not only from a philosophical standpoint. We have seen in practice that the best way to build software is together with the end-users. It all goes back to the idea of creating the best developer experience - so for us, this is a no-brainer.

Our community is just as important to us, as our vision is, so if any of this resonates with you - join us on discord.

Also, if you’re curious to learn more about how we are building this - check out our GitHub.

Discussion time!

With all of the above in mind, what do you think about Infrastructure from Code? We'd love to hear your opinions and questions!