Converting BibleWorks Hebrew

We recently announced that we’ll support importing BibleWorks notes into Logos 7. This is mostly a matter of converting RTF into our internal format, a fairly well-understood process.

The one wrinkle is supporting BibleWorks Greek and Hebrew fonts. BibleWorks didn’t support Unicode for many years; instead it used the Bwhebl and Bwgrkn 8-bit fonts to simulate Greek and Hebrew characters.

In Unicode, b and β and ב are all separate characters (that in some cases are all supported by a single font). With 8-bit fonts, one uses Latin characters (a, b, c) but changes the font so that “b” looks like β or ב. Behind-the-scenes, κύριος is stored as ku,rioj and אֲדֹנָ֣י as yn’ådoa}. This makes text processing more difficult as you can no longer perform a search for Greek or Hebrew using the Unicode versions of those characters. It also means the user must have these specific fonts installed and can’t change their preferred Greek or Hebrew font. For a good customer experience, we needed to convert the characters for users who had BibleWorks notes predating Unicode support.

The Greek was relatively straightforward, but Hebrew presented a bigger challenge. Not only is BibleWorks Hebrew stored using Latin characters, it’s also stored in display (i.e., left-to-right) order. In Unicode, characters are stored in logical order (which is right-to-left for fragments of Hebrew text); the display system will lay them out correctly. The string needs to be reversed, but with a catch: in both BibleWorks Hebrew and in Unicode, Hebrew vowels and accents are entered after the character that they’re positioned on top of. We can’t naively reverse the entire string; we have to reverse it one grapheme cluster at a time.

Moreover, Unicode has a concept of bidirectional mirroring in which “neutral” characters are replaced by their mirrored versions in a RTL run; for example ( will be displayed as ) in right-to-left text. When reversing the string, these characters need to be replaced by their mirrored version.

Finally, the documentation we found gave BibleWorks Hebrew characters as decimal numbers representing entries in an 8-bit font; due to the way we were reading the RTF source of BW Notes, these bytes had already gone through a Windows-1252 to Unicode conversion, so our character map had to be based off the Unicode characters that corresponded to Windows 1252 bytes.

Step                    
Initial input 191 121 110 39 229 100 111 97 125 192
Decode Windows-1252 to Unicode ¿ y n å d o a } À
Untransliterate ( י נ ָ ֣ ד ֹ א ֲ )
Reverse grapheme clusters ) א ֲ ד ֹ נ ָ ֣ י (
Flip punctuation ( א ֲ ד ֹ נ ָ ֣ י )

The final result: (אֲדֹנָ֣י)

Our complete BibleWorks Hebrew mapping table is available here.

Posted by Bradley Grainger on August 15, 2018


Faster API calls with JWT access tokens

At Faithlife, we’ve been using OAuth 1.0a to handle authentication between services. Instead of designing our apps as monoliths, we’ve been perferring to build lightweight frontend applications that call RESTful microservices, returning entities as JSON. These frontend applications don’t touch our databases directly. Among other benefits, this allows us to better allocate hardware resources (CPU, RAM, disk) to applications that need them.

A typical request to Faithlife might look something like this:

mermaid
sequenceDiagram
	participant Frontend
	participant Accounts
	participant Community Newsfeed
	participant Amber API
	participant Notifications API
	participant OAuth
	Frontend->> OAuth: Authenticate user
	Frontend->> Accounts: List groups
	Frontend->> Community Newsfeed: Fetch newsfeed
	Community Newsfeed->> OAuth: Authenticate user
	Community Newsfeed->> Amber API: Get post images
	Amber API->> OAuth: Authenticate user
	Frontend->> Notifications API: Get notifications
	Notifications API->> OAuth: Authenticate user

At the beginning of the request, Faithlife makes a call to OAuth API to ensure the current OAuth access token and secret are still valid. After that check passes, the current user’s OAuth credentials are also passed to all downstream services that require auth.

An authorization header presented to a downstream API looks something like:

Authorization: OAuth oauth_consumer_key="1E18E56BD0C3A51A945D98136D6462FCEAE65199",oauth_signature="0B847E32C6DE692A7BA899DF67EF5C1BCCAEFA89%262D3F6B2BD18B2DD85821EFF0F07EB130AD46E5C5",oauth_signature_method="PLAINTEXT",oauth_version="1.0",oauth_token="FE009074810F3D2E3A2EB6BF5603B1CA08082AB7"

However, this poses a problem - our microservices do not have access to the OAuth database directly, and can’t validate the current user’s authorization header without first calling OAuth API. These calls are not free - on average, we measured the time taking from 10-35 ms for apps within the same data center, depending on a variety of factors. As we add more API calls to Faithlife, it gets progressively worse:

  • Pages take longer to load, as each API dependency needs to call OAuth API.
  • APIs may need to fetch data from other downstream APIs, and each API needs to validate the authenticated user.
  • APIs hosted outside the datacenter (Azure, GKE, etc) can magnify this problem significantly if the app is not hosted geographically close to where OAuth API lives.
  • Locally caching the oauth validation state on a web node only solves part of the problem. Many APIs are backed by multiple web nodes, with round robin request balancing, so there could be a cache miss.

JWT Access Tokens

What we needed was a way to pass a token to downstream APIs that identifies the current user. OAuth 1.0a was suitable for a long time, and several years ago we decided to hold off on migrating to OAuth 2 because the need was not strong enough. OAuth 2 adds a few steps to the authentication flow:

  1. When signing a user in, obtain a refresh token and an access token.
  2. Use the access token for API calls. The OAuth 2 and OpenID Connect standards do not define the format that these access tokens have to be in, but OpenID Connect mandates JSON web tokens (JWTs) for identity tokens, and identity tokens can be used as access tokens. To future proof our implementation, we chose to use JWTs signed with ES256. This blog post explains the token differences in greater detail..
  3. When the access token expires, use the refresh token to obtain a new access token

JWT access tokens have a few desirable properties for our use case. Tokens contain claims about the current user (such as the user ID and current roles), an expiration date, and are signed with a public/private key pair. Downstream APIs can validate their integrity using the public key, but only the signing authority can issue new ones. For our use case, we established some requirements for all JWT access tokens:

  • Only OAuth API has access to the private key and is solely responsible for issuing JWT access tokens. The public key is available via a public API.
  • JWT access tokens can only be created from plaintext OAuth 1 access tokens. Creating a JWT access token from a previous JWT access token is not allowed.
  • JWT access tokens are signed with ES256. All other signatures must be rejected.
  • Expiration date is 10 minutes from the current time, and not valid before 10 minutes prior to current time.
  • JWT access tokens contain claims for the current user ID, frontend app consumer ID, and any other properties that would be normally obtained when validating the current user via OAuth API.

JWT access tokens are presented to the downstream APIs that Faithlife calls. On the very first request, the current public key is requested from OAuth API. Using this public key, tokens can now be validated locally. All future tokens for the lifetime of the app are validated with this public key. Because the token has claims stored within it, we now have no need to call OAuth API for successful authentication attempts. If the token can’t be validated locally, either because the token appears to be expired due to clock skew, or because the signing key was changed, the downstream API makes a validation call to OAuth API (just like it did before).

We did not end up implementing the full OAuth 2 authorization flow when adding support for JWT access tokens. Instead, we used the OAuth 1 credentials in place of OAuth 2 refresh tokens to obtain access tokens.

How is this approach different from OAuth 1?

This approach follows the full OAuth 1.0a authorization flow, but replaces OAuth 1 plaintext tokens with JWT access tokens when communicating with downstream APIs. An OAuth 1 plaintext token is still obtained and stored by the frontend web application (in an encrypted cookie), and then upgraded to an JWT access token at the beginning of a frontend request. We could have migrated our auth services to a full OAuth 2 implementation, but this would be a non-trivial amount of work, and was more than we wanted to take on in this iteration. We were mainly interested in the scalability wins of using JWT access tokens, and leaving open the future possibility of using the full OAuth 2 authorization flow in the future.

Tokens in action

When Faithlife gets a web request, it makes a call to OAuth API:

GET /oauth/v1/users/current
Authorization: OAuth oauth_consumer_key="1E18E56BD0C3A51A945D98136D6462FCEAE65199",oauth_signature="0B847E32C6DE692A7BA899DF67EF5C1BCCAEFA89%262D3F6B2BD18B2DD85821EFF0F07EB130AD46E5C5",oauth_signature_method="PLAINTEXT",oauth_version="1.0",oauth_token="FE009074810F3D2E3A2EB6BF5603B1CA08082AB7"

And gets back a JWT:

X-Bearer-Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyOTg2Njg5IiwiY29uc3VtZXJOYW1lIjoiRmFpdGhsaWZlIiwiY29uc3VtZXJUb2tlbiI6IjRFNTdGQTk1MDE1MTJDMUM0RjdFMzQ1NzE0NjNDMjI0QjBCMzc1NEQiLCJpc0FkbWluQ29uc3VtZXIiOiJ0cnVlIiwibmJmIjoxNTMyOTgyMDQ2LCJleHAiOjE1MzI5ODMyNDYsImlhdCI6MTUzMjk4MjY0NiwiaXNzIjoiYXV0aC5mYWl0aGxpZmUuY29tIiwiYXVkIjoiZmFpdGhsaWZlLWJhY2tlbmQtYXBpcyJ9.7GSdItnnCr8QOLS3uCbJMY0X-D7jTjp_XUAp8clo9LY4X5Zlf_5I7RSMZr3J6kOihwbHjEbuh0AFMXmF5YQZLg

Which decodes to:

{
  "sub": "2986689",
  "consumerName": "Faithlife",
  "consumerToken": "4E57FA9501512C1C4F7E34571463C224B0B3754D",
  "isAdminConsumer": "true",
  "nbf": 1532982046,
  "exp": 1532983246,
  "iat": 1532982646,
  "iss": "auth.faithlife.com",
  "aud": "faithlife-backend-apis"
}

This JWT is passed to all downstream services in the Authorization header. Our request graph now looks much better:

mermaid
sequenceDiagram
	participant Frontend
	participant Accounts
	participant Community Newsfeed
	participant Amber API
	participant Notifications API
	participant OAuth
	Frontend->> OAuth: Authenticate user and obtain JWT
	Frontend->> Accounts: List groups
	Frontend->> Community Newsfeed: Fetch newsfeed
	Community Newsfeed->> Amber API: Get post images
	Frontend->> Notifications API: Get notifications

On average we measured validating this token taking less than 4 ms per request. We’re happy with the results so far and are in the process of rolling support out to all of our APIs.

Alternate strategies

There is more than one way to solve this problem. A few other strategies we considered:

  • Using a shared service account to communicate with downstream services. This increases the chance that a frontend regression reveals access to data that the user is not allowed to see (e.g. posts to a secret group). There are many different teams in charge of the APIs that Faithlife calls (e.g. commerce APIs are separated from community APIs), and validation at the API layer is much easier to enforce across team boundaries.

  • Using a shared key and pass a signed token or cookie. This presents several security problems. Rotating the shared token would have been very complicated, and having the signing key on all of our web nodes increases the attack surface. We wanted a solution that was standardized and would scale well into the future. Some of these solutions are also tighly coupled to the web application stack (ASPXAUTH cookies for example), and our auth solution needs to work on multiple API platforms.

Technologies used

We primarily use ASP.NET here at Faithlife, although we also host services using NodeJS and .NET Core. A sample .NET Core app that demonstrates both signing and validating ES256 tokens is hosted here:

https://github.com/Faithlife/ES256-Demo

This demo uses these NuGet packages:

Thanks for reading!

If you’re intersted in working on projects like this, come work with us! Thanks to Robert Bolender, Justin Brooks, and Bradley Grainger for giving feedback on early drafts of this post.

Posted by Dustin Masters on August 06, 2018


Inspecting Response Headers in the Android WebView

The Android WebView is great for presenting users with web content in native or hybrid applications. Its ability to bind JavaScript code to a client-side interface, navigation controls, and relatively small API surface are all great. However, this week I ran into an unfortunate omission. There is no proper mechanism for inspecting response headers on WebView requests.

Getting the Response Headers

In our particular case, we needed some information from faithlife.com that is returned as a custom header in order to handle a specific edge-case in our app well. After some exploration, it seemed our best bet was to make the HTTP request ourselves without the help of WebView so we could inspect the headers. We use OkHttp for networking, but the idea is the same so long as you’re able to inspect response headers using your networking client of choice. That looks something like this:

val okHttpClient = OkHttpClient.Builder().Build()
val request = Request.Builder()
		.url(requestUrl)
		.build()
val response = okHttpClient.newCall(request).execute()
val importantInfo = response.headers.firstOrNull { it.key == "X-Important-Info" }

importantInfo?.let {
	// We have our information.
}

Note: When using this type of logic in shouldOverrideUrlLoading(WebView, WebViewRequest), be sure to copy the request headers on the second parameter into the headers of the initial get request (part of the RequestBuilder if you use OkHttp).

Handling Cookies

Since this WebView is showing user content on faithlife.com and is running within the context of our app, we’ll need to make sure faithlife.com knows that we’re authenticated. The site handles authentication via cookies. That cookie information is passed back from the initial request via Set-Cookie headers. Fortunately, it’s pretty easy to get that data where it needs to go.

response.headers("Set-Cookie")?.forEach { setCookieHeader ->
	CookieManager.getInstance()
		.setCookie(requestUrl, setCookieHeader)
}

Loading the Web Content

Now we have access to the response headers and we’ve made sure our cookies are up to date, but we still have to show the web page. Since we already have the HTML of the page from the initial GET, we can avoid loading the webpage again by loading that HTML into the WebView directly. The thing to pay attention to here is that the first parameter to loadDataWithBaseURL is used to resolve relative paths and for applying JavaScript’s same origin policy. You want to be sure to use the response’s last known url when loading this data in case the first call to the requestUrl triggers a redirect. response.request().url() is the okhttp3.Response way of getting the last url in the redirect chain.

if (response.isSuccessful) {
	val responseBody = response.body()
	responseBody?.let {
		webView.loadDataWithBaseURL(
			response.request().url().toString(),
			responseBody,
			response.header("Content-Type") ?: "text/html",
			null,
			requestUrl
		)
	}
}

Now the WebView takes back over as it renders the HTML, loading other resources just as if it had handled the initial get request also.

Extra Reading

We like Kotlin a lot. As it currently stands, the upcoming version of the app is exclusively written in the language. If you’re an Android developer and find problems like this fun, we’re hiring!

We have some exciting things planned for the Faithlife App [play store link]. Stay tuned!


Thanks to Dustin Masters & Logan Ash for reviewing earlier versions of the post.

Posted by Justin Brooks on July 31, 2018


Inspecting application state with the SOS debugging tools

In this post, we’ll cover how to use the SOS debugging tools to inspect variables from a process dump of a .NET Framework / .NET Core application.

Required:

Obtaining a memory dump

In this first example, we’ll use a running ASP.NET MVC 5 application hosted by IIS, but the steps here can be used on a normal .NET framework Windows application. Let’s start by taking a full memory dump of a running application.

Download ProcDump and copy it to the server that runs the application you want to debug. Obtain the process ID from the application you want to profile by using Task Manager, and then pass it as an argument to procdump.

procdump -ma <pid>

You should now have a dump named similar to w3wp_171229_151050.dmp in the working directory.

Note:

If you’re running several applications under a single app pool in IIS, it may be easier to debug by changing the app to run under its own application pool, which allows the ASP.NET app to run under a dedicated process.

Inspecting the ASP.NET application state (.NET Framework)

Now that we have a memory dump, it’s time to look at the suspended state of the application. Copy the dump file to your workstation, and then open it via File > Open Crash Dump in WinDBG. Your screen should look like this:

Load the SOS debugging extension, which will allow us to inspect the managed threads:

!loadby sos clr

Then, list the stack trace of every thread:

!eestack

Note:

If get an exception when running this command and you are using IIS Express, try the command again. There appears to be a bug that throws an exception only for the first command run from WinDbg, which should not affect the rest of your debugging session.

You should see a lot of threads in the output. To narrow the results down, search for the namespace of your project in the output text.

We can see that there is an external web request being made in Thread 34. Let’s look at what external URL is being requested. Switch to the thread, and then run clrstack -p to get some more detailed information about each method call.

~34 s
!clrstack -p

Note:

You may see many arguments that contain the value <no data>. This can be caused by compiler optimizations; inspecting the state of these parameters is beyond the scope of this article.

The controller is present in this call stack, so let’s inspect the object instance by clicking on the this instance address, which is a shortcut for the !DumpObj command.

This instance contains a field named _request, which contained a field named requestUri, which has the original URI for this request:

That’s it! The commands vary slightly for dumping different field types.


.NET Core application on Linux

Required:

  • LLDB 3.9
  • Locally-built copy of the SOS plugin in the CoreCLR repo - instructions

In this next scenario, we’ll look at inspecting a core dump from a .NET Core app running on an Ubuntu x64 instance. The instance will have a core dump taken while a request is processing, which we will then inspect.

Take a core dump of the process using the createdump utility. These commands assume you have the coreclr repo checked out to ~/git/coreclr, and that you’re running an application built with .NET Core 2.0.

sudo ~/git/coreclr/bin/Product/Linux.x64.Debug/createdump -u (pid)

Load the dump in LLDB. This command also loads the SOS debugging extension.

lldb-3.9 dotnet -c /tmp/coredump.18842 -o "plugin load ~/git/coreclr/bin/Product/Linux.x64.Debug/libsosplugin.so"

After a few moments, a CLI will become available. Run eestack to dump the state of all CLR threads. If you get an empty output or a segmentation fault, verify that you are running the correct version of lldb and are loading libsosplugin from the bin directory, and that you have created the core dump with createdump.

eestack

There is an instance of HomeController in the stack of Thread 17. Switch to it to reveal more information about the current request. This time, we’ll inspect the state of an internal .NET Core request frame, since information about the current request isn’t as accessible as it was in ASP.NET MVC 5.

thread select 17
sos DumpStackObjects

Look for the address of Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http.Frame'1[[Microsoft.AspNetCore.Hosting.Internal.HostingApplication+Context, Microsoft.AspNetCore.Hosting]] in the output, and then dump the object. The name of this class might differ slightly based on the version of the framework you’re running.

Identify the QueryString field address:

Dumping that field reveals the query part of the URL the browser requested!


If debugging applications like this sounds interesting to you, join us! Thanks to Kyle Sletten, Justin Brooks, and Bradley Grainger for reviewing early drafts of this post.

Further reading:

Posted by Dustin Masters on January 09, 2018


Mitigating cross-site scripting with Content Security Policy

In this post, we’re going to look at using Content Security Policy (CSP) as a defense-in-depth technique to block script injection attacks.

When building website that hosts user-generated content, such as:

Great to be here!
<script>window.location='https://example.com'</script>

It’s necessary to encode user-generated content so that browsers don’t mistake it for markup, and execute an untrusted script. This is easy to do for plain text, but what if a page needs to render user-generated HTML? Here’s an example of HTML that contains inline Javascript, which browsers could execute:

<p>Great to <b>be</b> here!</p>
<img src="" onerror="alert(0)" />
<a href="javascript:alert(0)">Hi</a>
<script>window.location='https://example.com'</script>

This content must be sanitized before rendering. Libraries such as HTMLAgilityPack or DOMPurify provide a way to parse the HTML and strip out elements or attributes known to execute scripts.

Sanitization is important, but what if an attacker has discovered a way around the filter? This is where Content Security Policy comes in.

If the Content-Security-Policy header is present when retrieving the page, and contains a script-src definition, scripts will be blocked unless they match one of the sources specified in the policy. A policy might look something like:

script-src 'self'; object-src 'none'; base-uri 'none';

This policy disallows:

  • External scripts not hosted on the same domain as the current page.
  • Inline script elements, such as <script>
  • Evaluated Javascript, such as <img src="" onerror="alert(0)" />
  • Base elements, which could break scripts loaded from a relative path
  • Object elements, which can host interactive content, such as Flash

Whitelisting inline scripts

Sometimes it is necessary to run inline scripts on your page. In these cases, the nonce attribute on script elements can be used to whitelist scripts that you control.

<script nonce="00deadbeef">doSomething()</script>

A matching nonce must be present in the CSP for the script to run. For compatibility with older browsers, unsafe-inline allows scripts to run if the nonce tag is unsupported.

script-src 'self' 'nonce-00deadbeef' 'unsafe-inline'; object-src 'none'; base-uri 'none';

It is critical that this nonce is derived from a cryptographic random number generator so that an attacker can’t guess a future nonce. In .NET, RNGCryptoServiceProvider.GetBytes can be used to fill a 16 byte array:

using (var random = new RNGCryptoServiceProvider())
{
    byte[] nonce = new byte[16];
    random.GetBytes(nonce);
    return Convert.ToBase64String(nonce);
}

Whitelisting external scripts

strict-dynamic can be used to allow scripts hosted on a third-party domain to be loaded by scripts that you control. However, at the time of writing, this isn’t supported by all major browsers, so a host whitelist should be used as well as a fallback until it has broad support.

script-src 'self' 'nonce-00deadbeef' 'unsafe-inline' 'strict-dynamic' https://example.com; object-src 'none'; base-uri 'none';

When using strict-dynamic, you will also need to add a nonce to any external scripts that are referenced.

<script nonce="00deadbeef" src="https://example.com/analytics.js" />

Note:

Be careful what sources you whitelist. If any endpoints return JSONP and fail to sanitize the callback, it is possible to inject code. For example:

<script src="https://example.com/getuser?callback=window.location='http://google.com';test"></script>

Might return window.location='http://google.com';test({}) in the JSONP response, which would cause arbitrary code to be executed!

There are other policies that you can define to strengthen your site’s security, such as restricting where stylesheets are loaded from. This post only focuses on mitigating cross-site scripting attacks.

Further Reading

Thanks to Bradley Grainger and Kyle Sletten for reviewing this implementation.

Posted by Dustin Masters on December 21, 2017


‘in’ will make your code slower

Problem

The new in keyword (for parameters) in C# 7.2 promises to make code faster:

When you add the in modifier to pass an argument by reference, you declare your design intent is to pass arguments by reference to avoid unnecessary copying.

However, naïve use of this modifier will result in more copies (and slower code)!

This side-effect is implied by the MSDN documentation:

You can call any instance method that uses pass-by-value semantics. In those instances, a copy of the in parameter is created.

It’s also mentioned in passing in the readonly ref proposal:

After adding support for in parameters and ref redonly [sic] returns the problem of defensive copying will get worse since readonly variables will become more common.

Consider the example method from MSDN:

private static double CalculateDistance(in Point3D point1, in Point3D point2)
{
    double xDifference = point1.X - point2.X;
    double yDifference = point1.Y - point2.Y;
    double zDifference = point1.Z - point2.Z;

    return Math.Sqrt(xDifference * xDifference + yDifference * yDifference + zDifference * zDifference);
}

And assume this implementation of Point3D:

public struct Point3D
{
    public Point3D(double x, double y, double z)
    {
        X = x;
        Y = y;
        Z = z;
    }

    public double X { get; }
    public double Y { get; }
    public double Z { get; }
}

A number of C# features now combine in an unfortunate way:

  1. An in parameter is readonly
  2. Calling an instance method on a readonly struct makes a copy
    • Because the method might mutate this, a copy has to be made to ensure the readonly value isn’t modified
  3. Property accessors are instance methods

Every time a property on an in parameter is accessed in CalculateDistance, the compiler has to defensively create a temporary copy of the parameter. We’ve now gone from avoiding one copy per argument (at the call site) to three copies per argument (inside the method body)!

This is not a new problem; see Jon Skeet’s post on The Surprising Inefficiency of Readonly Fields. But using in makes it a much more common problem.

Solution

The solution is also in C# 7.2: readonly struct.

If we change public struct Point3D to public readonly struct Point3D (the implementation doesn’t have to change because all fields are already readonly), then the compiler knows it can elide the temporary copy inside the body of CalculateDistance. This makes the method faster than passing the structs by value.

Note that we could have achieved the same effect in C# 7.1 by passing the struct by ref. However, this allows the caller to mutate its fields (if it’s mutable) or reassign the entire variable to a new value. Using in expresses the intent that the caller will not modify the variable at all (and the compiler enforces that).

Demonstration

I’ve created a test harness that benchmarks the various combinations of in, ref, struct and readonly struct. (Note that I increased the struct size to 56 bytes to make the differences more obvious; smaller structs may not be impacted as much.) The full benchmark results are in that repo; the summary is:

Method Mean
PointByValue 25.09 ns
PointByRef 21.77 ns
PointByIn 34.59 ns
ReadOnlyPointByValue 25.29 ns
ReadOnlyPointByRef 21.78 ns
ReadOnlyPointByIn 21.79 ns

Summary

  • If you’re using in to express design intent (instead of ref), be aware that there may be a slight performance penalty when passing large structs.
  • If you’re using in to avoid copies and improve performance, only use it with readonly struct.

Posted by Bradley Grainger on December 07, 2017


MySQL Best Practices for .NET

We advise the following best practices for using MySQL Server with .NET code.

General Recommendations

Increase max_allowed_packet

The max_allowed_packet server variable controls the maximum size of a SQL statement that can be sent to the server, or the largest individual row that can be returned. Before MySQL 8.0, this defaulted to 4MiB, which is too small for many applications.

In MySQL 8.0, the new default is 64MiB; if you’re running an earlier server version you should set max_allowed_packet=64M (or higher).

Use MySqlConnector

MySqlConnector is a replacement ADO.NET connector library (with many contributions from Faithlife developers). It provides true async I/O, has better performance, and fixes many bugs in MySQL Connector/NET (aka MySql.Data).

Data Schema

Use COLLATE utf8mb4_bin

All text columns should use the utf8mb4 character set, as it allows the full range of Unicode to be stored. (See In MySQL, never use “utf8”. Use “utf8mb4”. for more details.)

By default, we prefer to use a binary collation:

  • It’s faster
  • It matches C# semantics: "a" != "A"
  • Many stored string values are IDs or tokens, which don’t need case-insensitive comparison

If you have human-readable textual data where you’re certain that you want the database to perform non-ordinal equality comparison and ordering, then consider using utf8mb4_0900_ai_ci (or decide if another collation is more appropriate for your use case).

Note: The default character set has changed from latin1 to utf8mb4 in MySQL 8.0.

Store bool as TINYINT(1)

In MySQL Server, BOOL is an alias for TINYINT(1). The MySQL ADO.NET connector understands this convention and will marshal TINYINT(1) back to managed code as the C# bool type (System.Boolean).

Use the BOOL alias when defining columns in your SQL statements. Do not use BIT(1) (which gets mapped as a ulong) to represent a Boolean value.

Avoid TINYINT(1)

As a corollary to the above, avoid explicitly using TINYINT(1). If you need a one-byte integer, use TINYINT (or TINYINT UNSIGNED). The (1) suffix simply indicates the “display width” (which is typically ignored by .NET programs), not the number of bytes used for storage.

Store Guid as CHAR(36)

To store a Guid, use CHAR(36) [NOT NULL] COLLATE ascii_general_ci.

The MySQL UUID() function returns a GUID in this format. The MySQL ADO.NET connector understands this convention and will marshal CHAR(36) back to managed code as the .NET Guid type.

The collation is ascii_general_ci because:

  • Using a one-byte-per-character character set allows MySQL to use fixed-length storage
  • Index prefix length limits are measured in bytes, not characters
  • Case-insensitive collation allows GUIDs to be queried using uppercase or lowercase hex digits

If you’re storing millions of GUIDs, you may wish to consider using BINARY(16) and performing custom data transfer. This will save 20 bytes per value, which may significantly reduce your data storage needs. Note that for a BINARY(16) column, MySqlDataReader.GetValue will return a byte[], but MySqlDataReader.GetGuid will reinterpret the value as a Guid.

Connection String Options

CharacterSet=utf8mb4

Uses Unicode when transferring queries to and results from the server, avoiding potential data loss from encoding errors.

Note: this option is utf8mb4 by default in MySqlConnector

ConnectionReset=True

With connection pooling on, but ConnectionReset=False, temporary tables and session variables from the last connection to the database will be retained. This is almost never what you want, and can lead to bugs.

Note: This option is True by default in MySqlConnector

SslMode=None

If you’re OK with the risk of traffic between your web server and MySQL server being intercepted and read, then setting SslMode=None will use just a plaintext TCP connection. This increases connection speed (less handshaking to set up the connection) and reduces overhead (of TLS encryption) when transmitting queries & results. The overhead ranges from 10% (reading thousands of small rows) to 500% (reading a few large BLOBs).

Note also that SslMode=Preferred or SslMode=Required doesn’t really increase security because a MITM attack can just replace the server’s certificate; you need to specify SslMode=VerifyCA or SslMode=VerifyFull to ensure a secure connection.

UseAffectedRows=True

Setting UseAffectedRows=True matches the default expectations of most ADO.NET programmers; for example, DbCommand.ExecuteNonQuery is documented in MSDN as returning “the number of rows affected”.

Note: This option is True by default in MySqlConnector

Posted by Bradley Grainger on October 30, 2017


Local Functions and Allocations

C# 7 introduces local functions. By default, the compiler generates very efficient code for local functions, even if the argument to the method is captured.

public int Function(int value)
{
    // Imagine this is a complicated implementation.
    // Note: this captures 'value' from the outer function.
    int Impl() => value + value;

    // perform argument validation (and early-out) here, then delegate to implementation
    return value == 0 ? 0 : Impl();
}

The decompiled C# compiler output is:

[CompilerGenerated]
[StructLayout(LayoutKind.Auto)]
private struct <>c__DisplayClass0_0
{
    public int value;
}

public int Function(int value)
{
    LocalFunctions.<>c__DisplayClass0_0 <>c__DisplayClass0_;
    <>c__DisplayClass0_.value = value;
    if (<>c__DisplayClass0_.value != 0)
        return LocalFunctions.<Function>g__Impl0_0(ref <>c__DisplayClass0_);
    return 0;
}

[CompilerGenerated]
internal static int <Function>g__Impl0_0(ref LocalFunctions.<>c__DisplayClass0_0 ptr)
{
    return ptr.value + ptr.value;
}

The struct incurs no allocations, and the JITter will inline the local function so it’s extremely efficient at runtime.

In order to hide the implementation in C# 6, you would have had to use a local Func (see decompiled code):

public int Function(int value)
{
    Func<int> Impl = () => value + value;

    return value == 0 ? 0 : Impl();
}

This would allocate an instance of a compiler-generated class and an instance of Func<int> whether or not Impl was actually invoked. The C# 7 code is much better. (Read more about local functions versus lambdas.)

However, there is an edge case in C# 7. If your local function would be implemented with a compiler-generated class (two examples I’ve found are iterator methods and async methods), then that class will always be allocated when the outer function is invoked, whether it’s used or not.

public IEnumerable<int> Function(int value)
{
    IEnumerable<int> Impl()
    {
        yield return value;
    }

    return value == 0 ? Enumerable.Empty<int>() : Impl();
}

The decompiled C# compiler output:

[CompilerGenerated]
private sealed class <>c__DisplayClass0_0
{
    // iterator state machine elided
}

public IEnumerable<int> Function(int value)
{
    LocalFunctions.<>c__DisplayClass0_0 <>c__DisplayClass0_ = new LocalFunctions.<>c__DisplayClass0_0();
    <>c__DisplayClass0_.value = value;
    if (<>c__DisplayClass0_.value != 0)
    {
        return <>c__DisplayClass0_.<Function>g__Impl0();
    }
    return Enumerable.Empty<int>();
}

If the “early out” condition is taken >90% of the time, and if this function is called frequently, you may wish to avoid the overhead of the unnecessary allocations of the compiler-generated class. Fortunately, there is a workaround: instead of implicitly capturing the outer function’s parameter, explicitly alias it:

public IEnumerable<int> Function(int value)
{
    IEnumerable<int> Impl(int value_)
    {
        yield return value_;
    }

    return value == 0 ? Enumerable.Empty<int>() : Impl(value);
}

The decompiled C# compiler output:

[CompilerGenerated]
private sealed class <<Function>g__Impl0_0>d : IEnumerable<int>, IEnumerable, IEnumerator<int>, IDisposable, IEnumerator
{
    // iterator state machine elided
}

public IEnumerable<int> Function(int value)
{
    if (value != 0)
        return LocalFunctions.<Function>g__Impl0_0(value);
    return Enumerable.Empty<int>();
}

[CompilerGenerated, IteratorStateMachine(typeof(LocalFunctions.<<Function>g__Impl0_0>d))]
internal static IEnumerable<int> <Function>g__Impl0_0(int value_)
{
    LocalFunctions.<<Function>g__Impl0_0>d expr_07 = new LocalFunctions.<<Function>g__Impl0_0>d(-2);
    expr_07.<>3__value_ = value_;
    return expr_07;
}

Now the “happy path” has zero allocations and the compiler-generated class is only instantiated if the local function is actually called.

I wouldn’t recommend doing this by default, but if profiling indicates that extra allocations are a problem, you may want to perform this refactoring to avoid them. I strongly recommend checking the compiled IL to ensure that you’ve solved it. If your outer function has many parameters or locals and (due to a typo) you inadvertently capture just one of them, then the optimization won’t kick in.

And note that in the typical “argument validation” use case for local functions, there’s no point in doing this because the outer function should call the local function 100% of the time. (The only reason it wouldn’t is if a boneheaded exception is thrown because the function was called incorrectly.) This refactoring is only useful if the local function ends up being called extremely infrequently.

I encountered a “real world” example of this issue in MySqlConnector. When I refactored the code to use local functions, I noticed an increase in allocations (and a decrease in performance). The solution was to avoid implicitly capturing local variables in the local functions.

In that specific scenario, the MySQL client library was reading bytes from a TCP socket. Most of the time, the bytes have already arrived and are in an OS buffer. Thus, we can immediately (and synchronously) return a ValueTask<int> containing the number of bytes copied into the caller’s buffer. Infrequently, we have to asynchronously wait on network I/O. Only then do we want the overhead of allocating the compiler-generated async state machine in order to return a (wrapped) Task<int> to the caller.

Posted by Bradley Grainger on August 02, 2017


Usage Guidelines for HttpClient

The HttpClient class is used in modern .NET applications to make HTTP requests. It was introduced in .NET 4.5 as a replacement for HttpWebRequest and WebClient.

This post collects some usage guidelines for HttpClient that may not be obvious.

Reuse HttpClient instances

Per MSDN, “HttpClient is intended to be instantiated once and re-used throughout the life of an application.” The rationale is mentioned in that MSDN article and described in detail in this blog post.

All HttpClient methods for making HTTP requests are thread-safe, so as long as you don’t change any of its properties (BaseAddress, DefaultRequestHeaders, Timeout, etc.) after you start making requests, reusing the same instance on any thread will be fine.

The simplest way to reuse HttpClient instances is to create a static readonly field in the class that needs to make HTTP requests. Of course, that still results in one instance per class, so consider allowing the HttpClient instance to be specified via constructor or method parameter.

HttpClient is disposable, but there’s no harm in never disposing it if it is used for the life of the application.

Example: The HttpClientService class of Facility.Core accepts an HttpClient instance in the constructor, but if it isn’t specified, it uses a static readonly instance that is never disposed.

Dispose HttpRequestMessage and HttpResponseMessage

The SendAsync method is the most flexible way to send an HTTP request with HttpClient. It accepts an HttpRequestMessage and returns an HttpResponseMessage. Note that both classes are disposable; be sure to dispose of instances of both classes when you are finished with them.

Example: FacilityCSharp has tests that run a number of HTTP requests in a row that POST a JSON body and process a JSON result. After a few dozen requests, HttpClient would asynchronously deadlock. I never got to the bottom of it, but I did find a solution: dispose the HTTP requests and responses.

Handle timeouts properly

When an HTTP request times out, an OperationCanceledException exception is thrown, not a TimeoutException.

The default timeout is 100 seconds. If you are using a single HttpClient instance (see above), you’ll want to make sure that HttpClient.Timeout is set as high as any request might need.

To use a shorter timeout for certain requests, use CancellationTokenSource.CancelAfter and send in the corresponding cancellation token. If you already have a cancellation token, use CancellationTokenSource.CreateLinkedTokenSource and call CancelAfter on that. If you need to distinguish between the two types of cancellation, check if the original cancellation token is cancelled.

Example: This StackOverflow answer demonstrates combining a cancellation token and a timeout.

Respect DNS changes

I haven’t attempted to reproduce this behavior, but apparently using a singleton HttpClient doesn’t respect DNS changes. For more information, read this article and this article.

Apparently you can use ServicePoint.ConnectionLeaseTimeout to work around this problem (see linked articles).

Aside: FacilityCSharp does not address this problem, but if you’re a Facility user and experience it, please file an issue and let us know!

Posted by Ed Ball on March 30, 2017


Async and Await in WPF

In our last video, we looked at using the async and await keywords in a console application. This week’s video uses async and await in a WPF application.

First we create a simple event handler using async and await. Then we simulate what happens behind-the-scenes with await by implementing the same behavior using continuation tasks. Just like await, we capture the SynchronizationContext and use the Post method to run the continuation on the UI thread.

Next we use DBpedia’s SPARQL endpoint to asynchronously execute a query against its structured data from Wikipedia. We then see what happens when an exception is thrown in an awaited task.

Stephen Toub has an excellent three-part article (2) (3) on await, SynchronizationContext and console apps.

Posted by Scott Fleischman on June 03, 2013