From 9b110a64722e1b43368ccb1a2115ec00de78bcc9 Mon Sep 17 00:00:00 2001 From: Benjamin Gandon Date: Sat, 11 May 2024 16:22:38 +0200 Subject: [PATCH] Improve readme Facor links, remove EOL spaces, fix typo, improve alignments, suggest new title. --- README.md | 68 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 002e339..0a133ec 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,12 @@ -# concourse-keyval-resource -a [Concourse](https://concourse-ci.org/resources.html) resource for: +# Concourse Bloblang key-value resource + +A [Concourse](https://concourse-ci.org/resources.html) resource for: + - passing arbitrary data between steps and/or jobs - curating dynamic filesystem content ## Getting Started + ```yaml resource_types: - name: keyval @@ -35,9 +38,9 @@ jobs: test.md: | root = """ # Build Summary - | ID | Team | Pipeline | Job | Name | - | :---: | :--- | :--- | :--- | :--- | - | [%s](%s) | %s | %s | %s | %s | + | ID | Team | Pipeline | Job | Name | + | :------: | :--- | :------- | :--- | :--- | + | [%s](%s) | %s | %s | %s | %s | """.format(id, url, team, pipeline, job, name) test.json: | uid = ksuid() @@ -72,52 +75,60 @@ jobs: ## Configuration **Parameters:** -| Parameter | Type | Description | Required | -| :--- | :---: | :--- | :---: | +| Parameter | Type | Description | Required | +| :-------- | :---: | :---------- | :------: | | archive | [*archive.Archive](https://pkg.go.dev/github.com/cludden/concourse-go-sdk@v0.3.1/pkg/archive#Config) | optional archive config that can be used to enable [resource version archiving](https://github.com/cludden/concourse-go-sdk#archiving) | | -| initial_mapping | `string` | a [Bloblang mapping](https://www.benthos.dev/docs/guides/bloblang/about) that can be used to customize the initial version returned by this resource. See [Initial Mapping](#initial-mapping) for more details. | ⚠ | +| initial_mapping | `string` | a [Bloblang mapping][about_bloblang] that can be used to customize the initial version returned by this resource. See [Initial Mapping](#initial-mapping) for more details. | ⚠ | ## Behavior ### `check` + Check returns the latest available version produced by a `put` step. If `get` is used prior to `put`, an initial version will be returned which can be customized via the `initial_mapping` resource parameter. ### `in` + Fetches arbitrary key value data from a prior put step and writes it the file system as a JSON document. **Parameters:** -| Parameter | Type | Description | Required | -| :--- | :---: | :--- | :---: | -| files | `map[string]string` | a map of filenames to [Bloblang mappings](https://www.benthos.dev/docs/guides/bloblang/about), where the input document contains the [build metadata](https://concourse-ci.org/implementing-resource-types.html#resource-metadata) along with any key value data from the fetched version, and the output is the content of the file to write (note: unless the file extension is one of `.json`, `.yaml`, or `.yml`, the mapping output must be of type `string` or `[]byte`) | | +| Parameter | Type | Description | Required | +| :-------- | :---: | :---------- | :------: | +| files | `map[string]string` | a map of filenames to [Bloblang mappings][about_bloblang], where the input document contains the [build metadata][resource_metadata] along with any key value data from the fetched version, and the output is the content of the file to write (note: unless the file extension is one of `.json`, `.yaml`, or `.yml`, the mapping output must be of type `string` or `[]byte`) | | **Files:** - `version.json` - the key value pairs serialized as a JSON document -- `metadata.json` - the [build metadata](https://concourse-ci.org/implementing-resource-types.html#resource-metadata) serialized as a JSON document +- `metadata.json` - the [build metadata][resource_metadata] serialized as a JSON document - `*` any file mappings defined in the `files` parameter ### `out` + Publishes arbitrary key value data to be shared across jobs. **Parameters:** -| Parameter | Type | Description | Required | -| :--- | :---: | :--- | :---: | -| mapping | `string` | a [Bloblang mappings](https://www.benthos.dev/docs/guides/bloblang/about), where the input document contains the [build metadata](https://concourse-ci.org/implementing-resource-types.html#resource-metadata), and the output is a `map[string]string`, defaults to `root = this` | | +| Parameter | Type | Description | Required | +| :-------- | :---: | :---------- | :------: | +| mapping | `string` | a [Bloblang mappings][about_bloblang], where the input document contains the [build metadata][resource_metadata], and the output is a `map[string]string`, defaults to `root = this` | | + +[about_bloblang]: https://www.benthos.dev/docs/guides/bloblang/about +[resource_metadata]: https://concourse-ci.org/implementing-resource-types.html#resource-metadata ## Build Metadata -Each [Bloblang mappings](https://www.benthos.dev/docs/guides/bloblang/about) the following build metadata as input: -| Parameter | Type | Description | Always Available | -| :--- | :---: | :--- | :---: | -| build_created_by | `string` | the username that created the build, only available when the resource is configured to [expose_build_created_by](https://concourse-ci.org/resources.html#schema.resource.expose_build_created_by) | | -| build_id | `string` | the unique build identifier | ✓ | + +Each [Bloblang mappings][about_bloblang] the following build metadata as input: +| Parameter | Type | Description | Always Available | +| :-------- | :---: | :---------- | :--------------: | +| build_created_by | `string` | the username that created the build, only available when the resource is configured to [expose_build_created_by](https://concourse-ci.org/resources.html#schema.resource.expose_build_created_by) | | +| build_id | `string` | the unique build identifier | ✓ | | build_instance_vars | `string` | instance vars of the instanced pipeline that the build's job lives in, serialized as JSON | | -| build_job | `string` | the name of the job | ✓ | -| build_name | `string` | the build id in the context of the pipeline | ✓ | -| build_pipeline | `string` | the name of the pipeline | ✓ | -| build_team | `string` | the name of the team | ✓ | -| build_url | `string` | the fully qualified build url | ✓ | +| build_job | `string` | the name of the job | ✓ | +| build_name | `string` | the build id in the context of the pipeline | ✓ | +| build_pipeline | `string` | the name of the pipeline | ✓ | +| build_team | `string` | the name of the team | ✓ | +| build_url | `string` | the fully qualified build url | ✓ | ## Initial Mapping -In most sitautions, like the example below, the initial use of this resource is with a `put` step, followed by a later `get` step, in which case this field is not required and checking should be disabled via `check_every: never` to conserve resources. + +In most situations, like the example below, the initial use of this resource is with a `put` step, followed by a later `get` step, in which case this field is not required and checking should be disabled via `check_every: never` to conserve resources. ```yaml resource_types: @@ -140,7 +151,7 @@ jobs: params: mapping: | timestamp = now() - + - name: second plan: - get: keyval @@ -184,5 +195,6 @@ jobs: ``` ## License -Licensed under the [MIT License](LICENSE.md) + +Licensed under the [MIT License](LICENSE.md) Copyright (c) 2023 Chris Ludden \ No newline at end of file