Documentation
¶
Overview ¶
Package ref turns the flexible references the CLI accepts into concrete Microsoft Graph ids: Teams deep links, "Team/Channel/Message" name paths, "@person", e-mail addresses, aliases and raw ids.
PLAN.md "Smart references" is the specification for this package. Its two halves are the parser (ParseURL, Parse) and the resolver (Resolver), which is the only part that talks to Graph or the entity cache.
Everything here is tolerant by design. A pasted "Copy link" URL may carry the channel id raw (19:...@thread.tacv2) or percent-encoded, its query parameters in any order, and parameters we do not know; the parser accepts all of it and the resolver rejects only what cannot be resolved at all.
Index ¶
- func LooksLikeChannelID(s string) bool
- func LooksLikeChatID(s string) bool
- func PersonKey(raw string) string
- type Chooser
- type Error
- type Kind
- type Ref
- type Resolver
- func (r *Resolver) Cache() *store.EntityCache
- func (r *Resolver) Channel(ctx context.Context, raw, teamHint string) (Ref, error)
- func (r *Resolver) Chat(ctx context.Context, raw string) (Ref, error)
- func (r *Resolver) Client() *graph.Client
- func (r *Resolver) Message(ctx context.Context, raw, teamHint string) (Ref, error)
- func (r *Resolver) Person(ctx context.Context, raw string) (Ref, error)
- func (r *Resolver) PersonChat(ctx context.Context, raw string) (Ref, error)
- func (r *Resolver) PersonID(ctx context.Context, raw string) (string, error)
- func (r *Resolver) Team(ctx context.Context, raw string) (Ref, error)
- type ResolverOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LooksLikeChannelID ¶
LooksLikeChannelID reports whether s has the shape of a channel id.
func LooksLikeChatID ¶
LooksLikeChatID reports whether s has the shape of a chat id. Graph chat ids start with "19:" and end in a thread marker; a channel id shares the prefix but uses @thread.tacv2, so the suffix is what separates the two families (refs/msteams/msteams-platform/concepts/build-and-test/deep-link-teams.md).
Types ¶
type Chooser ¶
type Chooser interface {
Interactive() bool
Choose(question string, options []string) (int, error)
}
Chooser picks one of several candidates on a terminal. The CLI implements it; when it is nil, or says the session is not interactive, the resolver fails with the candidate list instead of guessing - which is what PLAN.md requires of non-interactive mode.
type Error ¶
Error is a reference error: a message, the exit code it maps to, and the one-line fix to print under it.
type Kind ¶
type Kind string
Kind is what a reference points at.
const ( KindUnknown Kind = "" KindTeam Kind = "team" KindChannel Kind = "channel" KindChat Kind = "chat" KindMessage Kind = "message" KindUser Kind = "user" KindFile Kind = "file" )
Reference kinds. KindUnknown is what a parse produces when the string is a bare Graph id whose meaning depends on the command that accepted it ("19:..." is a channel id in one command and a chat id in another), so the resolver, not the parser, decides.
type Ref ¶
type Ref struct {
Kind Kind
// Raw is the input, kept for error messages and for the entity cache key.
Raw string
// TeamID and TeamName come from a deep link (groupId, teamName or the name
// path's first element).
TeamID string
TeamName string
// ChannelID and ChannelName come from a deep link or a name path.
ChannelID string
ChannelName string
// ChatID is a chat's 19:... id, from a deep link or a raw id; ChatTopic is
// the display name when the chat was matched by one.
ChatID string
ChatTopic string
// MessageID and ParentMessageID are the message a link or a name path points
// at. InChat records that the message lives in a chat: /l/message/ carries
// both families and the query string is the only discriminator
// (refs/msteams/msteams-platform/concepts/build-and-test/deep-link-teams.md,
// "Deep link to navigate to chat messages").
MessageID string
ParentMessageID string
InChat bool
// User is the person form as typed: a display name, an e-mail, a UPN or a
// user id. UserID, UserName and UserMail are filled in by the resolver.
User string
UserID string
UserName string
UserMail string
// IsEmail records that User looks like an address, which resolves faster
// (an exact GET /users/{id} instead of a directory search).
IsEmail bool
// FileID is a /l/file/ link's file id.
FileID string
// Path is a name path split on "/": ["Engineering", "General"] or
// ["Engineering", "General", "1758..."].
Path []string
// Target is what an alias points at, when the reference came from one; it is
// empty for a direct reference. Raw stays the text the user typed, so an error
// message quotes what they wrote, while a name lookup searches Target: an alias
// for a chat topic has to match the topic, not the alias name (PLAN.md:168).
Target string
// Host is the deep link's host, so the parser can accept the newer
// teams.cloud.microsoft host defensively (PLAN.md:164).
Host string
// TenantID is the deep link's tenantId parameter, when present.
TenantID string
}
Ref is a parsed, unresolved reference. Only the fields that the input carried are set; everything else is filled in by the Resolver.
func Parse ¶
Parse classifies a reference string without touching the network. It is the first half of PLAN.md's "Smart references": the resolver then turns the classification into ids. The classification is deliberately loose, because the same string means different things to different commands: a bare 19:...@thread.v2 is a chat id to `chat read` and nothing useful to `team show`.
func ParseURL ¶
ParseURL parses a Teams deep link. ok is false when raw is not a Teams URL at all (the caller then tries the other reference shapes).
ok is true for every URL that is shaped like a Teams deep link, even when the parser refuses it: err is then set for the families the CLI cannot open (/l/app, /l/entity, /l/task, /l/call, /l/meeting*, PLAN.md:164), so the caller maps one error class to exit code 2 instead of silently treating a pasted URL as a raw id. A message link without groupId parses with an empty TeamID: the resolver decides whether to fail with exit 4 or ask for --team (PLAN.md:164 and refs/INDEX.md section 5).
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver turns references into Graph ids. It is the only part of this package that talks to Graph or to local state.
func (*Resolver) Cache ¶
func (r *Resolver) Cache() *store.EntityCache
Cache exposes the entity cache, so the CLI can persist it after a run.
func (*Resolver) Channel ¶
Channel resolves a channel reference. teamHint is the --team flag, which a channel-message link without groupId needs: every channel route takes the team id, and there is no channel-to-team lookup (PLAN.md:164).
func (*Resolver) Chat ¶
Chat resolves a chat reference: a chat id, a Teams chat link, a person (which means the 1:1 chat with them) or a chat topic.
func (*Resolver) Client ¶
Client exposes the Graph client the resolver was built with, so a command can keep using the same one.
func (*Resolver) Message ¶
Message resolves a message reference. A channel message needs its team and channel; a chat message needs its chat. A bare message id is rejected, because no Graph route can find the container from the id alone.
func (*Resolver) PersonChat ¶
PersonChat returns the 1:1 chat id with a person. PLAN.md:166 documents why this is a scan and not a lookup: there is no person-to-chat API. The result is cached for a week, so the scan runs once per person.
type ResolverOptions ¶
type ResolverOptions struct {
// Client is the Graph client every lookup uses.
Client *graph.Client
// Cache is the per-profile entity cache (may be nil in tests).
Cache *store.EntityCache
// Aliases is the per-profile alias table, name to target.
Aliases map[string]string
// Refresh bypasses the cache, for --refresh.
Refresh bool
// Chooser is the interactive picker; nil never prompts.
Chooser Chooser
// Now supplies the clock for cache metadata.
Now func() time.Time
// Debugf logs cache hits and lookups under --verbose.
Debugf func(format string, args ...any)
}
ResolverOptions configures a Resolver.