1 Builtins

Builtins are a special type of service provided by the Kumori DSL that can be used as part of your service applications (as a sub-service role). These services are typically essential for common tasks and infrastructure needs, such as handling HTTP requests.

The type alias definition available for builtins is as follows:

alias builtin struct {
    id          Ref
    srv         Links
    config      struct open[]
    resource    struct open[Resource]
}

alias Ref struct {
    name    string
    kind    "service" | "component"
    domain  string
    module  string
    version string
}

A builtin service is defined with an id field that uniquely identifies the builtin by its name, kind (service or component), domain, module, and version, as expressed in the Ref type alias.

Currently, there are two built-in services provided by Kumori DSL: HTTP Inbound and TCP Inbound.

1.1 HTTP Inbound Builtin

The HTTPInbound service allows your deployed service to be reached from the outside through HTTPS requests. The HTTPInbound service can be included within a service itself, just declaring the dependency in the service manifest.

The HTTPInbound builtin is specified as follows:

package builtin

import "kumori"

builtin HTTPInbound {
    id {
        name    "inbound"
        kind    "service"
        domain  "kumori.systems"
        module  "builtins/inbound"
        version "1.3.0"
    }
    
    srv {
        client { inbound "http" }
    }
    
    config {
        type "https"
    }
    
    resource {
        servercert:     kumori.Certificate
        serverdomain:   kumori.Domain
        clientcertca?:  kumori.CA
    }
}

In plain words, when instantiated in a service, the HTTPInbound builtin exposes a client channel named inbound, sets a configuration field type to https, and expect two mandatory resources: a server certificate and a server domain, and an optional client certificate authority.

1.2 TCP Inbound Builtin

The TCPInbound service allows your deployed service to be reached from the outside through TCP connections over a specific port. In the same way as the HTTPInbound service, the TCPInbound service can be deployed within a service itself, just declaring the dependency in the service manifest.

The TCPInbound builtin is specified as follows:

package builtin

import "kumori"

builtin TCPInbound {
    id {
        name    "inbound"
        kind    "service"
        domain  "kumori.systems"
        module  "builtins/inbound"
        version "1.3.0"
    }
    
    srv {
        client { inbound "tcp" }
    }
    
    config {
        type "tcp"
    }
    
    resource {
        port: kumori.Port
    }
}

In plain words, when instantiated in a service, the TCPInbound builtin exposes a client channel named inbound, sets a configuration field type to tcp, and expect a mandatory resource: a port.

1.3 Using Builtins in Service artifacts

To use a builtin in your service artifact, you must import the builtin package in your artifact’s implementation and declare a role that references the desired builtin. Here is an example of how to include the HTTPInbound builtin in a service:

import "kumori/builtin"

service MyService {
    role {
        inboundRole {
            artifact builtin.HTTPInbound

            resource {
                servercert   interface.resource.servercert
                serverdomain interface.resource.serverdomain
            }
        }
    }
}