Class SongGuessAPI

Staticoptions

name

• get name(): string

  The name for this server.

  Resolves from this.ctx.id.name — the native DO id name, populated whenever the stub was created via idFromName() or getByName(). This is available inside every entry point (including the constructor, alarms, and hibernating websocket handlers).

  For alarm handlers firing on stale on-disk alarm records from older workerd versions that didn't persist name into the alarm record, the name is recovered from a storage fallback record.

  Throws if neither source is available — typically this means the DO was addressed via idFromString() or newUniqueId(), which is not supported by PartyServer.

  Returns string

__unsafe_ensureInitialized

• __unsafe_ensureInitialized(): Promise<void>
  Internal

  — Do not use directly. This is an escape hatch for frameworks (like Agents) that receive calls via native DO RPC, bypassing the standard fetch/alarm/webSocket entry points where initialization normally happens. Calling this from application code is unsupported and may break without notice.

  Returns Promise<void>

_initAndFetch

• _initAndFetch(
      name: string,
      props: Record<string, unknown> | undefined,
      request: Request,
  ): Promise<Response>
  Internal

  Parameters

  • name: string
  • props: Record<string, unknown> | undefined
  • request: Request

  Returns Promise<Response>

  Deprecated

  Retained for backward compatibility with older callers. routePartykitRequest no longer uses this method; it sends props via the x-partykit-props header on the underlying fetch() request.

alarm

• alarm(): Promise<void>

  Returns Promise<void>

broadcast

• broadcast(
      msg: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>,
      without?: string[],
  ): void

  Send a message to all connected clients, except connection ids listed in without

  Parameters

  • msg: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>
  • Optionalwithout: string[]

  Returns void

fetch

• fetch(request: Request): Promise<Response>

  Handle incoming requests to the server.

  Parameters

  • request: Request

  Returns Promise<Response>

getConnection

• getConnection<TState = unknown>(id: string): Connection<TState> | undefined

  Get a connection by connection id

  Type Parameters

  • TState = unknown

  Parameters

  • id: string

  Returns Connection<TState> | undefined

getConnections

• getConnections<TState = unknown>(tag?: string): Iterable<Connection<TState>>

  Get all connections. Optionally, you can provide a tag to filter returned connections. Use Server#getConnectionTags to tag the connection on connect.

  Type Parameters

  • TState = unknown

  Parameters

  • Optionaltag: string

  Returns Iterable<Connection<TState>>

getConnectionTags

• getConnectionTags(
      connection: Connection,
      context: ConnectionContext,
  ): string[] | Promise<string[]>

  You can tag a connection to filter them in Server#getConnections. Each connection supports up to 9 tags, each tag max length is 256 characters.

  Parameters

  • connection: Connection
  • context: ConnectionContext

  Returns string[] | Promise<string[]>

onAlarm

• onAlarm(): void | Promise<void>

  Returns void | Promise<void>

onClose

• onClose(
      connection: Connection,
      code: number,
      reason: string,
      wasClean: boolean,
  ): void | Promise<void>

  Called when a connection is closed.

  Parameters

  • connection: Connection
  • code: number
  • reason: string
  • wasClean: boolean

  Returns void | Promise<void>

onConnect

• onConnect(connection: Connection, ctx: ConnectionContext): void | Promise<void>

  Called when a new connection is made to the server.

  Parameters

  • connection: Connection
  • ctx: ConnectionContext

  Returns void | Promise<void>

onError

• onError(connection: Connection, error: unknown): void | Promise<void>

  Called when an error occurs on a connection.

  Parameters

  • connection: Connection
  • error: unknown

  Returns void | Promise<void>

onException

• onException(error: unknown): void | Promise<void>

  Called when an exception occurs.

  Parameters

  • error: unknown

    The error that occurred.

  Returns void | Promise<void>

onMessage

• onMessage(connection: Connection, message: WSMessage): void | Promise<void>

  Called when a message is received from a connection.

  Parameters

  • connection: Connection
  • message: WSMessage

  Returns void | Promise<void>

onStart

• onStart(props?: Record<string, unknown>): void | Promise<void>

  Called when the server is started for the first time.

  Parameters

  • Optionalprops: Record<string, unknown>

  Returns void | Promise<void>

setName

• setName(name: string, props?: Record<string, unknown>): Promise<void>

  Establish this server's name and trigger onStart().

  Use cases:

  1. Framework-level bootstrap of DOs where ctx.id.name is undefined — e.g. DOs addressed via idFromString() / newUniqueId(). setName() stashes the name in memory and persists it under __ps_name so cold-wake invocations recover it via #ensureInitialized()'s legacy fallback.
  2. Delivering initial props to onStart() via the optional second argument.

  For DOs addressed via idFromName() / getByName(), calling setName() is redundant — this.name is available automatically from ctx.id.name. The normal initialization path also persists a fallback record so old-compat alarm handlers can recover the name. Throws if name does not match ctx.id.name.

  Not appropriate for facets. Cloudflare Agents and any other framework using ctx.facets.get(...) should pass an explicit id in FacetStartupOptions so the facet has its own ctx.id.name:

  const stub = ctx.facets.get(facetKey, () => ({
    class: ChildClass,
    id: ctx.exports.SomeBoundDOClass.idFromName(facetName),
  }));
  Copy

  Without an explicit id, the facet inherits the parent DO's ctx.id (including ctx.id.name), and setName() will throw the ctx.id.name-mismatch error because the facet's intended name differs from the parent's. See https://developers.cloudflare.com/dynamic-workers/usage/durable-object-facets/ for the FacetStartupOptions.id semantics.

  Parameters

  • name: string
  • Optionalprops: Record<string, unknown>

  Returns Promise<void>

  Deprecated

  for callers that address DOs via idFromName() / getByName(). Still the supported API for framework-level bootstrap of header/newUniqueId-addressed DOs and for delivering initial props to onStart().

sql

• sql<T = Record<string, string | number | boolean | null>>(
      strings: TemplateStringsArray,
      ...values: (string | number | boolean | null)[],
  ): T[]

  Execute SQL queries against the Server's database

  Type Parameters

  • T = Record<string, string | number | boolean | null>

    Type of the returned rows

  Parameters

  • strings: TemplateStringsArray

    SQL query template strings

  • ...values: (string | number | boolean | null)[]

    Values to be inserted into the query

  Returns T[]

  Array of query results

webSocketClose

• webSocketClose(
      ws: WebSocket,
      code: number,
      reason: string,
      wasClean: boolean,
  ): Promise<void>

  Parameters

  • ws: WebSocket
  • code: number
  • reason: string
  • wasClean: boolean

  Returns Promise<void>

webSocketError

• webSocketError(ws: WebSocket, error: unknown): Promise<void>

  Parameters

  • ws: WebSocket
  • error: unknown

  Returns Promise<void>

webSocketMessage

• webSocketMessage(ws: WebSocket, message: WSMessage): Promise<void>

  Parameters

  • ws: WebSocket
  • message: WSMessage

  Returns Promise<void>