JS application integration questions

[bsenthilr]

Trying to do a POC of porting a C++ application to JS. Managed to port most of the application logic and test it out on virtual enclave based on JS generics & ACL on Azure.
Can someone please clarify the following queries:

• The quickJS cannot include nodejs module. Assuming the polyfill mechanism is used to support crypto helpers. Require MDType::SHA384 hashing for signature verification and support for JWT token validation & decoding. This polyfill wrapper js_verify_signature seems to only support 256. Is this understanding right? What are other alternate recommended options?

• C++ application model comprised of a ccf::kv::Tx and KV where accessed via Tx. JS seems to be simpler and there is no notion of Kv::Tx. If this is the case how to account for global commits? Does forwarding primitives such as "always" etc., implicitly enforce this rule? Or does JS KV always goes through consensus due to sandboxing?
  On the same note are readonly/write primitives intended to determine access violations provided there is no notion of Tx in JS? Seems the checks where not enforced.

• Is there a way to enable JS application exception trace to quickly root cause 500 errors for development? This would save tons of time.

• The local virtual mode governor based on JS generic is extremely slow. It takes several magnitudes of seconds to execute an endpoint. Is this expected and how do we increase the performance? This is important for pytests/regression pipelines. The ACL version is reasonable in performance although not quantified it against C++ app.

Thanks

[achamayou]

The quickJS cannot include nodejs module. Assuming the polyfill mechanism is used to support crypto helpers. Require MDType::SHA384 hashing for signature verification and support for JWT token validation & decoding. This polyfill wrapper js_verify_signature seems to only support 256. Is this understanding right? What are other alternate recommended options?

You can import some packages from npm, so long as they do not require nodejs APIs, which are not implemented in CCF. For an example of what can be used, see https://github.com/microsoft/azure-privacy-sandbox-kms/blob/main/package.json

The polyfill.js is intended to be used outside of CCF, for unit tests. See https://microsoft.github.io/CCF/main/js/ccf-app/modules/global.html for what is available in CCF. ccfapp.crypto implements some of WebCrypto, but if functionality is missing, you can request it/propose it in a PR.

C++ application model comprised of a ccf::kv::Tx and KV where accessed via Tx. JS seems to be simpler and there is no notion of Kv::Tx. If this is the case how to account for global commits? Does forwarding primitives such as "always" etc., implicitly enforce this rule? Or does JS KV always goes through consensus due to sandboxing?

JS handlers also get a Tx, which is exposed through ccfapp.kv. I am not sure what you mean by accounting for global commits. In both C++ and JS, CCF attempts to commit the Tx locally after the user handler returns, and then globally. Handlers have no control over this process, regardless of the language they are implemented in. A way to think about JS apps is that they are sub-category of C++ apps that start by creating (or fetching) a JS runtime, getting the relevant JS code from the KV, and handing it the Tx object to execute. There is no difference wrt commit, forwarding etc.

On the same note are readonly/write primitives intended to determine access violations provided there is no notion of Tx in JS? Seems the checks where not enforced.

There is effectively a global Tx for the duration of the handler in JS. This is true in C++ too. It is not the case that the handlers can create and commit additional Tx objects. Checks not being enforced sounds like a bug, can you provide more detail?

Is there a way to enable JS application exception trace to quickly root cause 500 errors for development? This would save tons of time.

Yes, see options ending in "_details" under https://microsoft.github.io/CCF/main/governance/js_runtime.html#javascript-runtime-options

The local virtual mode governor based on JS generic is extremely slow. It takes several magnitudes of seconds to execute an endpoint. Is this expected and how do we increase the performance? This is important for pytests/regression pipelines. The ACL version is reasonable in performance although not quantified it against C++ app.

I am not sure what the local virtual mode governor is. One of the things that will impact commit time is the signature interval (see ledger_signatures.delay in https://microsoft.github.io/CCF/main/operations/configuration.html#configuration). Can you share more detail about what you are doing and experiencing?

[bsenthilr]

Thanks a lot @achamayou

You can import some packages from npm, so long as they do not require nodejs APIs, which are not implemented in CCF. For an example of what can be used, see https://github.com/microsoft/azure-privacy-sandbox-kms/blob/main/package.json
The polyfill.js is intended to be used outside of CCF, for unit tests. See https://microsoft.github.io/CCF/main/js/ccf-app/modules/global.html for what is available in CCF. ccfapp.crypto implements some of WebCrypto, but if functionality is missing, you can request it/propose it in a PR.

Thanks for confirming will review this and give a shot. But for security reasons it would be ideal to leverage production crypto under covers. This would not pass our security review. Any thoughts regarding this?
Is the polyfill code not intended for application consumption ? Thought that source is bound on the baseline via wrappers. Polyfill uses openssl via cpp which will be a safer bet. If its reasonable to leverage it can open a PR for the updates required.

JS handlers also get a Tx, which is exposed through ccfapp.kv. I am not sure what you mean by accounting for global commits. In both C++ and JS, CCF attempts to commit the Tx locally after the user handler returns, and then globally. Handlers have no control over this process, regardless of the language they are implemented in. A way to think about JS apps is that they are sub-category of C++ apps that start by creating (or fetching) a JS runtime, getting the relevant JS code from the KV, and handing it the Tx object to execute. There is no difference wrt commit, forwarding etc.

Sorry for the confusion and thanks for clarifying the design.
Our current application leverages Global commit during read path on some logic. How do we achieve the same on JS?
The C++ application also uses ccf::endpoints::EndpointContext::tx and enforces read/write safety. Assumed JS does not have similar precise controls to access ccf. Is it possible to achieve similar workflow with JS?

Yes, see options ending in "_details" under https://microsoft.github.io/CCF/main/governance/js_runtime.html#javascript-runtime-options

Thanks will try out the option.

I am not sure what the local virtual mode governor is. One of the things that will impact commit time is the signature interval (see ledger_signatures.delay in https://microsoft.github.io/CCF/main/operations/configuration.html#configuration). Can you share more detail about what you are doing and experiencing?

For testing the app on local VM, start the governor will following command line

${CCHOST} --config ${CCHOST_CONFIG} --enclave-file /opt/ccf_virtual/lib/libjs_generic.virtual.so &
fi

The endpoints functions but it runs several magnitudes slower than cpp counter part. Does this require any adjustments to some resource settings?

[achamayou]

Thanks for confirming will review this and give a shot. But for security reasons it would be ideal to leverage production crypto under covers. This would not pass our security review. Any thoughts regarding this?

I don't know what you mean by "production crypto", or what your security review is. The link I shared documents the crypto API provided by CCF.

Is the polyfill code not intended for application consumption ? Thought that source is bound on the baseline via wrappers. Polyfill uses openssl via cpp which will be a safer bet. If its reasonable to leverage it can open a PR for the updates required.

This is the polyfill:

CCF/js/ccf-app/src/polyfill.ts

Line 80 in 1b30b24

class CCFPolyfill implements CCF {

. It's a TypeScript re-implementation of some of the APIs provided by the CCF runtime (and documented under https://microsoft.github.io/CCF/main/js/ccf-app/modules/global.html), for the purpose of unit-testing TypeScript code before running it in a real CCF network.

The crypto section of the CCF runtime JavaScript APIs lives under https://github.com/microsoft/CCF/blob/1b30b2472f2eb6ddb2b8c61d5dbd1188479d55b2/src/js/extensions/ccf/crypto.cpp, it is absolutely reasonable to open issues and PRs against that to propose changes or extensions.

Our current application leverages Global commit during read path on some logic. How do we achieve the same on JS?

That functionality is not exposed in JS at the moment, it would need to be added here: https://github.com/microsoft/CCF/blob/main/src/js/extensions/ccf/kv_helpers.h

Note that taking read dependencies outside the Tx-provided read snapshot breaks serialization, meaning that you are potentially reading stale values.

The endpoints functions but it runs several magnitudes slower than cpp counter part.

You can find numbers for a very basic application we run in CI here:

https://bencher.dev/console/projects/ccf/perf?key=true&reports_per_page=4&branches_per_page=8&testbeds_per_page=8&benchmarks_per_page=8&plots_per_page=8&reports_page=1&branches_page=1&testbeds_page=1&benchmarks_page=1&plots_page=1&branches=d5004f0a-5dbe-42bb-a821-1f55704d6ec2&testbeds=1e6f6a27-eb58-4f16-8d01-0148fbaed70e&benchmarks=41e7278b-6190-49a8-8ec7-d172a115ab91%2Cd63419e2-b19a-4ef2-8927-128fb71eda0d%2C70a79d7d-4957-4a1d-9f77-29744fce6ba1%2Cd480994a-c7b3-499f-9cf8-4598456dd72f%2C78b6bb15-0b19-4c12-868e-e7233fa9e2d1%2Cbe37eb84-5a27-4159-b120-2ff9e9cd6e21%2C7a535009-325e-447a-8a2a-5a9f664ff259&measures=61344be9-e1b4-4c7d-b707-1d54c82119eb&start_time=1721752712000&end_time=1724344712000&clear=true&report=19ac89c1-989d-41e0-bb32-1c7a807d6d66

The C++ variant hovers around 60k Tx/s, whereas the JS variant is about 4.5kTx/s. You trade off some isolation for additional throughput by configuring CCF to re-use JS runtimes rather than create fresh ones for every request, as described under https://microsoft.github.io/CCF/main/build_apps/js_app_bundle.html#reusing-interpreters

[bsenthilr]

Thanks for detailed explanation @achamayou really appreciate it.

If my understanding is right, as long as we use the CCF crypto runtime plumbed via JS extensions wrappers it must be fine since it use openssl via core runtime. So basically do not need to care about polyfill since its unit testing specific and the core runtime and extensions will suffice(PR is reasonable for missing paths). So will need to try patching extensions locally, test and file a PR.
Does this make sense? Please suggest if there is a gap in understanding here.

Think the patch is simple to admit SHA-384 HERE and include definitions similar to HERE.

Currently the application container leverages mcr.microsoft.com/ccf/app/dev:4.0.16-virtual as base image. What is the correct way to build such base image with local patches?
Would be great if you could enumerate the steps required to build a patched base image.

Note: followed the steps here for 4.0.16 but build fails. Not clear if ghcr.io/microsoft/ccf/ci has external permissions. So trying to build a CI image using the Dockerfile.

# Build command
docker build -t ccf-ci:4.0.16-virtual -f docker/ccf_ci --build-arg="platform=virtual" --build-arg="clang_version=15" .

Note: ran into issues related to building behind proxy for apt-key (libstdc++-dev PPA could not get install - this is similar to Issue 116 ). Managed to work around it.

Not sure if the above build command is correct. But post adjusting playbook locally for proxy could build cchost and install them using "ninja install" then commit and create a base image. Is this the correct sequence?
Will try the same with ccf_dev.

Note that taking read dependencies outside the Tx-provided read snapshot breaks serialization, meaning that you are potentially reading stale values.
Sorry could you please elaborate the issue? Isn't all reads in a given endpoint dispatch on the same context? Let me figure out what scenario ended up required global commit reads.

Regarding reusing interpreters
The options seems to be on context of each endpoints. Is there a global way to toggle it?

Also tried to enable stack traces and it works definitely a time saver! Initially used the head/stack settings from the wiki but post proposal nothing worked :) so reset them to default heap values from source and that works.

Regarding performance

Based on quickjs documentation:
Fast interpreter with very low startup time: runs the 77000 tests of the ECMAScript Test Suite2 in less than 2 minutes on a single core of a desktop PC. The complete life cycle of a runtime instance completes in less than 300 microseconds.
Assuming thats the minimum overhead in event of spinning of a fresh runtime.

Thanks again

[achamayou]

If my understanding is right, as long as we use the CCF crypto runtime plumbed via JS extensions wrappers it must be fine since it use openssl via core runtime. So basically do not need to care about polyfill since its unit testing specific and the core runtime and extensions will suffice(PR is reasonable for missing paths). So will need to try patching extensions locally, test and file a PR.
Does this make sense? Please suggest if there is a gap in understanding here.

Yes, that makes sense. Extending the polyfill when adding APIs is nice to help folks who want to unit test their transaction handlers, but not required.

Think the patch is simple to admit SHA-384 HERE and include definitions similar to HERE.

That's a good place to start, yes.

Currently the application container leverages mcr.microsoft.com/ccf/app/dev:4.0.16-virtual as base image. What is the correct way to build such base image with local patches?
Would be great if you could enumerate the steps required to build a patched base image.

Please see:

https://microsoft.github.io/CCF/main/contribute/build_setup.html
https://microsoft.github.io/CCF/main/contribute/build_ccf.html

Release images are made with app_dev/app_run under https://github.com/microsoft/CCF/blob/main/docker/, but post GH release, you will need to patch up the ansible playbook a bit to pick up a local .deb file. You can make one of those with cpack -G DEB, after having run a build.

Not sure if the above build command is correct. But post adjusting playbook locally for proxy could build cchost and install them using "ninja install" then commit and create a base image. Is this the correct sequence?
Will try the same with ccf_dev.

That sounds fine, yes.

Fast interpreter with very low startup time: runs the 77000 tests of the ECMAScript Test Suite2 in less than 2 minutes on a single core of a desktop PC. The complete life cycle of a runtime instance completes in less than 300 microseconds.
Assuming thats the minimum overhead in event of spinning of a fresh runtime.

Yes, we are not aware of a JS interpreter with quicker startup (but we are interested in pointers!).

[bsenthilr]

Thanks again @achamayou had to test further before posting back.

That's a good place to start, yes.

Kind of concerned with JS workflow. With CCF C++ runtimes natively consumed by application things are flexible.
But with JS based on my understanding, JS API layer as above is required and wrappers are implemented based on webcrypto and standard ways which limits your flexibility.
In my use case, most of the prevailing clients are leveraging "DER" format and 384 digest and JS wrapper uses webcrypto style IEEE format. So the proposed change would impact API change on globals.js to include additional encoding type and extensions of underneath JS layer. Believe that will introduce additional housekeeping with patched local npm package until official release.

My further fundamental concern is regarding how this will pan on Azure ACL. Currently notice ACL lacks option to cherry pick a required CCF version for ACL. If we had to deploy emergency patch on CCF how does this work with ACL? Please share your thoughts can also open a Azure ticket if required. Would really appreciate if you could clarify the workflow with ACL since thats my final goal.

build/patch - ccf-dev
Referred to those website before posting here sorry some registry links referred there for old versions where not accessible. Was fundamentally looking for a container image to mount and build the patch.
Noticed ccf-dev based docker containers lacked stdc++dev headers required for c++ span support.
Only ccf-ci image provides it. So tweaked ansible(for proxy issues) and used the following command to patch specific ccf version we currently use.

docker build -t ccf-ci:4.0.16-virtual -f docker/ccf_ci --build-arg="platform=virtual" --build-arg="clang_version=15" --build-arg="ansible_vars=ccf_ver=4.0.16" .

Please let me know if this makes sense. If not please suggest the proper workflow to build.

Thanks Again!

[achamayou]

@bsenthilr I understand your concerns, but I think they are inherent in choosing to use a hosted service as opposed to hosting yourself. You trade off having to do maintenance for control over deployment cycles. With ACL you are in full control of the JS code, but the native code is updated by the ACL team. Reaching out to them for additional questions is definitely a good idea.

wrt the docker build, yes that looks like it should work.