Help language development. Donate to The Perl Foundation
# The Cro Development Tools Cro includes tools to help developers work more efficiently. Currently the tools are available through a command line interface; in the future a web interface will be added also. It is entirely possible to use Cro without these tools. They aim to provide some reasonable defaults, but will not be suitable for every project. ## Stubbing Services A new service can be stubbed using the `cro stub` command. The general usage is: cro stub <service-type> <service-id> <path> ['links-and-options'] Where * `service-type` is the type of service to create * `service-id` is the ID of the service (to be used with other `cro` commands; this will also be used as the service's default descriptive `name` in `.cro.yml`) * `path` is the location to create the service * `links-and-options` specifies links to other services that should be added to the stub, together with options specific to the service type If the links and options are not specified, then they will be requested interactively. To provide the options, place them in quotes using Raku colonpair-like syntax, where `:foo` enables an option, `:!foo` disables an option, and `:foo<bar>` is the option `foo` with the value `bar`. For example: cro stub http foo services/foo ':!secure :websocket' cro stub http bar services/bar ':!secure :websocket' The stubbed services take port and certificate configuration from environment variables, and when there are relations between services their addresses are also injected using environment variables. This is convenient when setting up container deployment. Links cause the stubbed service to include code that creates some kind of "client" that can communicate with another endpoint. These go in with the options, having the form `:link<service-id:endpoint-id>`. The `service-id` is the `id` field from the target `.cro.yml`, and `endpoint-id` is the `id` field of an entry in the `endpoints` list of that `.cro.yml` file. cro stub http foo services/foo ':link<flash-storage:http>' ### HTTP Services The `http` service type stubs in a HTTP service, using `Cro::HTTP::Router` and served by `Cro::HTTP::Server`. By default, it stubs an HTTPS service that will accept HTTP/1.0, HTTP/1.1 and HTTP/2.0 requests. cro stub http flashcard-backend backend/flashcards The following options may be supplied: * `:secure`: generates an HTTPS service instead of an HTTP one (`:!secure` is the default); implies `:http1 :http2` by default, using ALPN to negotiate whether to use HTTP/2 * `:!http2`: generates a service without HTTP 2 support * `:!http1`: generates a service without HTTP 1 support * `:websocket`: adds a dependency to the `Cro::WebSocket` module and adds a stub web socket example ## Running Services cro run [<service-id> ...] The `cro run` command is used to run services. It automatically sets up file watching and restarts services when there are source changes to the services (with a debounce to handle a stampede of changes, for example due to fetching latest changes of a running service from version control or saving many files in an editor). To run all services (identified by searching for `.cro.yml` files in the current working directory and its subdirectories), use: cro run To run a specific service, write its `service-id` (which must appear as the `id` field in a `.cro.yml` file in the current working directory or one of its subdirectories): cro run flashcard-backend It's also possible to list multiple services: cro run flashcard-backend users frontend The output of the services will be displayed, prefixed with the `service-name`. Sending SIGINT (hitting Ctrl+C) will kill all of the services. Ports are automatically allocated and the environment variable set per the `.cro.yml` for the service. The host environment variable will be set to `localhost` by default, however can be specified with the `--host` option: cro --host=dev-vm run ## Tracing Services cro trace <service-id-or-filter> The `cro trace` command is much like `cro run`, except it turns on pipeline debugging in the services. This makes it possible to see the traffic that each service is receiving and sending, and how it is being interpreted and affected by middleware. The amount of output may be slightly overwhelming, so it can be filtered by the message type name. This is done by checking if any name component is, case-insensitively, equal to the filter. Inclusive filters are expressed as `:name`, and exclusive filters as `:!name`. For example, to exclude all of the TCP message messages from the trace, do: cro trace :!tcp To see only HTTP messages, do: cro trace :http To restrict that further to just requests, do: cro trace :http :request Anything not starting with a `:` is taken as a `service-name`. The order is unimportant, so these are equivalent: cro trace :http flashcard-backend cro trace flashcard-backend :http The `--host` option may be specified as for `cro run`: cro --host=dev-vm trace ## Serving Static Content cro serve <host-port> [<directory>] Sometimes it is useful to set up a HTTP server to serve some static content. Serve the current directory on port 8080 of localhost with: cro serve 8080 Or specify a directory to serve: cro serve 8080 static_content/ An IP address to bind to may also be provided before the port number: cro serve 192.168.0.1:8080 static_content/ ## Working with service links The `cro link` subcommand is used to manage the `links` section of `.cro.yml` files. These describe how one Cro service uses another, resulting in the injection of environment variables specifying the host and port where the service can be found. In production, these would be set by a container engine such as Kubernetes, by some kind of configuration management system, or even just hardcoded into a wrapper script. To add a service link, use `add`: cro link add <from-service-id> <to-service-id> [<to-endpoint-id>] Where `from-service-id` is the `id` of the `.cro.yml` that whose links should be modified, `to-service-id` is the `id` of the `.cro.yml` of the service that will be consumed, and `to-endpoint-id` is the `id` of an endpoint in that service's `.cro.yml`. This command will, provided there is a link template matching the protocol of the service linked to, produce some stub code that you can paste into your service code at the appropriate place (Cro is not so crazy as to think it can edit your code under you!) If `to-endpoint-id` is not specified, and the `to-service-id` service has only one endpoint, then that one will be used by default. Otherwise, the ambiguity will be whined about. To regenerate the code for an existing link, do: cro link code <from-service-id> <to-service-id> [<to-endpoint-id>] To remove a link, use: cro link rm <from-service-id> <to-service-id> [<to-endpoint-id>] Which simply removes the entry from the `links` section of the `.cro.yml` that is identified by `from-service-id`.