Class: Infrawrench::SharedConsolesNamespace

Inherits:
Object
  • Object
show all
Defined in:
lib/infrawrench/client.rb,
sig/infrawrench/sdk.rbs

Overview

client.shared_consoles

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(transport) ⇒ SharedConsolesNamespace

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of SharedConsolesNamespace.

Parameters:



14319
14320
14321
14322
14323
 
# File 'lib/infrawrench/client.rb', line 14319

def initialize(transport)
  @transport = transport
  @invites = SharedConsolesInvitesNamespace.new(@transport)
  @participants = SharedConsolesParticipantsNamespace.new(@transport)
end

Instance Attribute Details

#invites ⇒ SharedConsolesInvitesNamespace (readonly)

Returns client.shared_consoles.invites.

Returns:



14313
14314
14315
 
# File 'lib/infrawrench/client.rb', line 14313

def invites
  @invites
end

#participants ⇒ SharedConsolesParticipantsNamespace (readonly)

Returns client.shared_consoles.participants.

Returns:



14315
14316
14317
 
# File 'lib/infrawrench/client.rb', line 14315

def participants
  @participants
end

Instance Method Details

#create(org_id: nil, body: nil, request_options: nil) ⇒ Hash

Share a live SSH session

Opens a share on a session you already have running and mints its first invite. You become the driver.

Returns 409 console_not_here when the pty is held by a different server replica than the one answering this call — reopen the terminal and share again. Writing the share anyway would produce a link that authorises correctly and then finds nothing to attach to.

Requires resources:execute — the same permission as opening the terminal. Closed to API keys: sharing a shell is an act a person performs.

Requires permission: resources:execute.

POST /api/org/orgId/shared-consoles

Raises on 400: Bad request

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • body (Hash, nil) (defaults to: nil) —

    Request body, shaped as CreateSharedConsole.

  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • org_id: (String, nil) (defaults to: nil)
  • body: (create_shared_console, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as SharedConsoleCreated — see sig/infrawrench/sdk.rbs.

Raises:



14355
14356
14357
14358
14359
14360
14361
14362
14363
 
# File 'lib/infrawrench/client.rb', line 14355

def create(org_id: nil, body: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/shared-consoles",
    path_params: { "orgId" => org_id },
    body: body,
    request_options: request_options
  )
end

#delete(console_id:, org_id: nil, request_options: nil) ⇒ Hash

Revoke a share

Disconnects every guest and stops the fan-out. The sharer's own SSH session carries on — revoking a share is not killing a terminal.

The sharer or a holder of org:settings:write. Deliberately does not require resources:execute: ending access must never be gated on still holding the access, or an owner whose role was narrowed mid-incident could not close the session they opened.

DELETE /api/org/orgId/shared-consoles/consoleId

Raises on 403: Forbidden

Raises on 404: Not found

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • console_id (String)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • console_id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as Ok — see sig/infrawrench/sdk.rbs.

Raises:



14387
14388
14389
14390
14391
14392
14393
14394
 
# File 'lib/infrawrench/client.rb', line 14387

def delete(console_id:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "DELETE",
    path: "/api/org/{orgId}/shared-consoles/{consoleId}",
    path_params: { "orgId" => org_id, "consoleId" => console_id },
    request_options: request_options
  )
end

#get(console_id:, org_id: nil, request_options: nil) ⇒ Hash

Get one shared console

Visible to participants and to anyone who could revoke it (the sharer, or a holder of org:settings:write). Others get 404 — that a named colleague has a root shell open on a named production host right now is operational information.

Requires permission: resources:execute.

GET /api/org/orgId/shared-consoles/consoleId

Raises on 404: Not found

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • console_id (String)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • console_id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as SharedConsoleState — see sig/infrawrench/sdk.rbs.

Raises:



14416
14417
14418
14419
14420
14421
14422
14423
 
# File 'lib/infrawrench/client.rb', line 14416

def get(console_id:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "GET",
    path: "/api/org/{orgId}/shared-consoles/{consoleId}",
    path_params: { "orgId" => org_id, "consoleId" => console_id },
    request_options: request_options
  )
end

#handover(console_id:, org_id: nil, body: nil, request_options: nil) ⇒ Hash

Move the keyboard to another participant

Authorised by the current driver (the keyboard is theirs to give) or by the sharer (it is their box, and asking permission from somebody who has stopped responding is not a control). An observer cannot promote themselves — that is /request-driver.

Two simultaneous grants cannot both win: the database's partial unique index decides the order, and the loser gets 409 driver-race-lost.

The pty resizes to the new driver's viewport; everyone else letterboxes.

Requires permission: resources:execute.

POST /api/org/orgId/shared-consoles/consoleId/handover

Raises on 400: Bad request

Raises on 403: Forbidden

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • console_id (String)
  • body (Hash, nil) (defaults to: nil) —

    Request body, shaped as Hash.

  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • console_id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • body: ({ "participantId" => String }, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as SharedConsoleState — see sig/infrawrench/sdk.rbs.

Raises:



14457
14458
14459
14460
14461
14462
14463
14464
14465
 
# File 'lib/infrawrench/client.rb', line 14457

def handover(console_id:, org_id: nil, body: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/shared-consoles/{consoleId}/handover",
    path_params: { "orgId" => org_id, "consoleId" => console_id },
    body: body,
    request_options: request_options
  )
end

#join(console_id:, org_id: nil, body: nil, request_options: nil) ⇒ Hash

Redeem an invite and join

Admission needs live org membership and resources:execute — the invite is a locator, never a capability, so a leaked link admits nobody who could not have opened the shell themselves.

The invite is consumed by the first person it admits. Somebody already on the console resumes their own row without a token, so a reload costs them nothing and obliges the sharer to mint nothing. New joiners always start as observers whatever the link said.

Audit-logged as shared_console.join, and written onto the recording's timeline as an asciicast marker.

Requires permission: resources:execute.

POST /api/org/orgId/shared-consoles/consoleId/join

Raises on 400: Bad request

Raises on 403: Forbidden

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • console_id (String)
  • body (Hash, nil) (defaults to: nil) —

    Request body, shaped as Hash.

  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • console_id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • body: ({ "token" => String }, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as SharedConsoleJoined — see sig/infrawrench/sdk.rbs.

Raises:



14501
14502
14503
14504
14505
14506
14507
14508
14509
 
# File 'lib/infrawrench/client.rb', line 14501

def join(console_id:, org_id: nil, body: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/shared-consoles/{consoleId}/join",
    path_params: { "orgId" => org_id, "consoleId" => console_id },
    body: body,
    request_options: request_options
  )
end

#leave(console_id:, org_id: nil, request_options: nil) ⇒ Hash

Leave a shared console

Steps you off without ending the session. Your row survives, so the same invite is not needed again. Deliberately does not require resources:execute: giving access up must never be gated on still holding it.

POST /api/org/orgId/shared-consoles/consoleId/leave

Raises on 404: Not found

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • console_id (String)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • console_id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as SharedConsoleState — see sig/infrawrench/sdk.rbs.

Raises:



14529
14530
14531
14532
14533
14534
14535
14536
 
# File 'lib/infrawrench/client.rb', line 14529

def leave(console_id:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/shared-consoles/{consoleId}/leave",
    path_params: { "orgId" => org_id, "consoleId" => console_id },
    request_options: request_options
  )
end

#list(org_id: nil, request_options: nil) ⇒ Array<Hash>

List sessions currently shared

Live shared SSH sessions in this organization, with who is on each. Only cloud SSH can be shared: those sessions are already proxied by the server, so fanning the pty out to a second socket is a consumer of a stream it holds. A desktop session dialling a host directly never reaches the server and cannot be shared.

Requires permission: resources:execute.

GET /api/org/orgId/shared-consoles

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Array<Hash>) —

    Parsed JSON, shaped as Array<SharedConsoleSummary> — see sig/infrawrench/sdk.rbs.

Raises:



14556
14557
14558
14559
14560
14561
14562
14563
 
# File 'lib/infrawrench/client.rb', line 14556

def list(org_id: nil, request_options: nil)
  @transport.request(
    http_method: "GET",
    path: "/api/org/{orgId}/shared-consoles",
    path_params: { "orgId" => org_id },
    request_options: request_options
  )
end

#request_driver(console_id:, org_id: nil, request_options: nil) ⇒ Hash

Ask for the keyboard

Raises a flag the driver and the sharer can see. Grants nothing on its own — that is the point.

Requires permission: resources:execute.

POST /api/org/orgId/shared-consoles/consoleId/request-driver

Raises on 403: Forbidden

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • console_id (String)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • console_id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as SharedConsoleState — see sig/infrawrench/sdk.rbs.

Raises:



14587
14588
14589
14590
14591
14592
14593
14594
 
# File 'lib/infrawrench/client.rb', line 14587

def request_driver(console_id:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/shared-consoles/{consoleId}/request-driver",
    path_params: { "orgId" => org_id, "consoleId" => console_id },
    request_options: request_options
  )
end