host

type AuthorizedKey struct {
	PublicKeys []ssh.PublicKey
	Comment    string
}

type CredentialMode int

type Fetcher struct {
	Logger *slog.Logger
	// Transport, when set, is the base round tripper for every request. Tests
	// use it to trust httptest certificates; production leaves it nil.
	Transport http.RoundTripper
}

type Host struct {
	Host              string
	KeepAliveDuration time.Duration
	Command           []string
	ForceCommand      []string
	Signers           []ssh.Signer
	// HostKey is the key the embedded sshd presents on both its doors and
	// the key the relay is told to expect from this host. A session's key,
	// not the operator's: Signers authenticate the tunnel and are used for
	// nothing else. Left nil, Run generates one for that run and does not
	// keep it, so a Host run twice presents two keys; a caller that needs
	// the public half before Run — the CLI, to pin its own attach — sets it
	// and it is used as given.
	HostKey                 ssh.Signer
	HostKeyCallback         ssh.HostKeyCallback
	AuthorizedKeys          []*AuthorizedKey
	AdminSocketFile         string
	SessionCreatedCallback  func(context.Context, *api.GetSessionResponse) error
	ClientJoinedCallback    func(*api.Client)
	ClientLeftCallback      func(*api.Client)
	Logger                  *slog.Logger
	ReadOnly                bool
	AllowLocalTCPForwarding bool
	// ProxyURL, when non-nil, routes the connection to the upterm server
	// through an HTTP proxy.
	ProxyURL   *url.URL
	PtySize    termsize.Size
	PinPtySize bool
	Term       string

	// AttachSocketFile is where the local attach door is bound. Like
	// AdminSocketFile, supplying it means the caller manages the path and
	// no name is claimed; left empty with AdminSocketFile set, no attach
	// door is served, which is how an embedder that will never attach a
	// terminal says so. Claimed with the name otherwise.
	AttachSocketFile string
	// AttachListeningCallback is called once the attach socket is bound,
	// before the command starts, with the path a client should dial. With
	// AwaitInitialClient set, this is the moment to attach.
	//
	// Called on Run's own goroutine, before the run.Group exists, so it must
	// not block: everything after it — the command, the guest door, the
	// readiness record — waits behind it.
	AttachListeningCallback func(attachSocket string)
	// CommandStartedCallback is called once the hosted command is running,
	// which with AwaitInitialClient is also the news that a client got
	// through the door. A caller whose own attach failed asks this whether
	// there is a session to leave alone.
	//
	// Called on the server's own goroutine, in front of everything the
	// command's start releases, so it must not block.
	CommandStartedCallback func()
	// SessionReadyCallback is called once the session's record has been
	// published: the admin socket is bound, the command is running, and the
	// record a reader would consult already carries the session ID and the
	// status handed to this callback. A caller that tells anyone else the
	// session is up says it here, not from CommandStartedCallback — the
	// command starting is one of the two facts readiness is made of, and the
	// record is written after both. A script that runs `upterm session info`
	// the instant it is told "ready" would otherwise be told "starting" by
	// the record.
	//
	// The status is what the record ended on, which is not always ready:
	// advanceStatus refuses to move a status backwards, so a tunnel lost
	// between the command starting and this write leaves "disconnected"
	// standing and the ready write is a no-op. The caller is told what the
	// record says rather than what this actor asked for, because the two
	// agreeing is the whole point of the callback.
	//
	// Not called when the record could not be published: the run fails
	// instead, so that nobody is told about a record that was never written.
	// With no session directory — an embedder that supplied its own admin
	// socket — there is no record, the two facts alone are it, and the
	// status is ready.
	//
	// Called once, on the readiness actor's own goroutine, after the write;
	// it must not block.
	SessionReadyCallback func(status string)
	// SessionClaimedCallback is called once the session's name is claimed,
	// with the directory that holds it, before the tunnel is dialled: the
	// first thing a caller can know about a session is its name and its
	// paths, and a caller that relays prompts wants them before any prompt.
	// Not called when AdminSocketFile was supplied, since nothing is claimed.
	//
	// Called on Run's own goroutine; it must not block.
	SessionClaimedCallback func(*sessiondir.Dir)
	// VersionWarningCallback is called when the server's version is
	// incompatible with this host's. Nil logs the mismatch and nothing more:
	// the daemon has no terminal to print to.
	VersionWarningCallback func(*version.CompatibilityResult)

	// AwaitInitialClient defers starting the command until the first host
	// client's output subscription is installed, and defers serving guests
	// until the command has started. Foreground use sets it: a command that
	// exits at once — `upterm host -- false` — would otherwise race the local
	// terminal's attach, and lose. Headless use leaves it off.
	AwaitInitialClient bool
	// InitialClientTimeout bounds that wait; zero means
	// internal.DefaultInitialClientTimeout.
	InitialClientTimeout time.Duration

	// StopGrace bounds each step of the command's teardown; zero means
	// internal.DefaultStopGrace.
	StopGrace time.Duration

	// JoinTimeout bounds the wait for the first guest, starting at readiness.
	// Zero waits forever. The session enforces it independently of its launcher;
	// a guest joining disarms it permanently, even after that guest leaves.
	JoinTimeout time.Duration

	// SFTP configuration
	SFTPDisabled          bool                   // Disable SFTP subsystem entirely (--no-sftp)
	SFTPPermissionChecker sftp.PermissionChecker // Optional: prompts user for SFTP permissions (nil = auto-allow)

	// Name is the session's local name. It determines the socket paths, so
	// they are known before the server is ever contacted. It is unrelated to
	// the server-assigned session ID in the connect string.
	//
	// Ignored when AdminSocketFile is set: supplying a socket is how a caller
	// says it is managing the paths itself, so Run claims no name and there is
	// nothing for this to name. SessionDir stays nil in that case, and no
	// record is published.
	Name string

	// SessionDir is claimed by Run and readable for as long as Run is
	// running. Run clears it on the way out: the directory is released by
	// then, a released Dir may not be touched again, and leaving it here
	// would be leaving a handle to a name that now belongs to whoever claimed
	// it next. Nil when AdminSocketFile was supplied, which is how tests
	// drive Host without taking a name.
	SessionDir *sessiondir.Dir
	// contains filtered or unexported fields
}

type SignerOptions struct {
	PrivateKeys []string
	// IdentitiesOnly makes PrivateKeys the whole identity set, as OpenSSH's
	// IdentitiesOnly does: every entry must resolve to a signer, and no
	// other key the agent holds is offered.
	IdentitiesOnly bool
	// Passphrase is asked for an encrypted key's passphrase. Nil prompts on
	// this process's terminal, which a daemon does not have.
	Passphrase func(file string) ([]byte, error)
	// OnSkip is told about a key file that was skipped and why. Nil is
	// silent, as SignersFromFiles always was.
	OnSkip func(file string, err error)
}

type UserRef struct {
	Provider string // "" for the raw-URL form
	User     string
	Host     string // host[:port] as written; "" means "provider default"
	URL      string // raw-URL form only: the complete .keys URL
	Raw      string // the original string, for error messages
	Mode     CredentialMode
}