r00t2/gosecret
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

updating docs

Browse Source
This commit is contained in:
brent s. 2021-11-27 02:26:51 -05:00
parent b96f17fb19
commit 55e740793a
Signed by: bts
GPG Key ID: 8C004C2F93481F6B
4 changed files with 164 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
.idea/codeStyles/Project.xml Normal file
View File

@ -0,0 +1,33 @@
<component name="ProjectCodeStyleConfiguration">
<code_scheme name="Project" version="173">
<option name="OTHER_INDENT_OPTIONS">
<value>
<option name="USE_TAB_CHARACTER" value="true" />
<option name="SMART_TABS" value="true" />
</value>
</option>
<GoCodeStyleSettings>
<option name="USE_BACK_QUOTES_FOR_IMPORTS" value="true" />
<option name="ADD_PARENTHESES_FOR_SINGLE_IMPORT" value="true" />
<option name="REMOVE_REDUNDANT_IMPORT_ALIASES" value="true" />
<option name="ADD_LEADING_SPACE_TO_COMMENTS" value="true" />
<option name="MOVE_ALL_STDLIB_IMPORTS_IN_ONE_GROUP" value="true" />
<option name="GROUP_STDLIB_IMPORTS" value="true" />
<option name="WRAP_COMP_LIT" value="5" />
<option name="WRAP_FUNC_PARAMS" value="5" />
<option name="WRAP_FUNC_RESULT" value="5" />
</GoCodeStyleSettings>
<XML>
<option name="XML_KEEP_WHITESPACES" value="true" />
<option name="XML_KEEP_WHITE_SPACES_INSIDE_CDATA" value="true" />
</XML>
<codeStyleSettings language="XML">
<option name="WRAP_ON_TYPING" value="1" />
</codeStyleSettings>
<codeStyleSettings language="go">
<option name="RIGHT_MARGIN" value="180" />
<option name="CALL_PARAMETERS_WRAP" value="5" />
<option name="WRAP_ON_TYPING" value="1" />
</codeStyleSettings>
</code_scheme>
</component>

5
.idea/codeStyles/codeStyleConfig.xml Normal file
View File

@ -0,0 +1,5 @@
<component name="ProjectCodeStyleConfiguration">
<state>
<option name="PREFERRED_PROJECT_CODE_STYLE" value="custom" />
</state>
</component>

66
README.adoc
View File

@ -1,6 +1,5 @@
= libsecret/gosecret
Brent Saner <bts@square-r00t.net>
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:
@ -43,6 +43,7 @@ replace (
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.

////

63
doc.go
View File

@ -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.