diff --git a/docs/modules/pkl-core/pages/index.adoc b/docs/modules/pkl-core/pages/index.adoc index 1d09e4f82f..0ce9dd7e7d 100644 --- a/docs/modules/pkl-core/pages/index.adoc +++ b/docs/modules/pkl-core/pages/index.adoc @@ -131,3 +131,174 @@ Module loaders can be configured and customized using {uri-pkl-core-ModuleKeyFac == Further Information Refer to the Javadoc and sources published with the library, or browse the library's {uri-pkl-core-main-sources}[main] and {uri-pkl-core-test-sources}[test] sources. + +== Experimental polyglot object and function access + +Pkl can be evaluated in a GraalVM polyglot context alongside other Truffle languages. +The result is a read-only view of the Pkl module, with lazy access to its properties. +For example, with compatible Pkl and GraalJS dependencies on the classpath: + +[source,java] +---- +try (var context = org.graalvm.polyglot.Context.newBuilder("js", "pkl") + .allowPolyglotAccess(org.graalvm.polyglot.PolyglotAccess.ALL) + .build()) { + var result = context.eval("js", """ + const config = Polyglot.eval('pkl', ` + name = "birds" + ports = List(8080, 8081) + `); + config.name + ':' + config.ports[0]; + """); + System.out.println(result.asString()); // birds:8080 +} +---- + +A Java host can also call `context.eval("pkl", source)` and use the returned +`org.graalvm.polyglot.Value` directly. +JavaScript uses GraalJS here; this does not add Pkl support to arbitrary Node.js or browser runtimes. + +[cols="1,2"] +|=== +|Pkl value |Interop representation + +|Boolean, String, Int, Float +|Native interop primitives. Int remains a signed 64-bit integer; a consuming language's numeric conversion rules still apply. + +|Null +|Interop null. + +|Module, Typed, Dynamic +|Readable public properties. Local and hidden properties are excluded, including from direct lookup. + +|List, Listing, Bytes +|Read-only arrays and iterables. Bytes expose unsigned integer elements. + +|Map, Mapping +|Read-only hash entries and entry iterators. Keys retain their types rather than being converted to strings. + +|Dynamic elements and entries +|Array (when elements are present) and hash protocols, respectively, in addition to named properties. + +|Set +|An iterable in Pkl iteration order. + +|Pair +|Readable `first` and `second` properties. + +|Duration, DataSize +|Readable `value` and `unit` properties, preserving the original unit. + +|Function-valued properties +|Executable closures. Arguments may be primitives or Pkl values belonging to the same context. + +|Other Pkl values +|Opaque Pkl values. Named Pkl method declarations and class instantiation are not yet exposed. +|=== + +Numeric hash-key lookup first tries the supplied numeric type. If no key matches, it tries the +other Pkl numeric type only when conversion is lossless. This accommodates languages such as +JavaScript whose numeric representations do not distinguish Pkl Int and Float reliably. + +Member enumeration does not evaluate property values. +Reading a property or element performs normal Pkl evaluation and type checking, and caches the result +according to Pkl's existing rules. Errors in unread properties remain deferred. +Object identity is preserved across repeated reads, including cyclic references; values are not +recursively copied or serialized. Debugger display strings do not force lazy values. +All views and iterators belong to their originating context and must be used before it is closed. + +The standalone polyglot entry point accepts supplied source text and standard-library imports. +It does not configure filesystem, network, package, environment, or external-property readers, +even when the host grants the polyglot context I/O access. +The existing `Evaluator` API retains its own configuration and behavior. +Each evaluation creates a new root module; source caching does not share root module values. + +=== Calling Pkl functions + +Function-valued properties can be read and executed, or invoked directly from a guest language. +For example, JavaScript in the context above can use: + +[source,javascript] +---- +const functions = Polyglot.eval('pkl', ` + greeting = (name: String) -> "Hello, " + name + describe = (data: Dynamic) -> data.name + ":" + data.port.toString() +`); +functions.greeting('Sam'); // "Hello, Sam" +---- + +A Java host uses `module.getMember("greeting").execute("Sam")`. +Calls use Pkl's normal call targets, preserving parameter constraints and declared return checks. +Arity errors and unsupported argument types are reported through the interop protocol; +Pkl evaluation errors retain their formatted diagnostics. +Returned objects remain lazy, read-only Pkl views. +Function-type annotations have the same semantics as within Pkl; interop does not strengthen them. + +Foreign objects and callbacks are rejected as direct arguments. Pkl objects and closures can be +passed back to functions in their owning context, but cannot be passed directly to a function in +a different context, even when both contexts share an engine. + +Capability queries do not evaluate properties. An unread property advertises deferred invocation +because its value might be a function. Calling it evaluates the property and reports a type error +if the value is not callable. Once the value is cached, invocation capability reflects its type. +This preserves lazy evaluation while allowing ordinary JavaScript method-call syntax. + +=== Explicit snapshots of foreign data + +Use `PolyglotContext.snapshot(context, foreignValue)` from Java to copy foreign data into +immutable Pkl values. The operation is also available as +`context.getBindings("pkl").getMember("snapshot")`. +To expose it to JavaScript, bind the Pkl scope once: + +[source,java] +---- +context.getBindings("js").putMember("Pkl", context.getBindings("pkl")); +---- + +[source,javascript] +---- +const source = {name: 'api', port: 8080}; +const saved = Pkl.snapshot(source); +source.port = 9999; +functions.describe(saved); // "api:8080" +---- + +Snapshots use the following mappings, in this order: + +* Null-like values, booleans, strings, and losslessly representable numbers become Pkl primitives. + Numbers fitting Int are represented as Int; other exactly representable numbers become Float. + GraalJS `undefined`, including readable sparse-array holes, becomes Pkl `null`. +* Arrays become List; additional named properties are not copied. +* Hash entries become Map, preserving key types and rejecting keys that collapse to the same Pkl key. +* Other iterables, including foreign sets, become List in iteration order. +* Objects with readable members become Dynamic using the enumerated member names. + +Repeated references within a snapshot preserve identity. Cycles are rejected with a path to the +cycle, as are foreign functions, constructors, known side-effecting accessors, unreadable values, +and numbers that cannot be represented without loss. Collection sizes and visited values are +limited to 100,000, and nesting depth to 256. A failed snapshot publishes no partial graph and does +not affect subsequent copies. Pkl values already belonging to the target context are reused +without forcing or copying. + +The source must remain stable while copying: a snapshot is not an atomic transaction over +concurrent mutations. Foreign iteration and proxy operations can execute guest code during the +explicit copy. After a successful copy, foreign mutation cannot change the captured data, and no +foreign object or callback is retained in that data. + +=== Independent engines and lifecycle + +Ordinary `Context.newBuilder(...)` and caller-supplied `Engine` instances are supported. +`PolyglotContext.newBuilder(...)` is a convenience alias for the ordinary builder. +Each Truffle language instance owns its standard-library modules, built-in classes, and factory +call targets. Contexts on compatible sharing layers of one engine reuse that state; independent +engines do not retain each other's executable nodes or prototypes. + +Contexts on different engines may use different host-access policies. Contexts sharing an engine +must still obey GraalVM's engine-sharing requirements. Closing one engine does not invalidate +values in another. A value, function, snapshot, or iterator must be used before its own context +is closed. + +The existing `Evaluator` API continues to use its internal shared engine. Standard-library +bootstrap uses fixed inputs and isolated type-checking state, without capturing the embedding +context's environment or external properties. Foreign mutation remains outside Pkl evaluation; +there is no implicit live import of objects or callbacks. diff --git a/pkl-core/pkl-core.gradle.kts b/pkl-core/pkl-core.gradle.kts index b9784263f9..62a8c62c66 100644 --- a/pkl-core/pkl-core.gradle.kts +++ b/pkl-core/pkl-core.gradle.kts @@ -64,7 +64,7 @@ dependencies { implementation(projects.pklFormatter) implementation(libs.msgpack) implementation(libs.truffleApi) - implementation(libs.graalSdk) + api(libs.graalSdk) implementation(libs.paguro) { exclude(group = "org.jetbrains", module = "annotations") } @@ -72,6 +72,7 @@ dependencies { testImplementation(projects.pklCommonsTest) testImplementation(libs.wiremock) + testRuntimeOnly(libs.graalJs) add("generatorImplementation", libs.javaPoet) add("generatorImplementation", libs.truffleApi) diff --git a/pkl-core/src/main/java/org/pkl/core/PolyglotContext.java b/pkl-core/src/main/java/org/pkl/core/PolyglotContext.java new file mode 100644 index 0000000000..18820ac0a1 --- /dev/null +++ b/pkl-core/src/main/java/org/pkl/core/PolyglotContext.java @@ -0,0 +1,47 @@ +/* + * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.pkl.core; + +import org.graalvm.polyglot.Context; +import org.graalvm.polyglot.Value; + +/** Convenience entry point for independent polyglot contexts supporting Pkl. */ +public final class PolyglotContext { + private PolyglotContext() {} + + /** + * Returns a standard polyglot context builder. Callers may supply their own engine and host + * access policy. An empty language list permits all installed languages. Cross-language + * evaluation additionally requires the builder's polyglot-access permission. + */ + public static Context.Builder newBuilder(String... permittedLanguages) { + return Context.newBuilder(permittedLanguages); + } + + /** + * Explicitly copies foreign data into immutable Pkl values owned by {@code context}. Objects + * become Dynamic, arrays/iterables become List, and hash entries become Map. Repeated references + * are preserved; cycles, foreign functions, known side-effecting accessors, lossy numbers, and + * graphs exceeding the snapshot limits are rejected. + * + *

The source must remain stable while copying. This is not an atomic transaction over a + * concurrently changing guest object. No foreign object is retained by a successful snapshot. Pkl + * values already belonging to the target context are returned without forcing or copying. + */ + public static Value snapshot(Context context, Object value) { + return context.getBindings("pkl").getMember("snapshot").execute(value); + } +} diff --git a/pkl-core/src/main/java/org/pkl/core/runtime/VmContext.java b/pkl-core/src/main/java/org/pkl/core/runtime/VmContext.java index d0824f41f3..64f901b4f7 100644 --- a/pkl-core/src/main/java/org/pkl/core/runtime/VmContext.java +++ b/pkl-core/src/main/java/org/pkl/core/runtime/VmContext.java @@ -19,12 +19,14 @@ import com.oracle.truffle.api.TruffleLanguage.Env; import com.oracle.truffle.api.instrumentation.Instrumenter; import com.oracle.truffle.api.nodes.Node; +import java.io.PrintWriter; import java.nio.file.Path; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.Objects; import java.util.function.Supplier; +import java.util.regex.Pattern; import org.jspecify.annotations.Nullable; import org.pkl.core.Logger; import org.pkl.core.Loggers; @@ -43,8 +45,11 @@ public final class VmContext { private static final ContextReference REFERENCE = ContextReference.create(VmLanguage.class); private final VmValueTrackerFactory valueTrackerFactory; + private final Env env; + final VmPolyglotScope polyglotScope = new VmPolyglotScope(this); public VmContext(VmLanguage vmLanguage, Env env) { + this.env = env; this.valueTrackerFactory = new VmValueTrackerFactory(env.lookup(Instrumenter.class), vmLanguage); } @@ -119,6 +124,32 @@ public void initialize(Holder holder) { this.holder = holder; } + /** Initializes standalone polyglot evaluation without ambient I/O capabilities. */ + void initializeForPolyglot() { + // The embedding Evaluator supplies its own holder before evaluating any source. + //noinspection ConstantValue + if (holder != null) return; + var securityManager = + SecurityManagers.standard( + List.of(Pattern.compile(".*")), List.of(), SecurityManagers.defaultTrustLevels, null); + initialize( + new Holder( + StackFrameTransformers.empty, + securityManager, + HttpClient.dummyClient(), + new ModuleResolver(List.of(ModuleKeyFactories.standardLibrary)), + new ResourceManager(securityManager, List.of()), + Loggers.writer(new PrintWriter(env.err(), true)), + Map.of(), + Map.of(), + null, + null, + null, + null, + TraceMode.COMPACT, + false)); + } + private Holder getHolder() { return Objects.requireNonNull(holder, "Pkl context is not initialized"); } diff --git a/pkl-core/src/main/java/org/pkl/core/runtime/VmForeignSnapshot.java b/pkl-core/src/main/java/org/pkl/core/runtime/VmForeignSnapshot.java new file mode 100644 index 0000000000..5f6ed3aee5 --- /dev/null +++ b/pkl-core/src/main/java/org/pkl/core/runtime/VmForeignSnapshot.java @@ -0,0 +1,180 @@ +/* + * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.pkl.core.runtime; + +import com.oracle.truffle.api.interop.*; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.HashSet; +import java.util.List; +import java.util.Map; +import org.jspecify.annotations.Nullable; + +/** One explicit, bounded copy operation. No foreign objects survive in the resulting graph. */ +final class VmForeignSnapshot { + private static final int MAX_DEPTH = 256; + private static final int MAX_VALUES = 100_000; + private final VmContext owner; + private final InteropLibrary interop = InteropLibrary.getUncached(); + private final Map> seen = new HashMap<>(); + private int values; + + VmForeignSnapshot(VmContext owner) { + this.owner = owner; + } + + static @Nullable Object primitive(Object value) { + var interop = InteropLibrary.getUncached(); + try { + if (interop.isNull(value)) return VmNull.withoutDefault(); + if (interop.isBoolean(value)) return interop.asBoolean(value); + if (interop.isString(value)) return interop.asString(value); + if (interop.fitsInLong(value)) return interop.asLong(value); + if (interop.fitsInDouble(value)) return interop.asDouble(value); + } catch (UnsupportedMessageException e) { + return null; + } + return null; + } + + Object copy(Object value) throws UnsupportedTypeException { + return copy(value, "$", 0); + } + + private Object copy(Object value, String path, int depth) throws UnsupportedTypeException { + if (++values > MAX_VALUES || depth > MAX_DEPTH) { + throw error(value, path, "Snapshot exceeds the depth (256) or value-count (100000) limit."); + } + if (value instanceof VmPolyglotValue wrapper) { + if (wrapper.owner != owner) throw error(value, path, "Pkl values belong to another context."); + return wrapper.value; + } + var primitive = primitive(value); + if (primitive != null) return primitive; + if (interop.isNumber(value)) + throw error(value, path, "Number cannot be represented losslessly by Pkl Int or Float."); + if (interop.isExecutable(value) || interop.isInstantiable(value)) { + throw error(value, path, "Functions and constructors cannot be snapshotted."); + } + try { + int hash = + interop.hasIdentity(value) + ? interop.identityHashCode(value) + : System.identityHashCode(value); + var bucket = seen.computeIfAbsent(hash, ignored -> new ArrayList<>()); + for (var memo : bucket) { + if (value == memo.original || interop.isIdentical(value, memo.original, interop)) { + if (memo.result == null) throw error(value, path, "Cycle refers to " + memo.path + "."); + return memo.result; + } + } + var memo = new Memo(value, path); + bucket.add(memo); + Object result; + if (interop.hasArrayElements(value)) { + long size = interop.getArraySize(value); + checkSize(value, path, size); + var elements = new Object[(int) size]; + for (int i = 0; i < size; i++) { + if (!interop.isArrayElementReadable(value, i)) + throw error(value, path + "[" + i + "]", "Sparse or unreadable array element."); + elements[i] = copy(interop.readArrayElement(value, i), path + "[" + i + "]", depth + 1); + } + result = VmList.create(elements); + } else if (interop.hasHashEntries(value)) { + checkSize(value, path, interop.getHashSize(value)); + var entries = interop.getHashEntriesIterator(value); + var builder = VmMap.builder(); + var keys = new HashSet(); + int index = 0; + while (interop.hasIteratorNextElement(entries)) { + if (index >= MAX_VALUES) throw error(value, path, "Too many map entries."); + var entry = interop.getIteratorNextElement(entries); + var key = + copy(interop.readArrayElement(entry, 0), path + ".key[" + index + "]", depth + 1); + if (!keys.add(key)) + throw error(value, path, "Distinct foreign map keys become equal Pkl keys."); + builder.add( + key, + copy(interop.readArrayElement(entry, 1), path + ".value[" + index + "]", depth + 1)); + index++; + } + result = builder.build(); + } else if (interop.hasIterator(value)) { + // The protocol cannot distinguish a foreign set from an arbitrary iterable. + var iterator = interop.getIterator(value); + var elements = new ArrayList(); + while (interop.hasIteratorNextElement(iterator)) { + elements.add( + copy( + interop.getIteratorNextElement(iterator), + path + "[" + elements.size() + "]", + depth + 1)); + } + result = VmList.create(elements); + } else if (interop.hasMembers(value)) { + var members = interop.getMembers(value, false); + long size = interop.getArraySize(members); + checkSize(value, path, size); + var builder = new VmObjectBuilder((int) size); + var names = new HashSet(); + for (long i = 0; i < size; i++) { + var name = interop.asString(interop.readArrayElement(members, i)); + var memberPath = path + "." + name; + if (!names.add(name)) throw error(value, memberPath, "Duplicate member name."); + if (!interop.isMemberReadable(value, name)) + throw error(value, memberPath, "Unreadable member."); + if (interop.hasMemberReadSideEffects(value, name)) + throw error( + value, memberPath, "Accessor properties must be materialized before snapshotting."); + builder.addProperty( + Identifier.get(name), copy(interop.readMember(value, name), memberPath, depth + 1)); + } + result = builder.toDynamic(); + } else { + throw error(value, path, "Unsupported foreign value."); + } + memo.result = result; + return result; + } catch (UnsupportedMessageException + | InvalidArrayIndexException + | UnknownIdentifierException + | StopIterationException e) { + throw error(value, path, "Foreign value changed or cannot be read: " + e.getMessage()); + } + } + + private static void checkSize(Object value, String path, long size) + throws UnsupportedTypeException { + if (size < 0 || size > MAX_VALUES) + throw error(value, path, "Collection exceeds the snapshot size limit."); + } + + private static UnsupportedTypeException error(Object value, String path, String message) { + return UnsupportedTypeException.create(new Object[] {value}, path + ": " + message); + } + + private static final class Memo { + final Object original; + final String path; + @Nullable Object result; + + Memo(Object original, String path) { + this.original = original; + this.path = path; + } + } +} diff --git a/pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java b/pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java index b74431a979..487fdf08a2 100644 --- a/pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java +++ b/pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java @@ -16,16 +16,20 @@ package org.pkl.core.runtime; import com.oracle.truffle.api.CallTarget; +import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary; import com.oracle.truffle.api.ContextThreadLocal; import com.oracle.truffle.api.TruffleLanguage; import com.oracle.truffle.api.TruffleLanguage.ContextPolicy; +import com.oracle.truffle.api.frame.VirtualFrame; import com.oracle.truffle.api.instrumentation.ProvidedTags; import com.oracle.truffle.api.nodes.Node; +import com.oracle.truffle.api.nodes.RootNode; import com.oracle.truffle.api.source.Source; import org.jspecify.annotations.Nullable; import org.pkl.core.ast.PklRootNode; import org.pkl.core.ast.builder.AstBuilder; import org.pkl.core.module.ModuleKey; +import org.pkl.core.module.ModuleKeys; import org.pkl.core.module.ResolvedModuleKey; import org.pkl.core.util.IoUtils; import org.pkl.parser.Parser; @@ -59,9 +63,32 @@ protected VmContext createContext(Env env) { return new VmContext(this, env); } + @Override + protected Object getScope(VmContext context) { + return context.polyglotScope; + } + @Override public CallTarget parse(ParsingRequest request) { - throw new UnsupportedOperationException("parse"); + if (!request.getArgumentNames().isEmpty()) { + throw new IllegalArgumentException("Pkl modules do not accept parse arguments."); + } + var source = request.getSource(); + var moduleKey = ModuleKeys.synthetic(source.getURI(), source.getCharacters().toString()); + return new RootNode(this) { + @Override + @TruffleBoundary + public Object execute(VirtualFrame frame) { + var context = VmContext.get(this); + context.initializeForPolyglot(); + return VmPolyglotValue.export(VmLanguage.get(this).loadModule(moduleKey)); + } + + @Override + public String getName() { + return source.getName(); + } + }.getCallTarget(); } public VmTyped loadModule(ModuleKey moduleKey) { diff --git a/pkl-core/src/main/java/org/pkl/core/runtime/VmPolyglotScope.java b/pkl-core/src/main/java/org/pkl/core/runtime/VmPolyglotScope.java new file mode 100644 index 0000000000..dee7ea8dbb --- /dev/null +++ b/pkl-core/src/main/java/org/pkl/core/runtime/VmPolyglotScope.java @@ -0,0 +1,106 @@ +/* + * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.pkl.core.runtime; + +import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary; +import com.oracle.truffle.api.interop.*; +import com.oracle.truffle.api.library.ExportLibrary; +import com.oracle.truffle.api.library.ExportMessage; + +/** Explicit data-import capabilities exposed through Context.getBindings("pkl"). */ +@ExportLibrary(InteropLibrary.class) +final class VmPolyglotScope implements TruffleObject { + private final Snapshot snapshot; + + VmPolyglotScope(VmContext context) { + snapshot = new Snapshot(context); + } + + @ExportMessage + boolean isScope() { + return true; + } + + @ExportMessage + boolean hasLanguageId() { + return true; + } + + @ExportMessage + String getLanguageId() { + return "pkl"; + } + + @ExportMessage + Object toDisplayString(@SuppressWarnings("unused") boolean allowSideEffects) { + return "Pkl bindings"; + } + + @ExportMessage + boolean hasMembers() { + return true; + } + + @ExportMessage + Object getMembers(@SuppressWarnings("unused") boolean includeInternal) { + return new VmPolyglotValue.Array(new Object[] {"snapshot"}); + } + + @ExportMessage + boolean isMemberReadable(String name) { + return name.equals("snapshot"); + } + + @ExportMessage + Object readMember(String name) throws UnknownIdentifierException { + if (!isMemberReadable(name)) throw UnknownIdentifierException.create(name); + return snapshot; + } + + @ExportMessage + boolean isMemberInvocable(String name) { + return name.equals("snapshot"); + } + + @ExportMessage + Object invokeMember(String name, Object[] arguments) + throws UnknownIdentifierException, ArityException, UnsupportedTypeException { + if (!isMemberInvocable(name)) throw UnknownIdentifierException.create(name); + return snapshot.execute(arguments); + } + + @ExportLibrary(InteropLibrary.class) + static final class Snapshot implements TruffleObject { + private final VmContext context; + + Snapshot(VmContext context) { + this.context = context; + } + + @ExportMessage + boolean isExecutable() { + return true; + } + + @ExportMessage + @TruffleBoundary + Object execute(Object[] arguments) throws ArityException, UnsupportedTypeException { + if (arguments.length != 1) throw ArityException.create(1, 1, arguments.length); + context.initializeForPolyglot(); + return VmPolyglotValue.export(new VmForeignSnapshot(context).copy(arguments[0])); + } + } +} diff --git a/pkl-core/src/main/java/org/pkl/core/runtime/VmPolyglotValue.java b/pkl-core/src/main/java/org/pkl/core/runtime/VmPolyglotValue.java new file mode 100644 index 0000000000..1bc2d6ddac --- /dev/null +++ b/pkl-core/src/main/java/org/pkl/core/runtime/VmPolyglotValue.java @@ -0,0 +1,505 @@ +/* + * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.pkl.core.runtime; + +import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary; +import com.oracle.truffle.api.interop.*; +import com.oracle.truffle.api.library.ExportLibrary; +import com.oracle.truffle.api.library.ExportMessage; +import com.oracle.truffle.api.nodes.IndirectCallNode; +import com.oracle.truffle.api.utilities.TriState; +import java.util.ArrayList; +import java.util.Iterator; +import java.util.List; +import org.jspecify.annotations.Nullable; +import org.pkl.core.runtime.VmObjectCursor.CursorOption; + +/** + * A read-only, lazy view of a Pkl value. The view never imports foreign state into evaluation. + * Wrappers use Pkl reference identity, without invoking structural equality or retaining a + * context-wide wrapper cache. All operations must run in the owning polyglot context. + */ +@ExportLibrary(InteropLibrary.class) +final class VmPolyglotValue implements TruffleObject { + final VmValue value; + final VmContext owner; + + private VmPolyglotValue(VmValue value) { + this.value = value; + this.owner = VmContext.get(null); + } + + static Object export(Object value) { + return value instanceof VmValue vmValue ? new VmPolyglotValue(vmValue) : value; + } + + @ExportMessage + boolean isExecutable() { + return value instanceof VmFunction; + } + + @ExportMessage + @TruffleBoundary + Object execute(Object[] arguments) + throws UnsupportedMessageException, ArityException, UnsupportedTypeException { + if (!(value instanceof VmFunction function)) throw UnsupportedMessageException.create(); + int count = function.getParameterCount(); + if (arguments.length != count) throw ArityException.create(count, count, arguments.length); + var args = new Object[count + 2]; + args[0] = function.getThisValue(); + args[1] = function; + for (int i = 0; i < count; i++) args[i + 2] = importArgument(arguments[i], owner); + try { + return export(function.getCallTarget().call(args)); + } catch (VmException e) { + throw new VmExceptionBuilder() + .adhocEvalError(e.toPklException(owner.getFrameTransformer(), false).getMessage()) + .withCause(e) + .build(); + } + } + + static Object importArgument(Object argument, VmContext owner) throws UnsupportedTypeException { + if (argument instanceof VmPolyglotValue wrapper) { + if (wrapper.owner == owner) return wrapper.value; + throw UnsupportedTypeException.create( + new Object[] {argument}, "Pkl values must belong to the calling context."); + } + var primitive = VmForeignSnapshot.primitive(argument); + if (primitive != null) return primitive; + throw UnsupportedTypeException.create( + new Object[] {argument}, + "Foreign objects and callbacks cannot be passed directly to Pkl. Use Pkl.snapshot(value) for data."); + } + + @ExportMessage + boolean hasLanguageId() { + return true; + } + + @ExportMessage + String getLanguageId() { + return "pkl"; + } + + @ExportMessage + boolean isNull() { + return value instanceof VmNull; + } + + @ExportMessage + @TruffleBoundary + Object toDisplayString(@SuppressWarnings("unused") boolean allowSideEffects) { + // Debugger previews must not force lazy properties, including when side effects are allowed. + return value instanceof VmNull ? "null" : "Pkl " + value.getVmClass().getSimpleName(); + } + + @ExportMessage + TriState isIdenticalOrUndefined(Object other) { + return other instanceof VmPolyglotValue wrapper + ? TriState.valueOf(owner == wrapper.owner && value == wrapper.value) + : TriState.UNDEFINED; + } + + @ExportMessage + int identityHashCode() { + return System.identityHashCode(value); + } + + @ExportMessage + boolean hasMembers() { + return value instanceof VmObject + || value instanceof VmPair + || value instanceof VmDuration + || value instanceof VmDataSize; + } + + @ExportMessage + @TruffleBoundary + Object getMembers(@SuppressWarnings("unused") boolean includeInternal) + throws UnsupportedMessageException { + if (!hasMembers()) throw UnsupportedMessageException.create(); + var names = new ArrayList(); + if (value instanceof VmObject object) { + for (var cursor = object.properties(CursorOption.LAZY_REQUIRED); cursor.advance(); ) { + names.add(cursor.key().toString()); + } + } else if (value instanceof VmPair) { + names.addAll(List.of("first", "second")); + } else { + names.addAll(List.of("value", "unit")); + } + return new Array(names.toArray()); + } + + @ExportMessage + @TruffleBoundary + boolean isMemberReadable(String name) { + if (value instanceof VmObject object) { + for (var cursor = object.properties(CursorOption.LAZY_REQUIRED); cursor.advance(); ) { + if (cursor.key().toString().equals(name)) return true; + } + return false; + } + if (value instanceof VmPair) return name.equals("first") || name.equals("second"); + return (value instanceof VmDuration || value instanceof VmDataSize) + && (name.equals("value") || name.equals("unit")); + } + + @ExportMessage + @TruffleBoundary + boolean hasMemberReadSideEffects(String name) { + return value instanceof VmObject object + && isMemberReadable(name) + && !object.hasCachedValue(Identifier.get(name)); + } + + @ExportMessage + @TruffleBoundary + boolean isMemberInvocable(String name) { + // An unread property can produce a function. Advertise a deferred invocation without + // evaluating it during capability discovery; invocation reports a type error if it is data. + if (!(value instanceof VmObject object) || !isMemberReadable(name)) return false; + var cached = object.getCachedValue(Identifier.get(name)); + return cached == null || cached instanceof VmFunction; + } + + @ExportMessage + @TruffleBoundary + Object invokeMember(String name, Object[] arguments) + throws UnsupportedMessageException, + UnknownIdentifierException, + ArityException, + UnsupportedTypeException { + boolean invocable = isMemberInvocable(name); + var member = readMember(name); + if (!(member instanceof VmPolyglotValue wrapper) || !wrapper.isExecutable()) { + if (invocable) + throw UnsupportedTypeException.create( + new Object[] {member}, "Pkl property '" + name + "' is not a function."); + throw UnknownIdentifierException.create(name); + } + return wrapper.execute(arguments); + } + + @ExportMessage + @TruffleBoundary + Object readMember(String name) throws UnknownIdentifierException, UnsupportedMessageException { + if (!hasMembers()) throw UnsupportedMessageException.create(); + if (value instanceof VmObject object) { + for (var cursor = object.properties(CursorOption.LAZY_REQUIRED); cursor.advance(); ) { + if (cursor.key().toString().equals(name)) { + return export(cursor.value(IndirectCallNode.getUncached())); + } + } + } else if (isMemberReadable(name)) { + if (value instanceof VmPair pair) { + return export(name.equals("first") ? pair.getFirst() : pair.getSecond()); + } + if (value instanceof VmDuration duration) { + return name.equals("value") ? duration.getValue() : duration.getUnit().toString(); + } + if (value instanceof VmDataSize size) { + return name.equals("value") ? size.getValue() : size.getUnit().toString(); + } + } + throw UnknownIdentifierException.create(name); + } + + @ExportMessage + boolean hasArrayElements() { + return value instanceof VmList + || value instanceof VmListing + || (value instanceof VmDynamic dynamic && dynamic.hasElements()) + || value instanceof VmBytes; + } + + @ExportMessage + @TruffleBoundary + long getArraySize() throws UnsupportedMessageException { + if (value instanceof VmList list) return list.getLength(); + if (value instanceof VmListing listing) return listing.getLength(); + if (value instanceof VmDynamic dynamic && dynamic.hasElements()) return dynamic.getLength(); + if (value instanceof VmBytes bytes) return bytes.getLength(); + throw UnsupportedMessageException.create(); + } + + @ExportMessage + @TruffleBoundary + boolean isArrayElementReadable(long index) { + try { + return hasArrayElements() && index >= 0 && index < getArraySize(); + } catch (UnsupportedMessageException e) { + return false; + } + } + + @ExportMessage + @TruffleBoundary + Object readArrayElement(long index) + throws InvalidArrayIndexException, UnsupportedMessageException { + if (!hasArrayElements()) throw UnsupportedMessageException.create(); + if (!isArrayElementReadable(index)) throw InvalidArrayIndexException.create(index); + if (value instanceof VmList list) return export(list.get(index)); + if (value instanceof VmBytes bytes) return bytes.get(index); + return export(VmUtils.readMember((VmObject) value, index)); + } + + @ExportMessage + boolean hasHashEntries() { + return value instanceof VmMap || value instanceof VmMapping || value instanceof VmDynamic; + } + + @ExportMessage + @TruffleBoundary + long getHashSize() throws UnsupportedMessageException { + if (value instanceof VmMap map) return map.getLength(); + if (value instanceof VmMapping mapping) return mapping.getLength(); + if (value instanceof VmDynamic dynamic) { + long size = 0; + for (var cursor = dynamic.entries(CursorOption.LAZY_REQUIRED); cursor.advance(); ) size++; + return size; + } + throw UnsupportedMessageException.create(); + } + + // A lookup key may be a primitive or a Pkl value returned through interop. Foreign objects + // are never coerced to Pkl objects. In particular, this does not stringify non-string keys. + private static @Nullable Object importKey(Object key) { + if (key instanceof VmPolyglotValue wrapper) { + return wrapper.owner == VmContext.get(null) ? wrapper.value : null; + } + if (key instanceof String + || key instanceof Boolean + || key instanceof Long + || key instanceof Double) { + return key; + } + var interop = InteropLibrary.getUncached(); + try { + if (interop.isNull(key)) return VmNull.withoutDefault(); + if (interop.isString(key)) return interop.asString(key); + if (interop.isBoolean(key)) return interop.asBoolean(key); + if (interop.fitsInLong(key)) return interop.asLong(key); + if (interop.fitsInDouble(key)) return interop.asDouble(key); + } catch (UnsupportedMessageException e) { + return null; + } + return null; + } + + // Languages such as JavaScript can represent an integral number as either an integer or a + // double. Prefer an exact key-type match, then try the other numeric type only without loss. + private static @Nullable Object alternateNumericKey(Object key) { + var interop = InteropLibrary.getUncached(); + try { + if (key instanceof Long && interop.fitsInDouble(key)) return interop.asDouble(key); + if (key instanceof Double && interop.fitsInLong(key)) return interop.asLong(key); + } catch (UnsupportedMessageException e) { + return null; + } + return null; + } + + private boolean containsKey(Object key) { + if (value instanceof VmMap map) return map.getOrNull(key) != null; + if (value instanceof VmMapping || value instanceof VmDynamic) { + for (var cursor = ((VmObject) value).entries(CursorOption.LAZY_REQUIRED); + cursor.advance(); ) { + if (cursor.key().equals(key)) return true; + } + } + return false; + } + + private @Nullable Object resolveKey(Object key) { + var pklKey = importKey(key); + if (pklKey == null) return null; + if (containsKey(pklKey)) return pklKey; + var alternate = alternateNumericKey(pklKey); + return alternate != null && containsKey(alternate) ? alternate : null; + } + + @ExportMessage + @TruffleBoundary + boolean isHashEntryReadable(Object key) { + return resolveKey(key) != null; + } + + @ExportMessage + @TruffleBoundary + Object readHashValue(Object key) throws UnknownKeyException, UnsupportedMessageException { + if (!hasHashEntries()) throw UnsupportedMessageException.create(); + var pklKey = resolveKey(key); + if (pklKey != null) { + if (value instanceof VmMap map) { + var result = map.getOrNull(pklKey); + assert result != null; + return export(result); + } + for (var cursor = ((VmObject) value).entries(CursorOption.LAZY_REQUIRED); + cursor.advance(); ) { + if (cursor.key().equals(pklKey)) + return export(cursor.value(IndirectCallNode.getUncached())); + } + } + throw UnknownKeyException.create(key); + } + + @ExportMessage + @TruffleBoundary + Object getHashEntriesIterator() throws UnsupportedMessageException { + if (value instanceof VmMap map) { + var iterator = map.iterator(); + return new ValueIterator( + new Iterator<>() { + public boolean hasNext() { + return iterator.hasNext(); + } + + public Object next() { + var entry = iterator.next(); + return new Array(new Object[] {export(entry.getKey()), export(entry.getValue())}); + } + }); + } + if (value instanceof VmMapping || value instanceof VmDynamic) { + var cursor = ((VmObject) value).entries(CursorOption.LAZY_REQUIRED); + return new ValueIterator( + new Iterator<>() { + private boolean ready; + private boolean done; + + public boolean hasNext() { + if (!ready && !done) { + ready = cursor.advance(); + done = !ready; + } + return ready; + } + + public Object next() { + if (!hasNext()) throw new java.util.NoSuchElementException(); + ready = false; + return new Array( + new Object[] { + export(cursor.key()), export(cursor.value(IndirectCallNode.getUncached())) + }); + } + }); + } + throw UnsupportedMessageException.create(); + } + + @ExportMessage + boolean hasIterator() { + return hasArrayElements() || value instanceof VmSet; + } + + @ExportMessage + @TruffleBoundary + Object getIterator() throws UnsupportedMessageException { + if (value instanceof VmSet set) { + var iterator = set.iterator(); + return new ValueIterator( + new Iterator<>() { + public boolean hasNext() { + return iterator.hasNext(); + } + + public Object next() { + return export(iterator.next()); + } + }); + } + if (!hasArrayElements()) throw UnsupportedMessageException.create(); + var size = getArraySize(); + return new ValueIterator( + new Iterator<>() { + private long index; + + public boolean hasNext() { + return index < size; + } + + public Object next() { + if (!hasNext()) throw new java.util.NoSuchElementException(); + try { + return readArrayElement(index++); + } catch (InvalidArrayIndexException | UnsupportedMessageException e) { + throw new AssertionError(e); + } + } + }); + } + + @ExportLibrary(InteropLibrary.class) + static final class Array implements TruffleObject { + private final Object[] elements; + + Array(Object[] elements) { + this.elements = elements; + } + + @ExportMessage + boolean hasArrayElements() { + return true; + } + + @ExportMessage + long getArraySize() { + return elements.length; + } + + @ExportMessage + boolean isArrayElementReadable(long index) { + return index >= 0 && index < elements.length; + } + + @ExportMessage + Object readArrayElement(long index) throws InvalidArrayIndexException { + if (!isArrayElementReadable(index)) throw InvalidArrayIndexException.create(index); + return elements[(int) index]; + } + } + + @ExportLibrary(InteropLibrary.class) + static final class ValueIterator implements TruffleObject { + private final Iterator iterator; + + ValueIterator(Iterator iterator) { + this.iterator = iterator; + } + + @ExportMessage + boolean isIterator() { + return true; + } + + @ExportMessage + @TruffleBoundary + boolean hasIteratorNextElement() { + return iterator.hasNext(); + } + + @ExportMessage + @TruffleBoundary + Object getIteratorNextElement() throws StopIterationException { + if (!iterator.hasNext()) throw StopIterationException.create(); + return iterator.next(); + } + } +} diff --git a/pkl-core/src/test/kotlin/org/pkl/core/PolyglotExecutionTest.kt b/pkl-core/src/test/kotlin/org/pkl/core/PolyglotExecutionTest.kt new file mode 100644 index 0000000000..42a87edee8 --- /dev/null +++ b/pkl-core/src/test/kotlin/org/pkl/core/PolyglotExecutionTest.kt @@ -0,0 +1,294 @@ +/* + * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.pkl.core + +import java.util.concurrent.Callable +import java.util.concurrent.Executors +import org.assertj.core.api.Assertions.assertThat +import org.graalvm.polyglot.Context +import org.graalvm.polyglot.Engine +import org.graalvm.polyglot.PolyglotAccess +import org.graalvm.polyglot.PolyglotException +import org.graalvm.polyglot.Source +import org.junit.jupiter.api.Test +import org.junit.jupiter.api.assertThrows + +class PolyglotExecutionTest { + private fun context() = + Context.newBuilder("js", "pkl").allowPolyglotAccess(PolyglotAccess.ALL).build() + + @Test + fun `functions execute with type checks closures objects and precise primitives`() { + context().use { context -> + val module = + context.eval( + "pkl", + """ + prefix = "Hello, " + greeting = (name: String) -> prefix + name + sum = (a: Int, b: Int) -> a + b + identity = (value) -> value + positive = (value: Int(isPositive)) -> value + make = (name: String) -> new Dynamic { value = name } + empty = () -> 42 + function wrong(value: Int): String = value + bad = (value) -> wrong(value) + """ + .trimIndent(), + ) + assertThat(module.getMember("greeting").canExecute()).isTrue() + assertThat(module.getMember("greeting").execute("Sam").asString()).isEqualTo("Hello, Sam") + assertThat(module.getMember("sum").execute(3, 4).asLong()).isEqualTo(7) + assertThat(module.getMember("identity").execute(9007199254740993L).asLong()) + .isEqualTo(9007199254740993L) + assertThat(module.getMember("identity").execute(null as Any?).isNull).isTrue() + assertThat(module.getMember("empty").execute().asInt()).isEqualTo(42) + val child = module.getMember("make").execute("bird") + assertThat(child.getMember("value").asString()).isEqualTo("bird") + assertThat(module.getMember("identity").execute(child)).isEqualTo(child) + assertThrows { module.getMember("sum").execute(1) } + assertThrows { module.getMember("sum").execute(1, 2, 3) } + val mismatch = assertThrows { module.getMember("sum").execute("wrong", 1) } + assertThat(mismatch.isInternalError).isFalse() + assertThat(mismatch.message).contains("Int", "String") + assertThrows { module.getMember("positive").execute(-1) } + assertThrows { module.getMember("bad").execute(1) } + val foreignObject = context.eval("js", "({name: 'bird'})") + val foreignFunction = context.eval("js", "(x) => x") + assertThrows { module.getMember("identity").execute(foreignObject) } + assertThrows { + module.getMember("identity").execute(foreignFunction) + } + } + } + + @Test + fun `JavaScript invokes Pkl functions and snapshots are isolated from later writes`() { + context().use { context -> + context.getBindings("js").putMember("Pkl", context.getBindings("pkl")) + val result = + context.eval( + "js", + """ + const functions = Polyglot.eval('pkl', ` + greeting = (name: String) -> "Hello, " + name + describe = (data: Dynamic) -> data.child.name + data.items[0].toString() + identity = (value) -> value + `); + const child = {name: 'bird'}; + const source = {child, alias: child, items: [7, 8], map: new Map([['bird', 2]])}; + const saved = Pkl.snapshot(source); + source.child.name = 'changed'; source.items[0] = 99; source.map.set('bird', 100); + [functions.greeting('Sam') === 'Hello, Sam', + functions.describe(saved) === 'bird7', + saved.child === saved.alias, + saved.map.get('bird') === 2, + functions.identity(saved) === saved, + (() => { try { saved.child.name = 'bad'; } catch (_) {} return saved.child.name === 'bird'; })() + ].every(Boolean); + """ + .trimIndent(), + ) + assertThat(result.asBoolean()).isTrue() + } + } + + @Test + fun `snapshot rejects cyclic graphs functions accessors and lossy numbers`() { + context().use { context -> + val snapshot = context.getBindings("pkl").getMember("snapshot") + for ((script, expected) in + listOf( + "(() => { let x = {}; x.self = x; return x; })()" to "Cycle", + "({callback: () => 1})" to "Functions", + "({get value() { throw Error('must not run'); }})" to "Accessor", + "18446744073709551617n" to "losslessly", + "new Map([[{x: 1}, 'a'], [{x: 1}, 'b']])" to "equal Pkl keys", + "(() => { let x = {}; for (let i = 0; i < 300; i++) x = {next: x}; return x; })()" to + "depth", + "new Array(100001).fill(1)" to "size limit", + )) { + val value = context.eval("js", script) + val error = assertThrows(script) { snapshot.execute(value) } + assertThat(error.message).contains(expected) + } + assertThrows { snapshot.execute() } + assertThrows { snapshot.execute(1, 2) } + // A failed copy never poisons subsequent snapshots or the evaluation context. + val recovered = snapshot.execute(context.eval("js", "({value: 42})")) + assertThat(recovered.getMember("value").asInt()).isEqualTo(42) + } + } + + @Test + fun `snapshot handles map keys null arrays and iterables without retaining guest objects`() { + context().use { context -> + val snapshot = context.getBindings("pkl").getMember("snapshot") + val result = + snapshot.execute( + context.eval( + "js", + """ + ({empty: {}, list: [null, true, 1.5, 'x'], sparse: [1, , 3], set: new Set([1, 2]), + map: new Map([[null, 'nil'], [true, 'yes'], [3, 'three']])}) + """ + .trimIndent(), + ) + ) + assertThat(result.getMember("empty").memberKeys).isEmpty() + assertThat(result.getMember("sparse").getArrayElement(1).isNull).isTrue() + assertThat(result.getMember("list").getArrayElement(0).isNull).isTrue() + assertThat(result.getMember("list").getArrayElement(1).asBoolean()).isTrue() + assertThat(result.getMember("list").getArrayElement(2).asDouble()).isEqualTo(1.5) + assertThat(result.getMember("set").arraySize).isEqualTo(2) + assertThat(result.getMember("map").getHashValue(null).asString()).isEqualTo("nil") + assertThat(result.getMember("map").getHashValue(true).asString()).isEqualTo("yes") + assertThat(result.getMember("map").getHashValue(3).asString()).isEqualTo("three") + } + } + + @Test + fun `Pkl arguments cannot bypass context ownership even on the same engine`() { + Engine.create().use { engine -> + Context.newBuilder("pkl").engine(engine).build().use { first -> + Context.newBuilder("pkl").engine(engine).build().use { second -> + val identity = first.eval("pkl", "identity = (value) -> value").getMember("identity") + val foreign = second.eval("pkl", "child = new Dynamic { n = 1 }").getMember("child") + assertThrows { identity.execute(foreign) } + } + } + } + } + + @Test + fun `snapshots do not retain a source context`() { + Context.create("pkl").use { target -> + val copied = + Context.create("js").use { source -> + PolyglotContext.snapshot(target, source.eval("js", "({child: {n: 7}, list: [1, 2]})")) + } + assertThat(copied.getMember("child").getMember("n").asInt()).isEqualTo(7) + assertThat(copied.getMember("list").getArrayElement(1).asInt()).isEqualTo(2) + val identity = + target.eval("pkl", "identity = (value: Dynamic) -> value").getMember("identity") + assertThat(identity.execute(copied)).isEqualTo(copied) + } + } + + @Test + fun `shared engine contexts initialize concurrently and remain isolated`() { + Engine.create().use { engine -> + val executor = Executors.newFixedThreadPool(3) + try { + val tasks = + (1..6).map { n -> + Callable { + Context.newBuilder("pkl").engine(engine).build().use { context -> + val module = + context.eval( + "pkl", + "import \"pkl:semver\"; v = semver.Version(\"1.2.3\"); n = $n", + ) + assertThat(module.getMember("v").getMember("minor").asInt()).isEqualTo(2) + assertThat(module.getMember("n").asInt()).isEqualTo(n) + } + } + } + for (future in executor.invokeAll(tasks)) future.get() + } finally { + executor.shutdownNow() + } + } + } + + @Test + fun `Java snapshot helper and invocation metadata preserve lazy evaluation`() { + context().use { context -> + val module = + context.eval( + "pkl", + """ + identity = (value) -> value + data = "not callable" + bad = throw("lazy") + """ + .trimIndent(), + ) + // Discovering invocation support must not evaluate the failing property. + assertThat(module.canInvokeMember("bad")).isTrue() + assertThat(module.canInvokeMember("identity")).isTrue() + val saved = PolyglotContext.snapshot(context, context.eval("js", "({name: 'bird'})")) + assertThat(module.invokeMember("identity", saved)).isEqualTo(saved) + assertThrows { module.invokeMember("data") } + assertThat(module.canInvokeMember("data")).isFalse() + assertThat(module.getMember("identity").execute(saved).getMember("name").asString()) + .isEqualTo("bird") + } + } + + @Test + fun `engine local standard libraries support independent parallel evaluation and shutdown`() { + val source = + Source.newBuilder( + "pkl", + """ + import "pkl:math" + import "pkl:reflect" + import "pkl:semver" + import "pkl:net" + n = math.sqrt(16) + pair = Pair(n, 5) + version = semver.Version("1.2.3") + url = net.Url("https://example.com/test") + reflection = reflect.Class(String).name + emptyDynamic = new Dynamic {} + emptyListing = new Listing {} + emptyMapping = new Mapping {} + identity = (value) -> value + """ + .trimIndent(), + "engines.pkl", + ) + .build() + val executor = Executors.newFixedThreadPool(3) + try { + val tasks = + (1..6).map { + Callable { + Context.create("pkl").use { context -> + val module = context.eval(source) + assertThat(module.getMember("pair").getMember("first").asDouble()).isEqualTo(4.0) + assertThat(module.getMember("version").getMember("major").asLong()).isEqualTo(1) + assertThat(module.getMember("url").getMember("rawHost").asString()) + .isEqualTo("example.com") + assertThat(module.getMember("reflection").asString()).isEqualTo("String") + val empty = module.getMember("emptyDynamic") + assertThat(module.getMember("identity").execute(empty)).isEqualTo(empty) + assertThat(module.getMember("emptyListing").arraySize).isZero() + assertThat(module.getMember("emptyMapping").hashSize).isZero() + } + } + } + for (future in executor.invokeAll(tasks)) future.get() + } finally { + executor.shutdownNow() + } + // Closing unrelated engines must not invalidate the original evaluator path. + Evaluator.preconfigured().use { evaluator -> + assertThat(evaluator.evaluate(ModuleSource.text("n = 1")).getProperty("n")).isEqualTo(1L) + } + } +} diff --git a/pkl-core/src/test/kotlin/org/pkl/core/PolyglotTest.kt b/pkl-core/src/test/kotlin/org/pkl/core/PolyglotTest.kt new file mode 100644 index 0000000000..b006cbe610 --- /dev/null +++ b/pkl-core/src/test/kotlin/org/pkl/core/PolyglotTest.kt @@ -0,0 +1,270 @@ +/* + * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.pkl.core + +import org.assertj.core.api.Assertions.assertThat +import org.graalvm.polyglot.Context +import org.graalvm.polyglot.PolyglotAccess +import org.graalvm.polyglot.PolyglotException +import org.graalvm.polyglot.Source +import org.graalvm.polyglot.io.IOAccess +import org.junit.jupiter.api.Test +import org.junit.jupiter.api.assertThrows + +class PolyglotTest { + @Test + fun `objects are lazy read only and preserve identity`() { + PolyglotContext.newBuilder("pkl").build().use { context -> + val module = + context.eval( + "pkl", + """ + local secret = 1 + hidden invisible = 2 + answer = 42 + child = new Dynamic { name = "bird" } + alias = child + self = this + bad = throw("not evaluated") + absent = null + """ + .trimIndent(), + ) + assertThat(module.memberKeys).contains("answer", "child", "alias", "self", "bad", "absent") + assertThat(module.memberKeys).doesNotContain("secret", "invisible") + assertThat(module.hasMember("secret")).isFalse() + assertThat(module.hasMember("invisible")).isFalse() + assertThat(module.getMember("missing")).isNull() + assertThat(module.getMember("answer").asLong()).isEqualTo(42) + assertThat(module.getMember("child").getMember("name").asString()).isEqualTo("bird") + assertThat(module.getMember("child")).isEqualTo(module.getMember("alias")) + assertThat(module.getMember("self")).isEqualTo(module) + assertThat(module.getMember("absent").isNull).isTrue() + assertThat(module.toString()).contains("Pkl") + assertThrows { module.putMember("answer", 7) } + assertThrows { module.removeMember("answer") } + assertThat(module.getMember("answer").asLong()).isEqualTo(42) + val error = assertThrows { module.getMember("bad") } + assertThat(error.isGuestException).isTrue() + assertThat(error.isInternalError).isFalse() + } + } + + @Test + fun `collections retain distinct elements entries and properties`() { + PolyglotContext.newBuilder("pkl").build().use { context -> + val module = + context.eval( + "pkl", + """ + list = List(1, 2, new Dynamic { name = "bird" }) + listing = new Listing { 3; 4 } + mapping = new Mapping { ["key"] = 5; [42] = null } + map = Map("key", 6, 42, "number") + set = Set(1, 2, 1) + mixed = new Dynamic { title = "mixed"; 7; ["key"] = 8 } + duration = 3.ms + size = 2.kib + pair = Pair("a", 9) + """ + .trimIndent(), + ) + val list = module.getMember("list") + assertThat(list.arraySize).isEqualTo(3) + assertThat(list.getArrayElement(2).getMember("name").asString()).isEqualTo("bird") + assertThrows { list.getArrayElement(-1) } + assertThrows { list.getArrayElement(3) } + assertThrows { list.setArrayElement(0, 9) } + assertThat(module.getMember("listing").getArrayElement(1).asLong()).isEqualTo(4) + val mapping = module.getMember("mapping") + assertThat(mapping.hashSize).isEqualTo(2) + assertThat(mapping.getHashValue("key").asLong()).isEqualTo(5) + assertThat(mapping.getHashValue(42).isNull).isTrue() + assertThat(mapping.hasHashEntry("missing")).isFalse() + assertThrows { mapping.putHashEntry("key", 9) } + val map = module.getMember("map") + assertThat(map.getHashValue(42).asString()).isEqualTo("number") + val entries = map.hashEntriesIterator + assertThat(entries.iteratorNextElement.getArrayElement(0).asString()).isEqualTo("key") + assertThat(entries.iteratorNextElement.getArrayElement(1).asString()).isEqualTo("number") + assertThat(entries.hasIteratorNextElement()).isFalse() + val set = module.getMember("set").iterator + assertThat(set.iteratorNextElement.asLong()).isEqualTo(1) + assertThat(set.iteratorNextElement.asLong()).isEqualTo(2) + assertThat(set.hasIteratorNextElement()).isFalse() + val mixed = module.getMember("mixed") + assertThat(mixed.getMember("title").asString()).isEqualTo("mixed") + assertThat(mixed.getArrayElement(0).asLong()).isEqualTo(7) + assertThat(mixed.getHashValue("key").asLong()).isEqualTo(8) + assertThat(mixed.hashSize).isEqualTo(1) + assertThat(module.getMember("duration").getMember("unit").asString()).isEqualTo("ms") + assertThat(module.getMember("size").getMember("value").asDouble()).isEqualTo(2.0) + assertThat(module.getMember("pair").getMember("second").asLong()).isEqualTo(9) + } + } + + @Test + fun `hash keys retain types and exact numeric values`() { + PolyglotContext.newBuilder("pkl").build().use { context -> + val module = + context.eval( + "pkl", + """ + key = new Dynamic { name = "key" } + map = Map(key, "object", null, "null", true, "boolean", 1.5, "float", 9007199254740993, "large") + large = 9007199254740993 + """ + .trimIndent(), + ) + val map = module.getMember("map") + assertThat(map.getHashValue(module.getMember("key")).asString()).isEqualTo("object") + assertThat(map.getHashValue(null).asString()).isEqualTo("null") + assertThat(map.getHashValue(true).asString()).isEqualTo("boolean") + assertThat(map.getHashValue(1.5).asString()).isEqualTo("float") + assertThat(map.getHashValue(9007199254740993L).asString()).isEqualTo("large") + assertThat(module.getMember("large").asLong()).isEqualTo(9007199254740993L) + assertThat(map.hasHashEntry("true")).isFalse() + val entries = map.hashEntriesIterator + while (entries.hasIteratorNextElement()) { + val entry = entries.iteratorNextElement + assertThat(map.getHashValue(entry.getArrayElement(0))).isEqualTo(entry.getArrayElement(1)) + } + } + } + + @Test + fun `reads retain type constraints and enumeration does not force values`() { + PolyglotContext.newBuilder("pkl").build().use { context -> + val module = + context.eval( + "pkl", + """ + good = 1 + bad: Int = "wrong" + listing: Listing = new { "wrong" } + mapping = new Mapping { ["good"] = 1; ["bad"] = throw("lazy") } + """ + .trimIndent(), + ) + assertThat(module.memberKeys).contains("bad") + assertThat(module.getMember("good").asInt()).isEqualTo(1) + assertThrows { module.getMember("bad") } + val listing = module.getMember("listing") + assertThat(listing.arraySize).isEqualTo(1) + assertThrows { listing.getArrayElement(0) } + val mapping = module.getMember("mapping") + assertThat(mapping.hashSize).isEqualTo(2) + assertThat(mapping.hasHashEntry("bad")).isTrue() + assertThat(mapping.getHashValue("good").asInt()).isEqualTo(1) + assertThrows { mapping.getHashValue("bad") } + } + } + + @Test + fun `source caching does not reuse module instances across evaluations or contexts`() { + val source = Source.newBuilder("pkl", "child = new Dynamic { n = 1 }", "test.pkl").build() + PolyglotContext.newBuilder("pkl").build().use { first -> + val a = first.eval(source) + val b = first.eval(source) + assertThat(a).isNotEqualTo(b) + assertThat(a.getMember("child").getMember("n").asInt()).isEqualTo(1) + PolyglotContext.newBuilder("pkl").build().use { second -> + assertThat(second.eval(source).getMember("child").getMember("n").asInt()).isEqualTo(1) + } + assertThat(a.getMember("child").getMember("n").asInt()).isEqualTo(1) + } + } + + @Test + fun `independent engines support stdlib calls and different host access policies`() { + Context.newBuilder("pkl").allowAllAccess(true).build().use { first -> + Context.create("pkl").use { second -> + for (context in listOf(first, second, first)) { + val module = context.eval("pkl", "import \"pkl:math\"; pair = Pair(math.sqrt(9), 2)") + assertThat(module.getMember("pair").getMember("first").asDouble()).isEqualTo(3.0) + } + } + assertThat(first.eval("pkl", "n = List(1, 2).length").getMember("n").asInt()).isEqualTo(2) + } + } + + @Test + fun `values cannot be used after context close`() { + val context = PolyglotContext.newBuilder("pkl").build() + val module = context.eval("pkl", "n = 1") + context.close() + assertThrows { module.getMember("n") } + } + + @Test + fun `standalone evaluation allows stdlib but does not inherit ambient IO`() { + PolyglotContext.newBuilder("pkl").allowIO(IOAccess.ALL).build().use { context -> + assertThat( + context.eval("pkl", "import \"pkl:math\"; n = math.sqrt(9)").getMember("n").asDouble() + ) + .isEqualTo(3.0) + for (source in + listOf( + "import \"file:/etc/passwd\"; n = 1", + "import \"https://example.com/module.pkl\"; n = 1", + "n = read(\"env:HOME\")", + "n = read(\"file:/etc/passwd\")", + )) { + assertThrows { context.eval("pkl", source).getMember("n") } + } + } + } + + @Test + fun `JavaScript can evaluate and consume Pkl objects without a conversion layer`() { + PolyglotContext.newBuilder("js", "pkl").allowPolyglotAccess(PolyglotAccess.ALL).build().use { + context -> + val result = + context.eval( + "js", + """ + const config = Polyglot.eval('pkl', ` + title = "birds" + nested = new Dynamic { count = 2 } + alias = nested + values = List(3, 4) + lookup = Map("bird", "owl", 10000000000, "large", 1.0, "float") + unique = Set(3, 4, 3) + absent = null + broken = throw("lazy") + `); + const keys = Object.keys(config); + [config.title === 'birds', + config.nested.count === 2, + config.nested === config.alias, + config.values[0] + config.values[1] === 7, + Array.from(config.values).join(',') === '3,4', + config.absent == null, + config.lookup.get('bird') === 'owl', + config.lookup.get(10000000000) === 'large', + config.lookup.get(1) === 'float', + JSON.stringify(config.nested) === '{"count":2}', + Array.from(config.unique).join(',') === '3,4', + keys.includes('broken'), + (() => { try { config.title = 'changed'; } catch (_) {} return config.title === 'birds'; })() + ].every(Boolean); + """ + .trimIndent(), + ) + assertThat(result.asBoolean()).isTrue() + } + } +}