x/ref: Restructure services/agent to follow conventions.
Here are the renamings:
services/agent/*.go -> services/agent/agentlib
services/agent/server -> services/agent/internal/server
services/agent/server/wire.vdl -> services/agent/wire.vdl
For reference, our convention is as follows:
services/gizmo - VDL files, the "API"
services/gizmo/gizmo - Client tool binary
services/gizmo/gizmod - Server daemon binary
services/gizmo/gizmolib - Library used by others
Change-Id: Ia0a821f142944a3ce18462e3f084014e47700463
diff --git a/services/agent/agentd/main.go b/services/agent/agentd/main.go
index 60bccd3..f5d69e0 100644
--- a/services/agent/agentd/main.go
+++ b/services/agent/agentd/main.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon agentd holds a private key in memory and makes it available to a
+// subprocess via the agent protocol.
package main
import (
@@ -23,8 +25,8 @@
"v.io/x/ref/envvar"
vsecurity "v.io/x/ref/lib/security"
vsignals "v.io/x/ref/lib/signals"
- "v.io/x/ref/services/agent"
- "v.io/x/ref/services/agent/server"
+ "v.io/x/ref/services/agent/agentlib"
+ "v.io/x/ref/services/agent/internal/server"
_ "v.io/x/ref/profiles"
)
@@ -108,7 +110,7 @@
vlog.Panic("failed to set principal for ctx: %v", err)
}
- if err = os.Setenv(agent.FdVarName, "3"); err != nil {
+ if err = os.Setenv(agentlib.FdVarName, "3"); err != nil {
vlog.Fatalf("setenv: %v", err)
}
diff --git a/services/agent/agent_test.go b/services/agent/agentlib/agent_test.go
similarity index 96%
rename from services/agent/agent_test.go
rename to services/agent/agentlib/agent_test.go
index 2c3c17d..a8a70e5 100644
--- a/services/agent/agent_test.go
+++ b/services/agent/agentlib/agent_test.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-package agent_test
+package agentlib_test
import (
"fmt"
@@ -17,8 +17,8 @@
"v.io/v23"
"v.io/v23/context"
"v.io/v23/security"
- "v.io/x/ref/services/agent"
- "v.io/x/ref/services/agent/server"
+ "v.io/x/ref/services/agent/agentlib"
+ "v.io/x/ref/services/agent/internal/server"
"v.io/x/ref/test"
"v.io/x/ref/test/modules"
"v.io/x/ref/test/testutil"
@@ -44,9 +44,9 @@
return nil, err
}
if cached {
- return agent.NewAgentPrincipal(ctx, fd, v23.GetClient(ctx))
+ return agentlib.NewAgentPrincipal(ctx, fd, v23.GetClient(ctx))
} else {
- return agent.NewUncachedPrincipal(ctx, fd, v23.GetClient(ctx))
+ return agentlib.NewUncachedPrincipal(ctx, fd, v23.GetClient(ctx))
}
}
diff --git a/services/agent/agent_v23_test.go b/services/agent/agentlib/agent_v23_test.go
similarity index 99%
rename from services/agent/agent_v23_test.go
rename to services/agent/agentlib/agent_v23_test.go
index 33f60eb..daa9185 100644
--- a/services/agent/agent_v23_test.go
+++ b/services/agent/agentlib/agent_v23_test.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-package agent_test
+package agentlib_test
import (
"bytes"
diff --git a/services/agent/client.go b/services/agent/agentlib/client.go
similarity index 97%
rename from services/agent/client.go
rename to services/agent/agentlib/client.go
index 64cd670..f6aaeba 100644
--- a/services/agent/client.go
+++ b/services/agent/agentlib/client.go
@@ -2,9 +2,9 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package agent provides a client for communicating with an "Agent"
-// process holding the private key for an identity.
-package agent
+// Package agentlib implements a client for communicating with an agentd process
+// holding the private key for an identity.
+package agentlib
import (
"fmt"
diff --git a/services/agent/peer_test.go b/services/agent/agentlib/peer_test.go
similarity index 95%
rename from services/agent/peer_test.go
rename to services/agent/agentlib/peer_test.go
index 3c5ff13..ea5959d 100644
--- a/services/agent/peer_test.go
+++ b/services/agent/agentlib/peer_test.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-package agent
+package agentlib
import (
"v.io/v23/context"
diff --git a/services/agent/v23_test.go b/services/agent/agentlib/v23_test.go
similarity index 97%
rename from services/agent/v23_test.go
rename to services/agent/agentlib/v23_test.go
index a6b4044..3e4061b 100644
--- a/services/agent/v23_test.go
+++ b/services/agent/agentlib/v23_test.go
@@ -4,7 +4,7 @@
// This file was auto-generated via go generate.
// DO NOT UPDATE MANUALLY
-package agent_test
+package agentlib_test
import "fmt"
import "testing"
diff --git a/services/agent/server/server.go b/services/agent/internal/server/server.go
similarity index 97%
rename from services/agent/server/server.go
rename to services/agent/internal/server/server.go
index 6710b1a..46b5e0b 100644
--- a/services/agent/server/server.go
+++ b/services/agent/internal/server/server.go
@@ -26,12 +26,13 @@
"v.io/v23/verror"
"v.io/x/lib/vlog"
vsecurity "v.io/x/ref/lib/security"
+ "v.io/x/ref/services/agent"
"v.io/x/ref/services/agent/internal/unixfd"
)
const PrincipalHandleByteSize = sha512.Size
-const pkgPath = "v.io/x/ref/services/agent/server"
+const pkgPath = "v.io/x/ref/services/agent/internal/server"
// Errors
var (
@@ -261,9 +262,8 @@
}
spec := rpc.ListenSpec{Addrs: rpc.ListenAddrs(a)}
if _, err = s.Listen(spec); err == nil {
- agent := &agentd{w.newID(), w, principal, ctx}
- serverAgent := AgentServer(agent)
- err = s.Serve("", serverAgent, nil)
+ server := agent.AgentServer(&agentd{w.newID(), w, principal, ctx})
+ err = s.Serve("", server, nil)
}
ack()
}
@@ -430,7 +430,7 @@
return a.principal.Roots().DebugString(), nil
}
-func (a agentd) NotifyWhenChanged(call AgentNotifyWhenChangedServerCall) error {
+func (a agentd) NotifyWhenChanged(call agent.AgentNotifyWhenChangedServerCall) error {
ch := a.w.register(a.id)
defer a.w.unregister(a.id, ch)
for {
diff --git a/services/agent/server/sharing.go b/services/agent/internal/server/sharing.go
similarity index 100%
rename from services/agent/server/sharing.go
rename to services/agent/internal/server/sharing.go
diff --git a/services/agent/server/sharing_test.go b/services/agent/internal/server/sharing_test.go
similarity index 100%
rename from services/agent/server/sharing_test.go
rename to services/agent/internal/server/sharing_test.go
diff --git a/services/agent/internal/test_principal/main.go b/services/agent/internal/test_principal/main.go
index d60f430..06bbc52 100644
--- a/services/agent/internal/test_principal/main.go
+++ b/services/agent/internal/test_principal/main.go
@@ -16,7 +16,7 @@
"v.io/v23"
"v.io/v23/security"
"v.io/x/ref/envvar"
- "v.io/x/ref/services/agent"
+ "v.io/x/ref/services/agent/agentlib"
_ "v.io/x/ref/profiles"
)
@@ -56,8 +56,8 @@
if got := os.Getenv(envvar.Credentials); len(got) != 0 {
errorf("%v environment variable is unexpectedly set", envvar.Credentials)
}
- if got := os.Getenv(agent.FdVarName); len(got) == 0 {
- errorf("%v environment variable is not set", agent.FdVarName)
+ if got := os.Getenv(agentlib.FdVarName); len(got) == 0 {
+ errorf("%v environment variable is not set", agentlib.FdVarName)
}
// A pristine agent has a single blessing "agent_principal" (from agentd/main.go).
if blessings := p.BlessingsInfo(p.BlessingStore().Default()); len(blessings) != 1 {
diff --git a/services/agent/keymgr/client.go b/services/agent/keymgr/client.go
index d6c34a3..01098de 100644
--- a/services/agent/keymgr/client.go
+++ b/services/agent/keymgr/client.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package keymgr provides a client for the Device Manager to manage keys in
-// the "Agent" process.
+// Package keymgr implements a client for deviced to manage keys in the agentd
+// process.
package keymgr
import (
@@ -14,8 +14,8 @@
"v.io/v23/context"
"v.io/v23/verror"
+ "v.io/x/ref/services/agent/internal/server"
"v.io/x/ref/services/agent/internal/unixfd"
- "v.io/x/ref/services/agent/server"
)
const pkgPath = "v.io/x/ref/services/agent/keymgr"
diff --git a/services/agent/keymgr/keymgr_test.go b/services/agent/keymgr/keymgr_test.go
index 1e2a521..15348b6 100644
--- a/services/agent/keymgr/keymgr_test.go
+++ b/services/agent/keymgr/keymgr_test.go
@@ -15,8 +15,8 @@
"v.io/v23"
"v.io/v23/context"
"v.io/v23/security"
- "v.io/x/ref/services/agent"
- "v.io/x/ref/services/agent/server"
+ "v.io/x/ref/services/agent/agentlib"
+ "v.io/x/ref/services/agent/internal/server"
"v.io/x/ref/test"
_ "v.io/x/ref/profiles"
@@ -72,7 +72,7 @@
return nil, err
}
- return agent.NewAgentPrincipal(ctx, fd, v23.GetClient(ctx))
+ return agentlib.NewAgentPrincipal(ctx, fd, v23.GetClient(ctx))
}
func TestSigning(t *testing.T) {
diff --git a/services/agent/server/wire.vdl b/services/agent/wire.vdl
similarity index 95%
rename from services/agent/server/wire.vdl
rename to services/agent/wire.vdl
index c025f6f..4c93acb 100644
--- a/services/agent/server/wire.vdl
+++ b/services/agent/wire.vdl
@@ -2,10 +2,10 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package server provides a server which keeps a principal in memory
-// and allows clients to use that principal.
+// Package agent defines an interface to keep a private key in memory, and for
+// clients to have access to the private key.
//
-// PROTOCOL
+// Protocol
//
// The agent starts processes with the VEYRON_AGENT_FD set to one end of a
// unix domain socket. To connect to the agent, a client should create
@@ -30,9 +30,7 @@
// The protocol also has limited support for caching: A client can
// request notification when any other client modifies the principal so it
// can flush the cache. See NotifyWhenChanged for details.
-
-
-package server
+package agent
import (
"v.io/v23/security"
diff --git a/services/agent/server/wire.vdl.go b/services/agent/wire.vdl.go
similarity index 93%
rename from services/agent/server/wire.vdl.go
rename to services/agent/wire.vdl.go
index 16af73a..f01c204 100644
--- a/services/agent/server/wire.vdl.go
+++ b/services/agent/wire.vdl.go
@@ -5,7 +5,35 @@
// This file was auto-generated by the vanadium vdl tool.
// Source: wire.vdl
-package server
+// Package agent defines an interface to keep a private key in memory, and for
+// clients to have access to the private key.
+//
+// Protocol
+//
+// The agent starts processes with the VEYRON_AGENT_FD set to one end of a
+// unix domain socket. To connect to the agent, a client should create
+// a unix domain socket pair. Then send one end of the socket to the agent
+// with 1 byte of data. The agent will then serve the Agent service on
+// the received socket, using SecurityNone.
+//
+// The agent also supports an optional mode where it can manage multiple principals.
+// Typically this is only used by Device Manager. In this mode, VEYRON_AGENT_FD
+// will be 3, and there will be another socket at fd 4.
+// Creating a new principal is similar to connecting to to agent: create a socket
+// pair and send one end on fd 4 with 1 byte of data.
+// Set the data to 1 to request the principal only be stored in memory.
+// The agent will create a new principal and respond with a principal handle on fd 4.
+// To connect using a previously created principal, create a socket pair and send
+// one end with the principal handle as data on fd 4. The agent will not send a
+// response on fd 4.
+// In either, you can use the normal process to connect to an agent over the
+// other end of the pair. Typically you would pass the other end to a child
+// process and set VEYRON_AGENT_FD so it knows to connect.
+//
+// The protocol also has limited support for caching: A client can
+// request notification when any other client modifies the principal so it
+// can flush the cache. See NotifyWhenChanged for details.
+package agent
import (
// VDL system imports
@@ -393,7 +421,7 @@
// descAgent hides the desc to keep godoc clean.
var descAgent = rpc.InterfaceDesc{
Name: "Agent",
- PkgPath: "v.io/x/ref/services/agent/server",
+ PkgPath: "v.io/x/ref/services/agent",
Methods: []rpc.MethodDesc{
{
Name: "Bless",
