LLM's and Smaller, Less Popular Programming Languages

I work for GitHub, and so I've been a happy Copilot user since it was first created. It's been amazing to watch the pace of improvements in all of the foundation models that we use, and all of the models out there. (For programming, I love o1-mini, and I'm sure I'll love o3-mini, too.)

I'm also an F# programmer. My version control system, Grace, is written almost entirely in F#.

That means that when I'm asking LLM's to generate code for me, I'm usually asking them for F#. In fact, my custom instructions for Copilot and ChatGPT include this:

For questions about programming, assume the programming language is F#, unless told otherwise.
Code samples should be provided in F#, unless told otherwise.

And here's the thing: none of the models are very good at generating modern, idiomatic F#.

This led me to two big questions:

1. What does this mean for the future of less popular programming languages?
2. What should we do to help LLM's have a better understanding of less popular programming languages?

LLM's are Great with Popular Languages

Well, "duh", right?

Popular languages, by definition, have more lines of code written for LLM's to train on. They have more examples of more ways to do stuff, so the LLM's have more of an opportunity to build a rich, internal model of the language they can use when generating code for us.

Which languages am I talking about? I don't know, <waves hands> something like:

• C#
• Java
• JavaScript
• TypeScript
• Python
• C++
• Ruby

You know... popular ones.

Same thing for popular vs. not-as-popular frameworks, like React, Angular, Rails, etc.

The models have gotten particularly good at creating new projects in these languages (and frameworks) with nothing more than a natural-language requirements list.

They're also pretty good at refactoring and suggesting edits in those languages.

If you're using one of those languages, you're one of the lucky ones in these still-early days of AI coding assistants.

LLM's are Not Great with Less Popular Languages

So... I write a lot of F#. F# is not one of the big languages - even though it should be because it's fucking awesome - and so the Generative AI results I get when asking for F# are... <sigh>...

They're just not good. I mean, sometimes, for easy things, they're fine and I can use them and go. But for anything of any complexity, I need to specify a lot of detail to get good code, and sometimes, even then, I don't get usable, correct F#.

I don't spend any time in Julia, Crystal, OCaml, or Zig, or any of the other dozens of languages that fall into the "smaller, less popular" category, so I can't confirm they all get the same lower-fidelity treatment that F# does, but, it can't be good today to have fewer examples of code in your favorite language available for training the models.

Problem #1: Old syntax

The custom instructions I shared above isn't the whole section I have about F#. What I actually have is:

For questions about programming, assume the programming language is F#, unless told otherwise.
Code samples should be provided in F#, unless told otherwise.
All F# code uses the task { } computation expression to handle asynchronous operations.
All F# code should be written in a functional style, using immutability and pure functions where possible.
All F# code should the new syntax when referring to arrays, lists, and sequences: use myArray[0] instead of myArray.[0].

Why do I have all of that? Because, without going into details about F#, to get even close to good output, I'm forced to explicitly say to the model: "Use modern, correct syntax, not syntax from older language versions and older examples."

And this isn't just a problem for small languages. I haven't written any C++ lately, but I follow developments in the language. I imagine that a lot of the code examples you'd get using LLM's right now are going to show out-of-date examples of C++98-style, less safe stuff, instead of the much safer, declaratively safe, C++23.

(Seriously, check out the videos from CPPCon. Anything with Herb Sutter, Andrei Alexandrescu, and Chandler Carruth is highly recommended.)

Problem #2: Invalid structure and syntax

Here's an example I dealt with recently.

In C#, or any object-oriented-ish language, doing early exits from a method is normal. For instance:

public async Task<int> DoSomethingWithStorageAsync(string writeToStorage, string readFromStorage, string clearState)
{
    if(String.IsNullOrEmpty(writeToStorage))
    {
        return -1;
    }

    // Keep doing whatever the method is supposed to do...
    // ...
    // ...
    // Cool, we're done. Everything worked.
    return 0;
}

Getting out early with return -1 is how you avoid using an else and indenting everything after it, and, for better or worse, it's standard style these days.

Doing that in F#, though, is not allowed. In F#, the if expression is exactly that: an expression. It returns a value.

(There is no if statement in F#, because functional programming.)

You just can't use that early-exit construct without raising an exception, and that's not good functional practice.

I was asking the models to do something that I would describe as a medium-complexity function. I should start by saying: I expect that the use of the GitHub REST API, and, specifically, use of the GitHub .NET SDK, are well-enough-known to the LLM's that that shouldn't have been a problem. The prompt starts:

I am developing an F# command-line application that retrieves issues and pull requests from a specific GitHub repository using the GitHub API, and stores this data in a SQLite database...

and goes on with some detail, as I worked with GPT-4o first to craft the prompt before submitting it to o1-mini. And then to Claude Sonnet 3.5. And then to Google Gemini 2.0 Experimental. And even locally on LM Studio running Phi 3.5 and Llama 3.1.

None of them generated useful, working code. To get any of it working, I had to do way-too-much syntax fixing, and then way-too-much debugging.

There were problems with understanding how to use the F# Task Computation Expression - i.e. how F# does modern .NET async/await.

There were problems with understanding the output of the GitHub API and how to process it.

But, most worryingly... there were early exits.

These are obvious syntax errors, they're structurally wrong, they make no sense in F#, and I cannot imagine there are many examples of them in open-source F# code.

I guess the models are doing something like "F# is .NET; .NET is C#; C# patterns therefore work in F#...".

Even after I updated the prompt to include "do not use early exits" and then even "do not use early exits that look like bad example it generated" I couldn't get proper code for it.

Wrong solution (that kind-of worked)

Well, that was two hours of my life I can't get back.

I went to bed, and woke up with an idea: what if I just generate it in C#, and then have the LLM translate it to F#? I know they're better at code generation in C# than F#, and translating between languages is something they all do pretty well already.

So, I did. And, well, it kind-of worked. Still took more hand-holding than I'd like, but, I got it done.

But, that's not the right solution for this problem. I'll get object-oriented-ish F# out of that, not idiomatic, functional code that's beautiful.

Right solution: Help train the LLM's

I was thinking it might be good to use some pipeline of LLM's + compilers + thoughtful prompting to generate entire repositories of code that demonstrate the latest syntax and are published only after they successfully compile and are post-processed by a style-checker that validates that older syntax isn't present. With some human-in-the-loop, of course.

I wish there were a standard mechanism that the LLM's could recognize during training where we tell them "here are examples of correct, modern, up-to-date code in this language; when generating new code, translate older syntax into this new syntax", or something like that.

But even if there is... is a repository full of LLM-generated code just spam? I think it doesn't have to be, but I see the point.

Language Model Optimization

For over 20 years, we've all been aware of how important it is to do Search Engine Optimization (SEO) if you want your site to appear near the top of the search rankings.

Maybe, with LLM's, we need to do Language Model Optimization (LMO).

I would suggest that, if you want your programming language to be generated well by the models, that you'll need to take ownership of the LMO for your language.

This presents an entirely new workstream for language owners to handle. Hopefully, the LLM's can help us with it.

I Have No Idea How This Would Work

One idea is to work together to identify some set of tokens to tell the models: "this is the good stuff", and maybe also to give each language one owner who is allowed to create such repositories, so that the models have a trusted source during training.

I'm happy to hear other ideas... seriously, I have no idea how this would work, but I think we need it, and I think the programming business, in particular, deserves some special treatment during training.

If we don't help, we'll lose the smaller languages

If we don't do something to help the smaller languages, as code generation quality continues to improve for the more popular languages, the gap in quality between large and small languages will just continue to grow. Soon, the upside of trying a new language will be massively outweighed by that quality gap, and we'll become locked into the popular languages in an ever-tightening spiral of more popular = more quality.

Try talking your manager into letting the team learn that cool, new language when you can't use Copilot to get great results with it.

Anyway, I really love F#. I know people who love other, small languages as well. There's a good reason to have a healthy ecosystem of languages and ideas floating around, influencing each other. It's a Good Thing.

I hope Generative AI gets as good with idiomatic F# / Julia / Scheme / whatever as it already is with Java and TypeScript. I think it might need some help getting there.

(image by Simon Berger, shared on Unsplash)

I'm pleased to have the Friday-of-Christmas-weekend slot for F# Advent Calendar 2023. That means I know a lot of you will have some time to unwind with a longer read. I hope you enjoy. 😉

Je n'ai fait celle-ci plus longue que parce que je n'ai pas eu le loisir de la faire plus courte.

I have made this [letter] longer than usual because I have not had the time to make it shorter.

- Blaise Pascal, Provincial Letters, 1656 ¹

Hi! I'm Scott. (Hi Scott.) And I've been struggling to think of something interesting to write about for F# Advent of Code 2023.

I mean, I love F#. It's my favorite programming language, ever. It's been the vehicle for me to learn how to think functionally about programming, after two decades of object-oriented[ish] programming. And I've never seen a language like this where almost everyone who starts using it regularly, loves it, too.

I know I could do some Using F# with <insert technology here>! posts. And I probably should. I've written around 24,000 lines of F# code for my version control system, Grace, for almost three years now, and it uses things like Dapr, Dapr Actors, CosmosDB, Azure Storage, Spectre.Console, and more. I've got some interesting, functional code in there that I could talk about. (I think.) But none of that felt like the right thing to write about.

Anyway, one of the things I've learned about getting unstuck creatively is that sometimes it's best to start just by espressing something about what's present for you, what's going on in your life, right now.²

What's going on for me is: I'm working through some of the early code from Grace, figuring out how to rewrite it so it doesn't suck, and stumbling through the bugs I've found because of it.

So, that's what I'll share with you today: some not-great code I wrote a while back, why it's not great, how I'm fixing it, and what that might say about my development with F# and functional programming.

Anything worth doing is worth doing poorly, at first.

– Brian Tracy, many others

You don’t have to be great to start. But you have to start to be great.

– Zig Ziglar

My hope is that by sharing this part of my journey, I can free you to get started in your own journey with a new programming language (especially F#!).

I started writing an entire version control system when I didn't quite know what I was doing. You can start, too.

A little bit about Grace

This post isn't meant to be about Grace, but just to give the tiniest bit of context for what's coming:

Grace is a new, modern, cloud-native version control system. It is multi-tenant, centralized, and relies on PaaS products like Azure Blob Storage and AWS S3 for storing versions of files. Because it's centralized, Grace needs to ensure that when commands like grace switch or grace rebase are run, that the existing state of the branch is saved and uploaded before changes are made to the working directory.³

And, yes, it's really fast.

What I'm working on right now

What the hell?!?

– Me, looking at code I wrote a couple of years ago

Like you'd expect in a version control system, Grace has a command - grace switch - that lets you switch to another branch in your repo, and will update your working directory with the current contents of that other branch.

Grace also has a background agent mode - grace watch - that maintains a live connection to the server, enabling 2-way communication and local and server-side event processing, and that watches your working directory for changes and automatically uploads after every save-on-disk, allowing most of the more common Grace commands to run incredibly fast.

There's plenty of overlap between those two use cases. Both grace switch and grace watch have to:

• understand the current contents of the working directory,
• make sure that the current contents are uploaded to the server,
• update the local object cache that holds recent versions of the files in the repo, and
• update the local Grace Status file that holds the state of the branch.

That means that they share some function calls, of course.

Also, if you run grace switch while grace watch is running, grace watch has to be aware of it and ignore the changes in the working directory until the switch is complete.

The code for grace watch is about two years old. grace switch came right around the same time, maybe a month or two later. At the time, I wasn't very good at some important things. To make it worse, I was in a hurry writing it. 🤦🏼‍♂️

The problem (It's me. Hi.)

<stares at monitor, blinking>

– Me, looking at code I wrote a couple of years ago

There's a lot that I hadn't yet learned about thinking functionally. When I look at it now, some of the code is clearly, "yeah, had no clue how to do that." Some of it is, "Awww... that's cute. At least I tried." Some of it is, "I need to come up with better names for those functions."

In the "had no clue" department, you'll find some of my code for Grace's command-line interface (CLI), specifically, the way I'm trying to interleave work being done, like calls to the server, or writing new local files, with UI updates (updating progress bars) that reflect the progress of completing the command.

As I was writing it, I knew it wasn't great. It all looked like the Pyramid of Doom [towards the middle of the article] that our friend Scott Wlaschin warned us about, that I knew I should avoid, but couldn't figure out how to, and didn't have the time to deeply work through. It worked, but it wasn't anything I was proud of. I haven't deeply dived into this part of Grace in a long time, and I knew it would be a challenge to get back into it.

Let's fix... something

I decided some weeks ago to start by rewriting grace switch to be more idiomatically functional, to clean it up as the first example of how to do it for the rest of the CLI commands. This was kind-of stupid, because it's the longest bit of code in all of the CLI commands, it's complex, and would be the most difficult to do. But it was deliberate: if I could make it work for grace switch I could make it work for the rest.

Before

The "before" code starts here, and runs for 342 lines. I won't quote it here, and I don't expect anyone to actually read it or comprehend the logic, but if you glance at it, you'll notice how deeply indented the code gets. At its longest, the indentation is -------------------------------------------------------------------- this long. Ugh.

What's worse is that because Grace has multiple output modes – Normal, Json, Verbose, Minimal, and Silent – I duplicated most of the code in this function: once for when I'm showing output, and once for when I'm not. (DRY? Pfft.) That means that if I find a bug, I have to remember to fix it twice. Making a long story short, the logic is:

if showOutput then
    // Imagine lots of code with all of the steps to switch branches,
    //   with crazy levels of indentation, 
    //   and then show some output
else
    // Imagine almost exactly the same code,
    //   with crazy levels of indentation, 
    //   and then show little-to-no output

It's not my finest work.

After

After extracting the work steps into separate functions, it's much easier to understand and deal with.

Let's start with the main part of the new grace switch handler function. In the local function generateResult, look! monadic bind! With that defined, we check if we should show output, and either create those progress bars, or not:

let generateResult (progressTasks: ProgressTask array) =
    task {
        let! result = 
            (showOutput, parseResult, switchParameters)
            |> validateIncomingParameters
            >>=! getCurrentBranch progressTasks[0]
            >>=! readGraceStatusFile progressTasks[1]
            >>=! scanForDifferences progressTasks[2]
            >>=! getNewGraceStatusAndDirectoryVersions progressTasks[3]
            >>=! uploadChangedFilesToObjectStorage progressTasks[4]
            >>=! uploadNewDirectoryVersions progressTasks[5]
            >>=! createSaveReference progressTasks[6]
            >>=! getLatestVersionOfNewBranch progressTasks[7]
            >>=! UpdateWorkingDirectory progressTasks[8]

        match result with
            | Ok _ -> return 0
            | Error error ->
                logToAnsiConsole Colors.Error $"{error}"
                return -1
    }

if showOutput then
    return! progress.Columns(progressColumns)
            .StartAsync(fun progressContext ->
            task {
                let t0 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString GettingCurrentBranch}[/]", autoStart = false)
                let t1 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString ReadingGraceStatus}[/]", autoStart = false)
                let t2 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString ScanningWorkingDirectory}[/]", autoStart = false)
                let t3 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString CreatingNewDirectoryVersions}[/]", autoStart = false)
                let t4 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString UploadingFiles}[/]", autoStart = false)
                let t5 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString SavingDirectoryVersions}[/]", autoStart = false)
                let t6 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString CreatingSaveReference}[/]", autoStart = false)
                let t7 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString GettingLatestVersion}[/]", autoStart = false)
                let t8 = progressContext.AddTask($"[{Color.DodgerBlue1}]{UIString.getString UpdatingWorkingDirectory}[/]", autoStart = false)

                return! generateResult [| t0; t1; t2; t3; t4; t5; t6; t7; t8 |]
            })
else
    // If we're not showing output, we don't need to create the progress tasks.
    return! generateResult [| emptyTask; emptyTask; emptyTask; emptyTask; emptyTask; emptyTask; emptyTask; emptyTask; emptyTask |]

I even created a custom monadic bind function and operator for it!

let bindTaskResult (result: Task<Result<'T, 'TError>>) (f: 'T -> Task<Result<'U, 'TError>>) =
		(task {
				match! result with
				| Ok returnValue -> return (f returnValue)
				| Error error -> return Error error |> returnTask
		}).Unwrap()

/// Custom monadic bind operator for the nested monad Task<Result<'T, 'TError>>.
let inline (>>=!) (result: Task<Result<'T, 'TError>>) (f: 'T -> Task<Result<'U, 'TError>>) =
		bindTaskResult result f

And instead of all of it in one huge function, here's a sample of some of that logic broken down into a smaller function that's easy to understand, with fewer places for bugs to hide, that handles its own output. This is the part that checks for changes in your working directory:

// 2. Scan the working directory for differences.
let scanForDifferences (t: ProgressTask) (showOutput, parseResult: ParseResult, parameters: CommonParameters, currentBranch: BranchDto) =
    task {
        t |> startProgressTask showOutput
        let! differences = 
            if currentBranch.SaveEnabled then
                scanForDifferences newGraceStatus
            else
                List<FileSystemDifference>() |> returnTask
        t |> setProgressTaskValue showOutput 100.0
        return Ok (showOutput, parseResult, parameters, currentBranch, differences)
    }

Mission Accomplished!

So, yay! Cleaner code, easier to maintain, less duplication. Winning!

uhh...

But... not exactly. After I refactored the code and started testing it, I found some bugs, and those bugs go all the way back to when I wrote grace watch and grace switch in the first place. Some of those bugs have now been fixed. A few remain that I'm tracking down.

All of them have the same root causes: an early, less-developed sense of what good functional programming looks like, and a lack of careful thinking, reflected in a lack of carefully-written code.

For instance...

Why is this happening? Better add some

logToConsole $"...stuff...".

– Me, debugging code I wrote a couple of years ago

In Services.CLI.fs, I have a function called getNewGraceStatusAndDirectoryVersions. You can see it here.

It's almost 200 lines long. That may or may not sound like a lot to you, but, to me, now used to F# and thinking in terms of small, single-purpose, composable functions, it's a lot, it's probably too much, and it's a code smell.

In my first job out of college, in 1991, as a mainframe COBOL programmer for AT&T, I remember the senior programmer on the team telling me, "Most people can only hold about a screenful of code in mind at any given time," and that was back when we used 24 x 80 character green-screen monitors!

That same senior programmer had worked on that code for its entire six-year existence, and had previously worked on the system it replaced for many years. When I asked him questions about the code, like why a certain module was written the way it was, he would look up, scratch his chin, and start into a story like "well, about four or five years ago, there was this requirement..." or "in the old system, about ten years ago, <something>... and we never cleaned that up." It was always a story, and almost always something that, if you didn't have the context from that story, would be much more difficult to understand.

That experience led me to one of my most important rules for programming:

Never write code that you have to tell a story about.

200-line functions are not good for comprehensibility or maintainability. They invite subtle bugs. They're hard to debug when you've never seen them before. (And, apparently, even when I wrote it myself.) If you get asked about why they are they way they are, you probably have to tell a story, and that's not good.

My story for getNewGraceStatusAndDirectoryVersions: I wasn't very good at this when I wrote it. 🤷🏼‍♂️

Also, the function name itself is a code smell. If your function name has "and" in it, that's a good sign that it's doing too many things and should be broken down into smaller pieces.

That's exactly what I'm working on: refactoring getNewGraceStatusAndDirectoryVersions and some of its related functions that are called both by grace watch and grace switch. It's a slog. I was trying to think in functions back then, but they're not shaped well, they do too much, and they're just hard to understand. I don't want to tell that story. I don't want to leave that for the next maintainer, who could be Future Me.

(You may have noticed that I still have that name for a smaller function in my refactored grace switch code, and I'll be looking at that, too.)

My development in F#

So where am I in my F# journey?

Well, I've gotten a much better sense of "how big is too big?" and "how complex is too complex?" when creating and refactoring functions. I might write a first-draft of a new function that's a bit long, but I immediately start breaking it down into smaller parts that are easier to understand, so I don't have to tell any stories for someone else to maintain the code.

As I showed above, I've figured out how to use monads in interesting ways to help write concise, easy-to-understand code.

I'm comfortable thinking about functions as first-class language constructs that can be passed as parameters, and I've gone through all of the phases of "I still use classes because I'm still embedded in OO thinking" to "I never use classes because I'm cool like that" to "I use classes where it makes sense".

And I'm 100% willing to dive in and rewrite some of the less elegant, older code that gets in the way of moving forward quickly.

Some of Grace is really clever and well-written, if I do say so myself. For instance, the way I do parameter validations in Server API endpoints is kind-of neat. I create an array of function calls that check the values passed in, return a custom error if they fail, and I execute them before I run the "real" action of the endpoint. It took a bit to figure out the right pattern, but once I did, repeating if for all of the API endpoints has been easy. Here's an example, from the endpoint to set the name of an organization:

let validations (parameters: SetOrganizationNameParameters) (context: HttpContext) =
    [| Guid.isValidAndNotEmpty parameters.OwnerId InvalidOwnerId
       String.isValidGraceName parameters.OwnerName InvalidOwnerName
       Input.eitherIdOrNameMustBeProvided parameters.OwnerId parameters.OwnerName EitherOwnerIdOrOwnerNameRequired
       Guid.isValidAndNotEmpty parameters.OrganizationId InvalidOrganizationId
       String.isValidGraceName parameters.OrganizationName InvalidOrganizationName
       Input.eitherIdOrNameMustBeProvided parameters.OrganizationId parameters.OrganizationName EitherOrganizationIdOrOrganizationNameRequired
       String.isNotEmpty parameters.NewName OrganizationNameIsRequired
       String.isValidGraceName parameters.NewName InvalidOrganizationName
       Organization.organizationExists parameters.OwnerId parameters.OwnerName parameters.OrganizationId parameters.OrganizationName OrganizationDoesNotExist
       Organization.organizationIsNotDeleted parameters.OwnerId parameters.OwnerName parameters.OrganizationId parameters.OrganizationName OrganizationIsDeleted |]

validations here is a function that takes in a parameter object, and the HttpContext, and returns ValueTask<Result<unit, OrganizationError>> array. With that in place, when I run the validations, I can use a utility function allPass to say:

let validationResults = validations parameters context
let! validationsPassed = validationResults |> allPass

I have some small but nice utility functions to serialize and deserialize objects, using Grace's custom JsonSerializerOptions:

/// Serializes an object to JSON, using Grace's custom JsonSerializerOptions.
let serialize<'T> item =
    JsonSerializer.Serialize<'T>(item, Constants.JsonSerializerOptions)

/// Serializes an object to JSON and writes it to a stream, using Grace's custom JsonSerializerOptions.
let serializeAsync<'T> stream item =
    task {
        return! JsonSerializer.SerializeAsync<'T>(stream, item, Constants.JsonSerializerOptions)
    }

/// Deserializes a JSON string to a provided type, using Grace's custom JsonSerializerOptions.
let deserialize<'T> (s: string) =
    JsonSerializer.Deserialize<'T>(s, Constants.JsonSerializerOptions)

/// Deserializes a stream of JSON to a provided type, using Grace's custom JsonSerializerOptions.
let deserializeAsync<'T> stream =
    task {
        return! JsonSerializer.DeserializeAsync<'T>(stream, Constants.JsonSerializerOptions)
    }

These let me say things like

    let json = serialize myThing
    let myThing = deserialize<MyThing> json
		
    logToConsole $"DirectoryVersion: {serialize directoryVersion}"

    override this.ToString() = serialize this

etc. really easily wherever I need to.

There's much more in Grace's code that I'd show you, but, the details aren't important for this.

I still have lots more to learn about F# and about functional programming.

I've never used statically-resolved type parameters (SRTP). I've never used or created a type provider. I've never created a custom computation expression (CE), and I still don't have an intuitive grasp of when creating and using one would improve my code. I have a basic understanding of category theory, but I'd love to deepen that and use more of the patterns from category theory where they make sense in my code. I've never written Haskell, and knowing Haskell, and being able to compare it to F#, would, no doubt, be helpful.

I say all of that to say: I'm not at the beginning of my journey in F# anymore. And I'm far from the end of it. I'm solidly in the middle, and that means that I'm good enough to be creative and concise, and to feel good about the code I'm writing now.

And, probably, one day, I'll look back on the code I write in 2024 and think, "I can do that better now."

We've all come a long way

Debugging and refactoring that older code over the last few weeks has been a trip. It's like visiting a younger version of myself.

Even though that code isn't as elegant as I'd like it to be, I'm still proud that I wrote it.

And you should be proud of where you are in your journey. If you're a programmer (and if you've read this far, you probably are) then you've had your experience of starting knowing nothing, writing and shipping code even though you weren't very good at it yet, and consistently improving, maybe even approaching mastery with the languages and tools you use.

I'm proud that I stuck with F#.

I'm proud that I'm still working on Grace.

I'm proud that I can see the progress I've made, and it gives me proof that I can still learn completely new things, move from beginner to experienced to mastery, and continue to develop both my art and craft.

So can you. I hope you will.

TL;DR: I've tried everything I can to get Dapr to talk to the CosmosDB Emulator container, which ships with a self-signed certificate and which therefore fails making an https connection, and I'm giving up for now.

If I find a solution to this, I'll write another blog post about it and link to it here. If there's no link, 🤷‍♂️.

Introduction

So... I'm working on my source control system, Grace, and the next thing I'd like to do is to enable contributors (and myself) to work on it using a Docker Compose configuration.

Grace is built using Dapr, which allows users to write code once, and then plug in over 100 different pieces of infrastructure, including cloud PaaS services, so that the platform can be chosen at runtime. I love lots of things about this, but one of the big ones is that you can imagine writing your code locally running on containers for state store, observability, secrets, pub/sub, etc. and then run that same exact code in production on completely different, larger, scalable infrastructure.

Right now, Grace is sort-of hard-coded to expect Azure CosmosDB as the state store under Dapr. There was a reason in earlier versions of Dapr that I needed to do this, but Dapr has since added the features I need to remove that specific code and replace it with higher-level Dapr queries.

As part of the process of getting a Docker Compose setup going, I figured, hey, CosmosDB has an emulator container available. Might as well add that to Compose so it's there while I spend the time to rewrite the CosmosDB-specific parts into Dapr code.

The problem

The CosmosDB emulator container ships expecting to be connected to over https, which is a reasonable thing these days, but it ships with a self-signed certificate, which makes connecting over https a bit challenging. The certificate it has is not sourced from a root CA, and, by default, every browser and HTTP stack will refuse to connect to a site with a broken chain-of-trust, and self-signed certificates do not have a chain-of-trust. This is same problem we run into when, for instance, we spin up a new web project, configure it to run on https, and then get a warning message in the browser when we try to connect to it.

In my F# code, I can bypass this by configuring my CosmosClient with a custom HttpClientFactory that provides HttpClient instances that bypass TLS checking. Because this is something that you never want to do in production, I've configured it to only happen in debug builds.

    let CosmosClient() = 
        if not <| isNull cosmosClient then
            cosmosClient
        else
            let cosmosDbConnectionString = Environment.GetEnvironmentVariable(Constants.EnvironmentVariables.AzureCosmosDBConnectionString)
            let cosmosClientOptions = CosmosClientOptions(
                ApplicationName = Constants.GraceServerAppId, 
                EnableContentResponseOnWrite = false, 
                LimitToEndpoint = true, 
                Serializer = new CosmosJsonSerializer(Constants.JsonSerializerOptions))
#if DEBUG
            let httpClientFactory = fun () ->
                let httpMessageHandler: HttpMessageHandler = new HttpClientHandler(
                    ServerCertificateCustomValidationCallback = (fun _ _ _ _ -> true))
                new HttpClient(httpMessageHandler)
            cosmosClientOptions.HttpClientFactory <- httpClientFactory
            cosmosClientOptions.ConnectionMode <- ConnectionMode.Direct
#endif
            cosmosClient <- new CosmosClient(cosmosDbConnectionString, cosmosClientOptions)
            cosmosClient

And in my Dapr config for a state store using Azure CosmosDB, I can specify the values to connect to the emulator.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: actorStorage
spec:
  type: state.azure.cosmosdb
  version: v1
  initTimeout: 1m
  metadata:
  - name: url
    value: https://localhost:8081/
	# This key is a well-known default value for the emulator.	
  - name: masterKey
    value: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
  - name: database
    value: gracevcs-development-db
  - name: collection
    value: grace-development
  - name: partitionKey
    value: "/partitionKey"
  - name: actorStateStore
    value: "true"

Cool so far. The problem comes when Dapr starts and tries to connect to the emulator.

It just doesn't work

{"app_id":"grace","instance":"dd6c98246b75","level":"fatal","msg":"process component actorStorage error: [INIT_COMPONENT_FAILURE]: initialization error occurred for actorStorage (state.azure.cosmosdb/v1): Get \"https://localhost:8081/dbs/gracevcs-development-db/colls/grace-development\": dial tcp 127.0.0.1:8081: connect: connection refused","scope":"dapr.runtime","time":"2022-12-03T01:08:37.581552869Z","type":"log","ver":"1.9.4"}

And that connection refused error is happening because of the self-signed cert on the emulator. Sigh.

I'm running on Windows 11, using WSL 2 and Docker Desktop in Linux mode. I've tried to do the things listed in Microsoft's documentation for the emulator container, including exporting the cert from the emulator and installing it into Linux. But, still, the connection is failing.

I don't have any way to tell Dapr to bypass TLS checking on connections, and I don't think they should have a flag in their code to even enable that. It's bad practice, I get that, and I don't want to give anyone a footgun they'll regret using.

Let's call it

Usually you write a blog post announcing how awesome you are for having figured something out.

In this case, I'm just admitting defeat for now. Just wanted this up here in case anyone else is searching for information on this. I might revisit this in a few weeks, but, for now, I'm going to try using the installed CosmosDB Emulator, and if that doesn't work quickly, I'll just keep using actual CosmosDB until I can replace the code that needs it and just use Dapr's functionality.

Photo by Clint Patterson

I was setting up this very blog you're seeing, and wanted to try Orchard CMS. So far, I like it a lot.

For the media library - the part where I upload the images that go into the posts - I wanted to use an Azure Storage account, and it was a bit of a journey to get it set up.

The Orchard docs show how to configure everything in appsettings.json, but I wanted to set my configuration values in environment variables. to make sure I didn't check in any secrets to my source code.

And I wanted to put Azure CDN in front of all of the static files I serve. Why? Because I can. 🙂

Here's what I did.

Basic steps

• Enable the Media features in Orchard's admin site
• Set up Azure CDN endpoints for both your Azure Storage account, and the web site itself
• Configure the environment variables to tell Orchard to use Azure Storage for the Media Library
• Configure the Site CDN in Orchard's admin
• Restart the site so it picks up the new configuration

Enable Media features

First, in order to enable storing the Media Library in Azure Blob Storage, you need to make sure three features are enabled in Orchard.

• Media
• Media Cache
• Azure Media Storage

To find them, in the /admin section of your site, go to Configuration / Features, and search for Media.

Set up Azure CDN

I have a Microsoft CDN (classic) already running, so that's what I'm using. Azure Front Door seems like a great service for web sites with significant traffic, but this blog isn't one of them, so I'm sticking with a "regular" CDN service.

I wanted to put Azure CDN in front of two things:

• the Azure Storage account that's holding my Media Library, i.e. all of the images on the site
• the static files from the web server, i.e. CSS and JS and other stuff like that

That meant that I needed to create two separate endpoints:

• scottarbeitstorage
  • Origin hostname of my Azure Storage account, scottarbeit.blob.core.windows.net
  • mapped to scottarbeitstorage.azureedge.net
• scottarbeitweb
  • Origin hostname of www.scottarbeit.com
  • mapped to scottarbeitweb.azureedge.net

I also figured I'd create custom domain names for them. (Why not, right?)

First, I needed to create two CNAME's in my domain's DNS entries:

• cdn.scottarbeit.com, mapped to scottarbeitstorage.azureedge.net
• static.scottarbeit.com, mapped to scottarbeitweb.azureedge.net

Then I needed to add them as custom domains in the configuration of each endpoint. It's simple enough to add them if you have the CNAME's you're going to use ready to go.

I strongly recommend, of course, that you enable HTTPS, allow Azure to create and manage the certificates you need - which is really, really nice - and set a minimum TLS version of 1.2.

Here's the results for the first custom domain I set up:

Configuring environment variables for the Media Library

I need to provide the connection string for Azure Storage, the name of the container that I'm using for the Media Library, the URL of the storage CDN endpoint we set up above, and a few other values. I want to use environment variables to keep secrets out of my code.

By setting the CdnBaseUrl value, Orchard will emit requests for files in the Media Library - images in my case - to come from the CDN instead of directly from Azure Storage.

In appsettings.json (or appsettings.{Environment}.json), we'd have:

{
  "Logging": {
    ...
  },
  "OrchardCore": {
    "OrchardCore.Media": {
      "CdnBaseUrl": "https://cdn.mydomain.com",
      "AssetsRequestPath": "/static"  // Default value is "/media"
    },
    "OrchardCore.Media.Azure": {
      "ConnectionString": "DefaultEndpointsProtocol=https;AccountName=(your storage account name);AccountKey=(your storage account key);EndpointSuffix=core.windows.net",
      "ContainerName": "static",  // Default value is "media"
      "BasePath": "",
      "CreateContainer": true
    }
  }
}

When translating a configuration hierarchy to environment variable names, substitute a double underscore __ to denote a level, and replace periods in configuration key names with a single underscore _. That becomes:

• OrchardCore__OrchardCore_Media__CdnBaseUrl
• OrchardCore__OrchardCore_Media__AssetsRequestPath
• OrchardCore__OrchardCore_Media_Azure__ConnectionString
• OrchardCore__OrchardCore_Media_Azure__ContainerName
• OrchardCore__OrchardCore_Media_Azure__BasePath
• OrchardCore__OrchardCore_Media_Azure__CreateContainer

How you set your environment variables depends on how you deploy, of course. I'm in Azure App Service, so I set them in the Configuration page there.

With those values set, Orchard will read them at startup, you'll be able to keep them out of appsettings.json, and keep secrets out of your source code.

Configure Orchard's Site CDN

The environment variables hold the CDN endpoint for the Media Library.

Now, I need to configure the CDN for the static files that are served from the web site itself, using the other CDN endpoint I created.

In the /admin site, go to Configuration / Settings / General, and click on the Resources tab. Then set the Site CDN (Content Delivery Network) base url to the static file CDN custom domain.

Success

With all of that done, I have this very blog that you're reading accelerated through the use of Azure Storage and CDN's.

You should be able to get your instance of Orchard configured like this with a little patience and a little bit of time.