fix(server): store null instead of empty string for session deviceType and deviceOS

Aligns session.deviceType and session.deviceOS with the pattern established
by #30223 (user.password), #30123 (album.description) and #31560
(user.oauthId): the database stores NULL instead of '' when the field is
unknown, while API responses continue to return '' for backwards
compatibility until v4.

Changes:
- schema: DB columns nullable with default NULL, migration converts
  existing '' rows.
- database.ts / session.table.ts: Session.deviceType and .deviceOS are now
  string | null.
- session.dto.ts:
    - SessionCreateSchema input accepts null/undefined/'' and coerces to
      null (TODO(v4): drop the transform, clients should send null).
    - SessionResponseSchema stays z.string() and mapSession coerces
      null -> '' with a TODO(v4) note.
- utils/request.getUserAgentDetails: returns null instead of '' when the
  header can't be parsed, so new sessions written by the login flow store
  null directly.
- LoginDetails type + affected test fixtures updated to match.

Refs #28832

Author: Guardiansoftiktok

server/src/database.ts

@@ -231,8 +231,8 @@ export type Session = {
   createdAt: Date;
   updatedAt: Date;
   expiresAt: Date | null;
-  deviceOS: string;
-  deviceType: string;
+  deviceOS: string | null;
+  deviceType: string | null;
   appVersion: string | null;
   pinExpiresAt: Date | null;
   isPendingSyncReset: boolean;

server/src/dtos/session.dto.ts

@@ -5,8 +5,18 @@ import { Session } from 'src/database.js';
 const SessionCreateSchema = z
   .object({
     duration: z.int().min(1).optional().describe('Session duration in seconds'),
-    deviceType: z.string().optional().describe('Device type'),
-    deviceOS: z.string().optional().describe('Device OS'),
+    // TODO(v4): drop the empty-string-to-null transform (clients should send null)
+    deviceType: z
+      .string()
+      .nullish()
+      .transform((value) => (value === '' ? null : value))
+      .describe('Device type'),
+    // TODO(v4): drop the empty-string-to-null transform (clients should send null)
+    deviceOS: z
+      .string()
+      .nullish()
+      .transform((value) => (value === '' ? null : value))
+      .describe('Device OS'),
   })
   .meta({ id: 'SessionCreateDto' });
 
@@ -46,7 +56,9 @@ export const mapSession = (entity: Session, currentId?: string): SessionResponse
   expiresAt: entity.expiresAt?.toISOString(),
   current: currentId === entity.id,
   appVersion: entity.appVersion,
-  deviceOS: entity.deviceOS,
-  deviceType: entity.deviceType,
+  // TODO(v4): remove the null coercion and make `deviceOS` nullable on the response
+  deviceOS: entity.deviceOS ?? '',
+  // TODO(v4): remove the null coercion and make `deviceType` nullable on the response
+  deviceType: entity.deviceType ?? '',
   isPendingSyncReset: entity.isPendingSyncReset,
 });

server/src/schema/migrations/1789763328290-ConvertSessionDeviceTypeAndOSEmptyStringToNull.ts

@@ -0,0 +1,19 @@
+import { Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await sql`ALTER TABLE "session" ALTER COLUMN "deviceType" DROP NOT NULL;`.execute(db);
+  await sql`ALTER TABLE "session" ALTER COLUMN "deviceType" SET DEFAULT NULL;`.execute(db);
+  await sql`UPDATE "session" SET "deviceType" = NULL WHERE "deviceType" = '';`.execute(db);
+  await sql`ALTER TABLE "session" ALTER COLUMN "deviceOS" DROP NOT NULL;`.execute(db);
+  await sql`ALTER TABLE "session" ALTER COLUMN "deviceOS" SET DEFAULT NULL;`.execute(db);
+  await sql`UPDATE "session" SET "deviceOS" = NULL WHERE "deviceOS" = '';`.execute(db);
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await sql`UPDATE "session" SET "deviceOS" = '' WHERE "deviceOS" IS NULL;`.execute(db);
+  await sql`ALTER TABLE "session" ALTER COLUMN "deviceOS" SET DEFAULT '';`.execute(db);
+  await sql`ALTER TABLE "session" ALTER COLUMN "deviceOS" SET NOT NULL;`.execute(db);
+  await sql`UPDATE "session" SET "deviceType" = '' WHERE "deviceType" IS NULL;`.execute(db);
+  await sql`ALTER TABLE "session" ALTER COLUMN "deviceType" SET DEFAULT '';`.execute(db);
+  await sql`ALTER TABLE "session" ALTER COLUMN "deviceType" SET NOT NULL;`.execute(db);
+}

server/src/schema/migrations/ORDER

@@ -95,3 +95,4 @@
 1787148183729-ClusterGroups
 1787148183730-DeleteMismatchedMemoryAssets
 1789419229196-ConvertUserOAuthIdEmptyStringToNull
+1789763328290-ConvertSessionDeviceTypeAndOSEmptyStringToNull

server/src/schema/tables/session.table.ts

@@ -35,11 +35,11 @@ export class SessionTable {
   @ForeignKeyColumn(() => SessionTable, { onUpdate: 'CASCADE', onDelete: 'CASCADE', nullable: true })
   parentId!: string | null;
 
-  @Column({ default: '' })
-  deviceType!: Generated<string>;
+  @Column({ nullable: true })
+  deviceType!: string | null;
 
-  @Column({ default: '' })
-  deviceOS!: Generated<string>;
+  @Column({ nullable: true })
+  deviceOS!: string | null;
 
   @Column({ nullable: true })
   appVersion!: string | null;

server/src/services/auth.service.spec.ts

@@ -21,8 +21,8 @@ const email = 'test@immich.com';
 const loginDetails = {
   isSecure: true,
   clientIp: '127.0.0.1',
-  deviceOS: '',
-  deviceType: '',
+  deviceOS: null,
+  deviceType: null,
   appVersion: null,
 };
 

server/src/services/auth.service.ts

@@ -32,8 +32,8 @@ import { getUserAgentDetails } from 'src/utils/request.js';
 export interface LoginDetails {
   isSecure: boolean;
   clientIp: string;
-  deviceType: string;
-  deviceOS: string;
+  deviceType: string | null;
+  deviceOS: string | null;
   appVersion: string | null;
 }
 

server/src/utils/request.ts

@@ -18,8 +18,8 @@ export const getUserAgentDetails = (headers: IncomingHttpHeaders) => {
   const appVersion = getAppVersionFromUA(headers['user-agent'] ?? '');
 
   return {
-    deviceType: userAgent.browser.name || userAgent.device.type || (headers['devicemodel'] as string) || '',
-    deviceOS: userAgent.os.name || (headers['devicetype'] as string) || '',
+    deviceType: userAgent.browser.name || userAgent.device.type || (headers['devicemodel'] as string) || null,
+    deviceOS: userAgent.os.name || (headers['devicetype'] as string) || null,
     appVersion,
   };
 };

server/test/medium.factory.ts

@@ -832,7 +832,7 @@ const syncStream = () => {
 };
 
 const loginDetails = () => {
-  return { isSecure: false, clientIp: '', deviceType: '', deviceOS: '', appVersion: null };
+  return { isSecure: false, clientIp: '', deviceType: null, deviceOS: null, appVersion: null };
 };
 
 const loginResponse = (): LoginResponseDto => {