updating docs
This commit is contained in:
parent
b96f17fb19
commit
55e740793a
GPG Key ID:
8C004C2F93481F6B
|
|
@ -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>
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
<component name="ProjectCodeStyleConfiguration">
|
||||
<state>
|
||||
<option name="PREFERRED_PROJECT_CODE_STYLE" value="custom" />
|
||||
</state>
|
||||
</component>
|
||||
68
README.adoc
68
README.adoc
|
|
@ -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:
|
||||
|
|
@ -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.
|
||||
|
||||
////
|
||||
|
|
|
|||
63
doc.go
63
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue