soulfire.instance_connect.InstanceServiceSync¶
- class soulfire.instance_connect.InstanceServiceSync[source]¶
Bases:
ProtocolService for managing SoulFire instances. An instance is a permission and configuration compartment for independently controlled Minecraft bots, settings, accounts, proxies, and remote clients.
All operations require appropriate permissions: - CREATE_INSTANCE (global): Required to create new instances - READ_INSTANCE: Required to list and view instance details - UPDATE_INSTANCE_META: Required to change instance name/icon - UPDATE_INSTANCE_CONFIG: Required to modify settings, accounts, and proxies - DELETE_INSTANCE: Required to delete an instance - READ_INSTANCE_AUDIT_LOGS: Required to view audit logs - READ_BOT_INFO: Required to read account metadata
- get_or_create_instance(request: soulfire.instance_pb2.InstanceGetOrCreateRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceGetOrCreateRequest, soulfire.instance_pb2.InstanceGetOrCreateResponse], /) soulfire.instance_pb2.InstanceGetOrCreateResponse[source]¶
Gets or creates an instance owned by the caller without a list/create race.
- get_or_create_bot(request: soulfire.instance_pb2.InstanceGetOrCreateBotRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceGetOrCreateBotRequest, soulfire.instance_pb2.InstanceGetOrCreateBotResponse], /) soulfire.instance_pb2.InstanceGetOrCreateBotResponse[source]¶
Gets or creates a named bot account. Does not change its desired state.
- create_instance(request: soulfire.instance_pb2.InstanceCreateRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceCreateRequest, soulfire.instance_pb2.InstanceCreateResponse], /) soulfire.instance_pb2.InstanceCreateResponse[source]¶
Creates a new instance with the given friendly name. Requires: CREATE_INSTANCE global permission Returns: The UUID of the newly created instance Errors: INTERNAL if creation fails
- duplicate_instance(request: soulfire.instance_pb2.InstanceDuplicateRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceDuplicateRequest, soulfire.instance_pb2.InstanceDuplicateResponse], /) soulfire.instance_pb2.InstanceDuplicateResponse[source]¶
Copies the source configuration and icon into a new instance in one write. Includes accounts, proxies, and persistent metadata. Bots start stopped. Does not copy permissions, files, scripts, audit logs, or runtime state. Requires: CREATE_INSTANCE globally and READ_INSTANCE on the source. Errors: INVALID_ARGUMENT for invalid input, NOT_FOUND for a missing source.
- delete_instance(request: soulfire.instance_pb2.InstanceDeleteRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceDeleteRequest, soulfire.instance_pb2.InstanceDeleteResponse], /) soulfire.instance_pb2.InstanceDeleteResponse[source]¶
Permanently deletes an instance and all its data. Connected bots are stopped before the instance is deleted. This operation cannot be undone. Requires: DELETE_INSTANCE permission on the instance Errors: NOT_FOUND if instance does not exist
- list_instances(request: soulfire.instance_pb2.InstanceListRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceListRequest, soulfire.instance_pb2.InstanceListResponse], /) soulfire.instance_pb2.InstanceListResponse[source]¶
Lists all instances the current user has permission to view. Only instances where the user has READ_INSTANCE permission are returned. Returns summary information for each instance.
- get_instance_info(request: soulfire.instance_pb2.InstanceInfoRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceInfoRequest, soulfire.instance_pb2.InstanceInfoResponse], /) soulfire.instance_pb2.InstanceInfoResponse[source]¶
Gets detailed information about a specific instance. Supports conditional requests via if_modified_since to reduce bandwidth. Requires: READ_INSTANCE permission on the instance Returns: Full instance info or not_modified status Errors: NOT_FOUND if instance does not exist
- update_instance_meta(request: soulfire.instance_pb2.InstanceUpdateMetaRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateMetaRequest, soulfire.instance_pb2.InstanceUpdateMetaResponse], /) soulfire.instance_pb2.InstanceUpdateMetaResponse[source]¶
Updates instance metadata (friendly name or icon). Only one field can be updated per request. Requires: UPDATE_INSTANCE_META permission on the instance Errors: NOT_FOUND if instance does not exist
- update_instance_config(request: soulfire.instance_pb2.InstanceUpdateConfigRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateConfigRequest, soulfire.instance_pb2.InstanceUpdateConfigResponse], /) soulfire.instance_pb2.InstanceUpdateConfigResponse[source]¶
Replaces the entire instance configuration. Used primarily for profile import operations. For individual setting changes, use UpdateInstanceConfigEntry instead. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- update_instance_config_entry(request: soulfire.instance_pb2.InstanceUpdateConfigEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateConfigEntryRequest, soulfire.instance_pb2.InstanceUpdateConfigEntryResponse], /) soulfire.instance_pb2.InstanceUpdateConfigEntryResponse[source]¶
Updates a single configuration entry by namespace and key. More efficient than UpdateInstanceConfig for individual changes. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- add_instance_account(request: soulfire.instance_pb2.InstanceAddAccountRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAddAccountRequest, soulfire.instance_pb2.InstanceAddAccountResponse], /) soulfire.instance_pb2.InstanceAddAccountResponse[source]¶
Adds a Minecraft account to the instance. The account’s profile_id must be unique within the instance. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- remove_instance_account(request: soulfire.instance_pb2.InstanceRemoveAccountRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveAccountRequest, soulfire.instance_pb2.InstanceRemoveAccountResponse], /) soulfire.instance_pb2.InstanceRemoveAccountResponse[source]¶
Removes a Minecraft account from the instance by profile_id. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- update_instance_account(request: soulfire.instance_pb2.InstanceUpdateAccountRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateAccountRequest, soulfire.instance_pb2.InstanceUpdateAccountResponse], /) soulfire.instance_pb2.InstanceUpdateAccountResponse[source]¶
Updates an existing Minecraft account in the instance. The account is matched by profile_id and replaced. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- add_instance_accounts_batch(request: soulfire.instance_pb2.InstanceAddAccountsBatchRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAddAccountsBatchRequest, soulfire.instance_pb2.InstanceAddAccountsBatchResponse], /) soulfire.instance_pb2.InstanceAddAccountsBatchResponse[source]¶
Adds multiple Minecraft accounts to the instance in a single operation. More efficient than multiple AddInstanceAccount calls. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- replace_instance_accounts(request: soulfire.instance_pb2.InstanceReplaceAccountsRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceReplaceAccountsRequest, soulfire.instance_pb2.InstanceReplaceAccountsResponse], /) soulfire.instance_pb2.InstanceReplaceAccountsResponse[source]¶
Atomically replaces the account list and stops bots whose accounts were removed. Other instance configuration remains unchanged. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if the instance does not exist; INVALID_ARGUMENT for invalid accounts
- remove_instance_accounts_batch(request: soulfire.instance_pb2.InstanceRemoveAccountsBatchRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveAccountsBatchRequest, soulfire.instance_pb2.InstanceRemoveAccountsBatchResponse], /) soulfire.instance_pb2.InstanceRemoveAccountsBatchResponse[source]¶
Removes multiple Minecraft accounts from the instance by their profile_ids. More efficient than multiple RemoveInstanceAccount calls. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- add_instance_proxy(request: soulfire.instance_pb2.InstanceAddProxyRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAddProxyRequest, soulfire.instance_pb2.InstanceAddProxyResponse], /) soulfire.instance_pb2.InstanceAddProxyResponse[source]¶
Adds a proxy to the instance. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- remove_instance_proxy(request: soulfire.instance_pb2.InstanceRemoveProxyRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveProxyRequest, soulfire.instance_pb2.InstanceRemoveProxyResponse], /) soulfire.instance_pb2.InstanceRemoveProxyResponse[source]¶
Removes a proxy from the instance by its index. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist Errors: INVALID_ARGUMENT if index is out of bounds
- update_instance_proxy(request: soulfire.instance_pb2.InstanceUpdateProxyRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateProxyRequest, soulfire.instance_pb2.InstanceUpdateProxyResponse], /) soulfire.instance_pb2.InstanceUpdateProxyResponse[source]¶
Updates an existing proxy in the instance by its index. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist Errors: INVALID_ARGUMENT if index is out of bounds
- add_instance_proxies_batch(request: soulfire.instance_pb2.InstanceAddProxiesBatchRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAddProxiesBatchRequest, soulfire.instance_pb2.InstanceAddProxiesBatchResponse], /) soulfire.instance_pb2.InstanceAddProxiesBatchResponse[source]¶
Adds multiple proxies to the instance in a single operation. More efficient than multiple AddInstanceProxy calls. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- remove_instance_proxies_batch(request: soulfire.instance_pb2.InstanceRemoveProxiesBatchRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveProxiesBatchRequest, soulfire.instance_pb2.InstanceRemoveProxiesBatchResponse], /) soulfire.instance_pb2.InstanceRemoveProxiesBatchResponse[source]¶
Removes multiple proxies from the instance by their addresses. More efficient than multiple RemoveInstanceProxy calls. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- remove_instance_proxy_entries(request: soulfire.instance_pb2.InstanceRemoveProxyEntriesRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveProxyEntriesRequest, soulfire.instance_pb2.InstanceRemoveProxyEntriesResponse], /) soulfire.instance_pb2.InstanceRemoveProxyEntriesResponse[source]¶
Removes one matching occurrence of each requested proxy entry. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if the instance does not exist; INVALID_ARGUMENT for invalid proxies
- get_audit_log(request: soulfire.instance_pb2.InstanceAuditLogRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAuditLogRequest, soulfire.instance_pb2.InstanceAuditLogResponse], /) soulfire.instance_pb2.InstanceAuditLogResponse[source]¶
Retrieves the audit log for an instance. Returns a list of recorded actions ordered by timestamp (newest first). Requires: READ_INSTANCE_AUDIT_LOGS permission on the instance Errors: NOT_FOUND if instance does not exist
- get_account_metadata(request: soulfire.instance_pb2.GetAccountMetadataRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.GetAccountMetadataRequest, soulfire.instance_pb2.GetAccountMetadataResponse], /) soulfire.instance_pb2.GetAccountMetadataResponse[source]¶
Gets persistent metadata for a Minecraft account. Persistent metadata survives bot restarts and session changes. Requires: READ_BOT_INFO permission on the instance Errors: NOT_FOUND if instance or account does not exist
- set_account_metadata_entry(request: soulfire.instance_pb2.SetAccountMetadataEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.SetAccountMetadataEntryRequest, soulfire.instance_pb2.SetAccountMetadataEntryResponse], /) soulfire.instance_pb2.SetAccountMetadataEntryResponse[source]¶
Sets a single persistent metadata entry for a Minecraft account. Creates the namespace and key if they don’t exist, or updates if they do. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- delete_account_metadata_entry(request: soulfire.instance_pb2.DeleteAccountMetadataEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.DeleteAccountMetadataEntryRequest, soulfire.instance_pb2.DeleteAccountMetadataEntryResponse], /) soulfire.instance_pb2.DeleteAccountMetadataEntryResponse[source]¶
Deletes a persistent metadata entry from a Minecraft account. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist
- get_instance_metadata(request: soulfire.instance_pb2.GetInstanceMetadataRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.GetInstanceMetadataRequest, soulfire.instance_pb2.GetInstanceMetadataResponse], /) soulfire.instance_pb2.GetInstanceMetadataResponse[source]¶
Gets persistent metadata for the instance itself. Persistent metadata survives restarts and session changes. Requires: READ_INSTANCE permission on the instance Errors: NOT_FOUND if instance does not exist
- set_instance_metadata_entry(request: soulfire.instance_pb2.SetInstanceMetadataEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.SetInstanceMetadataEntryRequest, soulfire.instance_pb2.SetInstanceMetadataEntryResponse], /) soulfire.instance_pb2.SetInstanceMetadataEntryResponse[source]¶
Sets a single persistent metadata entry for the instance. Creates the namespace and key if they don’t exist, or updates if they do. Requires: UPDATE_INSTANCE_META permission on the instance Errors: NOT_FOUND if instance does not exist
- delete_instance_metadata_entry(request: soulfire.instance_pb2.DeleteInstanceMetadataEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.DeleteInstanceMetadataEntryRequest, soulfire.instance_pb2.DeleteInstanceMetadataEntryResponse], /) soulfire.instance_pb2.DeleteInstanceMetadataEntryResponse[source]¶
Deletes a persistent metadata entry from the instance. Requires: UPDATE_INSTANCE_META permission on the instance Errors: NOT_FOUND if instance does not exist