Readme

AlexeyRaga · Aug 12, 2024 · b4af29d · b4af29d
1 parent ffeca65
commit b4af29d
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 1 deletion.
diff --git a/src/Contrib.KafkaFlow.CryptoShredding.Avro/Contrib.KafkaFlow.CryptoShredding.Avro.csproj b/src/Contrib.KafkaFlow.CryptoShredding.Avro/Contrib.KafkaFlow.CryptoShredding.Avro.csproj
@@ -16,4 +16,8 @@
     <PackageReference Include="Nullable" Version="1.3.1" PrivateAssets="all"/>
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="Readme.md" Pack="true" PackagePath="\"/>
+  </ItemGroup>
+
 </Project>
diff --git a/src/Contrib.KafkaFlow.CryptoShredding.Avro/Readme.md b/src/Contrib.KafkaFlow.CryptoShredding.Avro/Readme.md
@@ -33,6 +33,66 @@ sensitiveData = EncryptedString.FromPlain("secret-value");
 To prevent accidental leakage of secrets, `EncryptedString.Plain` cannot be serialized to Avro. An attempt to do so will result in an
 exception.
 
+### Generating Avro types
+
+Here is an example of an Avro schema that uses encrypted secrets:
+
+```avro
+{
+  "type": "record",
+  "name": "EncryptedMessage",
+  "namespace": "TestContract",
+
+  "fields": [
+    { "name": "secret",
+      "type": { "type": "string", "logicalType": "encrypted-string" } }
+  ]
+}
+```
+
+C# types can be generated using the [avrogen](https://www.nuget.org/packages/Apache.Avro.Tools) tool
+or by using `Contrib.KafkaFlow.CryptoShredding.Avro.Analyzers` package.
+
+In both cases, make sure to register `EncryptedString` as a logical type:
+
+```csharp
+LogicalTypeFactory.Instance.Register(new EncryptedStringLogicalType());
+```
+
+### Using avrogen
+
+Install [avrogen](https://www.nuget.org/packages/Apache.Avro.Tools):
+
+```bash
+$ dotnet tool install Apache.Avro.Tools
+```
+
+Then generate C# types:
+
+```bash
+$ dotnet avrogen -s <schema-file> <output-directory>
+```
+
+### Using Avro Analyzers
+
+Reference the package in your `.csproj` file:
+
+```xml
+<PackageReference Include="Contrib.KafkaFlow.CryptoShredding.Avro.Analyzers"
+                  Version="x.x.x"
+                  OutputItemType="Analyzer"
+                  ReferenceOutputAssembly="false" />
+```
+and add `*.avsc` files:
+
+```xml
+<ItemGroup>
+    <AdditionalFiles Include="avro\*.avsc" />
+</ItemGroup>
+```
+
+C# classes will be generated automatically for all schemas in the `avro` directory.
+
 ## Encryption Process
 
 For serialization to occur, the secrets must be encrypted first, converting `EncryptedString.Plain` into `EncryptedString.Encrypted`. The

diff --git a/src/Contrib.KafkaFlow.Outbox/Contrib.KafkaFlow.Outbox.csproj b/src/Contrib.KafkaFlow.Outbox/Contrib.KafkaFlow.Outbox.csproj
@@ -8,7 +8,7 @@
     <LangVersion>latest</LangVersion>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
-    <PackageVersion></PackageVersion>
+    <PackageReadmeFile>Readme.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
@@ -23,4 +23,8 @@
     <PackageReference Include="System.Text.Json" Version="8.0.4" />
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="Readme.md" Pack="true" PackagePath="\"/>
+  </ItemGroup>
+
 </Project>
diff --git a/src/Contrib.KafkaFlow.ProcessManagers/Contrib.KafkaFlow.ProcessManagers.csproj b/src/Contrib.KafkaFlow.ProcessManagers/Contrib.KafkaFlow.ProcessManagers.csproj
@@ -8,6 +8,7 @@
     <LangVersion>latest</LangVersion>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
+    <PackageReadmeFile>Readme.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
@@ -20,4 +21,8 @@
     <PackageReference Include="System.Text.Json" Version="8.0.4" />
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="Readme.md" Pack="true" PackagePath="\"/>
+  </ItemGroup>
+
 </Project>