External function runtime checks

[lpil]

External functions are the main area in Gleam where the compiler is unable to help you catch mistakes; Any time you are writing external functions you just have to make sure that you are using the correct runtime values for the types you have specified the functions takes and receives. This often results in mistakes.

To help with this we when an external function is defined we could generate code that checks they are correct at runtime.

@external(erlang, "wibble", "wobble")
@external(javascript, "wibble", "wobble")
pub thingy(id: Int, name: String, items: List(String)) -> Float

thingy(Id, Name, Items) ->
    if
        not erlang:is_integer(Id) -> erlang:error(id is not an int);
        not erlang:is_binary(Name) -> erlang:error(name is not a binary);
        not erlang:is_list(Items) -> erlang:error(items is not a list);
        true -> ok
    end,
    case wibble:wobble(Id, Name, Items) of
        Return when erlang:is_float(Return) -> Return;
        Return -> erlang:error(return is not a float)
    end.

export function thingy(id, name, list) {
  if (!Number.isInteger(id)) throw id is not an int;
  if (typeof name !== "string") throw name is not a string;
  if (!$isList(items)) throw items is not a list;
  const return_ = wibble.wobble(id, name);
  if (typeof return_ !== "number") throw return is not an float;
  return return_;
}

Traversing lists each time they go through FFI would be expensive, so the list is only checked shallowly.

This example uses prelude types, but custom types could be checked too. The depth to which they should be checked I am unsure of. Perhaps it could traverse through any nested custom types with only a single variant, as those values cannot be recursive and so have a constant size.

External types have unknown runtime representation, so it is impossible to generate checks for them.

I thought these checks would be useful for catching mistakes in development and in tests, but wouldn't be desired in production due to their (slight) runtime cost and increase in code size. To control this would could expose the production compile mode in the tooling's public API by adding a --production or such flag to gleam run and gleam build. gleam export would continue to use production mode, and gleam dev and gleam test would continue to use dev mode.

What do you think?

[hayleigh-dot-dev]

I'm a little unclear what this is protecting me from or what problem this is intended to solve. It looks like these runtime checks would only save me in instances where both the following are true:

• i have an external function declared in gleam
• i call that external function from outside of gleam

To take the example already given:

// example.gleam

@external(erlang, "wibble", "wobble")
@external(javascript, "wibble", "wobble")
pub thingy(id: Int, name: String, items: List(String)) -> Nil

This external function has annotated types – as it must for externals in Gleam. That means I cannot, in my gleam code, call:

thing("hello", -123.4, <<>>)

So the proposed runtime checks would only help me prevent mistakes when i do something like:

// whoopsie.mjs

import { thingy } from './example.mjs'

// proposed runtime checks could catch this.
thing("hello")

This seems like an incredibly niche case. I can see a stronger argument for all public functions having these runtime checks in a development mode, but limiting it to just externals seems far too specific to be useful.

[hayleigh-dot-dev]

Could you give a clearer example of when this is helpful? In your example above I don't see how it's possible to call thingy in gleam with anything other than Int, String, and List(String) arguments as that is the type of the function.

How would I, for example, call thingy with a Float instead to trigger this runtime error?

[lpil]

Ah! I understand now! Sorry I messed up my examples, I forgot to add the return type check. I will correct that now.

[GearsDatapacks]

Oh yes you're right, I hadn't thought enough about how this would work. We could check that the return type of the called function is correct, but I can't see an easy way to verify parameters, given Erlang and JavaScript are dynamically typed languages.

[lpil]

Thinking more about this, perhaps the checks for the arguments are rather pointless compared to the checks of the return value?

[GearsDatapacks]

Checks of the arguments are already performed by the static analysis of the compiler. What we would really want is something that checked the Gleam programmers's annotations against what the JS/Erlang code expects, though that is likely impossible.

[GearsDatapacks]

One thing I often want to do with a library or application is to benchmark various approaches to see how I can improve performance. I would usually do this by writing some code in a test or dev module.

If we always enabled development mode for test and dev, this would lead to misleading benchmarks due to the additional FFI checks. I suppose we would want to have some way to enable production mode for this purpose, to get a more accurate representation of code speed in the production environment.

Also you didn't mention this explicitly, but I assume gleam publish would also use production mode.

[lpil]

Code inside test/ and dev/ can (and often is) be run with gleam run, so they can use the production mode flag. We could also add the flag to gleam test and gleam dev if we think that is useful in future.

When I said it's enabled for gleam dev and gleam test I only mean those two commands, it would not extend that to any code inside dev/ and test/, regardless of the command use to run them.

Internally we likely would need to rework the build tool a little, so that dev and test can be compiled in the production mode.

Also you didn't mention this explicitly, but I assume gleam publish would also use production mode.

Yup, same as today

gleam/compiler-cli/src/publish.rs

Lines 446 to 458 in e8eb002

	let built = build::main(
	paths,
	Options {
	root_target_support: TargetSupport::Enforced,
	warnings_as_errors: false,
	mode: Mode::Prod,
	target: Some(target),
	codegen: Codegen::All,
	compile: Compile::All,
	no_print_progress: false,
	},
	manifest,
	)?;