Skip to content

Commit

Permalink
build: bump release version (#142)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ravisuhag
ravisuhag authored Aug 31, 2022
1 parent f25ecc8 commit 85a6f1f
Show file tree
Hide file tree
Showing 10 changed files with 363 additions and 308 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ docker pull odpf/stencil:latest
To pull a specific version:

```
docker pull odpf/stencil:v0.2.2
docker pull odpf/stencil:v0.3.0
```

## Usage
Expand Down
113 changes: 66 additions & 47 deletions clients/clojure/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,19 @@
# Stencil Clojure Client

A Clojure library designed to easily encode and decode protobuf messages by using Clojure maps.
A Clojure library designed to easily encode and decode protobuf messages by using Clojure maps.

## Installation

Add the below dependency to your `project.clj` file:

```clj
[io.odpf/stencil-clj "0.2.2"]
[io.odpf/stencil-clj "0.3.0"]
```

## Usage

Consider following proto message

```proto
syntax = "proto3";
Expand Down Expand Up @@ -39,6 +41,7 @@ message Person {
int32 age = 5;
}
```

1. Create stencil client. You can refer to [java client](../java) documentation for all available options.

```clojure
Expand All @@ -52,6 +55,7 @@ message Person {
```

2. To serialize data from clojure map

```clojure
(:require [stencil.core :refer [serialize]])

Expand All @@ -64,6 +68,7 @@ message Person {
```

3. Deserialize data from bytes to clojure map

```clojure
(:require [stencil.core :refer [deserialize]])

Expand All @@ -78,40 +83,44 @@ message Person {

## Protocol buffers - Clojure interop

| Protobuf | Clojure | Notes |
| ----------- | --------------------------- | ---------------- |
| field names | keywords in kebab case | `name` -> `:name`, `field_name` -> `:field-name` |
| scalar fields | Values follow [protobuf-java scalar value mappings](https://developers.google.com/protocol-buffers/docs/proto3#scalar) | |
| enums | Values converted as keywords of enum's original value | `UNKNOWN` -> `:UNKNOWN` |
| messages | clojure map | ```message Hello {string name = 1;}``` -> {:name "odpf"} |
| repeated fields | clojure vector | |
| one-of fields | treated as regular fields | if two fields are set that are part of one-of, last seen value is considered while serializing data |
| map | map values follow it's [wire representation](https://developers.google.com/protocol-buffers/docs/proto3#backwards_compatibility) | for `map<string, string>` type, example value will be `[{:key "key" :value "value"}]` |
| Protobuf | Clojure | Notes |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| field names | keywords in kebab case | `name` -> `:name`, `field_name` -> `:field-name` |
| scalar fields | Values follow [protobuf-java scalar value mappings](https://developers.google.com/protocol-buffers/docs/proto3#scalar) | |
| enums | Values converted as keywords of enum's original value | `UNKNOWN` -> `:UNKNOWN` |
| messages | clojure map | `message Hello {string name = 1;}` -> {:name "odpf"} |
| repeated fields | clojure vector | |
| one-of fields | treated as regular fields | if two fields are set that are part of one-of, last seen value is considered while serializing data |
| map | map values follow it's [wire representation](https://developers.google.com/protocol-buffers/docs/proto3#backwards_compatibility) | for `map<string, string>` type, example value will be `[{:key "key" :value "value"}]` |

**Note on errors:**
Serialize will throw error in following cases

1. unknown field is passed that's not present in schema `{:cause :unknown-field :info {:field-name <field-name>}}`
2. if non-collection type is passed to repeated field `{:cause :not-a-collection :info {:value <value>}}`
3. If unknown enum value passed that's not present in schema `{:cause :unknown-enum-value :info {:field-name <field-name>}}`

## API

- `create-client (client-config)`

Returns a new Stencil Clojure client instance by passing client-config.

### Client config structure :
| Key | Type | Description |
| -----------------------|-----------|---------------------------------------------------------------------------------------------|
| `url` | _String_ | Stencil url to fetch latest descriptor sets |
| `refresh-cache` | _Boolean_ | Whether the cache should be refreshed or not |
| `refresh-ttl` | _Integer_ | Cache TTL in minutes |
| `request-timeout` | _Integer_ | Request timeout in milliseconds |
| `request-backoff-time` | _Integer_ | Request back off time in minutes |
| `retry-count` | _Integer_ | Number of retries to be made to fetch descriptor sets |
| `headers` | _Map_ | Map with key as header key and value as header value, which will be passed to stencil server|
| `refresh-strategy` | _keyword_ | Possible values :version-based-refresh, :long-polling-refresh. Default :long-polling-refresh|

| Key | Type | Description |
| ---------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `url` | _String_ | Stencil url to fetch latest descriptor sets |
| `refresh-cache` | _Boolean_ | Whether the cache should be refreshed or not |
| `refresh-ttl` | _Integer_ | Cache TTL in minutes |
| `request-timeout` | _Integer_ | Request timeout in milliseconds |
| `request-backoff-time` | _Integer_ | Request back off time in minutes |
| `retry-count` | _Integer_ | Number of retries to be made to fetch descriptor sets |
| `headers` | _Map_ | Map with key as header key and value as header value, which will be passed to stencil server |
| `refresh-strategy` | _keyword_ | Possible values :version-based-refresh, :long-polling-refresh. Default :long-polling-refresh |

Example:

```clojure
(let [sample-client-config {:url "https://example-url"
:refresh-cache true
Expand All @@ -130,17 +139,20 @@ Serialize will throw error in following cases
Returns protobuf descriptor object for the given protobuf class name.

### Argument list :
| Key | Type | Description |
| ------------------------------------------------|-------------------|-----------------------------------------------------------------------------|
| `client` | _Object_ | Instantiated Clojure client object |
| `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required |

| Key | Type | Description |
| ------------------ | -------- | ----------------------------------------------------------------- |
| `client` | _Object_ | Instantiated Clojure client object |
| `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required |

### Response structure
| Value | Type | Description |
|-------------------------------------------------|-------------------|-----------------------------------------------------------------------------|
| **proto-desc** | _Object_ | Protobuf descriptor for given proto class name |

| Value | Type | Description |
| -------------- | -------- | ---------------------------------------------- |
| **proto-desc** | _Object_ | Protobuf descriptor for given proto class name |

Example:

```clojure
(let [client (create-client sample-client-config)
proto-package "io.odpf.stencil_clj_test"
Expand All @@ -154,18 +166,21 @@ Serialize will throw error in following cases
Returns Clojure map for the given protobuf encoded byte array and protobuf class name.

### Argument list :
| Key | Type | Description |
| ------------------------------------------------|---------------------|-----------------------------------------------------------------------------|
| `client` | _Object_ | Instantiated Clojure client object |
| `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required |
| `data` | _Byte-Array_ | Data (byte-array) to be deserialized using proto-descriptor object |

| Key | Type | Description |
| ------------------ | ------------ | ------------------------------------------------------------------ |
| `client` | _Object_ | Instantiated Clojure client object |
| `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required |
| `data` | _Byte-Array_ | Data (byte-array) to be deserialized using proto-descriptor object |

### Response structure
| Value | Type | Description |
|-------------------------------------------------|---------------------|-----------------------------------------------------------------------------|
| **deserialized-message** | _PersistentArrayMap_| Deserialized message (Clojure Map) |

| Value | Type | Description |
| ------------------------ | -------------------- | ---------------------------------- |
| **deserialized-message** | _PersistentArrayMap_ | Deserialized message (Clojure Map) |

Example:

```clojure
(let [client (create-client sample-client-config)
proto-package "io.odpf.stencil_clj_test"
Expand All @@ -181,18 +196,21 @@ Serialize will throw error in following cases
Returns protobuf encoded byte array for the given Clojure and protobuf class name.

### Argument list :
| Key | Type | Description |
| ------------------------------------------------|----------------------|-----------------------------------------------------------------------------|
| `client` | _Object_ | Instantiated Clojure client object |
| `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required |
| `map` | _PersistentArrayMap_ | Data (in the form of map) to be serialized using proto descriptor object |

| Key | Type | Description |
| ------------------ | -------------------- | ------------------------------------------------------------------------ |
| `client` | _Object_ | Instantiated Clojure client object |
| `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required |
| `map` | _PersistentArrayMap_ | Data (in the form of map) to be serialized using proto descriptor object |

### Response structure
| Value | Type | Description |
|-------------------------------------------------|---------------------|------------------------------------------------------------------------------|
| **serialized-message** | _Byte-Array_ | Serialized message (byte-array) |

| Value | Type | Description |
| ---------------------- | ------------ | ------------------------------- |
| **serialized-message** | _Byte-Array_ | Serialized message (byte-array) |

Example:

```clojure
(let [client (create-client sample-client-config)
proto-package "io.odpf.stencil_clj_test"
Expand All @@ -201,13 +219,14 @@ Serialize will throw error in following cases
proto-desc (get-descriptor client fully-qualified-proto-name)]
(serialize client fully-qualified-proto-name {:field-one 1.25}))
```

## Development
- Ensure [leiningen](https://leiningen.org/) is installed.

- Run tests: ```lein clean && lein javac && lein test```
- Ensure [leiningen](https://leiningen.org/) is installed.

- Run formatting: ```lein cljfmt fix```
- Run tests: `lein clean && lein javac && lein test`

- Run formatting: `lein cljfmt fix`

## License

Expand Down
2 changes: 1 addition & 1 deletion clients/clojure/project.clj
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(defproject io.odpf/stencil-clj "0.2.2"
(defproject io.odpf/stencil-clj "0.3.0"
:description "Stencil client for clojure"
:url "https://github.com/odpf/stencil"
:license {:name "Apache 2.0"
Expand Down
2 changes: 1 addition & 1 deletion clients/java/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Protobuf allows you to define a protobuf file using DescriptorSet. A FileDescrip
#### Gradle

```groovy
implementation group: 'io.odpf', name: 'stencil', version: '0.2.2'
implementation group: 'io.odpf', name: 'stencil', version: '0.3.0'
```

#### Maven
Expand Down
2 changes: 1 addition & 1 deletion clients/java/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ plugins {
}

group 'io.odpf'
version '0.2.2'
version '0.3.0'

repositories {
mavenLocal()
Expand Down
2 changes: 1 addition & 1 deletion clients/js/package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@odpf/stencil",
"version": "0.2.2",
"version": "0.3.0",
"description": "Stencil js client package provides a store to lookup protobuf descriptors and options to keep the protobuf descriptors upto date.",
"main": "main.js",
"scripts": {
Expand Down
Loading

0 comments on commit 85a6f1f

Please sign in to comment.