diff --git a/.idea/codeStyles/Project.xml b/.idea/codeStyles/Project.xml
new file mode 100644
index 0000000..b28b8a2
--- /dev/null
+++ b/.idea/codeStyles/Project.xml
@@ -0,0 +1,33 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/.idea/codeStyles/codeStyleConfig.xml b/.idea/codeStyles/codeStyleConfig.xml
new file mode 100644
index 0000000..bf4e156
--- /dev/null
+++ b/.idea/codeStyles/codeStyleConfig.xml
@@ -0,0 +1,5 @@
+
+
+
+
+
\ No newline at end of file
diff --git a/README.adoc b/README.adoc
index c21e9ce..919e4f4 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,6 +1,5 @@
= libsecret/gosecret
Brent Saner
-Last updated {localdatetime}
:doctype: book
:docinfo: shared
:data-uri:
@@ -26,6 +25,7 @@ This project is originally forked from https://github.com/gsterjov/go-libsecret[
and as such, hopefully this library should serve as a more effective libsecret/SecretService interface.
== Backwards Compatability/Drop-In Replacement Support
+
Version series `v0.X.X` of this library promises full and non-breaking backwards support of API interaction with the original project. The only changes should be internal optimizations, adding documentation, some file reorganizing, adding Golang module support, etc. -- all transparent from the library API itself.
To use this library as a replacement without significantly modifying your code, you can simply use a `replace` directive:
@@ -36,13 +36,14 @@ To use this library as a replacement without significantly modifying your code,
----
// ...
replace (
- github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0
+ github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0
)
----
and then run `go mod tidy`.
== New Developer API
+
Starting from `v1.0.0` onwards, entirely breaking changes can be assumed from the original project.
To use the new version,
@@ -56,7 +57,70 @@ import (
To reflect the absolute breaking changes, the module name changes as well from `libsecret` to `gosecret`.
+=== Status
+
+The new API is underway, and all functionality in V0 is present. However, It's not "complete". https://github.com/johnnybubonic/gosecret/pulls[PRs^] welcome, of course, but this will be an ongoing effort for a bit of time.
+
+== SecretService Concepts
+
+For reference:
+
+* A *`Service`* allows one to operate on/with *`Session`* objects.
+* A *`Session`* allows one to operate on/with `*Collection*` objects.
+* A `*Collection*` allows one to operate on/with `*Item*` objects.
+* An `*Item*` allows one to operate on/with `*Secrets*`.
+(`*Secrets*` are considered "terminating objects" in this model, and contain
+actual secret value(s) and metadata).
+
+Various interactions are handled by `*Prompts*`.
+
+So the object hierarchy in *theory* looks kind of like this:
+
+----
+Service
+├─ Session "A"
+│ ├─ Collection "A.1"
+│ │ ├─ Item "A.1.a"
+│ │ │ ├─ Secret "A_1_a_I"
+│ │ │ └─ Secret "A_1_a_II"
+│ │ └─ Item "A.1.b"
+│ │ ├─ Secret "A_1_b_I"
+│ │ └─ Secret "A_1_b_II"
+│ └─ Collection "A.2"
+│ ├─ Item "A.2.a"
+│ │ ├─ Secret "A_2_a_I"
+│ │ └─ Secret "A_2_a_II"
+│ └─ Item "A.2.b"
+│ ├─ Secret "A_2_b_I"
+│ └─ Secret "A_2_b_II"
+└─ Session "B"
+ ├─ Collection "B.1"
+ │ ├─ Item "B.1.a"
+ │ │ ├─ Secret "B_1_a_I"
+ │ │ └─ Secret "B_1_a_II"
+ │ └─ Item "B.1.b"
+ │ ├─ Secret "B_1_b_I"
+ │ └─ Secret "B_1_b_II"
+ └─ Collection "B.2"#
+ ├─ Item "B.2.a"
+ │ ├─ Secret "B_2_a_I"
+ │ └─ Secret "B_2_a_II"
+ └─ Item "B.2.b"
+ ├─ Secret "B_2_b_I"
+ └─ Secret "B_2_b_II"
+----
+
+And so on.
+
+In *practice*, however, most users will only have two Session types:
+
+* a default "system" one, and
+* a temporary one that may or may not exist, running in memory for the current login session
+
+and a single Collection, named `login` (and aliased to `default`, usually).
+
== Usage
+
Full documentation can be found via inline documentation. Either via the https://pkg.go.dev/r00t2.io/gosecret[pkg.go.dev documentation^] or https://pkg.go.dev/golang.org/x/tools/cmd/godoc[`godoc`^] (or `go doc`) in the source root.
////
diff --git a/doc.go b/doc.go
index a554e04..857a129 100644
--- a/doc.go
+++ b/doc.go
@@ -1,7 +1,7 @@
// See LICENSE in source root directory for copyright and licensing information.
/*
-Package libsecret is(/was originally) a fork of go-libsecret (see https://github.com/gsterjov/go-libsecret
+Package gosecret is(/was originally) a fork of go-libsecret (see https://github.com/gsterjov/go-libsecret
and https://pkg.go.dev/github.com/gsterjov/go-libsecret).
It was forked in order to present bugfixes, actually document the library, conform to more Go-like patterns, and
@@ -10,11 +10,13 @@ As such, hopefully this library should serve as a more effective libsecret/Secre
Backwards Compatibility
-Version series `v0.X.X` of this library promises full and non-breaking backwards compatibility/drop-in support of API interaction with the original project.
+Version series `v0.X.X` of this library promises full and non-breaking backwards compatibility/drop-in
+support of API interaction with the original project.
The only changes should be internal optimizations, adding documentation, some file reorganizing, adding Golang module support,
etc. -- all transparent from the library API itself.
-To use this library as a replacement without significantly modifying your code, you can simply use a `replace` directive in your go.mod file:
+To use this library as a replacement without significantly modifying your code,
+you can simply use a `replace` directive in your go.mod file:
// ...
replace (
@@ -37,6 +39,61 @@ To use the new version,
To reflect the absolute breaking changes, the module name changes as well from `libsecret` to `gosecret`.
+SecretService Concepts
+
+For reference:
+
+- A Service allows one to operate on/with Session objects.
+
+- A Session allows one to operate on/with Collection objects.
+
+- A Collection allows one to operate on/with Item objects.
+
+- An Item allows one to operate on/with Secrets.
+
+(Secrets are considered "terminating objects" in this model, and contain actual secret value(s) and metadata).
+
+Various interactions are handled by Prompts.
+
+So the object hierarchy in THEORY looks kind of like this:
+
+ Service
+ ├─ Session "A"
+ │ ├─ Collection "A.1"
+ │ │ ├─ Item "A.1.a"
+ │ │ │ ├─ Secret "A_1_a_I"
+ │ │ │ └─ Secret "A_1_a_II"
+ │ │ └─ Item "A.1.b"
+ │ │ ├─ Secret "A_1_b_I"
+ │ │ └─ Secret "A_1_b_II"
+ │ └─ Collection "A.2"
+ │ ├─ Item "A.2.a"
+ │ │ ├─ Secret "A_2_a_I"
+ │ │ └─ Secret "A_2_a_II"
+ │ └─ Item "A.2.b"
+ │ ├─ Secret "A_2_b_I"
+ │ └─ Secret "A_2_b_II"
+ └─ Session "B"
+ ├─ Collection "B.1"
+ │ ├─ Item "B.1.a"
+ │ │ ├─ Secret "B_1_a_I"
+ │ │ └─ Secret "B_1_a_II"
+ │ └─ Item "B.1.b"
+ │ ├─ Secret "B_1_b_I"
+ │ └─ Secret "B_1_b_II"
+ └─ Collection "B.2"#
+ ├─ Item "B.2.a"
+ │ ├─ Secret "B_2_a_I"
+ │ └─ Secret "B_2_a_II"
+ └─ Item "B.2.b"
+ ├─ Secret "B_2_b_I"
+ └─ Secret "B_2_b_II"
+
+And so on.
+In PRACTICE, however, most users will only have two Session types
+(a default "system" one and a temporary one that may or may not exist, running in memory for the current login session)
+and a single Collection, named "login" (and aliased to "default", usually).
+
Usage
Full documentation can be found via inline documentation.