Scaffolding

[lkingland]

This is the umbrella issue for implementation of Function Scaffolding as laid out in the related discussion.

At a high level this encapsulates creating a function source-code scaffolding engine which supports host-based running, building and pushing without the need for podman or docker, and both instanced and static method signatures.

This is an initial implementation which focuses on the minimum necessary changes to enable an end-to-end experience using function scaffolding for Go functions. There are several rough edges and missing features needed before this could be considered complete, and of course scaffolding needs to be created for each of the other runtimes. The intent of this inital implementation is to serve as a a fast-track for a very focused subset of functions, and as a reference implementation for creating scaffolding for the other languages.

Running Functions Locally

Running locally from within a container remains the default for now, though this should be the default when scaffolding is implemented for the other languages. To run a Go container locally outside of a container use --container=false

mkdir f && cd $_
func create -l go
func run --container=false

Languages other than Go will yield the error:

Error: The ability to run functions outside of a container via 'func run' is coming soon.

Building Scaffolded Functions

Functions built using the --builder=host option (currently not the default) are scaffolded into the directory .func/builds/$HASH. This option is available to both run and deploy. This build step builds the OCI-compliant directory structure directly rather than using Podman or Docker.

Deploying Scaffolded Functions

A function which indicates that its builder is/was "host" will use the inbuilt OCI pusher, which uses the container data built into the .func/builds/$HASH directory.

mkdir f && cd $_
func create -l go
func deploy --builder=host

Route Selection

As part of this update, mostly with the intent of making a clean end-to-end demo, the --domain flag can be specified when deploying a function to indicate which of the configured domains of the cluster should be used. The default is to use the cluster default. This requires that the cluster be configured correctly otherwise the setting is ignored. On the docket for our next discussion is how we can query the underlying platform for this and other settings which could be used informatively for the user. For the best experience an entire domain would be delegated to the cluster and the namespace removed from the route creation, along with a ClusterIssuer for HTTPS:

$ mkdir www && cd $_
$ func create -l go
$ func deploy --builder=host --domain=boson-project.org
Function deployed at https://www.boson-project.org
$ curl https://www.boson-project.org
Hello, world!

Instanced vs Static Method Signatures

In order to write the correct scaffolding, we need to know invocation (cloudevents or http) and language. This adds a layer of logic inbetween the code and the scaffolding which is the correct place to do more advanced operations. To illustrate this, the scaffolding code supports both static and "instanced" cloudevent and http functions. Currently only available for Go with the "host" builder, a function author can now opt to implement a func New() *MyFunction constructor which will have its .Handle method invoked. Also supported are overrides for lifecycle methods such as .Start, .Stop, .Alive, and Ready. This is only possible when using an instance rather than a package-static function Handle.

Subtasks

• Track Go Sumfiles and Test backward compatibility
  feat: track go template sumfiles #1688
• Support domain command for selecting route
  feat: func domain route #1690
• Update run command to support all build options
  (feat: func run support all build options #1693)
• Rename client library Instances to InstaceRefs to avoid confusion with func runtme library
  (src: rename Instance to InstanceRefs #1694)
• Update Jobs to support Scaffolded and non-scaffolded (local) runs
  (feat: job scaffolding #1697)
• Define and Detect Function Signatures
  (feat: function signature detection #1699)
• Basic OCI builder with plugable language layer builders
  (feat: host oci builder #1730)
• Scaffolding Code for both Static and Instanced Go Functions with Writer
  (feat: go scaffolding #1732)
• Container pusher which directly submits an OCI-compliant directory as a tarball to a remote registry
  (feat: oci directory pusher #1702)
• localhost default runner which builds using the OCI builder on func run --container=false
  (feat: host-based scaffolded function runner #1733)
• integrate the scaffolding with the OCI builder and pusher
  (feat: enable scaffolding for host builds #1750)
• enable scaffolded builder, runner and pusher into CLI (enable)
  (feat: enable host-based build and push on build cmd #1748)
• enable function external dependencies auto-import
  (feat: support dependencies in host-built functions #1790)
• Multi-OS root SSL certs layer in resultant image
  (feat: scaffolding ca certs #1823)

Open Questions

Should we prompt persistence of options for func run?

The run command does not persist configuration parameters to func.yaml because the way one runs the container locally, especially when outside of a container, should not affect how it is run in production (ie affect the source code).
This could very well lead to confusion on the part of the user. We could leave this as a documentation issue, or we could implement an interactive Prompt to ask the user if they would like to save changes to key attributes such as "builder".