Feedback on initial work

[stroiman]

I'm starting to get the hang of Goja and seem to have a way forward for my ambitious project, a headless browser in Go.

I was hoping that I could get some feedback on the initial work, and the path I am following right now, if there are things I should do differently, or things that could be smarter.

I know this is a long write, and I open source maintainers get lots of request for help, so if this is beyond what you have time for, I fully respect that.

Requirements

As this should emulate a browser environment, all objects should have the right prototypes, the prototype chain should be correct, and the functions should exist as properties on the right object. E.g. document.getElementById is not an "own property" on the document, but exists on Document.prototype.getElementById; whereas document.location is an own property on the document.

Example, EventTarget and Window

In a browser environment, globalThis is the window object, which is an instance of Window, which inherits from EventTarget. You cannot create new instances of Window, but you can create new instances of EventTarget.

The native implementations follow a pattern like this:

type EventTarget interface {
	AddEventListener(...)
	RemoveEventListener(...)
	DispatchEvent(...)
}

type Window interface {
	EventTarget
	Document() Document
	...
}

They are implemented in unexported structs

type eventTarget struct {
	...
}

type window struct {
	eventTarget
	...
}

Creating prototypes

For each type in the code I create a ...Wrapper type. For the EventTarget where the JS code can create new instances, the constructor looks like this

type EventTargetWrapper struct {
	ctx *gojaContext // My own wrapper of the runtime, as well project specific context, like the native global Window.
}

func (w EventTargetWrapper) Constructor(call ConstructorCall) *Object {
	result := r.ToValue(dom.NewEventTarget()).(*Object)
	result.SetPrototype(call.This.Prototype())
	return result
}

The prototype chains are are setup like this:

eventTargetFunctionObject := vm.ToValue(EventTargetWrapper.Constructor).(*Object)
eventTargetPrototype := eventTargetFunctionObject.Get("prototype")
globalThis.Set("EventTarget", eventTargetFunctionObject)
windowFunctionObject, windowPrototype := // create just as eventtarget
windowPrototype.SetPrototype(eventTargetPrototype).

Handling method calls.

While Goja can automatically wrap Go objects, and forward calls, which is an amazing feature 👏, this doesn't seem like the right way for me. The functions should be defined on the prototype.

Here are two examples of functions on EventTarget, and how they are implemented. They use a GetInstance to extract the underlying native Go object.

func (w EventTargetWrapper) AddEventListener(c FunctionCall) Value {
	instance := w.GetInstance(c)
	name := c.Argument(0).String()
	instance.AddEventListener(name, NewGojaEventListener(w.instance, c.Argument(1)))
	return nil
}

func (w EventTargetWrapper) DispatchEvent(c FunctionCall) Value {
	vm := w.vm
	instance := w.GetInstance(c)
	if event, ok := c.Argument(0).Export().(dom.Event); ok {
		return vm.ToValue(instance.DispatchEvent(event))
	} else {
		panic(vm.NewTypeError("Not an event"))
	}
}

func (w EventTargetWrapper) InitializePrototype(prototype *Object) {
	prototype.Set("addEventListener", w.AddEventListener)
	prototype.Set("dispatchEvent", w.DispatchEvent)
}

Getting the underlying instance

The previous examples were somewhat simplified. I have a generic wrapper, so a common function can be used for all wrapper types, here the [T] is the native Go interface being wrapped.

One problem is that I need special handling for the window.

func (w GojaWrapper[T]) GetInstance(call FunctionCall) T {
	var instance any
	this := call.This
	if this == nil {
		// This really shouldn't happen? There should always be _a_ value for this.
		panic(w.vm.NewTypeError("No this pointer"))
	}
	if this == w.vm.GlobalObject() {
		instance = w.instance.window
	} else {
		instance = this.(*Object).Export()
	}
	if result, ok := instance.(T); ok {
		return result
	} else {
		panic(w.vm.NewTypeError("Not the right instance"))
	}
}

The problem is that the globalThis should is the window object, but since it is created for me, I cannot wrap a native object with ToValue, and I couldn't find a way to inject one after the fact?

Alternate solution

I was wondering is it made sense to create wrapper types for each instance,

type EventTargetInstanceWrapper struct {
	wrapped dom.EventTarget // dom is the package with native go objects
}

func (w EventTargetInstanceWrapper) AddEventListener(c FunctionCall) Value {
	w.wrapped.AddEventListener( ... convert arguments to wrapped values )
}

And then construct the instance wrapper in the constructor

func (w EventTargetWrapper) Constructor(call ConstructorCall) *Object {
	internalValue := EventTargetInstanceWrapper{dom.NewEventTarget())
	result := r.ToValue(internalValue).(*Object)
	result.SetPrototype(call.This.Prototype())
	return result
}

I was thinking the automatic wrapping of Go objects could be useful here. But then the functions would be "own properties" of the instance, not the prototype, as they should be

This might be a benefit for "own properties", but they seem to have to be defined using DefineAccessorProperty (unless mapping magic could set that up, e.g. based on tags on the wrapped go struct)

Question: Handling complex argument conversion

I was considering placing this as a separate question, as it does make sense on it's own (Let me know if I should).

XMLHttpRequest.prototype.send can accept a

• null
• Document
• XMLHttpRequestBodyInit, which cabn be a Blob, ArrayBuffer, and many more.

I was imagining that I could create a single type to handle parsing the body argument

type XmlHttpRequestBodyConvert struct {
}

func (x XmlHttpRequestBodyConvert) ToBody() dom.XMLHttpRequestBody { ... } 

func (w XHRWrapper) Send(c FunctionCall) Value {
  var bodyInit XmlHttpRequestBodyConvert
  vm.ExportTo(c.Argument(0), &bodyInit)
  body := bodyInit.ToBody()
  w.GetInstance(c).Send(body)
}

If the ExportTo supports e.g. an interface I could implement, I could wrap all logic of converting the possible input values in one simple place.

func (x XmlHttpRequestBodyConvert) OfGojaValue(v Value) {}

Is such a thing possible? Or are there other best practices for argument conversion?

Wrapper code is not a problem

There will be a lot of trivial wrapper code, but optimising for minimum wrapper code is not necessary from a code maintenance point of vies (but maybe from a build time point of view).

I have already setup for v8 that much of the wrapper code is generated based on information in IDL files from web specs. So once I have a sensible path forward, it's just a matter of making a new variant of the code generator targetting Goja.

[dop251]

See my comment here: #529 (comment)

This approach could be improved by using generics, but basically when implementing a JS library you should structure your code as you would in Javascript, rather than write a Go API and expose it to Javascript, if you know what I mean.

[stroiman]

Hey, thanks a lot, I really appreciate it :)

Something clicked there about the "extensibility" of wrapped structs, and the difference between wrapped an native object.

I will try storing the underlying Go object in a symbol property. I suppose this becomes visible in JS, which could have some security implications for some applications? It shouldn't be the case for the intended use of my project though.

fwiw, v8 has the idea of "internal fields", values you can assign to objects that are only accessible to the host application, not JS, and the specific intended use to store C++ object pointers.

[stroiman]

structure your code as you would in Javascript, rather than write a Go API

I totally get this, and I think with the realization that clicked now, I feel confident about the way forward. Shouldn't take long now before I have a native Go version up-to-date in supported functionality.